MCP
知识库简介
Model Context Protocol（MCP）是一套让 AI 应用以统一方式连接外部能力与上下文的开放协议。本知识库不把目标停在“会复制一段 server 配置”，而是让初学者能：
- 解释 host、client、server 与双向能力；
- 读懂 JSON-RPC 生命周期和 capability 协商；
- 为 tools/resources/prompts 与 roots/sampling/elicitation 选择正确边界；
- 比较 stdio 与 Streamable HTTP；
- 做授权、安全、调试与版本审查；
- 用离线项目验证消息、schema、错误和实验性 Tasks 的关键规则；
- 用真实 loopback HTTP 往返验证 Streamable HTTP、session 与 OAuth resource boundary。
知识库分两层：
- 学习路线：7 篇稳定核心课程与可运行项目，先学这一层；另有 1 篇前沿观察专题，不作为稳定前置。
- 官方文档参考层：任务开始前已有的 18 篇本地中文摘要，均采用“核心结论—主要内容—注意事项—相关页面”压缩模板，不是上游正文镜像或完整翻译。它们原则上保持冻结并按需查阅；已确认的问题只做窄范围勘误。
来源边界：学习路线是本项目原创讲解；18 篇历史摘要现已逐页标为 curated / needs-review，准确反映“本地整理、尚未完成当前事实与来源恢复”的状态。由于它们仍位于冻结参考树，公开门禁继续全部生成 stub；只改 frontmatter 不能放行正文。真正独立且完成验证的重写应迁入学习路线层，不能把本地摘要误标成 third-party / frozen-reference 来绕过门禁。
MCP 文档许可不能统一写成 MIT
官方旧
modelcontextprotocol/docs仓库以 MIT 归档；项目迁入modelcontextprotocol/modelcontextprotocol后，2026-01-05 的许可切换规定普通新文档贡献使用 CC BY 4.0，未重新许可的旧贡献保留原许可。跨切换演进的页面可能包含不同许可贡献。因此当前参考层使用page-specific：在完成页面级提交历史、署名与改动说明核验前，公开站点继续只显示来源跳转页。
2026-07-20 参考层审计边界
抓取时刻之前最近的官方仓库提交是
76ceb47f，当时 18 个来源路径都存在；本地没有保存 HTTP 响应哈希或 deployment revision，因此不能声称抓取正文与该 tree 逐字节一致。提交历史只支持把“版本管理”和“示例服务器”视为 MIT 恢复候选，把“使用 Agent Skills 构建”和“客户端最佳实践”视为 CC BY 4.0 恢复候选；其余 14 页跨许可切换，继续失败关闭。候选也必须先补齐固定来源、许可通知、署名/改动说明和事实复核，不能因找到许可证就自动发布。
动态事实边界
本路线按 2026-07-21 获取的第一方资料复核。官方版本页仍把
2025-11-25标为 latest；2026-07-28仍是/specification/draft下的 release candidate，且日期晚于当前复核日，尚不能作为当前稳定互操作合同。两个项目都只实现2025-11-25教学子集，不混入 candidate 的无 initialize、server/discover或逐请求 capability 形状。真实实现必须核对 host、client、server、SDK 与扩展支持，并以实际协商为准。
在总路线中的位置
MCP 是“单 Agent 与工具”阶段的按需互操作分支。课程目录中的编号只表示展示顺序；只有当项目需要跨进程、跨产品或跨组织标准化交换工具、资源、提示或 client features 时，才需要进入本库。开始前应具备：
- API：HTTP、认证、超时与错误；
- JSON：JSON 与 JSON Schema；
- 若主要目标是暴露或调用 tools，先学 Tool Calling（含 Function Calling），理解模型如何选择工具、host 怎样验证与调度；
- 在连接不可信 resource、远程 server 或把协议检查写成回归用例前，完成总路线的早期安全与评测 milestone。它不是整门 AI 安全与评测体系的前置要求。
MCP 进一步把工具、上下文和 client features 标准化为跨实现的协议边界。它不是 Agent 的规划循环，也不是 Agent 核心 的普遍前置；可在 Agent 核心前后按互操作需求学习。只使用进程内函数、直接 SDK 或既有私有接口且没有协议互操作需求时，可以暂不学习 MCP。
学习目标
- 分清 host、client、server，以及数据层与传输层。
- 用方向矩阵解释 server features 与 client features。
- 正确区分 request、response、notification 和双向 request ID。
- 解释初始化、协议版本选择、capability/sub-capability 与运行/关闭。
- 写出 tool input/output schema，并区分协议错误和工具执行错误。
- 理解 roots、sampling、elicitation 与 Tasks 的控制权和安全边界。
- 比较 stdio、Streamable HTTP 与旧 HTTP+SSE 资料。
- 使用 Inspector 和分层日志定位故障，记录四类版本事实。
- 完成离线数据驱动验证项目，理解它为何不是官方 conformance suite。
- 运行真实 loopback Streamable HTTP，区分 transport、session、OAuth resource policy 与消息 schema。
前置知识
- 会读 JSON 对象、数组和最小 JSON Schema。
- 理解 HTTP request/response、status code、bearer token、timeout。
- 能在 Windows 11 / PowerShell 7 运行
python -B script.py。 - 知道 stdout 与 stderr 的区别。
- 不要求先会某个 MCP SDK；先学协议，再选实现。
核心心智模型
| 能力拥有者 | 主要能力 | 典型请求方向 |
|---|---|---|
| server | tools、resources、prompts、logging、completions | client → server |
| client | roots、sampling、elicitation | server → client |
| 双方/utility | ping、progress、cancellation、实验性 Tasks | 依具体方法与 capability |
capability 表示“该会话声明可用的协议功能”，不等于用户已同意、资源已授权或 server 内容可信。
推荐学习顺序
| 顺序 | 课程 | 解决的问题 | 完成证据 |
|---|---|---|---|
| 1 | 架构与角色 | 谁连接谁，双向能力和控制权在哪里？ | 能画出多 server host 与信任边界 |
| 2 | Primitives 与工具契约 | 何时选 tool/resource/prompt/root/sampling/elicitation？ | 能为贯穿场景选择能力并写 schema |
| 3 | 生命周期、能力协商与传输 | 消息以什么顺序、方向和传输运行？ | 能手写握手并分层定位失败 |
| 4 | 授权与安全边界 | capability 可用后，怎样防越权和泄露？ | 完成一张有预防/检测/恢复的威胁模型 |
| 5 | Inspector、调试与版本管理 | 怎样用实际证据排错和升级？ | 完成七层问题单与四版本表 |
| 6 | 项目：离线 MCP 消息验证 | 怎样把关键协议规则变成回归检查？ | 54 场景与 108 tests 全通过 |
| 7 | 项目：Loopback Streamable HTTP 与 OAuth 资源边界 | 怎样用真实 HTTP 验证 header/status、JSON/SSE、session、PRM 形状与授权失效？ | CLI PASS/BLOCK，80 tests 四种模式全通过 |
| 8（选修） | 前沿专题：扩展、Apps 与版本兼容 | 怎样区分稳定 core、扩展、实验与草案并安全降级？ | 版本账本 + 兼容矩阵 + 负向互操作测试 |
建议用 11–16 小时完成稳定核心：前 5 课各 60–90 分钟，两个项目各 2–4 小时。前沿专题只在需要扩展或迁移预研时学习。不要一开始顺序阅读 18 篇参考层；遇到具体问题再查。
动手实践入口
主项目：离线 MCP 教学验证器
从仓库根目录运行：
Set-Location ".\docs\MCP" # 进入 MCP 教学项目目录，使后续相对路径可正确解析
python -B .\examples\validate_mcp_messages.py # 运行 54 个离线 JSON-RPC 场景；-B 不生成 __pycache__
python -B .\examples\test_validate_mcp_messages.py # 在普通解释器模式运行全部回归测试
python -B -O .\examples\test_validate_mcp_messages.py # 验证关键协议 gate 没有依赖会被 -O 移除的 bare assert
python -B -W error .\examples\test_validate_mcp_messages.py # 把任何警告升级为失败，及早暴露兼容性问题
python -B -O -W error .\examples\test_validate_mcp_messages.py # 同时覆盖优化模式与严格警告模式的组合当前验收基线：
- 严格 JSON fixture：54 个场景；
- 16 个正向通过、38 个负向按预期拒绝；
- 108 个单元/数据驱动测试；
- 普通与
-O模式、warnings-as-errors 均通过； - 无网络、密钥、第三方依赖或缓存要求。
进阶项目：Loopback Streamable HTTP 与 OAuth 资源边界
先完成离线消息状态机，再运行独立的真实 HTTP boundary：
python -B .\examples\streamable_http\loopback_mcp_http.py demo # 运行真实 loopback HTTP 的正常握手、JSON/SSE 与 session 链路
python -B .\examples\streamable_http\loopback_mcp_http.py attack # 运行攻击链路；输出 BLOCK 代表攻击被成功拒绝
python -B .\examples\streamable_http\test_loopback_mcp_http.py # 普通模式运行 80 个 HTTP boundary 回归测试
python -B -O .\examples\streamable_http\test_loopback_mcp_http.py # 优化模式验证 production gate 不依赖 bare assert
python -B -W error .\examples\streamable_http\test_loopback_mcp_http.py # 将资源、线程和 HTTP 警告提升为失败
python -B -O -W error .\examples\streamable_http\test_loopback_mcp_http.py # 组合最严格的解释器与警告检查当前验收基线：真实 loopback POST/GET/DELETE 与 JSON/SSE 往返；CLI 分别输出 PASS/BLOCK；80 个测试覆盖初始化替代版本、Origin、header/status、Unicode identity/session、PRM 文档/challenge 形状、RFC 8707 resource、scope/tenant/revision、并发、JSON 深度预算、显式恢复、无 cursor 不重放、过期和撤销。详见 项目课程。
授权能力边界
该项目的 HTTP 是真实的，token policy 是离线 fixture。它没有 authorization server、PKCE、验签/JWKS、introspection 或 TLS，不能被描述成“已经实现 OAuth”；其
http://127.0.0.1resource 只验证 PRM 形状，不符合 RFC 9728 的 HTTPS 要求。
第三项目：真实 SDK 最小互操作
完成两个教学项目后，选择一种官方 SDK：
- 按 构建 MCP 服务器 做只读、离线最小 server。
- 用 MCP Inspector 验证 initialize 与 tool/resource。
- 按 构建 MCP 客户端 做最小 client。
- 记录协议规范、协商版本、SDK、client/server 版本。
- 再加一个负向 schema、一个 capability 缺失和一个安全测试。
动态 SDK 命令、包名和参数以实际开发时的官方文档为准，不从本路线猜测。
掌握标准
- 能解释一个 host 为何通常为每个 server 建立独立 client。
- 能不看笔记列出三类 server features 与三类 client features。
- 能为任一消息说明方向、ID、capability 和生命周期状态。
- 能说明
sampling.tools、elicitation mode 与 Tasks 为什么需要 sub-capability。 - 能写有必填、枚举、未知字段策略的 input schema 和可验证 output schema。
- 能区分 JSON-RPC protocol error 与 tool execution error。
- 能说明 stdio stdout 限制与 Streamable HTTP 的 Origin/session/authorization 风险。
- 能解释 token passthrough 为什么被禁止，form/url elicitation 的秘密边界是什么。
- 能按七层法用 Inspector/日志定位问题，并记录四种版本事实。
- 能运行并解释离线项目的 54 场景与 108 tests。
- 能运行 loopback 项目的 CLI
PASS/BLOCK与 80 tests，并解释初始化版本协商、JSON/SSE、Unicode identity/session 和 401/403。 - 能明确指出离线消息验证器未覆盖真实传输；loopback 项目仍未覆盖真实 OAuth、完整规范与 SDK 互操作。
与其他知识库的关系
- Tool Calling（含 Function Calling）：模型/host 如何选择、审批和执行工具；MCP 描述跨进程/服务怎样发现与交换能力。
- Agent Skills：打包“如何完成任务”的程序性知识；MCP 提供“可访问哪些外部能力与上下文”。两者可组合，不互相替代。
- Agent 核心：规划、状态、记忆和执行循环；MCP 只是其集成边界之一。
- A2A：独立 Agent 应用之间的发现、消息、Task 与 Artifact 协议；MCP 面向 Agent/Host 与工具、资源和上下文能力，二者可组合但不可互换。
- API：HTTP、OAuth、重试、幂等和错误处理是远程 MCP 的底层基础。
- AI安全：扩展提示注入、权限、供应链和运行时治理。
- 运行监控：把 request ID、capability 决策、耗时和结果纳入可观测性。
主要参考资料
以下均为 MCP 第一方或协议原始来源，获取/复核日期：2026-07-21。
| 主题 | 来源 |
|---|---|
| 架构 | MCP Architecture |
| 当前规范 | MCP 2025-11-25 Specification |
| 生命周期/能力 | Lifecycle |
| 传输 | Transports |
| 授权 | Authorization、RFC 8707、RFC 9728 |
| schema | Schema Reference |
| tools | Server Tools |
| roots | Client Roots |
| sampling | Client Sampling |
| elicitation | Client Elicitation |
| Tasks | Tasks utility |
| 扩展、Apps 与 Tasks 迁移 | Extensions Overview、MCP Apps、Tasks extension |
| 安全 | Security Best Practices |
| 调试 | MCP Inspector、Debugging |
| JSON-RPC | JSON-RPC 2.0 Specification |
官方文档参考层
以下 18 篇全部是任务开始前已有的本地中文摘要，不是上游正文镜像。2026-07-19 至 20 日已窄范围修正 Roots、logging、elicitation 秘密边界、可选 session、厂商专有 Custom Connectors、Agent Skills 覆盖范围、session hijacking 风险分类，以及已删除的 Example Clients 来源。全部页面仍为 needs-review 并在公开站失败关闭；文件夹限定 wikilink 用于消除同名文件歧义。它们只能反映整理时的资料状态，当前协议与产品事实必须回到稳定规范、目标 SDK/host 和实际能力协商核验。