把 AI 接上外挂的标准插座

第一课 · 三个角色

一次 MCP 连接里，有三个东西在配合

点下面三个盒子，看清每个角色是谁、负责什么。理解这一点，后面的一切都顺了。

第二课 · 谁真的懂 MCP

模型不认识 MCP，懂它的是宿主程序

最容易搞混的一点：MCP 协议没有被「训练」进模型。模型只学会了「工具调用」这个通用能力；真正懂 MCP 协议、负责翻译消息的，是 Claude Code 这个宿主程序。点下面三层看各自懂什么、不懂什么。

# 1. 模型输出「工具调用意图」（不是 MCP，是模型的原生能力）
Claude 决定调用 codegraph_status，参数 {}

# 2. Claude Code 把意图翻译成 MCP 协议消息
{ "method": "tools/call", "params": { "name": "codegraph_status" } }

# 3. codegraph 执行，结果再被 Claude Code 翻译回给模型

第三课 · 完整一生

一次 MCP 连接，走完这 6 步

点圆点或「下一步」逐格推进。每一步都配了你电脑上的真实数据，看它每一步到底发生了什么。

第四课 · 方法 vs 工具

tools/list 是「方法」，由协议统一规定

MCP 底层是 JSON-RPC 2.0，每条消息里都有个 method 字段。协议规范定义了一组标准方法，所有 server 都实现同一套——这就是 Claude Code 能用一套代码连任何 server 的原因。点下面的方法，看它是什么、对应哪条消息。

第五课 · 工具的结构

一个「工具」，就是这三样东西

每个通过 tools/list 上报的工具，都是同一个模子：name + description + inputSchema。模型完全没见过 codegraph 的代码，就靠这三样学会用它。点每一段看含义。

{
  "name": "codegraph_trace",
  "description": "Call path between two symbols — how does <from> reach <to>?",
  "inputSchema": {
    "type": "object",
    "properties": {
      "from": { "type": "string" },
      "to":   { "type": "string" }
    },
    "required": ["from", "to"]
  }
}

第六课 · 配置

那段配置，逐字拆开看

这是写在你 ~/.claude.json 里的真实登记信息。点每一行，看它是什么意思。

第七课 · 命名

工具名为什么这么长

点名字的每一段，看它由什么拼成。

第八课 · 底层

一次调用，消息到底怎么跑

MCP 的底层是 JSON-RPC 2.0 消息，走标准输入输出（stdin/stdout）管道。点「发送请求」，看一条消息往返的完整旅程。

{ "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "name": "codegraph_status", "arguments": {} } }

{ "jsonrpc": "2.0", "id": 2, "result": { "content": [ { "type": "text", "text": "Index ready: 1,234 files · 8,901 symbols" } ] } }

第九课 · 传输方式

数据走哪条路：stdio、HTTP、SSE 还是 WebSocket

MCP 的「传输层」是可插拔的。点下面每个传输方式，看它是什么、底层跑在什么之上。

第十课 · 微服务互调

真实世界里：两个 Java 微服务怎么调

你问的 OpenFeign 调用，底层就是最普通的 HTTP + JSON。看一次调用怎么从 A 服务的代码走到 B 服务的代码。

GET /orders/1 HTTP/1.1
Host: order-service
Content-Type: application/json

# body 里装的是 JSON（Jackson 把 Java 对象序列化成的文本）

微服务互调的三大流派

第十一课 · RPC 与 JSON-RPC

JSON-RPC = JSON + RPC

RPC 是「远程过程调用」这个思想；JSON-RPC 就是用 JSON 来编码这种调用的协议。点下面消息的字段，看它对应 RPC 的哪个要素。

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": { "name": "codegraph_status" }
}

附录 · 分类尺子

概念 / 协议 / 框架 / 格式，一眼分清

拿不准一个名词属于哪类？记住这把尺子：协议是「规则」，框架是「代码」，格式是「文字」，概念是「想法」。点下面每类看判断标准。

第十三课 · CLI 与 MCP

同一个程序的两张脸：给人用 CLI，给 AI 用 MCP

CLI 和 MCP 工具不是二选一，而是同一个程序的两种接口。看 codegraph 自己的命令行长什么样——答案就藏在里面（这是你电脑上真实的 codegraph --help 输出）。

# 这些命令，人直接在终端里敲：
  codegraph query   AuthService     # 搜索符号
  codegraph context "实现登录"        # 构建任务上下文
  codegraph callers AuthService     # 谁调它
  codegraph impact  AuthService     # 影响分析
  codegraph status                  # 索引状态

# 而这两条，揭示了全部秘密：
  codegraph serve --mcp             ★ 作为 MCP server 启动（给 AI 用）
  codegraph install                 ★ 把 codegraph 装成各 agent 的 MCP server

秘密二：CLI 命令和 MCP 工具，几乎一一对应

CLI vs MCP，接口上的区别

第十四课 · skill 为什么不够

用 skill 教 CLI，为什么替代不了 MCP

你可能会想：把 CLI 操作指南封装进 skill，教 agent 用，不就跟 MCP 一样了吗？答案：能覆盖七八成，但有 5 个结构性硬伤——MCP 就是为治这 5 个伤而生的。

skill + CLI 的 5 个硬伤（点开看详情）

一个真实例子：找 AuthService 在哪

三者的定位