主题
MCP 官方文档本地镜像（仅 2026-07-28 当前版本）
本目录是 Model Context Protocol 官方文档的本地 Markdown 镜像，只包含当前有效的规范修订版 2026-07-28。
关于"不收什么"
刻意没有镜像以下内容，因为它们已经过时或被官方弃用：
| 排除对象 | 原因 |
|---|---|
specification/2024-11-05、2025-03-26、2025-06-18、2025-11-25 | 旧规范修订版。2026-07-28 是无状态化的破坏性改版，旧版对"握手 / 会话"的描述会让你得出错误结论 |
client/sampling.md | 已弃用（SEP-2577） |
client/roots.md | 已弃用（SEP-2577） |
server/utilities/logging.md | 已弃用（SEP-2577） |
| HTTP+SSE 双端点传输 | 已弃用，由 Streamable HTTP 取代 |
Mcp-Session-Id 会话机制 | 已移除 |
| 第三方中文翻译站 | 官方站有 .md 原文；第三方站点普遍停留在 2024/2025 版本 |
spec/99-avoid-deprecated.md是保留的：它是当前版本里的一张"哪些东西已弃用 + 怎么迁移"清单 —— 用来避免用过时做法，属于正向参考，不是过时文档。
目录结构
mcp-docs/
├── spec/ ★ 规范正文（协议的权威定义，含 MUST/SHOULD）
├── docs/ 概念与教程（更好读，适合入门）
├── extensions/ 扩展：MCP Apps / Tasks / Skills / 授权
├── registry/ MCP Registry（服务端注册表）
├── seps/ 规范增强提案索引（含 42 篇提案链接）
├── community/ 治理、特性生命周期、SDK 分级、路线图
└── sync.ps1 重新同步脚本推荐阅读路径
A. 先建立整体认知（1 小时内）
docs/01-what-is-mcp.md 什么是 MCP、解决什么问题
docs/02-architecture.md 三角色：Host / Client / Server
docs/03-server-concepts.md Tools / Resources / Prompts 三者区别
docs/04-client-concepts.md Elicitation 等客户端能力
spec/04-versioning.md ★ 为什么"没有握手了"、新旧如何共存B. 要动手实现（照着抄）
docs/08-build-server.md 写一个 Server
docs/09-build-client.md 写一个 Client
spec/12-transport-streamable-http.md ★ 传输层所有硬规则（单端点/只 POST/头/SSE）
spec/20-server-tools.md ★ tools/list 与 tools/call 的完整 schema
spec/26-schema-usage.md JSON Schema 2020-12 与 $ref 安全要求C. 要落地到生产
docs/13-authorization-tutorial.md 授权流程
docs/14-security-best-practices.md ★ 安全底线
spec/16-authorization-security-considerations.md 协议层的安全考量
spec/23-util-caching.md ttlMs / cacheScope（网关友好）
spec/19-server-discover.md server/discover 能力发现
extensions/08-tasks.md 长时异步任务
registry/02-quickstart.md 发布到公共注册表D. 只想快速排错
docs/16-debugging.md 调试方法
docs/15-inspector.md MCP Inspector（可直接抓报文）
spec/06-patterns-mrtr.md 多轮往返：为什么"没有反向请求了"
spec/99-avoid-deprecated.md ★ 别用了哪些东西关键变更速查（2026-07-28 相对旧版）
| 主题 | 现在怎么做 | 别再怎么做 |
|---|---|---|
| 起手 | 第一个 POST 就是业务请求 | initialize 握手 |
| 版本/能力 | 每个请求在 params._meta 里带 | |
| 会话 | 无协议层会话；跨调用状态用显式句柄 | Mcp-Session-Id |
| 服务端要输入 | resultType: "input_required" + requestState，客户端换新 id 重试 | |
| 服务端推送 | subscriptions/listen 的请求作用域流 | GET /mcp 独立 SSE 流 |
| 断流恢复 | 不支持 | Last-Event-ID |
| 取消 | 关闭该请求的 SSE 响应流 | notifications/cancelled（那是 stdio 的做法） |
| 列表结果 | 带 ttlMs / cacheScope，可安心缓存 | |
| 网关路由 | Mcp-Method / Mcp-Name / Mcp-Param-* 头 |
中文版
zh/ 目录是中文译文（同为 2026-07-28，不含已弃用内容）：
| 文件 | 说明 |
|---|---|
GLOSSARY.md | 术语对照表 —— 翻译与阅读的统一口径 |
translate.ps1 | 翻译流水线：按标题边界切片、不切断代码块、术语受词表约束、可增量续跑、自愈重译 |
verify.ps1 | 译文体检：六维交叉比对（体积比 / 标题数 / 代码围栏 / 表格 / 列表 / 规范关键词 / 乱码），输出 VERIFY-REPORT.md |
zh/ | 译文输出目录，结构与 spec/ docs/ ... 一致 |
VERIFY-REPORT.md | 最近一次体检结果 |
当前进度
| 项目 | 数量 |
|---|---|
| 镜像页总数 | 67（仅 2026-07-28 当前版本） |
| 人工精译 | 3 |
| 机器翻译 | 64 |
| 合计 | 67 / 67 已完成 |
| 体检结果 | 67 / 67 合格，0 失败 |
体检真实修掉的问题：
spec/16漏译 24 个规范关键词、spec/20与spec/26各漏译 1 个。 详见VERIFY-REPORT.md与zh/README.md中的"体检脚本踩过的坑"。
.cache-translate/是分片级缓存（可断点续传、可按内容哈希失效），不是文档内容，可以安全删除。
powershell
./verify.ps1 # 体检：结构与体积是否被截断/错乱powershell
$env:OPENAI_API_KEY = 'sk-xxx'
$env:OPENAI_BASE_URL = 'https://api.deepseek.com/v1' # 任意 OpenAI 兼容端点
$env:TRANSLATE_MODEL = 'deepseek-chat'
./translate.ps1 # 全量（自动跳过已翻译）
./translate.ps1 -Files spec/20-server-tools.md # 只翻指定文件
./translate.ps1 -Force # 重译目前 zh/ 里有 3 篇人工精译（spec/05-patterns-overview、spec/18-server-overview、spec/19-server-discover），其余待流水线生成。
重新同步
powershell
cd examples/demo/mcp-docs
./sync.ps1脚本会把所有页面重新拉一遍（覆盖同名文件）。官方每个页面 URL 后面加 .md 就是纯 Markdown 原文。
官方入口
镜像时间：2026-09-20（
2026-07-28为当时最新稳定修订版）。