MCP TypeScript SDK

在 AI 辅助开发蓬勃发展的今天，模型上下文协议已成为连接大语言模型与外部工具、数据源的核心标准。但协议本身只是规范，真正让开发者能够快速构建 MCP 服务器和客户端的，是官方提供的软件开发工具包。MCP TypeScript SDK 正是这样一套基石工具——它由 MCP 协议官方团队维护，用 TypeScript 实现了完整的 MCP 规范，让你能轻松构建生产级的 MCP 服务端和客户端应用。

项目基本信息

一、项目介绍

MCP TypeScript SDK 是构建一切 MCP 应用的起点。它不是一个面向最终用户的工具，而是为开发者提供的一套完整的 API 和抽象层。借助这套 SDK，你可以：

• 创建 MCP 服务器：以简洁的 API 暴露资源、工具和提示。
• 构建 MCP 客户端：连接到任何 MCP 服务器并调用其能力。
• 使用多种传输方式：stdio（适合本地命令行工具）和 Streamable HTTP（适合远程服务）。
• 处理完整的协议生命周期：包括初始化、消息路由、能力协商和会话管理。

核心概念

SDK 围绕三个核心概念构建，对应 MCP 协议的三类主要能力：

二、核心优势

官方出品，协议兼容性保障

作为 MCP 协议官方维护的 SDK，它始终与最新的协议规范保持同步。使用官方 SDK 意味着你不需要手动处理协议消息的序列化、反序列化和生命周期管理，这些复杂细节都已被妥善封装。

极简的 API 设计

SDK 将复杂的协议操作浓缩为极为简洁的代码。创建一个带工具的服务器只需几行代码：

const server = new McpServer({ name: "Demo", version: "1.0.0" });
server.tool("add", { a: z.number(), b: z.number() }, async ({ a, b }) => ({
  content: [{ type: "text", text: String(a + b) }]
}));

配合 Zod 进行参数验证，代码既清晰又类型安全。

灵活的传输层支持

SDK 支持两种主要的传输方式：

• stdio：适合本地命令行工具和桌面 IDE 集成（如 Claude Desktop、Cursor）。
• Streamable HTTP：适合远程服务器部署，支持有状态会话管理和无状态两种模式。当前推荐使用 Streamable HTTP，旧的 HTTP+SSE 传输已被弃用但仍提供向后兼容。

高级特性支持

SDK 不仅覆盖基础功能，还提供了：

• 动态工具管理：允许在运行时启用、禁用、更新或移除工具，服务器会自动发送 listChanged 通知。
• OAuth 授权：支持代理授权请求到外部认证提供商，并提供自定义令牌验证逻辑。
• 向后兼容：支持新旧传输协议的无缝切换。

MIT 开源协议

采用完全商业友好的 MIT 协议，可以自由使用和分发。

三、适用场景

构建自定义 MCP 服务器

这是 SDK 最主要的用途。无论你想让 AI 调用公司内部的数据库、触发 CI/CD 流程、查询天气信息，还是操作文件系统，都可以通过 SDK 将这些能力封装为 MCP 工具或资源。

开发 MCP 客户端应用

如果你正在构建一个需要调用多个 MCP 服务器的 AI 编排层或桌面应用，SDK 的客户端接口可以帮助你发现并调用各种服务器提供的工具和资源。

学习 MCP 协议

官方 SDK 是理解 MCP 协议的最佳学习材料。代码即文档，通过阅读 SDK 源码和示例，你可以深入理解 MCP 的消息流转、能力协商和生命周期管理。

为现有服务添加 MCP 接口

你可以使用 Streamable HTTP 模式，为一个已有的 Express 应用添加 MCP 端点，让 AI 代理能够通过标准协议调用你的业务功能。

四、安装教程

环境要求

安装 SDK

npm install @modelcontextprotocol/sdk

创建你的第一个 MCP 服务器

以下是一个完整的最小化示例——一个带加法工具的 MCP 服务器：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// 创建 MCP 服务器
const server = new McpServer({
  name: "Demo",
  version: "1.0.0"
});

// 添加一个加法工具
server.tool("add",
  { a: z.number(), b: z.number() },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }]
  })
);

// 启动 stdio 传输
const transport = new StdioServerTransport();
await server.connect(transport);

将此文件保存并运行，即可在支持 MCP 的客户端中看到 add 工具。

本地开发与测试

使用 MCP Inspector 可以可视化地调试你的服务器。详见 MCP Inspector 文档。

五、使用示例

以下示例均基于 SDK 的核心 API。

示例一：创建一个资源

资源用于向 LLM 暴露数据，类似于 GET 端点：

// 静态资源
server.resource("config", "config://app", async (uri) => ({
  contents: [{ uri: uri.href, text: "App configuration here" }]
}));

// 动态资源（带参数）
server.resource(
  "user-profile",
  new ResourceTemplate("users://{userId}/profile", { list: undefined }),
  async (uri, { userId }) => ({
    contents: [{ uri: uri.href, text: `Profile data for user ${userId}` }]
  })
);

示例二：创建一个调用外部 API 的工具

工具用于让 LLM 执行操作，可以包含副作用：

server.tool(
  "fetch-weather",
  { city: z.string() },
  async ({ city }) => {
    const response = await fetch(`https://api.weather.com/${city}`);
    const data = await response.text();
    return { content: [{ type: "text", text: data }] };
  }
);

示例三：创建 SQLite 数据库浏览器

这是一个更复杂的示例，展示了如何将数据库查询封装为 MCP 工具和资源：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import sqlite3 from "sqlite3";
import { promisify } from "util";
import { z } from "zod";

const server = new McpServer({
  name: "SQLite Explorer",
  version: "1.0.0"
});

const getDb = () => {
  const db = new sqlite3.Database("database.db");
  return {
    all: promisify<string, any[]>(db.all.bind(db)),
    close: promisify(db.close.bind(db))
  };
};

// 资源：暴露数据库表结构
server.resource("schema", "schema://main", async (uri) => {
  const db = getDb();
  try {
    const tables = await db.all("SELECT sql FROM sqlite_master WHERE type='table'");
    return { contents: [{ uri: uri.href, text: tables.map((t: any) => t.sql).join("\n") }] };
  } finally {
    await db.close();
  }
});

// 工具：执行 SQL 查询
server.tool("query", { sql: z.string() }, async ({ sql }) => {
  const db = getDb();
  try {
    const results = await db.all(sql);
    return { content: [{ type: "text", text: JSON.stringify(results, null, 2) }] };
  } catch (err: any) {
    return { content: [{ type: "text", text: `Error: ${err.message}` }], isError: true };
  } finally {
    await db.close();
  }
});

示例四：动态工具管理

你可以在运行时启用、禁用或更新工具：

const putMessageTool = server.tool(
  "putMessage",
  { channel: z.string(), message: z.string() },
  async ({ channel, message }) => ({
    content: [{ type: "text", text: await putMessage(channel, message) }]
  })
);
// 初始状态下禁用
putMessageTool.disable();

// 当用户通过认证后启用
putMessageTool.enable();

// 或更新工具的参数验证规则
upgradeAuthTool.update({
  paramSchema: { permission: z.enum(["admin"]) }
});

// 或完全移除工具
upgradeAuthTool.remove();

六、常见问题

问：我该使用 stdio 还是 Streamable HTTP？

答：

• stdio：适合本地工具和桌面应用集成（如 Claude Desktop），它是默认选项，无需网络配置。
• Streamable HTTP：适合远程服务器部署、多客户端共享和云环境。它支持有状态会话管理和无状态两种模式。

问：旧的 SSE 传输还能用吗？

答：SSE 传输已被官方弃用，推荐迁移至 Streamable HTTP。但 SDK 提供了向后兼容支持，允许新旧客户端和服务器在过渡期共存。

问：如何调试我的 MCP 服务器？

答：使用 MCP Inspector 可以可视化地查看你的服务器提供的工具和资源，并手动调用它们进行测试。

问：可以在已有 Express 应用中集成 MCP 吗？

答：可以。SDK 提供了 Streamable HTTP 传输层，你可以直接在现有 Express 应用中添加 MCP 端点，无需重建整个应用。

问：Zod 是必须使用的吗？

答：在高级 API（McpServer）中，Zod 用于定义工具参数的验证模式。这是一个推荐的做法，因为它能自动生成参数说明并验证输入。如果你使用低级 API（Server 类），可以手动处理参数验证。

七、总结

MCP TypeScript SDK 是 MCP 生态的基石。它不仅仅是一个工具包，更是官方对“如何正确实现 MCP 协议”这一问题的标准答案。通过极简的 API、灵活的传输支持和完整的高级特性，它为开发者提供了构建 MCP 服务器和客户端所需的一切。

对于任何想要构建自定义 MCP 工具的开发者来说，学习并掌握这个 SDK，是进入 AI 代理开发世界的必经之路。花一个下午的时间跟着官方示例走一遍，你就能从“理解 MCP”进阶到“实现 MCP”。