1
┌─────────────────────────────┐
2
│  Host（Claude Desktop / IDE）   │  ← AI 应用本体
3
│  ┌─────────────────────────┐ │
4
│  │  Client（协议连接器，1:1 到 Server）  │
5
│  └─────────────────────────┘ │
6
└──────────┬──────────────────┘
7
           │  JSON-RPC 2.0
8
┌──────────▼──────────────────┐
9
│  Server（工具/资源/提示词提供者）│  ← 数据源或外部服务
10
└─────────────────────────────┘

1
// Client → Server
2
{
3
  "jsonrpc": "2.0",
4
  "id": "1",
5
  "method": "tools/list",
6
  "params": {}
7
}
8

9
// Server → Client（响应）
10
{
11
  "jsonrpc": "2.0",
12
  "id": "1",
13
  "result": {
14
    "tools": [
15
      {
16
        "name": "calculate",
17
        "description": "执行数学运算",
18
        "inputSchema": {
19
          "type": "object",
20
          "properties": {
21
            "operation": { "type": "string", "enum": ["add", "multiply"] },
22
            "a": { "type": "number" },
23
            "b": { "type": "number" }
24
          }
25
        }
26
      }
27
    ]
28
  }
29
}

1
// Server → Client（工具列表变了，通知一声）
2
{
3
  "jsonrpc": "2.0",
4
  "method": "notifications/tools/list_changed"
5
}

1
Client                              Server
2
  │                                    │
3
  │──── initialize ──────────────────→│  ① 客户端声明能力和协议版本
4
  │                                    │
5
  │←─── { capabilities, serverInfo } ─│  ② 服务器返回自己的能力集
6
  │                                    │
7
  │──── initialized (notification) ──→│  ③ 客户端确认"我准备好了"
8
  │                                    │
9
  │══════ 正常通信开始 ═══════════════│
10
  │←──→ ping（双向心跳）               │
11
  │←──→ tools/call, resources/read ... │

1
// 从 types.ts 可以看到完整的配置联合类型
2
export const McpServerConfigSchema = z.union([
3
  McpStdioServerConfigSchema(),      // 本地进程：command + args + env
4
  McpSSEServerConfigSchema(),        // 远程 SSE：url + headers + oauth
5
  McpSSEIDEServerConfigSchema(),     // IDE 内 SSE
6
  McpWebSocketIDEServerConfigSchema(),// IDE 内 WebSocket
7
  McpHTTPServerConfigSchema(),       // 远程 HTTP
8
  McpWebSocketServerConfigSchema(),  // 远程 WebSocket
9
  McpSdkServerConfigSchema(),        // 嵌入式 SDK
10
  McpClaudeAIProxyServerConfigSchema(),// Claude.ai 代理
11
])

1
// 来自 client.ts — 导入的 SDK 客户端和传输层
2
import { Client } from '@modelcontextprotocol/sdk/client/index.js'
3
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js'
4
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
5
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
6
import { WebSocketTransport } from '../../utils/mcpWebSocketTransport.js'

1
用户说：帮我搜索 GitHub 上的 MCP 相关仓库
2

3
1. Claude Code 从配置加载 GitHub MCP Server 定义
4
2. 启动 stdio 子进程（或连接远程 HTTP endpoint）
5
3. Initialize 握手 → 拿到 Server 的 tools 列表
6
4. 将 tools 注入到 Claude 的上下文：mcp__github__search_repositories
7
5. 用户指令到来 → Claude 决定调用 mcp__github__search_repositories
8
6. MCPTool.call() → client.callTool({ name: "search_repositories", arguments: { query: "mcp" } })
9
7. MCP Server 执行 → 返回 JSON 结果
10
8. 结果如果太大 → 写磁盘 → 让模型用 Read 工具分段读取

1
┌──────────────────────────────────────┐
2
│  Layer 3: Protocol Bindings          │
3
│  JSON-RPC 2.0 / gRPC / HTTP+JSON     │  ← 三种等效的传输绑定
4
├──────────────────────────────────────┤
5
│  Layer 2: Abstract Operations        │
6
│  SendMessage / GetTask / CancelTask  │  ← 11 个核心操作（传输无关）
7
├──────────────────────────────────────┤
8
│  Layer 1: Canonical Data Model       │
9
│  a2a.proto (Protocol Buffers)        │  ← 单一规范数据源
10
└──────────────────────────────────────┘

1
{
2
  "name": "research-agent",
3
  "description": "搜索学术论文并进行文献综述",
4
  "version": "1.0.0",
5
  "url": "https://research-agent.example.com/agent",
6
  "supportedInterfaces": [
7
    {
8
      "url": "https://research-agent.example.com/agent/jsonrpc",
9
      "protocolBinding": "JSONRPC",
10
      "version": "1.0"
11
    }
12
  ],
13
  "capabilities": {
14
    "streaming": true,
15
    "pushNotifications": true,
16
    "extensions": []
17
  },
18
  "skills": [
19
    {
20
      "id": "paper_search",
21
      "name": "论文搜索",
22
      "description": "在 arXiv、Semantic Scholar 中搜索指定主题的论文",
23
      "tags": ["research", "search", "academic"],
24
      "examples": [
25
        "帮我找 2025 年关于 LLM agent 的最新论文",
26
        "搜索 GraphRAG 的相关研究"
27
      ]
28
    },
29
    {
30
      "id": "literature_review",
31
      "name": "文献综述",
32
      "description": "对给定论文列表进行系统性综述",
33
      "tags": ["research", "writing"],
34
      "examples": ["帮我写一份这些论文的文献综述"]
35
    }
36
  ],
37
  "securitySchemes": {
38
    "apiKey": { "in": "header", "name": "X-API-Key" }
39
  },
40
  "defaultInputModes": ["text/plain", "application/json"],
41
  "defaultOutputModes": ["text/markdown", "application/json"]
42
}

1
                     ┌──────────┐
2
                     │ SUBMITTED │
3
                     └────┬─────┘
4
                          │
5
              ┌───────────┼───────────┐
6
              ↓           ↓           ↓
7
        ┌─────────┐ ┌─────────┐ ┌──────────┐
8
        │ WORKING │ │REJECTED │ │ CANCELED  │ ← 拒绝/取消直接到终态
9
        └────┬────┘ └─────────┘ └──────────┘
10
             │
11
    ┌────────┼────────┬─────────┐
12
    ↓        ↓        ↓         ↓
13
┌───────┐ ┌──────┐ ┌──────┐ ┌──────────────┐
14
│COMPLET│ │FAILED│ │CANCEL│ │INPUT_REQUIRED│ ← 中断状态：Agent 需要你澄清
15
└───────┘ └──────┘ └──────┘ ├──────────────┤
16
 终态      终态      终态    │AUTH_REQUIRED │ ← 中断状态：需要升级权限
17
                            └──────────────┘

1
// POST → /agent/jsonrpc
2
{
3
  "jsonrpc": "2.0",
4
  "id": 1,
5
  "method": "tasks/sendMessage",
6
  "params": {
7
    "message": {
8
      "role": "user",
9
      "taskId": null,
10
      "parts": [{ "text": "帮我找 5 篇关于 MCP 协议的论文" }]
11
    }
12
  }
13
}

1
event: task
2
data: {"taskId":"task-123","status":{"state":"submitted"}}
3

4
event: taskStatusUpdate
5
data: {"taskId":"task-123","status":{"state":"working"}}
6

7
event: taskArtifactUpdate
8
data: {"taskId":"task-123","artifact":{"parts":[{"text":"找到了 5 篇..."}],"append":true}}
9

10
event: taskArtifactUpdate
11
data: {"taskId":"task-123","artifact":{"parts":[{"text":"..."}],"append":true,"lastChunk":true}}
12

13
event: taskStatusUpdate
14
data: {"taskId":"task-123","status":{"state":"completed"}}

1
---
2
name: code-review
3
description: 审查代码中的安全问题和最佳实践。当用户请求代码审查时使用。
4
---
5

6
# Code Review Skill
7

8
## 检查清单
9

10
1. 安全漏洞（SQL 注入、XSS、路径遍历）
11
2. 性能问题和代码异味
12
3. 代码风格一致性
13
4. 提供具体的改进建议和代码示例
14

15
## 输出格式
16

17
- **严重程度**：严重 / 高 / 中 / 低
18
- **位置**：filename:line
19
- **问题**：描述
20
- **修复方案**：建议代码