MCP指南
A2A协议
MCP规范
A2A规范
博客
MCP指南
A2A协议
MCP规范
A2A规范
博客

工具

工具是模型上下文协议（MCP）中的一个强大原语，允许服务器向客户端暴露可执行功能。通过工具，大型语言模型（LLM）可以与外部系统交互、执行计算并在现实世界中采取行动。

工具设计为模型控制，意味着工具从服务器暴露给客户端，目的是让 AI 模型能够自动调用它们（需有人在回路中批准）。

概述

MCP 中的工具允许服务器暴露可由客户端调用并由 LLM 用于执行操作的可执行函数。工具的关键方面包括：

  • 发现：客户端可以通过 tools/list 端点列出可用工具
  • 调用：通过 tools/call 端点调用工具，服务器执行请求的操作并返回结果
  • 灵活性：工具可以从简单计算到复杂的 API 交互

与资源类似，工具通过唯一名称标识，并可包含描述以指导使用。然而，与资源不同，工具表示可以修改状态或与外部系统交互的动态操作。

工具定义结构

每个工具的定义结构如下：

{
  name: string;          // 工具的唯一标识符
  description?: string;  // 可读的描述
  inputSchema: {         // 工具参数的 JSON Schema
    type: "object",
    properties: { ... }  // 工具特定的参数
  },
  annotations?: {        // 关于工具行为的可选提示
    title?: string;      // 工具的可读标题
    readOnlyHint?: boolean;    // 如果为 true，工具不修改其环境
    destructiveHint?: boolean; // 如果为 true，工具可能执行破坏性更新
    idempotentHint?: boolean;  // 如果为 true，重复调用相同参数无额外效果
    openWorldHint?: boolean;   // 如果为 true，工具与外部实体交互
  }
}

实现工具

以下是在 MCP 服务器中实现基本工具的示例：

const server = new Server({
  name: "example-server",
  version: "1.0.0"
}, {
  capabilities: {
    tools: {}
  }
});

// 定义可用工具
server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      description: "将两个数字相加",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      }
    }]
  };
});

// 处理工具执行
server.setRequestHandler(CallToolRequestSchema, async (request) => {
  if (request.params.name === "calculate_sum") {
    const { a, b } = request.params.arguments;
    return {
      content: [
        {
          type: "text",
          text: String(a + b)
        }
      ]
    };
  }
  throw new Error("未找到工具");
});

示例工具模式

以下是服务器可以提供的工具类型示例：

系统操作

与本地系统交互的工具：

{
  name: "execute_command",
  description: "运行 shell 命令",
  inputSchema: {
    type: "object",
    properties: {
      command: { type: "string" },
      args: { type: "array", items: { type: "string" } }
    }
  }
}

API 集成

封装外部 API 的工具：

{
  name: "github_create_issue",
  description: "创建 GitHub 问题",
  inputSchema: {
    type: "object",
    properties: {
      title: { type: "string" },
      body: { type: "string" },
      labels: { type: "array", items: { type: "string" } }
    }
  }
}

数据处理

转换或分析数据的工具：

{
  name: "analyze_csv",
  description: "分析 CSV 文件",
  inputSchema: {
    type: "object",
    properties: {
      filepath: { type: "string" },
      operations: {
        type: "array",
        items: {
          enum: ["sum", "average", "count"]
        }
      }
    }
  }
}

最佳实践

实现工具时：

  1. 提供清晰、描述性的名称和描述
  2. 为参数使用详细的 JSON Schema 定义
  3. 在工具描述中包含示例，展示模型应如何使用它们
  4. 实现适当的错误处理和验证
  5. 对长时间操作使用进度报告
  6. 保持工具操作的专注和原子性
  7. 记录预期的返回值结构
  8. 实现适当的超时
  9. 考虑对资源密集型操作设置速率限制
  10. 记录工具使用情况以便调试和监控

安全考虑

暴露工具时：

输入验证

  • 根据模式验证所有参数
  • 清理文件路径和系统命令
  • 验证 URL 和外部标识符
  • 检查参数大小和范围
  • 防止命令注入

访问控制

  • 在需要时实施认证
  • 使用适当的授权检查
  • 审计工具使用情况
  • 限制请求速率
  • 监控滥用行为

错误处理

  • 不要向客户端暴露内部错误
  • 记录与安全相关的错误
  • 适当处理超时
  • 在错误后清理资源
  • 验证返回值

工具发现和更新

MCP 支持动态工具发现：

  1. 客户端可以随时列出可用工具
  2. 服务器可以使用 notifications/tools/list_changed 通知客户端工具变更
  3. 工具可以在运行时添加或移除
  4. 工具定义可以更新（但需谨慎）

错误处理

工具错误应在结果对象中报告，而不是作为 MCP 协议级别的错误。这允许 LLM 查看并可能处理错误。工具遇到错误时：

  1. 在结果中将 isError 设置为 true
  2. 在 content 数组中包含错误详情

以下是工具正确错误处理的示例：

try {
  // 工具操作
  const result = performOperation();
  return {
    content: [
      {
        type: "text",
        text: `操作成功：${result}`
      }
    ]
  };
} catch (error) {
  return {
    isError: true,
    content: [
      {
        type: "text",
        text: `错误：${error.message}`
      }
    ]
  };
}

这种方式允许 LLM 看到错误发生，并可能采取纠正措施或请求人工干预。

工具注解

工具注解为工具的行为提供了额外的元数据，帮助客户端了解如何呈现和管理工具。这些注解是描述工具性质和影响的提示，但不应依赖其进行安全决策。

工具注解的目的

工具注解有以下几个关键用途：

  1. 提供不影响模型上下文的 UX 特定信息
  2. 帮助客户端适当地分类和呈现工具
  3. 传递有关工具潜在副作用的信息
  4. 协助开发直观的工具批准界面

可用工具注解

MCP 规范为工具定义了以下注解：

注解 类型 默认值 描述
title string - 工具的可读标题，适用于 UI 显示
readOnlyHint boolean false 如果为 true，表示工具不修改其环境
destructiveHint boolean true 如果为 true，工具可能执行破坏性更新（仅在 readOnlyHint 为 false 时有意义）
idempotentHint boolean false 如果为 true，重复调用相同参数无额外效果（仅在 readOnlyHint 为 false 时有意义）
openWorldHint boolean true 如果为 true，工具可能与外部实体交互

示例用法

以下是为不同场景定义带注解的工具的示例：

// 只读搜索工具
{
  name: "web_search",
  description: "搜索网络信息",
  inputSchema: {
    type: "object",
    properties: {
      query: { type: "string" }
    },
    required: ["query"]
  },
  annotations: {
    title: "网络搜索",
    readOnlyHint: true,
    openWorldHint: true
  }
}

// 破坏性文件删除工具
{
  name: "delete_file",
  description: "从文件系统中删除文件",
  inputSchema: {
    type: "object",
    properties: {
      path: { type: "string" }
    },
    required: ["path"]
  },
  annotations: {
    title: "删除文件",
    readOnlyHint: false,
    destructiveHint: true,
    idempotentHint: true,
    openWorldHint: false
  }
}

// 非破坏性数据库记录创建工具
{
  name: "create_record",
  description: "在数据库中创建新记录",
  inputSchema: {
    type: "object",
    properties: {
      table: { type: "string" },
      data: { type: "object" }
    },
    required: ["table", "data"]
  },
  annotations: {
    title: "创建数据库记录",
    readOnlyHint: false,
    destructiveHint: false,
    idempotentHint: false,
    openWorldHint: false
  }
}

在服务器实现中集成注解

server.setRequestHandler(ListToolsRequestSchema, async () => {
  return {
    tools: [{
      name: "calculate_sum",
      description: "将两个数字相加",
      inputSchema: {
        type: "object",
        properties: {
          a: { type: "number" },
          b: { type: "number" }
        },
        required: ["a", "b"]
      },
      annotations: {
        title: "计算总和",
        readOnlyHint: true,
        openWorldHint: false
      }
    }]
  };
});

工具注解的最佳实践

  1. 准确描述副作用：清楚地指明工具是否修改其环境，以及这些修改是否具有破坏性。
  2. 使用描述性标题：提供清晰描述工具用途的人性化标题。
  3. 正确标记幂等性：仅当重复调用相同参数确实无额外效果时才标记工具为幂等。
  4. 设置适当的开放/封闭世界提示：指明工具是与封闭系统（如数据库）还是开放系统（如网络）交互。
  5. 记住注解是提示：ToolAnnotations 中的所有属性都是提示，不能保证提供工具行为的忠实描述。客户端不应仅基于注解做出安全关键决策。

测试工具

MCP 工具的全面测试策略应涵盖：

  • 功能测试：验证工具在有效输入下正确执行，并适当地处理无效输入
  • 集成测试：使用真实和模拟依赖测试工具与外部系统的交互
  • 安全测试：验证认证、授权、输入清理和速率限制
  • 性能测试：检查负载下的行为、超时处理和资源清理
  • 错误处理：确保工具通过 MCP 协议正确报告错误并清理资源
ON THIS PAGE