AstrBot/openspec/mcp.md

MCP (Model Context Protocol) 协议规范

概述

MCP（Model Context Protocol）是由 Anthropic 创建的开放协议，用于将 AI 模型连接到外部工具和数据源。

核心定位：MCP 为 AI 模型提供标准化的工具调用和上下文获取能力，类似于 USB 协议为设备提供的标准化连接方式。

实现状态

组件	状态	说明
MCP Client (Python)	✅ 部分实现	astrbot/api/mcp.py 有简单封装，非完整实现
MCP Client (Rust)	⚠️ 待实现	应迁移到 Rust 核心
MCP Server	❌ 不计划	AstrBot 不托管 MCP 服务器
Stdio 传输	⚠️ 待实现	-
HTTP/SSE 传输	⚠️ 待实现	-
Tools/Resources/Prompts	⚠️ 待实现	-

相关协议: ABP（插件协议）, ACP（Agent 通信）, agent-message（消息处理框架）

核心功能

MCP 服务器通过三个构建块提供功能：

功能	说明	示例	控制方
Tools	LLM 可以主动调用的函数	搜索航班、发送消息、创建日历事件	模型
Resources	被动数据源，为上下文提供信息	检索文档、访问知识库、读取日历	应用程序
Prompts	预构建的指令模板	规划假期、总结会议内容、起草电子邮件	用户

与 A2A/ACP 的关系

协议	定位	关系
MCP	AI 模型与外部工具/数据源的连接	专注于"工具和上下文"
A2A	Agent 之间的通信和协作	专注于"互操作"
ACP	IDE 与本地 Agent 的紧密集成	专注于"本地控制"

互补关系：

• MCP 为 Agent 提供工具和数据访问能力
• A2A/ACP 处理 Agent 之间的通信
• 三者共同构成完整的 AI Agent 通信栈

架构

┌─────────────────────────────────────────┐
│           AI 应用 (Client)               │
│  - 模型                                 │
│  - 上下文管理                           │
└─────────────────────────────────────────┘
                      │ MCP 协议
                      ▼
┌─────────────────────────────────────────┐
│           MCP 服务器                     │
│  - Tools (工具)                         │
│  - Resources (资源)                     │
│  - Prompts (提示)                       │
└─────────────────────────────────────────┘

传输层

Stdio（本地）

• 适用场景：基于本地子进程的 MCP 服务器
• 协议：通过 stdin/stdout 的 JSON-RPC 2.0
• 启动方式：使用配置的 command 启动子进程

{"jsonrpc":"2.0","method":"initialize","params":{...},"id":1}

HTTP/SSE（远程）

• 适用场景：远程 MCP 服务器
• 协议：HTTP + Server-Sent Events (SSE) 用于服务器→客户端
• 端点：RESTful JSON-RPC over HTTP POST

核心方法

工具 (Tools)

协议操作：

方法	目的	返回
tools/list	发现可用工具	带有架构的工具定义数组
tools/call	执行特定工具	工具执行结果

工具定义示例：

{
  "name": "searchFlights",
  "description": "Search for available flights",
  "inputSchema": {
    "type": "object",
    "properties": {
      "origin": { "type": "string", "description": "Departure city" },
      "destination": { "type": "string", "description": "Arrival city" },
      "date": { "type": "string", "format": "date", "description": "Travel date" }
    },
    "required": ["origin", "destination", "date"]
  }
}

用户交互模型：工具由模型控制，但强调人工监督：

• UI 中显示可用工具，允许用户定义是否可用
• 针对单个工具执行的确认对话框
• 预先批准某些安全操作的权限设置
• 显示所有工具执行情况的活动日志

资源 (Resources)

协议操作：

方法	目的	返回
resources/list	列出可用的直接资源	资源描述符数组
resources/templates/list	发现资源模板	资源模板定义数组
resources/read	检索资源内容	带有元数据的资源数据
resources/subscribe	监控资源变化	订阅确认

资源模板示例：

{
  "uriTemplate": "weather://forecast/{city}/{date}",
  "name": "weather-forecast",
  "title": "Weather Forecast",
  "description": "Get weather forecast for any city and date",
  "mimeType": "application/json"
}

参数补全：动态资源支持参数补全，例如输入 "Par" 可能会提示 "Paris" 或 "Park City"。

用户交互模型：资源是应用程序驱动的：

• 文件夹式结构的树状或列表视图
• 用于查找特定资源的搜索和过滤界面
• 基于启发式方法或 AI 选择的自动上下文包含

提示 (Prompts)

协议操作：

方法	目的	返回
prompts/list	发现可用提示词	提示词描述符数组
prompts/get	检索提示词详情	带有参数的完整提示词定义

提示词示例：

{
  "name": "plan-vacation",
  "title": "Plan a vacation",
  "description": "Guide through vacation planning process",
  "arguments": [
    { "name": "destination", "type": "string", "required": true },
    { "name": "duration", "type": "number", "description": "days" },
    { "name": "budget", "type": "number", "required": false },
    { "name": "interests", "type": "array", "items": { "type": "string" } }
  ]
}

用户交互模型：提示由用户控制，需要显式调用：

• 斜杠命令（输入 "/" 查看可用提示词）
• 操作面板 (Command palettes)
• 常用提示词的专用 UI 按钮

消息格式

请求

{
  "jsonrpc": "2.0",
  "id": "unique-id",
  "method": "tools/call",
  "params": {
    "name": "searchFlights",
    "arguments": {
      "origin": "NYC",
      "destination": "Barcelona",
      "date": "2024-06-15"
    }
  }
}

响应

{
  "jsonrpc": "2.0",
  "id": "unique-id",
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Found 3 flights..."
      }
    ]
  }
}

通知

{
  "jsonrpc": "2.0",
  "method": "notifications/resources/updated",
  "params": {
    "uri": "calendar://events/2024"
  }
}

能力 (Capabilities)

客户端能力

{
  "roots": {
    "listChanged": true
  },
  "sampling": {}
}

服务器能力

{
  "tools": { "listChanged": true },
  "resources": { "subscribe": true, "listChanged": true },
  "prompts": { "listChanged": true }
}

多服务器整合

MCP 的真正威力在多服务器协同工作时显现。

示例：多服务器差旅规划

┌─────────────────────────────────────────┐
│         AI 差旅规划应用                   │
└─────────────────────────────────────────┘
          │          │          │
          ▼          ▼          ▼
┌────────────┐ ┌──────────┐ ┌─────────────┐
│ 旅行服务器  │ │天气服务器 │ │日历/邮件服务器│
│ - 航班搜索  │ │ - 气候数据│ │ - 日程管理   │
│ - 酒店预订  │ │ - 预报    │ │ - 发送邮件   │
└────────────┘ └──────────┘ └─────────────┘

完整流程：

1. 用户调用提示词：plan-vacation(destination: "Barcelona", date: "2024-06-15")
2. 用户选择资源：calendar://my-calendar/June-2024、travel://preferences/europe
3. AI 读取资源收集上下文
4. AI 执行工具：searchFlights()、checkWeather()
5. AI 请求用户批准：bookHotel()、createCalendarEvent()
6. 结果：量身定制的巴塞罗那之旅规划和预订

错误码

码值	名称	描述
-32700	Parse Error	无效的 JSON
-32600	Invalid Request	格式错误的请求
-32601	Method Not Found	未知方法
-32602	Invalid Params	无效参数
-32603	Internal Error	服务器内部错误

实现注意事项

• MCP 客户端使用指数退避管理重连
• 工具调用结果序列化为 JSON
• 资源可订阅变更通知
• 工具执行前可能需要用户授权
• 支持参数补全以帮助用户发现有效值