1.工具功能概述 #

Model Context Protocol (MCP) 允许服务器暴露可供语言模型调用的工具。这些工具使模型能够与外部系统交互，例如查询数据库、调用API或执行计算。每个工具通过唯一名称进行标识，并包含描述其模式的元数据。

2.用户交互模型 #

MCP中的工具设计旨在模型控制，这意味着语言模型可以根据其上下文理解及用户的提示自动发现并调用工具。

然而，具体实现可以自由选择适合其需求的任何接口模式来公开工具——协议本身并不强制规定任何特定的用户交互模型。

2.1 ⚠️ 重要安全提醒 #

出于信任、安全及保障考虑，应该始终确保有人参与其中，并有权拒绝工具调用。

应用程序应该:

• 提供清晰的用户界面，明确显示哪些工具已向AI模型开放
• 在调用工具时插入清晰的视觉指示器
• 向用户呈现操作确认提示，以确保人工参与决策流程

3.能力声明 #

支持工具的服务器必须声明tools能力：

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

listChanged表示服务器在可用工具列表发生变化时是否会发出通知。

4.协议消息 #

4.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 information for a location",
        "inputSchema": {
          "type": "object",
          "properties": {
            "location": {
              "type": "string",
              "description": "City name or zip code"
            }
          },
          "required": ["location"]
        }
      }
    ],
    "nextCursor": "next-page-cursor"
  }
}

4.2 调用工具 #

要调用工具，客户端需发送一个tools/call请求

请求：

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

响应：

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Current weather in New York:\nTemperature: 72°F\nConditions: Partly cloudy"
      }
    ],
    "isError": false
  }
}

4.3 列表变更通知 #

当可用工具列表发生变化时，已声明这些工具的服务器listChanged能力应该发送通知：

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

5.消息流 #

6.数据类型 #

6.1 工具 #

工具定义包含：

• name - 工具的独特标识符
• title - 工具的可选人类可读名称，用于显示用途
• description - 功能的人类可读描述
• inputSchema - 定义预期参数的JSON Schema
• outputSchema - 定义预期输出结构的可选JSON Schema
• annotations - 描述工具行为的可选属性

6.2 ⚠️ 安全提醒 #

出于信任、安全及保障考虑，客户端必须除非工具注释来自受信任的服务器，否则应将其视为不可信。

6.3 工具结果 #

工具结果可能包含结构化的或非结构化内容

非结构化内容以content一个结果的字段，可以包含多种不同类型的内容项：

注意: 所有内容类型（文本、图像、音频、资源链接及嵌入式资源）均支持可选功能注释这些元数据提供了关于受众、优先级和修改时间的信息。这与资源和提示所使用的注解格式相同。

6.3.1 文本内容 #

{
  "type": "text",
  "text": "Tool result text"
}

6.3.2 图片内容 #

{
  "type": "image",
  "data": "base64-encoded-data",
  "mimeType": "image/png",
  "annotations": {
    "audience": ["user"],
    "priority": 0.9
  }
}

这个示例演示了可选Annotation的使用。

6.3.3 音频内容 #

{
  "type": "audio",
  "data": "base64-encoded-audio-data",
  "mimeType": "audio/wav"
}

6.3.4 资源链接 #

一个工具可能返回链接至资源，用于提供额外的上下文或数据。此时，该工具将返回一个可由客户端订阅或获取的URI：

{
  "type": "resource_link",
  "uri": "file:///project/src/main.rs",
  "name": "main.rs",
  "description": "Primary application entry point",
  "mimeType": "text/x-rust",
  "annotations": {
    "audience": ["assistant"],
    "priority": 0.9
  }
}

资源链接支持相同的功能资源注解作为常规资源，帮助客户了解如何使用它们。

注意: 工具返回的资源链接不保证会出现在结果中。resources/list请求

6.3.5 嵌入式资源 #

资源 可能嵌入以使用合适的工具提供额外的上下文或数据URI方案使用嵌入式资源的服务器应该实现resources能力

{
  "type": "resource",
  "resource": {
    "uri": "file:///project/src/main.rs",
    "title": "Project Rust Main File",
    "mimeType": "text/x-rust",
    "text": "fn main() {\n    println!(\"Hello world!\");\n}",
    "annotations": {
      "audience": ["user", "assistant"],
      "priority": 0.7,
      "lastModified": "2025-05-03T14:30:00Z"
    }
  }
}

嵌入式资源支持相同的功能资源注解作为常规资源，帮助客户理解如何使用它们。

6.3.6 结构化内容 #

结构化的内容以JSON对象的形式返回structuredContent结果的字段

为了向后兼容，返回结构化内容的工具应该同时在TextContent块中返回序列化的JSON。

6.3.7 输出架构 #

工具可能还会提供一个输出模式（output schema）用于验证结构化结果。如果提供了输出模式：

• 服务器必须提供符合此模式的结构化结果
• 客户端应该根据此架构验证结构化结果

示例工具及其输出架构：

{
  "name": "get_weather_data",
  "title": "Weather Data Retriever",
  "description": "Get current weather data for a location",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": {
        "type": "string",
        "description": "City name or zip code"
      }
    },
    "required": ["location"]
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "temperature": {
        "type": "number",
        "description": "Temperature in celsius"
      },
      "conditions": {
        "type": "string",
        "description": "Weather conditions description"
      },
      "humidity": {
        "type": "number",
        "description": "Humidity percentage"
      }
    },
    "required": ["temperature", "conditions", "humidity"]
  }
}

本工具的有效响应示例：

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"temperature\": 22.5, \"conditions\": \"Partly cloudy\", \"humidity\": 65}"
      }
    ],
    "structuredContent": {
      "temperature": 22.5,
      "conditions": "Partly cloudy",
      "humidity": 65
    }
  }
}

提供输出模式有助于客户端和LLMs通过以下方式理解并正确处理结构化工具输出：

• 启用响应严格模式验证
• 为编程语言提供类型信息以实现更好的集成
• 引导客户和LLMs正确解析并利用返回的数据
• 支持更好的文档和开发者体验

7.错误处理 #

工具采用两种错误报告机制：

1. 协议错误 - 标准JSON-RPC错误，适用于以下问题：

   • 未知工具
   • 无效参数
   • 服务器错误

2. 工具执行错误 - 在工具结果中报告为isError: true:

   • API故障
   • 无效输入数据
   • 业务逻辑错误

示例协议错误：

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

示例工具执行错误：

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Failed to fetch weather data: API rate limit exceeded"
      }
    ],
    "isError": true
  }
}

8.安全注意事项 #

1. 服务器必须:

   • 验证所有工具输入
   • 实施适当的访问控制
   • 速率限制工具调用
   • 清理工具输出

2. 客户端应该:

   • 在敏感操作上提示用户确认
   • 在调用服务器之前向用户展示工具输入，以防止恶意或意外的数据泄露
   • 在传递给LLM之前验证工具结果
   • 为工具调用实现超时机制
   • 用于审计目的的日志工具使用

9.最佳实践 #

9.1 工具设计原则 #

1. 明确的功能边界 - 每个工具应该有一个明确、单一的功能
2. 详细的文档 - 提供清晰的描述和示例
3. 错误处理 - 实现健壮的错误处理和用户友好的错误消息
4. 安全性 - 验证所有输入并实施适当的访问控制

9.2 实现建议 #

1. 输入验证 - 严格验证所有工具参数
2. 输出清理 - 确保输出不包含敏感信息
3. 性能优化 - 实现适当的缓存和超时机制
4. 监控和日志 - 记录工具使用情况以便审计

9.3 用户体验 #

1. 清晰的反馈 - 为用户提供清晰的操作反馈
2. 确认机制 - 对敏感操作实施用户确认
3. 进度指示 - 对长时间运行的工具显示进度
4. 错误恢复 - 提供有意义的错误信息和恢复选项

10.常见应用场景 #

10.1 数据查询工具 #

• 数据库查询
• API调用
• 文件系统操作

10.2 计算工具 #

• 数学计算
• 数据分析
• 格式转换

10.3 通信工具 #

• 邮件发送
• 消息推送
• 通知系统

10.4 集成工具 #

• 第三方服务集成
• 工作流自动化
• 系统监控

11.总结 #

MCP工具功能为语言模型提供了强大的外部交互能力，使其能够：

• 执行具体操作 - 通过标准化的接口调用外部服务
• 获取实时数据 - 访问最新的信息和资源
• 自动化工作流 - 实现复杂的业务流程自动化
• 增强用户体验 - 提供更丰富、更实用的交互体验

通过遵循安全最佳实践和用户友好的设计原则，工具功能可以显著提升AI应用的实用性和价值。

参考资源:

• MCP官方文档
• JSON-RPC 2.0规范
• JSON Schema规范