illegalCreed

中文

English

中文

English

Appearance

参考 ​

基于 MCP 官方规范（modelcontextprotocol.io/specification）编写，对照 2025-11-25 最新版

速查 ​

  • 协议基底：JSON-RPC 2.0 + UTF-8；双层架构 = Data 层 + Transport 层
  • 三类参与者：Host / Client / Server（1 Host → N Client → N Server）
  • 生命周期：initialize → notifications/initialized → operation → shutdown（无专用消息）
  • Transport：stdio（本地子进程）/ Streamable HTTP（远程单一 endpoint + SSE 流）
  • 五原语：Server 端 Resources / Tools / Prompts；Client 端 Sampling / Roots（+ Elicitation / Tasks 2025-11-25 新增）
  • 常见错误码：-32601 Method not found（未协商能力）、-32602 Invalid params、-32603 Internal error
  • 当前协议版本：2025-11-25；治理：Linux Foundation + SEP 流程
  • Tier1 SDK：TypeScript（@modelcontextprotocol/sdk）/ Python（mcp）/ C# / Go
  • 完整说明见 入门 / 协议原语与生命周期

JSON-RPC 消息格式 ​

类型字段示例
请求jsonrpc + id + method + params{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{...}}
响应jsonrpc + id + result（成功）/ error（失败）{"jsonrpc":"2.0","id":1,"result":{...}}
通知jsonrpc + method + params（无 id，无响应）{"jsonrpc":"2.0","method":"notifications/initialized"}
错误code + message + 可选 data{"code":-32601,"message":"Method not found"}

消息必须用 UTF-8 编码；stdio transport 下消息内不得包含嵌入换行（换行作为消息分隔符）。

JSON-RPC 方法完整清单 ​

生命周期 ​

方法 / 通知方向用途
initializeclient → server协商 protocolVersion + capabilities + clientInfo
notifications/initializedclient → server初始化完成通知
ping双向心跳

Server 原语：Resources ​

方法用途
resources/list列出资源
resources/read读取资源内容
resources/templates/list列出 URI 模板
resources/subscribe / unsubscribe订阅 / 取消订阅
notifications/resources/updated内容变更通知
notifications/resources/list_changed清单变更通知

Server 原语：Tools ​

方法用途
tools/list列出工具
tools/call调用工具
notifications/tools/list_changed清单变更通知

Server 原语：Prompts ​

方法用途
prompts/list列出提示模板
prompts/get取具体提示（带 arguments）
notifications/prompts/list_changed清单变更通知

Client 原语 ​

方法用途
sampling/createMessageserver 反向请求 client 调 LLM
roots/listclient 返回文件系统边界
notifications/roots/list_changedroots 变更通知
elicitation/create（2025-11-25）server 向用户请求输入 / 确认
notifications/message（Logging）server → client 结构化日志

通用通知 ​

通知用途
notifications/progress长任务进度（双向）
notifications/cancelled取消请求（双向）

实验性（2025-11-25） ​

方法用途
tasks/...（多方法）durable 异步执行 / 轮询 / 延迟结果

JSON-RPC 错误码表 ​

错误码名称含义
-32700Parse errorJSON 解析失败
-32600Invalid Request请求结构非法
-32601Method not found方法不存在或未在 capabilities 中协商
-32602Invalid params参数缺失或类型错误
-32603Internal errorserver 内部异常
-32000Server error（保留段起始）server 自定义错误
-32001Request failed请求失败（部分 SDK 用）
-32002Resource not found资源 / 工具 / 提示不存在
-32003Unknown resource / tool 等兜底未知实体

业务错误（如工具入参校验失败）不应走 JSON-RPC error——应用 CallToolResult.isError:true 返回，让 LLM 自纠正。

Tool 字段规则 ​

字段规则
name1–128 字符；A–Z a–z 0–9 _ - . /；大小写敏感；server 内唯一
title可选，UI 展示用人类可读标题
description可选，给 LLM 看的语义说明
inputSchema必填，合法 JSON Schema 2020-12 object；无参写 {type:"object", additionalProperties:false}
outputSchema可选；声明后需同时填 structuredContent
annotations可选；4 类 hint：readOnlyHint / destructiveHint / idempotentHint / openWorldHint
icons可选（2025-11-25 新增）

Sampling modelPreferences 字段 ​

字段类型含义
hints`[{ name: "claude""sonnet"
costPriority0–1越高越偏向低成本模型
speedPriority0–1越高越偏向高速模型
intelligencePriority0–1越高越偏向高能力模型

Transport 对照 ​

维度stdioStreamable HTTP
适用场景本地 server（单 client）远程 server（多 client）
进程模型client 拉起 server 子进程独立进程，跨网络
消息格式newline-delimited JSONHTTP POST body / SSE event
鉴权继承用户权限OAuth 2.1 + OIDC Discovery
会话标识进程本身Mcp-Session-Id 头
流式支持否（单条请求-响应）是（SSE event + Last-Event-ID 续传）
复用单 client 一条多 client 共享 endpoint
安全要点stdout 严禁写非协议内容校验 Origin + 绑 127.0.0.1 防 DNS rebinding

SDK 分级（截至 2025-11-25） ​

Tier语言包名 / 入口关键 API
Tier 1TypeScript@modelcontextprotocol/sdkMcpServer.registerTool() + StdioServerTransport + server.connect()
Tier 1Pythonmcp（pip）FastMCP + @mcp.tool() + mcp.run(transport="stdio")
Tier 1C#ModelContextProtocolMcpServer + attribute 注册
Tier 1Gogithub.com/mark3labs/mcp-gomcp.NewServer + AddTool
Tier 2Java / Spring AIspring-ai-mcpstarter 集成
Tier 2Rustrmcp cratetrait 实现
Tier 3Swift / Ruby / PHP / Kotlin / Elixir社区维护见官方 SDK 列表

版本演进 ​

版本时间关键变化
2024-11-052024-11首发；含旧 HTTP+SSE transport（双端点 GET-SSE + POST）
2025-03-262025-03引入 Streamable HTTP transport 取代旧 HTTP+SSE；旧 transport 标记 deprecated
2025-06-182025-06稳定版；多数 SDK 与文档示例默认协商此版
2025-11-252025-11（最新）Elicitation form/url 模式增强；Sampling 支持 tools + toolChoice；Tool outputSchema / structuredContent / annotations / icons 完善；JSON Schema 2020-12 成默认方言；OAuth 增强（OIDC Discovery、WWW-Authenticate、OAuth Client ID Metadata）；实验性 Tasks 原语；治理已交 Linux Foundation

废弃状态（2025-11-25） ​

项状态替代
旧 HTTP+SSE transport（2024-11-05）deprecated（仍可向后兼容）Streamable HTTP
sampling.includeContext = thisServer / allServerssoft-deprecatedsampling capability 声明或省略

客户端生态 ​

客户端厂商配置方式
Claude DesktopAnthropicclaude_desktop_config.json 的 mcpServers
Claude CodeAnthropic.mcp.json 或 CLI 命令
CursorAnysphere设置面板 → MCP
Cline开源VS Code 扩展配置
VS Code Copilot ChatMicrosoft.vscode/mcp.json
ChatGPT（Connectors）OpenAI系统连接器配置
MCPJam社区Web UI

claude_desktop_config.json 中 command + args 须用绝对路径，否则 server 无法启动。

官方资源 ​