{
"canonical_name": "modelcontextprotocol/typescript-sdk",
"compilation_id": "pack_6a9bfb035e114da1a0adb50602ef7b63",
"created_at": "2026-05-13T12:21:01.443594+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npm install @modelcontextprotocol/server` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npm install @modelcontextprotocol/server",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_0242e18e5aac4079a7a124f4a54ba209"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_8ee9d7e4a8ce4cfe91fe5150681c5a7f",
"canonical_name": "modelcontextprotocol/typescript-sdk",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/modelcontextprotocol/typescript-sdk",
"slug": "typescript-sdk",
"source_packet_id": "phit_486a69e713494e8e92659a14b1160ece",
"source_validation_id": "dval_8cca56272487449aa01d18df1fa47cf3"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 1835,
"github_stars": 12412,
"one_liner_en": "The official TypeScript SDK for Model Context Protocol servers and clients",
"one_liner_zh": "The official TypeScript SDK for Model Context Protocol servers and clients",
"primary_category": {
"category_id": "software-development",
"confidence": "high",
"name_en": "Software Development",
"name_zh": "软件开发与交付",
"reason": "matched_keywords:git, ci, cli"
},
"target_user": "使用 local_cli 等宿主 AI 的用户",
"title_en": "typescript-sdk",
"title_zh": "typescript-sdk 能力包",
"visible_tags": [
{
"label_en": "Security & Permissions",
"label_zh": "安全审查与权限治理",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-security-permissions",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Browser Automation",
"label_zh": "浏览器自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-browser-automation",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_486a69e713494e8e92659a14b1160ece",
"page_model": {
"artifacts": {
"artifact_slug": "typescript-sdk",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npm install @modelcontextprotocol/server",
"label": "Node.js / npm · 官方安装入口",
"source": "https://github.com/modelcontextprotocol/typescript-sdk#readme",
"verified": true
}
],
"display_tags": [
"安全审查与权限治理",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"评测体系"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "The official TypeScript SDK for Model Context Protocol servers and clients"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "local_cli",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：client code can't execute inside browser due to import spawn",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_8a06947266aa4987ad712baf87a7a156 | https://github.com/modelcontextprotocol/typescript-sdk/issues/2077 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：client code can't execute inside browser due to import spawn",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "仓库名 `typescript-sdk` 与安装入口 `@modelcontextprotocol/server` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | repo=typescript-sdk; install=@modelcontextprotocol/server"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/node@2.0.0-alpha.1",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_fc8de64b72814f8eb9ed0e53852408c2 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/node%402.0.0-alpha.1 | 来源讨论提到 node 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：@modelcontextprotocol/node@2.0.0-alpha.1",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/server@2.0.0-alpha.1",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_dff36a13cb954c3b84b05e99a28dc4d0 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.0.0-alpha.1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：@modelcontextprotocol/server@2.0.0-alpha.1",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "No sandbox install has been executed yet; downstream must verify before user use.",
"category": "安全/权限坑",
"evidence": [
"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."
],
"severity": "medium",
"suggested_check": "转成明确权限清单和安全审查提示。",
"title": "存在安全注意事项",
"user_impact": "用户安装前需要知道权限边界和敏感操作。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：运行坑 - 来源证据：client code can't execute inside browser due to import spawn。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 166,
"forks": 1835,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 12412
},
"source_url": "https://github.com/modelcontextprotocol/typescript-sdk",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "The official TypeScript SDK for Model Context Protocol servers and clients",
"title": "typescript-sdk 能力包",
"trial_prompt": "# typescript-sdk - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 typescript-sdk 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: The official TypeScript SDK for Model Context Protocol servers and clients 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：MCP TypeScript SDK 概述。围绕“MCP TypeScript SDK 概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构与包结构。围绕“系统架构与包结构”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：协议与类型定义。围绕“协议与类型定义”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：数据验证与 Schema。围绕“数据验证与 Schema”模拟一次用户任务，不展示安装或运行结果。\n5. page-5：传输层实现。围绕“传输层实现”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“MCP TypeScript SDK 概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构与包结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“协议与类型定义”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“数据验证与 Schema”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-5\n输入：用户提供的“传输层实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“MCP TypeScript SDK 概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构与包结构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“协议与类型定义”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“数据验证与 Schema”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-5：Step 5 必须围绕“传输层实现”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/modelcontextprotocol/typescript-sdk\n- https://github.com/modelcontextprotocol/typescript-sdk#readme\n- README.md\n- package.json\n- packages/core/src/index.ts\n- packages/server/package.json\n- packages/client/package.json\n- packages/middleware/node/package.json\n- pnpm-workspace.yaml\n- packages/core/src/types/spec.types.ts\n- packages/core/src/shared/protocol.ts\n- packages/core/src/types/types.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 typescript-sdk 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"voices": [
{
"body": "来源平台：github。github/github_issue: client code can't execute inside browser due to import spawn（https://github.com/modelcontextprotocol/typescript-sdk/issues/2077）；github/github_release: @modelcontextprotocol/server@2.0.0-alpha.2（https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.0.0-alpha.2）；github/github_release: @modelcontextprotocol/node@2.0.0-alpha.2（https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/node%402.0.0-alpha.2）；github/github_release: @modelcontextprotocol/hono@2.0.0-alpha.2（https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/hono%402.0.0-alpha.2）；github/github_release: @modelcontextprotocol/fastify@2.0.0-alpha.2（https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/fastify%402.0.0-alpha.2）；github/github_release: @modelcontextprotocol/express@2.0.0-alpha.2（https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/express%402.0.0-alpha.2）；github/github_release: @modelcontextprotocol/server@2.0.0-alpha.1（https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.0.0-alpha.1）；github/github_release: @modelcontextprotocol/node@2.0.0-alpha.1（https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/node%402.0.0-alpha.1）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "client code can't execute inside browser due to import spawn",
"url": "https://github.com/modelcontextprotocol/typescript-sdk/issues/2077"
},
{
"kind": "github_release",
"source": "github",
"title": "@modelcontextprotocol/server@2.0.0-alpha.2",
"url": "https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.0.0-alpha.2"
},
{
"kind": "github_release",
"source": "github",
"title": "@modelcontextprotocol/node@2.0.0-alpha.2",
"url": "https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/node%402.0.0-alpha.2"
},
{
"kind": "github_release",
"source": "github",
"title": "@modelcontextprotocol/hono@2.0.0-alpha.2",
"url": "https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/hono%402.0.0-alpha.2"
},
{
"kind": "github_release",
"source": "github",
"title": "@modelcontextprotocol/fastify@2.0.0-alpha.2",
"url": "https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/fastify%402.0.0-alpha.2"
},
{
"kind": "github_release",
"source": "github",
"title": "@modelcontextprotocol/express@2.0.0-alpha.2",
"url": "https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/express%402.0.0-alpha.2"
},
{
"kind": "github_release",
"source": "github",
"title": "@modelcontextprotocol/server@2.0.0-alpha.1",
"url": "https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.0.0-alpha.1"
},
{
"kind": "github_release",
"source": "github",
"title": "@modelcontextprotocol/node@2.0.0-alpha.1",
"url": "https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/node%402.0.0-alpha.1"
}
],
"status": "已收录 8 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "The official TypeScript SDK for Model Context Protocol servers and clients",
"effort": "安装已验证",
"forks": 1835,
"icon": "code",
"name": "typescript-sdk 能力包",
"risk": "可发布",
"slug": "typescript-sdk",
"stars": 12412,
"tags": [
"安全审查与权限治理",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/modelcontextprotocol/typescript-sdk 项目说明书\n\n生成时间：2026-05-13 12:02:59 UTC\n\n## 目录\n\n- [MCP TypeScript SDK 概述](#page-1)\n- [系统架构与包结构](#page-2)\n- [协议与类型定义](#page-3)\n- [数据验证与 Schema](#page-4)\n- [传输层实现](#page-5)\n- [服务器开发指南](#page-6)\n- [客户端开发指南](#page-7)\n- [认证与授权机制](#page-8)\n- [Web 框架中间件集成](#page-9)\n- [实验性功能与任务系统](#page-10)\n\n\n\n## MCP TypeScript SDK 概述\n\n### 相关页面\n\n相关主题：[系统架构与包结构](#page-2), [服务器开发指南](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/README.md)\n- [CLAUDE.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)\n- [examples/server/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)\n- [examples/client/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/README.md)\n- [packages/server/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)\n- [packages/core/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)\n- [packages/client/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)\n- [packages/middleware/express/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/CHANGELOG.md)\n- [packages/middleware/hono/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/CHANGELOG.md)\n- [packages/middleware/fastify/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/CHANGELOG.md)\n- [common/tsconfig/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/common/tsconfig/package.json)\n \n\n# MCP TypeScript SDK 概述\n\n## 简介\n\nMCP TypeScript SDK（Model Context Protocol TypeScript SDK）是 Model Context Protocol 的 TypeScript/Node.js 实现，为开发者提供了构建 MCP 服务器和客户端的能力。该 SDK 采用 Monorepo 结构，包含核心包、客户端包、服务器包以及多种 Web 框架适配器。\n\n资料来源：[README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/README.md)\n\n## 架构设计\n\n### 两层导出结构\n\nSDK 采用精心设计的两层导出结构，以清晰分离内部实现和公共 API：\n\n```mermaid\ngraph TD\n A[\"@modelcontextprotocol/core
packages/core/src/index.ts\"] --> B[\"内部 barrel
导出全部内容\"]\n A --> C[\"包括 Zod schemas、Protocol 类、stdio 工具\"]\n B --> D[\"@modelcontextprotocol/core/public
packages/core/src/exports/public/index.ts\"]\n D --> E[\"仅导出：TypeScript 类型、错误类、常量、守卫函数\"]\n D --> F[\"@modelcontextprotocol/client\"]\n D --> G[\"@modelcontextprotocol/server\"]\n F --> H[\"最终公共表面\"]\n G --> H\n```\n\n资料来源：[CLAUDE.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)\n\n### 导出层级说明\n\n| 层级 | 包名 | 用途 | 可见性 |\n|------|------|------|--------|\n| 第一层 | `@modelcontextprotocol/core` | 内部 barrel，导出所有内容 | 私有，仅 monorepo 内部使用 |\n| 第二层 | `@modelcontextprotocol/core/public` | 精选公共 API | 公共 |\n| 第三层 | `@modelcontextprotocol/client` | 客户端特定导出 | 公共 |\n| 第三层 | `@modelcontextprotocol/server` | 服务器特定导出 | 公共 |\n\n**导出规范要求：**\n\n- 在包的 `index.ts` 文件和 `core/public` 中使用显式命名导出（`export *` 禁止）\n- 向包的 `index.ts` 添加符号会使其成为公共 API，需谨慎操作\n- 内部辅助函数应保留在 core 内部 barrel 中，不添加到 `core/public`\n\n资料来源：[CLAUDE.md:1-15](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)\n\n## 核心模块\n\n### 包结构总览\n\n```mermaid\ngraph LR\n subgraph \"核心包\"\n A[\"@modelcontextprotocol/core\"]\n end\n subgraph \"中间件适配器\"\n B[\"@modelcontextprotocol/express\"]\n C[\"@modelcontextprotocol/hono\"]\n D[\"@modelcontextprotocol/fastify\"]\n E[\"@modelcontextprotocol/node\"]\n end\n subgraph \"应用包\"\n F[\"@modelcontextprotocol/client\"]\n G[\"@modelcontextprotocol/server\"]\n end\n A --> F\n A --> G\n B --> G\n C --> G\n D --> G\n```\n\n### 传输系统\n\n传输层（`packages/core/src/shared/transport.ts`）提供通信层支持：\n\n- **Streamable HTTP**：现代推荐的传输方式，支持有状态和无状态模式\n- **SSE（Server-Sent Events）**：传统轮询方式，用于向后兼容\n\n资料来源：[CLAUDE.md:24-26](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)\n\n### 实验性功能\n\n实验性功能通过 `@modelcontextprotocol/sdk/experimental` 模块导出：\n\n```typescript\nimport { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';\n```\n\n资料来源：[packages/server/src/experimental/index.ts:1-10](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)\n\n## 服务器开发\n\n### 服务器示例索引\n\n| 场景 | 描述 | 文件 |\n|------|------|------|\n| Streamable HTTP 服务器（有状态） | 功能丰富的服务器，支持工具/资源/提示、日志、任务、采样和可选 OAuth | `src/simpleStreamableHttp.ts` |\n| Streamable HTTP 服务器（无状态） | 无会话跟踪，适用于简单的 API 风格服务器 | `src/simpleStatelessStreamableHttp.ts` |\n| 仅资源服务器认证 | 使用 SDK 的 `mcpAuthMetadataRouter` + `requireBearerAuth` 的最小化 OAuth RS | `src/resourceServerOnly.ts` |\n| JSON 响应模式（无 SSE） | 仅 JSON 响应的 Streamable HTTP，有限的通知支持 | `src/jsonResponseStreamableHttp.ts` |\n\n资料来源：[examples/server/README.md:20-30](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)\n\n### 运行服务器示例\n\n从仓库根目录运行：\n\n```bash\npnpm install\npnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts\n```\n\n或在示例包内运行：\n\n```bash\ncd examples/server\npnpm tsx src/simpleStreamableHttp.ts\n```\n\n资料来源：[examples/server/README.md:10-15](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)\n\n### Web 框架适配器\n\nSDK 提供多种 Web 框架的中间件适配器：\n\n| 适配器 | 包名 | 文档 |\n|--------|------|------|\n| Express | `@modelcontextprotocol/express` | `packages/middleware/express` |\n| Hono | `@modelcontextprotocol/hono` | `packages/middleware/hono` |\n| Fastify | `@modelcontextprotocol/fastify` | `packages/middleware/fastify` |\n| Node.js | `@modelcontextprotocol/node` | `packages/middleware/node` |\n\n所有中间件适配器均基于统一的适配器模式构建，遵循 Express 和 Hono 适配器的设计规范。\n\n资料来源：[packages/middleware/fastify/CHANGELOG.md:18-22](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/CHANGELOG.md)\n\n## 客户端开发\n\n### 客户端示例索引\n\n| 场景 | 描述 | 文件 |\n|------|------|------|\n| 交互式 Streamable HTTP 客户端 | CLI 客户端，测试工具/资源/提示、通知、 elicit 内容和任务 | `src/simpleStreamableHttp.ts` |\n| 向后兼容客户端 | 优先尝试 Streamable HTTP，在 4xx 响应时回退到传统 SSE | `src/streamableHttpWithSseFallbackClient.ts` |\n| SSE 轮询客户端（传统） | 轮询传统 HTTP+SSE 服务器，展示通知处理 | `src/ssePollingClient.ts` |\n| 并行工具调用 | 并行运行多个工具调用 | - |\n\n资料来源：[examples/client/README.md:18-25](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/README.md)\n\n### 运行客户端示例\n\n从仓库根目录运行：\n\n```bash\npnpm install\npnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts\n```\n\n大多数客户端示例需要先启动服务器（参考服务器示例）。\n\n资料来源：[examples/client/README.md:8-12](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/README.md)\n\n### 客户端核心功能\n\n#### OAuth 发现功能\n\nSDK 2.0.0-alpha.1 引入了 `discoverOAuthServerInfo()` 函数和统一的发现状态缓存机制。\n\n资料来源：[packages/client/CHANGELOG.md:14-17](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)\n\n#### WebSocket 变更\n\n**重要变更**：从 2.0.0-alpha.1 开始，`WebSocketClientTransport` 已被移除。WebSocket 不是规范定义的传输方式，请使用 stdio 或 Streamable HTTP。`Transport` 接口仍然导出以支持自定义实现。\n\n资料来源：[packages/client/CHANGELOG.md:10-14](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)\n\n## 核心包功能\n\n### 资源模式增强\n\nSDK 在 `ResourceSchema` 中添加了缺失的 `size` 字段，以匹配 MCP 规范。\n\n资料来源：[packages/core/CHANGELOG.md:2-4](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)\n\n### 安全修复\n\n#### ReDoS 漏洞修复\n\n修复了 UriTemplate 正则表达式模式中的 ReDoS 漏洞（CVE-2026-0621）。\n\n资料来源：[packages/core/CHANGELOG.md:6-8](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)\n\n### 能力断言规范化\n\nSDK 将剩余的能力断言转换为 `SdkError(SdkErrorCode.CapabilityNotSupported, ...)` 格式，包括：\n- `Client.assertCapability()`\n- 实验性任务辅助函数（`experimental/tasks/helpers.ts`）\n- 采样/elicitation 能力检查（`experimental/tasks/server.ts`）\n\n资料来源：[packages/core/CHANGELOG.md:9-15](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)\n\n## 版本历史\n\n### 最新版本动态\n\n| 包 | 当前版本 | 关键变更 |\n|----|----------|----------|\n| `@modelcontextprotocol/core` | 2.0.0 | 核心库 |\n| `@modelcontextprotocol/client` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n| `@modelcontextprotocol/server` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n| `@modelcontextprotocol/express` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n| `@modelcontextprotocol/hono` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n| `@modelcontextprotocol/fastify` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n| `@modelcontextprotocol/node` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n\n所有中间件包的 2.0.0-alpha.2 版本都依赖于 `@modelcontextprotocol/server@2.0.0-alpha.2`。\n\n资料来源：[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)\n\n## 开发工具配置\n\n### TypeScript 配置\n\nSDK 使用统一的 TypeScript 配置：\n\n```json\n{\n \"name\": \"@modelcontextprotocol/tsconfig\",\n \"private\": true,\n \"main\": \"tsconfig.json\",\n \"type\": \"module\",\n \"dependencies\": {\n \"typescript\": \"catalog:devTools\"\n }\n}\n```\n\n资料来源：[common/tsconfig/package.json:1-13](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/common/tsconfig/package.json)\n\n## 快速开始\n\n### 安装依赖\n\n```bash\npnpm install\n```\n\n### 构建项目\n\n```bash\npnpm build\n```\n\n### 开发工作流\n\n```mermaid\ngraph LR\n A[\"安装 pnpm install\"] --> B[\"运行示例\"]\n B --> C[\"服务器示例
pnpm --filter @modelcontextprotocol/examples-server\"]\n B --> D[\"客户端示例
pnpm --filter @modelcontextprotocol/examples-client\"]\n```\n\n## 相关文档\n\n- [服务器开发指南](../../docs/server.md)\n- [客户端开发指南](../../docs/client.md)\n- [官方 MCP 规范](https://modelcontextprotocol.io)\n\n---\n\n\n\n## 系统架构与包结构\n\n### 相关页面\n\n相关主题：[MCP TypeScript SDK 概述](#page-1), [协议与类型定义](#page-3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/server/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/package.json)\n- [packages/client/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/package.json)\n- [packages/middleware/node/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/package.json)\n- [packages/core/src/types/spec.types.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/spec.types.ts)\n- [CLAUDE.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)\n- [package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/package.json)\n \n\n# 系统架构与包结构\n\n## 概述\n\nMCP TypeScript SDK 是一个用于实现 Model Context Protocol (MCP) 的 TypeScript 工具包，采用 monorepo 结构组织。该 SDK 提供客户端和服务端的完整实现，支持多种传输层协议，包括 Streamable HTTP 和标准输入输出 (stdio)。SDK 的设计目标是分离内部实现与公共 API，确保只有经过审核的类型、错误类和守卫函数对外暴露，同时保持对浏览器和 Cloudflare Workers 等不同运行环境的兼容性。\n\n## 核心架构分层\n\nSDK 采用三层架构设计，从底层到顶层依次为：类型层 (Types Layer)、协议层 (Protocol Layer) 和高级 API 层 (High-Level APIs)。这种分层设计确保了关注点分离，便于维护和扩展。\n\n### 类型层 (Types Layer)\n\n类型层位于 `packages/core/src/types/types.ts`，定义了从 MCP 规范生成的所有协议类型。所有 JSON-RPC 消息类型、Zod 模式定义和协议常量都在这一层声明。类型层使用 Zod v4 进行运行时验证，确保数据的完整性和类型安全。资料来源：[CLAUDE.md]()\n\n```mermaid\ngraph TD\n A[MCP 规范] --> B[Types Layer]\n B --> C[JSON-RPC 消息类型]\n B --> D[Zod Schema]\n B --> E[协议常量]\n```\n\n### 协议层 (Protocol Layer)\n\n协议层位于 `packages/core/src/shared/protocol.ts`，包含抽象的 `Protocol` 类。该类负责处理 JSON-RPC 消息路由、请求/响应关联、能力协商和传输层管理。`Client` 和 `Server` 都继承自这个基类，共享核心协议逻辑。资料来源：[CLAUDE.md]()\n\n### 高级 API 层 (High-Level APIs)\n\n高级 API 层提供面向终端用户的接口：\n\n| 类名 | 文件位置 | 职责 |\n|------|---------|------|\n| `Client` | `packages/client/src/client/client.ts` | 客户端实现，扩展 Protocol 类，提供 MCP 操作的类型化方法 |\n| `Server` | `packages/server/src/server/server.ts` | 服务端实现，扩展 Protocol 类，提供请求处理器注册 |\n| `McpServer` | `packages/server/src/server/mcp.ts` | 高层服务器 API，简化资源/工具/提示的注册流程 |\n\n## 包结构概览\n\nSDK 采用 monorepo 结构，使用 pnpm workspaces 管理多个包。以下是主要包的层次结构：资料来源：[package.json]()\n\n```mermaid\ngraph TD\n subgraph 核心层\n A[@modelcontextprotocol/core]\n B[@modelcontextprotocol/core/public]\n end\n \n subgraph 公共API层\n C[@modelcontextprotocol/client]\n D[@modelcontextprotocol/server]\n end\n \n subgraph 中间件层\n E[@modelcontextprotocol/hono]\n F[@modelcontextprotocol/fastify]\n G[@modelcontextprotocol/node]\n end\n \n A --> B\n B --> C\n B --> D\n D --> E\n D --> F\n C --> G\n \n style A fill:#f9f,opacity:0.3\n style B fill:#ff9,opacity:0.3\n style C fill:#9f9,opacity:0.3\n style D fill:#9f9,opacity:0.3\n```\n\n## 核心包详解\n\n### @modelcontextprotocol/core\n\n这是 SDK 的内部核心包，所有内部代码都在此处实现。该包的主要入口文件为 `packages/core/src/index.ts`，导出内容包括 Zod 模式、Protocol 类和 stdio 工具函数。由于该包标记为 `private: true`，仅供 monorepo 内部的其他包消费，不对外部直接发布。\n\n核心导出结构：\n\n- **主入口** (`packages/core/src/index.ts`) — 内部桶，导出所有内部实现\n- **公共入口** (`packages/core/src/exports/public/index.ts`) — 精选的公共 API，仅包含 TypeScript 类型、错误类、常量和守卫函数\n\n### @modelcontextprotocol/client\n\n客户端包提供 MCP 协议的客户端实现，支持连接 MCP 服务器、调用工具、访问资源和获取提示。该包的入口文件导出命名符号，遵循显式导出而非 `export *` 的原则。\n\n支持的传输方式：\n\n| 传输类型 | 描述 | 适用场景 |\n|---------|------|---------|\n| Streamable HTTP | 推荐的现代传输方式，支持状态化会话 | Web 应用、服务端集成 |\n| stdio | 标准输入输出传输 | 本地进程、CLI 工具 |\n| SSE (Legacy) | 服务端发送事件，兼容旧版服务器 | 向后兼容 |\n\n资料来源：[packages/client/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/package.json)\n\n### @modelcontextprotocol/server\n\n服务端包提供 MCP 协议的服务端实现，允许开发者注册工具、资源、提示，并处理来自客户端的请求。该包是许多框架适配器的基础依赖。\n\n主要功能：\n\n- 工具注册与处理\n- 资源管理\n- 提示注册\n- 采样请求处理\n- 任务管理 (experimental)\n\n服务端包提供多个子路径导出以支持不同的运行环境：\n\n| 导出路径 | 类型定义 | 说明 |\n|---------|---------|------|\n| `.` | `dist/index.d.mts` | 主入口 |\n| `./stdio` | `dist/stdio.d.mts` | stdio 传输支持 |\n| `./validators/cf-worker` | `dist/validators/cfWorker.d.mts` | Cloudflare Workers 验证器 |\n| `./_shims` | 多环境 | workerd、browser、node 环境垫片 |\n\n资料来源：[packages/server/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/package.json)\n\n## 中间件与适配器层\n\n中间件层提供将 MCP 服务端集成到不同 Web 框架的适配器，简化常见服务器框架的使用。\n\n### @modelcontextprotocol/hono\n\nHono 框架适配器，用于在 Hono 应用中运行 MCP 服务端。Hono 是一个轻量、跨平台的 Web 框架，支持 Cloudflare Workers、Deno、Bun 等运行环境。\n\n```typescript\n// 使用示例结构\nimport { createMcpServer } from '@modelcontextprotocol/server';\nimport { Hono } from 'hono';\nimport { mcpHonoAdapter } from '@modelcontextprotocol/hono';\n\nconst app = new Hono();\nconst mcpServer = createMcpServer({ /* 配置 */ });\napp.use('/mcp', mcpHonoAdapter(mcpServer));\n```\n\n### @modelcontextprotocol/fastify\n\nFastify 框架适配器，提供与 Fastify 的集成。Fastify 以其高性能和低开销著称，适合需要高吞吐量的场景。资料来源：[packages/middleware/fastify/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/CHANGELOG.md)\n\n### @modelcontextprotocol/node\n\nNode.js 原生适配器，提供基于 `@hono/node-server` 的服务端实现。这是运行在标准 Node.js 环境中时推荐使用的中间件。\n\n该包已添加缺失的 `hono` peer 依赖，确保运行时依赖完整。资料来源：[packages/middleware/node/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/CHANGELOG.md)\n\n## 传输系统\n\n传输层位于 `packages/core/src/shared/transport.ts`，负责客户端与服务端之间的通信。SDK 支持多种传输机制，每种都有特定的适用场景。\n\n### Streamable HTTP\n\nStreamable HTTP 是 V2 版本推荐的传输方式，支持状态化会话管理。它允许服务器跟踪会话状态，适合需要维护上下文的复杂交互场景。\n\n```mermaid\ngraph LR\n A[Client] -->|HTTP POST /mcp| B[Streamable HTTP Server]\n B -->|Streaming Response| A\n A <-->|Session Token| B\n```\n\n### stdio 传输\n\nstdio 传输通过标准输入输出进行通信，适用于本地进程调用和命令行工具。这是 MCP 最初设计的传输方式，配置简单，无需网络。\n\n### 传输导出结构\n\n为确保运行时环境兼容性，stdio 相关的导出位于命名子路径：\n\n```typescript\n// 运行时中性导入（浏览器、Cloudflare Workers）\nimport { Client } from '@modelcontextprotocol/client';\n\n// Node.js 专用 stdio 导入\nimport { stdioClientTransport } from '@modelcontextprotocol/client/stdio';\n```\n\n资料来源：[packages/client/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/package.json)\n\n## 导出结构与命名规范\n\nSDK 采用两层导出结构来区分内部实现和公共 API，这是确保包边界清晰的关键设计。\n\n### 内部导出 (Internal Barrel)\n\n`@modelcontextprotocol/core` 的主入口导出所有内部实现，包括：\n\n- Zod 模式 (Schema)\n- Protocol 类\n- stdio 工具函数\n- 内部帮助函数\n\n这些导出仅供 monorepo 内部包使用，不应被外部代码直接依赖。\n\n### 公共导出 (Public API)\n\n`@modelcontextprotocol/core/public` 提供精选的公共 API，仅包含：\n\n| 类别 | 内容 |\n|-----|------|\n| TypeScript 类型 | 所有公共接口和类型定义 |\n| 错误类 | 异常处理类 |\n| 常量 | 协议常量 |\n| 守卫函数 | 类型守卫和验证函数 |\n\n### 包索引导出规则\n\n在修改导出时需遵循以下规则：\n\n1. **使用显式命名导出** — 包索引文件应使用 `export { SpecificExport }` 而非 `export *`\n2. **公共 API 变更需谨慎** — 添加到包索引的符号即成为公共 API\n3. **内部代码隔离** — 内部帮助函数应保留在 core 内部桶中\n4. **运行时中性** — 包根入口必须保持运行时中性，确保浏览器和 Cloudflare Workers 可正常打包\n\n## 实验性功能\n\nSDK 将某些功能标记为实验性，通过 `@modelcontextprotocol/sdk/experimental` 导出。当前实验性功能包括任务存储 (TaskStore) 相关实现。\n\n```typescript\n// 导入实验性功能\nimport { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';\n```\n\n实验性 API 可能随时变更，不提供稳定性保证。使用前请评估风险。\n\n资料来源：[packages/server/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)\n\n## 构建与工具链\n\nSDK 使用以下工具链进行开发和构建：\n\n| 工具 | 用途 | 配置位置 |\n|-----|------|---------|\n| pnpm | 包管理器 | `pnpm-workspace.yaml` |\n| TypeScript | 类型检查 | `tsconfig.json` |\n| tsdown | 包构建 | 各包的 `package.json` |\n| vitest | 测试框架 | `vitest.config.ts` |\n| typedoc | 文档生成 | TypeDoc 配置 |\n\n### 常用构建命令\n\n```bash\n# 安装依赖\npnpm install\n\n# 类型检查\npnpm typecheck:all\n\n# 构建所有包\npnpm build:all\n\n# 生成文档\npnpm docs\n\n# 运行测试\npnpm test\n```\n\n## 版本与兼容性\n\n| 包 | 当前版本 | Node.js 最低版本 |\n|----|---------|-----------------|\n| @modelcontextprotocol/client | 2.0.0-alpha.2 | >=20 |\n| @modelcontextprotocol/server | 2.0.0-alpha.2 | >=20 |\n| @modelcontextprotocol/sdk | 2.0.0-alpha.0 | >=20 |\n\nV2 版本移除了 WebSocket 传输，WebSocket 不是规范定义的传输方式。推荐使用 stdio 或 Streamable HTTP。如需自定义传输，可实现并使用 `Transport` 接口。资料来源：[packages/client/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)\n\n---\n\n\n\n## 协议与类型定义\n\n### 相关页面\n\n相关主题：[系统架构与包结构](#page-2), [数据验证与 Schema](#page-4)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/shared/protocol.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/shared/protocol.ts)\n- [packages/core/src/types/types.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/types.ts)\n- [packages/core/src/types/specTypeSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/specTypeSchema.ts)\n- [packages/core/src/validators/fromJsonSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/validators/fromJsonSchema.ts)\n- [packages/server/src/server/completable.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/completable.ts)\n \n\n# 协议与类型定义\n\n## 概述\n\nMCP TypeScript SDK 的核心架构建立在两层抽象之上：**协议层（Protocol Layer）** 和 **类型层（Types Layer）**。协议层负责 JSON-RPC 消息的路由、请求/响应关联、能力协商和传输管理；类型层则定义了所有 MCP 协议消息的 Zod v4 模式和数据结构。\n\n这两个层次共同构成了 SDK 的基础设施，支撑着 Client、Server 和 McpServer 的高级 API 实现。\n\n## 架构分层\n\n```mermaid\ngraph TB\n subgraph \"High-Level APIs\"\n McpServer[\"McpServer
packages/server/src/server/mcp.ts\"]\n Server[\"Server
packages/server/src/server/server.ts\"]\n Client[\"Client
packages/client/src/client/client.ts\"]\n end\n \n subgraph \"Protocol Layer\"\n Protocol[\"Protocol
packages/core/src/shared/protocol.ts\"]\n end\n \n subgraph \"Types Layer\"\n Types[\"Types
packages/core/src/types/types.ts\"]\n SpecTypes[\"SpecTypes
packages/core/src/types/specTypeSchema.ts\"]\n Schemas[\"Zod Schemas\"]\n end\n \n subgraph \"Transport Layer\"\n Transport[\"Transport Interface\"]\n end\n \n McpServer --> Server\n Server --> Protocol\n Client --> Protocol\n Protocol --> Types\n Protocol --> SpecTypes\n Protocol --> Transport\n Types --> Schemas\n```\n\n资料来源：[CLAUDE.md]()\n\n## 协议层\n\n### Protocol 基类\n\n`Protocol` 是 Client 和 Server 共同继承的抽象基类，处理所有底层协议逻辑：\n\n| 职责 | 说明 |\n|------|------|\n| JSON-RPC 消息路由 | 解析和分发 JSON-RPC 请求/响应/通知 |\n| 请求-响应关联 | 维护 pendingRequests Map，关联请求 ID 与回调 |\n| 能力协商 | 能力注册和匹配机制 |\n| 传输管理 | 底层通信抽象 |\n\n### JSON-RPC 消息类型\n\nMCP 协议使用标准 JSON-RPC 2.0 消息格式：\n\n| 消息类型 | 方向 | 说明 |\n|----------|------|------|\n| Request | 双向 | 需要响应的消息，带 `id` |\n| Response | 双向 | 对请求的响应，包含 `id` 和 `result`/`error` |\n| Notification | 双向 | 无需响应的消息，不带 `id` |\n\n```mermaid\nsequenceDiagram\n participant C as Client\n participant P as Protocol\n participant T as Transport\n \n C->>P: 构造 Request\n P->>P: 生成 requestId\n P->>P: 存储 PromiseResolver\n P->>T: 发送 JSON-RPC Request\n T->>P: 接收 JSON-RPC Response\n P->>P: 根据 requestId 恢复 Promise\n P->>C: 返回 Response\n```\n\n### 消息处理器注册\n\nProtocol 类提供方法注册各类消息的处理器：\n\n```typescript\n// 资料来源：packages/core/src/shared/protocol.ts\nrequestHandlers: Map\nnotificationHandlers: Map\n```\n\n## 类型层\n\n### 类型组织结构\n\n类型层位于 `packages/core/src/types/`，包含以下核心文件：\n\n| 文件 | 职责 |\n|------|------|\n| `types.ts` | MCP 协议类型定义，从规范生成 |\n| `specTypeSchema.ts` | StandardSchemaV1 类型架构 |\n| `errors.ts` | 错误类型定义 |\n| `enums.ts` | 枚举类型定义 |\n\n### 资源类型（Resources）\n\n资源用于向客户端暴露可读取的数据：\n\n```typescript\n// 资料来源：packages/core/src/types/types.ts\nexport type TextResourceContents = Infer;\nexport type BlobResourceContents = Infer;\nexport type Resource = Infer;\nexport type ResourceTemplate = Infer;\n```\n\n| 类型 | 说明 |\n|------|------|\n| `TextResourceContents` | 文本资源内容 |\n| `BlobResourceContents` | 二进制资源内容 |\n| `Resource` | 完整资源定义 |\n| `ResourceTemplate` | 资源模板（带占位符） |\n\n### 提示类型（Prompts）\n\n提示用于定义可复用的消息模板：\n\n```typescript\n// 资料来源：packages/core/src/types/types.ts\nexport type PromptArgument = Infer;\nexport type Prompt = Infer;\nexport type ListPromptsResult = Infer;\nexport type GetPromptRequest = Infer;\n```\n\n### 工具类型（Tools）\n\n工具是服务器暴露的可执行操作：\n\n| 类型 | 说明 |\n|------|------|\n| `CallToolRequest` | 工具调用请求 |\n| `CallToolResult` | 工具调用结果 |\n| `Tool` | 工具定义 |\n| `ToolAnnotations` | 工具注解（毒性、是否确定性等） |\n\n```typescript\n// 资料来源：packages/core/src/types/types.ts\nexport type CallToolResult = Infer;\nexport type Tool = Infer;\n```\n\n### 任务类型（Tasks）\n\n任务支持长时运行的异步操作：\n\n```typescript\n// 资料来源：packages/server/src/server/mcp.ts\ntype TaskHandlerInternal = {\n createTask: (args: unknown, ctx: CreateTaskServerContext) => CreateTaskResult | Promise;\n};\n```\n\n## StandardSchemaV1 类型系统\n\n### 概述\n\nSDK 使用 [StandardSchemaV1](https://github.com/ModelContextProtocol/typescript-sdk/blob/main/packages/core/src/types/specTypeSchema.ts) 作为输入输出的标准模式格式，这是一个供应商中立（vendor-neutral）的模式接口。\n\n### 模式注册机制\n\n`specTypeSchema.ts` 通过注册表模式将 MCP 规范中的所有类型映射到 StandardSchemaV1：\n\n```typescript\n// 资料来源：packages/core/src/types/specTypeSchema.ts\nconst _specTypeSchemas: Record = {};\nconst _isSpecType: Record boolean> = {};\n\nfunction register(key: string, schema: z.ZodType): void {\n const name = key.slice(0, -'Schema'.length);\n _specTypeSchemas[name] = schema;\n _isSpecType[name] = (v: unknown) => schema.safeParse(v).success;\n}\n```\n\n### SpecTypes 类型映射\n\n```typescript\n// 资料来源：packages/core/src/types/specTypeSchema.ts\nexport type SpecTypes = {\n [K in SchemaKey as StripSchemaSuffix]: SchemaFor extends z.ZodType ? z.output> : never;\n};\n```\n\n### 从 JSON Schema 转换\n\nSDK 提供 `fromJsonSchema` 函数将 JSON Schema 转换为 StandardSchemaV1：\n\n```typescript\n// 资料来源：packages/core/src/validators/fromJsonSchema.ts\nexport function fromJsonSchema(\n schema: JsonSchemaType, \n validator: jsonSchemaValidator\n): StandardSchemaWithJSON {\n return {\n '~standard': {\n version: 1,\n vendor: 'mcp',\n jsonSchema: {\n input: () => schema as Record,\n output: () => schema as Record\n },\n validate: (data: unknown): StandardSchemaV1.Result => {\n const result = check(data);\n return result.valid \n ? { value: result.data } \n : { issues: [{ message: result.errorMessage }] };\n }\n }\n };\n}\n```\n\n## Completable 类型\n\nCompletable 提供参数自动完成功能：\n\n```typescript\n// 资料来源：packages/server/src/server/completable.ts\nexport const COMPLETABLE_SYMBOL: unique symbol = Symbol.for('mcp.completable');\n\nexport type CompleteCallback = (\n value: StandardSchemaV1.InferInput,\n context?: {\n arguments?: Record;\n }\n) => StandardSchemaV1.InferInput[] | Promise[]>;\n\nexport type CompletableSchema = T & {\n [COMPLETABLE_SYMBOL]: CompletableMeta;\n};\n```\n\n使用示例：\n\n```typescript\n// 资料来源：packages/server/src/server/completable.ts\nserver.registerPrompt(\n 'review-code',\n {\n title: 'Code Review',\n argsSchema: z.object({\n language: completable(\n z.string().describe('Programming language'), \n value => ['typescript', 'javascript', 'python', 'rust', 'go']\n .filter(lang => lang.startsWith(value))\n )\n })\n },\n ({ language }) => ({\n messages: [{ role: 'user', content: { type: 'text', text: `Review this ${language} code.` } }]\n })\n);\n```\n\n## Zod Schema 结构\n\n### Schema 层级\n\n```mermaid\ngraph TD\n ZodType[\"z.ZodType
基础类型\"]\n ZodObject[\"z.ZodObject
对象类型\"]\n ZodArray[\"z.ZodArray
数组类型\"]\n ZodString[\"z.ZodString
字符串\"]\n ZodNumber[\"z.ZodNumber
数字\"]\n ZodBoolean[\"z.ZodBoolean
布尔值\"]\n \n ZodType --> ZodObject\n ZodType --> ZodArray\n ZodType --> ZodString\n ZodType --> ZodNumber\n ZodType --> ZodBoolean\n```\n\n### 模式验证流程\n\n```mermaid\nsequenceDiagram\n participant Input as 用户输入\n participant Schema as Zod Schema\n participant Validate as validateStandardSchema\n participant Output as 类型安全输出\n \n Input->>Schema: 原始数据\n Schema->>Validate: 调用 safeParse\n Validate->>Output: 验证成功，返回类型化数据\n Note over Validate,Output: parseResult.success === true\n```\n\n## 错误类型\n\nSDK 定义了结构化的错误类型：\n\n| 错误类型 | 说明 |\n|----------|------|\n| `JsonRpcError` | JSON-RPC 标准错误 |\n| `McpError` | MCP 特定错误 |\n| 错误码范围 | MCP 保留 10000-19999 |\n\n## 枚举类型\n\n`enums.ts` 定义了协议中使用的枚举值：\n\n| 枚举 | 用途 |\n|------|------|\n| 日志级别 | `debug`, `info`, `warning`, `error` |\n| 资源可见性 | `secret`, `information`, `documentation` |\n| 采样优先级 | `low`, `medium`, `high` |\n\n## 类型推断机制\n\nSDK 使用 TypeScript 的类型推断来提供类型安全：\n\n```typescript\n// 资料来源：packages/core/src/types/types.ts\n// 使用 Infer 类型工具从 Zod schema 推断 TypeScript 类型\nexport type Resource = Infer;\nexport type Prompt = Infer;\nexport type CallToolResult = Infer;\n```\n\n### Infer 类型定义\n\n```typescript\n// Infer 类型工具允许从 Zod schema 反向推断 TypeScript 类型\ntype Infer = T extends z.ZodType \n ? Output \n : never;\n```\n\n## 模式键名约定\n\nMCP 规范中的模式使用统一后缀约定：\n\n| 后缀 | 含义 | 示例 |\n|------|------|------|\n| `Schema` | 原始 Zod schema | `ListResourcesRequestSchema` |\n| 无后缀 | 推断后的 TypeScript 类型 | `ListResourcesRequest` |\n\n## 导出结构\n\nSDK 采用两层导出结构：\n\n```mermaid\ngraph LR\n subgraph \"@modelcontextprotocol/core\"\n Core[\"内部 barrel
导出所有内容\"]\n end\n \n subgraph \"@modelcontextprotocol/client\"\n Client[\"公共 API
客户端专用\"]\n end\n \n subgraph \"@modelcontextprotocol/server\"\n Server[\"公共 API
服务端专用\"]\n end\n \n Core --> Client\n Core --> Server\n```\n\n- **`@modelcontextprotocol/core`** — 内部 barrel，导出所有内容（包含 Zod schemas、Protocol 类等），仅供 monorepo 内部使用\n- **`@modelcontextprotocol/client`** — 客户端公共 API\n- **`@modelcontextprotocol/server`** — 服务端公共 API\n\n资料来源：[CLAUDE.md]()\n\n## 最佳实践\n\n### 类型安全保证\n\n1. **使用 Zod 进行运行时验证** — 所有输入都经过 Zod schema 验证\n2. **TypeScript 类型推断** — 减少手动类型标注，降低错误风险\n3. **StandardSchemaV1 抽象** — 支持供应商中立的模式定义\n\n### 模式设计\n\n| 实践 | 说明 |\n|------|------|\n| 显式类型注解 | 使用 `z.object()` 显式定义对象结构 |\n| 描述字段 | 使用 `.describe()` 提供字段文档 |\n| 默认值 | 使用 `.default()` 提供安全的默认值 |\n| 可选链 | 使用 `.optional()` 明确可选字段 |\n\n---\n\n\n\n## 数据验证与 Schema\n\n### 相关页面\n\n相关主题：[协议与类型定义](#page-3), [服务器开发指南](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/util/zodCompat.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/util/zodCompat.ts)\n- [packages/core/src/util/standardSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/util/standardSchema.ts)\n- [packages/core/src/validators/fromJsonSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/validators/fromJsonSchema.ts)\n- [packages/core/src/validators/ajvProvider.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/validators/ajvProvider.ts)\n- [packages/core/src/util/schema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/util/schema.ts)\n- [packages/server/src/server/completable.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/completable.ts)\n- [packages/core/src/types/specTypeSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/specTypeSchema.ts)\n \n\n# 数据验证与 Schema\n\n## 概述\n\nMCP TypeScript SDK 提供了一套完整的 Schema 验证体系，支持多种 Schema 定义方式。该系统允许开发者使用任意实现了 [Standard Schema 规范](https://standardschema.dev/) 的验证库来定义工具（Tool）、提示（Prompt）和资源的输入输出结构。\n\nSDK 的验证架构基于以下核心原则：\n\n- **标准化接口**：使用 `StandardSchemaV1` 接口统一不同验证库的行为\n- **多库支持**：原生支持 Zod v4、Valibot、ArkType 等主流验证库\n- **JSON Schema 桥接**：通过 `fromJsonSchema` 适配器支持纯 JSON Schema\n- **向后兼容**：保留 Zod v3 的部分兼容层\n\n资料来源：[packages/core/src/util/standardSchema.ts:1-50]()\n\n## 架构图\n\n```mermaid\ngraph TD\n subgraph \"用户层\"\n ZOD_V4[Zod v4 Schema]\n VALIBOT[Valibot Schema]\n ARKTYPE[ArkType Schema]\n JSON_SCHEMA[Raw JSON Schema]\n RAW_SHAPE[Zod Raw Shape]\n end\n\n subgraph \"标准化层\"\n STD_SCHEMA[StandardSchemaV1]\n STD_JSON[StandardJSONSchemaV1]\n end\n\n subgraph \"适配器层\"\n ZOD_COMPAT[zodCompat.ts]\n FROM_JSON[fromJsonSchema.ts]\n NORMALIZE[normalizeRawShapeSchema]\n end\n\n subgraph \"验证器层\"\n ZOD_VALIDATOR[Zod 内置验证]\n AJV[AjvJsonSchemaValidator]\n CUSTOM[自定义验证器]\n end\n\n ZOD_V4 -->|原生实现| STD_SCHEMA\n VALIBOT -->|原生实现| STD_SCHEMA\n ARKTYPE -->|原生实现| STD_SCHEMA\n JSON_SCHEMA -->|fromJsonSchema| FROM_JSON\n RAW_SHAPE -->|auto-wrap| ZOD_COMPAT\n\n FROM_JSON --> AJV\n ZOD_COMPAT --> ZOD_VALIDATOR\n\n STD_SCHEMA -->|registerTool| MCP_SERVER\n STD_SCHEMA -->|registerPrompt| MCP_SERVER\n\n classDef sdk fill:#e1f5fe\n classDef adapter fill:#fff3e0\n classDef validator fill:#e8f5e9\n```\n\n## Standard Schema 支持\n\n### 标准接口定义\n\n`StandardSchemaV1` 是 MCP SDK 验证系统的核心接口，定义了所有 Schema 必须实现的标准化方法：\n\n```typescript\ninterface StandardSchemaV1 {\n '~standard': {\n version: 1;\n vendor: string;\n jsonSchema?: StandardJSONSchemaV1;\n validate?: (value: unknown) => StandardSchemaV1.Result;\n };\n}\n```\n\n资料来源：[packages/core/src/util/standardSchema.ts:1-30]()\n\n### 标准 Schema 工具函数\n\nSDK 提供了两个核心工具函数用于处理 Standard Schema：\n\n| 函数 | 作用 | 参数 |\n|------|------|------|\n| `standardSchemaToJsonSchema()` | 将 Standard Schema 转换为 JSON Schema | `schema`, `io` ('input' \\| 'output') |\n| `validateStandardSchema()` | 验证数据是否符合 Schema | `schema`, `data` |\n\n`standardSchemaToJsonSchema` 函数支持从多种 Schema 库提取 JSON Schema 表示：\n\n```typescript\nexport function standardSchemaToJsonSchema(\n schema: StandardJSONSchemaV1, \n io: 'input' | 'output' = 'input'\n): Record {\n const std = schema['~standard'];\n let result: Record;\n \n if (std.jsonSchema) {\n result = std.jsonSchema[io]({ target: 'draft-2020-12' });\n } else if (std.vendor === 'zod') {\n // Zod v4 实现 StandardSchemaV1 但没有 ~standard.jsonSchema\n // 回退到 z.toJSONSchema()\n }\n return result;\n}\n```\n\n资料来源：[packages/core/src/util/standardSchema.ts:60-90]()\n\n## Zod 兼容性\n\n### Zod 版本检测\n\nSDK 通过 `zodCompat.ts` 中的工具函数检测 Zod 版本差异：\n\n```typescript\nfunction isZodV4Schema(v: unknown): v is z.ZodType {\n // `_zod` 是 v4 内部命名空间属性\n return typeof v === 'object' && v !== null && '_zod' in v;\n}\n\nfunction looksLikeZodV3(v: unknown): boolean {\n // v3 schemas 有 `_def.typeName` (例如 'ZodString') 但没有 `_zod`\n return (\n typeof v === 'object' &&\n v !== null &&\n !('_zod' in v) &&\n '_def' in v &&\n typeof (v as { _def?: { typeName?: unknown } })._def?.typeName === 'string'\n );\n}\n```\n\n资料来源：[packages/core/src/util/zodCompat.ts:10-30]()\n\n### 版本兼容策略\n\n| Zod 版本 | 支持状态 | 说明 |\n|----------|----------|------|\n| Zod v4 (>= 4.2.0) | ✅ 原生支持 | 实现 `~standard.jsonSchema` 接口 |\n| Zod v4 (< 4.2.0) | ⚠️ 回退支持 | 回退到 `z.toJSONSchema()` |\n| Zod v3 | ❌ 不支持 | 无法转换为 JSON Schema |\n\n> 注意：SDK 已将 `zod` 从 `peerDependencies` 移除，保留为直接依赖。用户无需单独安装 Zod。\n\n资料来源：[packages/client/CHANGELOG.md](), [packages/core/src/util/standardSchema.ts:30-40]()\n\n## JSON Schema 支持\n\n### fromJsonSchema 适配器\n\n对于使用纯 JSON Schema 的场景（如 TypeBox 输出），SDK 提供了 `fromJsonSchema` 适配器：\n\n```typescript\nimport { fromJsonSchema, AjvJsonSchemaValidator } from '@modelcontextprotocol/core';\n\nconst schema = fromJsonSchema(\n { \n type: 'object', \n properties: { \n name: { type: 'string' } \n }, \n required: ['name'] \n },\n new AjvJsonSchemaValidator()\n);\n\nserver.registerTool(\n 'greet',\n { inputSchema: schema },\n async ({ name }) => ({ content: [{ type: 'text', text: `Hello, ${name}!` }] })\n);\n```\n\n资料来源：[packages/core/src/validators/fromJsonSchema.ts:20-40]()\n\n### AjvJsonSchemaValidator\n\n`AjvJsonSchemaValidator` 是基于 [AJV](https://ajv.js.org/) 的 JSON Schema 验证器实现：\n\n```typescript\nexport class AjvJsonSchemaValidator implements jsonSchemaValidator {\n private _ajv: Ajv;\n \n getValidator(schema: JsonSchemaType): ValidatorFn {\n const validate = this._ajv.compile(schema);\n return (data: unknown): ValidationResult => {\n const valid = validate(data);\n return valid \n ? { valid: true, data: data as T }\n : { valid: false, errorMessage: this._ajv.errorsText() };\n };\n }\n}\n```\n\n资料来源：[packages/core/src/validators/ajvProvider.ts]()\n\n## 工具与提示注册\n\n### registerTool 的 Schema 处理\n\n`McpServer.registerTool()` 方法接受 Standard Schema 作为 `inputSchema` 和 `outputSchema`：\n\n```typescript\n// 使用 Zod v4\nimport { z } from 'zod';\n\nserver.registerTool(\n 'calculate',\n {\n inputSchema: z.object({\n a: z.number(),\n b: z.number()\n }),\n outputSchema: z.object({\n result: z.number()\n })\n },\n async ({ a, b }) => ({\n content: [{ type: 'text', text: `${a + b}` }]\n })\n);\n\n// 使用 ArkType\nimport { type } from 'arktype';\n\nserver.registerTool(\n 'greet',\n {\n inputSchema: type({ name: 'string' })\n },\n async ({ name }) => ({ content: [{ type: 'text', text: `Hello, ${name}!` }] })\n);\n```\n\n资料来源：[packages/server/src/server/mcp.ts:150-200]()\n\n### registerPrompt 的 Schema 处理\n\n`registerPrompt` 支持类似的 Schema 定义方式：\n\n```typescript\nserver.registerPrompt(\n 'review-code',\n {\n title: 'Code Review',\n description: 'Review code for best practices',\n argsSchema: z.object({\n code: z.string(),\n language: z.enum(['typescript', 'javascript', 'python'])\n })\n },\n ({ code, language }) => ({\n messages: [\n {\n role: 'user' as const,\n content: {\n type: 'text' as const,\n text: `Please review this ${language} code:\\n\\n${code}`\n }\n }\n ]\n })\n);\n```\n\n资料来源：[packages/server/src/server/mcp.ts:100-150]()\n\n## Raw Shape 简化语法\n\n### 自动包装机制\n\n为简化 Zod 使用，SDK 支持 \"raw shape\" 语法——直接传递字段定义对象而无需显式包装：\n\n```typescript\n// 标准方式\nserver.registerTool('tool1', {\n inputSchema: z.object({ name: z.string() })\n}, handler);\n\n// Raw Shape 方式 (自动包装)\nserver.registerTool('tool2', {\n inputSchema: { name: z.string() } // 自动变成 z.object({...})\n}, handler);\n```\n\n内部通过 `normalizeRawShapeSchema()` 函数实现自动包装：\n\n```typescript\nfunction normalizeRawShapeSchema(schema: unknown): StandardSchemaWithJSON | undefined {\n if (schema === undefined || schema === null) return undefined;\n if (isStandardSchema(schema)) return schema;\n if (isZodV4Schema(schema)) return schema as StandardSchemaWithJSON;\n if (looksLikeZodV3(schema)) {\n // Zod v3: 包装成 z.object()\n return z.object(schema as ZodRawShape);\n }\n // ... 其他处理\n}\n```\n\n资料来源：[packages/core/src/util/zodCompat.ts:40-80]()\n\n## 可补全 Schema\n\n### completable 函数\n\nSDK 提供了 `completable()` 包装器，为 Schema 字段添加自动补全功能：\n\n```typescript\nimport { completable } from '@modelcontextprotocol/server';\n\nserver.registerPrompt(\n 'review-code',\n {\n argsSchema: z.object({\n language: completable(\n z.string().describe('Programming language'),\n (value) => ['typescript', 'javascript', 'python', 'rust', 'go']\n .filter(lang => lang.startsWith(value))\n )\n })\n },\n ({ language }) => ({\n messages: [{\n role: 'user',\n content: { type: 'text', text: `Review this ${language} code.` }\n }]\n })\n);\n```\n\n`CompletableSchema` 在标准 Schema 基础上添加了补全元数据：\n\n```typescript\nexport type CompletableSchema = T & {\n [COMPLETABLE_SYMBOL]: CompletableMeta;\n};\n```\n\n资料来源：[packages/server/src/server/completable.ts:20-50]()\n\n## 内置 Schema 类型\n\n### 协议类型定义\n\nMCP SDK 使用 Zod v4 定义了所有协议消息类型：\n\n```typescript\ntype SpecTypeInputs = {\n [K in SchemaKey as StripSchemaSuffix]: SchemaFor extends z.ZodType \n ? z.input> \n : never;\n};\n\ntype SpecTypes = {\n [K in SchemaKey as StripSchemaSuffix]: SchemaFor extends z.ZodType \n ? z.output> \n : never;\n};\n```\n\n通过 `register()` 函数批量注册所有规范类型：\n\n```typescript\nfor (const key of SPEC_SCHEMA_KEYS) {\n register(key, schemas[key]);\n}\n```\n\n资料来源：[packages/core/src/types/specTypeSchema.ts:20-50]()\n\n### 常用类型列表\n\n| 类型 | 用途 | Schema |\n|------|------|--------|\n| `CallToolRequest` | 工具调用请求 | CallToolRequestSchema |\n| `CallToolResult` | 工具调用结果 | CallToolResultSchema |\n| `GetPromptRequest` | 获取提示请求 | GetPromptRequestSchema |\n| `Resource` | 资源定义 | ResourceSchema |\n| `Prompt` | 提示定义 | PromptSchema |\n\n完整类型列表参见 [packages/core/src/types/types.ts]()。\n\n## 验证流程\n\n### 数据验证时序\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Validator\n participant Schema\n\n Client->>Server: registerTool(name, inputSchema, handler)\n Server->>Schema: 标准化 Schema\n Schema-->>Server: StandardSchemaV1\n\n Client->>Server: tools/call 请求\n Server->>Validator: validate(inputData)\n Validator->>Schema: 执行验证\n Schema-->>Validator: ValidationResult\n\n alt 验证通过\n Validator-->>Server: { valid: true, data }\n Server->>Server: 调用 handler\n Server-->>Client: 工具结果\n else 验证失败\n Validator-->>Server: { valid: false, issues }\n Server-->>Client: InvalidParams 错误\n end\n```\n\n## 最佳实践\n\n### Schema 选择建议\n\n| 场景 | 推荐方案 |\n|------|----------|\n| 新项目 | Zod v4 或 ArkType（类型推断完善） |\n| 已有 TypeBox 代码 | `fromJsonSchema` + `AjvJsonSchemaValidator` |\n| 轻量级验证 | Valibot（Bundle 体积小） |\n| 简单场景 | Raw Shape 语法 |\n\n### 迁移指南\n\n**从 Zod v3 迁移：**\n\n```typescript\n// Zod v3\nimport { z } from 'zod';\nconst schema = z.object({ name: z.string() });\n\n// Zod v4 (推荐)\nimport { z } from 'zod';\nconst schema = z.object({ name: z.string() }); // 兼容\n\n// 或使用其他库\nimport { type } from 'arktype';\nconst schema = type({ name: 'string' });\n```\n\n**处理 JSON Schema：**\n\n```typescript\nimport { fromJsonSchema, AjvJsonSchemaValidator } from '@modelcontextprotocol/core';\n\n// TypeBox 输出\nconst typeBoxSchema = Type.Strict(Type.Object({ name: Type.String() }));\n\n// 转换为 Standard Schema\nconst standardSchema = fromJsonSchema(\n TypeBox.toJsonSchema(typeBoxSchema),\n new AjvJsonSchemaValidator()\n);\n```\n\n## 相关配置\n\n### AjvJsonSchemaValidator 配置选项\n\n```typescript\nimport Ajv from 'ajv';\n\nconst ajv = new Ajv({\n allErrors: true, // 返回所有错误而非首次错误\n strict: false, // 禁用严格模式\n coerceTypes: false // 禁用类型强制\n});\n\nconst validator = new AjvJsonSchemaValidator(ajv);\n```\n\n## 总结\n\nMCP TypeScript SDK 的数据验证系统提供了灵活且强大的 Schema 支持：\n\n- 通过 **Standard Schema** 规范实现多库统一接口\n- 原生支持 **Zod v4**、Valibot、ArkType 等主流验证库\n- **JSON Schema** 通过 AJV 验证器完整支持\n- **Raw Shape** 语法简化常见使用场景\n- **completable()** 提供字段自动补全能力\n\n这套设计使开发者能够使用自己熟悉的验证库，同时保持与 MCP 协议的完全兼容。\n\n---\n\n\n\n## 传输层实现\n\n### 相关页面\n\n相关主题：[服务器开发指南](#page-6), [客户端开发指南](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/server/src/server/stdio.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/stdio.ts)\n- [packages/server/src/server/streamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/streamableHttp.ts)\n- [packages/client/src/client/stdio.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/stdio.ts)\n- [packages/client/src/client/streamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/streamableHttp.ts)\n- [packages/client/src/client/sse.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/sse.ts)\n- [packages/middleware/node/src/streamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/src/streamableHttp.ts)\n \n\n# 传输层实现\n\nMCP TypeScript SDK 的传输层（Transport Layer）是客户端与服务器之间通信的核心抽象层，负责消息的发送、接收和协议处理。该层实现了多种传输协议，包括 Streamable HTTP、传统 SSE 以及 stdio 方式，以满足不同场景下的集成需求。\n\n## 架构概览\n\n传输层采用接口抽象设计，通过 `Transport` 接口定义统一的通信契约。不同的传输实现（如 HTTP、stdio）都遵循这一接口规范，使得上层业务逻辑与底层传输方式解耦。\n\n```mermaid\ngraph TB\n subgraph \"客户端传输层\"\n C_STDIO[ClientStdioTransport]\n C_HTTP[ClientStreamableHttpTransport]\n C_SSE[ClientSseTransport]\n end\n \n subgraph \"服务端传输层\"\n S_STDIO[ServerStdioTransport]\n S_HTTP[ServerStreamableHttpTransport
WebStandardStreamableHTTPServerTransport]\n S_NODE_HTTP[NodeStreamableHTTPServerTransport]\n end\n \n subgraph \"核心传输接口\"\n Transport[Transport Interface]\n end\n \n C_STDIO --> Transport\n C_HTTP --> Transport\n C_SSE --> Transport\n Transport --> S_STDIO\n Transport --> S_HTTP\n Transport --> S_NODE_HTTP\n```\n\n## 核心接口定义\n\n传输层的核心是 `Transport` 接口，它定义了所有传输实现必须实现的方法和属性。该接口位于核心包中，被客户端和服务端共同依赖。\n\n### Transport 接口契约\n\n| 方法/属性 | 类型 | 描述 |\n|-----------|------|------|\n| `start()` | `Promise` | 启动传输层，开始监听/连接 |\n| `send(message)` | `Promise` | 发送 JSON-RPC 消息 |\n| `close()` | `Promise` | 关闭传输连接 |\n| `onclose` | `() => void` | 连接关闭回调 |\n| `onerror` | `(error: Error) => void` | 错误处理回调 |\n| `onmessage` | `(message: JSONRPCMessage) => void` | 消息接收回调 |\n| `onopen` | `() => void` | 连接打开回调 |\n\n## Streamable HTTP 传输\n\nStreamable HTTP 是 MCP SDK 推荐的主要传输协议，适用于远程服务器通信。该协议支持服务端发送（SSE）进行流式消息推送，同时兼容传统的请求-响应模式。\n\n### 服务端实现\n\n#### WebStandardStreamableHTTPServerTransport\n\n`WebStandardStreamableHTTPServerTransport` 是核心的 Web 标准 HTTP 服务器传输实现，支持两种运行模式：\n\n**有状态模式（Stateful）**：启用会话追踪，适用于需要维护状态的复杂应用场景。\n\n```typescript\nconst transport = new WebStandardStreamableHTTPServerTransport({\n sessionIdGenerator: () => crypto.randomUUID()\n});\n\nawait server.connect(transport);\n```\n\n**无状态模式（Stateless）**：不维护会话状态，适合简单的 API 风格服务器。\n\n```typescript\nconst transport = new WebStandardStreamableHTTPServerTransport({\n sessionIdGenerator: undefined\n});\n```\n\n资料来源：[packages/server/src/server/streamableHttp.ts:1-50]()\n\n#### NodeStreamableHTTPServerTransport\n\n`NodeStreamableHTTPServerTransport` 是针对 Node.js 环境优化的传输实现，内部封装了 `WebStandardStreamableHTTPServerTransport`，并使用 `getRequestListener` 将 Node.js HTTP 请求转换为 Web 标准请求。\n\n```typescript\nconst transport = new NodeStreamableHTTPServerTransport(options);\n\napp.all('/mcp', async c => {\n return transport.handleRequest(c.req.raw);\n});\n```\n\n该传输使用 `WeakMap` 存储每个请求的上下文信息，包括认证信息和解析后的请求体：\n\n```typescript\nprivate _requestContext: WeakMap = new WeakMap();\n```\n\n资料来源：[packages/middleware/node/src/streamableHttp.ts:1-80]()\n\n### 客户端实现\n\n`ClientStreamableHttpTransport` 实现了客户端侧的 Streamable HTTP 通信，支持与服务器的 SSE 消息流交互。\n\n```mermaid\nsequenceDiagram\n participant Client\n participant HttpTransport as ClientStreamableHttpTransport\n participant Server as Streamable HTTP Server\n \n Client->>HttpTransport: 创建传输实例\n Client->>HttpTransport: 调用 start()\n HttpTransport->>Server: 初始化请求\n Server-->>HttpTransport: 返回 SSE 流\n loop 消息循环\n Server->>HttpTransport: SSE 事件 (message)\n HttpTransport->>Client: 触发 onmessage\n Client->>HttpTransport: 调用 send()\n HttpTransport->>Server: POST 请求发送消息\n end\n```\n\n### 核心配置选项\n\nStreamable HTTP 传输支持多种配置选项：\n\n| 配置项 | 类型 | 默认值 | 描述 |\n|--------|------|--------|------|\n| `sessionIdGenerator` | `(() => string) \\| undefined` | `() => crypto.randomUUID()` | 会话 ID 生成器，undefined 表示无状态模式 |\n| `enableJsonResponse` | `boolean` | `false` | 启用纯 JSON 响应模式（禁用 SSE） |\n| `authProvider` | `AuthProvider \\| OAuthClientProvider` | `undefined` | 认证提供者 |\n| `statusLevel` | `number` | `200` | 日志级别阈值 |\n\n## Stdio 传输\n\nStdio（标准输入/输出）传输适用于本地进程集成场景，常见于本地 MCP 服务器或 CLI 工具集成。\n\n```mermaid\ngraph LR\n subgraph \"父进程\"\n ParentStdin[stdin]\n ParentStdout[stdout]\n ParentStderr[stderr]\n end\n \n subgraph \"子进程 MCP Server\"\n ServerStdin[stdin]\n ServerStdout[stdout]\n end\n \n ParentStdin --> ServerStdin\n ServerStdout --> ParentStdout\n```\n\n### 服务端 Stdio 传输\n\n服务端 `StdioServerTransport` 监听标准输入，将接收到的数据解析为 JSON-RPC 消息，并通过标准输出发送响应。\n\n```typescript\nimport { StdioServerTransport } from '@modelcontextprotocol/server';\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n### 客户端 Stdio 传输\n\n客户端 `StdioClientTransport` 通过子进程方式启动 MCP 服务器，通过 stdin/stdout 与服务器进程通信。\n\n```typescript\nimport { StdioClientTransport } from '@modelcontextprotocol/client';\n\nconst transport = new StdioClientTransport({\n command: 'npx',\n args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/dir']\n});\n\nawait client.connect(transport);\n```\n\n## SSE 传输（传统兼容）\n\nSSE（Server-Sent Events）传输是向后兼容的遗留实现，用于支持旧版 MCP 服务器的通信。\n\n### 客户端 SSE 轮询\n\n`SSEClientTransport` 实现了基于 SSE 的轮询机制，定期从服务器获取更新。\n\n```typescript\nconst transport = new SSEClientTransport(\n new URL('http://localhost:3000/mcp')\n);\n\nawait client.connect(transport);\n```\n\n该传输包含以下核心功能：\n\n| 功能 | 描述 |\n|------|------|\n| 消息队列 | 维护待处理消息队列 |\n| 重试机制 | 连接失败时自动重试 |\n| 心跳检测 | 定期发送心跳保持连接 |\n\n## 中间件系统\n\n客户端传输层支持中间件扩展，允许在请求/响应链中插入自定义逻辑。\n\n### 日志中间件\n\n`loggingMiddleware` 提供了请求/响应的详细日志记录功能：\n\n```typescript\nimport { loggingMiddleware } from '@modelcontextprotocol/client';\n\nconst transport = new ClientStreamableHttpTransport(url, {\n requestInit: {\n headers: {\n Authorization: `Bearer ${token}`\n }\n },\n middlewares: [\n loggingMiddleware({\n includeRequestHeaders: true,\n includeResponseHeaders: true,\n statusLevel: 300\n })\n ]\n});\n```\n\n中间件接收和返回 `fetch` 风格的请求/响应，支持请求拦截和响应修改。\n\n### 中间件管道\n\n多个中间件可以组合成管道，按顺序执行：\n\n```typescript\nconst composedMiddleware = composeFetchMiddlewares([middleware1, middleware2, middleware3]);\n```\n\n每个中间件的签名如下：\n\n```typescript\ntype FetchMiddleware = (\n next: FetchFn\n) => (input: RequestInfo, init?: RequestInit) => Promise;\n```\n\n## 认证集成\n\n传输层内置了对 OAuth 2.0 和 Bearer Token 认证的支持。\n\n### AuthProvider 接口\n\n```typescript\ninterface AuthProvider {\n token(): Promise;\n onUnauthorized?(ctx: AuthContext): Promise;\n}\n```\n\n### Bearer Token 认证\n\n简单的 Bearer Token 认证可以通过对象字面量实现：\n\n```typescript\nconst transport = new ClientStreamableHttpTransport(url, {\n authProvider: {\n token: async () => myApiKey\n }\n});\n```\n\n### OAuth 认证\n\nOAuth 客户端提供者会被传输自动适配，无需额外配置：\n\n```typescript\nimport { OAuthClientProvider } from '@modelcontextprotocol/core';\n\nconst oauthProvider: OAuthClientProvider = {\n getAccessToken: () => Promise.resolve(token),\n setAccessToken: (token) => { /* ... */ }\n};\n\nconst transport = new ClientStreamableHttpTransport(url, {\n authProvider: oauthProvider\n});\n```\n\n传输层在每次请求前调用 `authProvider.token()` 获取令牌，在收到 401 响应时调用 `onUnauthorized()` 进行重试。\n\n## 使用示例\n\n### 运行服务端示例\n\n```bash\n# 从仓库根目录运行\npnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts\n\n# 或从包目录运行\ncd examples/server\npnpm tsx src/simpleStreamableHttp.ts\n```\n\n### 运行客户端示例\n\n```bash\n# 客户端需要先启动服务器\npnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts\n```\n\n### 兼容模式客户端\n\n向后兼容的客户端会优先尝试 Streamable HTTP，失败时回退到 SSE：\n\n```typescript\n// 使用 streamableHttpWithSseFallbackClient\npnpm --filter @modelcontextprotocol/examples-client exec tsx src/streamableHttpWithSseFallbackClient.ts\n```\n\n资料来源：[examples/server/README.md:1-60]()\n\n## 总结\n\nMCP TypeScript SDK 的传输层设计遵循了以下原则：\n\n1. **接口抽象**：通过 `Transport` 接口统一不同传输实现的契约\n2. **环境适配**：提供 Web 标准、Node.js 和 stdio 三种环境的专用传输\n3. **向后兼容**：通过 SSE 传输支持遗留服务器\n4. **扩展性**：中间件系统允许灵活扩展传输功能\n5. **安全性**：内置 OAuth 和 Bearer Token 认证支持\n\n开发者应根据具体场景选择合适的传输方式：远程服务推荐使用 Streamable HTTP，本地进程集成使用 stdio，遗留系统使用 SSE 传输。\n\n---\n\n\n\n## 服务器开发指南\n\n### 相关页面\n\n相关主题：[客户端开发指南](#page-7), [认证与授权机制](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/server/src/server/mcp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/mcp.ts)\n- [packages/server/src/server/server.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/server.ts)\n- [examples/server/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)\n- [examples/server/src/simpleStreamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts)\n- [docs/server.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md)\n- [docs/server-quickstart.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server-quickstart.md)\n \n\n# 服务器开发指南\n\n## 概述\n\n服务器开发指南旨在帮助开发者使用 MCP TypeScript SDK 构建 MCP 服务器。MCP（Model Context Protocol）服务器是向 LLM（大语言模型）提供工具、资源和提示的桥梁，使 AI 能够与外部系统交互并执行实际操作。\n\nMCP SDK 提供两种服务器实现层级：\n\n1. **基础 Server 类** (`packages/server/src/server/server.ts`) - 低层级协议封装，处理 JSON-RPC 消息路由\n2. **McpServer 类** (`packages/server/src/server/mcp.ts`) - 高层级 API，简化资源/工具/提示的注册流程\n\n资料来源：[examples/server/README.md:1-10]()\n\n## 架构设计\n\n### 服务器层级结构\n\n```mermaid\ngraph TD\n A[McpServer 高层API] --> B[Server 基础协议类]\n B --> C[Protocol 协议处理核心]\n C --> D[Transport 传输层]\n \n A --> E[工具注册]\n A --> F[资源注册]\n A --> G[提示注册]\n \n style A fill:#e1f5fe\n style B fill:#fff3e0\n style C fill:#f3e5f5\n```\n\n### 核心组件职责\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| McpServer | `packages/server/src/server/mcp.ts` | 提供工具、资源、提示的注册接口 |\n| Server | `packages/server/src/server/server.ts` | 处理 JSON-RPC 协议、请求/响应关联 |\n| Protocol | `packages/core/src/shared/protocol.ts` | 消息路由、能力协商、传输管理 |\n\n资料来源：[CLAUDE.md:25-35]()\n\n## 快速开始\n\n### 环境准备\n\n```bash\n# 安装依赖\npnpm install\n\n# 运行服务器示例\npnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts\n```\n\n### 基础服务器创建\n\n```typescript\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StreamableHTTPTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\nimport { z } from \"zod\";\n\nconst server = new McpServer({\n name: \"my-server\",\n version: \"1.0.0\",\n});\n\n// 注册工具\nserver.tool(\n \"calculate\",\n \"执行数学计算\",\n { a: z.number(), b: z.number(), operation: z.enum([\"add\", \"subtract\"]) },\n async ({ a, b, operation }) => {\n const result = operation === \"add\" ? a + b : a - b;\n return { result };\n }\n);\n\n// 启动服务器\nconst transport = new StreamableHTTPTransport();\nawait server.connect(transport);\nawait transport.start();\n```\n\n资料来源：[docs/server-quickstart.md:1-30]()\n\n## 工具注册\n\n### 工具注册 API\n\nMcpServer 提供 `tool()` 方法注册工具，支持两种调用形式：\n\n```typescript\n// 标准 Schema 形式\nserver.tool(\n name: string,\n description: string,\n argsSchema: T,\n cb: ToolCallback\n): RegisteredTool\n\n// 废弃的 Zod Raw Shape 形式（自动包装为 z.object()）\nserver.tool(\n name: string,\n description: string,\n argsSchema: T,\n cb: LegacyToolCallback\n): RegisteredTool\n```\n\n### 工具注册参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 工具唯一标识名 |\n| description | string | 是 | 工具功能描述 |\n| argsSchema | ZodSchema/ZodRawShape | 是 | 参数验证 Schema |\n| cb | ToolCallback | 是 | 工具执行回调函数 |\n\n资料来源：[packages/server/src/server/mcp.ts:150-180]()\n\n### 工具动态管理\n\n注册后的工具返回 `RegisteredTool` 对象，支持运行时动态更新：\n\n```typescript\nconst tool = server.tool(\"greet\", \"问候用户\", { name: z.string() }, async ({ name }) => {\n return { message: `Hello, ${name}!` };\n});\n\n// 动态更新\ntool.update({\n title: \"新标题\",\n description: \"新描述\",\n enabled: false,\n callback: async ({ name }) => ({ message: `Hi, ${name}!` })\n});\n\n// 启用/禁用\ntool.enable();\ntool.disable();\n\n// 删除工具\ntool.remove();\n```\n\n工具更新时，如果修改了 `paramsSchema` 或 `callback`，系统会自动重新生成执行器：\n\n```typescript\nif (updates.paramsSchema !== undefined) {\n registeredTool.inputSchema = updates.paramsSchema;\n needsExecutorRegen = true;\n}\nif (updates.callback !== undefined) {\n registeredTool.handler = updates.callback;\n needsExecutorRegen = true;\n}\n```\n\n资料来源：[packages/server/src/server/mcp.ts:200-240]()\n\n## 资源注册\n\n### 资源类型\n\nMCP 服务器可暴露两类资源：\n\n1. **静态资源** (`Resource`) - 固定 URI 的资源\n2. **资源模板** (`ResourceTemplate`) - 支持 URI 参数化的动态资源\n\n### 注册静态资源\n\n```typescript\nserver.resource(\n \"config\",\n \"app://config\",\n (uri: URL) => {\n return {\n contents: [{\n uri: uri.toString(),\n mimeType: \"application/json\",\n text: JSON.stringify({ theme: \"dark\", language: \"zh\" })\n }]\n };\n }\n);\n```\n\n### 注册资源模板\n\n```typescript\nserver.resourceTemplate(\n \"user-profile\",\n \"users://{userId}/profile\",\n ({ userId }: { userId: string }) => {\n return {\n contents: [{\n uri: `users://${userId}/profile`,\n mimeType: \"application/json\",\n text: fetchUserProfile(userId)\n }]\n };\n }\n);\n```\n\n### 资源生命周期管理\n\n| 方法 | 说明 |\n|------|------|\n| `disable()` | 禁用资源（仍保留但不可访问） |\n| `enable()` | 启用资源 |\n| `remove()` | 移除资源 |\n| `update(updates)` | 更新资源属性 |\n\n资源更新后自动发送 `resourceListChanged` 通知：\n\n```typescript\nupdate: updates => {\n if (updates.uri !== undefined && updates.uri !== uri) {\n delete this._registeredResources[uri];\n if (updates.uri) this._registeredResources[updates.uri] = registeredResource;\n }\n if (updates.name !== undefined) registeredResource.name = updates.name;\n if (updates.enabled !== undefined) registeredResource.enabled = updates.enabled;\n this.sendResourceListChanged();\n}\n```\n\n资料来源：[packages/server/src/server/mcp.ts:280-350]()\n\n## 提示注册\n\n### 提示注册 API\n\n```typescript\nserver.registerPrompt(\n \"code-review\",\n {\n title: \"代码审查\",\n description: \"生成代码审查请求\",\n argsSchema: z.object({\n code: z.string(),\n language: z.string().optional()\n })\n },\n async ({ code, language }) => ({\n messages: [{\n role: \"user\",\n content: {\n type: \"text\",\n text: `请审查以下${language || \"\"}代码：\\n\\n${code}`\n }\n }]\n })\n);\n```\n\n### 提示参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| name | string | 提示唯一标识 |\n| config.title | string | 显示标题 |\n| config.description | string | 功能描述 |\n| config.argsSchema | ZodSchema | 参数验证 Schema |\n| cb | PromptCallback | 返回消息数组的异步函数 |\n\n资料来源：[packages/server/src/server/mcp.ts:180-210]()\n\n## 服务器运行模式\n\n### Streamable HTTP 模式（有状态）\n\n适用于需要会话跟踪、任务管理的复杂服务器：\n\n```typescript\nimport { StreamableHTTPTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\n\nconst transport = new StreamableHTTPTransport({\n sessionIdGenerator: () => crypto.randomUUID(),\n});\n\nawait server.connect(transport);\n```\n\n### Streamable HTTP 模式（无状态）\n\n适用于简单的 API 风格服务器，无会话跟踪：\n\n```typescript\nimport { StreamableHTTPTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\n\nconst transport = new StreamableHTTPTransport();\nawait server.connect(transport);\n```\n\n### JSON 响应模式\n\n仅使用 JSON 响应，不支持 SSE：\n\n```typescript\nimport { JSONResponseStreamableHttpTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\n\nconst transport = new JSONResponseStreamableHttpTransport();\nawait server.connect(transport);\n```\n\n资料来源：[examples/server/README.md:25-45]()\n\n## 错误处理\n\n### SDK 错误码\n\n```typescript\nimport { SdkError, SdkErrorCode } from \"@modelcontextprotocol/sdk\";\n\ntry {\n await server.requestHandler.handleRequest(request);\n} catch (error) {\n if (error instanceof SdkError) {\n switch (error.code) {\n case SdkErrorCode.InvalidRequest:\n // 处理无效请求\n break;\n case SdkErrorCode.MethodNotFound:\n // 方法未找到\n break;\n case SdkErrorCode.CapabilityNotSupported:\n // 能力不支持\n break;\n }\n }\n}\n```\n\n资料来源：[packages/core/CHANGELOG.md:10-15]()\n\n## 示例服务器索引\n\n| 场景 | 描述 | 文件 |\n|------|------|------|\n| 有状态 Streamable HTTP | 功能丰富的服务器，支持工具/资源/提示、日志、任务、采样 | `src/simpleStreamableHttp.ts` |\n| 无状态 Streamable HTTP | 无会话跟踪，适合简单 API 服务器 | `src/simpleStatelessStreamableHttp.ts` |\n| 资源服务器 OAuth | 使用 `mcpAuthMetadataRouter` 的最小 OAuth RS | `src/resourceServerOnly.ts` |\n| JSON 响应模式 | 仅 JSON 响应的 Streamable HTTP | `src/jsonResponseStreamableHttp.ts` |\n\n资料来源：[examples/server/README.md:28-40]()\n\n## 下一步\n\n- 查看 [客户端开发指南](./client.md) 了解如何连接到此服务器\n- 阅读 [协议规范文档](./protocol.md) 深入理解底层协议\n- 参考 [示例代码库](../examples/server/) 获取完整实现\n\n---\n\n\n\n## 客户端开发指南\n\n### 相关页面\n\n相关主题：[服务器开发指南](#page-6), [Web 框架中间件集成](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/client/src/client/client.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/client.ts)\n- [examples/client/src/clientGuide.examples.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/clientGuide.examples.ts)\n- [examples/client-quickstart/src/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client-quickstart/src/index.ts)\n- [docs/client-quickstart.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/client-quickstart.md)\n- [docs/client.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/client.md)\n \n\n# 客户端开发指南\n\n## 概述\n\nMCP TypeScript SDK 的客户端开发模块位于 `packages/client` 包中，提供了与 MCP 服务器通信的完整能力。该模块基于核心协议层构建，封装了 JSON-RPC 消息处理、请求/响应关联、能力协商和传输层管理等功能。客户端支持 Streamable HTTP 传输协议，这是 MCP V2 规范定义的主要通信方式。\n\n## 核心架构\n\n### 客户端层次结构\n\nMCP SDK 采用三层架构设计，客户端位于最上层：\n\n| 层级 | 位置 | 职责 |\n|------|------|------|\n| 类型层 | `packages/core/src/types/types.ts` | 定义 MCP 协议的 TypeScript 类型和 Zod Schema |\n| 协议层 | `packages/core/src/shared/protocol.ts` | 处理 JSON-RPC 路由、能力协商和消息分发 |\n| 客户端层 | `packages/client/src/client/client.ts` | 提供面向用户的 MCP 操作接口 |\n\n### 客户端与协议层关系\n\n```mermaid\ngraph TD\n A[Client 实例] --> B[Protocol 基类]\n B --> C[Transport 传输层]\n C --> D[Streamable HTTP]\n \n A --> E[工具调用]\n A --> F[资源访问]\n A --> G[提示模板]\n A --> H[采样请求]\n A --> I[任务管理]\n \n E --> B\n F --> B\n G --> B\n H --> B\n I --> B\n```\n\n## 安装与配置\n\n### 依赖安装\n\n```bash\npnpm add @modelcontextprotocol/client\n```\n\n### 基本导入\n\n```typescript\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';\n```\n\n## 客户端初始化\n\n### 创建客户端实例\n\n客户端初始化需要提供服务器能力信息和连接配置：\n\n```typescript\nconst transport = new StreamableHTTPClientTransport({\n url: new URL('http://localhost:3000/mcp'),\n requestOptions: {\n headers: {\n Authorization: 'Bearer your-token-here'\n }\n }\n});\n\nconst client = new Client(\n {\n name: 'example-client',\n version: '1.0.0'\n },\n {\n capabilities: {\n resources: {},\n tools: {},\n prompts: {},\n sampling: {}\n }\n }\n);\n```\n\n### 连接到服务器\n\n```typescript\nawait client.connect(transport);\n```\n\n连接过程会触发服务器能力协商，确认双方支持的 MCP 功能范围。\n\n## 核心功能\n\n### 工具调用\n\n工具是 MCP 服务器暴露的可执行函数，客户端可以调用这些工具获取计算结果或执行特定操作。\n\n```mermaid\nsequenceDiagram\n 客户端->>服务器: 调用工具 (tools/call)\n 服务器->>服务器: 执行工具逻辑\n 服务器-->>客户端: 工具结果\n```\n\n#### 调用单个工具\n\n```typescript\nconst result = await client.callTool({\n name: 'calculate',\n arguments: { expression: '2 + 2' }\n});\n```\n\n#### 并行调用多个工具\n\n```typescript\nconst results = await Promise.all([\n client.callTool({ name: 'tool-a', arguments: { id: 1 } }),\n client.callTool({ name: 'tool-b', arguments: { id: 2 } }),\n client.callTool({ name: 'tool-c', arguments: { id: 3 } })\n]);\n```\n\n### 资源管理\n\n资源是服务器提供的只读数据源，客户端可以列出、读取和订阅资源变更通知。\n\n#### 列出可用资源\n\n```typescript\nconst resourceList = await client.listResources();\nfor (const resource of resourceList.resources) {\n console.log(`${resource.name}: ${resource.uri}`);\n}\n```\n\n#### 读取资源内容\n\n```typescript\nconst resourceContent = await client.readResource({\n uri: 'file:///config/app.json'\n});\n```\n\n#### 订阅资源变更\n\n```typescript\nawait client.subscribeResource({ uri: 'file:///config/app.json' });\n\n// 设置资源更新处理器\nclient.setRequestHandler(ResourceUpdatedNotificationSchema, (notification) => {\n console.log('资源已更新:', notification.params.uri);\n return Promise.resolve();\n});\n```\n\n### 提示模板\n\n提示模板允许服务器定义可参数化的消息模板，客户端可以获取并使用这些模板。\n\n#### 列出可用提示\n\n```typescript\nconst promptList = await client.listPrompts();\n```\n\n#### 获取提示内容\n\n```typescript\nconst prompt = await client.getPrompt({\n name: 'code-review',\n arguments: { code: 'const x = 1;' }\n});\n\n// prompt.messages 包含渲染后的消息数组\nfor (const message of prompt.messages) {\n console.log(`${message.role}: ${message.content}`);\n}\n```\n\n### 采样请求\n\n采样功能允许服务器向客户端请求采样数据，通常用于 AI 模型的调用。\n\n```typescript\nconst sample = await client.createMessage({\n messages: [{ role: 'user', content: { type: 'text', text: 'Hello' } }],\n systemPrompt: 'You are a helpful assistant.',\n maxTokens: 100\n});\n```\n\n## 认证机制\n\n### AuthProvider 接口\n\nSDK 提供了灵活的认证机制，通过 `AuthProvider` 接口实现可组合的认证功能：\n\n```typescript\ninterface AuthProvider {\n token(): Promise;\n onUnauthorized?(ctx: AuthorizationCtx): Promise;\n}\n```\n\n### 简单Bearer Token认证\n\n对于简单的 API 密钥或网关管理的令牌，可以使用对象字面量：\n\n```typescript\nconst client = new Client({ name: 'my-app', version: '1.0.0' }, { capabilities: {} });\n\nawait client.connect(transport, {\n authProvider: {\n token: async () => 'my-api-key'\n }\n});\n```\n\n### OAuth 认证\n\nOAuth 认证由 `OAuthClientProvider` 提供，传输层会自动适配：\n\n```typescript\nimport { adaptOAuthProvider } from '@modelcontextprotocol/sdk/client/auth.js';\n\nconst oauthProvider = new MyOAuthProvider(config);\nawait client.connect(transport, {\n authProvider: adaptOAuthProvider(oauthProvider)\n});\n```\n\n认证流程如下：\n\n```mermaid\ngraph LR\n A[发起请求] --> B{获取Token}\n B --> C[发送带Token的请求]\n C --> D{响应状态}\n D -->|200| E[成功]\n D -->|401| F[onUnauthorized]\n F --> G[重试请求]\n G --> E\n```\n\n## 传输层配置\n\n### Streamable HTTP 传输\n\nStreamable HTTP 是 V2 版本的主要传输协议，支持服务端推送和流式响应：\n\n```typescript\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';\n\nconst transport = new StreamableHTTPClientTransport({\n url: new URL('http://localhost:3000/mcp'),\n requestOptions: {\n headers: {\n 'Content-Type': 'application/json'\n }\n },\n // 启用SSE回落机制\n sseFallbackEnabled: true\n});\n```\n\n### SSE 回落机制\n\n客户端支持自动回落机制，当 Streamable HTTP 返回 4xx 错误时，自动切换到传统 SSE 轮询模式：\n\n```typescript\nconst client = new Client({ name: 'fallback-client', version: '1.0.0' }, { capabilities: {} });\nconst transport = new StreamableHTTPClientTransport({\n url: new URL('http://localhost:3000/mcp'),\n sseFallbackEnabled: true\n});\nawait client.connect(transport);\n```\n\n## 错误处理\n\n### 连接错误\n\n```typescript\ntry {\n await client.connect(transport);\n} catch (error) {\n if (error instanceof ConnectionError) {\n console.error('连接失败:', error.message);\n }\n}\n```\n\n### 请求错误\n\n```typescript\ntry {\n const result = await client.callTool({\n name: 'risky-operation',\n arguments: {}\n });\n} catch (error) {\n if (error instanceof ToolExecutionError) {\n console.error('工具执行错误:', error.message);\n }\n}\n```\n\n## 完整示例\n\n### 交互式客户端\n\n以下示例展示了完整的客户端使用流程：\n\n```typescript\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';\n\nasync function main() {\n // 初始化传输层\n const transport = new StreamableHTTPClientTransport({\n url: new URL('http://localhost:3000/mcp')\n });\n\n // 创建客户端\n const client = new Client(\n { name: 'interactive-client', version: '1.0.0' },\n { capabilities: { resources: {}, tools: {}, prompts: {} } }\n );\n\n // 连接服务器\n await client.connect(transport);\n console.log('已连接到 MCP 服务器');\n\n // 列出资源\n const { resources } = await client.listResources();\n console.log(`发现 ${resources.length} 个资源`);\n\n // 调用工具\n const toolResult = await client.callTool({\n name: 'greeting',\n arguments: { name: 'World' }\n });\n console.log('工具响应:', toolResult);\n\n // 获取提示\n const prompt = await client.getPrompt({\n name: 'welcome',\n arguments: { user: 'Developer' }\n });\n console.log('提示内容:', prompt.messages);\n\n // 断开连接\n await client.close();\n}\n\nmain().catch(console.error);\n```\n\n### 带认证的客户端\n\n```typescript\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';\n\nasync function authenticatedClient() {\n const transport = new StreamableHTTPClientTransport({\n url: new URL('https://api.example.com/mcp'),\n requestOptions: {\n headers: {\n 'X-API-Key': process.env.API_KEY\n }\n }\n });\n\n const client = new Client(\n { name: 'secure-client', version: '1.0.0' },\n { capabilities: { tools: {}, resources: {} } }\n );\n\n await client.connect(transport, {\n authProvider: {\n token: async () => process.env.AUTH_TOKEN,\n onUnauthorized: async (ctx) => {\n // 刷新令牌逻辑\n const newToken = await refreshToken();\n ctx.retried = true;\n }\n }\n });\n\n return client;\n}\n```\n\n## 实验性功能\n\n实验性功能通过 `@modelcontextprotocol/sdk/client/experimental` 模块导出：\n\n```typescript\nimport { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/client/experimental';\n\n// 任务存储配置\nconst taskStore = new InMemoryTaskStore();\n```\n\n## 最佳实践\n\n| 实践 | 说明 |\n|------|------|\n| 单一职责 | 每个客户端实例专注于一个服务器连接 |\n| 错误处理 | 始终使用 try-catch 包装异步操作 |\n| 资源清理 | 使用完毕后调用 `client.close()` |\n| 认证管理 | 将令牌刷新逻辑放在 `onUnauthorized` 回调中 |\n| 类型安全 | 使用 Zod Schema 验证工具参数 |\n\n## 相关资源\n\n- [MCP 规范文档](https://modelcontextprotocol.io/specification/latest)\n- [服务器开发指南](./server.md)\n- [客户端快速开始](./client-quickstart.md)\n- [examples/client](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/client)\n\n---\n\n\n\n## 认证与授权机制\n\n### 相关页面\n\n相关主题：[Web 框架中间件集成](#page-9), [实验性功能与任务系统](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/shared/auth.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/shared/auth.ts)\n- [packages/core/src/shared/authUtils.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/shared/authUtils.ts)\n- [packages/client/src/client/auth.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/auth.ts)\n- [packages/client/src/client/authExtensions.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/authExtensions.ts)\n- [packages/client/src/client/crossAppAccess.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/crossAppAccess.ts)\n- [packages/middleware/express/src/auth/bearerAuth.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/src/auth/bearerAuth.ts)\n \n\n# 认证与授权机制\n\n## 概述\n\nMCP TypeScript SDK 提供了一套完整的认证与授权机制，支持多种认证方式，包括 Bearer Token 认证、OAuth 2.0 认证以及可组合的自定义认证提供者。该机制设计为传输层无关，可与 Streamable HTTP、SSE 等传输协议配合使用，为 MCP 客户端和服务器之间的安全通信提供保障。\n\n认证系统的核心设计理念是通过统一的 `AuthProvider` 接口抽象不同的认证方式，使得开发者可以根据实际需求选择或组合使用 Bearer Token、OAuth 等认证策略。资料来源：[packages/client/CHANGELOG.md]()\n\n## 核心架构\n\n### 认证提供者体系\n\nMCP SDK 的认证体系采用分层架构设计，核心包含以下组件：\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| AuthProvider | packages/core/src/shared/auth.ts | 认证提供者核心接口 |\n| OAuthClientProvider | packages/client/src/client/auth.ts | OAuth 客户端实现 |\n| BearerAuthMiddleware | packages/middleware/express/src/auth/bearerAuth.ts | Bearer Token 中间件 |\n| adaptOAuthProvider | packages/client/src/client/auth.ts | OAuth 适配器 |\n\n资料来源：[packages/client/CHANGELOG.md](), [packages/core/src/shared/auth.ts]()\n\n### 认证流程架构图\n\n```mermaid\ngraph TD\n A[Client Request] --> B{AuthProvider}\n B -->|Bearer Token| C[Token 获取]\n B -->|OAuth| D[OAuth Flow]\n C --> E[Authorization Header]\n D --> F[Token Exchange]\n F --> G[Access Token]\n G --> E\n E --> H[Server Validation]\n H -->|401| I[onUnauthorized]\n I -->|Retry| B\n H -->|200| J[Request Success]\n```\n\n## AuthProvider 接口\n\n`AuthProvider` 是认证系统的核心接口，定义了两个关键方法：\n\n```typescript\nexport interface AuthProvider {\n token(): Promise;\n onUnauthorized?(ctx): Promise;\n}\n```\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| token | Promise | 返回认证令牌，若返回 undefined 则跳过认证 |\n| onUnauthorized | Promise (可选) | 收到 401 响应时的回调，可用于重新认证 |\n\n资料来源：[packages/client/CHANGELOG.md]()\n\n### Bearer Token 认证方式\n\n对于简单的场景，可以使用对象字面量形式快速配置 Bearer Token：\n\n```typescript\nconst client = createClient({\n authProvider: {\n token: async () => myApiKey\n }\n});\n```\n\n这种方式的优点是配置简洁，无需创建类实例，适合 API Key、网关托管令牌等场景。资料来源：[packages/client/CHANGELOG.md]()\n\n## OAuth 认证\n\n### OAuthClientProvider\n\nSDK 提供了完整的 OAuth 客户端认证支持：\n\n```typescript\nexport interface OAuthClientProvider {\n // OAuth 认证核心方法\n auth(provider: {\n serverUrl: string;\n resourceMetadataUrl?: string;\n scope?: string;\n fetchFn: typeof fetch;\n }): Promise<'REDIRECT' | 'AUTHORIZED' | 'UNAUTHORIZED'>;\n}\n```\n\n资料来源：[packages/client/CHANGELOG.md]()\n\n### OAuth 认证流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant MCP_Server as MCP Server\n participant OAuth_Provider as OAuth Provider\n \n Client->>MCP_Server: Request with token()\n MCP_Server->>MCP_Server: Validate Token\n alt Token Invalid (401)\n MCP_Server->>Client: 401 Unauthorized\n Client->>OAuth_Provider: auth() with REDIRECT\n OAuth_Provider->>Client: Authorization URL\n Client->>OAuth_Provider: User Login\n OAuth_Provider->>Client: Authorization Code\n Client->>OAuth_Provider: Token Exchange\n OAuth_Provider->>Client: Access Token\n Client->>MCP_Server: Retry with new token\n end\n```\n\n### adaptOAuthProvider 适配器\n\n对于已有的 `OAuthClientProvider` 实现，SDK 提供 `adaptOAuthProvider()` 函数进行适配，无需修改现有代码：\n\n```typescript\nimport { adaptOAuthProvider } from '@modelcontextprotocol/client';\n\n// 适配已有的 OAuth 提供者\nconst adaptedProvider = adaptOAuthProvider(existingOAuthProvider);\n```\n\n资料来源：[packages/client/CHANGELOG.md]()\n\n## Bearer 认证中间件\n\n### bearerAuthMiddleware\n\nExpress 中间件实现了 Bearer Token 认证验证逻辑：\n\n```typescript\nexport function bearerAuthMiddleware(\n options: BearerAuthOptions\n): RequestHandler {\n // 实现 Bearer Token 验证逻辑\n}\n```\n\n| 配置项 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| token | string \\| () => string \\| Promise | 是 | Bearer Token 或返回 Token 的函数 |\n| realm | string | 否 | 认证域，用于 WWW-Authenticate 头 |\n| prefix | string | 否 | Token 前缀，默认为 'Bearer ' |\n| skip | (req: Request) => boolean | 否 | 跳过认证的条件函数 |\n\n资料来源：[packages/middleware/express/src/auth/bearerAuth.ts]()\n\n### requireBearerAuth 工具函数\n\n中间件导出 `requireBearerAuth` 函数用于简化认证配置：\n\n```typescript\nconst { bearerAuthMiddleware, requireBearerAuth } = createBearerAuth({\n token: () => process.env.BEARER_TOKEN\n});\n```\n\n资料来源：[packages/middleware/express/src/auth/bearerAuth.ts]()\n\n## 资源访问控制\n\n### URL 路径匹配\n\n`authUtils.ts` 提供了资源访问控制的核心工具函数 `matchesResource`：\n\n```typescript\nexport function matchesResource(requestedResource: URL | string, configuredResource: URL | string): boolean\n```\n\n该函数通过以下规则判断请求的资源是否在允许范围内：\n\n| 匹配条件 | 说明 |\n|----------|------|\n| Origin 匹配 | 协议、域名和端口必须一致 |\n| 路径前缀匹配 | 请求路径必须以配置的路径开头 |\n| 尾部斜杠处理 | 智能处理带斜杠和不带斜杠的路径 |\n\n```typescript\n// 路径匹配示例\nmatchesResource('https://example.com/api/users', 'https://example.com/api'); // true\nmatchesResource('https://example.com/api123', 'https://example.com/api'); // false\n```\n\n资料来源：[packages/core/src/shared/authUtils.ts]()\n\n### 资源匹配逻辑详解\n\n```mermaid\ngraph TD\n A[解析 requestedResource] --> B[解析 configuredResource]\n B --> C{Origin 相同?}\n C -->|否| D[返回 false]\n C -->|是| E{路径长度足够?}\n E -->|否| D\n E -->|是| F[添加尾部斜杠]\n F --> G[比较路径前缀]\n G --> H{匹配成功?}\n H -->|是| I[返回 true]\n H -->|否| D\n```\n\n## 认证中间件\n\n### createMiddleware\n\nSDK 提供了 `createMiddleware` 工厂函数用于创建自定义认证中间件：\n\n```typescript\nexport function createMiddleware(\n handler: (next: typeof fetch, input: RequestInfo, init?: RequestInit) => Promise\n): MiddlewareFunction\n```\n\n资料来源：[packages/client/src/client/middleware.ts]()\n\n### 认证中间件工作流程\n\n```mermaid\ngraph TD\n A[Request Incoming] --> B{AuthProvider.token()}\n B -->|返回 token| C[添加 Authorization 头]\n B -->|返回 undefined| D[跳过认证]\n C --> E[发送请求到 next]\n D --> E\n E --> F{Response 401?}\n F -->|是| G{cb.onUnauthorized?}\n F -->|否| H[返回 Response]\n G -->|存在| I[调用 onUnauthorized]\n G -->|不存在| J[抛出 UnauthorizedError]\n I --> K[重试请求]\n K --> H\n J --> L[终止流程]\n```\n\n### 中间件示例\n\n**自定义认证中间件：**\n\n```typescript\nconst customAuthMiddleware = createMiddleware(async (next, input, init) => {\n const headers = new Headers(init?.headers);\n headers.set('X-Custom-Auth', 'my-token');\n \n const response = await next(input, { ...init, headers });\n \n if (response.status === 401) {\n console.log('Authentication failed');\n }\n \n return response;\n});\n```\n\n**条件认证中间件：**\n\n```typescript\nconst conditionalMiddleware = createMiddleware(async (next, input, init) => {\n const url = typeof input === 'string' ? input : input.toString();\n \n if (url.includes('/api/')) {\n const headers = new Headers(init?.headers);\n headers.set('X-API-Version', 'v2');\n return next(input, { ...init, headers });\n }\n \n return next(input, init);\n});\n```\n\n资料来源：[packages/client/src/client/middleware.ts]()\n\n## 跨应用访问控制\n\n### CrossAppAccess 认证\n\n`crossAppAccess.ts` 实现了跨应用程序访问的认证机制，支持对特定资源路径的细粒度访问控制：\n\n```typescript\nexport interface CrossAppAccessAuth {\n validateCrossAppRequest(requestedResource: string): Promise;\n}\n```\n\n| 功能 | 说明 |\n|------|------|\n| 路径验证 | 验证请求的资源路径是否符合配置 |\n| 跨域控制 | 防止跨应用的未授权访问 |\n| 前缀匹配 | 支持目录级别的访问控制 |\n\n资料来源：[packages/client/src/client/crossAppAccess.ts]()\n\n## 日志记录\n\n### RequestLogger\n\n认证系统支持详细的日志记录，便于调试和审计：\n\n```typescript\nexport type RequestLogger = (input: {\n method: string;\n url: string | URL;\n status: number;\n statusText: string;\n duration: number;\n requestHeaders?: Headers;\n responseHeaders?: Headers;\n error?: Error;\n}) => void;\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| method | string | HTTP 方法 |\n| url | string \\| URL | 请求 URL |\n| status | number | 响应状态码 |\n| statusText | string | 响应状态文本 |\n| duration | number | 请求耗时（毫秒） |\n| requestHeaders | Headers | 请求头 |\n| responseHeaders | Headers | 响应头 |\n| error | Error | 错误对象（若有） |\n\n资料来源：[packages/client/src/client/middleware.ts]()\n\n## Session 管理\n\n### Session Cookie 处理\n\n认证服务器使用 Cookie 机制管理用户会话：\n\n```typescript\nfunction getUserSessionCookie(cookieHeader?: string): { \n userId: string; \n name: string; \n timestamp: number \n} | null\n```\n\n该函数解析 `demo_session` Cookie 并返回用户会话信息。Cookie 存储的用户信息包括：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| userId | string | 用户唯一标识 |\n| name | string | 用户名称 |\n| timestamp | number | 会话创建时间戳 |\n\n资料来源：[examples/shared/src/authServer.ts]()\n\n### 认证流程中的 Session 处理\n\n```mermaid\ngraph LR\n A[用户登录] --> B[创建 Session]\n B --> C[设置 Set-Cookie]\n C --> D[浏览器存储 Cookie]\n D --> E[后续请求自动携带 Cookie]\n E --> F[服务端验证 Session]\n```\n\n## 最佳实践\n\n### 认证配置建议\n\n| 场景 | 推荐方案 |\n|------|----------|\n| 简单 API Key | 使用对象字面量 `authProvider: { token: async () => key }` |\n| OAuth 认证 | 实现 `OAuthClientProvider` 并使用 `adaptOAuthProvider` |\n| 多认证方式 | 实现自定义 `AuthProvider`，组合多种认证策略 |\n| 资源访问控制 | 使用 `matchesResource` 进行路径验证 |\n\n### 安全注意事项\n\n1. **Token 存储**：避免在前端代码中硬编码敏感 Token\n2. **HTTPS 传输**：确保所有认证请求通过 HTTPS 进行\n3. **Token 刷新**：实现 `onUnauthorized` 回调处理 Token 过期\n4. **错误处理**：妥善处理认证失败情况，避免信息泄露\n\n资料来源：[packages/client/CHANGELOG.md](), [packages/middleware/express/src/auth/bearerAuth.ts]()\n\n## 相关资源\n\n- [认证与授权官方文档](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/auth.md)\n- [Express 中间件示例](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/middleware/express)\n- [OAuth 示例服务器](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/shared/src/authServer.ts)\n\n---\n\n\n\n## Web 框架中间件集成\n\n### 相关页面\n\n相关主题：[传输层实现](#page-5), [实验性功能与任务系统](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/middleware/express/src/express.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/src/express.ts)\n- [packages/middleware/hono/src/hono.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/src/hono.ts)\n- [packages/middleware/fastify/src/fastify.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/src/fastify.ts)\n- [packages/middleware/express/src/middleware/hostHeaderValidation.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/src/middleware/hostHeaderValidation.ts)\n- [packages/middleware/hono/src/middleware/hostHeaderValidation.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/src/middleware/hostHeaderValidation.ts)\n- [packages/middleware/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/README.md)\n \n\n# Web 框架中间件集成\n\n## 概述\n\nModel Context Protocol (MCP) TypeScript SDK 提供了与主流 Web 框架的中间件集成支持，使开发者能够将 MCP 服务器无缝嵌入到现有的 Express、Hono 和 Fastify 应用中。这些中间件适配器充当 MCP 传输层与 Web 框架之间的桥梁，实现了标准化的请求处理和响应流式传输机制。\n\n中间件集成的核心价值在于：开发者无需构建独立的 MCP 服务器进程，而是可以直接在现有的 Web 应用中暴露 MCP 工具、资源和提示词功能。这种架构模式特别适合需要将 MCP 功能与现有 API 服务、认证中间件、日志系统等组件整合的场景。\n\n## 架构设计\n\n### 整体架构\n\nMCP Web 框架中间件采用了适配器模式设计，每种框架都有对应的传输层实现。中间件负责接收框架的 HTTP 请求，将其转换为 MCP 协议消息，然后调用底层 MCP 服务器处理逻辑，最终将处理结果以框架兼容的方式返回给客户端。\n\n```mermaid\ngraph TD\n A[HTTP 客户端] --> B[Web 框架路由]\n B --> C[MCP 中间件适配器]\n C --> D[MCP 协议消息解析]\n D --> E[MCP 服务器核心]\n E --> F[工具/资源/提示词处理器]\n F --> G[响应序列化]\n G --> C\n C --> H[HTTP 响应]\n H --> A\n```\n\n### 核心组件关系\n\n中间件层由三个主要包组成，分别对应三种 Web 框架：\n\n| 包名 | 功能 | 传输类型 |\n|------|------|----------|\n| `@modelcontextprotocol/express` | Express.js 框架集成 | Streamable HTTP |\n| `@modelcontextprotocol/hono` | Hono 框架集成 | Streamable HTTP |\n| `@modelcontextprotocol/fastify` | Fastify 框架集成 | Streamable HTTP |\n\n每个中间件包都包含核心适配器模块和安全验证中间件两个部分。核心适配器负责处理 MCP 协议通信，而安全中间件则提供主机头验证等防护功能。\n\n## Express 中间件集成\n\n### 核心功能\n\nExpress 中间件 (`packages/middleware/express/src/express.ts`) 提供了与 Express 框架的完整集成能力。它基于 MCP Streamable HTTP 传输协议实现，支持状态ful 和无状态两种运行模式。\n\nExpress 中间件的主要职责包括：\n\n- 将 Express 请求转换为 MCP JSON-RPC 消息\n- 管理会话状态（状态ful 模式）\n- 处理流式响应和 Server-Sent Events (SSE)\n- 与 Express 路由系统和中间件链集成\n\n### 使用方式\n\n开发者可以通过标准的 Express `use()` 方法将 MCP 中间件添加到应用中：\n\n```typescript\nimport express from 'express';\nimport { useMcpExpress } from '@modelcontextprotocol/express';\n\nconst app = express();\n\napp.use(express.json());\n\napp.use('/mcp', useMcpExpress(server, {\n transport: 'streamable-http',\n mode: 'stateful' // 或 'stateless'\n}));\n```\n\n中间件配置选项允许指定传输类型、运行模式和回调处理函数。状态ful 模式会维护会话信息，适合需要跨请求保持状态的复杂应用场景；无状态模式则每次请求独立处理，更适合简单的 API 式服务器。\n\n### 安全中间件\n\nExpress 包还包含了主机头验证中间件 (`packages/middleware/express/src/middleware/hostHeaderValidation.ts`)，用于防止主机头欺骗攻击。该中间件会验证请求中的 Host 和 X-Forwarded-Host 头，确保请求确实发往预期的目标地址。\n\n## Hono 中间件集成\n\n### 核心功能\n\nHono 中间件 (`packages/middleware/hono/src/hono.ts`) 提供了轻量级、高性能的 Hono 框架集成。Hono 本身是一个支持多个运行时的 Web 框架，因此 MCP Hono 中间件可以同时在 Node.js、Cloudflare Workers、Deno Deploy 等环境中运行。\n\nHono 中间件利用了 Hono 的流式响应处理能力，可以高效地处理 MCP 的流式消息传输。\n\n### 使用方式\n\nHono 中间件通过 Hono 的标准中间件机制注册：\n\n```typescript\nimport { Hono } from 'hono';\nimport { mcpHono } from '@modelcontextprotocol/hono';\n\nconst app = new Hono();\nconst mcp = new McpServer({ /* 配置 */ });\n\napp.use('/mcp', mcpHono(mcp, {\n transport: 'streamable-http',\n binder: someBinder\n}));\n```\n\n### 安全中间件\n\nHono 包同样包含了主机头验证中间件 (`packages/middleware/hono/src/middleware/hostHeaderValidation.ts`)，实现方式与 Express 版本类似，但针对 Hono 的上下文 API 进行了适配。\n\n## Fastify 中间件集成\n\n### 核心功能\n\nFastify 中间件 (`packages/middleware/fastify/src/fastify.ts`) 提供了与高性能 Node.js 框架 Fastify 的集成。Fastify 以其卓越的性能著称，MCP 中间件充分利用了 Fastify 的插件系统和流式处理能力。\n\nFastify 集成支持：\n\n- Fastify 插件式架构\n- 高性能请求路由\n- JSON Schema 验证集成\n- 流式响应处理\n\n### 使用方式\n\n```typescript\nimport Fastify from 'fastify';\nimport { mcpFastify } from '@modelcontextprotocol/fastify';\n\nconst fastify = Fastify();\nconst server = new McpServer({ /* 配置 */ });\n\nfastify.register(mcpFastify, {\n server,\n prefix: '/mcp'\n});\n```\n\n## 传输协议\n\n### Streamable HTTP 传输\n\n所有 Web 框架中间件都使用 Streamable HTTP 作为传输协议。这是 MCP 规范中定义的标准传输方式，支持：\n\n| 特性 | 说明 |\n|------|------|\n| 请求-响应模式 | 标准 HTTP POST 请求，JSON-RPC 响应 |\n| 流式响应 | 支持 Server-Sent Events 格式的流式消息 |\n| 会话管理 | 通过会话标识符维护状态 |\n| 心跳机制 | 保持连接活跃 |\n\n### 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant C as 客户端\n participant M as 中间件\n participant S as MCP服务器\n participant H as 处理器\n\n C->>M: POST /mcp (JSON-RPC Request)\n M->>S: 路由请求\n S->>H: 调用处理器\n H->>S: 返回结果\n S->>M: 流式响应\n M->>C: SSE 流\n C->>M: GET /mcp (SSE 连接)\n M->>S: 建立会话\n S->>M: 会话通道\n M->>C: 事件流\n```\n\n## 安全特性\n\n### 主机头验证\n\n主机头验证中间件是所有 Web 框架集成的标准安全组件。其工作原理包括：\n\n1. **白名单检查**：验证请求的 Host 头是否在允许的域名列表中\n2. **代理头处理**：正确处理 X-Forwarded-Host 等代理头\n3. **协议验证**：确保请求协议与预期匹配\n\n该中间件能够有效防御以下攻击：\n\n- DNS 重绑定攻击\n- 主机头欺骗\n- 代理层配置错误导致的安全问题\n\n### 认证集成\n\nWeb 框架中间件可以与各框架的认证系统无缝集成。开发者可以在 MCP 中间件之前注册任何 Express/Hono/Fastify 认证中间件，例如 JWT 验证、OAuth 验证或自定义会话验证。\n\n## 配置选项\n\n### 通用配置\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `transport` | `string` | `'streamable-http'` | 传输协议类型 |\n| `mode` | `'stateful' \\| 'stateless'` | `'stateful'` | 会话管理模式 |\n| `maxSessions` | `number` | 1000 | 最大并发会话数（状态ful模式） |\n| `sessionTimeout` | `number` | 300000 | 会话超时时间（毫秒） |\n\n### 状态ful 与无状态模式\n\n**状态ful 模式**维护会话状态，允许跨请求保持上下文：\n\n- 适合需要维护状态的复杂交互\n- 支持长连接和持久化上下文\n- 需要配置会话存储\n\n**无状态模式**每次请求独立处理：\n\n- 适合简单的工具调用场景\n- 更易于水平扩展\n- 无需会话管理开销\n\n## 与示例代码的对应关系\n\n`examples/server/README.md` 中列出的示例演示了这些中间件的实际应用：\n\n| 场景 | 描述 | 框架 |\n|------|------|------|\n| 状态ful Streamable HTTP 服务器 | 完整的工具/资源/提示词功能 | Express |\n| 无状态 Streamable HTTP 服务器 | 简化 API 式服务 | Express |\n| 资源服务器认证 | OAuth RS + Bearer 认证 | Express |\n\n这些示例位于 `examples/server/src/` 目录，展示了从简单的服务器配置到复杂的认证集成的完整使用方式。\n\n## 最佳实践\n\n### 生产环境部署\n\n1. **安全配置**：始终在 MCP 中间件之前配置认证和主机头验证中间件\n2. **会话管理**：根据应用场景选择合适的状态管理模式\n3. **超时设置**：合理配置请求超时和会话超时\n4. **错误处理**：实现统一的错误处理中间件，确保错误信息正确返回\n\n### 性能优化\n\n1. **路由前缀**：使用明确的路由前缀避免与其他 API 冲突\n2. **中间件顺序**：将 MCP 中间件放在合适的路由层级\n3. **会话限制**：在状态ful 模式下设置合理的最大会话数\n\n## 总结\n\nMCP TypeScript SDK 的 Web 框架中间件集成提供了强大而灵活的解决方案，使开发者能够将 Model Context Protocol 无缝嵌入到任何基于 Express、Hono 或 Fastify 的应用中。通过统一的适配器接口和安全组件，中间件系统确保了跨框架的一致性体验，同时充分发挥了各框架的独特优势。\n\n---\n\n\n\n## 实验性功能与任务系统\n\n### 相关页面\n\n相关主题：[服务器开发指南](#page-6), [客户端开发指南](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/experimental/tasks/interfaces.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/interfaces.ts)\n- [packages/core/src/experimental/tasks/helpers.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/helpers.ts)\n- [packages/core/src/experimental/tasks/stores/inMemory.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/stores/inMemory.ts)\n- [packages/server/src/experimental/tasks/server.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/tasks/server.ts)\n- [packages/client/src/experimental/tasks/client.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/experimental/tasks/client.ts)\n- [packages/client/src/shimsBrowser.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/shimsBrowser.ts)\n- [packages/client/src/shimsWorkerd.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/shimsWorkerd.ts)\n \n\n# 实验性功能与任务系统\n\n## 概述\n\nMCP TypeScript SDK 提供了一套实验性的任务系统（Task System），允许服务器和客户端管理异步长时运行任务。这些任务可以通过唯一标识符进行追踪、查询和取消操作。\n\n实验性功能通过 `@modelcontextprotocol/sdk/experimental` 模块导出，使用前需注意：\n\n> ⚠️ **警告**：这些 API 是实验性的，可能会在没有任何通知的情况下发生变化。\n\n```typescript\nimport { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';\n```\n\n资料来源：[packages/server/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)\n\n---\n\n## 架构设计\n\n### 组件关系图\n\n```mermaid\ngraph TD\n subgraph 客户端层\n ClientTaskAPI[\"ClientTaskApi\"]\n TaskStore[\"TaskStore\"]\n end\n \n subgraph 服务端层\n ServerTaskAPI[\"ServerTaskApi\"]\n TaskModule[\"TaskModule\"]\n end\n \n subgraph 传输层\n Transport[\"Transport Layer\"]\n end\n \n ClientTaskAPI -->|JSON-RPC| Transport\n Transport -->|JSON-RPC| ServerTaskAPI\n ServerTaskAPI --> TaskModule\n ClientTaskAPI --> TaskStore\n \n TaskModule -.->|状态存储| TaskStore\n```\n\n### 核心模块结构\n\n| 模块 | 位置 | 职责 |\n|------|------|------|\n| `interfaces.ts` | `packages/core/src/experimental/tasks/` | 定义任务接口和数据模型 |\n| `helpers.ts` | `packages/core/src/experimental/tasks/` | 提供任务相关辅助函数 |\n| `inMemory.ts` | `packages/core/src/experimental/tasks/stores/` | 实现内存任务存储 |\n| `client.ts` | `packages/client/src/experimental/tasks/` | 客户端任务 API |\n| `server.ts` | `packages/server/src/experimental/tasks/` | 服务端任务 API |\n\n---\n\n## 服务端任务 API\n\n### ServerTaskApi 类\n\n`ServerTaskApi` 封装了服务端处理任务的核心方法。\n\n资料来源：[packages/server/src/experimental/tasks/server.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/tasks/server.ts)\n\n### 核心方法\n\n#### getTaskResult\n\n获取指定任务的执行结果。\n\n```typescript\nasync getTaskResult(\n taskId: string, \n options?: RequestOptions\n): Promise\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `taskId` | `string` | 任务唯一标识符 |\n| `options` | `RequestOptions` | 可选的请求配置 |\n\n**返回值**：`GetTaskPayloadResult` 类型的 Promise，封装了任务的执行结果（如工具调用返回的 `CallToolResult`）。\n\n资料来源：[packages/server/src/experimental/tasks/server.ts:20-26]()\n\n#### listTasks\n\n列出所有任务，支持分页查询。\n\n```typescript\nasync listTasks(\n cursor?: string, \n options?: RequestOptions\n): Promise\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `cursor` | `string` | 可选的分页游标 |\n| `options` | `RequestOptions` | 可选的请求配置 |\n\n**返回值**：`ListTasksResult` 包含任务列表和可选的下一页游标。\n\n资料来源：[packages/server/src/experimental/tasks/server.ts:34-43]()\n\n#### cancelTask\n\n取消一个正在运行的任务。\n\n```typescript\nasync cancelTask(\n taskId: string, \n options?: RequestOptions\n): Promise\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `taskId` | `string` | 要取消的任务标识符 |\n| `options` | `RequestOptions` | 可选的请求配置 |\n\n**返回值**：`CancelTaskResult` 表示取消操作的结果。\n\n资料来源：[packages/server/src/experimental/tasks/server.ts:52-60]()\n\n---\n\n## 客户端任务 API\n\n### ClientTaskApi 类\n\n客户端通过 `ClientTaskApi` 与服务端的任务系统进行交互。\n\n资料来源：[packages/client/src/experimental/tasks/client.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/experimental/tasks/client.ts)\n\n### 浏览器与 Workerd 适配\n\n客户端支持多种运行环境，通过不同的 shim 文件提供适配：\n\n| 环境 | Shim 文件 | 用途 |\n|------|----------|------|\n| 浏览器 | `packages/client/src/shimsBrowser.ts` | 浏览器环境适配 |\n| Workerd | `packages/client/src/shimsWorkerd.ts` | Cloudflare Workerd 环境适配 |\n\n资料来源：[packages/client/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/experimental/index.ts)\n\n---\n\n## 任务存储\n\n### TaskStore 接口\n\n任务存储定义了任务状态管理的基本接口。\n\n资料来源：[packages/core/src/experimental/tasks/interfaces.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/interfaces.ts)\n\n### InMemoryTaskStore\n\n默认提供的内存实现，适用于单进程场景。\n\n```typescript\nimport { InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';\n\nconst taskStore = new InMemoryTaskStore();\n```\n\n特点：\n\n- 数据存储在内存中，进程重启后会丢失\n- 适合开发、测试或单实例部署\n- 性能最优，无需序列化/反序列化开销\n\n资料来源：[packages/core/src/experimental/tasks/stores/inMemory.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/stores/inMemory.ts)\n\n### 自定义存储实现\n\n可通过实现 `TaskStore` 接口创建自定义存储：\n\n```typescript\ninterface TaskStore {\n get(taskId: string): Promise;\n set(taskId: string, task: Task): Promise;\n delete(taskId: string): Promise;\n list(cursor?: string): Promise;\n}\n```\n\n资料来源：[packages/core/src/experimental/tasks/interfaces.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/interfaces.ts)\n\n---\n\n## 辅助函数\n\n### helpers.ts\n\n提供任务创建、验证、序列化等辅助功能。\n\n资料来源：[packages/core/src/experimental/tasks/helpers.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/helpers.ts)\n\n### 常用辅助函数\n\n| 函数 | 功能 |\n|------|------|\n| `createTask()` | 创建新任务实例 |\n| `validateTaskId()` | 验证任务标识符格式 |\n| `serializeTask()` | 序列化任务数据 |\n| `deserializeTask()` | 反序列化任务数据 |\n\n---\n\n## 使用工作流\n\n### 创建并追踪任务\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Server as 服务端\n participant Store as 任务存储\n \n Client->>Server: 发起需要长时间执行的操作\n Server->>Store: 创建任务记录\n Server-->>Client: 返回 taskId\n \n loop 任务执行中\n Client->>Server: getTaskResult(taskId)\n Server->>Store: 查询任务状态\n Store-->>Server: 返回任务结果\n Server-->>Client: 返回 GetTaskPayloadResult\n end\n \n Client->>Server: cancelTask(taskId)\n Server->>Store: 更新任务状态为已取消\n Server-->>Client: 返回 CancelTaskResult\n```\n\n### 完整示例\n\n```typescript\nimport { Client } from '@modelcontextprotocol/sdk/client';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp';\nimport { ClientTaskApi } from '@modelcontextprotocol/sdk/experimental';\n\n// 初始化客户端\nconst transport = new StreamableHTTPClientTransport('http://localhost:3000/mcp');\nconst client = new Client({ name: 'example-client', version: '1.0.0' });\nawait client.connect(transport);\n\n// 创建任务 API 实例\nconst taskApi = new ClientTaskApi(client);\n\n// 获取任务结果\nconst result = await taskApi.getTaskResult('task-123');\nconsole.log(result);\n\n// 列出所有任务\nconst { tasks, nextCursor } = await taskApi.listTasks();\n\n// 取消任务\nawait taskApi.cancelTask('task-456');\n```\n\n---\n\n## 类型定义\n\n### 核心类型\n\n| 类型 | 描述 |\n|------|------|\n| `Task` | 任务数据模型 |\n| `TaskId` | 任务唯一标识符 |\n| `GetTaskPayloadResult` | 任务结果载荷 |\n| `ListTasksResult` | 任务列表结果 |\n| `CancelTaskResult` | 取消操作结果 |\n| `RequestOptions` | 请求配置选项 |\n\n资料来源：[packages/core/src/types/types.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/types.ts)\n\n---\n\n## 最佳实践\n\n### 1. 错误处理\n\n始终对任务操作进行错误处理：\n\n```typescript\ntry {\n const result = await taskApi.getTaskResult(taskId);\n} catch (error) {\n if (error.code === 'TASK_NOT_FOUND') {\n console.error('任务不存在:', taskId);\n } else {\n throw error;\n }\n}\n```\n\n### 2. 任务超时管理\n\n建议设置合理的请求超时：\n\n```typescript\nconst result = await taskApi.getTaskResult(taskId, {\n timeout: 30000, // 30秒超时\n signal: AbortSignal.timeout(30000)\n});\n```\n\n### 3. 进度追踪\n\n对于长时间运行的任务，定期轮询状态：\n\n```typescript\nasync function waitForCompletion(taskId: string, interval = 1000) {\n while (true) {\n const result = await taskApi.getTaskResult(taskId);\n if (result.status === 'completed') {\n return result;\n }\n if (result.status === 'failed') {\n throw new Error(`任务失败: ${result.error}`);\n }\n await new Promise(resolve => setTimeout(resolve, interval));\n }\n}\n```\n\n---\n\n## 注意事项\n\n1. **实验性警告**：所有任务系统 API 均为实验性，可能在后续版本中发生不兼容变更。\n\n2. **状态持久化**：`InMemoryTaskStore` 不支持持久化，进程重启后任务状态会丢失。如需持久化，请实现自定义存储。\n\n3. **并发限制**：大量并发任务可能影响性能，建议实现适当的限流机制。\n\n4. **资源清理**：任务完成后应及时调用 `cancelTask` 或清理过期任务，避免内存泄漏。\n\n---\n\n## 相关资源\n\n- [MCP 协议规范](https://modelcontextprotocol.io/specification)\n- [服务端文档](../../docs/server.md)\n- [客户端文档](../../docs/client.md)\n- [Streamable HTTP 传输](../transports/streamableHttp.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：modelcontextprotocol/typescript-sdk\n\n摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：运行坑 - 来源证据：client code can't execute inside browser due to import spawn。\n\n## 1. 运行坑 · 来源证据：client code can't execute inside browser due to import spawn\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：client code can't execute inside browser due to import spawn\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8a06947266aa4987ad712baf87a7a156 | https://github.com/modelcontextprotocol/typescript-sdk/issues/2077 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `typescript-sdk` 与安装入口 `@modelcontextprotocol/server` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @modelcontextprotocol/server`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | repo=typescript-sdk; install=@modelcontextprotocol/server\n\n## 3. 安装坑 · 来源证据：@modelcontextprotocol/node@2.0.0-alpha.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/node@2.0.0-alpha.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fc8de64b72814f8eb9ed0e53852408c2 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/node%402.0.0-alpha.1 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：@modelcontextprotocol/server@2.0.0-alpha.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/server@2.0.0-alpha.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dff36a13cb954c3b84b05e99a28dc4d0 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.0.0-alpha.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | release_recency=unknown\n\n\n",
"markdown_key": "typescript-sdk",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:862578138",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/modelcontextprotocol/typescript-sdk"
},
{
"evidence_id": "art_5d5a87c5cff84e18aaeb6177de09391a",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/modelcontextprotocol/typescript-sdk#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "typescript-sdk 说明书",
"toc": [
"https://github.com/modelcontextprotocol/typescript-sdk 项目说明书",
"目录",
"MCP TypeScript SDK 概述",
"简介",
"架构设计",
"核心模块",
"服务器开发",
"客户端开发",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "2c0c481cb9dbfd15c8613f765c940a5f5bace94d",
"repo_inspection_error": null,
"repo_inspection_files": [
"pnpm-lock.yaml",
"package.json",
"README.md",
"docs/migration-SKILL.md",
"docs/v2-banner.js",
"docs/server.md",
"docs/client-quickstart.md",
"docs/server-quickstart.md",
"docs/faq.md",
"docs/client.md",
"docs/migration.md",
"docs/documents.md",
"examples/server-quickstart/package.json",
"examples/server-quickstart/tsconfig.json",
"examples/client-quickstart/package.json",
"examples/client-quickstart/tsconfig.json",
"examples/server/tsdown.config.ts",
"examples/server/package.json",
"examples/server/README.md",
"examples/server/vitest.config.js",
"examples/server/tsconfig.json",
"examples/client/tsdown.config.ts",
"examples/client/package.json",
"examples/client/README.md",
"examples/client/vitest.config.js",
"examples/client/tsconfig.json",
"examples/shared/package.json",
"examples/shared/vitest.config.js",
"examples/shared/tsconfig.json",
"examples/server-quickstart/src/index.ts",
"examples/client-quickstart/src/index.ts",
"examples/server/src/toolWithSampleServer.ts",
"examples/server/src/serverGuide.examples.ts",
"examples/server/src/standaloneSseWithGetStreamableHttp.ts",
"examples/server/src/valibotExample.ts",
"examples/server/src/jsonResponseStreamableHttp.ts",
"examples/server/src/simpleStreamableHttp.ts",
"examples/server/src/resourceServerOnly.ts",
"examples/server/src/ssePollingExample.ts",
"examples/server/src/customMethodExample.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @modelcontextprotocol/sdk - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @modelcontextprotocol/sdk 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md`, `docs/client-quickstart.md`, `docs/server-quickstart.md`, `packages/client/README.md` 等 Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `npm install @modelcontextprotocol/server` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0009` supported 0.86, `clm_0010` supported 0.86, `clm_0011` supported 0.86 等\n- `npm install @modelcontextprotocol/client` 证据：`README.md` Claim：`clm_0004` supported 0.86, `clm_0008` supported 0.86\n- `npm install @modelcontextprotocol/node` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npm install @modelcontextprotocol/express express` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npm install @modelcontextprotocol/hono hono` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npm install @modelcontextprotocol/client@alpha` 证据：`packages/client/README.md` Claim：`clm_0008` supported 0.86\n- `npm install @modelcontextprotocol/server @modelcontextprotocol/express express` 证据：`packages/middleware/express/README.md` Claim：`clm_0009` supported 0.86\n- `npm install @modelcontextprotocol/server @modelcontextprotocol/fastify fastify` 证据：`packages/middleware/fastify/README.md` Claim：`clm_0010` supported 0.86\n- `npm install @modelcontextprotocol/server @modelcontextprotocol/hono hono` 证据：`packages/middleware/hono/README.md` Claim：`clm_0011` supported 0.86\n- `npm install @modelcontextprotocol/server @modelcontextprotocol/node` 证据：`packages/middleware/node/README.md` Claim：`clm_0012` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md`, `docs/client-quickstart.md`, `docs/server-quickstart.md`, `packages/client/README.md` 等 Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0009` supported 0.86, `clm_0010` supported 0.86, `clm_0011` supported 0.86\n\n### 现在还不能相信\n\n- **角色质量和任务匹配不能直接相信。**（unverified）：角色库证明有很多角色，不证明每个角色都适合你的具体任务，也不证明角色能产生高质量结果。\n- **不能把角色文案当成真实执行能力。**（unverified）：安装前只能判断角色描述和任务画像是否匹配，不能证明它能在宿主 AI 里完成任务。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`, `docs/client-quickstart.md`, `docs/server-quickstart.md`, `packages/client/README.md` 等\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `docs/client-quickstart.md`, `docs/server-quickstart.md`, `packages/client/README.md` 等\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`docs/client-quickstart.md`, `examples/client-quickstart/src/index.ts`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：先用交互式试用验证任务画像和角色匹配，不要先导入整套角色库。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **保留原始角色选择记录**：如果输出偏题，可以回到任务画像阶段重新选择角色，而不是继续沿着错误角色推进。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0017` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md`, `docs/client-quickstart.md`, `docs/server-quickstart.md`, `packages/client/README.md` 等 Claim：`clm_0018` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md`, `docs/client-quickstart.md`, `docs/server-quickstart.md`, `packages/client/README.md` 等 Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：422\n- 重要文件覆盖：40/422\n- 证据索引条目：80\n- 角色 / Skill 条目：60\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @modelcontextprotocol/sdk 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @modelcontextprotocol/sdk 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @modelcontextprotocol/sdk 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 60 个角色 / Skill / 项目文档条目。\n\n- **Changesets**（project_doc）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/README.md`\n- **CLAUDE.md**（project_doc）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **MCP TypeScript SDK**（project_doc）：!IMPORTANT This is the main branch which contains v2 of the SDK currently in development, pre-alpha . We anticipate a stable v2 release in Q1 2026. Until then, v1.x remains the recommended version for production use. v1.x will continue to receive bug fixes and security updates for at least 6 months after v2 ships to give people time to upgrade. For v1 documentation, see the V1 API docs https://ts.sdk.modelcontextpro… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **MCP TypeScript SDK Examples Client**（project_doc）：This directory contains runnable MCP client examples built with @modelcontextprotocol/client . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/client/README.md`\n- **MCP TypeScript SDK Examples Server**（project_doc）：This directory contains runnable MCP server examples built with @modelcontextprotocol/server plus framework adapters: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/server/README.md`\n- **@modelcontextprotocol/client**（project_doc）：The MCP Model Context Protocol TypeScript client SDK. Build MCP clients that connect to MCP servers. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/client/README.md`\n- **Middleware packages**（project_doc）：The packages in packages/middleware/ are thin integration layers that help you expose an MCP server in a specific runtime, platform, or web framework. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/middleware/README.md`\n- **@modelcontextprotocol/express**（project_doc）：Express adapters for the MCP TypeScript server SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/middleware/express/README.md`\n- **@modelcontextprotocol/fastify**（project_doc）：Fastify adapters for the MCP TypeScript server SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/middleware/fastify/README.md`\n- **@modelcontextprotocol/hono**（project_doc）：Hono adapters for the MCP TypeScript server SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/middleware/hono/README.md`\n- **@modelcontextprotocol/node**（project_doc）：Node.js adapters for the MCP TypeScript server SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/middleware/node/README.md`\n- **@modelcontextprotocol/server**（project_doc）：The MCP Model Context Protocol TypeScript server SDK. Build MCP servers that expose tools, resources, and prompts. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`packages/server/README.md`\n- **Conformance Tests**（project_doc）：This directory contains conformance test implementations for the TypeScript MCP SDK. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`test/conformance/README.md`\n- **Contributing to MCP TypeScript SDK**（project_doc）：Welcome, and thanks for your interest in contributing! We're glad you're here. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Quickstart: Build an LLM-powered chatbot**（project_doc）：Quickstart: Build an LLM-powered chatbot 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/client-quickstart.md`\n- **Building MCP clients**（project_doc）：This guide covers the TypeScript SDK APIs for building MCP clients. For protocol-level concepts, see the MCP overview https://modelcontextprotocol.io/docs/learn/architecture . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/client.md`\n- **Documents**（project_doc）：- Server Quickstart ./server-quickstart.md – build a weather server from scratch and connect it to VS Code - Server ./server.md – building MCP servers: transports, tools, resources, prompts, server-initiated requests, and deployment - Client Quickstart ./client-quickstart.md – build an LLM-powered chatbot that connects to an MCP server and calls its tools - Client ./client.md – building MCP clients: connecting, tool… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/documents.md`\n- **FAQ**（project_doc）：- General general - Clients clients - Servers servers - v1 legacy v1-legacy 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/faq.md`\n- **migrate-v1-to-v2**（project_doc）：Migrate MCP TypeScript SDK code from v1 @modelcontextprotocol/sdk to v2 @modelcontextprotocol/core, /client, /server . Use when a user asks to migrate, upgrade, or port their MCP TypeScript code from v1 to v2. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/migration-SKILL.md`\n- **Migration Guide: v1 to v2**（project_doc）：This guide covers the breaking changes introduced in v2 of the MCP TypeScript SDK and how to update your code. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/migration.md`\n- **Quickstart: Build a weather server**（project_doc）：In this tutorial, we'll build a simple MCP weather server and connect it to a host. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/server-quickstart.md`\n- **Building MCP servers**（project_doc）：This guide covers the TypeScript SDK APIs for building MCP servers. For protocol-level concepts — what tools, resources, and prompts are and when to use each — see the MCP overview https://modelcontextprotocol.io/docs/learn/architecture . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/server.md`\n- **Abort Handlers On Close**（project_doc）：Abort in-flight request handlers when the connection closes. Previously, request handlers would continue running after the transport disconnected, wasting resources and preventing proper cleanup. Also fixes InMemoryTransport.close firing onclose twice on the initiating side. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/abort-handlers-on-close.md`\n- **Add Fastify Middleware**（project_doc）：Add Fastify middleware adapter for MCP servers, following the same pattern as the Express and Hono adapters. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/add-fastify-middleware.md`\n- **Add Hono Peer Dep**（project_doc）：Add missing hono peer dependency to @modelcontextprotocol/node . The package already depends on @hono/node-server which requires hono at runtime, but hono was only listed in the workspace root, not as a peer dependency of the package itself. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/add-hono-peer-dep.md`\n- **Add Resource Size Field**（project_doc）：Add missing size field to ResourceSchema to match the MCP specification 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/add-resource-size-field.md`\n- **Brave Lions Glow**（project_doc）：Prevent Hono from overriding global Response object by passing overrideGlobalObjects: false to getRequestListener . This fixes compatibility with frameworks like Next.js whose response classes extend the native Response. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/brave-lions-glow.md`\n- **Busy Rice Smoke**（project_doc）：tasks - disallow requesting a null TTL 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/busy-rice-smoke.md`\n- **Busy Weeks Hang**（project_doc）：Fix ReDoS vulnerability in UriTemplate regex patterns CVE-2026-0621 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/busy-weeks-hang.md`\n- **Cfworker Out Of Barrel**（project_doc）：Stop bundling @cfworker/json-schema into the main package barrel. Previously CfWorkerJsonSchemaValidator was re-exported from the core internal barrel, so tsdown inlined the @cfworker/json-schema dev dependency into every consumer's bundle even when it was never used. The validator is now reachable only via the shims conditional workerd/browser and the explicit @modelcontextprotocol/{server,client}/validators/cf-wor… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/cfworker-out-of-barrel.md`\n- **Custom Methods Minimal**（project_doc）：Add custom non-spec method support: a 3-arg setRequestHandler method, schemas, handler / setNotificationHandler method, schemas, handler form for vendor-prefixed methods, and a request req, resultSchema overload also on ctx.mcpReq.send for typed custom-method results. Spec-method calls are unchanged. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/custom-methods-minimal.md`\n- **Cyan Cycles Pump**（project_doc）：missing change for fix client : replace body.cancel with text to prevent hanging 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/cyan-cycles-pump.md`\n- **Drop Zod Peer Dep**（project_doc）：Drop zod from peerDependencies kept as direct dependency 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/drop-zod-peer-dep.md`\n- **Export Inmemory Transport**（project_doc）：Export InMemoryTransport for in-process testing. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/export-inmemory-transport.md`\n- **Expose Auth Server Discovery**（project_doc）：Add discoverOAuthServerInfo function and unified discovery state caching for OAuth 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/expose-auth-server-discovery.md`\n- **Express Resource Server Auth**（project_doc）：Add OAuth Resource-Server glue to the Express adapter: requireBearerAuth middleware token verification + RFC 6750 WWW-Authenticate challenges , mcpAuthMetadataRouter serves RFC 9728 Protected Resource Metadata and mirrors RFC 8414 AS metadata at the resource origin , the getOAuthProtectedResourceMetadataUrl helper, and the OAuthTokenVerifier interface. These restore the v1 src/server/auth Resource-Server pieces as f… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/express-resource-server-auth.md`\n- **Extract Task Manager**（project_doc）：refactor: extract task orchestration from Protocol into TaskManager 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/extract-task-manager.md`\n- **Fast Dragons Lead**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fast-dragons-lead.md`\n- **Finish Sdkerror Capability**（project_doc）：Convert remaining capability-assertion throws to SdkError SdkErrorCode.CapabilityNotSupported, ... . Follow-up to 1454 which missed Client.assertCapability , the task capability helpers in experimental/tasks/helpers.ts , and the sampling/elicitation capability checks in experimental/tasks/server.ts . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/finish-sdkerror-capability.md`\n- **Fix Abort Listener Leak**（project_doc）：Consolidate per-request cleanup in requestWithSchema into a single .finally block. This fixes an abort signal listener leak listeners accumulated when a caller reused one AbortSignal across requests and two cases where responseHandlers entries leaked on send-failure paths. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-abort-listener-leak.md`\n- **Fix Failed Task Result Retrieval**（project_doc）：Fix requestStream to call tasks/result for failed tasks instead of yielding a hardcoded ProtocolError . When a task reaches the failed terminal status, the stream now retrieves and yields the actual stored result matching the behavior for completed tasks , as required by the spec. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-failed-task-result-retrieval.md`\n- **Fix Oauth 5Xx Discovery**（project_doc）：Continue OAuth metadata discovery on 502 Bad Gateway responses, matching the existing behavior for 4xx. This fixes MCP servers behind reverse proxies that return 502 for path-aware metadata URLs. Other 5xx errors still throw to avoid retrying against overloaded servers. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-oauth-5xx-discovery.md`\n- **Fix Onerror Callbacks**（project_doc）：Fix transport errors being silently swallowed by adding missing onerror callback invocations before all createJsonErrorResponse calls in WebStandardStreamableHTTPServerTransport . This ensures errors like parse failures, invalid headers, and session validation errors are properly reported via the onerror callback. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-onerror-callbacks.md`\n- **Fix Server Protocol Version**（project_doc）：fix server : propagate negotiated protocol version to transport in oninitialize 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-server-protocol-version.md`\n- **Fix Session Status Codes**（project_doc）：Example servers now return HTTP 404 not 400 when a request includes an unknown session ID, so clients can correctly detect they need to start a new session. Requests missing a session ID entirely still return 400. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-session-status-codes.md`\n- **Fix Stdio Epipe Crash**（project_doc）：Handle stdout errors e.g. EPIPE in StdioServerTransport gracefully instead of crashing. When the client disconnects abruptly, the transport now catches the stdout error, surfaces it via onerror , and closes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-stdio-epipe-crash.md`\n- **Fix Stdio Windows Hide**（project_doc）：Always set windowsHide when spawning stdio server processes on Windows, not just in Electron environments. Prevents unwanted console windows in non-Electron Windows applications. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-stdio-windows-hide.md`\n- **Fix Streamable Close Reentrant**（project_doc）：Prevent stack overflow in StreamableHTTPServerTransport.close with re-entrant guard 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-streamable-close-reentrant.md`\n- **Fix Streamable Http Error Response**（project_doc）：Fix StreamableHTTPClientTransport to handle error responses in SSE streams 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-streamable-http-error-response.md`\n- **Fix Task Session Isolation**（project_doc）：Fix InMemoryTaskStore to enforce session isolation. Previously, sessionId was accepted but ignored on all TaskStore methods, allowing any session to enumerate, read, and mutate tasks created by other sessions. The store now persists sessionId at creation time and enforces ownership on all reads and writes. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-task-session-isolation.md`\n- **Fix Transport Exact Optional Property Types**（project_doc）：Add explicit undefined to optional properties on the Transport interface and TransportSendOptions onclose , onerror , onmessage , sessionId , setProtocolVersion , setSupportedProtocolVersions , onresumptiontoken . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-transport-exact-optional-property-types.md`\n- **Fix Unknown Tool Protocol Error**（project_doc）：Fix error handling for unknown tools and resources per MCP spec. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-unknown-tool-protocol-error.md`\n- **Fix Validate Client Metadata Url**（project_doc）：Add validateClientMetadataUrl utility for early validation of clientMetadataUrl 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/fix-validate-client-metadata-url.md`\n- **Funky Baths Attack**（project_doc）：remove deprecated .tool, .prompt, .resource method signatures 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/funky-baths-attack.md`\n- **Gentle Planets Rest**（project_doc）：Add undefined to optional callback and function properties on WebStandardStreamableHTTPServerTransportOptions sessionIdGenerator , onsessioninitialized , onsessionclosed and corresponding private fields. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/gentle-planets-rest.md`\n- **Heavy Walls Swim**（project_doc）：reverting application/json in notifications 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/heavy-walls-swim.md`\n- **Hono Peer Optional**（project_doc）：Mark hono peer dependency as optional. @modelcontextprotocol/node only uses getRequestListener from @hono/node-server Node HTTP ↔ Web Standard conversion , which does not require the hono framework at runtime. Consumers no longer need to install hono to use NodeStreamableHTTPServerTransport . Note: @hono/node-server itself still declares hono as a hard peer, so package managers may emit a warning; this is upstream a… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/hono-peer-optional.md`\n- **Legacy Module Resolution Types**（project_doc）：Add top-level types field and typesVersions on client/server for their subpath exports so consumers on legacy moduleResolution: \"node\" can resolve type declarations. The exports map remains the source of truth for nodenext / bundler resolution. The typesVersions map includes entries for subpaths added by sibling PRs in this series zod-schemas , stdio ; those entries are no-ops until the corresponding dist/ .d.mts fi… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/legacy-module-resolution-types.md`\n- **Oauth Error Http200**（project_doc）：Fix OAuth error handling for servers returning errors with HTTP 200 status 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/oauth-error-http200.md`\n- **Odd Forks Enjoy**（project_doc）：fix client : append custom Accept headers to spec-required defaults in StreamableHTTPClientTransport 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.changeset/odd-forks-enjoy.md`\n\n## 证据索引\n\n- 共索引 80 条证据。\n\n- **Changesets**（documentation）：Hello and welcome! This folder has been automatically generated by @changesets/cli , a build tool that works with multi-package repos, or single-package repos to help you version and publish your code. You can find the full documentation for it in our repository https://github.com/changesets/changesets 证据：`.changeset/README.md`\n- **CLAUDE.md**（documentation）：This file provides guidance to Claude Code claude.ai/code when working with code in this repository. 证据：`CLAUDE.md`\n- **MCP TypeScript SDK**（documentation）：!IMPORTANT This is the main branch which contains v2 of the SDK currently in development, pre-alpha . We anticipate a stable v2 release in Q1 2026. Until then, v1.x remains the recommended version for production use. v1.x will continue to receive bug fixes and security updates for at least 6 months after v2 ships to give people time to upgrade. For v1 documentation, see the V1 API docs https://ts.sdk.modelcontextprotocol.io/ . For v2 API docs, see /v2/ https://ts.sdk.modelcontextprotocol.io/v2/ . 证据：`README.md`\n- **MCP TypeScript SDK Examples Client**（documentation）：This directory contains runnable MCP client examples built with @modelcontextprotocol/client . 证据：`examples/client/README.md`\n- **MCP TypeScript SDK Examples Server**（documentation）：This directory contains runnable MCP server examples built with @modelcontextprotocol/server plus framework adapters: 证据：`examples/server/README.md`\n- **@modelcontextprotocol/client**（documentation）：The MCP Model Context Protocol TypeScript client SDK. Build MCP clients that connect to MCP servers. 证据：`packages/client/README.md`\n- **Middleware packages**（documentation）：The packages in packages/middleware/ are thin integration layers that help you expose an MCP server in a specific runtime, platform, or web framework. 证据：`packages/middleware/README.md`\n- **@modelcontextprotocol/express**（documentation）：Express adapters for the MCP TypeScript server SDK. 证据：`packages/middleware/express/README.md`\n- **@modelcontextprotocol/fastify**（documentation）：Fastify adapters for the MCP TypeScript server SDK. 证据：`packages/middleware/fastify/README.md`\n- **@modelcontextprotocol/hono**（documentation）：Hono adapters for the MCP TypeScript server SDK. 证据：`packages/middleware/hono/README.md`\n- **@modelcontextprotocol/node**（documentation）：Node.js adapters for the MCP TypeScript server SDK. 证据：`packages/middleware/node/README.md`\n- **@modelcontextprotocol/server**（documentation）：The MCP Model Context Protocol TypeScript server SDK. Build MCP servers that expose tools, resources, and prompts. 证据：`packages/server/README.md`\n- **Conformance Tests**（documentation）：This directory contains conformance test implementations for the TypeScript MCP SDK. 证据：`test/conformance/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/sdk\", \"private\": true, \"version\": \"2.0.0-alpha.0\", \"description\": \"Model Context Protocol implementation for TypeScript\", \"license\": \"SEE LICENSE IN LICENSE\", \"author\": \"Model Context Protocol a Series of LF Projects, LLC.\", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\" }, \"packageManager\": \"pnpm@10.26.1\", \"keywords\": \"modelcontextprotocol\", \"mcp\" , \"scripts\": { \"fetch:spec-types\": \"tsx scripts/fetch-spec-types.ts\", \"sync:snippets\": \"ts… 证据：`package.json`\n- **Contributing to MCP TypeScript SDK**（documentation）：Welcome, and thanks for your interest in contributing! We're glad you're here. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/eslint-config\", \"private\": true, \"main\": \"eslint.config.mjs\", \"type\": \"module\", \"exports\": { \".\": \"./eslint.config.mjs\" }, \"dependencies\": { \"typescript\": \"catalog:devTools\" }, \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"bugs\": { \"url\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\" }, \"homepage\": \"https://github.com/modelcontextprotocol/typescript-sdk/tree/develop/common/eslint-config\", \"publishConfig\": { \"registry\": \"https://npm.pkg.github.com/\" }, \"version\": \"2.0.0\", \"devDependencies\": { \"@eslint/js\": \"catalog:devTools\", \"eslint\": \"catalog:devTools\", \"eslint-config-prettier\": \"cat… 证据：`common/eslint-config/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/tsconfig\", \"private\": true, \"main\": \"tsconfig.json\", \"type\": \"module\", \"dependencies\": { \"typescript\": \"catalog:devTools\" }, \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"bugs\": { \"url\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\" }, \"homepage\": \"https://github.com/modelcontextprotocol/typescript-sdk/tree/develop/common/ts-config\", \"publishConfig\": { \"registry\": \"https://npm.pkg.github.com/\" }, \"version\": \"2.0.0\" } 证据：`common/tsconfig/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/vitest-config\", \"private\": true, \"main\": \"vitest.config.mjs\", \"type\": \"module\", \"exports\": { \".\": \"./vitest.config.js\" }, \"dependencies\": { \"typescript\": \"catalog:devTools\" }, \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"bugs\": { \"url\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\" }, \"homepage\": \"https://github.com/modelcontextprotocol/typescript-sdk/tree/develop/common/vitest-config\", \"publishConfig\": { \"registry\": \"https://npm.pkg.github.com/\" }, \"version\": \"2.0.0\", \"devDependencies\": { \"@modelcontextprotocol/tsconfig\": \"workspace:^\", \"vite-tsconfig-paths\": \"catalog:devTools\" } } 证据：`common/vitest-config/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/examples-client-quickstart\", \"private\": true, \"version\": \"2.0.0-alpha.0\", \"type\": \"module\", \"bin\": { \"mcp-client-cli\": \"./build/index.js\" }, \"scripts\": { \"build\": \"tsc\", \"typecheck\": \"tsc --noEmit\" }, \"dependencies\": { \"@anthropic-ai/sdk\": \"^0.74.0\", \"@modelcontextprotocol/client\": \"workspace:^\" }, \"devDependencies\": { \"@types/node\": \"^24.10.1\", \"typescript\": \"catalog:devTools\" } } 证据：`examples/client-quickstart/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/examples-client\", \"private\": true, \"version\": \"2.0.0-alpha.0\", \"description\": \"Model Context Protocol implementation for TypeScript\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\" }, \"keywords\": \"modelcontextprotocol\", \"mcp\" , \"scripts\": { \"typecheck\": \"tsgo -p tsconfig.json --noEmit\", \"build\": \"tsdown\", \"build:watch\": \"tsdown --watch\", \"prepack\": \"pnpm run build:esm &… 证据：`examples/client/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/examples-server-quickstart\", \"private\": true, \"version\": \"2.0.0-alpha.0\", \"type\": \"module\", \"bin\": { \"weather\": \"./build/index.js\" }, \"scripts\": { \"build\": \"tsc\", \"typecheck\": \"tsc --noEmit\" }, \"dependencies\": { \"@modelcontextprotocol/server\": \"workspace:^\", \"zod\": \"catalog:runtimeShared\" }, \"devDependencies\": { \"@types/node\": \"^24.10.1\", \"typescript\": \"catalog:devTools\" } } 证据：`examples/server-quickstart/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/examples-server\", \"private\": true, \"version\": \"2.0.0-alpha.0\", \"description\": \"Model Context Protocol implementation for TypeScript\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\" }, \"keywords\": \"modelcontextprotocol\", \"mcp\" , \"scripts\": { \"typecheck\": \"tsgo -p tsconfig.json --noEmit\", \"build\": \"tsdown\", \"build:watch\": \"tsdown --watch\", \"prepack\": \"pnpm run build:esm &… 证据：`examples/server/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/examples-shared\", \"private\": true, \"version\": \"2.0.0-alpha.0\", \"description\": \"Model Context Protocol implementation for TypeScript\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\" }, \"keywords\": \"modelcontextprotocol\", \"mcp\" , \"scripts\": { \"typecheck\": \"tsgo -p tsconfig.json --noEmit\", \"prepack\": \"pnpm run build:esm && pnpm run build:cjs\", \"lint\": \"eslint src/ && prett… 证据：`examples/shared/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/client\", \"version\": \"2.0.0-alpha.2\", \"description\": \"Model Context Protocol implementation for TypeScript - Client package\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\" }, \"keywords\": \"modelcontextprotocol\", \"mcp\", \"client\" , \"exports\": { \".\": { \"types\": \"./dist/index.d.mts\", \"import\": \"./dist/index.mjs\" }, \"./stdio\": { \"types\": \"./dist/stdio.d.mts\", \"import\": \"./dis… 证据：`packages/client/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/core\", \"private\": true, \"version\": \"2.0.0-alpha.1\", \"description\": \"Model Context Protocol implementation for TypeScript - Core package\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\" }, \"keywords\": \"modelcontextprotocol\", \"mcp\", \"core\" , \"exports\": { \".\": { \"types\": \"./dist/index.d.ts\", \"import\": \"./dist/index.mjs\" }, \"./types\": { \"types\": \"./src/exports/types/index.t… 证据：`packages/core/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/express\", \"private\": false, \"version\": \"2.0.0-alpha.2\", \"description\": \"Express adapters for the Model Context Protocol TypeScript server SDK - Express middleware\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\" }, \"keywords\": \"modelcontextprotocol\", \"mcp\", \"express\", \"middleware\" , \"exports\": { \".\": { \"types\": \"./dist/index.d.mts\", \"import\": \"./dist/index.mjs\" } }, \"ty… 证据：`packages/middleware/express/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/fastify\", \"private\": false, \"version\": \"2.0.0-alpha.2\", \"description\": \"Fastify adapters for the Model Context Protocol TypeScript server SDK - Fastify middleware\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\" }, \"keywords\": \"modelcontextprotocol\", \"mcp\", \"fastify\", \"middleware\" , \"exports\": { \".\": { \"types\": \"./dist/index.d.mts\", \"import\": \"./dist/index.mjs\" } }, \"ty… 证据：`packages/middleware/fastify/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/hono\", \"private\": false, \"version\": \"2.0.0-alpha.2\", \"description\": \"Hono adapters for the Model Context Protocol TypeScript server SDK - Hono middleware\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\" }, \"keywords\": \"modelcontextprotocol\", \"mcp\", \"hono\", \"middleware\" , \"exports\": { \".\": { \"types\": \"./dist/index.d.mts\", \"import\": \"./dist/index.mjs\" } }, \"types\": \"./dis… 证据：`packages/middleware/hono/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/node\", \"version\": \"2.0.0-alpha.2\", \"description\": \"Model Context Protocol implementation for TypeScript - Node.js middleware\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\" }, \"keywords\": \"modelcontextprotocol\", \"mcp\", \"node.js\", \"middleware\" , \"exports\": { \".\": { \"types\": \"./dist/index.d.mts\", \"import\": \"./dist/index.mjs\" } }, \"types\": \"./dist/index.d.mts\", \"typesVers… 证据：`packages/middleware/node/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/server\", \"version\": \"2.0.0-alpha.2\", \"description\": \"Model Context Protocol implementation for TypeScript - Server package\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\" }, \"keywords\": \"modelcontextprotocol\", \"mcp\", \"server\" , \"exports\": { \".\": { \"types\": \"./dist/index.d.mts\", \"import\": \"./dist/index.mjs\" }, \"./stdio\": { \"types\": \"./dist/stdio.d.mts\", \"import\": \"./dis… 证据：`packages/server/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/test-conformance\", \"private\": true, \"version\": \"2.0.0-alpha.0\", \"description\": \"Model Context Protocol implementation for TypeScript\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\", \"pnpm\": \" =10.24.0\" }, \"packageManager\": \"pnpm@10.24.0\", \"keywords\": \"modelcontextprotocol\", \"mcp\" , \"scripts\": { \"lint\": \"eslint src/ && prettier --ignore-path ../../.prettierignore --chec… 证据：`test/conformance/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/test-helpers\", \"private\": true, \"version\": \"2.0.0-alpha.0\", \"description\": \"Model Context Protocol implementation for TypeScript\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\", \"pnpm\": \" =10.24.0\" }, \"packageManager\": \"pnpm@10.24.0\", \"keywords\": \"modelcontextprotocol\", \"mcp\" , \"scripts\": { \"lint\": \"eslint src/ && prettier --ignore-path ../../.prettierignore --check .\"… 证据：`test/helpers/package.json`\n- **Package**（package_manifest）：{ \"name\": \"@modelcontextprotocol/test-integration\", \"private\": true, \"version\": \"2.0.0-alpha.1\", \"description\": \"Model Context Protocol implementation for TypeScript\", \"license\": \"MIT\", \"author\": \"Anthropic, PBC https://anthropic.com \", \"homepage\": \"https://modelcontextprotocol.io\", \"bugs\": \"https://github.com/modelcontextprotocol/typescript-sdk/issues\", \"type\": \"module\", \"repository\": { \"type\": \"git\", \"url\": \"git+https://github.com/modelcontextprotocol/typescript-sdk.git\" }, \"engines\": { \"node\": \" =20\", \"pnpm\": \" =10.24.0\" }, \"packageManager\": \"pnpm@10.24.0\", \"keywords\": \"modelcontextprotocol\", \"mcp\" , \"scripts\": { \"lint\": \"eslint test/ && prettier --ignore-path ../../.prettierignore --che… 证据：`test/integration/package.json`\n- **License**（source_file）：The MCP project is undergoing a licensing transition from the MIT License to the Apache License, Version 2.0 \"Apache-2.0\" . All new code and specification contributions to the project are licensed under Apache-2.0. Documentation contributions excluding specifications are licensed under CC-BY-4.0. 证据：`LICENSE`\n- **Quickstart: Build an LLM-powered chatbot**（documentation）：Quickstart: Build an LLM-powered chatbot 证据：`docs/client-quickstart.md`\n- **Building MCP clients**（documentation）：This guide covers the TypeScript SDK APIs for building MCP clients. For protocol-level concepts, see the MCP overview https://modelcontextprotocol.io/docs/learn/architecture . 证据：`docs/client.md`\n- **Documents**（documentation）：- Server Quickstart ./server-quickstart.md – build a weather server from scratch and connect it to VS Code - Server ./server.md – building MCP servers: transports, tools, resources, prompts, server-initiated requests, and deployment - Client Quickstart ./client-quickstart.md – build an LLM-powered chatbot that connects to an MCP server and calls its tools - Client ./client.md – building MCP clients: connecting, tools, resources, prompts, server-initiated requests, and error handling - FAQ ./faq.md – frequently asked questions and troubleshooting 证据：`docs/documents.md`\n- **FAQ**（documentation）：- General general - Clients clients - Servers servers - v1 legacy v1-legacy 证据：`docs/faq.md`\n- **MCP TypeScript SDK: v1 → v2 Migration**（skill_instruction）：MCP TypeScript SDK: v1 → v2 Migration 证据：`docs/migration-SKILL.md`\n- **Migration Guide: v1 to v2**（documentation）：This guide covers the breaking changes introduced in v2 of the MCP TypeScript SDK and how to update your code. 证据：`docs/migration.md`\n- **Quickstart: Build a weather server**（documentation）：In this tutorial, we'll build a simple MCP weather server and connect it to a host. 证据：`docs/server-quickstart.md`\n- **Building MCP servers**（documentation）：This guide covers the TypeScript SDK APIs for building MCP servers. For protocol-level concepts — what tools, resources, and prompts are and when to use each — see the MCP overview https://modelcontextprotocol.io/docs/learn/architecture . 证据：`docs/server.md`\n- **Abort Handlers On Close**（documentation）：Abort in-flight request handlers when the connection closes. Previously, request handlers would continue running after the transport disconnected, wasting resources and preventing proper cleanup. Also fixes InMemoryTransport.close firing onclose twice on the initiating side. 证据：`.changeset/abort-handlers-on-close.md`\n- **Add Fastify Middleware**（documentation）：Add Fastify middleware adapter for MCP servers, following the same pattern as the Express and Hono adapters. 证据：`.changeset/add-fastify-middleware.md`\n- **Add Hono Peer Dep**（documentation）：Add missing hono peer dependency to @modelcontextprotocol/node . The package already depends on @hono/node-server which requires hono at runtime, but hono was only listed in the workspace root, not as a peer dependency of the package itself. 证据：`.changeset/add-hono-peer-dep.md`\n- **Add Resource Size Field**（documentation）：Add missing size field to ResourceSchema to match the MCP specification 证据：`.changeset/add-resource-size-field.md`\n- **Brave Lions Glow**（documentation）：Prevent Hono from overriding global Response object by passing overrideGlobalObjects: false to getRequestListener . This fixes compatibility with frameworks like Next.js whose response classes extend the native Response. 证据：`.changeset/brave-lions-glow.md`\n- **Busy Rice Smoke**（documentation）：tasks - disallow requesting a null TTL 证据：`.changeset/busy-rice-smoke.md`\n- **Busy Weeks Hang**（documentation）：Fix ReDoS vulnerability in UriTemplate regex patterns CVE-2026-0621 证据：`.changeset/busy-weeks-hang.md`\n- **Cfworker Out Of Barrel**（documentation）：Stop bundling @cfworker/json-schema into the main package barrel. Previously CfWorkerJsonSchemaValidator was re-exported from the core internal barrel, so tsdown inlined the @cfworker/json-schema dev dependency into every consumer's bundle even when it was never used. The validator is now reachable only via the shims conditional workerd/browser and the explicit @modelcontextprotocol/{server,client}/validators/cf-worker subpath, so consumers that don't opt into it no longer ship that code. No public API change. 证据：`.changeset/cfworker-out-of-barrel.md`\n- **Custom Methods Minimal**（documentation）：Add custom non-spec method support: a 3-arg setRequestHandler method, schemas, handler / setNotificationHandler method, schemas, handler form for vendor-prefixed methods, and a request req, resultSchema overload also on ctx.mcpReq.send for typed custom-method results. Spec-method calls are unchanged. 证据：`.changeset/custom-methods-minimal.md`\n- **Cyan Cycles Pump**（documentation）：missing change for fix client : replace body.cancel with text to prevent hanging 证据：`.changeset/cyan-cycles-pump.md`\n- **Drop Zod Peer Dep**（documentation）：Drop zod from peerDependencies kept as direct dependency 证据：`.changeset/drop-zod-peer-dep.md`\n- **Export Inmemory Transport**（documentation）：Export InMemoryTransport for in-process testing. 证据：`.changeset/export-inmemory-transport.md`\n- **Expose Auth Server Discovery**（documentation）：Add discoverOAuthServerInfo function and unified discovery state caching for OAuth 证据：`.changeset/expose-auth-server-discovery.md`\n- **Express Resource Server Auth**（documentation）：Add OAuth Resource-Server glue to the Express adapter: requireBearerAuth middleware token verification + RFC 6750 WWW-Authenticate challenges , mcpAuthMetadataRouter serves RFC 9728 Protected Resource Metadata and mirrors RFC 8414 AS metadata at the resource origin , the getOAuthProtectedResourceMetadataUrl helper, and the OAuthTokenVerifier interface. These restore the v1 src/server/auth Resource-Server pieces as first-class v2 API so MCP servers can plug into an external Authorization Server with a few lines of Express wiring. 证据：`.changeset/express-resource-server-auth.md`\n- **Extract Task Manager**（documentation）：refactor: extract task orchestration from Protocol into TaskManager 证据：`.changeset/extract-task-manager.md`\n- **Fast Dragons Lead**（documentation）：--- '@modelcontextprotocol/express': patch '@modelcontextprotocol/fastify': patch '@modelcontextprotocol/hono': patch '@modelcontextprotocol/node': patch '@modelcontextprotocol/client': patch '@modelcontextprotocol/server': patch --- tsdown exports resolution fix 证据：`.changeset/fast-dragons-lead.md`\n- **Finish Sdkerror Capability**（documentation）：Convert remaining capability-assertion throws to SdkError SdkErrorCode.CapabilityNotSupported, ... . Follow-up to 1454 which missed Client.assertCapability , the task capability helpers in experimental/tasks/helpers.ts , and the sampling/elicitation capability checks in experimental/tasks/server.ts . 证据：`.changeset/finish-sdkerror-capability.md`\n- **Fix Abort Listener Leak**（documentation）：Consolidate per-request cleanup in requestWithSchema into a single .finally block. This fixes an abort signal listener leak listeners accumulated when a caller reused one AbortSignal across requests and two cases where responseHandlers entries leaked on send-failure paths. 证据：`.changeset/fix-abort-listener-leak.md`\n- 其余 20 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`.changeset/README.md`, `CLAUDE.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`.changeset/README.md`, `CLAUDE.md`, `README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **MCP TypeScript SDK 概述**：importance `high`\n - source_paths: README.md, package.json, packages/core/src/index.ts\n- **系统架构与包结构**：importance `high`\n - source_paths: packages/server/package.json, packages/client/package.json, packages/middleware/node/package.json, pnpm-workspace.yaml, packages/core/src/types/spec.types.ts\n- **协议与类型定义**：importance `high`\n - source_paths: packages/core/src/shared/protocol.ts, packages/core/src/types/spec.types.ts, packages/core/src/types/types.ts, packages/core/src/types/errors.ts, packages/core/src/types/enums.ts\n- **数据验证与 Schema**：importance `high`\n - source_paths: packages/core/src/util/zodCompat.ts, packages/core/src/util/standardSchema.ts, packages/core/src/validators/fromJsonSchema.ts, packages/core/src/validators/ajvProvider.ts, packages/core/src/util/schema.ts\n- **传输层实现**：importance `high`\n - source_paths: packages/server/src/server/stdio.ts, packages/server/src/server/streamableHttp.ts, packages/client/src/client/stdio.ts, packages/client/src/client/streamableHttp.ts, packages/client/src/client/sse.ts\n- **服务器开发指南**：importance `high`\n - source_paths: packages/server/src/server/mcp.ts, packages/server/src/server/server.ts, examples/server/src/serverGuide.examples.ts, examples/server-quickstart/src/index.ts, docs/server-quickstart.md\n- **客户端开发指南**：importance `high`\n - source_paths: packages/client/src/client/client.ts, examples/client/src/clientGuide.examples.ts, examples/client-quickstart/src/index.ts, docs/client-quickstart.md, docs/client.md\n- **认证与授权机制**：importance `high`\n - source_paths: packages/core/src/shared/auth.ts, packages/core/src/shared/authUtils.ts, packages/client/src/client/auth.ts, packages/client/src/client/authExtensions.ts, packages/client/src/client/crossAppAccess.ts\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `2c0c481cb9dbfd15c8613f765c940a5f5bace94d`\n- inspected_files: `pnpm-lock.yaml`, `package.json`, `README.md`, `docs/migration-SKILL.md`, `docs/v2-banner.js`, `docs/server.md`, `docs/client-quickstart.md`, `docs/server-quickstart.md`, `docs/faq.md`, `docs/client.md`, `docs/migration.md`, `docs/documents.md`, `examples/server-quickstart/package.json`, `examples/server-quickstart/tsconfig.json`, `examples/client-quickstart/package.json`, `examples/client-quickstart/tsconfig.json`, `examples/server/tsdown.config.ts`, `examples/server/package.json`, `examples/server/README.md`, `examples/server/vitest.config.js`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：client code can't execute inside browser due to import spawn\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：client code can't execute inside browser due to import spawn\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8a06947266aa4987ad712baf87a7a156 | https://github.com/modelcontextprotocol/typescript-sdk/issues/2077 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `typescript-sdk` 与安装入口 `@modelcontextprotocol/server` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | repo=typescript-sdk; install=@modelcontextprotocol/server\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：@modelcontextprotocol/node@2.0.0-alpha.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/node@2.0.0-alpha.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_fc8de64b72814f8eb9ed0e53852408c2 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/node%402.0.0-alpha.1 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：@modelcontextprotocol/server@2.0.0-alpha.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/server@2.0.0-alpha.1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_dff36a13cb954c3b84b05e99a28dc4d0 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.0.0-alpha.1 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 存在安全注意事项\n\n- Trigger: No sandbox install has been executed yet; downstream must verify before user use.\n- Host AI rule: 转成明确权限清单和安全审查提示。\n- Why it matters: 用户安装前需要知道权限边界和敏感操作。\n- Evidence: 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.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：modelcontextprotocol/typescript-sdk\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：local_cli\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：client code can't execute inside browser due to import spawn（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 来源证据：@modelcontextprotocol/node@2.0.0-alpha.1（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：@modelcontextprotocol/server@2.0.0-alpha.1（medium）：可能影响升级、迁移或版本选择。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/modelcontextprotocol/typescript-sdk 项目说明书\n\n生成时间：2026-05-13 12:02:59 UTC\n\n## 目录\n\n- [MCP TypeScript SDK 概述](#page-1)\n- [系统架构与包结构](#page-2)\n- [协议与类型定义](#page-3)\n- [数据验证与 Schema](#page-4)\n- [传输层实现](#page-5)\n- [服务器开发指南](#page-6)\n- [客户端开发指南](#page-7)\n- [认证与授权机制](#page-8)\n- [Web 框架中间件集成](#page-9)\n- [实验性功能与任务系统](#page-10)\n\n\n\n## MCP TypeScript SDK 概述\n\n### 相关页面\n\n相关主题：[系统架构与包结构](#page-2), [服务器开发指南](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/README.md)\n- [CLAUDE.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)\n- [examples/server/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)\n- [examples/client/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/README.md)\n- [packages/server/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)\n- [packages/core/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)\n- [packages/client/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)\n- [packages/middleware/express/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/CHANGELOG.md)\n- [packages/middleware/hono/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/CHANGELOG.md)\n- [packages/middleware/fastify/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/CHANGELOG.md)\n- [common/tsconfig/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/common/tsconfig/package.json)\n \n\n# MCP TypeScript SDK 概述\n\n## 简介\n\nMCP TypeScript SDK（Model Context Protocol TypeScript SDK）是 Model Context Protocol 的 TypeScript/Node.js 实现，为开发者提供了构建 MCP 服务器和客户端的能力。该 SDK 采用 Monorepo 结构，包含核心包、客户端包、服务器包以及多种 Web 框架适配器。\n\n资料来源：[README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/README.md)\n\n## 架构设计\n\n### 两层导出结构\n\nSDK 采用精心设计的两层导出结构，以清晰分离内部实现和公共 API：\n\n```mermaid\ngraph TD\n A[\"@modelcontextprotocol/core
packages/core/src/index.ts\"] --> B[\"内部 barrel
导出全部内容\"]\n A --> C[\"包括 Zod schemas、Protocol 类、stdio 工具\"]\n B --> D[\"@modelcontextprotocol/core/public
packages/core/src/exports/public/index.ts\"]\n D --> E[\"仅导出：TypeScript 类型、错误类、常量、守卫函数\"]\n D --> F[\"@modelcontextprotocol/client\"]\n D --> G[\"@modelcontextprotocol/server\"]\n F --> H[\"最终公共表面\"]\n G --> H\n```\n\n资料来源：[CLAUDE.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)\n\n### 导出层级说明\n\n| 层级 | 包名 | 用途 | 可见性 |\n|------|------|------|--------|\n| 第一层 | `@modelcontextprotocol/core` | 内部 barrel，导出所有内容 | 私有，仅 monorepo 内部使用 |\n| 第二层 | `@modelcontextprotocol/core/public` | 精选公共 API | 公共 |\n| 第三层 | `@modelcontextprotocol/client` | 客户端特定导出 | 公共 |\n| 第三层 | `@modelcontextprotocol/server` | 服务器特定导出 | 公共 |\n\n**导出规范要求：**\n\n- 在包的 `index.ts` 文件和 `core/public` 中使用显式命名导出（`export *` 禁止）\n- 向包的 `index.ts` 添加符号会使其成为公共 API，需谨慎操作\n- 内部辅助函数应保留在 core 内部 barrel 中，不添加到 `core/public`\n\n资料来源：[CLAUDE.md:1-15](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)\n\n## 核心模块\n\n### 包结构总览\n\n```mermaid\ngraph LR\n subgraph \"核心包\"\n A[\"@modelcontextprotocol/core\"]\n end\n subgraph \"中间件适配器\"\n B[\"@modelcontextprotocol/express\"]\n C[\"@modelcontextprotocol/hono\"]\n D[\"@modelcontextprotocol/fastify\"]\n E[\"@modelcontextprotocol/node\"]\n end\n subgraph \"应用包\"\n F[\"@modelcontextprotocol/client\"]\n G[\"@modelcontextprotocol/server\"]\n end\n A --> F\n A --> G\n B --> G\n C --> G\n D --> G\n```\n\n### 传输系统\n\n传输层（`packages/core/src/shared/transport.ts`）提供通信层支持：\n\n- **Streamable HTTP**：现代推荐的传输方式，支持有状态和无状态模式\n- **SSE（Server-Sent Events）**：传统轮询方式，用于向后兼容\n\n资料来源：[CLAUDE.md:24-26](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)\n\n### 实验性功能\n\n实验性功能通过 `@modelcontextprotocol/sdk/experimental` 模块导出：\n\n```typescript\nimport { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';\n```\n\n资料来源：[packages/server/src/experimental/index.ts:1-10](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)\n\n## 服务器开发\n\n### 服务器示例索引\n\n| 场景 | 描述 | 文件 |\n|------|------|------|\n| Streamable HTTP 服务器（有状态） | 功能丰富的服务器，支持工具/资源/提示、日志、任务、采样和可选 OAuth | `src/simpleStreamableHttp.ts` |\n| Streamable HTTP 服务器（无状态） | 无会话跟踪，适用于简单的 API 风格服务器 | `src/simpleStatelessStreamableHttp.ts` |\n| 仅资源服务器认证 | 使用 SDK 的 `mcpAuthMetadataRouter` + `requireBearerAuth` 的最小化 OAuth RS | `src/resourceServerOnly.ts` |\n| JSON 响应模式（无 SSE） | 仅 JSON 响应的 Streamable HTTP，有限的通知支持 | `src/jsonResponseStreamableHttp.ts` |\n\n资料来源：[examples/server/README.md:20-30](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)\n\n### 运行服务器示例\n\n从仓库根目录运行：\n\n```bash\npnpm install\npnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts\n```\n\n或在示例包内运行：\n\n```bash\ncd examples/server\npnpm tsx src/simpleStreamableHttp.ts\n```\n\n资料来源：[examples/server/README.md:10-15](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)\n\n### Web 框架适配器\n\nSDK 提供多种 Web 框架的中间件适配器：\n\n| 适配器 | 包名 | 文档 |\n|--------|------|------|\n| Express | `@modelcontextprotocol/express` | `packages/middleware/express` |\n| Hono | `@modelcontextprotocol/hono` | `packages/middleware/hono` |\n| Fastify | `@modelcontextprotocol/fastify` | `packages/middleware/fastify` |\n| Node.js | `@modelcontextprotocol/node` | `packages/middleware/node` |\n\n所有中间件适配器均基于统一的适配器模式构建，遵循 Express 和 Hono 适配器的设计规范。\n\n资料来源：[packages/middleware/fastify/CHANGELOG.md:18-22](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/CHANGELOG.md)\n\n## 客户端开发\n\n### 客户端示例索引\n\n| 场景 | 描述 | 文件 |\n|------|------|------|\n| 交互式 Streamable HTTP 客户端 | CLI 客户端，测试工具/资源/提示、通知、 elicit 内容和任务 | `src/simpleStreamableHttp.ts` |\n| 向后兼容客户端 | 优先尝试 Streamable HTTP，在 4xx 响应时回退到传统 SSE | `src/streamableHttpWithSseFallbackClient.ts` |\n| SSE 轮询客户端（传统） | 轮询传统 HTTP+SSE 服务器，展示通知处理 | `src/ssePollingClient.ts` |\n| 并行工具调用 | 并行运行多个工具调用 | - |\n\n资料来源：[examples/client/README.md:18-25](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/README.md)\n\n### 运行客户端示例\n\n从仓库根目录运行：\n\n```bash\npnpm install\npnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts\n```\n\n大多数客户端示例需要先启动服务器（参考服务器示例）。\n\n资料来源：[examples/client/README.md:8-12](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/README.md)\n\n### 客户端核心功能\n\n#### OAuth 发现功能\n\nSDK 2.0.0-alpha.1 引入了 `discoverOAuthServerInfo()` 函数和统一的发现状态缓存机制。\n\n资料来源：[packages/client/CHANGELOG.md:14-17](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)\n\n#### WebSocket 变更\n\n**重要变更**：从 2.0.0-alpha.1 开始，`WebSocketClientTransport` 已被移除。WebSocket 不是规范定义的传输方式，请使用 stdio 或 Streamable HTTP。`Transport` 接口仍然导出以支持自定义实现。\n\n资料来源：[packages/client/CHANGELOG.md:10-14](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)\n\n## 核心包功能\n\n### 资源模式增强\n\nSDK 在 `ResourceSchema` 中添加了缺失的 `size` 字段，以匹配 MCP 规范。\n\n资料来源：[packages/core/CHANGELOG.md:2-4](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)\n\n### 安全修复\n\n#### ReDoS 漏洞修复\n\n修复了 UriTemplate 正则表达式模式中的 ReDoS 漏洞（CVE-2026-0621）。\n\n资料来源：[packages/core/CHANGELOG.md:6-8](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)\n\n### 能力断言规范化\n\nSDK 将剩余的能力断言转换为 `SdkError(SdkErrorCode.CapabilityNotSupported, ...)` 格式，包括：\n- `Client.assertCapability()`\n- 实验性任务辅助函数（`experimental/tasks/helpers.ts`）\n- 采样/elicitation 能力检查（`experimental/tasks/server.ts`）\n\n资料来源：[packages/core/CHANGELOG.md:9-15](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/CHANGELOG.md)\n\n## 版本历史\n\n### 最新版本动态\n\n| 包 | 当前版本 | 关键变更 |\n|----|----------|----------|\n| `@modelcontextprotocol/core` | 2.0.0 | 核心库 |\n| `@modelcontextprotocol/client` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n| `@modelcontextprotocol/server` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n| `@modelcontextprotocol/express` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n| `@modelcontextprotocol/hono` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n| `@modelcontextprotocol/fastify` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n| `@modelcontextprotocol/node` | 2.0.0-alpha.2 | tsdown exports resolution fix |\n\n所有中间件包的 2.0.0-alpha.2 版本都依赖于 `@modelcontextprotocol/server@2.0.0-alpha.2`。\n\n资料来源：[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)\n\n## 开发工具配置\n\n### TypeScript 配置\n\nSDK 使用统一的 TypeScript 配置：\n\n```json\n{\n \"name\": \"@modelcontextprotocol/tsconfig\",\n \"private\": true,\n \"main\": \"tsconfig.json\",\n \"type\": \"module\",\n \"dependencies\": {\n \"typescript\": \"catalog:devTools\"\n }\n}\n```\n\n资料来源：[common/tsconfig/package.json:1-13](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/common/tsconfig/package.json)\n\n## 快速开始\n\n### 安装依赖\n\n```bash\npnpm install\n```\n\n### 构建项目\n\n```bash\npnpm build\n```\n\n### 开发工作流\n\n```mermaid\ngraph LR\n A[\"安装 pnpm install\"] --> B[\"运行示例\"]\n B --> C[\"服务器示例
pnpm --filter @modelcontextprotocol/examples-server\"]\n B --> D[\"客户端示例
pnpm --filter @modelcontextprotocol/examples-client\"]\n```\n\n## 相关文档\n\n- [服务器开发指南](../../docs/server.md)\n- [客户端开发指南](../../docs/client.md)\n- [官方 MCP 规范](https://modelcontextprotocol.io)\n\n---\n\n\n\n## 系统架构与包结构\n\n### 相关页面\n\n相关主题：[MCP TypeScript SDK 概述](#page-1), [协议与类型定义](#page-3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/server/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/package.json)\n- [packages/client/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/package.json)\n- [packages/middleware/node/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/package.json)\n- [packages/core/src/types/spec.types.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/spec.types.ts)\n- [CLAUDE.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/CLAUDE.md)\n- [package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/package.json)\n \n\n# 系统架构与包结构\n\n## 概述\n\nMCP TypeScript SDK 是一个用于实现 Model Context Protocol (MCP) 的 TypeScript 工具包，采用 monorepo 结构组织。该 SDK 提供客户端和服务端的完整实现，支持多种传输层协议，包括 Streamable HTTP 和标准输入输出 (stdio)。SDK 的设计目标是分离内部实现与公共 API，确保只有经过审核的类型、错误类和守卫函数对外暴露，同时保持对浏览器和 Cloudflare Workers 等不同运行环境的兼容性。\n\n## 核心架构分层\n\nSDK 采用三层架构设计，从底层到顶层依次为：类型层 (Types Layer)、协议层 (Protocol Layer) 和高级 API 层 (High-Level APIs)。这种分层设计确保了关注点分离，便于维护和扩展。\n\n### 类型层 (Types Layer)\n\n类型层位于 `packages/core/src/types/types.ts`，定义了从 MCP 规范生成的所有协议类型。所有 JSON-RPC 消息类型、Zod 模式定义和协议常量都在这一层声明。类型层使用 Zod v4 进行运行时验证，确保数据的完整性和类型安全。资料来源：[CLAUDE.md]()\n\n```mermaid\ngraph TD\n A[MCP 规范] --> B[Types Layer]\n B --> C[JSON-RPC 消息类型]\n B --> D[Zod Schema]\n B --> E[协议常量]\n```\n\n### 协议层 (Protocol Layer)\n\n协议层位于 `packages/core/src/shared/protocol.ts`，包含抽象的 `Protocol` 类。该类负责处理 JSON-RPC 消息路由、请求/响应关联、能力协商和传输层管理。`Client` 和 `Server` 都继承自这个基类，共享核心协议逻辑。资料来源：[CLAUDE.md]()\n\n### 高级 API 层 (High-Level APIs)\n\n高级 API 层提供面向终端用户的接口：\n\n| 类名 | 文件位置 | 职责 |\n|------|---------|------|\n| `Client` | `packages/client/src/client/client.ts` | 客户端实现，扩展 Protocol 类，提供 MCP 操作的类型化方法 |\n| `Server` | `packages/server/src/server/server.ts` | 服务端实现，扩展 Protocol 类，提供请求处理器注册 |\n| `McpServer` | `packages/server/src/server/mcp.ts` | 高层服务器 API，简化资源/工具/提示的注册流程 |\n\n## 包结构概览\n\nSDK 采用 monorepo 结构，使用 pnpm workspaces 管理多个包。以下是主要包的层次结构：资料来源：[package.json]()\n\n```mermaid\ngraph TD\n subgraph 核心层\n A[@modelcontextprotocol/core]\n B[@modelcontextprotocol/core/public]\n end\n \n subgraph 公共API层\n C[@modelcontextprotocol/client]\n D[@modelcontextprotocol/server]\n end\n \n subgraph 中间件层\n E[@modelcontextprotocol/hono]\n F[@modelcontextprotocol/fastify]\n G[@modelcontextprotocol/node]\n end\n \n A --> B\n B --> C\n B --> D\n D --> E\n D --> F\n C --> G\n \n style A fill:#f9f,opacity:0.3\n style B fill:#ff9,opacity:0.3\n style C fill:#9f9,opacity:0.3\n style D fill:#9f9,opacity:0.3\n```\n\n## 核心包详解\n\n### @modelcontextprotocol/core\n\n这是 SDK 的内部核心包，所有内部代码都在此处实现。该包的主要入口文件为 `packages/core/src/index.ts`，导出内容包括 Zod 模式、Protocol 类和 stdio 工具函数。由于该包标记为 `private: true`，仅供 monorepo 内部的其他包消费，不对外部直接发布。\n\n核心导出结构：\n\n- **主入口** (`packages/core/src/index.ts`) — 内部桶，导出所有内部实现\n- **公共入口** (`packages/core/src/exports/public/index.ts`) — 精选的公共 API，仅包含 TypeScript 类型、错误类、常量和守卫函数\n\n### @modelcontextprotocol/client\n\n客户端包提供 MCP 协议的客户端实现，支持连接 MCP 服务器、调用工具、访问资源和获取提示。该包的入口文件导出命名符号，遵循显式导出而非 `export *` 的原则。\n\n支持的传输方式：\n\n| 传输类型 | 描述 | 适用场景 |\n|---------|------|---------|\n| Streamable HTTP | 推荐的现代传输方式，支持状态化会话 | Web 应用、服务端集成 |\n| stdio | 标准输入输出传输 | 本地进程、CLI 工具 |\n| SSE (Legacy) | 服务端发送事件，兼容旧版服务器 | 向后兼容 |\n\n资料来源：[packages/client/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/package.json)\n\n### @modelcontextprotocol/server\n\n服务端包提供 MCP 协议的服务端实现，允许开发者注册工具、资源、提示，并处理来自客户端的请求。该包是许多框架适配器的基础依赖。\n\n主要功能：\n\n- 工具注册与处理\n- 资源管理\n- 提示注册\n- 采样请求处理\n- 任务管理 (experimental)\n\n服务端包提供多个子路径导出以支持不同的运行环境：\n\n| 导出路径 | 类型定义 | 说明 |\n|---------|---------|------|\n| `.` | `dist/index.d.mts` | 主入口 |\n| `./stdio` | `dist/stdio.d.mts` | stdio 传输支持 |\n| `./validators/cf-worker` | `dist/validators/cfWorker.d.mts` | Cloudflare Workers 验证器 |\n| `./_shims` | 多环境 | workerd、browser、node 环境垫片 |\n\n资料来源：[packages/server/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/package.json)\n\n## 中间件与适配器层\n\n中间件层提供将 MCP 服务端集成到不同 Web 框架的适配器，简化常见服务器框架的使用。\n\n### @modelcontextprotocol/hono\n\nHono 框架适配器，用于在 Hono 应用中运行 MCP 服务端。Hono 是一个轻量、跨平台的 Web 框架，支持 Cloudflare Workers、Deno、Bun 等运行环境。\n\n```typescript\n// 使用示例结构\nimport { createMcpServer } from '@modelcontextprotocol/server';\nimport { Hono } from 'hono';\nimport { mcpHonoAdapter } from '@modelcontextprotocol/hono';\n\nconst app = new Hono();\nconst mcpServer = createMcpServer({ /* 配置 */ });\napp.use('/mcp', mcpHonoAdapter(mcpServer));\n```\n\n### @modelcontextprotocol/fastify\n\nFastify 框架适配器，提供与 Fastify 的集成。Fastify 以其高性能和低开销著称，适合需要高吞吐量的场景。资料来源：[packages/middleware/fastify/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/CHANGELOG.md)\n\n### @modelcontextprotocol/node\n\nNode.js 原生适配器，提供基于 `@hono/node-server` 的服务端实现。这是运行在标准 Node.js 环境中时推荐使用的中间件。\n\n该包已添加缺失的 `hono` peer 依赖，确保运行时依赖完整。资料来源：[packages/middleware/node/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/CHANGELOG.md)\n\n## 传输系统\n\n传输层位于 `packages/core/src/shared/transport.ts`，负责客户端与服务端之间的通信。SDK 支持多种传输机制，每种都有特定的适用场景。\n\n### Streamable HTTP\n\nStreamable HTTP 是 V2 版本推荐的传输方式，支持状态化会话管理。它允许服务器跟踪会话状态，适合需要维护上下文的复杂交互场景。\n\n```mermaid\ngraph LR\n A[Client] -->|HTTP POST /mcp| B[Streamable HTTP Server]\n B -->|Streaming Response| A\n A <-->|Session Token| B\n```\n\n### stdio 传输\n\nstdio 传输通过标准输入输出进行通信，适用于本地进程调用和命令行工具。这是 MCP 最初设计的传输方式，配置简单，无需网络。\n\n### 传输导出结构\n\n为确保运行时环境兼容性，stdio 相关的导出位于命名子路径：\n\n```typescript\n// 运行时中性导入（浏览器、Cloudflare Workers）\nimport { Client } from '@modelcontextprotocol/client';\n\n// Node.js 专用 stdio 导入\nimport { stdioClientTransport } from '@modelcontextprotocol/client/stdio';\n```\n\n资料来源：[packages/client/package.json](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/package.json)\n\n## 导出结构与命名规范\n\nSDK 采用两层导出结构来区分内部实现和公共 API，这是确保包边界清晰的关键设计。\n\n### 内部导出 (Internal Barrel)\n\n`@modelcontextprotocol/core` 的主入口导出所有内部实现，包括：\n\n- Zod 模式 (Schema)\n- Protocol 类\n- stdio 工具函数\n- 内部帮助函数\n\n这些导出仅供 monorepo 内部包使用，不应被外部代码直接依赖。\n\n### 公共导出 (Public API)\n\n`@modelcontextprotocol/core/public` 提供精选的公共 API，仅包含：\n\n| 类别 | 内容 |\n|-----|------|\n| TypeScript 类型 | 所有公共接口和类型定义 |\n| 错误类 | 异常处理类 |\n| 常量 | 协议常量 |\n| 守卫函数 | 类型守卫和验证函数 |\n\n### 包索引导出规则\n\n在修改导出时需遵循以下规则：\n\n1. **使用显式命名导出** — 包索引文件应使用 `export { SpecificExport }` 而非 `export *`\n2. **公共 API 变更需谨慎** — 添加到包索引的符号即成为公共 API\n3. **内部代码隔离** — 内部帮助函数应保留在 core 内部桶中\n4. **运行时中性** — 包根入口必须保持运行时中性，确保浏览器和 Cloudflare Workers 可正常打包\n\n## 实验性功能\n\nSDK 将某些功能标记为实验性，通过 `@modelcontextprotocol/sdk/experimental` 导出。当前实验性功能包括任务存储 (TaskStore) 相关实现。\n\n```typescript\n// 导入实验性功能\nimport { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';\n```\n\n实验性 API 可能随时变更，不提供稳定性保证。使用前请评估风险。\n\n资料来源：[packages/server/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)\n\n## 构建与工具链\n\nSDK 使用以下工具链进行开发和构建：\n\n| 工具 | 用途 | 配置位置 |\n|-----|------|---------|\n| pnpm | 包管理器 | `pnpm-workspace.yaml` |\n| TypeScript | 类型检查 | `tsconfig.json` |\n| tsdown | 包构建 | 各包的 `package.json` |\n| vitest | 测试框架 | `vitest.config.ts` |\n| typedoc | 文档生成 | TypeDoc 配置 |\n\n### 常用构建命令\n\n```bash\n# 安装依赖\npnpm install\n\n# 类型检查\npnpm typecheck:all\n\n# 构建所有包\npnpm build:all\n\n# 生成文档\npnpm docs\n\n# 运行测试\npnpm test\n```\n\n## 版本与兼容性\n\n| 包 | 当前版本 | Node.js 最低版本 |\n|----|---------|-----------------|\n| @modelcontextprotocol/client | 2.0.0-alpha.2 | >=20 |\n| @modelcontextprotocol/server | 2.0.0-alpha.2 | >=20 |\n| @modelcontextprotocol/sdk | 2.0.0-alpha.0 | >=20 |\n\nV2 版本移除了 WebSocket 传输，WebSocket 不是规范定义的传输方式。推荐使用 stdio 或 Streamable HTTP。如需自定义传输，可实现并使用 `Transport` 接口。资料来源：[packages/client/CHANGELOG.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/CHANGELOG.md)\n\n---\n\n\n\n## 协议与类型定义\n\n### 相关页面\n\n相关主题：[系统架构与包结构](#page-2), [数据验证与 Schema](#page-4)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/shared/protocol.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/shared/protocol.ts)\n- [packages/core/src/types/types.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/types.ts)\n- [packages/core/src/types/specTypeSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/specTypeSchema.ts)\n- [packages/core/src/validators/fromJsonSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/validators/fromJsonSchema.ts)\n- [packages/server/src/server/completable.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/completable.ts)\n \n\n# 协议与类型定义\n\n## 概述\n\nMCP TypeScript SDK 的核心架构建立在两层抽象之上：**协议层（Protocol Layer）** 和 **类型层（Types Layer）**。协议层负责 JSON-RPC 消息的路由、请求/响应关联、能力协商和传输管理；类型层则定义了所有 MCP 协议消息的 Zod v4 模式和数据结构。\n\n这两个层次共同构成了 SDK 的基础设施，支撑着 Client、Server 和 McpServer 的高级 API 实现。\n\n## 架构分层\n\n```mermaid\ngraph TB\n subgraph \"High-Level APIs\"\n McpServer[\"McpServer
packages/server/src/server/mcp.ts\"]\n Server[\"Server
packages/server/src/server/server.ts\"]\n Client[\"Client
packages/client/src/client/client.ts\"]\n end\n \n subgraph \"Protocol Layer\"\n Protocol[\"Protocol
packages/core/src/shared/protocol.ts\"]\n end\n \n subgraph \"Types Layer\"\n Types[\"Types
packages/core/src/types/types.ts\"]\n SpecTypes[\"SpecTypes
packages/core/src/types/specTypeSchema.ts\"]\n Schemas[\"Zod Schemas\"]\n end\n \n subgraph \"Transport Layer\"\n Transport[\"Transport Interface\"]\n end\n \n McpServer --> Server\n Server --> Protocol\n Client --> Protocol\n Protocol --> Types\n Protocol --> SpecTypes\n Protocol --> Transport\n Types --> Schemas\n```\n\n资料来源：[CLAUDE.md]()\n\n## 协议层\n\n### Protocol 基类\n\n`Protocol` 是 Client 和 Server 共同继承的抽象基类，处理所有底层协议逻辑：\n\n| 职责 | 说明 |\n|------|------|\n| JSON-RPC 消息路由 | 解析和分发 JSON-RPC 请求/响应/通知 |\n| 请求-响应关联 | 维护 pendingRequests Map，关联请求 ID 与回调 |\n| 能力协商 | 能力注册和匹配机制 |\n| 传输管理 | 底层通信抽象 |\n\n### JSON-RPC 消息类型\n\nMCP 协议使用标准 JSON-RPC 2.0 消息格式：\n\n| 消息类型 | 方向 | 说明 |\n|----------|------|------|\n| Request | 双向 | 需要响应的消息，带 `id` |\n| Response | 双向 | 对请求的响应，包含 `id` 和 `result`/`error` |\n| Notification | 双向 | 无需响应的消息，不带 `id` |\n\n```mermaid\nsequenceDiagram\n participant C as Client\n participant P as Protocol\n participant T as Transport\n \n C->>P: 构造 Request\n P->>P: 生成 requestId\n P->>P: 存储 PromiseResolver\n P->>T: 发送 JSON-RPC Request\n T->>P: 接收 JSON-RPC Response\n P->>P: 根据 requestId 恢复 Promise\n P->>C: 返回 Response\n```\n\n### 消息处理器注册\n\nProtocol 类提供方法注册各类消息的处理器：\n\n```typescript\n// 资料来源：packages/core/src/shared/protocol.ts\nrequestHandlers: Map\nnotificationHandlers: Map\n```\n\n## 类型层\n\n### 类型组织结构\n\n类型层位于 `packages/core/src/types/`，包含以下核心文件：\n\n| 文件 | 职责 |\n|------|------|\n| `types.ts` | MCP 协议类型定义，从规范生成 |\n| `specTypeSchema.ts` | StandardSchemaV1 类型架构 |\n| `errors.ts` | 错误类型定义 |\n| `enums.ts` | 枚举类型定义 |\n\n### 资源类型（Resources）\n\n资源用于向客户端暴露可读取的数据：\n\n```typescript\n// 资料来源：packages/core/src/types/types.ts\nexport type TextResourceContents = Infer;\nexport type BlobResourceContents = Infer;\nexport type Resource = Infer;\nexport type ResourceTemplate = Infer;\n```\n\n| 类型 | 说明 |\n|------|------|\n| `TextResourceContents` | 文本资源内容 |\n| `BlobResourceContents` | 二进制资源内容 |\n| `Resource` | 完整资源定义 |\n| `ResourceTemplate` | 资源模板（带占位符） |\n\n### 提示类型（Prompts）\n\n提示用于定义可复用的消息模板：\n\n```typescript\n// 资料来源：packages/core/src/types/types.ts\nexport type PromptArgument = Infer;\nexport type Prompt = Infer;\nexport type ListPromptsResult = Infer;\nexport type GetPromptRequest = Infer;\n```\n\n### 工具类型（Tools）\n\n工具是服务器暴露的可执行操作：\n\n| 类型 | 说明 |\n|------|------|\n| `CallToolRequest` | 工具调用请求 |\n| `CallToolResult` | 工具调用结果 |\n| `Tool` | 工具定义 |\n| `ToolAnnotations` | 工具注解（毒性、是否确定性等） |\n\n```typescript\n// 资料来源：packages/core/src/types/types.ts\nexport type CallToolResult = Infer;\nexport type Tool = Infer;\n```\n\n### 任务类型（Tasks）\n\n任务支持长时运行的异步操作：\n\n```typescript\n// 资料来源：packages/server/src/server/mcp.ts\ntype TaskHandlerInternal = {\n createTask: (args: unknown, ctx: CreateTaskServerContext) => CreateTaskResult | Promise;\n};\n```\n\n## StandardSchemaV1 类型系统\n\n### 概述\n\nSDK 使用 [StandardSchemaV1](https://github.com/ModelContextProtocol/typescript-sdk/blob/main/packages/core/src/types/specTypeSchema.ts) 作为输入输出的标准模式格式，这是一个供应商中立（vendor-neutral）的模式接口。\n\n### 模式注册机制\n\n`specTypeSchema.ts` 通过注册表模式将 MCP 规范中的所有类型映射到 StandardSchemaV1：\n\n```typescript\n// 资料来源：packages/core/src/types/specTypeSchema.ts\nconst _specTypeSchemas: Record = {};\nconst _isSpecType: Record boolean> = {};\n\nfunction register(key: string, schema: z.ZodType): void {\n const name = key.slice(0, -'Schema'.length);\n _specTypeSchemas[name] = schema;\n _isSpecType[name] = (v: unknown) => schema.safeParse(v).success;\n}\n```\n\n### SpecTypes 类型映射\n\n```typescript\n// 资料来源：packages/core/src/types/specTypeSchema.ts\nexport type SpecTypes = {\n [K in SchemaKey as StripSchemaSuffix]: SchemaFor extends z.ZodType ? z.output> : never;\n};\n```\n\n### 从 JSON Schema 转换\n\nSDK 提供 `fromJsonSchema` 函数将 JSON Schema 转换为 StandardSchemaV1：\n\n```typescript\n// 资料来源：packages/core/src/validators/fromJsonSchema.ts\nexport function fromJsonSchema(\n schema: JsonSchemaType, \n validator: jsonSchemaValidator\n): StandardSchemaWithJSON {\n return {\n '~standard': {\n version: 1,\n vendor: 'mcp',\n jsonSchema: {\n input: () => schema as Record,\n output: () => schema as Record\n },\n validate: (data: unknown): StandardSchemaV1.Result => {\n const result = check(data);\n return result.valid \n ? { value: result.data } \n : { issues: [{ message: result.errorMessage }] };\n }\n }\n };\n}\n```\n\n## Completable 类型\n\nCompletable 提供参数自动完成功能：\n\n```typescript\n// 资料来源：packages/server/src/server/completable.ts\nexport const COMPLETABLE_SYMBOL: unique symbol = Symbol.for('mcp.completable');\n\nexport type CompleteCallback = (\n value: StandardSchemaV1.InferInput,\n context?: {\n arguments?: Record;\n }\n) => StandardSchemaV1.InferInput[] | Promise[]>;\n\nexport type CompletableSchema = T & {\n [COMPLETABLE_SYMBOL]: CompletableMeta;\n};\n```\n\n使用示例：\n\n```typescript\n// 资料来源：packages/server/src/server/completable.ts\nserver.registerPrompt(\n 'review-code',\n {\n title: 'Code Review',\n argsSchema: z.object({\n language: completable(\n z.string().describe('Programming language'), \n value => ['typescript', 'javascript', 'python', 'rust', 'go']\n .filter(lang => lang.startsWith(value))\n )\n })\n },\n ({ language }) => ({\n messages: [{ role: 'user', content: { type: 'text', text: `Review this ${language} code.` } }]\n })\n);\n```\n\n## Zod Schema 结构\n\n### Schema 层级\n\n```mermaid\ngraph TD\n ZodType[\"z.ZodType
基础类型\"]\n ZodObject[\"z.ZodObject
对象类型\"]\n ZodArray[\"z.ZodArray
数组类型\"]\n ZodString[\"z.ZodString
字符串\"]\n ZodNumber[\"z.ZodNumber
数字\"]\n ZodBoolean[\"z.ZodBoolean
布尔值\"]\n \n ZodType --> ZodObject\n ZodType --> ZodArray\n ZodType --> ZodString\n ZodType --> ZodNumber\n ZodType --> ZodBoolean\n```\n\n### 模式验证流程\n\n```mermaid\nsequenceDiagram\n participant Input as 用户输入\n participant Schema as Zod Schema\n participant Validate as validateStandardSchema\n participant Output as 类型安全输出\n \n Input->>Schema: 原始数据\n Schema->>Validate: 调用 safeParse\n Validate->>Output: 验证成功，返回类型化数据\n Note over Validate,Output: parseResult.success === true\n```\n\n## 错误类型\n\nSDK 定义了结构化的错误类型：\n\n| 错误类型 | 说明 |\n|----------|------|\n| `JsonRpcError` | JSON-RPC 标准错误 |\n| `McpError` | MCP 特定错误 |\n| 错误码范围 | MCP 保留 10000-19999 |\n\n## 枚举类型\n\n`enums.ts` 定义了协议中使用的枚举值：\n\n| 枚举 | 用途 |\n|------|------|\n| 日志级别 | `debug`, `info`, `warning`, `error` |\n| 资源可见性 | `secret`, `information`, `documentation` |\n| 采样优先级 | `low`, `medium`, `high` |\n\n## 类型推断机制\n\nSDK 使用 TypeScript 的类型推断来提供类型安全：\n\n```typescript\n// 资料来源：packages/core/src/types/types.ts\n// 使用 Infer 类型工具从 Zod schema 推断 TypeScript 类型\nexport type Resource = Infer;\nexport type Prompt = Infer;\nexport type CallToolResult = Infer;\n```\n\n### Infer 类型定义\n\n```typescript\n// Infer 类型工具允许从 Zod schema 反向推断 TypeScript 类型\ntype Infer = T extends z.ZodType \n ? Output \n : never;\n```\n\n## 模式键名约定\n\nMCP 规范中的模式使用统一后缀约定：\n\n| 后缀 | 含义 | 示例 |\n|------|------|------|\n| `Schema` | 原始 Zod schema | `ListResourcesRequestSchema` |\n| 无后缀 | 推断后的 TypeScript 类型 | `ListResourcesRequest` |\n\n## 导出结构\n\nSDK 采用两层导出结构：\n\n```mermaid\ngraph LR\n subgraph \"@modelcontextprotocol/core\"\n Core[\"内部 barrel
导出所有内容\"]\n end\n \n subgraph \"@modelcontextprotocol/client\"\n Client[\"公共 API
客户端专用\"]\n end\n \n subgraph \"@modelcontextprotocol/server\"\n Server[\"公共 API
服务端专用\"]\n end\n \n Core --> Client\n Core --> Server\n```\n\n- **`@modelcontextprotocol/core`** — 内部 barrel，导出所有内容（包含 Zod schemas、Protocol 类等），仅供 monorepo 内部使用\n- **`@modelcontextprotocol/client`** — 客户端公共 API\n- **`@modelcontextprotocol/server`** — 服务端公共 API\n\n资料来源：[CLAUDE.md]()\n\n## 最佳实践\n\n### 类型安全保证\n\n1. **使用 Zod 进行运行时验证** — 所有输入都经过 Zod schema 验证\n2. **TypeScript 类型推断** — 减少手动类型标注，降低错误风险\n3. **StandardSchemaV1 抽象** — 支持供应商中立的模式定义\n\n### 模式设计\n\n| 实践 | 说明 |\n|------|------|\n| 显式类型注解 | 使用 `z.object()` 显式定义对象结构 |\n| 描述字段 | 使用 `.describe()` 提供字段文档 |\n| 默认值 | 使用 `.default()` 提供安全的默认值 |\n| 可选链 | 使用 `.optional()` 明确可选字段 |\n\n---\n\n\n\n## 数据验证与 Schema\n\n### 相关页面\n\n相关主题：[协议与类型定义](#page-3), [服务器开发指南](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/util/zodCompat.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/util/zodCompat.ts)\n- [packages/core/src/util/standardSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/util/standardSchema.ts)\n- [packages/core/src/validators/fromJsonSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/validators/fromJsonSchema.ts)\n- [packages/core/src/validators/ajvProvider.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/validators/ajvProvider.ts)\n- [packages/core/src/util/schema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/util/schema.ts)\n- [packages/server/src/server/completable.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/completable.ts)\n- [packages/core/src/types/specTypeSchema.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/specTypeSchema.ts)\n \n\n# 数据验证与 Schema\n\n## 概述\n\nMCP TypeScript SDK 提供了一套完整的 Schema 验证体系，支持多种 Schema 定义方式。该系统允许开发者使用任意实现了 [Standard Schema 规范](https://standardschema.dev/) 的验证库来定义工具（Tool）、提示（Prompt）和资源的输入输出结构。\n\nSDK 的验证架构基于以下核心原则：\n\n- **标准化接口**：使用 `StandardSchemaV1` 接口统一不同验证库的行为\n- **多库支持**：原生支持 Zod v4、Valibot、ArkType 等主流验证库\n- **JSON Schema 桥接**：通过 `fromJsonSchema` 适配器支持纯 JSON Schema\n- **向后兼容**：保留 Zod v3 的部分兼容层\n\n资料来源：[packages/core/src/util/standardSchema.ts:1-50]()\n\n## 架构图\n\n```mermaid\ngraph TD\n subgraph \"用户层\"\n ZOD_V4[Zod v4 Schema]\n VALIBOT[Valibot Schema]\n ARKTYPE[ArkType Schema]\n JSON_SCHEMA[Raw JSON Schema]\n RAW_SHAPE[Zod Raw Shape]\n end\n\n subgraph \"标准化层\"\n STD_SCHEMA[StandardSchemaV1]\n STD_JSON[StandardJSONSchemaV1]\n end\n\n subgraph \"适配器层\"\n ZOD_COMPAT[zodCompat.ts]\n FROM_JSON[fromJsonSchema.ts]\n NORMALIZE[normalizeRawShapeSchema]\n end\n\n subgraph \"验证器层\"\n ZOD_VALIDATOR[Zod 内置验证]\n AJV[AjvJsonSchemaValidator]\n CUSTOM[自定义验证器]\n end\n\n ZOD_V4 -->|原生实现| STD_SCHEMA\n VALIBOT -->|原生实现| STD_SCHEMA\n ARKTYPE -->|原生实现| STD_SCHEMA\n JSON_SCHEMA -->|fromJsonSchema| FROM_JSON\n RAW_SHAPE -->|auto-wrap| ZOD_COMPAT\n\n FROM_JSON --> AJV\n ZOD_COMPAT --> ZOD_VALIDATOR\n\n STD_SCHEMA -->|registerTool| MCP_SERVER\n STD_SCHEMA -->|registerPrompt| MCP_SERVER\n\n classDef sdk fill:#e1f5fe\n classDef adapter fill:#fff3e0\n classDef validator fill:#e8f5e9\n```\n\n## Standard Schema 支持\n\n### 标准接口定义\n\n`StandardSchemaV1` 是 MCP SDK 验证系统的核心接口，定义了所有 Schema 必须实现的标准化方法：\n\n```typescript\ninterface StandardSchemaV1 {\n '~standard': {\n version: 1;\n vendor: string;\n jsonSchema?: StandardJSONSchemaV1;\n validate?: (value: unknown) => StandardSchemaV1.Result;\n };\n}\n```\n\n资料来源：[packages/core/src/util/standardSchema.ts:1-30]()\n\n### 标准 Schema 工具函数\n\nSDK 提供了两个核心工具函数用于处理 Standard Schema：\n\n| 函数 | 作用 | 参数 |\n|------|------|------|\n| `standardSchemaToJsonSchema()` | 将 Standard Schema 转换为 JSON Schema | `schema`, `io` ('input' \\| 'output') |\n| `validateStandardSchema()` | 验证数据是否符合 Schema | `schema`, `data` |\n\n`standardSchemaToJsonSchema` 函数支持从多种 Schema 库提取 JSON Schema 表示：\n\n```typescript\nexport function standardSchemaToJsonSchema(\n schema: StandardJSONSchemaV1, \n io: 'input' | 'output' = 'input'\n): Record {\n const std = schema['~standard'];\n let result: Record;\n \n if (std.jsonSchema) {\n result = std.jsonSchema[io]({ target: 'draft-2020-12' });\n } else if (std.vendor === 'zod') {\n // Zod v4 实现 StandardSchemaV1 但没有 ~standard.jsonSchema\n // 回退到 z.toJSONSchema()\n }\n return result;\n}\n```\n\n资料来源：[packages/core/src/util/standardSchema.ts:60-90]()\n\n## Zod 兼容性\n\n### Zod 版本检测\n\nSDK 通过 `zodCompat.ts` 中的工具函数检测 Zod 版本差异：\n\n```typescript\nfunction isZodV4Schema(v: unknown): v is z.ZodType {\n // `_zod` 是 v4 内部命名空间属性\n return typeof v === 'object' && v !== null && '_zod' in v;\n}\n\nfunction looksLikeZodV3(v: unknown): boolean {\n // v3 schemas 有 `_def.typeName` (例如 'ZodString') 但没有 `_zod`\n return (\n typeof v === 'object' &&\n v !== null &&\n !('_zod' in v) &&\n '_def' in v &&\n typeof (v as { _def?: { typeName?: unknown } })._def?.typeName === 'string'\n );\n}\n```\n\n资料来源：[packages/core/src/util/zodCompat.ts:10-30]()\n\n### 版本兼容策略\n\n| Zod 版本 | 支持状态 | 说明 |\n|----------|----------|------|\n| Zod v4 (>= 4.2.0) | ✅ 原生支持 | 实现 `~standard.jsonSchema` 接口 |\n| Zod v4 (< 4.2.0) | ⚠️ 回退支持 | 回退到 `z.toJSONSchema()` |\n| Zod v3 | ❌ 不支持 | 无法转换为 JSON Schema |\n\n> 注意：SDK 已将 `zod` 从 `peerDependencies` 移除，保留为直接依赖。用户无需单独安装 Zod。\n\n资料来源：[packages/client/CHANGELOG.md](), [packages/core/src/util/standardSchema.ts:30-40]()\n\n## JSON Schema 支持\n\n### fromJsonSchema 适配器\n\n对于使用纯 JSON Schema 的场景（如 TypeBox 输出），SDK 提供了 `fromJsonSchema` 适配器：\n\n```typescript\nimport { fromJsonSchema, AjvJsonSchemaValidator } from '@modelcontextprotocol/core';\n\nconst schema = fromJsonSchema(\n { \n type: 'object', \n properties: { \n name: { type: 'string' } \n }, \n required: ['name'] \n },\n new AjvJsonSchemaValidator()\n);\n\nserver.registerTool(\n 'greet',\n { inputSchema: schema },\n async ({ name }) => ({ content: [{ type: 'text', text: `Hello, ${name}!` }] })\n);\n```\n\n资料来源：[packages/core/src/validators/fromJsonSchema.ts:20-40]()\n\n### AjvJsonSchemaValidator\n\n`AjvJsonSchemaValidator` 是基于 [AJV](https://ajv.js.org/) 的 JSON Schema 验证器实现：\n\n```typescript\nexport class AjvJsonSchemaValidator implements jsonSchemaValidator {\n private _ajv: Ajv;\n \n getValidator(schema: JsonSchemaType): ValidatorFn {\n const validate = this._ajv.compile(schema);\n return (data: unknown): ValidationResult => {\n const valid = validate(data);\n return valid \n ? { valid: true, data: data as T }\n : { valid: false, errorMessage: this._ajv.errorsText() };\n };\n }\n}\n```\n\n资料来源：[packages/core/src/validators/ajvProvider.ts]()\n\n## 工具与提示注册\n\n### registerTool 的 Schema 处理\n\n`McpServer.registerTool()` 方法接受 Standard Schema 作为 `inputSchema` 和 `outputSchema`：\n\n```typescript\n// 使用 Zod v4\nimport { z } from 'zod';\n\nserver.registerTool(\n 'calculate',\n {\n inputSchema: z.object({\n a: z.number(),\n b: z.number()\n }),\n outputSchema: z.object({\n result: z.number()\n })\n },\n async ({ a, b }) => ({\n content: [{ type: 'text', text: `${a + b}` }]\n })\n);\n\n// 使用 ArkType\nimport { type } from 'arktype';\n\nserver.registerTool(\n 'greet',\n {\n inputSchema: type({ name: 'string' })\n },\n async ({ name }) => ({ content: [{ type: 'text', text: `Hello, ${name}!` }] })\n);\n```\n\n资料来源：[packages/server/src/server/mcp.ts:150-200]()\n\n### registerPrompt 的 Schema 处理\n\n`registerPrompt` 支持类似的 Schema 定义方式：\n\n```typescript\nserver.registerPrompt(\n 'review-code',\n {\n title: 'Code Review',\n description: 'Review code for best practices',\n argsSchema: z.object({\n code: z.string(),\n language: z.enum(['typescript', 'javascript', 'python'])\n })\n },\n ({ code, language }) => ({\n messages: [\n {\n role: 'user' as const,\n content: {\n type: 'text' as const,\n text: `Please review this ${language} code:\\n\\n${code}`\n }\n }\n ]\n })\n);\n```\n\n资料来源：[packages/server/src/server/mcp.ts:100-150]()\n\n## Raw Shape 简化语法\n\n### 自动包装机制\n\n为简化 Zod 使用，SDK 支持 \"raw shape\" 语法——直接传递字段定义对象而无需显式包装：\n\n```typescript\n// 标准方式\nserver.registerTool('tool1', {\n inputSchema: z.object({ name: z.string() })\n}, handler);\n\n// Raw Shape 方式 (自动包装)\nserver.registerTool('tool2', {\n inputSchema: { name: z.string() } // 自动变成 z.object({...})\n}, handler);\n```\n\n内部通过 `normalizeRawShapeSchema()` 函数实现自动包装：\n\n```typescript\nfunction normalizeRawShapeSchema(schema: unknown): StandardSchemaWithJSON | undefined {\n if (schema === undefined || schema === null) return undefined;\n if (isStandardSchema(schema)) return schema;\n if (isZodV4Schema(schema)) return schema as StandardSchemaWithJSON;\n if (looksLikeZodV3(schema)) {\n // Zod v3: 包装成 z.object()\n return z.object(schema as ZodRawShape);\n }\n // ... 其他处理\n}\n```\n\n资料来源：[packages/core/src/util/zodCompat.ts:40-80]()\n\n## 可补全 Schema\n\n### completable 函数\n\nSDK 提供了 `completable()` 包装器，为 Schema 字段添加自动补全功能：\n\n```typescript\nimport { completable } from '@modelcontextprotocol/server';\n\nserver.registerPrompt(\n 'review-code',\n {\n argsSchema: z.object({\n language: completable(\n z.string().describe('Programming language'),\n (value) => ['typescript', 'javascript', 'python', 'rust', 'go']\n .filter(lang => lang.startsWith(value))\n )\n })\n },\n ({ language }) => ({\n messages: [{\n role: 'user',\n content: { type: 'text', text: `Review this ${language} code.` }\n }]\n })\n);\n```\n\n`CompletableSchema` 在标准 Schema 基础上添加了补全元数据：\n\n```typescript\nexport type CompletableSchema = T & {\n [COMPLETABLE_SYMBOL]: CompletableMeta;\n};\n```\n\n资料来源：[packages/server/src/server/completable.ts:20-50]()\n\n## 内置 Schema 类型\n\n### 协议类型定义\n\nMCP SDK 使用 Zod v4 定义了所有协议消息类型：\n\n```typescript\ntype SpecTypeInputs = {\n [K in SchemaKey as StripSchemaSuffix]: SchemaFor extends z.ZodType \n ? z.input> \n : never;\n};\n\ntype SpecTypes = {\n [K in SchemaKey as StripSchemaSuffix]: SchemaFor extends z.ZodType \n ? z.output> \n : never;\n};\n```\n\n通过 `register()` 函数批量注册所有规范类型：\n\n```typescript\nfor (const key of SPEC_SCHEMA_KEYS) {\n register(key, schemas[key]);\n}\n```\n\n资料来源：[packages/core/src/types/specTypeSchema.ts:20-50]()\n\n### 常用类型列表\n\n| 类型 | 用途 | Schema |\n|------|------|--------|\n| `CallToolRequest` | 工具调用请求 | CallToolRequestSchema |\n| `CallToolResult` | 工具调用结果 | CallToolResultSchema |\n| `GetPromptRequest` | 获取提示请求 | GetPromptRequestSchema |\n| `Resource` | 资源定义 | ResourceSchema |\n| `Prompt` | 提示定义 | PromptSchema |\n\n完整类型列表参见 [packages/core/src/types/types.ts]()。\n\n## 验证流程\n\n### 数据验证时序\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Validator\n participant Schema\n\n Client->>Server: registerTool(name, inputSchema, handler)\n Server->>Schema: 标准化 Schema\n Schema-->>Server: StandardSchemaV1\n\n Client->>Server: tools/call 请求\n Server->>Validator: validate(inputData)\n Validator->>Schema: 执行验证\n Schema-->>Validator: ValidationResult\n\n alt 验证通过\n Validator-->>Server: { valid: true, data }\n Server->>Server: 调用 handler\n Server-->>Client: 工具结果\n else 验证失败\n Validator-->>Server: { valid: false, issues }\n Server-->>Client: InvalidParams 错误\n end\n```\n\n## 最佳实践\n\n### Schema 选择建议\n\n| 场景 | 推荐方案 |\n|------|----------|\n| 新项目 | Zod v4 或 ArkType（类型推断完善） |\n| 已有 TypeBox 代码 | `fromJsonSchema` + `AjvJsonSchemaValidator` |\n| 轻量级验证 | Valibot（Bundle 体积小） |\n| 简单场景 | Raw Shape 语法 |\n\n### 迁移指南\n\n**从 Zod v3 迁移：**\n\n```typescript\n// Zod v3\nimport { z } from 'zod';\nconst schema = z.object({ name: z.string() });\n\n// Zod v4 (推荐)\nimport { z } from 'zod';\nconst schema = z.object({ name: z.string() }); // 兼容\n\n// 或使用其他库\nimport { type } from 'arktype';\nconst schema = type({ name: 'string' });\n```\n\n**处理 JSON Schema：**\n\n```typescript\nimport { fromJsonSchema, AjvJsonSchemaValidator } from '@modelcontextprotocol/core';\n\n// TypeBox 输出\nconst typeBoxSchema = Type.Strict(Type.Object({ name: Type.String() }));\n\n// 转换为 Standard Schema\nconst standardSchema = fromJsonSchema(\n TypeBox.toJsonSchema(typeBoxSchema),\n new AjvJsonSchemaValidator()\n);\n```\n\n## 相关配置\n\n### AjvJsonSchemaValidator 配置选项\n\n```typescript\nimport Ajv from 'ajv';\n\nconst ajv = new Ajv({\n allErrors: true, // 返回所有错误而非首次错误\n strict: false, // 禁用严格模式\n coerceTypes: false // 禁用类型强制\n});\n\nconst validator = new AjvJsonSchemaValidator(ajv);\n```\n\n## 总结\n\nMCP TypeScript SDK 的数据验证系统提供了灵活且强大的 Schema 支持：\n\n- 通过 **Standard Schema** 规范实现多库统一接口\n- 原生支持 **Zod v4**、Valibot、ArkType 等主流验证库\n- **JSON Schema** 通过 AJV 验证器完整支持\n- **Raw Shape** 语法简化常见使用场景\n- **completable()** 提供字段自动补全能力\n\n这套设计使开发者能够使用自己熟悉的验证库，同时保持与 MCP 协议的完全兼容。\n\n---\n\n\n\n## 传输层实现\n\n### 相关页面\n\n相关主题：[服务器开发指南](#page-6), [客户端开发指南](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/server/src/server/stdio.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/stdio.ts)\n- [packages/server/src/server/streamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/streamableHttp.ts)\n- [packages/client/src/client/stdio.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/stdio.ts)\n- [packages/client/src/client/streamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/streamableHttp.ts)\n- [packages/client/src/client/sse.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/sse.ts)\n- [packages/middleware/node/src/streamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/node/src/streamableHttp.ts)\n \n\n# 传输层实现\n\nMCP TypeScript SDK 的传输层（Transport Layer）是客户端与服务器之间通信的核心抽象层，负责消息的发送、接收和协议处理。该层实现了多种传输协议，包括 Streamable HTTP、传统 SSE 以及 stdio 方式，以满足不同场景下的集成需求。\n\n## 架构概览\n\n传输层采用接口抽象设计，通过 `Transport` 接口定义统一的通信契约。不同的传输实现（如 HTTP、stdio）都遵循这一接口规范，使得上层业务逻辑与底层传输方式解耦。\n\n```mermaid\ngraph TB\n subgraph \"客户端传输层\"\n C_STDIO[ClientStdioTransport]\n C_HTTP[ClientStreamableHttpTransport]\n C_SSE[ClientSseTransport]\n end\n \n subgraph \"服务端传输层\"\n S_STDIO[ServerStdioTransport]\n S_HTTP[ServerStreamableHttpTransport
WebStandardStreamableHTTPServerTransport]\n S_NODE_HTTP[NodeStreamableHTTPServerTransport]\n end\n \n subgraph \"核心传输接口\"\n Transport[Transport Interface]\n end\n \n C_STDIO --> Transport\n C_HTTP --> Transport\n C_SSE --> Transport\n Transport --> S_STDIO\n Transport --> S_HTTP\n Transport --> S_NODE_HTTP\n```\n\n## 核心接口定义\n\n传输层的核心是 `Transport` 接口，它定义了所有传输实现必须实现的方法和属性。该接口位于核心包中，被客户端和服务端共同依赖。\n\n### Transport 接口契约\n\n| 方法/属性 | 类型 | 描述 |\n|-----------|------|------|\n| `start()` | `Promise` | 启动传输层，开始监听/连接 |\n| `send(message)` | `Promise` | 发送 JSON-RPC 消息 |\n| `close()` | `Promise` | 关闭传输连接 |\n| `onclose` | `() => void` | 连接关闭回调 |\n| `onerror` | `(error: Error) => void` | 错误处理回调 |\n| `onmessage` | `(message: JSONRPCMessage) => void` | 消息接收回调 |\n| `onopen` | `() => void` | 连接打开回调 |\n\n## Streamable HTTP 传输\n\nStreamable HTTP 是 MCP SDK 推荐的主要传输协议，适用于远程服务器通信。该协议支持服务端发送（SSE）进行流式消息推送，同时兼容传统的请求-响应模式。\n\n### 服务端实现\n\n#### WebStandardStreamableHTTPServerTransport\n\n`WebStandardStreamableHTTPServerTransport` 是核心的 Web 标准 HTTP 服务器传输实现，支持两种运行模式：\n\n**有状态模式（Stateful）**：启用会话追踪，适用于需要维护状态的复杂应用场景。\n\n```typescript\nconst transport = new WebStandardStreamableHTTPServerTransport({\n sessionIdGenerator: () => crypto.randomUUID()\n});\n\nawait server.connect(transport);\n```\n\n**无状态模式（Stateless）**：不维护会话状态，适合简单的 API 风格服务器。\n\n```typescript\nconst transport = new WebStandardStreamableHTTPServerTransport({\n sessionIdGenerator: undefined\n});\n```\n\n资料来源：[packages/server/src/server/streamableHttp.ts:1-50]()\n\n#### NodeStreamableHTTPServerTransport\n\n`NodeStreamableHTTPServerTransport` 是针对 Node.js 环境优化的传输实现，内部封装了 `WebStandardStreamableHTTPServerTransport`，并使用 `getRequestListener` 将 Node.js HTTP 请求转换为 Web 标准请求。\n\n```typescript\nconst transport = new NodeStreamableHTTPServerTransport(options);\n\napp.all('/mcp', async c => {\n return transport.handleRequest(c.req.raw);\n});\n```\n\n该传输使用 `WeakMap` 存储每个请求的上下文信息，包括认证信息和解析后的请求体：\n\n```typescript\nprivate _requestContext: WeakMap = new WeakMap();\n```\n\n资料来源：[packages/middleware/node/src/streamableHttp.ts:1-80]()\n\n### 客户端实现\n\n`ClientStreamableHttpTransport` 实现了客户端侧的 Streamable HTTP 通信，支持与服务器的 SSE 消息流交互。\n\n```mermaid\nsequenceDiagram\n participant Client\n participant HttpTransport as ClientStreamableHttpTransport\n participant Server as Streamable HTTP Server\n \n Client->>HttpTransport: 创建传输实例\n Client->>HttpTransport: 调用 start()\n HttpTransport->>Server: 初始化请求\n Server-->>HttpTransport: 返回 SSE 流\n loop 消息循环\n Server->>HttpTransport: SSE 事件 (message)\n HttpTransport->>Client: 触发 onmessage\n Client->>HttpTransport: 调用 send()\n HttpTransport->>Server: POST 请求发送消息\n end\n```\n\n### 核心配置选项\n\nStreamable HTTP 传输支持多种配置选项：\n\n| 配置项 | 类型 | 默认值 | 描述 |\n|--------|------|--------|------|\n| `sessionIdGenerator` | `(() => string) \\| undefined` | `() => crypto.randomUUID()` | 会话 ID 生成器，undefined 表示无状态模式 |\n| `enableJsonResponse` | `boolean` | `false` | 启用纯 JSON 响应模式（禁用 SSE） |\n| `authProvider` | `AuthProvider \\| OAuthClientProvider` | `undefined` | 认证提供者 |\n| `statusLevel` | `number` | `200` | 日志级别阈值 |\n\n## Stdio 传输\n\nStdio（标准输入/输出）传输适用于本地进程集成场景，常见于本地 MCP 服务器或 CLI 工具集成。\n\n```mermaid\ngraph LR\n subgraph \"父进程\"\n ParentStdin[stdin]\n ParentStdout[stdout]\n ParentStderr[stderr]\n end\n \n subgraph \"子进程 MCP Server\"\n ServerStdin[stdin]\n ServerStdout[stdout]\n end\n \n ParentStdin --> ServerStdin\n ServerStdout --> ParentStdout\n```\n\n### 服务端 Stdio 传输\n\n服务端 `StdioServerTransport` 监听标准输入，将接收到的数据解析为 JSON-RPC 消息，并通过标准输出发送响应。\n\n```typescript\nimport { StdioServerTransport } from '@modelcontextprotocol/server';\n\nconst transport = new StdioServerTransport();\nawait server.connect(transport);\n```\n\n### 客户端 Stdio 传输\n\n客户端 `StdioClientTransport` 通过子进程方式启动 MCP 服务器，通过 stdin/stdout 与服务器进程通信。\n\n```typescript\nimport { StdioClientTransport } from '@modelcontextprotocol/client';\n\nconst transport = new StdioClientTransport({\n command: 'npx',\n args: ['-y', '@modelcontextprotocol/server-filesystem', '/path/to/dir']\n});\n\nawait client.connect(transport);\n```\n\n## SSE 传输（传统兼容）\n\nSSE（Server-Sent Events）传输是向后兼容的遗留实现，用于支持旧版 MCP 服务器的通信。\n\n### 客户端 SSE 轮询\n\n`SSEClientTransport` 实现了基于 SSE 的轮询机制，定期从服务器获取更新。\n\n```typescript\nconst transport = new SSEClientTransport(\n new URL('http://localhost:3000/mcp')\n);\n\nawait client.connect(transport);\n```\n\n该传输包含以下核心功能：\n\n| 功能 | 描述 |\n|------|------|\n| 消息队列 | 维护待处理消息队列 |\n| 重试机制 | 连接失败时自动重试 |\n| 心跳检测 | 定期发送心跳保持连接 |\n\n## 中间件系统\n\n客户端传输层支持中间件扩展，允许在请求/响应链中插入自定义逻辑。\n\n### 日志中间件\n\n`loggingMiddleware` 提供了请求/响应的详细日志记录功能：\n\n```typescript\nimport { loggingMiddleware } from '@modelcontextprotocol/client';\n\nconst transport = new ClientStreamableHttpTransport(url, {\n requestInit: {\n headers: {\n Authorization: `Bearer ${token}`\n }\n },\n middlewares: [\n loggingMiddleware({\n includeRequestHeaders: true,\n includeResponseHeaders: true,\n statusLevel: 300\n })\n ]\n});\n```\n\n中间件接收和返回 `fetch` 风格的请求/响应，支持请求拦截和响应修改。\n\n### 中间件管道\n\n多个中间件可以组合成管道，按顺序执行：\n\n```typescript\nconst composedMiddleware = composeFetchMiddlewares([middleware1, middleware2, middleware3]);\n```\n\n每个中间件的签名如下：\n\n```typescript\ntype FetchMiddleware = (\n next: FetchFn\n) => (input: RequestInfo, init?: RequestInit) => Promise;\n```\n\n## 认证集成\n\n传输层内置了对 OAuth 2.0 和 Bearer Token 认证的支持。\n\n### AuthProvider 接口\n\n```typescript\ninterface AuthProvider {\n token(): Promise;\n onUnauthorized?(ctx: AuthContext): Promise;\n}\n```\n\n### Bearer Token 认证\n\n简单的 Bearer Token 认证可以通过对象字面量实现：\n\n```typescript\nconst transport = new ClientStreamableHttpTransport(url, {\n authProvider: {\n token: async () => myApiKey\n }\n});\n```\n\n### OAuth 认证\n\nOAuth 客户端提供者会被传输自动适配，无需额外配置：\n\n```typescript\nimport { OAuthClientProvider } from '@modelcontextprotocol/core';\n\nconst oauthProvider: OAuthClientProvider = {\n getAccessToken: () => Promise.resolve(token),\n setAccessToken: (token) => { /* ... */ }\n};\n\nconst transport = new ClientStreamableHttpTransport(url, {\n authProvider: oauthProvider\n});\n```\n\n传输层在每次请求前调用 `authProvider.token()` 获取令牌，在收到 401 响应时调用 `onUnauthorized()` 进行重试。\n\n## 使用示例\n\n### 运行服务端示例\n\n```bash\n# 从仓库根目录运行\npnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts\n\n# 或从包目录运行\ncd examples/server\npnpm tsx src/simpleStreamableHttp.ts\n```\n\n### 运行客户端示例\n\n```bash\n# 客户端需要先启动服务器\npnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts\n```\n\n### 兼容模式客户端\n\n向后兼容的客户端会优先尝试 Streamable HTTP，失败时回退到 SSE：\n\n```typescript\n// 使用 streamableHttpWithSseFallbackClient\npnpm --filter @modelcontextprotocol/examples-client exec tsx src/streamableHttpWithSseFallbackClient.ts\n```\n\n资料来源：[examples/server/README.md:1-60]()\n\n## 总结\n\nMCP TypeScript SDK 的传输层设计遵循了以下原则：\n\n1. **接口抽象**：通过 `Transport` 接口统一不同传输实现的契约\n2. **环境适配**：提供 Web 标准、Node.js 和 stdio 三种环境的专用传输\n3. **向后兼容**：通过 SSE 传输支持遗留服务器\n4. **扩展性**：中间件系统允许灵活扩展传输功能\n5. **安全性**：内置 OAuth 和 Bearer Token 认证支持\n\n开发者应根据具体场景选择合适的传输方式：远程服务推荐使用 Streamable HTTP，本地进程集成使用 stdio，遗留系统使用 SSE 传输。\n\n---\n\n\n\n## 服务器开发指南\n\n### 相关页面\n\n相关主题：[客户端开发指南](#page-7), [认证与授权机制](#page-8)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/server/src/server/mcp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/mcp.ts)\n- [packages/server/src/server/server.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/server/server.ts)\n- [examples/server/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/README.md)\n- [examples/server/src/simpleStreamableHttp.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/server/src/simpleStreamableHttp.ts)\n- [docs/server.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server.md)\n- [docs/server-quickstart.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/server-quickstart.md)\n \n\n# 服务器开发指南\n\n## 概述\n\n服务器开发指南旨在帮助开发者使用 MCP TypeScript SDK 构建 MCP 服务器。MCP（Model Context Protocol）服务器是向 LLM（大语言模型）提供工具、资源和提示的桥梁，使 AI 能够与外部系统交互并执行实际操作。\n\nMCP SDK 提供两种服务器实现层级：\n\n1. **基础 Server 类** (`packages/server/src/server/server.ts`) - 低层级协议封装，处理 JSON-RPC 消息路由\n2. **McpServer 类** (`packages/server/src/server/mcp.ts`) - 高层级 API，简化资源/工具/提示的注册流程\n\n资料来源：[examples/server/README.md:1-10]()\n\n## 架构设计\n\n### 服务器层级结构\n\n```mermaid\ngraph TD\n A[McpServer 高层API] --> B[Server 基础协议类]\n B --> C[Protocol 协议处理核心]\n C --> D[Transport 传输层]\n \n A --> E[工具注册]\n A --> F[资源注册]\n A --> G[提示注册]\n \n style A fill:#e1f5fe\n style B fill:#fff3e0\n style C fill:#f3e5f5\n```\n\n### 核心组件职责\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| McpServer | `packages/server/src/server/mcp.ts` | 提供工具、资源、提示的注册接口 |\n| Server | `packages/server/src/server/server.ts` | 处理 JSON-RPC 协议、请求/响应关联 |\n| Protocol | `packages/core/src/shared/protocol.ts` | 消息路由、能力协商、传输管理 |\n\n资料来源：[CLAUDE.md:25-35]()\n\n## 快速开始\n\n### 环境准备\n\n```bash\n# 安装依赖\npnpm install\n\n# 运行服务器示例\npnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts\n```\n\n### 基础服务器创建\n\n```typescript\nimport { McpServer } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StreamableHTTPTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\nimport { z } from \"zod\";\n\nconst server = new McpServer({\n name: \"my-server\",\n version: \"1.0.0\",\n});\n\n// 注册工具\nserver.tool(\n \"calculate\",\n \"执行数学计算\",\n { a: z.number(), b: z.number(), operation: z.enum([\"add\", \"subtract\"]) },\n async ({ a, b, operation }) => {\n const result = operation === \"add\" ? a + b : a - b;\n return { result };\n }\n);\n\n// 启动服务器\nconst transport = new StreamableHTTPTransport();\nawait server.connect(transport);\nawait transport.start();\n```\n\n资料来源：[docs/server-quickstart.md:1-30]()\n\n## 工具注册\n\n### 工具注册 API\n\nMcpServer 提供 `tool()` 方法注册工具，支持两种调用形式：\n\n```typescript\n// 标准 Schema 形式\nserver.tool(\n name: string,\n description: string,\n argsSchema: T,\n cb: ToolCallback\n): RegisteredTool\n\n// 废弃的 Zod Raw Shape 形式（自动包装为 z.object()）\nserver.tool(\n name: string,\n description: string,\n argsSchema: T,\n cb: LegacyToolCallback\n): RegisteredTool\n```\n\n### 工具注册参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| name | string | 是 | 工具唯一标识名 |\n| description | string | 是 | 工具功能描述 |\n| argsSchema | ZodSchema/ZodRawShape | 是 | 参数验证 Schema |\n| cb | ToolCallback | 是 | 工具执行回调函数 |\n\n资料来源：[packages/server/src/server/mcp.ts:150-180]()\n\n### 工具动态管理\n\n注册后的工具返回 `RegisteredTool` 对象，支持运行时动态更新：\n\n```typescript\nconst tool = server.tool(\"greet\", \"问候用户\", { name: z.string() }, async ({ name }) => {\n return { message: `Hello, ${name}!` };\n});\n\n// 动态更新\ntool.update({\n title: \"新标题\",\n description: \"新描述\",\n enabled: false,\n callback: async ({ name }) => ({ message: `Hi, ${name}!` })\n});\n\n// 启用/禁用\ntool.enable();\ntool.disable();\n\n// 删除工具\ntool.remove();\n```\n\n工具更新时，如果修改了 `paramsSchema` 或 `callback`，系统会自动重新生成执行器：\n\n```typescript\nif (updates.paramsSchema !== undefined) {\n registeredTool.inputSchema = updates.paramsSchema;\n needsExecutorRegen = true;\n}\nif (updates.callback !== undefined) {\n registeredTool.handler = updates.callback;\n needsExecutorRegen = true;\n}\n```\n\n资料来源：[packages/server/src/server/mcp.ts:200-240]()\n\n## 资源注册\n\n### 资源类型\n\nMCP 服务器可暴露两类资源：\n\n1. **静态资源** (`Resource`) - 固定 URI 的资源\n2. **资源模板** (`ResourceTemplate`) - 支持 URI 参数化的动态资源\n\n### 注册静态资源\n\n```typescript\nserver.resource(\n \"config\",\n \"app://config\",\n (uri: URL) => {\n return {\n contents: [{\n uri: uri.toString(),\n mimeType: \"application/json\",\n text: JSON.stringify({ theme: \"dark\", language: \"zh\" })\n }]\n };\n }\n);\n```\n\n### 注册资源模板\n\n```typescript\nserver.resourceTemplate(\n \"user-profile\",\n \"users://{userId}/profile\",\n ({ userId }: { userId: string }) => {\n return {\n contents: [{\n uri: `users://${userId}/profile`,\n mimeType: \"application/json\",\n text: fetchUserProfile(userId)\n }]\n };\n }\n);\n```\n\n### 资源生命周期管理\n\n| 方法 | 说明 |\n|------|------|\n| `disable()` | 禁用资源（仍保留但不可访问） |\n| `enable()` | 启用资源 |\n| `remove()` | 移除资源 |\n| `update(updates)` | 更新资源属性 |\n\n资源更新后自动发送 `resourceListChanged` 通知：\n\n```typescript\nupdate: updates => {\n if (updates.uri !== undefined && updates.uri !== uri) {\n delete this._registeredResources[uri];\n if (updates.uri) this._registeredResources[updates.uri] = registeredResource;\n }\n if (updates.name !== undefined) registeredResource.name = updates.name;\n if (updates.enabled !== undefined) registeredResource.enabled = updates.enabled;\n this.sendResourceListChanged();\n}\n```\n\n资料来源：[packages/server/src/server/mcp.ts:280-350]()\n\n## 提示注册\n\n### 提示注册 API\n\n```typescript\nserver.registerPrompt(\n \"code-review\",\n {\n title: \"代码审查\",\n description: \"生成代码审查请求\",\n argsSchema: z.object({\n code: z.string(),\n language: z.string().optional()\n })\n },\n async ({ code, language }) => ({\n messages: [{\n role: \"user\",\n content: {\n type: \"text\",\n text: `请审查以下${language || \"\"}代码：\\n\\n${code}`\n }\n }]\n })\n);\n```\n\n### 提示参数\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| name | string | 提示唯一标识 |\n| config.title | string | 显示标题 |\n| config.description | string | 功能描述 |\n| config.argsSchema | ZodSchema | 参数验证 Schema |\n| cb | PromptCallback | 返回消息数组的异步函数 |\n\n资料来源：[packages/server/src/server/mcp.ts:180-210]()\n\n## 服务器运行模式\n\n### Streamable HTTP 模式（有状态）\n\n适用于需要会话跟踪、任务管理的复杂服务器：\n\n```typescript\nimport { StreamableHTTPTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\n\nconst transport = new StreamableHTTPTransport({\n sessionIdGenerator: () => crypto.randomUUID(),\n});\n\nawait server.connect(transport);\n```\n\n### Streamable HTTP 模式（无状态）\n\n适用于简单的 API 风格服务器，无会话跟踪：\n\n```typescript\nimport { StreamableHTTPTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\n\nconst transport = new StreamableHTTPTransport();\nawait server.connect(transport);\n```\n\n### JSON 响应模式\n\n仅使用 JSON 响应，不支持 SSE：\n\n```typescript\nimport { JSONResponseStreamableHttpTransport } from \"@modelcontextprotocol/sdk/server/streamableHttp.js\";\n\nconst transport = new JSONResponseStreamableHttpTransport();\nawait server.connect(transport);\n```\n\n资料来源：[examples/server/README.md:25-45]()\n\n## 错误处理\n\n### SDK 错误码\n\n```typescript\nimport { SdkError, SdkErrorCode } from \"@modelcontextprotocol/sdk\";\n\ntry {\n await server.requestHandler.handleRequest(request);\n} catch (error) {\n if (error instanceof SdkError) {\n switch (error.code) {\n case SdkErrorCode.InvalidRequest:\n // 处理无效请求\n break;\n case SdkErrorCode.MethodNotFound:\n // 方法未找到\n break;\n case SdkErrorCode.CapabilityNotSupported:\n // 能力不支持\n break;\n }\n }\n}\n```\n\n资料来源：[packages/core/CHANGELOG.md:10-15]()\n\n## 示例服务器索引\n\n| 场景 | 描述 | 文件 |\n|------|------|------|\n| 有状态 Streamable HTTP | 功能丰富的服务器，支持工具/资源/提示、日志、任务、采样 | `src/simpleStreamableHttp.ts` |\n| 无状态 Streamable HTTP | 无会话跟踪，适合简单 API 服务器 | `src/simpleStatelessStreamableHttp.ts` |\n| 资源服务器 OAuth | 使用 `mcpAuthMetadataRouter` 的最小 OAuth RS | `src/resourceServerOnly.ts` |\n| JSON 响应模式 | 仅 JSON 响应的 Streamable HTTP | `src/jsonResponseStreamableHttp.ts` |\n\n资料来源：[examples/server/README.md:28-40]()\n\n## 下一步\n\n- 查看 [客户端开发指南](./client.md) 了解如何连接到此服务器\n- 阅读 [协议规范文档](./protocol.md) 深入理解底层协议\n- 参考 [示例代码库](../examples/server/) 获取完整实现\n\n---\n\n\n\n## 客户端开发指南\n\n### 相关页面\n\n相关主题：[服务器开发指南](#page-6), [Web 框架中间件集成](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/client/src/client/client.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/client.ts)\n- [examples/client/src/clientGuide.examples.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client/src/clientGuide.examples.ts)\n- [examples/client-quickstart/src/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/client-quickstart/src/index.ts)\n- [docs/client-quickstart.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/client-quickstart.md)\n- [docs/client.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/client.md)\n \n\n# 客户端开发指南\n\n## 概述\n\nMCP TypeScript SDK 的客户端开发模块位于 `packages/client` 包中，提供了与 MCP 服务器通信的完整能力。该模块基于核心协议层构建，封装了 JSON-RPC 消息处理、请求/响应关联、能力协商和传输层管理等功能。客户端支持 Streamable HTTP 传输协议，这是 MCP V2 规范定义的主要通信方式。\n\n## 核心架构\n\n### 客户端层次结构\n\nMCP SDK 采用三层架构设计，客户端位于最上层：\n\n| 层级 | 位置 | 职责 |\n|------|------|------|\n| 类型层 | `packages/core/src/types/types.ts` | 定义 MCP 协议的 TypeScript 类型和 Zod Schema |\n| 协议层 | `packages/core/src/shared/protocol.ts` | 处理 JSON-RPC 路由、能力协商和消息分发 |\n| 客户端层 | `packages/client/src/client/client.ts` | 提供面向用户的 MCP 操作接口 |\n\n### 客户端与协议层关系\n\n```mermaid\ngraph TD\n A[Client 实例] --> B[Protocol 基类]\n B --> C[Transport 传输层]\n C --> D[Streamable HTTP]\n \n A --> E[工具调用]\n A --> F[资源访问]\n A --> G[提示模板]\n A --> H[采样请求]\n A --> I[任务管理]\n \n E --> B\n F --> B\n G --> B\n H --> B\n I --> B\n```\n\n## 安装与配置\n\n### 依赖安装\n\n```bash\npnpm add @modelcontextprotocol/client\n```\n\n### 基本导入\n\n```typescript\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';\n```\n\n## 客户端初始化\n\n### 创建客户端实例\n\n客户端初始化需要提供服务器能力信息和连接配置：\n\n```typescript\nconst transport = new StreamableHTTPClientTransport({\n url: new URL('http://localhost:3000/mcp'),\n requestOptions: {\n headers: {\n Authorization: 'Bearer your-token-here'\n }\n }\n});\n\nconst client = new Client(\n {\n name: 'example-client',\n version: '1.0.0'\n },\n {\n capabilities: {\n resources: {},\n tools: {},\n prompts: {},\n sampling: {}\n }\n }\n);\n```\n\n### 连接到服务器\n\n```typescript\nawait client.connect(transport);\n```\n\n连接过程会触发服务器能力协商，确认双方支持的 MCP 功能范围。\n\n## 核心功能\n\n### 工具调用\n\n工具是 MCP 服务器暴露的可执行函数，客户端可以调用这些工具获取计算结果或执行特定操作。\n\n```mermaid\nsequenceDiagram\n 客户端->>服务器: 调用工具 (tools/call)\n 服务器->>服务器: 执行工具逻辑\n 服务器-->>客户端: 工具结果\n```\n\n#### 调用单个工具\n\n```typescript\nconst result = await client.callTool({\n name: 'calculate',\n arguments: { expression: '2 + 2' }\n});\n```\n\n#### 并行调用多个工具\n\n```typescript\nconst results = await Promise.all([\n client.callTool({ name: 'tool-a', arguments: { id: 1 } }),\n client.callTool({ name: 'tool-b', arguments: { id: 2 } }),\n client.callTool({ name: 'tool-c', arguments: { id: 3 } })\n]);\n```\n\n### 资源管理\n\n资源是服务器提供的只读数据源，客户端可以列出、读取和订阅资源变更通知。\n\n#### 列出可用资源\n\n```typescript\nconst resourceList = await client.listResources();\nfor (const resource of resourceList.resources) {\n console.log(`${resource.name}: ${resource.uri}`);\n}\n```\n\n#### 读取资源内容\n\n```typescript\nconst resourceContent = await client.readResource({\n uri: 'file:///config/app.json'\n});\n```\n\n#### 订阅资源变更\n\n```typescript\nawait client.subscribeResource({ uri: 'file:///config/app.json' });\n\n// 设置资源更新处理器\nclient.setRequestHandler(ResourceUpdatedNotificationSchema, (notification) => {\n console.log('资源已更新:', notification.params.uri);\n return Promise.resolve();\n});\n```\n\n### 提示模板\n\n提示模板允许服务器定义可参数化的消息模板，客户端可以获取并使用这些模板。\n\n#### 列出可用提示\n\n```typescript\nconst promptList = await client.listPrompts();\n```\n\n#### 获取提示内容\n\n```typescript\nconst prompt = await client.getPrompt({\n name: 'code-review',\n arguments: { code: 'const x = 1;' }\n});\n\n// prompt.messages 包含渲染后的消息数组\nfor (const message of prompt.messages) {\n console.log(`${message.role}: ${message.content}`);\n}\n```\n\n### 采样请求\n\n采样功能允许服务器向客户端请求采样数据，通常用于 AI 模型的调用。\n\n```typescript\nconst sample = await client.createMessage({\n messages: [{ role: 'user', content: { type: 'text', text: 'Hello' } }],\n systemPrompt: 'You are a helpful assistant.',\n maxTokens: 100\n});\n```\n\n## 认证机制\n\n### AuthProvider 接口\n\nSDK 提供了灵活的认证机制，通过 `AuthProvider` 接口实现可组合的认证功能：\n\n```typescript\ninterface AuthProvider {\n token(): Promise;\n onUnauthorized?(ctx: AuthorizationCtx): Promise;\n}\n```\n\n### 简单Bearer Token认证\n\n对于简单的 API 密钥或网关管理的令牌，可以使用对象字面量：\n\n```typescript\nconst client = new Client({ name: 'my-app', version: '1.0.0' }, { capabilities: {} });\n\nawait client.connect(transport, {\n authProvider: {\n token: async () => 'my-api-key'\n }\n});\n```\n\n### OAuth 认证\n\nOAuth 认证由 `OAuthClientProvider` 提供，传输层会自动适配：\n\n```typescript\nimport { adaptOAuthProvider } from '@modelcontextprotocol/sdk/client/auth.js';\n\nconst oauthProvider = new MyOAuthProvider(config);\nawait client.connect(transport, {\n authProvider: adaptOAuthProvider(oauthProvider)\n});\n```\n\n认证流程如下：\n\n```mermaid\ngraph LR\n A[发起请求] --> B{获取Token}\n B --> C[发送带Token的请求]\n C --> D{响应状态}\n D -->|200| E[成功]\n D -->|401| F[onUnauthorized]\n F --> G[重试请求]\n G --> E\n```\n\n## 传输层配置\n\n### Streamable HTTP 传输\n\nStreamable HTTP 是 V2 版本的主要传输协议，支持服务端推送和流式响应：\n\n```typescript\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';\n\nconst transport = new StreamableHTTPClientTransport({\n url: new URL('http://localhost:3000/mcp'),\n requestOptions: {\n headers: {\n 'Content-Type': 'application/json'\n }\n },\n // 启用SSE回落机制\n sseFallbackEnabled: true\n});\n```\n\n### SSE 回落机制\n\n客户端支持自动回落机制，当 Streamable HTTP 返回 4xx 错误时，自动切换到传统 SSE 轮询模式：\n\n```typescript\nconst client = new Client({ name: 'fallback-client', version: '1.0.0' }, { capabilities: {} });\nconst transport = new StreamableHTTPClientTransport({\n url: new URL('http://localhost:3000/mcp'),\n sseFallbackEnabled: true\n});\nawait client.connect(transport);\n```\n\n## 错误处理\n\n### 连接错误\n\n```typescript\ntry {\n await client.connect(transport);\n} catch (error) {\n if (error instanceof ConnectionError) {\n console.error('连接失败:', error.message);\n }\n}\n```\n\n### 请求错误\n\n```typescript\ntry {\n const result = await client.callTool({\n name: 'risky-operation',\n arguments: {}\n });\n} catch (error) {\n if (error instanceof ToolExecutionError) {\n console.error('工具执行错误:', error.message);\n }\n}\n```\n\n## 完整示例\n\n### 交互式客户端\n\n以下示例展示了完整的客户端使用流程：\n\n```typescript\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';\n\nasync function main() {\n // 初始化传输层\n const transport = new StreamableHTTPClientTransport({\n url: new URL('http://localhost:3000/mcp')\n });\n\n // 创建客户端\n const client = new Client(\n { name: 'interactive-client', version: '1.0.0' },\n { capabilities: { resources: {}, tools: {}, prompts: {} } }\n );\n\n // 连接服务器\n await client.connect(transport);\n console.log('已连接到 MCP 服务器');\n\n // 列出资源\n const { resources } = await client.listResources();\n console.log(`发现 ${resources.length} 个资源`);\n\n // 调用工具\n const toolResult = await client.callTool({\n name: 'greeting',\n arguments: { name: 'World' }\n });\n console.log('工具响应:', toolResult);\n\n // 获取提示\n const prompt = await client.getPrompt({\n name: 'welcome',\n arguments: { user: 'Developer' }\n });\n console.log('提示内容:', prompt.messages);\n\n // 断开连接\n await client.close();\n}\n\nmain().catch(console.error);\n```\n\n### 带认证的客户端\n\n```typescript\nimport { Client } from '@modelcontextprotocol/sdk/client/index.js';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/transport.js';\n\nasync function authenticatedClient() {\n const transport = new StreamableHTTPClientTransport({\n url: new URL('https://api.example.com/mcp'),\n requestOptions: {\n headers: {\n 'X-API-Key': process.env.API_KEY\n }\n }\n });\n\n const client = new Client(\n { name: 'secure-client', version: '1.0.0' },\n { capabilities: { tools: {}, resources: {} } }\n );\n\n await client.connect(transport, {\n authProvider: {\n token: async () => process.env.AUTH_TOKEN,\n onUnauthorized: async (ctx) => {\n // 刷新令牌逻辑\n const newToken = await refreshToken();\n ctx.retried = true;\n }\n }\n });\n\n return client;\n}\n```\n\n## 实验性功能\n\n实验性功能通过 `@modelcontextprotocol/sdk/client/experimental` 模块导出：\n\n```typescript\nimport { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/client/experimental';\n\n// 任务存储配置\nconst taskStore = new InMemoryTaskStore();\n```\n\n## 最佳实践\n\n| 实践 | 说明 |\n|------|------|\n| 单一职责 | 每个客户端实例专注于一个服务器连接 |\n| 错误处理 | 始终使用 try-catch 包装异步操作 |\n| 资源清理 | 使用完毕后调用 `client.close()` |\n| 认证管理 | 将令牌刷新逻辑放在 `onUnauthorized` 回调中 |\n| 类型安全 | 使用 Zod Schema 验证工具参数 |\n\n## 相关资源\n\n- [MCP 规范文档](https://modelcontextprotocol.io/specification/latest)\n- [服务器开发指南](./server.md)\n- [客户端快速开始](./client-quickstart.md)\n- [examples/client](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/client)\n\n---\n\n\n\n## 认证与授权机制\n\n### 相关页面\n\n相关主题：[Web 框架中间件集成](#page-9), [实验性功能与任务系统](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/shared/auth.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/shared/auth.ts)\n- [packages/core/src/shared/authUtils.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/shared/authUtils.ts)\n- [packages/client/src/client/auth.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/auth.ts)\n- [packages/client/src/client/authExtensions.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/authExtensions.ts)\n- [packages/client/src/client/crossAppAccess.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/client/crossAppAccess.ts)\n- [packages/middleware/express/src/auth/bearerAuth.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/src/auth/bearerAuth.ts)\n \n\n# 认证与授权机制\n\n## 概述\n\nMCP TypeScript SDK 提供了一套完整的认证与授权机制，支持多种认证方式，包括 Bearer Token 认证、OAuth 2.0 认证以及可组合的自定义认证提供者。该机制设计为传输层无关，可与 Streamable HTTP、SSE 等传输协议配合使用，为 MCP 客户端和服务器之间的安全通信提供保障。\n\n认证系统的核心设计理念是通过统一的 `AuthProvider` 接口抽象不同的认证方式，使得开发者可以根据实际需求选择或组合使用 Bearer Token、OAuth 等认证策略。资料来源：[packages/client/CHANGELOG.md]()\n\n## 核心架构\n\n### 认证提供者体系\n\nMCP SDK 的认证体系采用分层架构设计，核心包含以下组件：\n\n| 组件 | 文件位置 | 职责 |\n|------|----------|------|\n| AuthProvider | packages/core/src/shared/auth.ts | 认证提供者核心接口 |\n| OAuthClientProvider | packages/client/src/client/auth.ts | OAuth 客户端实现 |\n| BearerAuthMiddleware | packages/middleware/express/src/auth/bearerAuth.ts | Bearer Token 中间件 |\n| adaptOAuthProvider | packages/client/src/client/auth.ts | OAuth 适配器 |\n\n资料来源：[packages/client/CHANGELOG.md](), [packages/core/src/shared/auth.ts]()\n\n### 认证流程架构图\n\n```mermaid\ngraph TD\n A[Client Request] --> B{AuthProvider}\n B -->|Bearer Token| C[Token 获取]\n B -->|OAuth| D[OAuth Flow]\n C --> E[Authorization Header]\n D --> F[Token Exchange]\n F --> G[Access Token]\n G --> E\n E --> H[Server Validation]\n H -->|401| I[onUnauthorized]\n I -->|Retry| B\n H -->|200| J[Request Success]\n```\n\n## AuthProvider 接口\n\n`AuthProvider` 是认证系统的核心接口，定义了两个关键方法：\n\n```typescript\nexport interface AuthProvider {\n token(): Promise;\n onUnauthorized?(ctx): Promise;\n}\n```\n\n| 方法 | 返回类型 | 说明 |\n|------|----------|------|\n| token | Promise | 返回认证令牌，若返回 undefined 则跳过认证 |\n| onUnauthorized | Promise (可选) | 收到 401 响应时的回调，可用于重新认证 |\n\n资料来源：[packages/client/CHANGELOG.md]()\n\n### Bearer Token 认证方式\n\n对于简单的场景，可以使用对象字面量形式快速配置 Bearer Token：\n\n```typescript\nconst client = createClient({\n authProvider: {\n token: async () => myApiKey\n }\n});\n```\n\n这种方式的优点是配置简洁，无需创建类实例，适合 API Key、网关托管令牌等场景。资料来源：[packages/client/CHANGELOG.md]()\n\n## OAuth 认证\n\n### OAuthClientProvider\n\nSDK 提供了完整的 OAuth 客户端认证支持：\n\n```typescript\nexport interface OAuthClientProvider {\n // OAuth 认证核心方法\n auth(provider: {\n serverUrl: string;\n resourceMetadataUrl?: string;\n scope?: string;\n fetchFn: typeof fetch;\n }): Promise<'REDIRECT' | 'AUTHORIZED' | 'UNAUTHORIZED'>;\n}\n```\n\n资料来源：[packages/client/CHANGELOG.md]()\n\n### OAuth 认证流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant MCP_Server as MCP Server\n participant OAuth_Provider as OAuth Provider\n \n Client->>MCP_Server: Request with token()\n MCP_Server->>MCP_Server: Validate Token\n alt Token Invalid (401)\n MCP_Server->>Client: 401 Unauthorized\n Client->>OAuth_Provider: auth() with REDIRECT\n OAuth_Provider->>Client: Authorization URL\n Client->>OAuth_Provider: User Login\n OAuth_Provider->>Client: Authorization Code\n Client->>OAuth_Provider: Token Exchange\n OAuth_Provider->>Client: Access Token\n Client->>MCP_Server: Retry with new token\n end\n```\n\n### adaptOAuthProvider 适配器\n\n对于已有的 `OAuthClientProvider` 实现，SDK 提供 `adaptOAuthProvider()` 函数进行适配，无需修改现有代码：\n\n```typescript\nimport { adaptOAuthProvider } from '@modelcontextprotocol/client';\n\n// 适配已有的 OAuth 提供者\nconst adaptedProvider = adaptOAuthProvider(existingOAuthProvider);\n```\n\n资料来源：[packages/client/CHANGELOG.md]()\n\n## Bearer 认证中间件\n\n### bearerAuthMiddleware\n\nExpress 中间件实现了 Bearer Token 认证验证逻辑：\n\n```typescript\nexport function bearerAuthMiddleware(\n options: BearerAuthOptions\n): RequestHandler {\n // 实现 Bearer Token 验证逻辑\n}\n```\n\n| 配置项 | 类型 | 必填 | 说明 |\n|--------|------|------|------|\n| token | string \\| () => string \\| Promise | 是 | Bearer Token 或返回 Token 的函数 |\n| realm | string | 否 | 认证域，用于 WWW-Authenticate 头 |\n| prefix | string | 否 | Token 前缀，默认为 'Bearer ' |\n| skip | (req: Request) => boolean | 否 | 跳过认证的条件函数 |\n\n资料来源：[packages/middleware/express/src/auth/bearerAuth.ts]()\n\n### requireBearerAuth 工具函数\n\n中间件导出 `requireBearerAuth` 函数用于简化认证配置：\n\n```typescript\nconst { bearerAuthMiddleware, requireBearerAuth } = createBearerAuth({\n token: () => process.env.BEARER_TOKEN\n});\n```\n\n资料来源：[packages/middleware/express/src/auth/bearerAuth.ts]()\n\n## 资源访问控制\n\n### URL 路径匹配\n\n`authUtils.ts` 提供了资源访问控制的核心工具函数 `matchesResource`：\n\n```typescript\nexport function matchesResource(requestedResource: URL | string, configuredResource: URL | string): boolean\n```\n\n该函数通过以下规则判断请求的资源是否在允许范围内：\n\n| 匹配条件 | 说明 |\n|----------|------|\n| Origin 匹配 | 协议、域名和端口必须一致 |\n| 路径前缀匹配 | 请求路径必须以配置的路径开头 |\n| 尾部斜杠处理 | 智能处理带斜杠和不带斜杠的路径 |\n\n```typescript\n// 路径匹配示例\nmatchesResource('https://example.com/api/users', 'https://example.com/api'); // true\nmatchesResource('https://example.com/api123', 'https://example.com/api'); // false\n```\n\n资料来源：[packages/core/src/shared/authUtils.ts]()\n\n### 资源匹配逻辑详解\n\n```mermaid\ngraph TD\n A[解析 requestedResource] --> B[解析 configuredResource]\n B --> C{Origin 相同?}\n C -->|否| D[返回 false]\n C -->|是| E{路径长度足够?}\n E -->|否| D\n E -->|是| F[添加尾部斜杠]\n F --> G[比较路径前缀]\n G --> H{匹配成功?}\n H -->|是| I[返回 true]\n H -->|否| D\n```\n\n## 认证中间件\n\n### createMiddleware\n\nSDK 提供了 `createMiddleware` 工厂函数用于创建自定义认证中间件：\n\n```typescript\nexport function createMiddleware(\n handler: (next: typeof fetch, input: RequestInfo, init?: RequestInit) => Promise\n): MiddlewareFunction\n```\n\n资料来源：[packages/client/src/client/middleware.ts]()\n\n### 认证中间件工作流程\n\n```mermaid\ngraph TD\n A[Request Incoming] --> B{AuthProvider.token()}\n B -->|返回 token| C[添加 Authorization 头]\n B -->|返回 undefined| D[跳过认证]\n C --> E[发送请求到 next]\n D --> E\n E --> F{Response 401?}\n F -->|是| G{cb.onUnauthorized?}\n F -->|否| H[返回 Response]\n G -->|存在| I[调用 onUnauthorized]\n G -->|不存在| J[抛出 UnauthorizedError]\n I --> K[重试请求]\n K --> H\n J --> L[终止流程]\n```\n\n### 中间件示例\n\n**自定义认证中间件：**\n\n```typescript\nconst customAuthMiddleware = createMiddleware(async (next, input, init) => {\n const headers = new Headers(init?.headers);\n headers.set('X-Custom-Auth', 'my-token');\n \n const response = await next(input, { ...init, headers });\n \n if (response.status === 401) {\n console.log('Authentication failed');\n }\n \n return response;\n});\n```\n\n**条件认证中间件：**\n\n```typescript\nconst conditionalMiddleware = createMiddleware(async (next, input, init) => {\n const url = typeof input === 'string' ? input : input.toString();\n \n if (url.includes('/api/')) {\n const headers = new Headers(init?.headers);\n headers.set('X-API-Version', 'v2');\n return next(input, { ...init, headers });\n }\n \n return next(input, init);\n});\n```\n\n资料来源：[packages/client/src/client/middleware.ts]()\n\n## 跨应用访问控制\n\n### CrossAppAccess 认证\n\n`crossAppAccess.ts` 实现了跨应用程序访问的认证机制，支持对特定资源路径的细粒度访问控制：\n\n```typescript\nexport interface CrossAppAccessAuth {\n validateCrossAppRequest(requestedResource: string): Promise;\n}\n```\n\n| 功能 | 说明 |\n|------|------|\n| 路径验证 | 验证请求的资源路径是否符合配置 |\n| 跨域控制 | 防止跨应用的未授权访问 |\n| 前缀匹配 | 支持目录级别的访问控制 |\n\n资料来源：[packages/client/src/client/crossAppAccess.ts]()\n\n## 日志记录\n\n### RequestLogger\n\n认证系统支持详细的日志记录，便于调试和审计：\n\n```typescript\nexport type RequestLogger = (input: {\n method: string;\n url: string | URL;\n status: number;\n statusText: string;\n duration: number;\n requestHeaders?: Headers;\n responseHeaders?: Headers;\n error?: Error;\n}) => void;\n```\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| method | string | HTTP 方法 |\n| url | string \\| URL | 请求 URL |\n| status | number | 响应状态码 |\n| statusText | string | 响应状态文本 |\n| duration | number | 请求耗时（毫秒） |\n| requestHeaders | Headers | 请求头 |\n| responseHeaders | Headers | 响应头 |\n| error | Error | 错误对象（若有） |\n\n资料来源：[packages/client/src/client/middleware.ts]()\n\n## Session 管理\n\n### Session Cookie 处理\n\n认证服务器使用 Cookie 机制管理用户会话：\n\n```typescript\nfunction getUserSessionCookie(cookieHeader?: string): { \n userId: string; \n name: string; \n timestamp: number \n} | null\n```\n\n该函数解析 `demo_session` Cookie 并返回用户会话信息。Cookie 存储的用户信息包括：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| userId | string | 用户唯一标识 |\n| name | string | 用户名称 |\n| timestamp | number | 会话创建时间戳 |\n\n资料来源：[examples/shared/src/authServer.ts]()\n\n### 认证流程中的 Session 处理\n\n```mermaid\ngraph LR\n A[用户登录] --> B[创建 Session]\n B --> C[设置 Set-Cookie]\n C --> D[浏览器存储 Cookie]\n D --> E[后续请求自动携带 Cookie]\n E --> F[服务端验证 Session]\n```\n\n## 最佳实践\n\n### 认证配置建议\n\n| 场景 | 推荐方案 |\n|------|----------|\n| 简单 API Key | 使用对象字面量 `authProvider: { token: async () => key }` |\n| OAuth 认证 | 实现 `OAuthClientProvider` 并使用 `adaptOAuthProvider` |\n| 多认证方式 | 实现自定义 `AuthProvider`，组合多种认证策略 |\n| 资源访问控制 | 使用 `matchesResource` 进行路径验证 |\n\n### 安全注意事项\n\n1. **Token 存储**：避免在前端代码中硬编码敏感 Token\n2. **HTTPS 传输**：确保所有认证请求通过 HTTPS 进行\n3. **Token 刷新**：实现 `onUnauthorized` 回调处理 Token 过期\n4. **错误处理**：妥善处理认证失败情况，避免信息泄露\n\n资料来源：[packages/client/CHANGELOG.md](), [packages/middleware/express/src/auth/bearerAuth.ts]()\n\n## 相关资源\n\n- [认证与授权官方文档](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/docs/auth.md)\n- [Express 中间件示例](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/middleware/express)\n- [OAuth 示例服务器](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/examples/shared/src/authServer.ts)\n\n---\n\n\n\n## Web 框架中间件集成\n\n### 相关页面\n\n相关主题：[传输层实现](#page-5), [实验性功能与任务系统](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/middleware/express/src/express.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/src/express.ts)\n- [packages/middleware/hono/src/hono.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/src/hono.ts)\n- [packages/middleware/fastify/src/fastify.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/fastify/src/fastify.ts)\n- [packages/middleware/express/src/middleware/hostHeaderValidation.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/express/src/middleware/hostHeaderValidation.ts)\n- [packages/middleware/hono/src/middleware/hostHeaderValidation.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/hono/src/middleware/hostHeaderValidation.ts)\n- [packages/middleware/README.md](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/middleware/README.md)\n \n\n# Web 框架中间件集成\n\n## 概述\n\nModel Context Protocol (MCP) TypeScript SDK 提供了与主流 Web 框架的中间件集成支持，使开发者能够将 MCP 服务器无缝嵌入到现有的 Express、Hono 和 Fastify 应用中。这些中间件适配器充当 MCP 传输层与 Web 框架之间的桥梁，实现了标准化的请求处理和响应流式传输机制。\n\n中间件集成的核心价值在于：开发者无需构建独立的 MCP 服务器进程，而是可以直接在现有的 Web 应用中暴露 MCP 工具、资源和提示词功能。这种架构模式特别适合需要将 MCP 功能与现有 API 服务、认证中间件、日志系统等组件整合的场景。\n\n## 架构设计\n\n### 整体架构\n\nMCP Web 框架中间件采用了适配器模式设计，每种框架都有对应的传输层实现。中间件负责接收框架的 HTTP 请求，将其转换为 MCP 协议消息，然后调用底层 MCP 服务器处理逻辑，最终将处理结果以框架兼容的方式返回给客户端。\n\n```mermaid\ngraph TD\n A[HTTP 客户端] --> B[Web 框架路由]\n B --> C[MCP 中间件适配器]\n C --> D[MCP 协议消息解析]\n D --> E[MCP 服务器核心]\n E --> F[工具/资源/提示词处理器]\n F --> G[响应序列化]\n G --> C\n C --> H[HTTP 响应]\n H --> A\n```\n\n### 核心组件关系\n\n中间件层由三个主要包组成，分别对应三种 Web 框架：\n\n| 包名 | 功能 | 传输类型 |\n|------|------|----------|\n| `@modelcontextprotocol/express` | Express.js 框架集成 | Streamable HTTP |\n| `@modelcontextprotocol/hono` | Hono 框架集成 | Streamable HTTP |\n| `@modelcontextprotocol/fastify` | Fastify 框架集成 | Streamable HTTP |\n\n每个中间件包都包含核心适配器模块和安全验证中间件两个部分。核心适配器负责处理 MCP 协议通信，而安全中间件则提供主机头验证等防护功能。\n\n## Express 中间件集成\n\n### 核心功能\n\nExpress 中间件 (`packages/middleware/express/src/express.ts`) 提供了与 Express 框架的完整集成能力。它基于 MCP Streamable HTTP 传输协议实现，支持状态ful 和无状态两种运行模式。\n\nExpress 中间件的主要职责包括：\n\n- 将 Express 请求转换为 MCP JSON-RPC 消息\n- 管理会话状态（状态ful 模式）\n- 处理流式响应和 Server-Sent Events (SSE)\n- 与 Express 路由系统和中间件链集成\n\n### 使用方式\n\n开发者可以通过标准的 Express `use()` 方法将 MCP 中间件添加到应用中：\n\n```typescript\nimport express from 'express';\nimport { useMcpExpress } from '@modelcontextprotocol/express';\n\nconst app = express();\n\napp.use(express.json());\n\napp.use('/mcp', useMcpExpress(server, {\n transport: 'streamable-http',\n mode: 'stateful' // 或 'stateless'\n}));\n```\n\n中间件配置选项允许指定传输类型、运行模式和回调处理函数。状态ful 模式会维护会话信息，适合需要跨请求保持状态的复杂应用场景；无状态模式则每次请求独立处理，更适合简单的 API 式服务器。\n\n### 安全中间件\n\nExpress 包还包含了主机头验证中间件 (`packages/middleware/express/src/middleware/hostHeaderValidation.ts`)，用于防止主机头欺骗攻击。该中间件会验证请求中的 Host 和 X-Forwarded-Host 头，确保请求确实发往预期的目标地址。\n\n## Hono 中间件集成\n\n### 核心功能\n\nHono 中间件 (`packages/middleware/hono/src/hono.ts`) 提供了轻量级、高性能的 Hono 框架集成。Hono 本身是一个支持多个运行时的 Web 框架，因此 MCP Hono 中间件可以同时在 Node.js、Cloudflare Workers、Deno Deploy 等环境中运行。\n\nHono 中间件利用了 Hono 的流式响应处理能力，可以高效地处理 MCP 的流式消息传输。\n\n### 使用方式\n\nHono 中间件通过 Hono 的标准中间件机制注册：\n\n```typescript\nimport { Hono } from 'hono';\nimport { mcpHono } from '@modelcontextprotocol/hono';\n\nconst app = new Hono();\nconst mcp = new McpServer({ /* 配置 */ });\n\napp.use('/mcp', mcpHono(mcp, {\n transport: 'streamable-http',\n binder: someBinder\n}));\n```\n\n### 安全中间件\n\nHono 包同样包含了主机头验证中间件 (`packages/middleware/hono/src/middleware/hostHeaderValidation.ts`)，实现方式与 Express 版本类似，但针对 Hono 的上下文 API 进行了适配。\n\n## Fastify 中间件集成\n\n### 核心功能\n\nFastify 中间件 (`packages/middleware/fastify/src/fastify.ts`) 提供了与高性能 Node.js 框架 Fastify 的集成。Fastify 以其卓越的性能著称，MCP 中间件充分利用了 Fastify 的插件系统和流式处理能力。\n\nFastify 集成支持：\n\n- Fastify 插件式架构\n- 高性能请求路由\n- JSON Schema 验证集成\n- 流式响应处理\n\n### 使用方式\n\n```typescript\nimport Fastify from 'fastify';\nimport { mcpFastify } from '@modelcontextprotocol/fastify';\n\nconst fastify = Fastify();\nconst server = new McpServer({ /* 配置 */ });\n\nfastify.register(mcpFastify, {\n server,\n prefix: '/mcp'\n});\n```\n\n## 传输协议\n\n### Streamable HTTP 传输\n\n所有 Web 框架中间件都使用 Streamable HTTP 作为传输协议。这是 MCP 规范中定义的标准传输方式，支持：\n\n| 特性 | 说明 |\n|------|------|\n| 请求-响应模式 | 标准 HTTP POST 请求，JSON-RPC 响应 |\n| 流式响应 | 支持 Server-Sent Events 格式的流式消息 |\n| 会话管理 | 通过会话标识符维护状态 |\n| 心跳机制 | 保持连接活跃 |\n\n### 请求处理流程\n\n```mermaid\nsequenceDiagram\n participant C as 客户端\n participant M as 中间件\n participant S as MCP服务器\n participant H as 处理器\n\n C->>M: POST /mcp (JSON-RPC Request)\n M->>S: 路由请求\n S->>H: 调用处理器\n H->>S: 返回结果\n S->>M: 流式响应\n M->>C: SSE 流\n C->>M: GET /mcp (SSE 连接)\n M->>S: 建立会话\n S->>M: 会话通道\n M->>C: 事件流\n```\n\n## 安全特性\n\n### 主机头验证\n\n主机头验证中间件是所有 Web 框架集成的标准安全组件。其工作原理包括：\n\n1. **白名单检查**：验证请求的 Host 头是否在允许的域名列表中\n2. **代理头处理**：正确处理 X-Forwarded-Host 等代理头\n3. **协议验证**：确保请求协议与预期匹配\n\n该中间件能够有效防御以下攻击：\n\n- DNS 重绑定攻击\n- 主机头欺骗\n- 代理层配置错误导致的安全问题\n\n### 认证集成\n\nWeb 框架中间件可以与各框架的认证系统无缝集成。开发者可以在 MCP 中间件之前注册任何 Express/Hono/Fastify 认证中间件，例如 JWT 验证、OAuth 验证或自定义会话验证。\n\n## 配置选项\n\n### 通用配置\n\n| 选项 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `transport` | `string` | `'streamable-http'` | 传输协议类型 |\n| `mode` | `'stateful' \\| 'stateless'` | `'stateful'` | 会话管理模式 |\n| `maxSessions` | `number` | 1000 | 最大并发会话数（状态ful模式） |\n| `sessionTimeout` | `number` | 300000 | 会话超时时间（毫秒） |\n\n### 状态ful 与无状态模式\n\n**状态ful 模式**维护会话状态，允许跨请求保持上下文：\n\n- 适合需要维护状态的复杂交互\n- 支持长连接和持久化上下文\n- 需要配置会话存储\n\n**无状态模式**每次请求独立处理：\n\n- 适合简单的工具调用场景\n- 更易于水平扩展\n- 无需会话管理开销\n\n## 与示例代码的对应关系\n\n`examples/server/README.md` 中列出的示例演示了这些中间件的实际应用：\n\n| 场景 | 描述 | 框架 |\n|------|------|------|\n| 状态ful Streamable HTTP 服务器 | 完整的工具/资源/提示词功能 | Express |\n| 无状态 Streamable HTTP 服务器 | 简化 API 式服务 | Express |\n| 资源服务器认证 | OAuth RS + Bearer 认证 | Express |\n\n这些示例位于 `examples/server/src/` 目录，展示了从简单的服务器配置到复杂的认证集成的完整使用方式。\n\n## 最佳实践\n\n### 生产环境部署\n\n1. **安全配置**：始终在 MCP 中间件之前配置认证和主机头验证中间件\n2. **会话管理**：根据应用场景选择合适的状态管理模式\n3. **超时设置**：合理配置请求超时和会话超时\n4. **错误处理**：实现统一的错误处理中间件，确保错误信息正确返回\n\n### 性能优化\n\n1. **路由前缀**：使用明确的路由前缀避免与其他 API 冲突\n2. **中间件顺序**：将 MCP 中间件放在合适的路由层级\n3. **会话限制**：在状态ful 模式下设置合理的最大会话数\n\n## 总结\n\nMCP TypeScript SDK 的 Web 框架中间件集成提供了强大而灵活的解决方案，使开发者能够将 Model Context Protocol 无缝嵌入到任何基于 Express、Hono 或 Fastify 的应用中。通过统一的适配器接口和安全组件，中间件系统确保了跨框架的一致性体验，同时充分发挥了各框架的独特优势。\n\n---\n\n\n\n## 实验性功能与任务系统\n\n### 相关页面\n\n相关主题：[服务器开发指南](#page-6), [客户端开发指南](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [packages/core/src/experimental/tasks/interfaces.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/interfaces.ts)\n- [packages/core/src/experimental/tasks/helpers.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/helpers.ts)\n- [packages/core/src/experimental/tasks/stores/inMemory.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/stores/inMemory.ts)\n- [packages/server/src/experimental/tasks/server.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/tasks/server.ts)\n- [packages/client/src/experimental/tasks/client.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/experimental/tasks/client.ts)\n- [packages/client/src/shimsBrowser.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/shimsBrowser.ts)\n- [packages/client/src/shimsWorkerd.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/shimsWorkerd.ts)\n \n\n# 实验性功能与任务系统\n\n## 概述\n\nMCP TypeScript SDK 提供了一套实验性的任务系统（Task System），允许服务器和客户端管理异步长时运行任务。这些任务可以通过唯一标识符进行追踪、查询和取消操作。\n\n实验性功能通过 `@modelcontextprotocol/sdk/experimental` 模块导出，使用前需注意：\n\n> ⚠️ **警告**：这些 API 是实验性的，可能会在没有任何通知的情况下发生变化。\n\n```typescript\nimport { TaskStore, InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';\n```\n\n资料来源：[packages/server/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/index.ts)\n\n---\n\n## 架构设计\n\n### 组件关系图\n\n```mermaid\ngraph TD\n subgraph 客户端层\n ClientTaskAPI[\"ClientTaskApi\"]\n TaskStore[\"TaskStore\"]\n end\n \n subgraph 服务端层\n ServerTaskAPI[\"ServerTaskApi\"]\n TaskModule[\"TaskModule\"]\n end\n \n subgraph 传输层\n Transport[\"Transport Layer\"]\n end\n \n ClientTaskAPI -->|JSON-RPC| Transport\n Transport -->|JSON-RPC| ServerTaskAPI\n ServerTaskAPI --> TaskModule\n ClientTaskAPI --> TaskStore\n \n TaskModule -.->|状态存储| TaskStore\n```\n\n### 核心模块结构\n\n| 模块 | 位置 | 职责 |\n|------|------|------|\n| `interfaces.ts` | `packages/core/src/experimental/tasks/` | 定义任务接口和数据模型 |\n| `helpers.ts` | `packages/core/src/experimental/tasks/` | 提供任务相关辅助函数 |\n| `inMemory.ts` | `packages/core/src/experimental/tasks/stores/` | 实现内存任务存储 |\n| `client.ts` | `packages/client/src/experimental/tasks/` | 客户端任务 API |\n| `server.ts` | `packages/server/src/experimental/tasks/` | 服务端任务 API |\n\n---\n\n## 服务端任务 API\n\n### ServerTaskApi 类\n\n`ServerTaskApi` 封装了服务端处理任务的核心方法。\n\n资料来源：[packages/server/src/experimental/tasks/server.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/server/src/experimental/tasks/server.ts)\n\n### 核心方法\n\n#### getTaskResult\n\n获取指定任务的执行结果。\n\n```typescript\nasync getTaskResult(\n taskId: string, \n options?: RequestOptions\n): Promise\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `taskId` | `string` | 任务唯一标识符 |\n| `options` | `RequestOptions` | 可选的请求配置 |\n\n**返回值**：`GetTaskPayloadResult` 类型的 Promise，封装了任务的执行结果（如工具调用返回的 `CallToolResult`）。\n\n资料来源：[packages/server/src/experimental/tasks/server.ts:20-26]()\n\n#### listTasks\n\n列出所有任务，支持分页查询。\n\n```typescript\nasync listTasks(\n cursor?: string, \n options?: RequestOptions\n): Promise\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `cursor` | `string` | 可选的分页游标 |\n| `options` | `RequestOptions` | 可选的请求配置 |\n\n**返回值**：`ListTasksResult` 包含任务列表和可选的下一页游标。\n\n资料来源：[packages/server/src/experimental/tasks/server.ts:34-43]()\n\n#### cancelTask\n\n取消一个正在运行的任务。\n\n```typescript\nasync cancelTask(\n taskId: string, \n options?: RequestOptions\n): Promise\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `taskId` | `string` | 要取消的任务标识符 |\n| `options` | `RequestOptions` | 可选的请求配置 |\n\n**返回值**：`CancelTaskResult` 表示取消操作的结果。\n\n资料来源：[packages/server/src/experimental/tasks/server.ts:52-60]()\n\n---\n\n## 客户端任务 API\n\n### ClientTaskApi 类\n\n客户端通过 `ClientTaskApi` 与服务端的任务系统进行交互。\n\n资料来源：[packages/client/src/experimental/tasks/client.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/experimental/tasks/client.ts)\n\n### 浏览器与 Workerd 适配\n\n客户端支持多种运行环境，通过不同的 shim 文件提供适配：\n\n| 环境 | Shim 文件 | 用途 |\n|------|----------|------|\n| 浏览器 | `packages/client/src/shimsBrowser.ts` | 浏览器环境适配 |\n| Workerd | `packages/client/src/shimsWorkerd.ts` | Cloudflare Workerd 环境适配 |\n\n资料来源：[packages/client/src/experimental/index.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/client/src/experimental/index.ts)\n\n---\n\n## 任务存储\n\n### TaskStore 接口\n\n任务存储定义了任务状态管理的基本接口。\n\n资料来源：[packages/core/src/experimental/tasks/interfaces.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/interfaces.ts)\n\n### InMemoryTaskStore\n\n默认提供的内存实现，适用于单进程场景。\n\n```typescript\nimport { InMemoryTaskStore } from '@modelcontextprotocol/sdk/experimental';\n\nconst taskStore = new InMemoryTaskStore();\n```\n\n特点：\n\n- 数据存储在内存中，进程重启后会丢失\n- 适合开发、测试或单实例部署\n- 性能最优，无需序列化/反序列化开销\n\n资料来源：[packages/core/src/experimental/tasks/stores/inMemory.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/stores/inMemory.ts)\n\n### 自定义存储实现\n\n可通过实现 `TaskStore` 接口创建自定义存储：\n\n```typescript\ninterface TaskStore {\n get(taskId: string): Promise;\n set(taskId: string, task: Task): Promise;\n delete(taskId: string): Promise;\n list(cursor?: string): Promise;\n}\n```\n\n资料来源：[packages/core/src/experimental/tasks/interfaces.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/interfaces.ts)\n\n---\n\n## 辅助函数\n\n### helpers.ts\n\n提供任务创建、验证、序列化等辅助功能。\n\n资料来源：[packages/core/src/experimental/tasks/helpers.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/experimental/tasks/helpers.ts)\n\n### 常用辅助函数\n\n| 函数 | 功能 |\n|------|------|\n| `createTask()` | 创建新任务实例 |\n| `validateTaskId()` | 验证任务标识符格式 |\n| `serializeTask()` | 序列化任务数据 |\n| `deserializeTask()` | 反序列化任务数据 |\n\n---\n\n## 使用工作流\n\n### 创建并追踪任务\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Server as 服务端\n participant Store as 任务存储\n \n Client->>Server: 发起需要长时间执行的操作\n Server->>Store: 创建任务记录\n Server-->>Client: 返回 taskId\n \n loop 任务执行中\n Client->>Server: getTaskResult(taskId)\n Server->>Store: 查询任务状态\n Store-->>Server: 返回任务结果\n Server-->>Client: 返回 GetTaskPayloadResult\n end\n \n Client->>Server: cancelTask(taskId)\n Server->>Store: 更新任务状态为已取消\n Server-->>Client: 返回 CancelTaskResult\n```\n\n### 完整示例\n\n```typescript\nimport { Client } from '@modelcontextprotocol/sdk/client';\nimport { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp';\nimport { ClientTaskApi } from '@modelcontextprotocol/sdk/experimental';\n\n// 初始化客户端\nconst transport = new StreamableHTTPClientTransport('http://localhost:3000/mcp');\nconst client = new Client({ name: 'example-client', version: '1.0.0' });\nawait client.connect(transport);\n\n// 创建任务 API 实例\nconst taskApi = new ClientTaskApi(client);\n\n// 获取任务结果\nconst result = await taskApi.getTaskResult('task-123');\nconsole.log(result);\n\n// 列出所有任务\nconst { tasks, nextCursor } = await taskApi.listTasks();\n\n// 取消任务\nawait taskApi.cancelTask('task-456');\n```\n\n---\n\n## 类型定义\n\n### 核心类型\n\n| 类型 | 描述 |\n|------|------|\n| `Task` | 任务数据模型 |\n| `TaskId` | 任务唯一标识符 |\n| `GetTaskPayloadResult` | 任务结果载荷 |\n| `ListTasksResult` | 任务列表结果 |\n| `CancelTaskResult` | 取消操作结果 |\n| `RequestOptions` | 请求配置选项 |\n\n资料来源：[packages/core/src/types/types.ts](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/core/src/types/types.ts)\n\n---\n\n## 最佳实践\n\n### 1. 错误处理\n\n始终对任务操作进行错误处理：\n\n```typescript\ntry {\n const result = await taskApi.getTaskResult(taskId);\n} catch (error) {\n if (error.code === 'TASK_NOT_FOUND') {\n console.error('任务不存在:', taskId);\n } else {\n throw error;\n }\n}\n```\n\n### 2. 任务超时管理\n\n建议设置合理的请求超时：\n\n```typescript\nconst result = await taskApi.getTaskResult(taskId, {\n timeout: 30000, // 30秒超时\n signal: AbortSignal.timeout(30000)\n});\n```\n\n### 3. 进度追踪\n\n对于长时间运行的任务，定期轮询状态：\n\n```typescript\nasync function waitForCompletion(taskId: string, interval = 1000) {\n while (true) {\n const result = await taskApi.getTaskResult(taskId);\n if (result.status === 'completed') {\n return result;\n }\n if (result.status === 'failed') {\n throw new Error(`任务失败: ${result.error}`);\n }\n await new Promise(resolve => setTimeout(resolve, interval));\n }\n}\n```\n\n---\n\n## 注意事项\n\n1. **实验性警告**：所有任务系统 API 均为实验性，可能在后续版本中发生不兼容变更。\n\n2. **状态持久化**：`InMemoryTaskStore` 不支持持久化，进程重启后任务状态会丢失。如需持久化，请实现自定义存储。\n\n3. **并发限制**：大量并发任务可能影响性能，建议实现适当的限流机制。\n\n4. **资源清理**：任务完成后应及时调用 `cancelTask` 或清理过期任务，避免内存泄漏。\n\n---\n\n## 相关资源\n\n- [MCP 协议规范](https://modelcontextprotocol.io/specification)\n- [服务端文档](../../docs/server.md)\n- [客户端文档](../../docs/client.md)\n- [Streamable HTTP 传输](../transports/streamableHttp.md)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：modelcontextprotocol/typescript-sdk\n\n摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：运行坑 - 来源证据：client code can't execute inside browser due to import spawn。\n\n## 1. 运行坑 · 来源证据：client code can't execute inside browser due to import spawn\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：client code can't execute inside browser due to import spawn\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8a06947266aa4987ad712baf87a7a156 | https://github.com/modelcontextprotocol/typescript-sdk/issues/2077 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `typescript-sdk` 与安装入口 `@modelcontextprotocol/server` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @modelcontextprotocol/server`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | repo=typescript-sdk; install=@modelcontextprotocol/server\n\n## 3. 安装坑 · 来源证据：@modelcontextprotocol/node@2.0.0-alpha.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/node@2.0.0-alpha.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fc8de64b72814f8eb9ed0e53852408c2 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/node%402.0.0-alpha.1 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：@modelcontextprotocol/server@2.0.0-alpha.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/server@2.0.0-alpha.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dff36a13cb954c3b84b05e99a28dc4d0 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.0.0-alpha.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：modelcontextprotocol/typescript-sdk\n\n摘要：发现 11 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：运行坑 - 来源证据：client code can't execute inside browser due to import spawn。\n\n## 1. 运行坑 · 来源证据：client code can't execute inside browser due to import spawn\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：client code can't execute inside browser due to import spawn\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8a06947266aa4987ad712baf87a7a156 | https://github.com/modelcontextprotocol/typescript-sdk/issues/2077 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 2. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `typescript-sdk` 与安装入口 `@modelcontextprotocol/server` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npm install @modelcontextprotocol/server`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | repo=typescript-sdk; install=@modelcontextprotocol/server\n\n## 3. 安装坑 · 来源证据：@modelcontextprotocol/node@2.0.0-alpha.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/node@2.0.0-alpha.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_fc8de64b72814f8eb9ed0e53852408c2 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/node%402.0.0-alpha.1 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：@modelcontextprotocol/server@2.0.0-alpha.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：@modelcontextprotocol/server@2.0.0-alpha.1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_dff36a13cb954c3b84b05e99a28dc4d0 | https://github.com/modelcontextprotocol/typescript-sdk/releases/tag/%40modelcontextprotocol/server%402.0.0-alpha.1 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | README/documentation is current enough for a first validation pass.\n\n## 6. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | last_activity_observed missing\n\n## 7. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium\n\n## 8. 安全/权限坑 · 存在安全注意事项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：No sandbox install has been executed yet; downstream must verify before user use.\n- 对用户的影响：用户安装前需要知道权限边界和敏感操作。\n- 建议检查：转成明确权限清单和安全审查提示。\n- 防护动作：安全注意事项必须面向用户前置展示。\n- 证据：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.\n\n## 9. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | no_demo; severity=medium\n\n## 10. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作：issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | issue_or_pr_quality=unknown\n\n## 11. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:862578138 | https://github.com/modelcontextprotocol/typescript-sdk | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# typescript-sdk - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 typescript-sdk 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的软件开发与交付任务。\n我常用的宿主 AI：Local CLI\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: The official TypeScript SDK for Model Context Protocol servers and clients 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：MCP TypeScript SDK 概述。围绕“MCP TypeScript SDK 概述”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：系统架构与包结构。围绕“系统架构与包结构”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：协议与类型定义。围绕“协议与类型定义”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：数据验证与 Schema。围绕“数据验证与 Schema”模拟一次用户任务，不展示安装或运行结果。\n5. page-5：传输层实现。围绕“传输层实现”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“MCP TypeScript SDK 概述”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“系统架构与包结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“协议与类型定义”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“数据验证与 Schema”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-5\n输入：用户提供的“传输层实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“MCP TypeScript SDK 概述”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“系统架构与包结构”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“协议与类型定义”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“数据验证与 Schema”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-5：Step 5 必须围绕“传输层实现”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/modelcontextprotocol/typescript-sdk\n- https://github.com/modelcontextprotocol/typescript-sdk#readme\n- README.md\n- package.json\n- packages/core/src/index.ts\n- packages/server/package.json\n- packages/client/package.json\n- packages/middleware/node/package.json\n- pnpm-workspace.yaml\n- packages/core/src/types/spec.types.ts\n- packages/core/src/shared/protocol.ts\n- packages/core/src/types/types.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 typescript-sdk 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：modelcontextprotocol/typescript-sdk\n\n## 官方安装入口\n\n### Node.js / npm · 官方安装入口\n\n```bash\nnpm install @modelcontextprotocol/server\n```\n\n来源：https://github.com/modelcontextprotocol/typescript-sdk#readme\n\n## 来源\n\n- repo: https://github.com/modelcontextprotocol/typescript-sdk\n- docs: https://github.com/modelcontextprotocol/typescript-sdk#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_8cca56272487449aa01d18df1fa47cf3"
}