6600万次npm下载，27000个依赖包——这是MCP TypeScript SDK截至2026年4月的成绩单。但数字背后有个更狠的事实：AI模型干了这么多年，居然到今天才用上"通用接口"。
以前每接一个新数据源，你都要手写一套桥接代码。Anthropic 2023年憋出来的MCP（Model Context Protocol，模型上下文协议），本质上就是给AI造了个USB口：插上去就能用，拔下来就能换。现在谷歌、OpenAI都进场了，这协议从"Anthropic私货"变成了行业基建。
本文基于官方TypeScript SDK文档，把架构、工具、资源、提示词这些核心模块拆清楚。不聊概念，只聊你怎么用。
两层架构：McpServer和Server到底啥区别
SDK藏了个容易踩的坑——它有两套API。
Server是底层原语：手动处理JSON-RPC消息、协议版本协商、能力声明。适合你要完全控制通信流程的场景，比如自定义传输层或者调试协议细节。
McpServer是高层封装：工具注册、资源暴露、提示词管理，全部链式API搞定。99%的生产代码应该用这个。
打个比方：Server像TCP套接字，McpServer像Express框架。除非你在写框架本身，否则别碰底层。
初始化McpServer只需要三行：
const server = new McpServer({ name: "weather-server", version: "1.0.0" });
server.tool("getForecast", { city: z.string() }, async ({ city }) => { ... });
const transport = new StdioServerTransport(); await server.connect(transport);
工具定义用Zod做运行时校验，类型推导直接打通。你写一遍schema，TypeScript和运行时都认。
工具、资源、提示词：SDK的三板斧
MCP协议把AI能调用的东西分成三类，SDK的API设计完全对应这个分类。
工具（Tools）：让AI执行动作。查天气、调API、写文件，都算。关键特性是Zod校验 + 结构化错误。你的工具抛错时，可以返回isError: true和具体message，AI会据此决定重试还是换策略。
工具还能加annotations（注解），告诉AI这个操作是"只读"还是"破坏性"的。比如删除操作标记destructiveHint: true，模型会自动多问用户一句确认。
资源（Resources）：给AI提供上下文。分静态URI和动态模板两种。静态的像file:///config.json，动态的像file:///logs/{date}.txt。模板用URI Template语法，参数自动提取。
提示词（Prompts）：预置的可复用指令模板。可以带参数，比如/summarize?style=brief。客户端发现这些提示词后，用户一键就能触发复杂工作流。
这三类在SDK里是平行API：server.tool()、server.resource()、server.prompt()。设计意图很明显——协议层面一视同仁，但你的业务逻辑自己拆清楚。
Sampling：服务器主动调用LLM的野路子
大部分MCP交互是"客户端请求→服务器响应"的单向模式。但有个高级功能打破了这规矩：sampling（采样）。
场景是这样的：你的MCP服务器收到一个复杂查询，需要LLM帮忙拆解或者生成中间内容。这时候服务器可以反向调用客户端提供的LLM能力，拿到结果再继续执行。
流程变成：用户提问 → 服务器发现需要推理 → 发sampling请求给客户端 → 客户端调LLM → 结果返回服务器 → 服务器完成最终响应。
这个设计很微妙。它让MCP服务器不再是" dumb工具"，而是能自主决策、自主调用AI的agent节点。但代价是复杂度：你需要处理异步采样请求、上下文窗口管理、可能的循环调用。
SDK的sampling API长这样：
const result = await server.requestSampling({ messages: [...], maxTokens: 500 });
客户端必须显式声明supportsSampling: true才会响应。这是个安全闸门——服务器不能随便烧用户的token。
传输层选型：stdio还是HTTP
SDK内置两种传输实现，选错会直接影响部署架构。
StdioTransport：标准输入输出，进程间通信。适合本地CLI工具、桌面应用内嵌、或者任何"服务器和客户端跑在同一台机器"的场景。简单、无网络依赖、调试直接打console。
StreamableHTTP：HTTP长连接，支持SSE（Server-Sent Events）流式响应。适合远程部署、多客户端并发、或者需要穿越防火墙的场景。2025年3月协议更新后，这个传输支持真正的无状态扩展——每个请求独立鉴权，服务端可以随便水平扩容。
有个细节容易忽略：HTTP传输的path配置。默认是/mcp，但你可以改。如果你把多个MCP服务器挂在同一个域名下，用path区分比开多个端口干净。
生产环境建议直接上StreamableHTTP + 反向代理。stdio看着省事，但跨机器部署时你会重新写一遍网络层。
自动补全与结构化日志：被低估的生产力
SDK有两块功能文档没强调，但实际开发很香。
Completions（自动补全）：工具参数、资源URI、提示词参数，都可以注册补全回调。用户在客户端输入时，实时拿到建议列表。实现方式类似LSP的completionProvider：
server.setCompletionHandler("resource", "file", async (uri) => { return { values: await listFiles(uri) }; });
Structured Logging：SDK内置JSON格式日志，级别从debug到error。关键是可以附加任意metadata，比如请求ID、用户ID、工具名。接入ELK或者Datadog时，过滤和聚合直接可用。
这两块属于"用上就回不去"的基础设施。补全降低用户犯错率，结构化日志降低你排查问题的血压。
Agentic AI Foundation现在接手维护MCP， Anthropic、Google、OpenAI都在委员会里。但协议的真正考验才刚开始：当各家的大模型都想扩展这个协议时，标准会不会膨胀到失控？
SDK的下一个大版本据说要支持工具链（chained tools）和更细粒度的权限模型。但现在的问题是：你的MCP服务器，准备好从"demo玩具"变成"生产负载"了吗？
热门跟贴