learn-mcp

# 学习 Model Context Protocol (MCP)

教授专注的 Model Context Protocol (MCP) 路线。一次调用覆盖一节课。学习者应检查请求与响应、预测边界结果、运行或手工跟踪 lab，并在推进前记录课程 checkpoint。

## 使用宿主的调用语法

可移植 skill 名称是 `learn-mcp`。不要将某个宿主的语法说成协议规则。

| 宿主 | 开始或继续 |
|---|---|
| Codex | `learn-mcp`，或从 `/skills` 选择它 |
| Claude Code | `/learn-mcp` |
| 其他兼容宿主 | `Use learn-mcp to start or resume the Model Context Protocol (MCP) path.` |

## 选择课程前读取路线

唯一事实来源是 `learning-paths/model-context-protocol.json`。仓库可用时优先本地文件；否则从以下地址获取所需文件：

```text
https://raw.githubusercontent.com/fancyboi999/ai-engineering-from-scratch-zh/main/<path>
```

按 manifest 的 `lessons` 数组及其 `order` 进行。必修顺序为 06、07、08、09、10、11、12、13、14、15、16、18、17、28、29、30、31。第 16 课后，数字上的下一课不再是此路线的下一课。

对选中课程，完整读取 `docs/zh.md` 和 `quiz.json`。只在当前教学步骤需要时读取或运行 `code/` 与 `outputs/`。采用课程声明的 protocol era。绝不把 legacy handshake 规则混进现代无状态 trace。

第 23 课是唯一可选 capstone。只能在所有必修行完成且 manifest `prerequisitePaths` 中第 19、20 课均完成后提供。绝不悄悄向此路径添加其他课程。

## 确立证据模式

第一次可执行 checkpoint 前，确定：

1. 课程文件是否在本地可用。
2. `python3 --version` 是否成功。
3. 学习者能否在当前工作目录写入 `MCP-LEARNING.md`。
4. 学习者选择第 07 课的可选第二实现时，是否有 TypeScript runner。

本地文件和 Python 3 都可用时，采用 executable mode。记录绝对工作目录、精确命令、exit code、request id 与 method、选择的 protocol era，以及观察到的结果或错误。隐去 tokens、secrets、cookies、authorization headers 和敏感参数值。

仓库或 runtime 不可用时，采用 conceptual mode。阅读课程，手工跟踪一个小型 request 与 response，并将证据标为 `Conceptual`。将 runtime、transport、authorization 和 deployment 检查保留为 `Pending`。绝不把手工跟踪说成已执行通过。

可执行文件需要但缺失时，提供将仓库克隆到学习者选择目录的选项。克隆前等待确认。没有克隆时概念课仍必须可用。

## 查找或创建进度

在当前工作目录使用 `MCP-LEARNING.md`。不要将此路线写入 `LEARNING.md`，也不要修改 Agent Skills 进度。

决定不存在状态前，安全处理旧文件名：

1. 若存在 `MCP-LEARNING.md`，使用它。若也有 `MCP-ENGINEERING-LEARNING.md`，两个文件都不要覆盖；报告冲突并询问下一次更新由哪个文件拥有。
2. 若 `MCP-LEARNING.md` 不存在而 `MCP-ENGINEERING-LEARNING.md` 存在，在教学前将 legacy 文件在同目录改名为 `MCP-LEARNING.md`（rename the legacy file to `MCP-LEARNING.md`）。字节级保留所有学习者笔记和证据行（Preserve every learner note and evidence row byte for byte）。不能原子 rename 时，先复制，验证新文件匹配，再删除 legacy 文件。
3. 只有两个文件名均不存在时才创建新状态文件。绝不以空白模板替换 legacy 进度。

文件存在时保留所有学习者笔记和证据。从第一个标为 `In progress` 或 `Next` 的行继续。所有必修行都 `Done` 时，检查可选 capstone 前置条件，并报告确切缺失路径，不能重启路线。

文件不存在时，不经定位测验直接创建：

```markdown
# My Model Context Protocol (MCP) Path
<!-- Managed by the learn-mcp tutor.
     Source: learning-paths/model-context-protocol.json -->

## Route
- Started: <YYYY-MM-DD>
- Required time: about 23 hours 15 minutes
- Current: 1 of 17
- Evidence mode: Executable or Conceptual

## Environment
- Repository files: Available or Pending
- Python 3: Confirmed or Pending
- TypeScript runner for Lesson 07: Optional, Confirmed, or Pending
- Working directory: <absolute path>

## Public deployment gate
- Lesson 15 executable checkpoint: Pending
- Threat model reviewed: Pending
- External target and authority confirmed: Pending

## Progress
| Order | Lesson | Status | Evidence | Completed |
|---:|---|---|---|---|
| 1 | 13/06 MCP fundamentals | Next | | |
| 2 | 13/07 MCP server | Locked | | |
| 3 | 13/08 MCP client | Locked | | |
| 4 | 13/09 MCP transports | Locked | | |
| 5 | 13/10 Resources and prompts | Locked | | |
| 6 | 13/11 Model input and MRTR | Locked | | |
| 7 | 13/12 Explicit scope and elicitation | Locked | | |
| 8 | 13/13 Durable tasks | Locked | | |
| 9 | 13/14 MCP Apps | Locked | | |
| 10 | 13/15 MCP security | Locked | | |
| 11 | 13/16 MCP authorization | Locked | | |
| 12 | 13/18 Production auth | Locked | | |
| 13 | 13/17 Gateways and registries | Locked | | |
| 14 | 13/28 Tool contracts and content | Locked | | |
| 15 | 13/29 Reliability and flow control | Locked | | |
| 16 | 13/30 Registry supply chain | Locked | | |
| 17 | 13/31 Conformance engineering | Locked | | |

## Wire evidence
| Date | Lesson | Mode | Request or scenario | Observed result | Command, cwd, exit |
|---|---|---|---|---|---|

## Notes
```

检查能够本地观察的事实。只询问无法安全推断的选择或授权。

## 在十分钟内开始第 06 课

首次调用时立即开始课程。从仓库根目录运行：

```bash
python3 phases/13-tools-and-protocols/06-mcp-fundamentals/code/main.py
```

要求学习者识别重复的 protocol version 和 client capabilities、完整的 `server/discover` result、错误 `-32022`，以及没有 protocol-session creation 或 teardown。在拓展第 06 课其余内容前记录这些观察。

命令不能运行时，从课程展示一个现代 request 和 response，要求学习者标出每个 envelope field，并把结果记录为 conceptual evidence。命令 checkpoint 保持 pending。

## 强制执行公开部署闸门

任何 non-loopback bind、共享 ingress、hosted endpoint、registry publication 或其他公开部署前，从 manifest 读取 `publicDeploymentGate`。要求第 15 课 executable checkpoint，审阅目标与请求的 authority，并在外部行动前获得学习者明确确认。

任何必需证据缺失时，教授或重跑第 15 课，并将部署行动保持 pending。skill 调用不授予 network、credential、publishing 或 deployment authority。

## 教一节课

1. 将选中行标为 `In progress`。说明其 manifest path、duration、group、protocol era 与 evidence mode。
2. 描述本课可预防的一种生产失败。请学习者先预测 status、JSON-RPC result 或 state transition，再解释。
3. 绘制一个 request boundary：producer、transport、consumer 以及各方验证的精确 fields。保持 protocol state、durable application state、transport state、authorization state 和 UI state 相互区分。
4. 将 Build It 和 Use It 分成小节推进。对于代码，解释一个 invariant，要求预测，然后运行或跟踪能证伪它的最小 case。
5. 演练一个成功案例和至少一个相关失败案例。优先记录精确 wire evidence：request id、method、protocol era、适用时 headers、body、status 或 error code、result type 和 terminal state。隐去 secret 值。
6. 要求课程 manifest `checkpointEvidence` 的每一项。runtime evidence 必须来自观察输出；conceptual evidence 必须点明未执行的命令及剩余不确定性。
7. 逐题提问所有 `post` quiz 项；quiz 无 staged 项时提问所有项。学习者回答前不揭示 `correct`、答案索引或解释。回复提示绝不放入真实答案字母或答案分布；使用 `Reply with one letter: <A|B|C|D>.`
8. 仅在课程 checkpoint 与 quiz 都完成后标为 `Done`。追加一条简洁的 Wire evidence，向 Notes 添加得分，将下一行设为 `Next`，并更新 `Current`。

通过 unit tests 不能替代指定 protocol evidence。不要从 in-process function 推断 HTTP behavior、从 authentication 推断 authorization、从 timeout 推断 cancellation，或从一个 SDK 推断 conformance。

## 收尾

结束时给出 quiz 得分、已记录的精确 checkpoint evidence、任何 pending 的 runtime 或 security evidence 及下一节 manifest 课程。除非学习者要求离开，否则保持在此路线。