1. 什么是工具？ #

工具（Tools）是 MCP 服务器暴露的可执行函数，供语言模型根据对话内容自动发现并调用。模型通过工具与外部系统交互，如查天气、写文件、调 API。

协议版本：2025-11-25

用户交互建议：应用应当在 UI 中展示已暴露的工具、在调用时给出明显提示，并对敏感操作提供确认或拒绝。

2. 本章你将学到 #

• 工具的能力声明与协议消息
• 如何列出、调用工具
• 工具定义（inputSchema、outputSchema）
• 工具结果类型、错误处理与安全要点

3. 典型流程 #

用户问「巴黎天气怎么样？」→ 客户端将工具列表（含 get_weather）发给 LLM → LLM 决定调用 get_weather(location="Paris") → 客户端发 tools/call → 服务器执行并返回结果 → 客户端将结果交给 LLM → LLM 生成自然语言回复。

4. 能力 #

服务器必须声明 tools 能力：

{
  "capabilities": {
    "tools": {
      "listChanged": true
    }
  }
}

5. 协议消息 #

5.1 列出工具（tools/list） #

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": { "cursor": "optional-cursor-value" }
}

支持分页。

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "title": "Weather Information Provider",
        "description": "Get current weather for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name or zip code"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

5.2 调用工具（tools/call） #

请求：

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "location": "Paris" }
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Paris: 18°C, partly cloudy"
      }
    ],
    "isError": false
  }
}

5.3 列表变更通知 #

{
  "jsonrpc": "2.0",
  "method": "notifications/tools/list_changed"
}

6. 流程示意 #

7. 工具定义 #

7.1 字段 #

7.2 示例：有参数工具 #

{
  "name": "calculate_sum",
  "description": "Add two numbers",
  "inputSchema": {
    "type": "object",
    "properties": {
      "a": { "type": "number" },
      "b": { "type": "number" }
    },
    "required": ["a", "b"]
  }
}

7.3 示例：无参数工具 #

{
  "name": "get_current_time",
  "description": "Returns the current server time",
  "inputSchema": {
    "type": "object",
    "additionalProperties": false
  }
}

8. 工具结果 #

8.1 内容类型 #

示例：文本

{ "type": "text", "text": "Paris: 18°C, partly cloudy" }

示例：资源链接

{
  "type": "resource_link",
  "uri": "file:///project/src/main.rs",
  "name": "main.rs",
  "description": "Primary application entry point"
}

8.2 结构化输出（outputSchema） #

工具可定义 outputSchema，结果同时放在 content（文本）和 structuredContent（JSON）中：

{
  "content": [
    { "type": "text", "text": "{\"temperature\": 22.5, \"conditions\": \"Partly cloudy\"}" }
  ],
  "structuredContent": {
    "temperature": 22.5,
    "conditions": "Partly cloudy",
    "humidity": 65
  }
}

8.3 错误标记 #

工具执行失败时，在结果中设置 isError: true，错误信息仍放在 content 中，便于 LLM 自我纠正并重试：

{
  "content": [
    {
      "type": "text",
      "text": "Invalid departure date: must be in the future."
    }
  ],
  "isError": true
}

9. 错误处理 #

协议错误示例：

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code": -32602,
    "message": "Unknown tool: invalid_tool_name"
  }
}

工具执行错误示例：

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Invalid departure date: must be in the future. Current date is 08/08/2025."
      }
    ],
    "isError": true
  }
}

10. 安全要点 #