08b - MCP 深度架构解析

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "ghp_xxxxxxxxxxxx"
      }
    }
  }
}

# 初始化时，Server 返回会话 ID
HTTP/1.1 200 OK
MCP-Session-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890

# 后续请求必须携带会话 ID
POST /mcp HTTP/1.1
MCP-Session-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
MCP-Protocol-Version: 2025-11-25

# 终止会话
DELETE /mcp HTTP/1.1
MCP-Session-Id: a1b2c3d4-e5f6-7890-abcd-ef1234567890

# Server 在 SSE 事件中附带 ID
data: {"jsonrpc":"2.0","id":3,"result":{...}}
id: stream-abc-evt-42

# Client 断线重连时
GET /mcp HTTP/1.1
Last-Event-ID: stream-abc-evt-42

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "query_database",
    "arguments": {
      "sql": "SELECT * FROM users LIMIT 10"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "查询返回 10 条用户记录..."
      }
    ]
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params: SQL query is required",
    "data": {
      "field": "sql",
      "reason": "missing required parameter"
    }
  }
}

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

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

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "roots": {
        "listChanged": true
      },
      "sampling": {},
      "elicitation": {
        "form": {},
        "url": {}
      }
    },
    "clientInfo": {
      "name": "MyAIApp",
      "title": "My AI Application",
      "version": "2.0.0",
      "description": "一个自定义的 AI 助手应用"
    }
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": {
      "logging": {},
      "prompts": {
        "listChanged": true
      },
      "resources": {
        "subscribe": true,
        "listChanged": true
      },
      "tools": {
        "listChanged": true
      }
    },
    "serverInfo": {
      "name": "DatabaseServer",
      "title": "Database MCP Server",
      "version": "1.5.0",
      "description": "提供 PostgreSQL 数据库查询和管理能力"
    },
    "instructions": "本 Server 提供数据库查询工具，请确保 SQL 语句安全"
  }
}

{
  "jsonrpc": "2.0",
  "method": "notifications/initialized"
}

// 版本不匹配时的错误响应
{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Unsupported protocol version",
    "data": {
      "supported": ["2025-03-26", "2025-06-18"],
      "requested": "2025-11-25"
    }
  }
}

// Client → Server
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": { "roots": { "listChanged": true }, "sampling": {} },
    "clientInfo": { "name": "DemoClient", "version": "1.0.0" }
  }
}
 
// Server → Client
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": { "tools": { "listChanged": true }, "logging": {} },
    "serverInfo": { "name": "WeatherServer", "version": "1.0.0" }
  }
}
 
// Client → Server
{ "jsonrpc": "2.0", "method": "notifications/initialized" }

// Client → Server
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }
 
// Server → Client
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_weather",
        "description": "获取指定城市的当前天气信息",
        "inputSchema": {
          "type": "object",
          "properties": {
            "city": { "type": "string", "description": "城市名称" },
            "unit": { "type": "string", "enum": ["celsius", "fahrenheit"], "default": "celsius" }
          },
          "required": ["city"]
        }
      }
    ]
  }
}

// Client → Server
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "get_weather",
    "arguments": { "city": "北京", "unit": "celsius" }
  }
}
 
// Server → Client（可选：进度通知）
{
  "jsonrpc": "2.0",
  "method": "notifications/progress",
  "params": {
    "progressToken": 3,
    "progress": 50,
    "total": 100,
    "message": "正在查询天气 API..."
  }
}
 
// Server → Client（最终结果）
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "北京当前天气：晴，温度 28°C，湿度 45%，风速 12km/h"
      }
    ]
  }
}

# stdio 方式
1. Client 关闭 Server 的 stdin
2. 等待 Server 退出
3. 如未退出，发送 SIGTERM
4. 如仍未退出，发送 SIGKILL

# Streamable HTTP 方式
DELETE /mcp HTTP/1.1
MCP-Session-Id: abc123
→ Server 返回 200 OK 或 405 Method Not Allowed

npx @modelcontextprotocol/inspector

我的 MCP Server 连接出现问题。请帮我排查：

环境信息：
- Host 应用：[Claude Desktop / Cursor / Kiro / 自定义]
- 传输方式：[stdio / Streamable HTTP]
- Server 类型：[官方 Server / 自定义 Server]
- 错误现象：[具体错误信息]

请按以下步骤排查：
1. 检查 initialize 阶段是否成功
2. 检查能力协商结果
3. 检查传输层配置
4. 检查消息格式是否符合 JSON-RPC 2.0

以下是我的 MCP Server 的 JSON-RPC 消息日志。请分析：
1. 能力协商是否正确
2. 是否有异常的错误响应
3. 消息顺序是否符合协议规范
4. 是否有性能瓶颈（如超时、重试）

消息日志：
[粘贴 JSON-RPC 消息]