跳到主要内容

章节切分大纲 — learn-mcp-typescript(11 章)

原书 12 个正文章 → 我们 11 章。ch4(SSE)+ch5(Streamable HTTP)并成一章(同一条推理链:把服务器放上网络); ch2 的 sampling 概念段并入第 08 章统一讲;其余一章对一章。

每节一行:「进来时以为… → 出去时知道…」。自查:任意两行的「出去时知道」不得是同一件事。

01 为什么需要 MCP(原 ch1)​

  • s1 现象:以为 AI 应用就是「调个大模型 API」→ 知道真正费劲的是把每个外部能力挨个粘进来,而且换个应用重粘一遍
  • s2 历史:以为 MCP 是凭空冒出来的 → 知道它是 SOAP→REST→GraphQL→gRPC 这条「接口怎么描述自己」长链上最新一环
  • s3 标准:以为「我们会编程,什么都能粘」是优点 → 知道作者的论点是「能粘不等于该粘」,粘的代价就是标准的收益
  • s4 定义:以为 MCP 是又一个框架 → 知道它是一个开放协议,只管「应用怎么向 LLM 提供上下文」,官方自比 USB-C
  • s5 生态:以为 MCP 服务器要自己从头写 → 知道已有一大堆现成的(Blender/GitHub/Playwright),一个 mcp.json 就接上

02 徒手实现一遍协议(原 ch2)​

  • s1 消息:以为 MCP 消息是某种新格式 → 知道它就是 JSON-RPC 2.0,四个字段 jsonrpc/id/method/params
  • s2 传输:以为协议绑死某种通信方式 → 知道 transport agnostic,所有传输共用一个 start/send/close 接口
  • s3 STDIO:以为 STDIO 传输很神秘 → 知道就是「客户端把服务器 spawn 成子进程,写它 stdin、读它 stdout」
  • s4 握手:以为连上就能直接调工具 → 知道必须 initialize→回应 capabilities→notifications/initialized 三步,早一步都报错
  • s5 特性与通知:以为只有请求-响应一种消息 → 知道还有无 id 的 notification(进度、日志),来了不该有人回
  • s6 远端传输一瞥:以为 STDIO 能包打天下 → 知道本地用 STDIO、上网用 SSE/Streamable HTTP(细节第 04 章)

03 第一个真正的服务器(原 ch3)​

  • s1 三件套:以为服务器只能暴露「函数」 → 知道有 tools(做事)/resources(给数据)/prompts(给模板)三种,各归不同人控制
  • s2 资源:以为资源就是文件 → 知道资源是「给 LLM 的上下文」,固定名与 ResourceTemplate 模板两种
  • s3 模式:以为参数校验要自己写 → 知道用 Zod 声明输入,SDK 自动生成 JSON Schema 给客户端看
  • s4 搭起来:以为用 SDK 要学很多 → 知道 McpServer + server.tool/resource/prompt + connect(transport) 五步出活
  • s5 测试:以为测试要自己写客户端 → 知道 Inspector 可视化+CLI 两模式,模板资源还不在普通 resources/list 里

04 把服务器放上网络(原 ch4+ch5)​

  • s1 为什么:以为 STDIO 换个参数就能上网 → 知道上网要 HTTP,先有 SSE 后有 Streamable HTTP
  • s2 SSE:以为 SSE 是一种新协议 → 知道是 HTTP 长连接 + text/event-stream 单向推,MCP 拆 /sse 与 /messages 两端点
  • s3 废弃:以为书讲 SSE 就该学 SSE → 知道 SSE 传输 2025-05 已废弃,但 2000+ 存量服务器还得会接
  • s4 Streamable HTTP:以为它是 SSE 改名 → 知道单端点 /mcp,POST 发消息,Accept 双类型让服务器自选回 JSON 还是 SSE 流
  • s5 会话:以为 HTTP 无状态就没会话 → 知道 mcp-session-id 头承载会话,initialize 时发、之后每请求带
  • s6 断线续传:以为断线=重来 → 知道 eventStore + Last-Event-ID 让服务器重放漏掉的消息(附规范 2026 已砍的对照)
  • s7 通知:以为通知就是打印日志 → 知道要 logging 能力 + sendNotification + 客户端 setNotificationHandler 三件套

05 低层 API 与整洁架构(原 ch6)​

  • s1 动机:以为高层 API 够用 → 知道三件事逼你下低层:生命周期、架构自由、sampling/elicitation 只有低层
  • s2 上下文管理器:以为这是 Python 专利 → 知道它是「enter 拿资源、exit 必清理」的模式,TS 可以自己实现 With
  • s3 低层服务器:以为低层=更复杂 → 知道只是 McpServer 换 Server,注册式换 setRequestHandler(schema, fn)
  • s4 目录架构:以为工具只能堆在一个文件 → 知道 tools/ 目录 + Tool 接口,工具定义不碰框架、可单测
  • s5 调用处理:以为收到 tools/call 直接执行 → 知道要过三关:按名找工具、Schema.parse 校验、再调 callback

06 自己写客户端(原 ch7)​

  • s1 徒手客户端:以为客户端是 Claude 那种大件 → 知道五步:连接、列特性、选特性、问参数、展示
  • s2 痛点:以为能调通就完了 → 知道用户得背工具名和参数,这是「knowing」的负担
  • s3 接 LLM:以为 LLM 直接懂 MCP → 知道要把 tools/list 的结果翻译成 LLM 的 function 格式(toLLMTool)
  • s4 闭环:以为 LLM 会直接执行工具 → 知道它只回 tool_calls(名字+参数 JSON),真正执行的还是 client.callTool

07 不写代码的消费:宿主与 mcp.json(原 ch8)​

  • s1 宿主:以为用 MCP 必须写客户端 → 知道 VS Code/Claude Desktop 这种 host 内置 client+LLM+配置
  • s2 mcp.json:以为装服务器要安装程序 → 知道「安装」=往 mcp.json 的 servers 里加一条 entry,三种传输三种形态
  • s3 密钥:以为密钥只能写进配置 → 知道 inputs 的 promptString+password 让密钥运行时问、不落盘
  • s4 走查:以为接上服务器就会自动用 → 知道要在 agent 模式给 prompt,必要时 #工具名 点名,还要过批准
  • s5 排障:以为出错只能猜 → 知道 Output 面板有完整握手日志,stdout 混一行非 JSON 就会 parse 失败
  • s6 消费侧安全:以为装上就安全 → 知道四条底线:密钥入 inputs、每次批准、限制目录、只用审核过的 registry

08 采样:服务器反过来求你(原 ch9 + ch2 sampling 段)​

  • s1 概念:以为只有客户端能调服务器 → 知道 sampling 是服务器反向请求客户端的 LLM 帮忙
  • s2 为什么:以为服务器自己也能配 LLM → 知道这样服务器不用管密钥/账单/选模型,用户还能人在回路改请求
  • s3 消息:以为采样请求就是一句话 → 知道能带 messages/modelPreferences/systemPrompt/maxTokens,但全是建议
  • s4 服务器侧:以为发采样很复杂 → 知道工具里 server.server.createMessage 一调,等客户端回文本
  • s5 客户端侧:以为客户端自动会答 → 知道要声明 capabilities.sampling + setRequestHandler(CreateMessageRequestSchema)

09 征询:中途再问用户一句(原 ch10)​

  • s1 概念:以为答不上来只能说「没有」 → 知道 elicitation 让服务器中途向用户要缺失的信息
  • s2 两步:以为服务器直接弹窗 → 知道先问客户端、客户端再问用户,两层都能拒
  • s3 消息:以为想要什么都行 → 知道 requestedSchema 只有 string/number/boolean/enum 四种,且禁止索取敏感信息
  • s4 三种结局:以为用户只有填与不填 → 知道 accept(带 content)/decline(明说不要)/cancel(当没看见)三种
  • s5 实现:以为要新学一套 API → 知道服务器 elicitInput、客户端 setRequestHandler(ElicitRequestSchema)

10 安全:从 Basic 到 OAuth2.1(原 ch11)​

  • s1 分级:以为安全是非黑即白 → 知道按数据敏感度分三档,措施跟着档走
  • s2 Basic:以为 Basic Auth 没用 → 知道它防君子不防小人,但中间件 401/403 是最低成本的门槛
  • s3 JWT:以为令牌就是随机串 → 知道 JWT 三段式把 claims 和权限(scopes)签进令牌本身,服务器不用存会话
  • s4 OAuth:以为 OAuth 是另一种令牌 → 知道它是「授权服务器发牌、资源服务器验牌」的三方委派框架
  • s5 SDK 支持:以为要自己实现 OAuth → 知道 ProxyOAuthServerProvider + mcpAuthRouter 两个件就接上外部 IdP
  • s6 落点:以为鉴权挂好就完了 → 知道还要决定挂哪层(服务器/网关),并按工具检查 scope

11 走向生产(原 ch12)​

  • s1 架构:以为 MCP 应用是孤岛 → 知道它常躲在 REST API 后面,validation 用 Zod 挡在入口
  • s2 打包:以为服务器就是 npm 包 → 知道 standalone(沙箱)与 embedded(连客户端)两条路,分发有 Docker/包管理器/仓库三种
  • s3 测试:以为 AI 部分没法测 → 知道单元/集成照旧,AI 输出要对抗测试+黄金 prompt 集
  • s4 可观测:以为上线就完事 → 知道 logging/tracing/metrics 三件套,MCP 特有 token 用量账
  • s5 弹性:以为扩容是云的事 → 知道 LB/限流/熔断可以声明式挂在网关,AI 端点要单独算账
  • s6 未来:以为协议稳定了 → 知道 MCP 还在快速变(SSE 已废),SDK 版本要钉住+Dependabot 盯

自查记录​

  • 02-s4「握手三步」与 04-s5「会话」:一个是「没握手完不许发别的」,一个是「HTTP 上靠头携带会话」,两回事。✓
  • 04-s7「通知」与 02-s5「通知」:02 讲通知这种消息类型是什么(无 id、单向),04 讲在流式传输上怎么发怎么收(能力声明+API)。深浅两层,前者是概念、后者是工程。✓ 不合并。
  • 06-s4「LLM 只回 tool_calls」与 08-s1「服务器反向请求」:方向相反,两回事。✓
  • 08「采样」与 09「征询」:都是服务器反向请求客户端,但一个要 LLM 补全、一个要用户输入;原书分两章,我们也分两章。✓
  • 10-s3「JWT 无状态」与 04-s5「会话」:一个是令牌自包含不存会话,一个是传输层会话 id,两回事。✓