# https://github.com/modelcontextprotocol/typescript-sdk 项目说明书
生成时间：2026-05-13 12:02:59 UTC
## 目录
- [MCP TypeScript SDK 概述](#page-1)
- [系统架构与包结构](#page-2)
- [协议与类型定义](#page-3)
- [数据验证与 Schema](#page-4)
- [传输层实现](#page-5)
- [服务器开发指南](#page-6)
- [客户端开发指南](#page-7)
- [认证与授权机制](#page-8)
- [Web 框架中间件集成](#page-9)
- [实验性功能与任务系统](#page-10)
## MCP TypeScript SDK 概述
### 相关页面
相关主题：[系统架构与包结构](#page-2), [服务器开发指南](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/README.md)
- [CLAUDE.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)
- [examples/server/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)
- [examples/client/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/README.md)
- [packages/server/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)
- [packages/core/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)
- [packages/client/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)
- [packages/middleware/express/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/CHANGELOG.md)
- [packages/middleware/hono/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/CHANGELOG.md)
- [packages/middleware/fastify/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/CHANGELOG.md)
- [common/tsconfig/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/common/tsconfig/package.json)
# MCP TypeScript SDK 概述
## 简介
MCP TypeScript SDK（Model Context Protocol TypeScript SDK）是 Model Context Protocol 的 TypeScript/Node.js 实现，为开发者提供了构建 MCP 服务器和客户端的能力。该 SDK 采用 Monorepo 结构，包含核心包、客户端包、服务器包以及多种 Web 框架适配器。
资料来源：[README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/README.md)
## 架构设计
### 两层导出结构
SDK 采用精心设计的两层导出结构，以清晰分离内部实现和公共 API：
```mermaid
graph TD
A["@modelcontextprotocol/core
packages/core/src/index.ts"] --> B["内部 barrel
导出全部内容"]
A --> C["包括 Zod schemas、Protocol 类、stdio 工具"]
B --> D["@modelcontextprotocol/core/public
packages/core/src/exports/public/index.ts"]
D --> E["仅导出：TypeScript 类型、错误类、常量、守卫函数"]
D --> F["@modelcontextprotocol/client"]
D --> G["@modelcontextprotocol/server"]
F --> H["最终公共表面"]
G --> H
```
资料来源：[CLAUDE.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)
### 导出层级说明
| 层级 | 包名 | 用途 | 可见性 |
|------|------|------|--------|
| 第一层 | `@modelcontextprotocol/core` | 内部 barrel，导出所有内容 | 私有，仅 monorepo 内部使用 |
| 第二层 | `@modelcontextprotocol/core/public` | 精选公共 API | 公共 |
| 第三层 | `@modelcontextprotocol/client` | 客户端特定导出 | 公共 |
| 第三层 | `@modelcontextprotocol/server` | 服务器特定导出 | 公共 |
**导出规范要求：**
- 在包的 `index.ts` 文件和 `core/public` 中使用显式命名导出（`export *` 禁止）
- 向包的 `index.ts` 添加符号会使其成为公共 API，需谨慎操作
- 内部辅助函数应保留在 core 内部 barrel 中，不添加到 `core/public`
资料来源：[CLAUDE.md:1-15](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)
## 核心模块
### 包结构总览
```mermaid
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](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)
### 实验性功能
实验性功能通过 `@modelcontextprotocol/sdk/experimental` 模块导出：
```typescript
import { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';
```
资料来源：[packages/server/src/experimental/index.ts:1-10](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)
## 服务器开发
### 服务器示例索引
| 场景 | 描述 | 文件 |
|------|------|------|
| Streamable HTTP 服务器（有状态） | 功能丰富的服务器，支持工具/资源/提示、日志、任务、采样和可选 OAuth | `src/simpleStreamableHttp.ts` |
| Streamable HTTP 服务器（无状态） | 无会话跟踪，适用于简单的 API 风格服务器 | `src/simpleStatelessStreamableHttp.ts` |
| 仅资源服务器认证 | 使用 SDK 的 `mcpAuthMetadataRouter` + `requireBearerAuth` 的最小化 OAuth RS | `src/resourceServerOnly.ts` |
| JSON 响应模式（无 SSE） | 仅 JSON 响应的 Streamable HTTP，有限的通知支持 | `src/jsonResponseStreamableHttp.ts` |
资料来源：[examples/server/README.md:20-30](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)
### 运行服务器示例
从仓库根目录运行：
```bash
pnpm install
pnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts
```
或在示例包内运行：
```bash
cd examples/server
pnpm tsx src/simpleStreamableHttp.ts
```
资料来源：[examples/server/README.md:10-15](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)
### Web 框架适配器
SDK 提供多种 Web 框架的中间件适配器：
| 适配器 | 包名 | 文档 |
|--------|------|------|
| Express | `@modelcontextprotocol/express` | `packages/middleware/express` |
| Hono | `@modelcontextprotocol/hono` | `packages/middleware/hono` |
| Fastify | `@modelcontextprotocol/fastify` | `packages/middleware/fastify` |
| Node.js | `@modelcontextprotocol/node` | `packages/middleware/node` |
所有中间件适配器均基于统一的适配器模式构建，遵循 Express 和 Hono 适配器的设计规范。
资料来源：[packages/middleware/fastify/CHANGELOG.md:18-22](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/CHANGELOG.md)
## 客户端开发
### 客户端示例索引
| 场景 | 描述 | 文件 |
|------|------|------|
| 交互式 Streamable HTTP 客户端 | CLI 客户端，测试工具/资源/提示、通知、 elicit 内容和任务 | `src/simpleStreamableHttp.ts` |
| 向后兼容客户端 | 优先尝试 Streamable HTTP，在 4xx 响应时回退到传统 SSE | `src/streamableHttpWithSseFallbackClient.ts` |
| SSE 轮询客户端（传统） | 轮询传统 HTTP+SSE 服务器，展示通知处理 | `src/ssePollingClient.ts` |
| 并行工具调用 | 并行运行多个工具调用 | - |
资料来源：[examples/client/README.md:18-25](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/README.md)
### 运行客户端示例
从仓库根目录运行：
```bash
pnpm install
pnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts
```
大多数客户端示例需要先启动服务器（参考服务器示例）。
资料来源：[examples/client/README.md:8-12](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/README.md)
### 客户端核心功能
#### OAuth 发现功能
SDK 2.0.0-alpha.1 引入了 `discoverOAuthServerInfo()` 函数和统一的发现状态缓存机制。
资料来源：[packages/client/CHANGELOG.md:14-17](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)
#### WebSocket 变更
**重要变更**：从 2.0.0-alpha.1 开始，`WebSocketClientTransport` 已被移除。WebSocket 不是规范定义的传输方式，请使用 stdio 或 Streamable HTTP。`Transport` 接口仍然导出以支持自定义实现。
资料来源：[packages/client/CHANGELOG.md:10-14](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)
## 核心包功能
### 资源模式增强
SDK 在 `ResourceSchema` 中添加了缺失的 `size` 字段，以匹配 MCP 规范。
资料来源：[packages/core/CHANGELOG.md:2-4](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)
### 安全修复
#### ReDoS 漏洞修复
修复了 UriTemplate 正则表达式模式中的 ReDoS 漏洞（CVE-2026-0621）。
资料来源：[packages/core/CHANGELOG.md:6-8](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)
### 能力断言规范化
SDK 将剩余的能力断言转换为 `SdkError(SdkErrorCode.CapabilityNotSupported, ...)` 格式，包括：
- `Client.assertCapability()`
- 实验性任务辅助函数（`experimental/tasks/helpers.ts`）
- 采样/elicitation 能力检查（`experimental/tasks/server.ts`）
资料来源：[packages/core/CHANGELOG.md:9-15](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)
## 版本历史
### 最新版本动态
| 包 | 当前版本 | 关键变更 |
|----|----------|----------|
| `@modelcontextprotocol/core` | 2.0.0 | 核心库 |
| `@modelcontextprotocol/client` | 2.0.0-alpha.2 | tsdown exports resolution fix |
| `@modelcontextprotocol/server` | 2.0.0-alpha.2 | tsdown exports resolution fix |
| `@modelcontextprotocol/express` | 2.0.0-alpha.2 | tsdown exports resolution fix |
| `@modelcontextprotocol/hono` | 2.0.0-alpha.2 | tsdown exports resolution fix |
| `@modelcontextprotocol/fastify` | 2.0.0-alpha.2 | tsdown exports resolution fix |
| `@modelcontextprotocol/node` | 2.0.0-alpha.2 | tsdown exports resolution fix |
所有中间件包的 2.0.0-alpha.2 版本都依赖于 `@modelcontextprotocol/server@2.0.0-alpha.2`。
资料来源：[packages/client/CHANGELOG.md:1-10](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)，[packages/middleware/express/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/CHANGELOG.md)，[packages/middleware/hono/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/CHANGELOG.md)
## 开发工具配置
### TypeScript 配置
SDK 使用统一的 TypeScript 配置：
```json
{
"name": "@modelcontextprotocol/tsconfig",
"private": true,
"main": "tsconfig.json",
"type": "module",
"dependencies": {
"typescript": "catalog:devTools"
}
}
```
资料来源：[common/tsconfig/package.json:1-13](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/common/tsconfig/package.json)
## 快速开始
### 安装依赖
```bash
pnpm install
```
### 构建项目
```bash
pnpm build
```
### 开发工作流
```mermaid
graph LR
A["安装 pnpm install"] --> B["运行示例"]
B --> C["服务器示例
pnpm --filter @modelcontextprotocol/examples-server"]
B --> D["客户端示例
pnpm --filter @modelcontextprotocol/examples-client"]
```
## 相关文档
- [服务器开发指南](../../docs/server.md)
- [客户端开发指南](../../docs/client.md)
- [官方 MCP 规范](https://modelcontextprotocol.io)
---
## 系统架构与包结构
### 相关页面
相关主题：[MCP TypeScript SDK 概述](#page-1), [协议与类型定义](#page-3)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/server/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/package.json)
- [packages/client/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/package.json)
- [packages/middleware/node/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/package.json)
- [packages/core/src/types/spec.types.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/spec.types.ts)
- [CLAUDE.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)
- [package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/package.json)
# 系统架构与包结构
## 概述
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]()
```mermaid
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 层提供面向终端用户的接口：
| 类名 | 文件位置 | 职责 |
|------|---------|------|
| `Client` | `packages/client/src/client/client.ts` | 客户端实现，扩展 Protocol 类，提供 MCP 操作的类型化方法 |
| `Server` | `packages/server/src/server/server.ts` | 服务端实现，扩展 Protocol 类，提供请求处理器注册 |
| `McpServer` | `packages/server/src/server/mcp.ts` | 高层服务器 API，简化资源/工具/提示的注册流程 |
## 包结构概览
SDK 采用 monorepo 结构，使用 pnpm workspaces 管理多个包。以下是主要包的层次结构：资料来源：[package.json]()
```mermaid
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 *` 的原则。
支持的传输方式：
| 传输类型 | 描述 | 适用场景 |
|---------|------|---------|
| Streamable HTTP | 推荐的现代传输方式，支持状态化会话 | Web 应用、服务端集成 |
| stdio | 标准输入输出传输 | 本地进程、CLI 工具 |
| SSE (Legacy) | 服务端发送事件，兼容旧版服务器 | 向后兼容 |
资料来源：[packages/client/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/package.json)
### @modelcontextprotocol/server
服务端包提供 MCP 协议的服务端实现，允许开发者注册工具、资源、提示，并处理来自客户端的请求。该包是许多框架适配器的基础依赖。
主要功能：
- 工具注册与处理
- 资源管理
- 提示注册
- 采样请求处理
- 任务管理 (experimental)
服务端包提供多个子路径导出以支持不同的运行环境：
| 导出路径 | 类型定义 | 说明 |
|---------|---------|------|
| `.` | `dist/index.d.mts` | 主入口 |
| `./stdio` | `dist/stdio.d.mts` | stdio 传输支持 |
| `./validators/cf-worker` | `dist/validators/cfWorker.d.mts` | Cloudflare Workers 验证器 |
| `./_shims` | 多环境 | workerd、browser、node 环境垫片 |
资料来源：[packages/server/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/package.json)
## 中间件与适配器层
中间件层提供将 MCP 服务端集成到不同 Web 框架的适配器，简化常见服务器框架的使用。
### @modelcontextprotocol/hono
Hono 框架适配器，用于在 Hono 应用中运行 MCP 服务端。Hono 是一个轻量、跨平台的 Web 框架，支持 Cloudflare Workers、Deno、Bun 等运行环境。
```typescript
// 使用示例结构
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](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/CHANGELOG.md)
### @modelcontextprotocol/node
Node.js 原生适配器，提供基于 `@hono/node-server` 的服务端实现。这是运行在标准 Node.js 环境中时推荐使用的中间件。
该包已添加缺失的 `hono` peer 依赖，确保运行时依赖完整。资料来源：[packages/middleware/node/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/CHANGELOG.md)
## 传输系统
传输层位于 `packages/core/src/shared/transport.ts`，负责客户端与服务端之间的通信。SDK 支持多种传输机制，每种都有特定的适用场景。
### Streamable HTTP
Streamable HTTP 是 V2 版本推荐的传输方式，支持状态化会话管理。它允许服务器跟踪会话状态，适合需要维护上下文的复杂交互场景。
```mermaid
graph LR
A[Client] -->|HTTP POST /mcp| B[Streamable HTTP Server]
B -->|Streaming Response| A
A <-->|Session Token| B
```
### stdio 传输
stdio 传输通过标准输入输出进行通信，适用于本地进程调用和命令行工具。这是 MCP 最初设计的传输方式，配置简单，无需网络。
### 传输导出结构
为确保运行时环境兼容性，stdio 相关的导出位于命名子路径：
```typescript
// 运行时中性导入（浏览器、Cloudflare Workers）
import { Client } from '@modelcontextprotocol/client';
// Node.js 专用 stdio 导入
import { stdioClientTransport } from '@modelcontextprotocol/client/stdio';
```
资料来源：[packages/client/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/package.json)
## 导出结构与命名规范
SDK 采用两层导出结构来区分内部实现和公共 API，这是确保包边界清晰的关键设计。
### 内部导出 (Internal Barrel)
`@modelcontextprotocol/core` 的主入口导出所有内部实现，包括：
- Zod 模式 (Schema)
- Protocol 类
- stdio 工具函数
- 内部帮助函数
这些导出仅供 monorepo 内部包使用，不应被外部代码直接依赖。
### 公共导出 (Public API)
`@modelcontextprotocol/core/public` 提供精选的公共 API，仅包含：
| 类别 | 内容 |
|-----|------|
| TypeScript 类型 | 所有公共接口和类型定义 |
| 错误类 | 异常处理类 |
| 常量 | 协议常量 |
| 守卫函数 | 类型守卫和验证函数 |
### 包索引导出规则
在修改导出时需遵循以下规则：
1. **使用显式命名导出** — 包索引文件应使用 `export { SpecificExport }` 而非 `export *`
2. **公共 API 变更需谨慎** — 添加到包索引的符号即成为公共 API
3. **内部代码隔离** — 内部帮助函数应保留在 core 内部桶中
4. **运行时中性** — 包根入口必须保持运行时中性，确保浏览器和 Cloudflare Workers 可正常打包
## 实验性功能
SDK 将某些功能标记为实验性，通过 `@modelcontextprotocol/sdk/experimental` 导出。当前实验性功能包括任务存储 (TaskStore) 相关实现。
```typescript
// 导入实验性功能
import { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';
```
实验性 API 可能随时变更，不提供稳定性保证。使用前请评估风险。
资料来源：[packages/server/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)
## 构建与工具链
SDK 使用以下工具链进行开发和构建：
| 工具 | 用途 | 配置位置 |
|-----|------|---------|
| pnpm | 包管理器 | `pnpm-workspace.yaml` |
| TypeScript | 类型检查 | `tsconfig.json` |
| tsdown | 包构建 | 各包的 `package.json` |
| vitest | 测试框架 | `vitest.config.ts` |
| typedoc | 文档生成 | TypeDoc 配置 |
### 常用构建命令
```bash
# 安装依赖
pnpm install
# 类型检查
pnpm typecheck:all
# 构建所有包
pnpm build:all
# 生成文档
pnpm docs
# 运行测试
pnpm test
```
## 版本与兼容性
| 包 | 当前版本 | Node.js 最低版本 |
|----|---------|-----------------|
| @modelcontextprotocol/client | 2.0.0-alpha.2 | >=20 |
| @modelcontextprotocol/server | 2.0.0-alpha.2 | >=20 |
| @modelcontextprotocol/sdk | 2.0.0-alpha.0 | >=20 |
V2 版本移除了 WebSocket 传输，WebSocket 不是规范定义的传输方式。推荐使用 stdio 或 Streamable HTTP。如需自定义传输，可实现并使用 `Transport` 接口。资料来源：[packages/client/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)
---
## 协议与类型定义
### 相关页面
相关主题：[系统架构与包结构](#page-2), [数据验证与 Schema](#page-4)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/src/shared/protocol.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/shared/protocol.ts)
- [packages/core/src/types/types.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/types.ts)
- [packages/core/src/types/specTypeSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/specTypeSchema.ts)
- [packages/core/src/validators/fromJsonSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/validators/fromJsonSchema.ts)
- [packages/server/src/server/completable.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/completable.ts)
# 协议与类型定义
## 概述
MCP TypeScript SDK 的核心架构建立在两层抽象之上：**协议层（Protocol Layer）** 和 **类型层（Types Layer）**。协议层负责 JSON-RPC 消息的路由、请求/响应关联、能力协商和传输管理；类型层则定义了所有 MCP 协议消息的 Zod v4 模式和数据结构。
这两个层次共同构成了 SDK 的基础设施，支撑着 Client、Server 和 McpServer 的高级 API 实现。
## 架构分层
```mermaid
graph TB
subgraph "High-Level APIs"
McpServer["McpServer
packages/server/src/server/mcp.ts"]
Server["Server
packages/server/src/server/server.ts"]
Client["Client
packages/client/src/client/client.ts"]
end
subgraph "Protocol Layer"
Protocol["Protocol
packages/core/src/shared/protocol.ts"]
end
subgraph "Types Layer"
Types["Types
packages/core/src/types/types.ts"]
SpecTypes["SpecTypes
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 消息路由 | 解析和分发 JSON-RPC 请求/响应/通知 |
| 请求-响应关联 | 维护 pendingRequests Map，关联请求 ID 与回调 |
| 能力协商 | 能力注册和匹配机制 |
| 传输管理 | 底层通信抽象 |
### JSON-RPC 消息类型
MCP 协议使用标准 JSON-RPC 2.0 消息格式：
| 消息类型 | 方向 | 说明 |
|----------|------|------|
| Request | 双向 | 需要响应的消息，带 `id` |
| Response | 双向 | 对请求的响应，包含 `id` 和 `result`/`error` |
| Notification | 双向 | 无需响应的消息，不带 `id` |
```mermaid
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 类提供方法注册各类消息的处理器：
```typescript
// 资料来源：packages/core/src/shared/protocol.ts
requestHandlers: Map
notificationHandlers: Map
```
## 类型层
### 类型组织结构
类型层位于 `packages/core/src/types/`，包含以下核心文件：
| 文件 | 职责 |
|------|------|
| `types.ts` | MCP 协议类型定义，从规范生成 |
| `specTypeSchema.ts` | StandardSchemaV1 类型架构 |
| `errors.ts` | 错误类型定义 |
| `enums.ts` | 枚举类型定义 |
### 资源类型（Resources）
资源用于向客户端暴露可读取的数据：
```typescript
// 资料来源：packages/core/src/types/types.ts
export type TextResourceContents = Infer;
export type BlobResourceContents = Infer;
export type Resource = Infer;
export type ResourceTemplate = Infer;
```
| 类型 | 说明 |
|------|------|
| `TextResourceContents` | 文本资源内容 |
| `BlobResourceContents` | 二进制资源内容 |
| `Resource` | 完整资源定义 |
| `ResourceTemplate` | 资源模板（带占位符） |
### 提示类型（Prompts）
提示用于定义可复用的消息模板：
```typescript
// 资料来源：packages/core/src/types/types.ts
export type PromptArgument = Infer;
export type Prompt = Infer;
export type ListPromptsResult = Infer;
export type GetPromptRequest = Infer;
```
### 工具类型（Tools）
工具是服务器暴露的可执行操作：
| 类型 | 说明 |
|------|------|
| `CallToolRequest` | 工具调用请求 |
| `CallToolResult` | 工具调用结果 |
| `Tool` | 工具定义 |
| `ToolAnnotations` | 工具注解（毒性、是否确定性等） |
```typescript
// 资料来源：packages/core/src/types/types.ts
export type CallToolResult = Infer;
export type Tool = Infer;
```
### 任务类型（Tasks）
任务支持长时运行的异步操作：
```typescript
// 资料来源：packages/server/src/server/mcp.ts
type TaskHandlerInternal = {
createTask: (args: unknown, ctx: CreateTaskServerContext) => CreateTaskResult | Promise;
};
```
## StandardSchemaV1 类型系统
### 概述
SDK 使用 [StandardSchemaV1](https://github.com/ModelContextProtocol/typescript-sdk/blob/main/packages/core/src/types/specTypeSchema.ts) 作为输入输出的标准模式格式，这是一个供应商中立（vendor-neutral）的模式接口。
### 模式注册机制
`specTypeSchema.ts` 通过注册表模式将 MCP 规范中的所有类型映射到 StandardSchemaV1：
```typescript
// 资料来源：packages/core/src/types/specTypeSchema.ts
const _specTypeSchemas: Record = {};
const _isSpecType: Record 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 类型映射
```typescript
// 资料来源：packages/core/src/types/specTypeSchema.ts
export type SpecTypes = {
[K in SchemaKey as StripSchemaSuffix]: SchemaFor extends z.ZodType ? z.output> : never;
};
```
### 从 JSON Schema 转换
SDK 提供 `fromJsonSchema` 函数将 JSON Schema 转换为 StandardSchemaV1：
```typescript
// 资料来源：packages/core/src/validators/fromJsonSchema.ts
export function fromJsonSchema(
schema: JsonSchemaType,
validator: jsonSchemaValidator
): StandardSchemaWithJSON {
return {
'~standard': {
version: 1,
vendor: 'mcp',
jsonSchema: {
input: () => schema as Record,
output: () => schema as Record
},
validate: (data: unknown): StandardSchemaV1.Result => {
const result = check(data);
return result.valid
? { value: result.data }
: { issues: [{ message: result.errorMessage }] };
}
}
};
}
```
## Completable 类型
Completable 提供参数自动完成功能：
```typescript
// 资料来源：packages/server/src/server/completable.ts
export const COMPLETABLE_SYMBOL: unique symbol = Symbol.for('mcp.completable');
export type CompleteCallback = (
value: StandardSchemaV1.InferInput,
context?: {
arguments?: Record;
}
) => StandardSchemaV1.InferInput[] | Promise[]>;
export type CompletableSchema = T & {
[COMPLETABLE_SYMBOL]: CompletableMeta;
};
```
使用示例：
```typescript
// 资料来源：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 层级
```mermaid
graph TD
ZodType["z.ZodType
基础类型"]
ZodObject["z.ZodObject
对象类型"]
ZodArray["z.ZodArray
数组类型"]
ZodString["z.ZodString
字符串"]
ZodNumber["z.ZodNumber
数字"]
ZodBoolean["z.ZodBoolean
布尔值"]
ZodType --> ZodObject
ZodType --> ZodArray
ZodType --> ZodString
ZodType --> ZodNumber
ZodType --> ZodBoolean
```
### 模式验证流程
```mermaid
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 定义了结构化的错误类型：
| 错误类型 | 说明 |
|----------|------|
| `JsonRpcError` | JSON-RPC 标准错误 |
| `McpError` | MCP 特定错误 |
| 错误码范围 | MCP 保留 10000-19999 |
## 枚举类型
`enums.ts` 定义了协议中使用的枚举值：
| 枚举 | 用途 |
|------|------|
| 日志级别 | `debug`, `info`, `warning`, `error` |
| 资源可见性 | `secret`, `information`, `documentation` |
| 采样优先级 | `low`, `medium`, `high` |
## 类型推断机制
SDK 使用 TypeScript 的类型推断来提供类型安全：
```typescript
// 资料来源：packages/core/src/types/types.ts
// 使用 Infer 类型工具从 Zod schema 推断 TypeScript 类型
export type Resource = Infer;
export type Prompt = Infer;
export type CallToolResult = Infer;
```
### Infer 类型定义
```typescript
// Infer 类型工具允许从 Zod schema 反向推断 TypeScript 类型
type Infer = T extends z.ZodType
? Output
: never;
```
## 模式键名约定
MCP 规范中的模式使用统一后缀约定：
| 后缀 | 含义 | 示例 |
|------|------|------|
| `Schema` | 原始 Zod schema | `ListResourcesRequestSchema` |
| 无后缀 | 推断后的 TypeScript 类型 | `ListResourcesRequest` |
## 导出结构
SDK 采用两层导出结构：
```mermaid
graph LR
subgraph "@modelcontextprotocol/core"
Core["内部 barrel
导出所有内容"]
end
subgraph "@modelcontextprotocol/client"
Client["公共 API
客户端专用"]
end
subgraph "@modelcontextprotocol/server"
Server["公共 API
服务端专用"]
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 抽象** — 支持供应商中立的模式定义
### 模式设计
| 实践 | 说明 |
|------|------|
| 显式类型注解 | 使用 `z.object()` 显式定义对象结构 |
| 描述字段 | 使用 `.describe()` 提供字段文档 |
| 默认值 | 使用 `.default()` 提供安全的默认值 |
| 可选链 | 使用 `.optional()` 明确可选字段 |
---
## 数据验证与 Schema
### 相关页面
相关主题：[协议与类型定义](#page-3), [服务器开发指南](#page-6)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/src/util/zodCompat.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/util/zodCompat.ts)
- [packages/core/src/util/standardSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/util/standardSchema.ts)
- [packages/core/src/validators/fromJsonSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/validators/fromJsonSchema.ts)
- [packages/core/src/validators/ajvProvider.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/validators/ajvProvider.ts)
- [packages/core/src/util/schema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/util/schema.ts)
- [packages/server/src/server/completable.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/completable.ts)
- [packages/core/src/types/specTypeSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/specTypeSchema.ts)
# 数据验证与 Schema
## 概述
MCP TypeScript SDK 提供了一套完整的 Schema 验证体系，支持多种 Schema 定义方式。该系统允许开发者使用任意实现了 [Standard Schema 规范](https://standardschema.dev/) 的验证库来定义工具（Tool）、提示（Prompt）和资源的输入输出结构。
SDK 的验证架构基于以下核心原则：
- **标准化接口**：使用 `StandardSchemaV1` 接口统一不同验证库的行为
- **多库支持**：原生支持 Zod v4、Valibot、ArkType 等主流验证库
- **JSON Schema 桥接**：通过 `fromJsonSchema` 适配器支持纯 JSON Schema
- **向后兼容**：保留 Zod v3 的部分兼容层
资料来源：[packages/core/src/util/standardSchema.ts:1-50]()
## 架构图
```mermaid
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 必须实现的标准化方法：
```typescript
interface StandardSchemaV1 {
'~standard': {
version: 1;
vendor: string;
jsonSchema?: StandardJSONSchemaV1;
validate?: (value: unknown) => StandardSchemaV1.Result;
};
}
```
资料来源：[packages/core/src/util/standardSchema.ts:1-30]()
### 标准 Schema 工具函数
SDK 提供了两个核心工具函数用于处理 Standard Schema：
| 函数 | 作用 | 参数 |
|------|------|------|
| `standardSchemaToJsonSchema()` | 将 Standard Schema 转换为 JSON Schema | `schema`, `io` ('input' \| 'output') |
| `validateStandardSchema()` | 验证数据是否符合 Schema | `schema`, `data` |
`standardSchemaToJsonSchema` 函数支持从多种 Schema 库提取 JSON Schema 表示：
```typescript
export function standardSchemaToJsonSchema(
schema: StandardJSONSchemaV1,
io: 'input' | 'output' = 'input'
): Record {
const std = schema['~standard'];
let result: Record;
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 版本差异：
```typescript
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]()
### 版本兼容策略
| Zod 版本 | 支持状态 | 说明 |
|----------|----------|------|
| Zod v4 (>= 4.2.0) | ✅ 原生支持 | 实现 `~standard.jsonSchema` 接口 |
| Zod v4 (< 4.2.0) | ⚠️ 回退支持 | 回退到 `z.toJSONSchema()` |
| Zod v3 | ❌ 不支持 | 无法转换为 JSON Schema |
> 注意：SDK 已将 `zod` 从 `peerDependencies` 移除，保留为直接依赖。用户无需单独安装 Zod。
资料来源：[packages/client/CHANGELOG.md](), [packages/core/src/util/standardSchema.ts:30-40]()
## JSON Schema 支持
### fromJsonSchema 适配器
对于使用纯 JSON Schema 的场景（如 TypeBox 输出），SDK 提供了 `fromJsonSchema` 适配器：
```typescript
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](https://ajv.js.org/) 的 JSON Schema 验证器实现：
```typescript
export class AjvJsonSchemaValidator implements jsonSchemaValidator {
private _ajv: Ajv;
getValidator(schema: JsonSchemaType): ValidatorFn {
const validate = this._ajv.compile(schema);
return (data: unknown): ValidationResult => {
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`：
```typescript
// 使用 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 定义方式：
```typescript
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" 语法——直接传递字段定义对象而无需显式包装：
```typescript
// 标准方式
server.registerTool('tool1', {
inputSchema: z.object({ name: z.string() })
}, handler);
// Raw Shape 方式 (自动包装)
server.registerTool('tool2', {
inputSchema: { name: z.string() } // 自动变成 z.object({...})
}, handler);
```
内部通过 `normalizeRawShapeSchema()` 函数实现自动包装：
```typescript
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 字段添加自动补全功能：
```typescript
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 基础上添加了补全元数据：
```typescript
export type CompletableSchema = T & {
[COMPLETABLE_SYMBOL]: CompletableMeta;
};
```
资料来源：[packages/server/src/server/completable.ts:20-50]()
## 内置 Schema 类型
### 协议类型定义
MCP SDK 使用 Zod v4 定义了所有协议消息类型：
```typescript
type SpecTypeInputs = {
[K in SchemaKey as StripSchemaSuffix]: SchemaFor extends z.ZodType
? z.input>
: never;
};
type SpecTypes = {
[K in SchemaKey as StripSchemaSuffix]: SchemaFor extends z.ZodType
? z.output>
: never;
};
```
通过 `register()` 函数批量注册所有规范类型：
```typescript
for (const key of SPEC_SCHEMA_KEYS) {
register(key, schemas[key]);
}
```
资料来源：[packages/core/src/types/specTypeSchema.ts:20-50]()
### 常用类型列表
| 类型 | 用途 | Schema |
|------|------|--------|
| `CallToolRequest` | 工具调用请求 | CallToolRequestSchema |
| `CallToolResult` | 工具调用结果 | CallToolResultSchema |
| `GetPromptRequest` | 获取提示请求 | GetPromptRequestSchema |
| `Resource` | 资源定义 | ResourceSchema |
| `Prompt` | 提示定义 | PromptSchema |
完整类型列表参见 [packages/core/src/types/types.ts]()。
## 验证流程
### 数据验证时序
```mermaid
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 v4 或 ArkType（类型推断完善） |
| 已有 TypeBox 代码 | `fromJsonSchema` + `AjvJsonSchemaValidator` |
| 轻量级验证 | Valibot（Bundle 体积小） |
| 简单场景 | Raw Shape 语法 |
### 迁移指南
**从 Zod v3 迁移：**
```typescript
// 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：**
```typescript
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 配置选项
```typescript
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 协议的完全兼容。
---
## 传输层实现
### 相关页面
相关主题：[服务器开发指南](#page-6), [客户端开发指南](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/server/src/server/stdio.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/stdio.ts)
- [packages/server/src/server/streamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/streamableHttp.ts)
- [packages/client/src/client/stdio.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/stdio.ts)
- [packages/client/src/client/streamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/streamableHttp.ts)
- [packages/client/src/client/sse.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/sse.ts)
- [packages/middleware/node/src/streamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/src/streamableHttp.ts)
# 传输层实现
MCP TypeScript SDK 的传输层（Transport Layer）是客户端与服务器之间通信的核心抽象层，负责消息的发送、接收和协议处理。该层实现了多种传输协议，包括 Streamable HTTP、传统 SSE 以及 stdio 方式，以满足不同场景下的集成需求。
## 架构概览
传输层采用接口抽象设计，通过 `Transport` 接口定义统一的通信契约。不同的传输实现（如 HTTP、stdio）都遵循这一接口规范，使得上层业务逻辑与底层传输方式解耦。
```mermaid
graph TB
subgraph "客户端传输层"
C_STDIO[ClientStdioTransport]
C_HTTP[ClientStreamableHttpTransport]
C_SSE[ClientSseTransport]
end
subgraph "服务端传输层"
S_STDIO[ServerStdioTransport]
S_HTTP[ServerStreamableHttpTransport
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 接口契约
| 方法/属性 | 类型 | 描述 |
|-----------|------|------|
| `start()` | `Promise` | 启动传输层，开始监听/连接 |
| `send(message)` | `Promise` | 发送 JSON-RPC 消息 |
| `close()` | `Promise` | 关闭传输连接 |
| `onclose` | `() => void` | 连接关闭回调 |
| `onerror` | `(error: Error) => void` | 错误处理回调 |
| `onmessage` | `(message: JSONRPCMessage) => void` | 消息接收回调 |
| `onopen` | `() => void` | 连接打开回调 |
## Streamable HTTP 传输
Streamable HTTP 是 MCP SDK 推荐的主要传输协议，适用于远程服务器通信。该协议支持服务端发送（SSE）进行流式消息推送，同时兼容传统的请求-响应模式。
### 服务端实现
#### WebStandardStreamableHTTPServerTransport
`WebStandardStreamableHTTPServerTransport` 是核心的 Web 标准 HTTP 服务器传输实现，支持两种运行模式：
**有状态模式（Stateful）**：启用会话追踪，适用于需要维护状态的复杂应用场景。
```typescript
const transport = new WebStandardStreamableHTTPServerTransport({
sessionIdGenerator: () => crypto.randomUUID()
});
await server.connect(transport);
```
**无状态模式（Stateless）**：不维护会话状态，适合简单的 API 风格服务器。
```typescript
const transport = new WebStandardStreamableHTTPServerTransport({
sessionIdGenerator: undefined
});
```
资料来源：[packages/server/src/server/streamableHttp.ts:1-50]()
#### NodeStreamableHTTPServerTransport
`NodeStreamableHTTPServerTransport` 是针对 Node.js 环境优化的传输实现，内部封装了 `WebStandardStreamableHTTPServerTransport`，并使用 `getRequestListener` 将 Node.js HTTP 请求转换为 Web 标准请求。
```typescript
const transport = new NodeStreamableHTTPServerTransport(options);
app.all('/mcp', async c => {
return transport.handleRequest(c.req.raw);
});
```
该传输使用 `WeakMap` 存储每个请求的上下文信息，包括认证信息和解析后的请求体：
```typescript
private _requestContext: WeakMap = new WeakMap();
```
资料来源：[packages/middleware/node/src/streamableHttp.ts:1-80]()
### 客户端实现
`ClientStreamableHttpTransport` 实现了客户端侧的 Streamable HTTP 通信，支持与服务器的 SSE 消息流交互。
```mermaid
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 传输支持多种配置选项：
| 配置项 | 类型 | 默认值 | 描述 |
|--------|------|--------|------|
| `sessionIdGenerator` | `(() => string) \| undefined` | `() => crypto.randomUUID()` | 会话 ID 生成器，undefined 表示无状态模式 |
| `enableJsonResponse` | `boolean` | `false` | 启用纯 JSON 响应模式（禁用 SSE） |
| `authProvider` | `AuthProvider \| OAuthClientProvider` | `undefined` | 认证提供者 |
| `statusLevel` | `number` | `200` | 日志级别阈值 |
## Stdio 传输
Stdio（标准输入/输出）传输适用于本地进程集成场景，常见于本地 MCP 服务器或 CLI 工具集成。
```mermaid
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 消息，并通过标准输出发送响应。
```typescript
import { StdioServerTransport } from '@modelcontextprotocol/server';
const transport = new StdioServerTransport();
await server.connect(transport);
```
### 客户端 Stdio 传输
客户端 `StdioClientTransport` 通过子进程方式启动 MCP 服务器，通过 stdin/stdout 与服务器进程通信。
```typescript
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 的轮询机制，定期从服务器获取更新。
```typescript
const transport = new SSEClientTransport(
new URL('http://localhost:3000/mcp')
);
await client.connect(transport);
```
该传输包含以下核心功能：
| 功能 | 描述 |
|------|------|
| 消息队列 | 维护待处理消息队列 |
| 重试机制 | 连接失败时自动重试 |
| 心跳检测 | 定期发送心跳保持连接 |
## 中间件系统
客户端传输层支持中间件扩展，允许在请求/响应链中插入自定义逻辑。
### 日志中间件
`loggingMiddleware` 提供了请求/响应的详细日志记录功能：
```typescript
import { loggingMiddleware } from '@modelcontextprotocol/client';
const transport = new ClientStreamableHttpTransport(url, {
requestInit: {
headers: {
Authorization: `Bearer ${token}`
}
},
middlewares: [
loggingMiddleware({
includeRequestHeaders: true,
includeResponseHeaders: true,
statusLevel: 300
})
]
});
```
中间件接收和返回 `fetch` 风格的请求/响应，支持请求拦截和响应修改。
### 中间件管道
多个中间件可以组合成管道，按顺序执行：
```typescript
const composedMiddleware = composeFetchMiddlewares([middleware1, middleware2, middleware3]);
```
每个中间件的签名如下：
```typescript
type FetchMiddleware = (
next: FetchFn
) => (input: RequestInfo, init?: RequestInit) => Promise;
```
## 认证集成
传输层内置了对 OAuth 2.0 和 Bearer Token 认证的支持。
### AuthProvider 接口
```typescript
interface AuthProvider {
token(): Promise;
onUnauthorized?(ctx: AuthContext): Promise;
}
```
### Bearer Token 认证
简单的 Bearer Token 认证可以通过对象字面量实现：
```typescript
const transport = new ClientStreamableHttpTransport(url, {
authProvider: {
token: async () => myApiKey
}
});
```
### OAuth 认证
OAuth 客户端提供者会被传输自动适配，无需额外配置：
```typescript
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()` 进行重试。
## 使用示例
### 运行服务端示例
```bash
# 从仓库根目录运行
pnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts
# 或从包目录运行
cd examples/server
pnpm tsx src/simpleStreamableHttp.ts
```
### 运行客户端示例
```bash
# 客户端需要先启动服务器
pnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts
```
### 兼容模式客户端
向后兼容的客户端会优先尝试 Streamable HTTP，失败时回退到 SSE：
```typescript
// 使用 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 传输。
---
## 服务器开发指南
### 相关页面
相关主题：[客户端开发指南](#page-7), [认证与授权机制](#page-8)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/server/src/server/mcp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/mcp.ts)
- [packages/server/src/server/server.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/server.ts)
- [examples/server/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)
- [examples/server/src/simpleStreamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts)
- [docs/server.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md)
- [docs/server-quickstart.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server-quickstart.md)
# 服务器开发指南
## 概述
服务器开发指南旨在帮助开发者使用 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]()
## 架构设计
### 服务器层级结构
```mermaid
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
```
### 核心组件职责
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| McpServer | `packages/server/src/server/mcp.ts` | 提供工具、资源、提示的注册接口 |
| Server | `packages/server/src/server/server.ts` | 处理 JSON-RPC 协议、请求/响应关联 |
| Protocol | `packages/core/src/shared/protocol.ts` | 消息路由、能力协商、传输管理 |
资料来源：[CLAUDE.md:25-35]()
## 快速开始
### 环境准备
```bash
# 安装依赖
pnpm install
# 运行服务器示例
pnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts
```
### 基础服务器创建
```typescript
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()` 方法注册工具，支持两种调用形式：
```typescript
// 标准 Schema 形式
server.tool(
name: string,
description: string,
argsSchema: T,
cb: ToolCallback
): RegisteredTool
// 废弃的 Zod Raw Shape 形式（自动包装为 z.object()）
server.tool(
name: string,
description: string,
argsSchema: T,
cb: LegacyToolCallback
): RegisteredTool
```
### 工具注册参数
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | 工具唯一标识名 |
| description | string | 是 | 工具功能描述 |
| argsSchema | ZodSchema/ZodRawShape | 是 | 参数验证 Schema |
| cb | ToolCallback | 是 | 工具执行回调函数 |
资料来源：[packages/server/src/server/mcp.ts:150-180]()
### 工具动态管理
注册后的工具返回 `RegisteredTool` 对象，支持运行时动态更新：
```typescript
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`，系统会自动重新生成执行器：
```typescript
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 参数化的动态资源
### 注册静态资源
```typescript
server.resource(
"config",
"app://config",
(uri: URL) => {
return {
contents: [{
uri: uri.toString(),
mimeType: "application/json",
text: JSON.stringify({ theme: "dark", language: "zh" })
}]
};
}
);
```
### 注册资源模板
```typescript
server.resourceTemplate(
"user-profile",
"users://{userId}/profile",
({ userId }: { userId: string }) => {
return {
contents: [{
uri: `users://${userId}/profile`,
mimeType: "application/json",
text: fetchUserProfile(userId)
}]
};
}
);
```
### 资源生命周期管理
| 方法 | 说明 |
|------|------|
| `disable()` | 禁用资源（仍保留但不可访问） |
| `enable()` | 启用资源 |
| `remove()` | 移除资源 |
| `update(updates)` | 更新资源属性 |
资源更新后自动发送 `resourceListChanged` 通知：
```typescript
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
```typescript
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}`
}
}]
})
);
```
### 提示参数
| 参数 | 类型 | 说明 |
|------|------|------|
| name | string | 提示唯一标识 |
| config.title | string | 显示标题 |
| config.description | string | 功能描述 |
| config.argsSchema | ZodSchema | 参数验证 Schema |
| cb | PromptCallback | 返回消息数组的异步函数 |
资料来源：[packages/server/src/server/mcp.ts:180-210]()
## 服务器运行模式
### Streamable HTTP 模式（有状态）
适用于需要会话跟踪、任务管理的复杂服务器：
```typescript
import { StreamableHTTPTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
const transport = new StreamableHTTPTransport({
sessionIdGenerator: () => crypto.randomUUID(),
});
await server.connect(transport);
```
### Streamable HTTP 模式（无状态）
适用于简单的 API 风格服务器，无会话跟踪：
```typescript
import { StreamableHTTPTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
const transport = new StreamableHTTPTransport();
await server.connect(transport);
```
### JSON 响应模式
仅使用 JSON 响应，不支持 SSE：
```typescript
import { JSONResponseStreamableHttpTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
const transport = new JSONResponseStreamableHttpTransport();
await server.connect(transport);
```
资料来源：[examples/server/README.md:25-45]()
## 错误处理
### SDK 错误码
```typescript
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]()
## 示例服务器索引
| 场景 | 描述 | 文件 |
|------|------|------|
| 有状态 Streamable HTTP | 功能丰富的服务器，支持工具/资源/提示、日志、任务、采样 | `src/simpleStreamableHttp.ts` |
| 无状态 Streamable HTTP | 无会话跟踪，适合简单 API 服务器 | `src/simpleStatelessStreamableHttp.ts` |
| 资源服务器 OAuth | 使用 `mcpAuthMetadataRouter` 的最小 OAuth RS | `src/resourceServerOnly.ts` |
| JSON 响应模式 | 仅 JSON 响应的 Streamable HTTP | `src/jsonResponseStreamableHttp.ts` |
资料来源：[examples/server/README.md:28-40]()
## 下一步
- 查看 [客户端开发指南](./client.md) 了解如何连接到此服务器
- 阅读 [协议规范文档](./protocol.md) 深入理解底层协议
- 参考 [示例代码库](../examples/server/) 获取完整实现
---
## 客户端开发指南
### 相关页面
相关主题：[服务器开发指南](#page-6), [Web 框架中间件集成](#page-9)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/client/src/client/client.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/client.ts)
- [examples/client/src/clientGuide.examples.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/clientGuide.examples.ts)
- [examples/client-quickstart/src/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client-quickstart/src/index.ts)
- [docs/client-quickstart.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/client-quickstart.md)
- [docs/client.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/client.md)
# 客户端开发指南
## 概述
MCP TypeScript SDK 的客户端开发模块位于 `packages/client` 包中，提供了与 MCP 服务器通信的完整能力。该模块基于核心协议层构建，封装了 JSON-RPC 消息处理、请求/响应关联、能力协商和传输层管理等功能。客户端支持 Streamable HTTP 传输协议，这是 MCP V2 规范定义的主要通信方式。
## 核心架构
### 客户端层次结构
MCP SDK 采用三层架构设计，客户端位于最上层：
| 层级 | 位置 | 职责 |
|------|------|------|
| 类型层 | `packages/core/src/types/types.ts` | 定义 MCP 协议的 TypeScript 类型和 Zod Schema |
| 协议层 | `packages/core/src/shared/protocol.ts` | 处理 JSON-RPC 路由、能力协商和消息分发 |
| 客户端层 | `packages/client/src/client/client.ts` | 提供面向用户的 MCP 操作接口 |
### 客户端与协议层关系
```mermaid
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
```
## 安装与配置
### 依赖安装
```bash
pnpm add @modelcontextprotocol/client
```
### 基本导入
```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';
```
## 客户端初始化
### 创建客户端实例
客户端初始化需要提供服务器能力信息和连接配置：
```typescript
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: {}
}
}
);
```
### 连接到服务器
```typescript
await client.connect(transport);
```
连接过程会触发服务器能力协商，确认双方支持的 MCP 功能范围。
## 核心功能
### 工具调用
工具是 MCP 服务器暴露的可执行函数，客户端可以调用这些工具获取计算结果或执行特定操作。
```mermaid
sequenceDiagram
客户端->>服务器: 调用工具 (tools/call)
服务器->>服务器: 执行工具逻辑
服务器-->>客户端: 工具结果
```
#### 调用单个工具
```typescript
const result = await client.callTool({
name: 'calculate',
arguments: { expression: '2 + 2' }
});
```
#### 并行调用多个工具
```typescript
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 } })
]);
```
### 资源管理
资源是服务器提供的只读数据源，客户端可以列出、读取和订阅资源变更通知。
#### 列出可用资源
```typescript
const resourceList = await client.listResources();
for (const resource of resourceList.resources) {
console.log(`${resource.name}: ${resource.uri}`);
}
```
#### 读取资源内容
```typescript
const resourceContent = await client.readResource({
uri: 'file:///config/app.json'
});
```
#### 订阅资源变更
```typescript
await client.subscribeResource({ uri: 'file:///config/app.json' });
// 设置资源更新处理器
client.setRequestHandler(ResourceUpdatedNotificationSchema, (notification) => {
console.log('资源已更新:', notification.params.uri);
return Promise.resolve();
});
```
### 提示模板
提示模板允许服务器定义可参数化的消息模板，客户端可以获取并使用这些模板。
#### 列出可用提示
```typescript
const promptList = await client.listPrompts();
```
#### 获取提示内容
```typescript
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 模型的调用。
```typescript
const sample = await client.createMessage({
messages: [{ role: 'user', content: { type: 'text', text: 'Hello' } }],
systemPrompt: 'You are a helpful assistant.',
maxTokens: 100
});
```
## 认证机制
### AuthProvider 接口
SDK 提供了灵活的认证机制，通过 `AuthProvider` 接口实现可组合的认证功能：
```typescript
interface AuthProvider {
token(): Promise;
onUnauthorized?(ctx: AuthorizationCtx): Promise;
}
```
### 简单Bearer Token认证
对于简单的 API 密钥或网关管理的令牌，可以使用对象字面量：
```typescript
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` 提供，传输层会自动适配：
```typescript
import { adaptOAuthProvider } from '@modelcontextprotocol/sdk/client/auth.js';
const oauthProvider = new MyOAuthProvider(config);
await client.connect(transport, {
authProvider: adaptOAuthProvider(oauthProvider)
});
```
认证流程如下：
```mermaid
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 版本的主要传输协议，支持服务端推送和流式响应：
```typescript
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 轮询模式：
```typescript
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);
```
## 错误处理
### 连接错误
```typescript
try {
await client.connect(transport);
} catch (error) {
if (error instanceof ConnectionError) {
console.error('连接失败:', error.message);
}
}
```
### 请求错误
```typescript
try {
const result = await client.callTool({
name: 'risky-operation',
arguments: {}
});
} catch (error) {
if (error instanceof ToolExecutionError) {
console.error('工具执行错误:', error.message);
}
}
```
## 完整示例
### 交互式客户端
以下示例展示了完整的客户端使用流程：
```typescript
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);
```
### 带认证的客户端
```typescript
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` 模块导出：
```typescript
import { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/client/experimental';
// 任务存储配置
const taskStore = new InMemoryTaskStore();
```
## 最佳实践
| 实践 | 说明 |
|------|------|
| 单一职责 | 每个客户端实例专注于一个服务器连接 |
| 错误处理 | 始终使用 try-catch 包装异步操作 |
| 资源清理 | 使用完毕后调用 `client.close()` |
| 认证管理 | 将令牌刷新逻辑放在 `onUnauthorized` 回调中 |
| 类型安全 | 使用 Zod Schema 验证工具参数 |
## 相关资源
- [MCP 规范文档](https://modelcontextprotocol.io/specification/latest)
- [服务器开发指南](./server.md)
- [客户端快速开始](./client-quickstart.md)
- [examples/client](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/client)
---
## 认证与授权机制
### 相关页面
相关主题：[Web 框架中间件集成](#page-9), [实验性功能与任务系统](#page-10)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/src/shared/auth.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/shared/auth.ts)
- [packages/core/src/shared/authUtils.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/shared/authUtils.ts)
- [packages/client/src/client/auth.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/auth.ts)
- [packages/client/src/client/authExtensions.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/authExtensions.ts)
- [packages/client/src/client/crossAppAccess.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/crossAppAccess.ts)
- [packages/middleware/express/src/auth/bearerAuth.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/src/auth/bearerAuth.ts)
# 认证与授权机制
## 概述
MCP TypeScript SDK 提供了一套完整的认证与授权机制，支持多种认证方式，包括 Bearer Token 认证、OAuth 2.0 认证以及可组合的自定义认证提供者。该机制设计为传输层无关，可与 Streamable HTTP、SSE 等传输协议配合使用，为 MCP 客户端和服务器之间的安全通信提供保障。
认证系统的核心设计理念是通过统一的 `AuthProvider` 接口抽象不同的认证方式，使得开发者可以根据实际需求选择或组合使用 Bearer Token、OAuth 等认证策略。资料来源：[packages/client/CHANGELOG.md]()
## 核心架构
### 认证提供者体系
MCP SDK 的认证体系采用分层架构设计，核心包含以下组件：
| 组件 | 文件位置 | 职责 |
|------|----------|------|
| AuthProvider | packages/core/src/shared/auth.ts | 认证提供者核心接口 |
| OAuthClientProvider | packages/client/src/client/auth.ts | OAuth 客户端实现 |
| BearerAuthMiddleware | packages/middleware/express/src/auth/bearerAuth.ts | Bearer Token 中间件 |
| adaptOAuthProvider | packages/client/src/client/auth.ts | OAuth 适配器 |
资料来源：[packages/client/CHANGELOG.md](), [packages/core/src/shared/auth.ts]()
### 认证流程架构图
```mermaid
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` 是认证系统的核心接口，定义了两个关键方法：
```typescript
export interface AuthProvider {
token(): Promise;
onUnauthorized?(ctx): Promise;
}
```
| 方法 | 返回类型 | 说明 |
|------|----------|------|
| token | Promise | 返回认证令牌，若返回 undefined 则跳过认证 |
| onUnauthorized | Promise (可选) | 收到 401 响应时的回调，可用于重新认证 |
资料来源：[packages/client/CHANGELOG.md]()
### Bearer Token 认证方式
对于简单的场景，可以使用对象字面量形式快速配置 Bearer Token：
```typescript
const client = createClient({
authProvider: {
token: async () => myApiKey
}
});
```
这种方式的优点是配置简洁，无需创建类实例，适合 API Key、网关托管令牌等场景。资料来源：[packages/client/CHANGELOG.md]()
## OAuth 认证
### OAuthClientProvider
SDK 提供了完整的 OAuth 客户端认证支持：
```typescript
export interface OAuthClientProvider {
// OAuth 认证核心方法
auth(provider: {
serverUrl: string;
resourceMetadataUrl?: string;
scope?: string;
fetchFn: typeof fetch;
}): Promise<'REDIRECT' | 'AUTHORIZED' | 'UNAUTHORIZED'>;
}
```
资料来源：[packages/client/CHANGELOG.md]()
### OAuth 认证流程
```mermaid
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()` 函数进行适配，无需修改现有代码：
```typescript
import { adaptOAuthProvider } from '@modelcontextprotocol/client';
// 适配已有的 OAuth 提供者
const adaptedProvider = adaptOAuthProvider(existingOAuthProvider);
```
资料来源：[packages/client/CHANGELOG.md]()
## Bearer 认证中间件
### bearerAuthMiddleware
Express 中间件实现了 Bearer Token 认证验证逻辑：
```typescript
export function bearerAuthMiddleware(
options: BearerAuthOptions
): RequestHandler {
// 实现 Bearer Token 验证逻辑
}
```
| 配置项 | 类型 | 必填 | 说明 |
|--------|------|------|------|
| token | string \| () => string \| Promise | 是 | Bearer Token 或返回 Token 的函数 |
| realm | string | 否 | 认证域，用于 WWW-Authenticate 头 |
| prefix | string | 否 | Token 前缀，默认为 'Bearer ' |
| skip | (req: Request) => boolean | 否 | 跳过认证的条件函数 |
资料来源：[packages/middleware/express/src/auth/bearerAuth.ts]()
### requireBearerAuth 工具函数
中间件导出 `requireBearerAuth` 函数用于简化认证配置：
```typescript
const { bearerAuthMiddleware, requireBearerAuth } = createBearerAuth({
token: () => process.env.BEARER_TOKEN
});
```
资料来源：[packages/middleware/express/src/auth/bearerAuth.ts]()
## 资源访问控制
### URL 路径匹配
`authUtils.ts` 提供了资源访问控制的核心工具函数 `matchesResource`：
```typescript
export function matchesResource(requestedResource: URL | string, configuredResource: URL | string): boolean
```
该函数通过以下规则判断请求的资源是否在允许范围内：
| 匹配条件 | 说明 |
|----------|------|
| Origin 匹配 | 协议、域名和端口必须一致 |
| 路径前缀匹配 | 请求路径必须以配置的路径开头 |
| 尾部斜杠处理 | 智能处理带斜杠和不带斜杠的路径 |
```typescript
// 路径匹配示例
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]()
### 资源匹配逻辑详解
```mermaid
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` 工厂函数用于创建自定义认证中间件：
```typescript
export function createMiddleware(
handler: (next: typeof fetch, input: RequestInfo, init?: RequestInit) => Promise
): MiddlewareFunction
```
资料来源：[packages/client/src/client/middleware.ts]()
### 认证中间件工作流程
```mermaid
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[终止流程]
```
### 中间件示例
**自定义认证中间件：**
```typescript
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;
});
```
**条件认证中间件：**
```typescript
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` 实现了跨应用程序访问的认证机制，支持对特定资源路径的细粒度访问控制：
```typescript
export interface CrossAppAccessAuth {
validateCrossAppRequest(requestedResource: string): Promise;
}
```
| 功能 | 说明 |
|------|------|
| 路径验证 | 验证请求的资源路径是否符合配置 |
| 跨域控制 | 防止跨应用的未授权访问 |
| 前缀匹配 | 支持目录级别的访问控制 |
资料来源：[packages/client/src/client/crossAppAccess.ts]()
## 日志记录
### RequestLogger
认证系统支持详细的日志记录，便于调试和审计：
```typescript
export type RequestLogger = (input: {
method: string;
url: string | URL;
status: number;
statusText: string;
duration: number;
requestHeaders?: Headers;
responseHeaders?: Headers;
error?: Error;
}) => void;
```
| 字段 | 类型 | 说明 |
|------|------|------|
| method | string | HTTP 方法 |
| url | string \| URL | 请求 URL |
| status | number | 响应状态码 |
| statusText | string | 响应状态文本 |
| duration | number | 请求耗时（毫秒） |
| requestHeaders | Headers | 请求头 |
| responseHeaders | Headers | 响应头 |
| error | Error | 错误对象（若有） |
资料来源：[packages/client/src/client/middleware.ts]()
## Session 管理
### Session Cookie 处理
认证服务器使用 Cookie 机制管理用户会话：
```typescript
function getUserSessionCookie(cookieHeader?: string): {
userId: string;
name: string;
timestamp: number
} | null
```
该函数解析 `demo_session` Cookie 并返回用户会话信息。Cookie 存储的用户信息包括：
| 字段 | 类型 | 说明 |
|------|------|------|
| userId | string | 用户唯一标识 |
| name | string | 用户名称 |
| timestamp | number | 会话创建时间戳 |
资料来源：[examples/shared/src/authServer.ts]()
### 认证流程中的 Session 处理
```mermaid
graph LR
A[用户登录] --> B[创建 Session]
B --> C[设置 Set-Cookie]
C --> D[浏览器存储 Cookie]
D --> E[后续请求自动携带 Cookie]
E --> F[服务端验证 Session]
```
## 最佳实践
### 认证配置建议
| 场景 | 推荐方案 |
|------|----------|
| 简单 API Key | 使用对象字面量 `authProvider: { token: async () => key }` |
| OAuth 认证 | 实现 `OAuthClientProvider` 并使用 `adaptOAuthProvider` |
| 多认证方式 | 实现自定义 `AuthProvider`，组合多种认证策略 |
| 资源访问控制 | 使用 `matchesResource` 进行路径验证 |
### 安全注意事项
1. **Token 存储**：避免在前端代码中硬编码敏感 Token
2. **HTTPS 传输**：确保所有认证请求通过 HTTPS 进行
3. **Token 刷新**：实现 `onUnauthorized` 回调处理 Token 过期
4. **错误处理**：妥善处理认证失败情况，避免信息泄露
资料来源：[packages/client/CHANGELOG.md](), [packages/middleware/express/src/auth/bearerAuth.ts]()
## 相关资源
- [认证与授权官方文档](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/auth.md)
- [Express 中间件示例](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/middleware/express)
- [OAuth 示例服务器](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/shared/src/authServer.ts)
---
## Web 框架中间件集成
### 相关页面
相关主题：[传输层实现](#page-5), [实验性功能与任务系统](#page-10)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/middleware/express/src/express.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/src/express.ts)
- [packages/middleware/hono/src/hono.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/src/hono.ts)
- [packages/middleware/fastify/src/fastify.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/src/fastify.ts)
- [packages/middleware/express/src/middleware/hostHeaderValidation.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/src/middleware/hostHeaderValidation.ts)
- [packages/middleware/hono/src/middleware/hostHeaderValidation.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/src/middleware/hostHeaderValidation.ts)
- [packages/middleware/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/README.md)
# Web 框架中间件集成
## 概述
Model Context Protocol (MCP) TypeScript SDK 提供了与主流 Web 框架的中间件集成支持，使开发者能够将 MCP 服务器无缝嵌入到现有的 Express、Hono 和 Fastify 应用中。这些中间件适配器充当 MCP 传输层与 Web 框架之间的桥梁，实现了标准化的请求处理和响应流式传输机制。
中间件集成的核心价值在于：开发者无需构建独立的 MCP 服务器进程，而是可以直接在现有的 Web 应用中暴露 MCP 工具、资源和提示词功能。这种架构模式特别适合需要将 MCP 功能与现有 API 服务、认证中间件、日志系统等组件整合的场景。
## 架构设计
### 整体架构
MCP Web 框架中间件采用了适配器模式设计，每种框架都有对应的传输层实现。中间件负责接收框架的 HTTP 请求，将其转换为 MCP 协议消息，然后调用底层 MCP 服务器处理逻辑，最终将处理结果以框架兼容的方式返回给客户端。
```mermaid
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 框架：
| 包名 | 功能 | 传输类型 |
|------|------|----------|
| `@modelcontextprotocol/express` | Express.js 框架集成 | Streamable HTTP |
| `@modelcontextprotocol/hono` | Hono 框架集成 | Streamable HTTP |
| `@modelcontextprotocol/fastify` | Fastify 框架集成 | Streamable HTTP |
每个中间件包都包含核心适配器模块和安全验证中间件两个部分。核心适配器负责处理 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 中间件添加到应用中：
```typescript
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 的标准中间件机制注册：
```typescript
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 验证集成
- 流式响应处理
### 使用方式
```typescript
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 规范中定义的标准传输方式，支持：
| 特性 | 说明 |
|------|------|
| 请求-响应模式 | 标准 HTTP POST 请求，JSON-RPC 响应 |
| 流式响应 | 支持 Server-Sent Events 格式的流式消息 |
| 会话管理 | 通过会话标识符维护状态 |
| 心跳机制 | 保持连接活跃 |
### 请求处理流程
```mermaid
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 验证或自定义会话验证。
## 配置选项
### 通用配置
| 选项 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `transport` | `string` | `'streamable-http'` | 传输协议类型 |
| `mode` | `'stateful' \| 'stateless'` | `'stateful'` | 会话管理模式 |
| `maxSessions` | `number` | 1000 | 最大并发会话数（状态ful模式） |
| `sessionTimeout` | `number` | 300000 | 会话超时时间（毫秒） |
### 状态ful 与无状态模式
**状态ful 模式**维护会话状态，允许跨请求保持上下文：
- 适合需要维护状态的复杂交互
- 支持长连接和持久化上下文
- 需要配置会话存储
**无状态模式**每次请求独立处理：
- 适合简单的工具调用场景
- 更易于水平扩展
- 无需会话管理开销
## 与示例代码的对应关系
`examples/server/README.md` 中列出的示例演示了这些中间件的实际应用：
| 场景 | 描述 | 框架 |
|------|------|------|
| 状态ful Streamable HTTP 服务器 | 完整的工具/资源/提示词功能 | Express |
| 无状态 Streamable HTTP 服务器 | 简化 API 式服务 | Express |
| 资源服务器认证 | OAuth RS + Bearer 认证 | Express |
这些示例位于 `examples/server/src/` 目录，展示了从简单的服务器配置到复杂的认证集成的完整使用方式。
## 最佳实践
### 生产环境部署
1. **安全配置**：始终在 MCP 中间件之前配置认证和主机头验证中间件
2. **会话管理**：根据应用场景选择合适的状态管理模式
3. **超时设置**：合理配置请求超时和会话超时
4. **错误处理**：实现统一的错误处理中间件，确保错误信息正确返回
### 性能优化
1. **路由前缀**：使用明确的路由前缀避免与其他 API 冲突
2. **中间件顺序**：将 MCP 中间件放在合适的路由层级
3. **会话限制**：在状态ful 模式下设置合理的最大会话数
## 总结
MCP TypeScript SDK 的 Web 框架中间件集成提供了强大而灵活的解决方案，使开发者能够将 Model Context Protocol 无缝嵌入到任何基于 Express、Hono 或 Fastify 的应用中。通过统一的适配器接口和安全组件，中间件系统确保了跨框架的一致性体验，同时充分发挥了各框架的独特优势。
---
## 实验性功能与任务系统
### 相关页面
相关主题：[服务器开发指南](#page-6), [客户端开发指南](#page-7)
相关源码文件
以下源码文件用于生成本页说明：
- [packages/core/src/experimental/tasks/interfaces.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/interfaces.ts)
- [packages/core/src/experimental/tasks/helpers.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/helpers.ts)
- [packages/core/src/experimental/tasks/stores/inMemory.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/stores/inMemory.ts)
- [packages/server/src/experimental/tasks/server.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/tasks/server.ts)
- [packages/client/src/experimental/tasks/client.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/experimental/tasks/client.ts)
- [packages/client/src/shimsBrowser.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/shimsBrowser.ts)
- [packages/client/src/shimsWorkerd.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/shimsWorkerd.ts)
# 实验性功能与任务系统
## 概述
MCP TypeScript SDK 提供了一套实验性的任务系统（Task System），允许服务器和客户端管理异步长时运行任务。这些任务可以通过唯一标识符进行追踪、查询和取消操作。
实验性功能通过 `@modelcontextprotocol/sdk/experimental` 模块导出，使用前需注意：
> ⚠️ **警告**：这些 API 是实验性的，可能会在没有任何通知的情况下发生变化。
```typescript
import { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';
```
资料来源：[packages/server/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)
---
## 架构设计
### 组件关系图
```mermaid
graph TD
subgraph 客户端层
ClientTaskAPI["ClientTaskApi"]
TaskStore["TaskStore"]
end
subgraph 服务端层
ServerTaskAPI["ServerTaskApi"]
TaskModule["TaskModule"]
end
subgraph 传输层
Transport["Transport Layer"]
end
ClientTaskAPI -->|JSON-RPC| Transport
Transport -->|JSON-RPC| ServerTaskAPI
ServerTaskAPI --> TaskModule
ClientTaskAPI --> TaskStore
TaskModule -.->|状态存储| TaskStore
```
### 核心模块结构
| 模块 | 位置 | 职责 |
|------|------|------|
| `interfaces.ts` | `packages/core/src/experimental/tasks/` | 定义任务接口和数据模型 |
| `helpers.ts` | `packages/core/src/experimental/tasks/` | 提供任务相关辅助函数 |
| `inMemory.ts` | `packages/core/src/experimental/tasks/stores/` | 实现内存任务存储 |
| `client.ts` | `packages/client/src/experimental/tasks/` | 客户端任务 API |
| `server.ts` | `packages/server/src/experimental/tasks/` | 服务端任务 API |
---
## 服务端任务 API
### ServerTaskApi 类
`ServerTaskApi` 封装了服务端处理任务的核心方法。
资料来源：[packages/server/src/experimental/tasks/server.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/tasks/server.ts)
### 核心方法
#### getTaskResult
获取指定任务的执行结果。
```typescript
async getTaskResult(
taskId: string,
options?: RequestOptions
): Promise
```
| 参数 | 类型 | 描述 |
|------|------|------|
| `taskId` | `string` | 任务唯一标识符 |
| `options` | `RequestOptions` | 可选的请求配置 |
**返回值**：`GetTaskPayloadResult` 类型的 Promise，封装了任务的执行结果（如工具调用返回的 `CallToolResult`）。
资料来源：[packages/server/src/experimental/tasks/server.ts:20-26]()
#### listTasks
列出所有任务，支持分页查询。
```typescript
async listTasks(
cursor?: string,
options?: RequestOptions
): Promise
```
| 参数 | 类型 | 描述 |
|------|------|------|
| `cursor` | `string` | 可选的分页游标 |
| `options` | `RequestOptions` | 可选的请求配置 |
**返回值**：`ListTasksResult` 包含任务列表和可选的下一页游标。
资料来源：[packages/server/src/experimental/tasks/server.ts:34-43]()
#### cancelTask
取消一个正在运行的任务。
```typescript
async cancelTask(
taskId: string,
options?: RequestOptions
): Promise
```
| 参数 | 类型 | 描述 |
|------|------|------|
| `taskId` | `string` | 要取消的任务标识符 |
| `options` | `RequestOptions` | 可选的请求配置 |
**返回值**：`CancelTaskResult` 表示取消操作的结果。
资料来源：[packages/server/src/experimental/tasks/server.ts:52-60]()
---
## 客户端任务 API
### ClientTaskApi 类
客户端通过 `ClientTaskApi` 与服务端的任务系统进行交互。
资料来源：[packages/client/src/experimental/tasks/client.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/experimental/tasks/client.ts)
### 浏览器与 Workerd 适配
客户端支持多种运行环境，通过不同的 shim 文件提供适配：
| 环境 | Shim 文件 | 用途 |
|------|----------|------|
| 浏览器 | `packages/client/src/shimsBrowser.ts` | 浏览器环境适配 |
| Workerd | `packages/client/src/shimsWorkerd.ts` | Cloudflare Workerd 环境适配 |
资料来源：[packages/client/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/experimental/index.ts)
---
## 任务存储
### TaskStore 接口
任务存储定义了任务状态管理的基本接口。
资料来源：[packages/core/src/experimental/tasks/interfaces.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/interfaces.ts)
### InMemoryTaskStore
默认提供的内存实现，适用于单进程场景。
```typescript
import { InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';
const taskStore = new InMemoryTaskStore();
```
特点：
- 数据存储在内存中，进程重启后会丢失
- 适合开发、测试或单实例部署
- 性能最优，无需序列化/反序列化开销
资料来源：[packages/core/src/experimental/tasks/stores/inMemory.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/stores/inMemory.ts)
### 自定义存储实现
可通过实现 `TaskStore` 接口创建自定义存储：
```typescript
interface TaskStore {
get(taskId: string): Promise;
set(taskId: string, task: Task): Promise;
delete(taskId: string): Promise;
list(cursor?: string): Promise;
}
```
资料来源：[packages/core/src/experimental/tasks/interfaces.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/interfaces.ts)
---
## 辅助函数
### helpers.ts
提供任务创建、验证、序列化等辅助功能。
资料来源：[packages/core/src/experimental/tasks/helpers.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/helpers.ts)
### 常用辅助函数
| 函数 | 功能 |
|------|------|
| `createTask()` | 创建新任务实例 |
| `validateTaskId()` | 验证任务标识符格式 |
| `serializeTask()` | 序列化任务数据 |
| `deserializeTask()` | 反序列化任务数据 |
---
## 使用工作流
### 创建并追踪任务
```mermaid
sequenceDiagram
participant Client as 客户端
participant Server as 服务端
participant Store as 任务存储
Client->>Server: 发起需要长时间执行的操作
Server->>Store: 创建任务记录
Server-->>Client: 返回 taskId
loop 任务执行中
Client->>Server: getTaskResult(taskId)
Server->>Store: 查询任务状态
Store-->>Server: 返回任务结果
Server-->>Client: 返回 GetTaskPayloadResult
end
Client->>Server: cancelTask(taskId)
Server->>Store: 更新任务状态为已取消
Server-->>Client: 返回 CancelTaskResult
```
### 完整示例
```typescript
import { Client } from '@modelcontextprotocol/sdk/client';
import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp';
import { ClientTaskApi } from '@modelcontextprotocol/sdk/experimental';
// 初始化客户端
const transport = new StreamableHTTPClientTransport('http://localhost:3000/mcp');
const client = new Client({ name: 'example-client', version: '1.0.0' });
await client.connect(transport);
// 创建任务 API 实例
const taskApi = new ClientTaskApi(client);
// 获取任务结果
const result = await taskApi.getTaskResult('task-123');
console.log(result);
// 列出所有任务
const { tasks, nextCursor } = await taskApi.listTasks();
// 取消任务
await taskApi.cancelTask('task-456');
```
---
## 类型定义
### 核心类型
| 类型 | 描述 |
|------|------|
| `Task` | 任务数据模型 |
| `TaskId` | 任务唯一标识符 |
| `GetTaskPayloadResult` | 任务结果载荷 |
| `ListTasksResult` | 任务列表结果 |
| `CancelTaskResult` | 取消操作结果 |
| `RequestOptions` | 请求配置选项 |
资料来源：[packages/core/src/types/types.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/types.ts)
---
## 最佳实践
### 1. 错误处理
始终对任务操作进行错误处理：
```typescript
try {
const result = await taskApi.getTaskResult(taskId);
} catch (error) {
if (error.code === 'TASK_NOT_FOUND') {
console.error('任务不存在:', taskId);
} else {
throw error;
}
}
```
### 2. 任务超时管理
建议设置合理的请求超时：
```typescript
const result = await taskApi.getTaskResult(taskId, {
timeout: 30000, // 30秒超时
signal: AbortSignal.timeout(30000)
});
```
### 3. 进度追踪
对于长时间运行的任务，定期轮询状态：
```typescript
async function waitForCompletion(taskId: string, interval = 1000) {
while (true) {
const result = await taskApi.getTaskResult(taskId);
if (result.status === 'completed') {
return result;
}
if (result.status === 'failed') {
throw new Error(`任务失败: ${result.error}`);
}
await new Promise(resolve => setTimeout(resolve, interval));
}
}
```
---
## 注意事项
1. **实验性警告**：所有任务系统 API 均为实验性，可能在后续版本中发生不兼容变更。
2. **状态持久化**：`InMemoryTaskStore` 不支持持久化，进程重启后任务状态会丢失。如需持久化，请实现自定义存储。
3. **并发限制**：大量并发任务可能影响性能，建议实现适当的限流机制。
4. **资源清理**：任务完成后应及时调用 `cancelTask` 或清理过期任务，避免内存泄漏。
---
## 相关资源
- [MCP 协议规范](https://modelcontextprotocol.io/specification)
- [服务端文档](../../docs/server.md)
- [客户端文档](../../docs/client.md)
- [Streamable HTTP 传输](../transports/streamableHttp.md)
---
---
## Doramagic 踩坑日志
项目：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/node@2.0.0-alpha.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/node@2.0.0-alpha.1
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_fc8de64b72814f8eb9ed0e53852408c2 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/node%402.0.0-alpha.1 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 4. 安装坑 · 来源证据：@modelcontextprotocol/server@2.0.0-alpha.1
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/server@2.0.0-alpha.1
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：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