跳到主要内容

审查 learn-mcp-typescript — 2026-08-29

结论: ISSUES(4 条) —— 四门禁我亲自重跑全绿、6 条抽查脚注内容全部属实、主走查与实战三条线均合格; 卡住 PASS 的是出处一项:5 条「第 X–Y 段」范围脚注的人读段号与机跳地址不一致,其中 3 条的机跳地址落在「假朋友」行上 (校验器因范围前缀绕过了一致性检查)。

门禁实跑(末行原样):

book-jargon: 1 本,共 0 处专业词没解释就用了
生面孔配额:段级超额 0 处(上限 1)、节级超额 0 处(上限 5) —— 逐处看:加 --quota
book-dodged: 1 本,共 0 个词被躲开(阈值:原书出现 ≥15 次)
book-verify: 1 本有拆解、共 333 处出处、0 处对不上

已过的项(择要)​

  • 完整性:原书 12 个正文章全覆盖(04 合并原 ch4 SSE + ch5 Streamable HTTP,08 并收原 ch2 的 sampling 概念段, 合并决策在 notes/01-outline.md 有记录);营销页(15/16)与索引(17)正确排除;Foreword/Preface 仅用于作者身份与 AI 润色声明,未被当作正文章覆盖——与书卡 readChapters 一致。
  • 脚注抽查 6 条,内容全部属实
    ^1
    (作者简介,01-fm:131/139)、02[^14](initialized 前报错与通知不应答, 04-fm:514/667)、04[^8] (废弃时生态 20/50+/186 与 2000+ 存量,07-fm:83、06-fm:25)、07[^12](握手日志 protocolVersion 2025-06-18 与 Failed to parse,10-fm:855/861)、09[^13](reject 笔误属实:客户端代码 12-fm:805 确写 action: "reject",规范段 :267 附近代码实为 decline)、10[^12](code_challenge_method=plain, 13-fm:1238)。
  • 与 mcp-spec 书架口径三处一致:① 原语——03 章「模型/应用/用户各管一件」与 mcp-spec#03-server-primitives.md essence 逐字对得上;② 传输层——04 章[^21]「砍 HTTP 会话、GET 流、Last-Event-ID 可恢复 SSE、改 subscriptions/listen」 与 mcp-spec#05-transports.md 的废弃表逐项一致;③ 能力协商——02 章[^24] 与总纲 §5 的「有会话握手→每请求 自带身份的无状态协议」与 mcp-spec#index.md essence 一致,MRTR 引法与 #04 一致。未发现把书里说法写成 规范说法(或反之)的错位——02 §8 还把「作者经验建议(先交换 capabilities)」与「规范硬性要求(三步)」分开标了。
  • SSE+Streamable HTTP 合并:04 章覆盖了两原章的承重内容(SSE 概念与格式/双端点/Express 代码/cURL 三步/ Inspector add(5,10)=15/废弃声明与生态规模;单端点 /mcp/Accept 双类型/mcp-session-id 头/eventStore+ Last-Event-ID 重放/通知两端写法),「每一代的毛病是下一代的样子」的并章理由成立。
  • 实战三条线:读完 03 能照写出最小 server(McpServer+三件套+connect+Inspector 七步,first=2 second=4→"8" 等真值);06 客户端连接五站带真数据(StdioClientTransport→toLLMTool→tool_calls→callTool);04 传输线两代 cURL 走查带真 session id 与 event id。抽核的 2 章主走查(03「multiply 的一生」、04「同一 add 工具两代传输+ 断线重放」)每步旁边有具体数/字串,符合红线二加强。
  • 判断块 15 个(总纲 4 + 各章 11)全部带「如果错,会错在」;03 章无判断块不违规(§6 已分「有证据/作者判断」)。
  • 总纲:六节齐(另加一节「今天读,要修正的三处」,属本书必需的加餐);§3 主线九步独立成篇,海拔正确 (术语就地一句解释、机制细节留章节层);兑现表 22 行,抽核 6 行全部兑现。
  • 书卡:readState/readChapters/claims/notCovered/soWhat 填写完整,与拆解实际覆盖一致。
  • 无台账泄漏(结尾 colophon 与样板书同格式);TODO(没懂): 零命中;三类空转词零命中。

问题清单​

  1. [02/07/08/09:脚注] 5 条范围段号脚注的「第 X–Y 段」与首个机跳地址不一致,其中 3 条地址落在假朋友行上 — 违反出处写法「『第 N 段』和 file:N 两个数永远一致」;book-verify 的正则只抓「第 (\d+) 段」单数前缀, 范围写法天然绕过一致性检查,所以 333 处全绿也没拦住。逐条:
    • 02-jsonrpc-and-handshake.md [^22] 及原文地图「SSE 与 Streamable HTTP 概念」行:地址 :903 搜「/messages」 落在 from "./utils/messages.js" import 行(模块路径,不是 SSE 端点);SSE 端点概念实见原 ch2 文本 :2392 一带。 人读段号写 2368-2476,与 :903 也不相接。
    • 07-hosts-and-mcp-json.md [^13]:「第 713-778 段」配 :145 搜「dev」——:145 的命中是 "developing" 的子串; 真正的 "dev": {watch, debug} 配置在 :730-732(恰在所述范围内),地址应指到那里。
    • 08-sampling.md [^11]:「第 549-622 段」配 :5 搜「sampling」——:5 是章标题「Delegating Tasks with Sampling」, 对「客户端声明 capabilities.sampling」这一论断不构成证据;实证据在 :558 与已并列引用的 :605,应删 :5、收窄段号。
    • 09-elicitation.md [^5]:「第 240-289 段」配 :149(内容相关——两扇门里 accept/decline 那句,但在所述范围之外)。
    • 09-elicitation.md [^13]:「第 802-806 段」配 :263(内容相关——规范段把 decline 称作 "reject type message", 但客户端代码 action: "reject" 实见 :805,地址应与段号对齐)。 建议:逐条把机跳地址改到与人读段号同一段;另案考虑给 book-verify 补范围前缀的一致性检查(那是改尺子,需主人定夺)。
  2. [03-first-server.md §3 末] 正文许诺指错节号 —「记住『模板』这两个字——第 6 节测试时,它会变成一个大坑」, 坑实际兑现在 §5 主走查第⑥步(resources/list 为空);§6 是「作者的判断与证据」。总纲兑现表该行 (应兑现在 03 §5 第⑥步)是对的且标了 ✓,但正文里的指针写错了——兑现表逐行核时没回头核正文指针。改成「第 5 节」。
  3. [08-sampling.md §5、可带走 #8;index.md §5] 与 mcp-spec#04 的口径不完整:sampling/roots 在 2026-07-28 版 已废弃(SEP-2577)这一点全书拆解漏标 — 08 §5 引 mcp-spec#04-mrtr-and-client-features.md 说「概念与字段没变, 信封换了」,可带走 #8 说「2026-07-28 起这类请求改走 MRTR 模式」;但被引的那一章明示:Sampling 与 Roots 已废弃、 新实现不应采用(sampling 改直连 LLM 厂商 API,roots 改用工具参数/资源 URI/服务器配置),只有 elicitation 活跃。 总纲 §5「今天读,要修正的三处」也没收这条。08 是讲 sampling 的整章,读者照做新功能会踩在废弃能力上。 建议:08 §5 与可带走补一句废弃事实(废弃窗口内旧实现仍可用),总纲 §5 加第四行或并入第二行。
  4. [04-web-transports.md] 两原章的作业(assignment)未交代 — 原 ch6 的 SSE 电商服务器作业(06-fm:740)与 原 ch7 的通知作业(07-fm:1328)在 04 章只字未提;对照 03 §7 对自己原章的电商作业是有交代的。轻微覆盖缺口, 在 04 §8 边界里补一行即可。

复核路径​

  • 四门禁:node scripts/book-{jargon,jargon --quota,dodged,verify}.mjs learn-mcp-typescript
  • 问题 1 的原文证据:library/learn-mcp-typescript/text/ 的 04-fm:903/2392、10-fm:145/730、11-fm:5/558/605、 12-fm:149/263/805
  • 问题 3 的书架证据:../ai-protocol-reference/docs/mcp-spec/04-mrtr-and-client-features.md §4.4 表格 (Sampling/Roots「已废弃」,Elicitation「活跃」)与 index.md 的 Logging 废弃注记