简介

MCP TypeScript SDK（Model Context Protocol TypeScript SDK）是 Model Context Protocol 的 TypeScript/Node.js 实现，为开发者提供了构建 MCP 服务器和客户端的能力。该 SDK 采用 Monorepo 结构，包含核心包、客户端包、服务器包以及多种 Web 框架适配器。

资料来源：README.md

架构设计

两层导出结构

SDK 采用精心设计的两层导出结构，以清晰分离内部实现和公共 API：

graph TD
    A["@modelcontextprotocol/core<br/>packages/core/src/index.ts"] --> B["内部 barrel<br/>导出全部内容"]
    A --> C["包括 Zod schemas、Protocol 类、stdio 工具"]
    B --> D["@modelcontextprotocol/core/public<br/>packages/core/src/exports/public/index.ts"]
    D --> E["仅导出：TypeScript 类型、错误类、常量、守卫函数"]
    D --> F["@modelcontextprotocol/client"]
    D --> G["@modelcontextprotocol/server"]
    F --> H["最终公共表面"]
    G --> H

资料来源：CLAUDE.md

导出层级说明

导出规范要求：

• 在包的 index.ts 文件和 core/public 中使用显式命名导出（export * 禁止）
• 向包的 index.ts 添加符号会使其成为公共 API，需谨慎操作
• 内部辅助函数应保留在 core 内部 barrel 中，不添加到 core/public

资料来源：CLAUDE.md:1-15

核心模块

包结构总览

graph LR
    subgraph "核心包"
        A["@modelcontextprotocol/core"]
    end
    subgraph "中间件适配器"
        B["@modelcontextprotocol/express"]
        C["@modelcontextprotocol/hono"]
        D["@modelcontextprotocol/fastify"]
        E["@modelcontextprotocol/node"]
    end
    subgraph "应用包"
        F["@modelcontextprotocol/client"]
        G["@modelcontextprotocol/server"]
    end
    A --> F
    A --> G
    B --> G
    C --> G
    D --> G

传输系统

传输层（packages/core/src/shared/transport.ts）提供通信层支持：

• Streamable HTTP：现代推荐的传输方式，支持有状态和无状态模式
• SSE（Server-Sent Events）：传统轮询方式，用于向后兼容

资料来源：CLAUDE.md:24-26

实验性功能

实验性功能通过 @modelcontextprotocol/sdk/experimental 模块导出：

import { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';

资料来源：packages/server/src/experimental/index.ts:1-10

服务器开发

服务器示例索引

资料来源：examples/server/README.md:20-30

运行服务器示例

从仓库根目录运行：

pnpm install
pnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts

或在示例包内运行：

cd examples/server
pnpm tsx src/simpleStreamableHttp.ts

资料来源：examples/server/README.md:10-15

Web 框架适配器

SDK 提供多种 Web 框架的中间件适配器：

所有中间件适配器均基于统一的适配器模式构建，遵循 Express 和 Hono 适配器的设计规范。

资料来源：packages/middleware/fastify/CHANGELOG.md:18-22

客户端开发

客户端示例索引

资料来源：examples/client/README.md:18-25

运行客户端示例

从仓库根目录运行：

pnpm install
pnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts

大多数客户端示例需要先启动服务器（参考服务器示例）。

资料来源：examples/client/README.md:8-12

客户端核心功能

#### OAuth 发现功能

SDK 2.0.0-alpha.1 引入了 discoverOAuthServerInfo() 函数和统一的发现状态缓存机制。

资料来源：packages/client/CHANGELOG.md:14-17

#### WebSocket 变更

重要变更：从 2.0.0-alpha.1 开始，WebSocketClientTransport 已被移除。WebSocket 不是规范定义的传输方式，请使用 stdio 或 Streamable HTTP。Transport 接口仍然导出以支持自定义实现。

资料来源：packages/client/CHANGELOG.md:10-14

核心包功能

资源模式增强

SDK 在 ResourceSchema 中添加了缺失的 size 字段，以匹配 MCP 规范。

资料来源：packages/core/CHANGELOG.md:2-4

安全修复

#### ReDoS 漏洞修复

修复了 UriTemplate 正则表达式模式中的 ReDoS 漏洞（CVE-2026-0621）。

资料来源：packages/core/CHANGELOG.md:6-8

能力断言规范化

SDK 将剩余的能力断言转换为 SdkError(SdkErrorCode.CapabilityNotSupported, ...) 格式，包括：

• Client.assertCapability()
• 实验性任务辅助函数（experimental/tasks/helpers.ts）
• 采样/elicitation 能力检查（experimental/tasks/server.ts）

资料来源：packages/core/CHANGELOG.md:9-15

版本历史

最新版本动态

所有中间件包的 2.0.0-alpha.2 版本都依赖于 @modelcontextprotocol/[email protected]。

资料来源：packages/client/CHANGELOG.md:1-10，packages/middleware/express/CHANGELOG.md，packages/middleware/hono/CHANGELOG.md

开发工具配置

TypeScript 配置

SDK 使用统一的 TypeScript 配置：

{
    "name": "@modelcontextprotocol/tsconfig",
    "private": true,
    "main": "tsconfig.json",
    "type": "module",
    "dependencies": {
        "typescript": "catalog:devTools"
    }
}

资料来源：common/tsconfig/package.json:1-13

快速开始

安装依赖

pnpm install

构建项目

pnpm build

开发工作流

graph LR
    A["安装 pnpm install"] --> B["运行示例"]
    B --> C["服务器示例<br/>pnpm --filter @modelcontextprotocol/examples-server"]
    B --> D["客户端示例<br/>pnpm --filter @modelcontextprotocol/examples-client"]

相关文档

• 服务器开发指南
• 客户端开发指南
• 官方 MCP 规范

概述

MCP TypeScript SDK 是一个用于实现 Model Context Protocol (MCP) 的 TypeScript 工具包，采用 monorepo 结构组织。该 SDK 提供客户端和服务端的完整实现，支持多种传输层协议，包括 Streamable HTTP 和标准输入输出 (stdio)。SDK 的设计目标是分离内部实现与公共 API，确保只有经过审核的类型、错误类和守卫函数对外暴露，同时保持对浏览器和 Cloudflare Workers 等不同运行环境的兼容性。

核心架构分层

SDK 采用三层架构设计，从底层到顶层依次为：类型层 (Types Layer)、协议层 (Protocol Layer) 和高级 API 层 (High-Level APIs)。这种分层设计确保了关注点分离，便于维护和扩展。

类型层 (Types Layer)

类型层位于 packages/core/src/types/types.ts，定义了从 MCP 规范生成的所有协议类型。所有 JSON-RPC 消息类型、Zod 模式定义和协议常量都在这一层声明。类型层使用 Zod v4 进行运行时验证，确保数据的完整性和类型安全。资料来源：CLAUDE.md

graph TD
    A[MCP 规范] --> B[Types Layer]
    B --> C[JSON-RPC 消息类型]
    B --> D[Zod Schema]
    B --> E[协议常量]

协议层 (Protocol Layer)

协议层位于 packages/core/src/shared/protocol.ts，包含抽象的 Protocol 类。该类负责处理 JSON-RPC 消息路由、请求/响应关联、能力协商和传输层管理。Client 和 Server 都继承自这个基类，共享核心协议逻辑。资料来源：CLAUDE.md

高级 API 层 (High-Level APIs)

高级 API 层提供面向终端用户的接口：

包结构概览

SDK 采用 monorepo 结构，使用 pnpm workspaces 管理多个包。以下是主要包的层次结构：资料来源：package.json

graph TD
    subgraph 核心层
        A[@modelcontextprotocol/core]
        B[@modelcontextprotocol/core/public]
    end
    
    subgraph 公共API层
        C[@modelcontextprotocol/client]
        D[@modelcontextprotocol/server]
    end
    
    subgraph 中间件层
        E[@modelcontextprotocol/hono]
        F[@modelcontextprotocol/fastify]
        G[@modelcontextprotocol/node]
    end
    
    A --> B
    B --> C
    B --> D
    D --> E
    D --> F
    C --> G
    
    style A fill:#f9f,opacity:0.3
    style B fill:#ff9,opacity:0.3
    style C fill:#9f9,opacity:0.3
    style D fill:#9f9,opacity:0.3

核心包详解

@modelcontextprotocol/core

这是 SDK 的内部核心包，所有内部代码都在此处实现。该包的主要入口文件为 packages/core/src/index.ts，导出内容包括 Zod 模式、Protocol 类和 stdio 工具函数。由于该包标记为 private: true，仅供 monorepo 内部的其他包消费，不对外部直接发布。

核心导出结构：

• 主入口 (packages/core/src/index.ts) — 内部桶，导出所有内部实现
• 公共入口 (packages/core/src/exports/public/index.ts) — 精选的公共 API，仅包含 TypeScript 类型、错误类、常量和守卫函数

@modelcontextprotocol/client

客户端包提供 MCP 协议的客户端实现，支持连接 MCP 服务器、调用工具、访问资源和获取提示。该包的入口文件导出命名符号，遵循显式导出而非 export * 的原则。

支持的传输方式：

资料来源：packages/client/package.json

@modelcontextprotocol/server

服务端包提供 MCP 协议的服务端实现，允许开发者注册工具、资源、提示，并处理来自客户端的请求。该包是许多框架适配器的基础依赖。

主要功能：

• 工具注册与处理
• 资源管理
• 提示注册
• 采样请求处理
• 任务管理 (experimental)

服务端包提供多个子路径导出以支持不同的运行环境：

资料来源：packages/server/package.json

中间件与适配器层

中间件层提供将 MCP 服务端集成到不同 Web 框架的适配器，简化常见服务器框架的使用。

@modelcontextprotocol/hono

Hono 框架适配器，用于在 Hono 应用中运行 MCP 服务端。Hono 是一个轻量、跨平台的 Web 框架，支持 Cloudflare Workers、Deno、Bun 等运行环境。

// 使用示例结构
import { createMcpServer } from '@modelcontextprotocol/server';
import { Hono } from 'hono';
import { mcpHonoAdapter } from '@modelcontextprotocol/hono';

const app = new Hono();
const mcpServer = createMcpServer({ /* 配置 */ });
app.use('/mcp', mcpHonoAdapter(mcpServer));

@modelcontextprotocol/fastify

Fastify 框架适配器，提供与 Fastify 的集成。Fastify 以其高性能和低开销著称，适合需要高吞吐量的场景。资料来源：packages/middleware/fastify/CHANGELOG.md

@modelcontextprotocol/node

Node.js 原生适配器，提供基于 @hono/node-server 的服务端实现。这是运行在标准 Node.js 环境中时推荐使用的中间件。

该包已添加缺失的 hono peer 依赖，确保运行时依赖完整。资料来源：packages/middleware/node/CHANGELOG.md

传输系统

传输层位于 packages/core/src/shared/transport.ts，负责客户端与服务端之间的通信。SDK 支持多种传输机制，每种都有特定的适用场景。

Streamable HTTP

Streamable HTTP 是 V2 版本推荐的传输方式，支持状态化会话管理。它允许服务器跟踪会话状态，适合需要维护上下文的复杂交互场景。

graph LR
    A[Client] -->|HTTP POST /mcp| B[Streamable HTTP Server]
    B -->|Streaming Response| A
    A <-->|Session Token| B

stdio 传输

stdio 传输通过标准输入输出进行通信，适用于本地进程调用和命令行工具。这是 MCP 最初设计的传输方式，配置简单，无需网络。

传输导出结构

为确保运行时环境兼容性，stdio 相关的导出位于命名子路径：

// 运行时中性导入（浏览器、Cloudflare Workers）
import { Client } from '@modelcontextprotocol/client';

// Node.js 专用 stdio 导入
import { stdioClientTransport } from '@modelcontextprotocol/client/stdio';

资料来源：packages/client/package.json

导出结构与命名规范

SDK 采用两层导出结构来区分内部实现和公共 API，这是确保包边界清晰的关键设计。

内部导出 (Internal Barrel)

@modelcontextprotocol/core 的主入口导出所有内部实现，包括：

• Zod 模式 (Schema)
• Protocol 类
• stdio 工具函数
• 内部帮助函数

这些导出仅供 monorepo 内部包使用，不应被外部代码直接依赖。

公共导出 (Public API)

@modelcontextprotocol/core/public 提供精选的公共 API，仅包含：

包索引导出规则

在修改导出时需遵循以下规则：

1. 使用显式命名导出 — 包索引文件应使用 export { SpecificExport } 而非 export *
2. 公共 API 变更需谨慎 — 添加到包索引的符号即成为公共 API
3. 内部代码隔离 — 内部帮助函数应保留在 core 内部桶中
4. 运行时中性 — 包根入口必须保持运行时中性，确保浏览器和 Cloudflare Workers 可正常打包

实验性功能

SDK 将某些功能标记为实验性，通过 @modelcontextprotocol/sdk/experimental 导出。当前实验性功能包括任务存储 (TaskStore) 相关实现。

// 导入实验性功能
import { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';

实验性 API 可能随时变更，不提供稳定性保证。使用前请评估风险。

资料来源：packages/server/src/experimental/index.ts

构建与工具链

SDK 使用以下工具链进行开发和构建：

常用构建命令

# 安装依赖
pnpm install

# 类型检查
pnpm typecheck:all

# 构建所有包
pnpm build:all

# 生成文档
pnpm docs

# 运行测试
pnpm test

版本与兼容性

V2 版本移除了 WebSocket 传输，WebSocket 不是规范定义的传输方式。推荐使用 stdio 或 Streamable HTTP。如需自定义传输，可实现并使用 Transport 接口。资料来源：packages/client/CHANGELOG.md

概述

MCP TypeScript SDK 的核心架构建立在两层抽象之上：协议层（Protocol Layer） 和 类型层（Types Layer）。协议层负责 JSON-RPC 消息的路由、请求/响应关联、能力协商和传输管理；类型层则定义了所有 MCP 协议消息的 Zod v4 模式和数据结构。

这两个层次共同构成了 SDK 的基础设施，支撑着 Client、Server 和 McpServer 的高级 API 实现。

架构分层

graph TB
    subgraph "High-Level APIs"
        McpServer["McpServer<br/>packages/server/src/server/mcp.ts"]
        Server["Server<br/>packages/server/src/server/server.ts"]
        Client["Client<br/>packages/client/src/client/client.ts"]
    end
    
    subgraph "Protocol Layer"
        Protocol["Protocol<br/>packages/core/src/shared/protocol.ts"]
    end
    
    subgraph "Types Layer"
        Types["Types<br/>packages/core/src/types/types.ts"]
        SpecTypes["SpecTypes<br/>packages/core/src/types/specTypeSchema.ts"]
        Schemas["Zod Schemas"]
    end
    
    subgraph "Transport Layer"
        Transport["Transport Interface"]
    end
    
    McpServer --> Server
    Server --> Protocol
    Client --> Protocol
    Protocol --> Types
    Protocol --> SpecTypes
    Protocol --> Transport
    Types --> Schemas

资料来源：CLAUDE.md

协议层

Protocol 基类

Protocol 是 Client 和 Server 共同继承的抽象基类，处理所有底层协议逻辑：

JSON-RPC 消息类型

MCP 协议使用标准 JSON-RPC 2.0 消息格式：

sequenceDiagram
    participant C as Client
    participant P as Protocol
    participant T as Transport
    
    C->>P: 构造 Request
    P->>P: 生成 requestId
    P->>P: 存储 PromiseResolver
    P->>T: 发送 JSON-RPC Request
    T->>P: 接收 JSON-RPC Response
    P->>P: 根据 requestId 恢复 Promise
    P->>C: 返回 Response

消息处理器注册

Protocol 类提供方法注册各类消息的处理器：

// 资料来源：packages/core/src/shared/protocol.ts
requestHandlers: Map<string, RequestHandler>
notificationHandlers: Map<string, NotificationHandler>

类型层

类型组织结构

类型层位于 packages/core/src/types/，包含以下核心文件：

资源类型（Resources）

资源用于向客户端暴露可读取的数据：

// 资料来源：packages/core/src/types/types.ts
export type TextResourceContents = Infer<typeof TextResourceContentsSchema>;
export type BlobResourceContents = Infer<typeof BlobResourceContentsSchema>;
export type Resource = Infer<typeof ResourceSchema>;
export type ResourceTemplate = Infer<typeof ResourceTemplateSchema>;

提示类型（Prompts）

提示用于定义可复用的消息模板：

// 资料来源：packages/core/src/types/types.ts
export type PromptArgument = Infer<typeof PromptArgumentSchema>;
export type Prompt = Infer<typeof PromptSchema>;
export type ListPromptsResult = Infer<typeof ListPromptsResultSchema>;
export type GetPromptRequest = Infer<typeof GetPromptRequestSchema>;

工具类型（Tools）

工具是服务器暴露的可执行操作：

// 资料来源：packages/core/src/types/types.ts
export type CallToolResult = Infer<typeof CallToolResultSchema>;
export type Tool = Infer<typeof ToolSchema>;

任务类型（Tasks）

任务支持长时运行的异步操作：

// 资料来源：packages/server/src/server/mcp.ts
type TaskHandlerInternal = {
    createTask: (args: unknown, ctx: CreateTaskServerContext) => CreateTaskResult | Promise<CreateTaskResult>;
};

StandardSchemaV1 类型系统

概述

SDK 使用 StandardSchemaV1 作为输入输出的标准模式格式，这是一个供应商中立（vendor-neutral）的模式接口。

模式注册机制

specTypeSchema.ts 通过注册表模式将 MCP 规范中的所有类型映射到 StandardSchemaV1：

// 资料来源：packages/core/src/types/specTypeSchema.ts
const _specTypeSchemas: Record<string, StandardSchemaV1> = {};
const _isSpecType: Record<string, (value: unknown) => boolean> = {};

function register(key: string, schema: z.ZodType): void {
    const name = key.slice(0, -'Schema'.length);
    _specTypeSchemas[name] = schema;
    _isSpecType[name] = (v: unknown) => schema.safeParse(v).success;
}

SpecTypes 类型映射

// 资料来源：packages/core/src/types/specTypeSchema.ts
export type SpecTypes = {
    [K in SchemaKey as StripSchemaSuffix<K>]: SchemaFor<K> extends z.ZodType ? z.output<SchemaFor<K>> : never;
};

从 JSON Schema 转换

SDK 提供 fromJsonSchema 函数将 JSON Schema 转换为 StandardSchemaV1：

// 资料来源：packages/core/src/validators/fromJsonSchema.ts
export function fromJsonSchema<T = unknown>(
    schema: JsonSchemaType, 
    validator: jsonSchemaValidator
): StandardSchemaWithJSON<T, T> {
    return {
        '~standard': {
            version: 1,
            vendor: 'mcp',
            jsonSchema: {
                input: () => schema as Record<string, unknown>,
                output: () => schema as Record<string, unknown>
            },
            validate: (data: unknown): StandardSchemaV1.Result<T> => {
                const result = check(data);
                return result.valid 
                    ? { value: result.data } 
                    : { issues: [{ message: result.errorMessage }] };
            }
        }
    };
}

Completable 类型

Completable 提供参数自动完成功能：

// 资料来源：packages/server/src/server/completable.ts
export const COMPLETABLE_SYMBOL: unique symbol = Symbol.for('mcp.completable');

export type CompleteCallback<T extends StandardSchemaV1 = StandardSchemaV1> = (
    value: StandardSchemaV1.InferInput<T>,
    context?: {
        arguments?: Record<string, string>;
    }
) => StandardSchemaV1.InferInput<T>[] | Promise<StandardSchemaV1.InferInput<T>[]>;

export type CompletableSchema<T extends StandardSchemaV1> = T & {
    [COMPLETABLE_SYMBOL]: CompletableMeta<T>;
};

使用示例：

// 资料来源：packages/server/src/server/completable.ts
server.registerPrompt(
    'review-code',
    {
        title: 'Code Review',
        argsSchema: z.object({
            language: completable(
                z.string().describe('Programming language'), 
                value => ['typescript', 'javascript', 'python', 'rust', 'go']
                    .filter(lang => lang.startsWith(value))
            )
        })
    },
    ({ language }) => ({
        messages: [{ role: 'user', content: { type: 'text', text: `Review this ${language} code.` } }]
    })
);

Zod Schema 结构

Schema 层级

graph TD
    ZodType["z.ZodType<br/>基础类型"]
    ZodObject["z.ZodObject<br/>对象类型"]
    ZodArray["z.ZodArray<br/>数组类型"]
    ZodString["z.ZodString<br/>字符串"]
    ZodNumber["z.ZodNumber<br/>数字"]
    ZodBoolean["z.ZodBoolean<br/>布尔值"]
    
    ZodType --> ZodObject
    ZodType --> ZodArray
    ZodType --> ZodString
    ZodType --> ZodNumber
    ZodType --> ZodBoolean

模式验证流程

sequenceDiagram
    participant Input as 用户输入
    participant Schema as Zod Schema
    participant Validate as validateStandardSchema
    participant Output as 类型安全输出
    
    Input->>Schema: 原始数据
    Schema->>Validate: 调用 safeParse
    Validate->>Output: 验证成功，返回类型化数据
    Note over Validate,Output: parseResult.success === true

错误类型

SDK 定义了结构化的错误类型：

枚举类型

enums.ts 定义了协议中使用的枚举值：

类型推断机制

SDK 使用 TypeScript 的类型推断来提供类型安全：

// 资料来源：packages/core/src/types/types.ts
// 使用 Infer 类型工具从 Zod schema 推断 TypeScript 类型
export type Resource = Infer<typeof ResourceSchema>;
export type Prompt = Infer<typeof PromptSchema>;
export type CallToolResult = Infer<typeof CallToolResultSchema>;

Infer 类型定义

// Infer 类型工具允许从 Zod schema 反向推断 TypeScript 类型
type Infer<T> = T extends z.ZodType<infer Input, unknown, infer Output> 
    ? Output 
    : never;

模式键名约定

MCP 规范中的模式使用统一后缀约定：

导出结构

SDK 采用两层导出结构：

graph LR
    subgraph "@modelcontextprotocol/core"
        Core["内部 barrel<br/>导出所有内容"]
    end
    
    subgraph "@modelcontextprotocol/client"
        Client["公共 API<br/>客户端专用"]
    end
    
    subgraph "@modelcontextprotocol/server"
        Server["公共 API<br/>服务端专用"]
    end
    
    Core --> Client
    Core --> Server

• @modelcontextprotocol/core — 内部 barrel，导出所有内容（包含 Zod schemas、Protocol 类等），仅供 monorepo 内部使用
• @modelcontextprotocol/client — 客户端公共 API
• @modelcontextprotocol/server — 服务端公共 API

资料来源：CLAUDE.md

最佳实践

类型安全保证

1. 使用 Zod 进行运行时验证 — 所有输入都经过 Zod schema 验证
2. TypeScript 类型推断 — 减少手动类型标注，降低错误风险
3. StandardSchemaV1 抽象 — 支持供应商中立的模式定义

模式设计

概述

MCP TypeScript SDK 提供了一套完整的 Schema 验证体系，支持多种 Schema 定义方式。该系统允许开发者使用任意实现了 Standard Schema 规范 的验证库来定义工具（Tool）、提示（Prompt）和资源的输入输出结构。

SDK 的验证架构基于以下核心原则：

• 标准化接口：使用 StandardSchemaV1 接口统一不同验证库的行为
• 多库支持：原生支持 Zod v4、Valibot、ArkType 等主流验证库
• JSON Schema 桥接：通过 fromJsonSchema 适配器支持纯 JSON Schema
• 向后兼容：保留 Zod v3 的部分兼容层

资料来源：packages/core/src/util/standardSchema.ts:1-50

架构图

graph TD
    subgraph "用户层"
        ZOD_V4[Zod v4 Schema]
        VALIBOT[Valibot Schema]
        ARKTYPE[ArkType Schema]
        JSON_SCHEMA[Raw JSON Schema]
        RAW_SHAPE[Zod Raw Shape]
    end

    subgraph "标准化层"
        STD_SCHEMA[StandardSchemaV1]
        STD_JSON[StandardJSONSchemaV1]
    end

    subgraph "适配器层"
        ZOD_COMPAT[zodCompat.ts]
        FROM_JSON[fromJsonSchema.ts]
        NORMALIZE[normalizeRawShapeSchema]
    end

    subgraph "验证器层"
        ZOD_VALIDATOR[Zod 内置验证]
        AJV[AjvJsonSchemaValidator]
        CUSTOM[自定义验证器]
    end

    ZOD_V4 -->|原生实现| STD_SCHEMA
    VALIBOT -->|原生实现| STD_SCHEMA
    ARKTYPE -->|原生实现| STD_SCHEMA
    JSON_SCHEMA -->|fromJsonSchema| FROM_JSON
    RAW_SHAPE -->|auto-wrap| ZOD_COMPAT

    FROM_JSON --> AJV
    ZOD_COMPAT --> ZOD_VALIDATOR

    STD_SCHEMA -->|registerTool| MCP_SERVER
    STD_SCHEMA -->|registerPrompt| MCP_SERVER

    classDef sdk fill:#e1f5fe
    classDef adapter fill:#fff3e0
    classDef validator fill:#e8f5e9

Standard Schema 支持

标准接口定义

StandardSchemaV1 是 MCP SDK 验证系统的核心接口，定义了所有 Schema 必须实现的标准化方法：

interface StandardSchemaV1<TInput = unknown, TOutput = TInput> {
  '~standard': {
    version: 1;
    vendor: string;
    jsonSchema?: StandardJSONSchemaV1;
    validate?: (value: unknown) => StandardSchemaV1.Result<TOutput>;
  };
}

资料来源：packages/core/src/util/standardSchema.ts:1-30

标准 Schema 工具函数

SDK 提供了两个核心工具函数用于处理 Standard Schema：

standardSchemaToJsonSchema 函数支持从多种 Schema 库提取 JSON Schema 表示：

export function standardSchemaToJsonSchema(
  schema: StandardJSONSchemaV1, 
  io: 'input' | 'output' = 'input'
): Record<string, unknown> {
  const std = schema['~standard'];
  let result: Record<string, unknown>;
  
  if (std.jsonSchema) {
    result = std.jsonSchema[io]({ target: 'draft-2020-12' });
  } else if (std.vendor === 'zod') {
    // Zod v4 实现 StandardSchemaV1 但没有 ~standard.jsonSchema
    // 回退到 z.toJSONSchema()
  }
  return result;
}

资料来源：packages/core/src/util/standardSchema.ts:60-90

Zod 兼容性

Zod 版本检测

SDK 通过 zodCompat.ts 中的工具函数检测 Zod 版本差异：

function isZodV4Schema(v: unknown): v is z.ZodType {
  // `_zod` 是 v4 内部命名空间属性
  return typeof v === 'object' && v !== null && '_zod' in v;
}

function looksLikeZodV3(v: unknown): boolean {
  // v3 schemas 有 `_def.typeName` (例如 'ZodString') 但没有 `_zod`
  return (
    typeof v === 'object' &&
    v !== null &&
    !('_zod' in v) &&
    '_def' in v &&
    typeof (v as { _def?: { typeName?: unknown } })._def?.typeName === 'string'
  );
}

资料来源：packages/core/src/util/zodCompat.ts:10-30

版本兼容策略

注意：SDK 已将 zod 从 peerDependencies 移除，保留为直接依赖。用户无需单独安装 Zod。

资料来源：packages/client/CHANGELOG.md, packages/core/src/util/standardSchema.ts:30-40

JSON Schema 支持

fromJsonSchema 适配器

对于使用纯 JSON Schema 的场景（如 TypeBox 输出），SDK 提供了 fromJsonSchema 适配器：

import { fromJsonSchema, AjvJsonSchemaValidator } from '@modelcontextprotocol/core';

const schema = fromJsonSchema(
  { 
    type: 'object', 
    properties: { 
      name: { type: 'string' } 
    }, 
    required: ['name'] 
  },
  new AjvJsonSchemaValidator()
);

server.registerTool(
  'greet',
  { inputSchema: schema },
  async ({ name }) => ({ content: [{ type: 'text', text: `Hello, ${name}!` }] })
);

资料来源：packages/core/src/validators/fromJsonSchema.ts:20-40

AjvJsonSchemaValidator

AjvJsonSchemaValidator 是基于 AJV 的 JSON Schema 验证器实现：

export class AjvJsonSchemaValidator implements jsonSchemaValidator {
  private _ajv: Ajv;
  
  getValidator<T>(schema: JsonSchemaType): ValidatorFn<T> {
    const validate = this._ajv.compile(schema);
    return (data: unknown): ValidationResult<T> => {
      const valid = validate(data);
      return valid 
        ? { valid: true, data: data as T }
        : { valid: false, errorMessage: this._ajv.errorsText() };
    };
  }
}

资料来源：packages/core/src/validators/ajvProvider.ts

工具与提示注册

registerTool 的 Schema 处理

McpServer.registerTool() 方法接受 Standard Schema 作为 inputSchema 和 outputSchema：

// 使用 Zod v4
import { z } from 'zod';

server.registerTool(
  'calculate',
  {
    inputSchema: z.object({
      a: z.number(),
      b: z.number()
    }),
    outputSchema: z.object({
      result: z.number()
    })
  },
  async ({ a, b }) => ({
    content: [{ type: 'text', text: `${a + b}` }]
  })
);

// 使用 ArkType
import { type } from 'arktype';

server.registerTool(
  'greet',
  {
    inputSchema: type({ name: 'string' })
  },
  async ({ name }) => ({ content: [{ type: 'text', text: `Hello, ${name}!` }] })
);

资料来源：packages/server/src/server/mcp.ts:150-200

registerPrompt 的 Schema 处理

registerPrompt 支持类似的 Schema 定义方式：

server.registerPrompt(
  'review-code',
  {
    title: 'Code Review',
    description: 'Review code for best practices',
    argsSchema: z.object({
      code: z.string(),
      language: z.enum(['typescript', 'javascript', 'python'])
    })
  },
  ({ code, language }) => ({
    messages: [
      {
        role: 'user' as const,
        content: {
          type: 'text' as const,
          text: `Please review this ${language} code:\n\n${code}`
        }
      }
    ]
  })
);

资料来源：packages/server/src/server/mcp.ts:100-150

Raw Shape 简化语法

自动包装机制

为简化 Zod 使用，SDK 支持 "raw shape" 语法——直接传递字段定义对象而无需显式包装：

// 标准方式
server.registerTool('tool1', {
  inputSchema: z.object({ name: z.string() })
}, handler);

// Raw Shape 方式 (自动包装)
server.registerTool('tool2', {
  inputSchema: { name: z.string() }  // 自动变成 z.object({...})
}, handler);

内部通过 normalizeRawShapeSchema() 函数实现自动包装：

function normalizeRawShapeSchema(schema: unknown): StandardSchemaWithJSON | undefined {
  if (schema === undefined || schema === null) return undefined;
  if (isStandardSchema(schema)) return schema;
  if (isZodV4Schema(schema)) return schema as StandardSchemaWithJSON;
  if (looksLikeZodV3(schema)) {
    // Zod v3: 包装成 z.object()
    return z.object(schema as ZodRawShape);
  }
  // ... 其他处理
}

资料来源：packages/core/src/util/zodCompat.ts:40-80

可补全 Schema

completable 函数

SDK 提供了 completable() 包装器，为 Schema 字段添加自动补全功能：

import { completable } from '@modelcontextprotocol/server';

server.registerPrompt(
  'review-code',
  {
    argsSchema: z.object({
      language: completable(
        z.string().describe('Programming language'),
        (value) => ['typescript', 'javascript', 'python', 'rust', 'go']
          .filter(lang => lang.startsWith(value))
      )
    })
  },
  ({ language }) => ({
    messages: [{
      role: 'user',
      content: { type: 'text', text: `Review this ${language} code.` }
    }]
  })
);

CompletableSchema 在标准 Schema 基础上添加了补全元数据：

export type CompletableSchema<T extends StandardSchemaV1> = T & {
  [COMPLETABLE_SYMBOL]: CompletableMeta<T>;
};

资料来源：packages/server/src/server/completable.ts:20-50

内置 Schema 类型

协议类型定义

MCP SDK 使用 Zod v4 定义了所有协议消息类型：

type SpecTypeInputs = {
  [K in SchemaKey as StripSchemaSuffix<K>]: SchemaFor<K> extends z.ZodType 
    ? z.input<SchemaFor<K>> 
    : never;
};

type SpecTypes = {
  [K in SchemaKey as StripSchemaSuffix<K>]: SchemaFor<K> extends z.ZodType 
    ? z.output<SchemaFor<K>> 
    : never;
};

通过 register() 函数批量注册所有规范类型：

for (const key of SPEC_SCHEMA_KEYS) {
  register(key, schemas[key]);
}

资料来源：packages/core/src/types/specTypeSchema.ts:20-50

常用类型列表

完整类型列表参见 packages/core/src/types/types.ts。

验证流程

数据验证时序

sequenceDiagram
    participant Client
    participant Server
    participant Validator
    participant Schema

    Client->>Server: registerTool(name, inputSchema, handler)
    Server->>Schema: 标准化 Schema
    Schema-->>Server: StandardSchemaV1

    Client->>Server: tools/call 请求
    Server->>Validator: validate(inputData)
    Validator->>Schema: 执行验证
    Schema-->>Validator: ValidationResult

    alt 验证通过
        Validator-->>Server: { valid: true, data }
        Server->>Server: 调用 handler
        Server-->>Client: 工具结果
    else 验证失败
        Validator-->>Server: { valid: false, issues }
        Server-->>Client: InvalidParams 错误
    end

最佳实践

Schema 选择建议

迁移指南

从 Zod v3 迁移：

// Zod v3
import { z } from 'zod';
const schema = z.object({ name: z.string() });

// Zod v4 (推荐)
import { z } from 'zod';
const schema = z.object({ name: z.string() }); // 兼容

// 或使用其他库
import { type } from 'arktype';
const schema = type({ name: 'string' });

处理 JSON Schema：

import { fromJsonSchema, AjvJsonSchemaValidator } from '@modelcontextprotocol/core';

// TypeBox 输出
const typeBoxSchema = Type.Strict(Type.Object({ name: Type.String() }));

// 转换为 Standard Schema
const standardSchema = fromJsonSchema(
  TypeBox.toJsonSchema(typeBoxSchema),
  new AjvJsonSchemaValidator()
);

相关配置

AjvJsonSchemaValidator 配置选项

import Ajv from 'ajv';

const ajv = new Ajv({
  allErrors: true,      // 返回所有错误而非首次错误
  strict: false,        // 禁用严格模式
  coerceTypes: false   // 禁用类型强制
});

const validator = new AjvJsonSchemaValidator(ajv);

总结

MCP TypeScript SDK 的数据验证系统提供了灵活且强大的 Schema 支持：

• 通过 Standard Schema 规范实现多库统一接口
• 原生支持 Zod v4、Valibot、ArkType 等主流验证库
• JSON Schema 通过 AJV 验证器完整支持
• Raw Shape 语法简化常见使用场景
• completable() 提供字段自动补全能力

这套设计使开发者能够使用自己熟悉的验证库，同时保持与 MCP 协议的完全兼容。

架构概览

传输层采用接口抽象设计，通过 Transport 接口定义统一的通信契约。不同的传输实现（如 HTTP、stdio）都遵循这一接口规范，使得上层业务逻辑与底层传输方式解耦。

graph TB
    subgraph "客户端传输层"
        C_STDIO[ClientStdioTransport]
        C_HTTP[ClientStreamableHttpTransport]
        C_SSE[ClientSseTransport]
    end
    
    subgraph "服务端传输层"
        S_STDIO[ServerStdioTransport]
        S_HTTP[ServerStreamableHttpTransport<br/>WebStandardStreamableHTTPServerTransport]
        S_NODE_HTTP[NodeStreamableHTTPServerTransport]
    end
    
    subgraph "核心传输接口"
        Transport[Transport Interface]
    end
    
    C_STDIO --> Transport
    C_HTTP --> Transport
    C_SSE --> Transport
    Transport --> S_STDIO
    Transport --> S_HTTP
    Transport --> S_NODE_HTTP

核心接口定义

传输层的核心是 Transport 接口，它定义了所有传输实现必须实现的方法和属性。该接口位于核心包中，被客户端和服务端共同依赖。

Transport 接口契约

Streamable HTTP 传输

Streamable HTTP 是 MCP SDK 推荐的主要传输协议，适用于远程服务器通信。该协议支持服务端发送（SSE）进行流式消息推送，同时兼容传统的请求-响应模式。

服务端实现

#### WebStandardStreamableHTTPServerTransport

WebStandardStreamableHTTPServerTransport 是核心的 Web 标准 HTTP 服务器传输实现，支持两种运行模式：

有状态模式（Stateful）：启用会话追踪，适用于需要维护状态的复杂应用场景。

const transport = new WebStandardStreamableHTTPServerTransport({
    sessionIdGenerator: () => crypto.randomUUID()
});

await server.connect(transport);

无状态模式（Stateless）：不维护会话状态，适合简单的 API 风格服务器。

const transport = new WebStandardStreamableHTTPServerTransport({
    sessionIdGenerator: undefined
});

资料来源：packages/server/src/server/streamableHttp.ts:1-50

#### NodeStreamableHTTPServerTransport

NodeStreamableHTTPServerTransport 是针对 Node.js 环境优化的传输实现，内部封装了 WebStandardStreamableHTTPServerTransport，并使用 getRequestListener 将 Node.js HTTP 请求转换为 Web 标准请求。

const transport = new NodeStreamableHTTPServerTransport(options);

app.all('/mcp', async c => {
    return transport.handleRequest(c.req.raw);
});

该传输使用 WeakMap 存储每个请求的上下文信息，包括认证信息和解析后的请求体：

private _requestContext: WeakMap<Request, { authInfo?: AuthInfo; parsedBody?: unknown }> = new WeakMap();

资料来源：packages/middleware/node/src/streamableHttp.ts:1-80

客户端实现

ClientStreamableHttpTransport 实现了客户端侧的 Streamable HTTP 通信，支持与服务器的 SSE 消息流交互。

sequenceDiagram
    participant Client
    participant HttpTransport as ClientStreamableHttpTransport
    participant Server as Streamable HTTP Server
    
    Client->>HttpTransport: 创建传输实例
    Client->>HttpTransport: 调用 start()
    HttpTransport->>Server: 初始化请求
    Server-->>HttpTransport: 返回 SSE 流
    loop 消息循环
        Server->>HttpTransport: SSE 事件 (message)
        HttpTransport->>Client: 触发 onmessage
        Client->>HttpTransport: 调用 send()
        HttpTransport->>Server: POST 请求发送消息
    end

核心配置选项

Streamable HTTP 传输支持多种配置选项：

Stdio 传输

Stdio（标准输入/输出）传输适用于本地进程集成场景，常见于本地 MCP 服务器或 CLI 工具集成。

graph LR
    subgraph "父进程"
        ParentStdin[stdin]
        ParentStdout[stdout]
        ParentStderr[stderr]
    end
    
    subgraph "子进程 MCP Server"
        ServerStdin[stdin]
        ServerStdout[stdout]
    end
    
    ParentStdin --> ServerStdin
    ServerStdout --> ParentStdout

服务端 Stdio 传输

服务端 StdioServerTransport 监听标准输入，将接收到的数据解析为 JSON-RPC 消息，并通过标准输出发送响应。

import { StdioServerTransport } from '@modelcontextprotocol/server';

const transport = new StdioServerTransport();
await server.connect(transport);

客户端 Stdio 传输

客户端 StdioClientTransport 通过子进程方式启动 MCP 服务器，通过 stdin/stdout 与服务器进程通信。

import { StdioClientTransport } from '@modelcontextprotocol/client';

const transport = new StdioClientTransport({
    command: 'npx',
    args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/dir']
});

await client.connect(transport);

SSE 传输（传统兼容）

SSE（Server-Sent Events）传输是向后兼容的遗留实现，用于支持旧版 MCP 服务器的通信。

客户端 SSE 轮询

SSEClientTransport 实现了基于 SSE 的轮询机制，定期从服务器获取更新。

const transport = new SSEClientTransport(
    new URL('http://localhost:3000/mcp')
);

await client.connect(transport);

该传输包含以下核心功能：

中间件系统

客户端传输层支持中间件扩展，允许在请求/响应链中插入自定义逻辑。

日志中间件

loggingMiddleware 提供了请求/响应的详细日志记录功能：

import { loggingMiddleware } from '@modelcontextprotocol/client';

const transport = new ClientStreamableHttpTransport(url, {
    requestInit: {
        headers: {
            Authorization: `Bearer ${token}`
        }
    },
    middlewares: [
        loggingMiddleware({
            includeRequestHeaders: true,
            includeResponseHeaders: true,
            statusLevel: 300
        })
    ]
});

中间件接收和返回 fetch 风格的请求/响应，支持请求拦截和响应修改。

中间件管道

多个中间件可以组合成管道，按顺序执行：

const composedMiddleware = composeFetchMiddlewares([middleware1, middleware2, middleware3]);

每个中间件的签名如下：

type FetchMiddleware = (
    next: FetchFn
) => (input: RequestInfo, init?: RequestInit) => Promise<Response>;

认证集成

传输层内置了对 OAuth 2.0 和 Bearer Token 认证的支持。

AuthProvider 接口

interface AuthProvider {
    token(): Promise<string | undefined>;
    onUnauthorized?(ctx: AuthContext): Promise<void>;
}

Bearer Token 认证

简单的 Bearer Token 认证可以通过对象字面量实现：

const transport = new ClientStreamableHttpTransport(url, {
    authProvider: {
        token: async () => myApiKey
    }
});

OAuth 认证

OAuth 客户端提供者会被传输自动适配，无需额外配置：

import { OAuthClientProvider } from '@modelcontextprotocol/core';

const oauthProvider: OAuthClientProvider = {
    getAccessToken: () => Promise.resolve(token),
    setAccessToken: (token) => { /* ... */ }
};

const transport = new ClientStreamableHttpTransport(url, {
    authProvider: oauthProvider
});

传输层在每次请求前调用 authProvider.token() 获取令牌，在收到 401 响应时调用 onUnauthorized() 进行重试。

使用示例

运行服务端示例

# 从仓库根目录运行
pnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts

# 或从包目录运行
cd examples/server
pnpm tsx src/simpleStreamableHttp.ts

运行客户端示例

# 客户端需要先启动服务器
pnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts

兼容模式客户端

向后兼容的客户端会优先尝试 Streamable HTTP，失败时回退到 SSE：

// 使用 streamableHttpWithSseFallbackClient
pnpm --filter @modelcontextprotocol/examples-client exec tsx src/streamableHttpWithSseFallbackClient.ts

资料来源：examples/server/README.md:1-60

总结

MCP TypeScript SDK 的传输层设计遵循了以下原则：

1. 接口抽象：通过 Transport 接口统一不同传输实现的契约
2. 环境适配：提供 Web 标准、Node.js 和 stdio 三种环境的专用传输
3. 向后兼容：通过 SSE 传输支持遗留服务器
4. 扩展性：中间件系统允许灵活扩展传输功能
5. 安全性：内置 OAuth 和 Bearer Token 认证支持

开发者应根据具体场景选择合适的传输方式：远程服务推荐使用 Streamable HTTP，本地进程集成使用 stdio，遗留系统使用 SSE 传输。

概述

服务器开发指南旨在帮助开发者使用 MCP TypeScript SDK 构建 MCP 服务器。MCP（Model Context Protocol）服务器是向 LLM（大语言模型）提供工具、资源和提示的桥梁，使 AI 能够与外部系统交互并执行实际操作。

MCP SDK 提供两种服务器实现层级：

1. 基础 Server 类 (packages/server/src/server/server.ts) - 低层级协议封装，处理 JSON-RPC 消息路由
2. McpServer 类 (packages/server/src/server/mcp.ts) - 高层级 API，简化资源/工具/提示的注册流程

资料来源：examples/server/README.md:1-10

架构设计

服务器层级结构

graph TD
    A[McpServer 高层API] --> B[Server 基础协议类]
    B --> C[Protocol 协议处理核心]
    C --> D[Transport 传输层]
    
    A --> E[工具注册]
    A --> F[资源注册]
    A --> G[提示注册]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#f3e5f5

核心组件职责

资料来源：CLAUDE.md:25-35

快速开始

环境准备

# 安装依赖
pnpm install

# 运行服务器示例
pnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts

基础服务器创建

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

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

// 注册工具
server.tool(
  "calculate",
  "执行数学计算",
  { a: z.number(), b: z.number(), operation: z.enum(["add", "subtract"]) },
  async ({ a, b, operation }) => {
    const result = operation === "add" ? a + b : a - b;
    return { result };
  }
);

// 启动服务器
const transport = new StreamableHTTPTransport();
await server.connect(transport);
await transport.start();

资料来源：docs/server-quickstart.md:1-30

工具注册

工具注册 API

McpServer 提供 tool() 方法注册工具，支持两种调用形式：

// 标准 Schema 形式
server.tool<T extends StandardSchemaWithJSON>(
  name: string,
  description: string,
  argsSchema: T,
  cb: ToolCallback<T>
): RegisteredTool

// 废弃的 Zod Raw Shape 形式（自动包装为 z.object()）
server.tool<T extends ZodRawShape>(
  name: string,
  description: string,
  argsSchema: T,
  cb: LegacyToolCallback<T>
): RegisteredTool

工具注册参数

资料来源：packages/server/src/server/mcp.ts:150-180

工具动态管理

注册后的工具返回 RegisteredTool 对象，支持运行时动态更新：

const tool = server.tool("greet", "问候用户", { name: z.string() }, async ({ name }) => {
  return { message: `Hello, ${name}!` };
});

// 动态更新
tool.update({
  title: "新标题",
  description: "新描述",
  enabled: false,
  callback: async ({ name }) => ({ message: `Hi, ${name}!` })
});

// 启用/禁用
tool.enable();
tool.disable();

// 删除工具
tool.remove();

工具更新时，如果修改了 paramsSchema 或 callback，系统会自动重新生成执行器：

if (updates.paramsSchema !== undefined) {
  registeredTool.inputSchema = updates.paramsSchema;
  needsExecutorRegen = true;
}
if (updates.callback !== undefined) {
  registeredTool.handler = updates.callback;
  needsExecutorRegen = true;
}

资料来源：packages/server/src/server/mcp.ts:200-240

资源注册

资源类型

MCP 服务器可暴露两类资源：

1. 静态资源 (Resource) - 固定 URI 的资源
2. 资源模板 (ResourceTemplate) - 支持 URI 参数化的动态资源

注册静态资源

server.resource(
  "config",
  "app://config",
  (uri: URL) => {
    return {
      contents: [{
        uri: uri.toString(),
        mimeType: "application/json",
        text: JSON.stringify({ theme: "dark", language: "zh" })
      }]
    };
  }
);

注册资源模板

server.resourceTemplate(
  "user-profile",
  "users://{userId}/profile",
  ({ userId }: { userId: string }) => {
    return {
      contents: [{
        uri: `users://${userId}/profile`,
        mimeType: "application/json",
        text: fetchUserProfile(userId)
      }]
    };
  }
);

资源生命周期管理

资源更新后自动发送 resourceListChanged 通知：

update: updates => {
  if (updates.uri !== undefined && updates.uri !== uri) {
    delete this._registeredResources[uri];
    if (updates.uri) this._registeredResources[updates.uri] = registeredResource;
  }
  if (updates.name !== undefined) registeredResource.name = updates.name;
  if (updates.enabled !== undefined) registeredResource.enabled = updates.enabled;
  this.sendResourceListChanged();
}

资料来源：packages/server/src/server/mcp.ts:280-350

提示注册

提示注册 API

server.registerPrompt(
  "code-review",
  {
    title: "代码审查",
    description: "生成代码审查请求",
    argsSchema: z.object({
      code: z.string(),
      language: z.string().optional()
    })
  },
  async ({ code, language }) => ({
    messages: [{
      role: "user",
      content: {
        type: "text",
        text: `请审查以下${language || ""}代码：\n\n${code}`
      }
    }]
  })
);

提示参数

资料来源：packages/server/src/server/mcp.ts:180-210

服务器运行模式

Streamable HTTP 模式（有状态）

适用于需要会话跟踪、任务管理的复杂服务器：

import { StreamableHTTPTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const transport = new StreamableHTTPTransport({
  sessionIdGenerator: () => crypto.randomUUID(),
});

await server.connect(transport);

Streamable HTTP 模式（无状态）

适用于简单的 API 风格服务器，无会话跟踪：

import { StreamableHTTPTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const transport = new StreamableHTTPTransport();
await server.connect(transport);

JSON 响应模式

仅使用 JSON 响应，不支持 SSE：

import { JSONResponseStreamableHttpTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";

const transport = new JSONResponseStreamableHttpTransport();
await server.connect(transport);

资料来源：examples/server/README.md:25-45

错误处理

SDK 错误码

import { SdkError, SdkErrorCode } from "@modelcontextprotocol/sdk";

try {
  await server.requestHandler.handleRequest(request);
} catch (error) {
  if (error instanceof SdkError) {
    switch (error.code) {
      case SdkErrorCode.InvalidRequest:
        // 处理无效请求
        break;
      case SdkErrorCode.MethodNotFound:
        // 方法未找到
        break;
      case SdkErrorCode.CapabilityNotSupported:
        // 能力不支持
        break;
    }
  }
}

资料来源：packages/core/CHANGELOG.md:10-15

示例服务器索引

资料来源：examples/server/README.md:28-40

下一步

• 查看 客户端开发指南 了解如何连接到此服务器
• 阅读 协议规范文档 深入理解底层协议
• 参考 示例代码库 获取完整实现

概述

MCP TypeScript SDK 的客户端开发模块位于 packages/client 包中，提供了与 MCP 服务器通信的完整能力。该模块基于核心协议层构建，封装了 JSON-RPC 消息处理、请求/响应关联、能力协商和传输层管理等功能。客户端支持 Streamable HTTP 传输协议，这是 MCP V2 规范定义的主要通信方式。

核心架构

客户端层次结构

MCP SDK 采用三层架构设计，客户端位于最上层：

客户端与协议层关系

graph TD
    A[Client 实例] --> B[Protocol 基类]
    B --> C[Transport 传输层]
    C --> D[Streamable HTTP]
    
    A --> E[工具调用]
    A --> F[资源访问]
    A --> G[提示模板]
    A --> H[采样请求]
    A --> I[任务管理]
    
    E --> B
    F --> B
    G --> B
    H --> B
    I --> B

安装与配置

依赖安装

pnpm add @modelcontextprotocol/client

基本导入

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';

客户端初始化

创建客户端实例

客户端初始化需要提供服务器能力信息和连接配置：

const transport = new StreamableHTTPClientTransport({
  url: new URL('http://localhost:3000/mcp'),
  requestOptions: {
    headers: {
      Authorization: 'Bearer your-token-here'
    }
  }
});

const client = new Client(
  {
    name: 'example-client',
    version: '1.0.0'
  },
  {
    capabilities: {
      resources: {},
      tools: {},
      prompts: {},
      sampling: {}
    }
  }
);

连接到服务器

await client.connect(transport);

连接过程会触发服务器能力协商，确认双方支持的 MCP 功能范围。

核心功能

工具调用

工具是 MCP 服务器暴露的可执行函数，客户端可以调用这些工具获取计算结果或执行特定操作。

sequenceDiagram
    客户端->>服务器: 调用工具 (tools/call)
    服务器->>服务器: 执行工具逻辑
    服务器-->>客户端: 工具结果

#### 调用单个工具

const result = await client.callTool({
  name: 'calculate',
  arguments: { expression: '2 + 2' }
});

#### 并行调用多个工具

const results = await Promise.all([
  client.callTool({ name: 'tool-a', arguments: { id: 1 } }),
  client.callTool({ name: 'tool-b', arguments: { id: 2 } }),
  client.callTool({ name: 'tool-c', arguments: { id: 3 } })
]);

资源管理

资源是服务器提供的只读数据源，客户端可以列出、读取和订阅资源变更通知。

#### 列出可用资源

const resourceList = await client.listResources();
for (const resource of resourceList.resources) {
  console.log(`${resource.name}: ${resource.uri}`);
}

#### 读取资源内容

const resourceContent = await client.readResource({
  uri: 'file:///config/app.json'
});

#### 订阅资源变更

await client.subscribeResource({ uri: 'file:///config/app.json' });

// 设置资源更新处理器
client.setRequestHandler(ResourceUpdatedNotificationSchema, (notification) => {
  console.log('资源已更新:', notification.params.uri);
  return Promise.resolve();
});

提示模板

提示模板允许服务器定义可参数化的消息模板，客户端可以获取并使用这些模板。

#### 列出可用提示

const promptList = await client.listPrompts();

#### 获取提示内容

const prompt = await client.getPrompt({
  name: 'code-review',
  arguments: { code: 'const x = 1;' }
});

// prompt.messages 包含渲染后的消息数组
for (const message of prompt.messages) {
  console.log(`${message.role}: ${message.content}`);
}

采样请求

采样功能允许服务器向客户端请求采样数据，通常用于 AI 模型的调用。

const sample = await client.createMessage({
  messages: [{ role: 'user', content: { type: 'text', text: 'Hello' } }],
  systemPrompt: 'You are a helpful assistant.',
  maxTokens: 100
});

认证机制

AuthProvider 接口

SDK 提供了灵活的认证机制，通过 AuthProvider 接口实现可组合的认证功能：

interface AuthProvider {
  token(): Promise<string | undefined>;
  onUnauthorized?(ctx: AuthorizationCtx): Promise<void>;
}

简单Bearer Token认证

对于简单的 API 密钥或网关管理的令牌，可以使用对象字面量：

const client = new Client({ name: 'my-app', version: '1.0.0' }, { capabilities: {} });

await client.connect(transport, {
  authProvider: {
    token: async () => 'my-api-key'
  }
});

OAuth 认证

OAuth 认证由 OAuthClientProvider 提供，传输层会自动适配：

import { adaptOAuthProvider } from '@modelcontextprotocol/sdk/client/auth.js';

const oauthProvider = new MyOAuthProvider(config);
await client.connect(transport, {
  authProvider: adaptOAuthProvider(oauthProvider)
});

认证流程如下：

graph LR
    A[发起请求] --> B{获取Token}
    B --> C[发送带Token的请求]
    C --> D{响应状态}
    D -->|200| E[成功]
    D -->|401| F[onUnauthorized]
    F --> G[重试请求]
    G --> E

传输层配置

Streamable HTTP 传输

Streamable HTTP 是 V2 版本的主要传输协议，支持服务端推送和流式响应：

import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';

const transport = new StreamableHTTPClientTransport({
  url: new URL('http://localhost:3000/mcp'),
  requestOptions: {
    headers: {
      'Content-Type': 'application/json'
    }
  },
  // 启用SSE回落机制
  sseFallbackEnabled: true
});

SSE 回落机制

客户端支持自动回落机制，当 Streamable HTTP 返回 4xx 错误时，自动切换到传统 SSE 轮询模式：

const client = new Client({ name: 'fallback-client', version: '1.0.0' }, { capabilities: {} });
const transport = new StreamableHTTPClientTransport({
  url: new URL('http://localhost:3000/mcp'),
  sseFallbackEnabled: true
});
await client.connect(transport);

错误处理

连接错误

try {
  await client.connect(transport);
} catch (error) {
  if (error instanceof ConnectionError) {
    console.error('连接失败:', error.message);
  }
}

请求错误

try {
  const result = await client.callTool({
    name: 'risky-operation',
    arguments: {}
  });
} catch (error) {
  if (error instanceof ToolExecutionError) {
    console.error('工具执行错误:', error.message);
  }
}

完整示例

交互式客户端

以下示例展示了完整的客户端使用流程：

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';

async function main() {
  // 初始化传输层
  const transport = new StreamableHTTPClientTransport({
    url: new URL('http://localhost:3000/mcp')
  });

  // 创建客户端
  const client = new Client(
    { name: 'interactive-client', version: '1.0.0' },
    { capabilities: { resources: {}, tools: {}, prompts: {} } }
  );

  // 连接服务器
  await client.connect(transport);
  console.log('已连接到 MCP 服务器');

  // 列出资源
  const { resources } = await client.listResources();
  console.log(`发现 ${resources.length} 个资源`);

  // 调用工具
  const toolResult = await client.callTool({
    name: 'greeting',
    arguments: { name: 'World' }
  });
  console.log('工具响应:', toolResult);

  // 获取提示
  const prompt = await client.getPrompt({
    name: 'welcome',
    arguments: { user: 'Developer' }
  });
  console.log('提示内容:', prompt.messages);

  // 断开连接
  await client.close();
}

main().catch(console.error);

带认证的客户端

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';

async function authenticatedClient() {
  const transport = new StreamableHTTPClientTransport({
    url: new URL('https://api.example.com/mcp'),
    requestOptions: {
      headers: {
        'X-API-Key': process.env.API_KEY
      }
    }
  });

  const client = new Client(
    { name: 'secure-client', version: '1.0.0' },
    { capabilities: { tools: {}, resources: {} } }
  );

  await client.connect(transport, {
    authProvider: {
      token: async () => process.env.AUTH_TOKEN,
      onUnauthorized: async (ctx) => {
        // 刷新令牌逻辑
        const newToken = await refreshToken();
        ctx.retried = true;
      }
    }
  });

  return client;
}

实验性功能

实验性功能通过 @modelcontextprotocol/sdk/client/experimental 模块导出：

import { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/client/experimental';

// 任务存储配置
const taskStore = new InMemoryTaskStore();

最佳实践

相关资源

• MCP 规范文档
• 服务器开发指南
• 客户端快速开始
• examples/client

概述

MCP TypeScript SDK 提供了一套完整的认证与授权机制，支持多种认证方式，包括 Bearer Token 认证、OAuth 2.0 认证以及可组合的自定义认证提供者。该机制设计为传输层无关，可与 Streamable HTTP、SSE 等传输协议配合使用，为 MCP 客户端和服务器之间的安全通信提供保障。

认证系统的核心设计理念是通过统一的 AuthProvider 接口抽象不同的认证方式，使得开发者可以根据实际需求选择或组合使用 Bearer Token、OAuth 等认证策略。资料来源：packages/client/CHANGELOG.md

核心架构

认证提供者体系

MCP SDK 的认证体系采用分层架构设计，核心包含以下组件：

资料来源：packages/client/CHANGELOG.md, packages/core/src/shared/auth.ts

认证流程架构图

graph TD
    A[Client Request] --> B{AuthProvider}
    B -->|Bearer Token| C[Token 获取]
    B -->|OAuth| D[OAuth Flow]
    C --> E[Authorization Header]
    D --> F[Token Exchange]
    F --> G[Access Token]
    G --> E
    E --> H[Server Validation]
    H -->|401| I[onUnauthorized]
    I -->|Retry| B
    H -->|200| J[Request Success]

AuthProvider 接口

AuthProvider 是认证系统的核心接口，定义了两个关键方法：

export interface AuthProvider {
    token(): Promise<string | undefined>;
    onUnauthorized?(ctx): Promise<void>;
}

资料来源：packages/client/CHANGELOG.md

Bearer Token 认证方式

对于简单的场景，可以使用对象字面量形式快速配置 Bearer Token：

const client = createClient({
    authProvider: {
        token: async () => myApiKey
    }
});

这种方式的优点是配置简洁，无需创建类实例，适合 API Key、网关托管令牌等场景。资料来源：packages/client/CHANGELOG.md

OAuth 认证

OAuthClientProvider

SDK 提供了完整的 OAuth 客户端认证支持：

export interface OAuthClientProvider {
    // OAuth 认证核心方法
    auth(provider: {
        serverUrl: string;
        resourceMetadataUrl?: string;
        scope?: string;
        fetchFn: typeof fetch;
    }): Promise<'REDIRECT' | 'AUTHORIZED' | 'UNAUTHORIZED'>;
}

资料来源：packages/client/CHANGELOG.md

OAuth 认证流程

sequenceDiagram
    participant Client
    participant MCP_Server as MCP Server
    participant OAuth_Provider as OAuth Provider
    
    Client->>MCP_Server: Request with token()
    MCP_Server->>MCP_Server: Validate Token
    alt Token Invalid (401)
        MCP_Server->>Client: 401 Unauthorized
        Client->>OAuth_Provider: auth() with REDIRECT
        OAuth_Provider->>Client: Authorization URL
        Client->>OAuth_Provider: User Login
        OAuth_Provider->>Client: Authorization Code
        Client->>OAuth_Provider: Token Exchange
        OAuth_Provider->>Client: Access Token
        Client->>MCP_Server: Retry with new token
    end

adaptOAuthProvider 适配器

对于已有的 OAuthClientProvider 实现，SDK 提供 adaptOAuthProvider() 函数进行适配，无需修改现有代码：

import { adaptOAuthProvider } from '@modelcontextprotocol/client';

// 适配已有的 OAuth 提供者
const adaptedProvider = adaptOAuthProvider(existingOAuthProvider);

资料来源：packages/client/CHANGELOG.md

Bearer 认证中间件

bearerAuthMiddleware

Express 中间件实现了 Bearer Token 认证验证逻辑：

export function bearerAuthMiddleware(
    options: BearerAuthOptions
): RequestHandler {
    // 实现 Bearer Token 验证逻辑
}

资料来源：packages/middleware/express/src/auth/bearerAuth.ts

requireBearerAuth 工具函数

中间件导出 requireBearerAuth 函数用于简化认证配置：

const { bearerAuthMiddleware, requireBearerAuth } = createBearerAuth({
    token: () => process.env.BEARER_TOKEN
});

资料来源：packages/middleware/express/src/auth/bearerAuth.ts

资源访问控制

URL 路径匹配

authUtils.ts 提供了资源访问控制的核心工具函数 matchesResource：

export function matchesResource(requestedResource: URL | string, configuredResource: URL | string): boolean

该函数通过以下规则判断请求的资源是否在允许范围内：

// 路径匹配示例
matchesResource('https://example.com/api/users', 'https://example.com/api'); // true
matchesResource('https://example.com/api123', 'https://example.com/api'); // false

资料来源：packages/core/src/shared/authUtils.ts

资源匹配逻辑详解

graph TD
    A[解析 requestedResource] --> B[解析 configuredResource]
    B --> C{Origin 相同?}
    C -->|否| D[返回 false]
    C -->|是| E{路径长度足够?}
    E -->|否| D
    E -->|是| F[添加尾部斜杠]
    F --> G[比较路径前缀]
    G --> H{匹配成功?}
    H -->|是| I[返回 true]
    H -->|否| D

认证中间件

createMiddleware

SDK 提供了 createMiddleware 工厂函数用于创建自定义认证中间件：

export function createMiddleware(
    handler: (next: typeof fetch, input: RequestInfo, init?: RequestInit) => Promise<Response>
): MiddlewareFunction

资料来源：packages/client/src/client/middleware.ts

认证中间件工作流程

graph TD
    A[Request Incoming] --> B{AuthProvider.token()}
    B -->|返回 token| C[添加 Authorization 头]
    B -->|返回 undefined| D[跳过认证]
    C --> E[发送请求到 next]
    D --> E
    E --> F{Response 401?}
    F -->|是| G{cb.onUnauthorized?}
    F -->|否| H[返回 Response]
    G -->|存在| I[调用 onUnauthorized]
    G -->|不存在| J[抛出 UnauthorizedError]
    I --> K[重试请求]
    K --> H
    J --> L[终止流程]

中间件示例

自定义认证中间件：

const customAuthMiddleware = createMiddleware(async (next, input, init) => {
    const headers = new Headers(init?.headers);
    headers.set('X-Custom-Auth', 'my-token');
    
    const response = await next(input, { ...init, headers });
    
    if (response.status === 401) {
        console.log('Authentication failed');
    }
    
    return response;
});

条件认证中间件：

const conditionalMiddleware = createMiddleware(async (next, input, init) => {
    const url = typeof input === 'string' ? input : input.toString();
    
    if (url.includes('/api/')) {
        const headers = new Headers(init?.headers);
        headers.set('X-API-Version', 'v2');
        return next(input, { ...init, headers });
    }
    
    return next(input, init);
});

资料来源：packages/client/src/client/middleware.ts

跨应用访问控制

CrossAppAccess 认证

crossAppAccess.ts 实现了跨应用程序访问的认证机制，支持对特定资源路径的细粒度访问控制：

export interface CrossAppAccessAuth {
    validateCrossAppRequest(requestedResource: string): Promise<boolean>;
}

资料来源：packages/client/src/client/crossAppAccess.ts

日志记录

RequestLogger

认证系统支持详细的日志记录，便于调试和审计：

export type RequestLogger = (input: {
    method: string;
    url: string | URL;
    status: number;
    statusText: string;
    duration: number;
    requestHeaders?: Headers;
    responseHeaders?: Headers;
    error?: Error;
}) => void;

资料来源：packages/client/src/client/middleware.ts

Session 管理

Session Cookie 处理

认证服务器使用 Cookie 机制管理用户会话：

function getUserSessionCookie(cookieHeader?: string): { 
    userId: string; 
    name: string; 
    timestamp: number 
} | null

该函数解析 demo_session Cookie 并返回用户会话信息。Cookie 存储的用户信息包括：

资料来源：examples/shared/src/authServer.ts

认证流程中的 Session 处理

graph LR
    A[用户登录] --> B[创建 Session]
    B --> C[设置 Set-Cookie]
    C --> D[浏览器存储 Cookie]
    D --> E[后续请求自动携带 Cookie]
    E --> F[服务端验证 Session]

最佳实践

认证配置建议

安全注意事项

1. Token 存储：避免在前端代码中硬编码敏感 Token
2. HTTPS 传输：确保所有认证请求通过 HTTPS 进行
3. Token 刷新：实现 onUnauthorized 回调处理 Token 过期
4. 错误处理：妥善处理认证失败情况，避免信息泄露

资料来源：packages/client/CHANGELOG.md, packages/middleware/express/src/auth/bearerAuth.ts

相关资源

• 认证与授权官方文档
• Express 中间件示例
• OAuth 示例服务器

概述

Model Context Protocol (MCP) TypeScript SDK 提供了与主流 Web 框架的中间件集成支持，使开发者能够将 MCP 服务器无缝嵌入到现有的 Express、Hono 和 Fastify 应用中。这些中间件适配器充当 MCP 传输层与 Web 框架之间的桥梁，实现了标准化的请求处理和响应流式传输机制。

中间件集成的核心价值在于：开发者无需构建独立的 MCP 服务器进程，而是可以直接在现有的 Web 应用中暴露 MCP 工具、资源和提示词功能。这种架构模式特别适合需要将 MCP 功能与现有 API 服务、认证中间件、日志系统等组件整合的场景。

架构设计

整体架构

MCP Web 框架中间件采用了适配器模式设计，每种框架都有对应的传输层实现。中间件负责接收框架的 HTTP 请求，将其转换为 MCP 协议消息，然后调用底层 MCP 服务器处理逻辑，最终将处理结果以框架兼容的方式返回给客户端。

graph TD
    A[HTTP 客户端] --> B[Web 框架路由]
    B --> C[MCP 中间件适配器]
    C --> D[MCP 协议消息解析]
    D --> E[MCP 服务器核心]
    E --> F[工具/资源/提示词处理器]
    F --> G[响应序列化]
    G --> C
    C --> H[HTTP 响应]
    H --> A

核心组件关系

中间件层由三个主要包组成，分别对应三种 Web 框架：

每个中间件包都包含核心适配器模块和安全验证中间件两个部分。核心适配器负责处理 MCP 协议通信，而安全中间件则提供主机头验证等防护功能。

Express 中间件集成

核心功能

Express 中间件 (packages/middleware/express/src/express.ts) 提供了与 Express 框架的完整集成能力。它基于 MCP Streamable HTTP 传输协议实现，支持状态ful 和无状态两种运行模式。

Express 中间件的主要职责包括：

• 将 Express 请求转换为 MCP JSON-RPC 消息
• 管理会话状态（状态ful 模式）
• 处理流式响应和 Server-Sent Events (SSE)
• 与 Express 路由系统和中间件链集成

使用方式

开发者可以通过标准的 Express use() 方法将 MCP 中间件添加到应用中：

import express from 'express';
import { useMcpExpress } from '@modelcontextprotocol/express';

const app = express();

app.use(express.json());

app.use('/mcp', useMcpExpress(server, {
  transport: 'streamable-http',
  mode: 'stateful' // 或 'stateless'
}));

中间件配置选项允许指定传输类型、运行模式和回调处理函数。状态ful 模式会维护会话信息，适合需要跨请求保持状态的复杂应用场景；无状态模式则每次请求独立处理，更适合简单的 API 式服务器。

安全中间件

Express 包还包含了主机头验证中间件 (packages/middleware/express/src/middleware/hostHeaderValidation.ts)，用于防止主机头欺骗攻击。该中间件会验证请求中的 Host 和 X-Forwarded-Host 头，确保请求确实发往预期的目标地址。

Hono 中间件集成

核心功能

Hono 中间件 (packages/middleware/hono/src/hono.ts) 提供了轻量级、高性能的 Hono 框架集成。Hono 本身是一个支持多个运行时的 Web 框架，因此 MCP Hono 中间件可以同时在 Node.js、Cloudflare Workers、Deno Deploy 等环境中运行。

Hono 中间件利用了 Hono 的流式响应处理能力，可以高效地处理 MCP 的流式消息传输。

使用方式

Hono 中间件通过 Hono 的标准中间件机制注册：

import { Hono } from 'hono';
import { mcpHono } from '@modelcontextprotocol/hono';

const app = new Hono();
const mcp = new McpServer({ /* 配置 */ });

app.use('/mcp', mcpHono(mcp, {
  transport: 'streamable-http',
  binder: someBinder
}));

安全中间件

Hono 包同样包含了主机头验证中间件 (packages/middleware/hono/src/middleware/hostHeaderValidation.ts)，实现方式与 Express 版本类似，但针对 Hono 的上下文 API 进行了适配。

Fastify 中间件集成

核心功能

Fastify 中间件 (packages/middleware/fastify/src/fastify.ts) 提供了与高性能 Node.js 框架 Fastify 的集成。Fastify 以其卓越的性能著称，MCP 中间件充分利用了 Fastify 的插件系统和流式处理能力。

Fastify 集成支持：

• Fastify 插件式架构
• 高性能请求路由
• JSON Schema 验证集成
• 流式响应处理

使用方式

import Fastify from 'fastify';
import { mcpFastify } from '@modelcontextprotocol/fastify';

const fastify = Fastify();
const server = new McpServer({ /* 配置 */ });

fastify.register(mcpFastify, {
  server,
  prefix: '/mcp'
});

传输协议

Streamable HTTP 传输

所有 Web 框架中间件都使用 Streamable HTTP 作为传输协议。这是 MCP 规范中定义的标准传输方式，支持：

请求处理流程

sequenceDiagram
    participant C as 客户端
    participant M as 中间件
    participant S as MCP服务器
    participant H as 处理器

    C->>M: POST /mcp (JSON-RPC Request)
    M->>S: 路由请求
    S->>H: 调用处理器
    H->>S: 返回结果
    S->>M: 流式响应
    M->>C: SSE 流
    C->>M: GET /mcp (SSE 连接)
    M->>S: 建立会话
    S->>M: 会话通道
    M->>C: 事件流

安全特性

主机头验证

主机头验证中间件是所有 Web 框架集成的标准安全组件。其工作原理包括：

1. 白名单检查：验证请求的 Host 头是否在允许的域名列表中
2. 代理头处理：正确处理 X-Forwarded-Host 等代理头
3. 协议验证：确保请求协议与预期匹配

该中间件能够有效防御以下攻击：

• DNS 重绑定攻击
• 主机头欺骗
• 代理层配置错误导致的安全问题

认证集成

Web 框架中间件可以与各框架的认证系统无缝集成。开发者可以在 MCP 中间件之前注册任何 Express/Hono/Fastify 认证中间件，例如 JWT 验证、OAuth 验证或自定义会话验证。

配置选项

通用配置

状态ful 与无状态模式

状态ful 模式维护会话状态，允许跨请求保持上下文：

• 适合需要维护状态的复杂交互
• 支持长连接和持久化上下文
• 需要配置会话存储

无状态模式每次请求独立处理：

• 适合简单的工具调用场景
• 更易于水平扩展
• 无需会话管理开销

与示例代码的对应关系

examples/server/README.md 中列出的示例演示了这些中间件的实际应用：

这些示例位于 examples/server/src/ 目录，展示了从简单的服务器配置到复杂的认证集成的完整使用方式。

最佳实践

生产环境部署

1. 安全配置：始终在 MCP 中间件之前配置认证和主机头验证中间件
2. 会话管理：根据应用场景选择合适的状态管理模式
3. 超时设置：合理配置请求超时和会话超时
4. 错误处理：实现统一的错误处理中间件，确保错误信息正确返回

性能优化

1. 路由前缀：使用明确的路由前缀避免与其他 API 冲突
2. 中间件顺序：将 MCP 中间件放在合适的路由层级
3. 会话限制：在状态ful 模式下设置合理的最大会话数

总结

MCP TypeScript SDK 的 Web 框架中间件集成提供了强大而灵活的解决方案，使开发者能够将 Model Context Protocol 无缝嵌入到任何基于 Express、Hono 或 Fastify 的应用中。通过统一的适配器接口和安全组件，中间件系统确保了跨框架的一致性体验，同时充分发挥了各框架的独特优势。

概述

MCP TypeScript SDK 提供了一套实验性的任务系统（Task System），允许服务器和客户端管理异步长时运行任务。这些任务可以通过唯一标识符进行追踪、查询和取消操作。

实验性功能通过 @modelcontextprotocol/sdk/experimental 模块导出，使用前需注意：

⚠️ 警告：这些 API 是实验性的，可能会在没有任何通知的情况下发生变化。

import { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';

资料来源：packages/server/src/experimental/index.ts

Pitfall Log / 踩坑日志

项目：modelcontextprotocol/typescript-sdk

摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：运行坑 - 来源证据：client code can't execute inside browser due to import spawn。

1. 运行坑 · 来源证据：client code can't execute inside browser due to import spawn

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：client code can't execute inside browser due to import spawn
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_8a06947266aa4987ad712baf87a7a156 | https://github.com/modelcontextprotocol/typescript-sdk/issues/2077 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

2. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 typescript-sdk 与安装入口 @modelcontextprotocol/server 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：npm install @modelcontextprotocol/server
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | repo=typescript-sdk; install=@modelcontextprotocol/server

3. 安装坑 · 来源证据：@modelcontextprotocol/[email protected]

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/[email protected]
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_fc8de64b72814f8eb9ed0e53852408c2 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/node%402.0.0-alpha.1 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

4. 安装坑 · 来源证据：@modelcontextprotocol/[email protected]

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/[email protected]
• 对用户的影响：可能影响升级、迁移或版本选择。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_dff36a13cb954c3b84b05e99a28dc4d0 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.0.0-alpha.1 | 来源类型 github_release 暴露的待验证使用条件。

5. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | README/documentation is current enough for a first validation pass.

6. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | last_activity_observed missing

7. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium

8. 安全/权限坑 · 存在安全注意事项

• 严重度：medium
• 证据强度：source_linked
• 发现：No sandbox install has been executed yet; downstream must verify before user use.
• 对用户的影响：用户安装前需要知道权限边界和敏感操作。
• 建议检查：转成明确权限清单和安全审查提示。
• 防护动作：安全注意事项必须面向用户前置展示。
• 证据：risks.safety_notes | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | No sandbox install has been executed yet; downstream must verify before user use.

9. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium

10. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | issue_or_pr_quality=unknown

11. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | release_recency=unknown