MCP TypeScript SDK v2 快速入门：用一个文件暴露 AI 工具

本文基于 MCP 官方 TypeScript SDK v2 文档整理。v2 对应新的稳定规范线，与旧版 @modelcontextprotocol/sdk 的导入方式不同。

MCP 把 AI 应用与外部工具、数据源之间的连接标准化。服务端暴露 Tools、Resources 和 Prompts，Claude Code、VS Code、Cursor 或自研 Host 负责连接服务器并把能力交给模型。

最小工具服务器

官方 v2 SDK 将服务端拆成独立包。下面的服务器通过 stdio 暴露一个天气工具：

import { McpServer } from '@modelcontextprotocol/server'
import { serveStdio } from '@modelcontextprotocol/server/stdio'
import * as z from 'zod/v4'
 
serveStdio(() => {
  const server = new McpServer({
    name: 'weather',
    version: '1.0.0'
  })
 
  server.registerTool(
    'get-forecast',
    {
      description: '查询城市天气预报',
      inputSchema: z.object({ city: z.string().min(1) })
    },
    async ({ city }) => ({
      content: [{ type: 'text', text: city + '：晴' }]
    })
  )
 
  return server
})

SDK 会在 handler 执行前根据 Zod schema 验证输入，但业务权限仍需自己实现。

三类原语怎么分工

• Tools：模型可选择调用的动作，例如查询订单、创建工单。
• Resources：由应用选择并提供的上下文，例如文件、数据库记录。
• Prompts：用户可主动选择的模板或工作流入口。

不要把所有能力都设计成 Tool。只读且适合浏览的数据更适合 Resource；稳定的交互模板更适合 Prompt。

从本地走向远程

stdio 适合本地进程和桌面开发工具。远程服务通常使用 Streamable HTTP，并需要补齐：

• OAuth 或受控访问令牌
• Host/Origin 校验
• 请求体与 schema 深度限制
• 超时、取消与并发控制
• 工具调用审计和敏感参数脱敏

升级旧版时不要只改包名。先核对目标规范版本、传输方式和 Host 的兼容性，再逐个迁移工具并跑协议测试。

原文：MCP TypeScript SDK v2