{
"canonical_name": "modelcontextprotocol/python-sdk",
"compilation_id": "pack_5946a989e513494e977537318e2eb2b8",
"created_at": "2026-05-13T13:14:41.083935+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 `npx -y @modelcontextprotocol/inspector` 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": "npx -y @modelcontextprotocol/inspector",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_758fe094fc864845bed2f6aa04e812bc"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_5cbe53a3f482ddcfa629e8512803cebc",
"canonical_name": "modelcontextprotocol/python-sdk",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/modelcontextprotocol/python-sdk",
"slug": "python-sdk",
"source_packet_id": "phit_dc8c8558a5904a6dbbcac901cd3138f1",
"source_validation_id": "dval_1fed190163f04f2688cefc073878d95c"
},
"merchandising": {
"best_for": "需要软件开发与交付能力，并使用 local_cli的用户",
"github_forks": 3417,
"github_stars": 22976,
"one_liner_en": "The official Python SDK for Model Context Protocol servers and clients",
"one_liner_zh": "The official Python 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": "python-sdk",
"title_zh": "python-sdk 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"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": "Local-first",
"label_zh": "本地优先",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-local-first",
"type": "selection_signal"
}
]
},
"packet_id": "phit_dc8c8558a5904a6dbbcac901cd3138f1",
"page_model": {
"artifacts": {
"artifact_slug": "python-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": "npx -y @modelcontextprotocol/inspector",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/modelcontextprotocol/python-sdk#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"本地优先"
],
"eyebrow": "软件开发与交付",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要软件开发与交付能力，并使用 local_cli的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "The official Python 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 社区证据显示该项目存在一个运行相关的待验证问题：[packit] Pull from upstream failed for release 1.27.1",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_7cd3c6cd2e994e6cbd60b3cbb19c96e6 | https://github.com/modelcontextprotocol/python-sdk/issues/2563 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：[packit] Pull from upstream failed for release 1.27.1",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP client does not retry authenticated request after successful OAuth token exchange",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_437e528a826e41e6ae0d654e0e858cbc | https://github.com/modelcontextprotocol/python-sdk/issues/2577 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：MCP client does not retry authenticated request after successful OAuth token exchange",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_f4669be4619541d3bc0001e432fa5416 | https://github.com/modelcontextprotocol/python-sdk/issues/2578 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Race condition between SSE session init and tools/call rejection (-32602)",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_f707b6204fd541d3aea0e5c1ef97e432 | https://github.com/modelcontextprotocol/python-sdk/issues/2583 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Race condition between SSE session init and tools/call rejection (-32602)",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Types-only install option",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_1582e38e22384d509ffb75f91a25c9d0 | https://github.com/modelcontextprotocol/python-sdk/issues/2581 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Types-only install option",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Expose `schema_generator` on `FastMCP` for tool params schema generation",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_2a614d750d3f4ec59807cdd800d8ff75 | https://github.com/modelcontextprotocol/python-sdk/issues/2582 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Expose `schema_generator` on `FastMCP` for tool params schema generation",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.24.0",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_51df2611be1e47b586edd80b1adb1cfb | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.24.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.24.0",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：fix: 4 additional raise sites missing exception chaining with 'from'",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_71303d3f16c942efb8521432eba345a1 | https://github.com/modelcontextprotocol/python-sdk/issues/2575 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：fix: 4 additional raise sites missing exception chaining with 'from'",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.23.2",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_3c7b4addde6a4da3ae29d5f3f01e7455 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.23.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:862584018 | https://github.com/modelcontextprotocol/python-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:862584018 | https://github.com/modelcontextprotocol/python-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:862584018 | https://github.com/modelcontextprotocol/python-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:862584018 | https://github.com/modelcontextprotocol/python-sdk | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Claude Code client sends tools/call without initialize handshake — SSE transport rejects with -32602",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_48d1c0f7a5d040568e55a2fa6ead27d8 | https://github.com/modelcontextprotocol/python-sdk/issues/2579 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Claude Code client sends tools/call without initialize handshake — SSE transport rejects with -32602",
"user_impact": "可能阻塞安装或首次运行。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.23.0",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_ca7e48aa359f4c0b86a3ca42172b40d9 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：v1.23.0",
"user_impact": "可能影响授权、密钥配置或安全边界。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 22 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：运行坑 - 来源证据：[packit] Pull from upstream failed for release 1.27.1。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 185,
"forks": 3417,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 22976
},
"source_url": "https://github.com/modelcontextprotocol/python-sdk",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "The official Python SDK for Model Context Protocol servers and clients",
"title": "python-sdk 能力包",
"trial_prompt": "# python-sdk - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 python-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 Python SDK for Model Context Protocol servers and clients 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：MCP 协议与 Python SDK 简介。围绕“MCP 协议与 Python SDK 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始指南。围绕“快速开始指南”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构与核心组件。围绕“系统架构与核心组件”模拟一次用户任务，不展示安装或运行结果。\n5. page-transports：传输协议实现。围绕“传输协议实现”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“MCP 协议与 Python SDK 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构与核心组件”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-transports\n输入：用户提供的“传输协议实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“MCP 协议与 Python SDK 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始指南”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构与核心组件”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-transports：Step 5 必须围绕“传输协议实现”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/modelcontextprotocol/python-sdk\n- https://github.com/modelcontextprotocol/python-sdk#readme\n- README.md\n- docs/concepts.md\n- src/mcp/__init__.py\n- docs/installation.md\n- pyproject.toml\n- examples/snippets/servers/fastmcp_quickstart.py\n- examples/snippets/servers/basic_tool.py\n- examples/snippets/servers/basic_resource.py\n- examples/snippets/servers/basic_prompt.py\n- src/mcp/client/client.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 python-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: Race condition between SSE session init and tools/call rejection (-32602（https://github.com/modelcontextprotocol/python-sdk/issues/2583）；github/github_issue: Expose `schema_generator` on `FastMCP` for tool params schema generation（https://github.com/modelcontextprotocol/python-sdk/issues/2582）；github/github_issue: MCP client does not retry authenticated request after successful OAuth t（https://github.com/modelcontextprotocol/python-sdk/issues/2577）；github/github_issue: Types-only install option（https://github.com/modelcontextprotocol/python-sdk/issues/2581）；github/github_issue: [packit] Pull from upstream failed for release 1.27.1（https://github.com/modelcontextprotocol/python-sdk/issues/2563）；github/github_issue: OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0（https://github.com/modelcontextprotocol/python-sdk/issues/2578）；github/github_issue: Claude Code client sends tools/call without initialize handshake — SSE t（https://github.com/modelcontextprotocol/python-sdk/issues/2579）；github/github_issue: fix: 4 additional raise sites missing exception chaining with 'from'（https://github.com/modelcontextprotocol/python-sdk/issues/2575）；github/github_release: v1.27.1（https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.27.1）；github/github_release: v1.27.0（https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.27.0）；github/github_release: v1.26.0（https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.26.0）；github/github_release: v1.25.0（https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.25.0）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "Race condition between SSE session init and tools/call rejection (-32602",
"url": "https://github.com/modelcontextprotocol/python-sdk/issues/2583"
},
{
"kind": "github_issue",
"source": "github",
"title": "Expose `schema_generator` on `FastMCP` for tool params schema generation",
"url": "https://github.com/modelcontextprotocol/python-sdk/issues/2582"
},
{
"kind": "github_issue",
"source": "github",
"title": "MCP client does not retry authenticated request after successful OAuth t",
"url": "https://github.com/modelcontextprotocol/python-sdk/issues/2577"
},
{
"kind": "github_issue",
"source": "github",
"title": "Types-only install option",
"url": "https://github.com/modelcontextprotocol/python-sdk/issues/2581"
},
{
"kind": "github_issue",
"source": "github",
"title": "[packit] Pull from upstream failed for release 1.27.1",
"url": "https://github.com/modelcontextprotocol/python-sdk/issues/2563"
},
{
"kind": "github_issue",
"source": "github",
"title": "OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0",
"url": "https://github.com/modelcontextprotocol/python-sdk/issues/2578"
},
{
"kind": "github_issue",
"source": "github",
"title": "Claude Code client sends tools/call without initialize handshake — SSE t",
"url": "https://github.com/modelcontextprotocol/python-sdk/issues/2579"
},
{
"kind": "github_issue",
"source": "github",
"title": "fix: 4 additional raise sites missing exception chaining with 'from'",
"url": "https://github.com/modelcontextprotocol/python-sdk/issues/2575"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.27.1",
"url": "https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.27.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.27.0",
"url": "https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.27.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.26.0",
"url": "https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.26.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.25.0",
"url": "https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.25.0"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "软件开发与交付",
"desc": "The official Python SDK for Model Context Protocol servers and clients",
"effort": "安装已验证",
"forks": 3417,
"icon": "code",
"name": "python-sdk 能力包",
"risk": "可发布",
"slug": "python-sdk",
"stars": 22976,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"浏览器自动化",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/modelcontextprotocol/python-sdk 项目说明书\n\n生成时间：2026-05-13 12:56:39 UTC\n\n## 目录\n\n- [MCP 协议与 Python SDK 简介](#page-introduction)\n- [安装与配置](#page-installation)\n- [快速开始指南](#page-quickstart)\n- [系统架构与核心组件](#page-architecture)\n- [传输协议实现](#page-transports)\n- [FastMCP 服务器框架](#page-fastmcp)\n- [资源、资源模板、提示与工具](#page-resources-prompts-tools)\n- [上下文与会话管理](#page-context-session)\n- [客户端开发指南](#page-client-development)\n- [客户端 OAuth 认证](#page-client-auth)\n\n\n\n## MCP 协议与 Python SDK 简介\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [系统架构与核心组件](#page-architecture), [快速开始指南](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [AGENTS.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/CONTRIBUTING.md)\n- [examples/snippets/servers/completion.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/completion.py)\n- [src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n- [src/mcp/server/mcpserver/resources/base.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/base.py)\n- [src/mcp/server/mcpserver/resources/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n- [examples/servers/simple-prompt/mcp_simple_prompt/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-prompt/mcp_simple_prompt/server.py)\n- [examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py)\n- [RELEASE.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/RELEASE.md)\n \n\n# MCP 协议与 Python SDK 简介\n\n## 概述\n\nMCP（Model Context Protocol，模型上下文协议）是一种开放协议，用于在大型语言模型（LLM）应用程序与外部数据源、工具和服务之间建立标准化的通信桥梁。Python SDK 是该协议的核心实现库，为开发者提供了构建 MCP 服务器和客户端的能力。\n\nMCP 协议的核心价值在于**标准化**——它定义了 LLM 应用与外部世界交互的统一方式，使开发者能够创建可复用的组件，让 AI 系统能够安全、受控地访问本地文件、数据库、API 以及各类服务。\n\n## 核心概念\n\n### 服务器与客户端架构\n\nMCP 采用典型的客户端-服务器架构，支持多种通信传输方式：\n\n| 组件 | 说明 | 支持的传输方式 |\n|------|------|----------------|\n| MCP 服务器 | 托管资源、工具和提示的服务器 | stdio、streamable-http |\n| MCP 客户端 | 连接服务器并调用功能的客户端 | stdio、streamable-http |\n\n```mermaid\ngraph TD\n A[\"MCP 客户端\"] -->|\"stdio/streamable-http\"| B[\"MCP 服务器\"]\n B --> C[\"资源管理器\"]\n B --> D[\"工具管理器\"]\n B --> E[\"提示管理器\"]\n B --> F[\"完成处理器\"]\n C --> G[\"FunctionResource\"]\n C --> H[\"FileResource\"]\n G --> I[\"fn: Callable\"]\n H --> J[\"path: Path\"]\n```\n\n### 资源系统\n\nMCP 的资源系统允许服务器向客户端暴露可读取的数据。SDK 支持两种主要资源类型：\n\n| 资源类型 | 说明 | 关键字段 |\n|----------|------|----------|\n| FunctionResource | 通过函数动态生成的资源内容 | `fn: Callable` |\n| FileResource | 从文件系统读取的静态资源 | `path: Path`, `is_binary: bool` |\n\n所有资源都继承自基类 `Resource`，包含以下通用字段：\n\n- `uri`: 资源的唯一标识符\n- `name`: 资源名称\n- `title`: 人类可读的标题\n- `description`: 资源描述\n- `mime_type`: 资源的 MIME 类型，默认 `text/plain`\n- `annotations`: 资源的注解信息\n- `meta`: 额外的元数据\n\n资料来源：[src/mcp/server/mcpserver/resources/base.py:1-42](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/base.py)\n\n### 工具系统\n\n工具是 MCP 服务器暴露的可执行函数，客户端可以通过 JSON-RPC 调用这些工具。工具系统支持：\n\n- **结构化输出**: 使用 Pydantic 模型定义返回格式\n- **元数据**: 支持标题、描述、图标和注解\n- **异步执行**: 所有工具函数支持异步调用\n\n```python\ndef add_tool(\n self,\n fn: Callable[..., Any],\n name: str | None = None,\n title: str | None = None,\n description: str | None = None,\n annotations: Annotations | None = None,\n icons: list[Icon] | None = None,\n meta: ToolMeta | None = None,\n structured_output: type[BaseModel] | None = None,\n) -> None:\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n\n### 提示系统\n\n提示（Prompts）允许服务器定义可复用的消息模板，这些模板可以接受参数并生成动态内容：\n\n```python\nclass Prompt(BaseModel, abc.ABC):\n name: str\n description: str | None = None\n arguments: list[PromptArgument] | None = None\n icons: list[Icon] | None = None\n```\n\n使用示例：\n\n```python\nreturn types.GetPromptResult(\n messages=create_messages(context=arguments.get(\"context\"), topic=arguments.get(\"topic\")),\n description=\"A simple prompt with optional context and topic arguments\",\n)\n```\n\n资料来源：[examples/servers/simple-prompt/mcp_simple_prompt/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-prompt/mcp_simple_prompt/server.py)\n\n### 完成处理器\n\n完成处理器为资源模板和提示参数提供动态补全建议：\n\n```python\n@mcp.completion()\nasync def handle_completion(ref, argument, context):\n if isinstance(ref, ResourceTemplateReference):\n if ref.uri == \"github://repos/{owner}/{repo}\" and argument.name == \"repo\":\n if context and context.arguments and context.arguments.get(\"owner\") == \"modelcontextprotocol\":\n repos = [\"python-sdk\", \"typescript-sdk\", \"specification\"]\n return Completion(values=repos, has_more=False)\n return None\n```\n\n资料来源：[examples/snippets/servers/completion.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/completion.py)\n\n## 交互式任务系统\n\nMCP 支持长时间运行的任务（Tasks），包括两个关键功能：\n\n### elicitation（征询）\n\n用于在执行过程中请求用户确认或输入：\n\n```mermaid\ngraph LR\n A[\"工具调用\"] --> B[\"task.elicit()\"]\n B --> C[\"input_required 状态\"]\n C --> D[\"用户响应\"]\n D --> E[\"任务完成\"]\n```\n\n### Sampling（采样）\n\n允许服务器请求 LLM 生成内容：\n\n```mermaid\ngraph LR\n A[\"工具调用\"] --> B[\"task.create_message()\"]\n B --> C[\"input_required 状态\"]\n C --> D[\"LLM 响应\"]\n D --> E[\"任务完成\"]\n```\n\n资料来源：[examples/servers/simple-task-interactive/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-task-interactive/README.md)\n\n## 认证系统\n\nSDK 提供了 OAuth 认证支持，包括完整的授权码流程：\n\n```mermaid\ngraph TD\n A[\"客户端\"] --> B[\"授权请求\"]\n B --> C[\"用户登录\"]\n C --> D[\"授权码回调\"]\n D --> E[\"令牌交换\"]\n E --> F[\"认证完成\"]\n```\n\n认证服务器可以返回 HTML 表单进行交互：\n\n```python\nasync def handle_login_callback(self, request: Request) -> Response:\n form = await request.form()\n username = form.get(\"username\")\n password = form.get(\"password\")\n state = form.get(\"state\")\n```\n\n资料来源：[examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py)\n\n## 开发指南\n\n### 环境配置\n\n```bash\n# 安装 uv（如果尚未安装）\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# 克隆仓库\ngit clone https://github.com/modelcontextprotocol/python-sdk.git\n\n# 安装依赖\nuv sync --frozen --all-extras --dev\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/CONTRIBUTING.md)\n\n### 代码质量要求\n\n| 检查项 | 命令 | 说明 |\n|--------|------|------|\n| 格式化 | `uv run --frozen ruff format .` | 使用 ruff 格式化代码 |\n| 静态检查 | `uv run --frozen ruff check . --fix` | 自动修复 lint 问题 |\n| 类型检查 | `uv run --frozen pyright` | 运行 pyright 类型检查 |\n| 测试 | `uv run --frozen pytest` | 执行测试套件 |\n\n### 核心规范\n\n1. **类型提示**: 所有公共 API 必须包含类型提示\n2. **文档字符串**: 公共 API 必须有 docstring，包含 `Raises:` 部分说明可能抛出的异常\n3. **异常处理**: \n - 使用 `logger.exception()` 而非 `logger.error()`\n - 捕获具体异常类型而非通用 `Exception`\n - 禁止在顶级处理器之外使用 `except Exception:`\n4. **导入规范**: 所有导入必须位于文件顶部，禁止内联导入\n\n```python\n# 正确示例\ntry:\n resource = await self._resource_manager.get_resource(uri, context)\nexcept ValueError as exc:\n raise ResourceError(f\"Unknown resource: {uri}\") from exc\n```\n\n资料来源：[AGENTS.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/AGENTS.md)\n\n### 测试规范\n\n- 使用 `anyio` 进行异步测试，而非 `asyncio`\n- 测试应快速且确定性，使用内存异步执行\n- 使用线程仅在必要时，使用子进程作为最后手段\n- 不要使用 `Test` 前缀的类，使用顶层 `test_*` 函数\n\n```python\n# 推荐\ndef test_resource_read():\n assert isinstance(resource, FunctionResource)\n\n# 避免\nclass TestResource:\n def test_read(self):\n ...\n```\n\n## 分支模型\n\n| 分支 | 用途 | 变更类型 |\n|------|------|----------|\n| `main` | V2 开发分支 | 新功能、破坏性变更 |\n| `v1.x` | 稳定版发布分支 | 安全修复、关键 bug 修复 |\n\n资料来源：[AGENTS.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/AGENTS.md)\n\n## 发布流程\n\n1. 在 `pyproject.toml` 中更新依赖版本\n2. 运行 `uv lock --resolution lowest-direct` 升级锁文件\n3. 通过 GitHub UI 创建 Release，标签格式为 `vX.Y.Z`\n4. 版本号将从标签自动设置\n\n资料来源：[RELEASE.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/RELEASE.md)\n\n## 快速开始示例\n\n### 创建简单服务器\n\n```python\nfrom mcp.server.mcpserver import Server\nfrom mcp.server.stdio import stdio_server\n\napp = Server(\"my-mcp-server\")\n\n@app.list_tools()\nasync def handle_list_tools():\n return [types.Tool(\n name=\"greet\",\n description=\"Greet someone\",\n inputSchema={\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}}\n )]\n\nasync def main():\n async with stdio_server() as streams:\n await app.run(streams[0], streams[1], app.create_initialization_options())\n```\n\n### 启动 HTTP 服务器\n\n```python\nimport uvicorn\n\nif transport == \"streamable-http\":\n uvicorn.run(app.streamable_http_app(), host=\"127.0.0.1\", port=port)\n```\n\n资料来源：[examples/servers/simple-prompt/mcp_simple_prompt/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-prompt/mcp_simple_prompt/server.py)\n\n## 总结\n\nMCP Python SDK 提供了一套完整、健壮的框架，用于构建与 LLM 应用交互的服务器和客户端。通过标准化的资源、工具、提示和完成处理器接口，开发者可以创建可复用、安全且易于维护的 MCP 组件。SDK 遵循严格的代码质量标准，包括类型提示要求、完整的文档字符串规范以及全面的测试覆盖，确保其稳定性和可维护性。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[MCP 协议与 Python SDK 简介](#page-introduction), [快速开始指南](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/CONTRIBUTING.md)\n- [AGENTS.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/AGENTS.md)\n- [examples/clients/simple-auth-client/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/clients/simple-auth-client/README.md)\n- [examples/servers/simple-auth/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-auth/README.md)\n- [examples/clients/simple-task-client/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/clients/simple-task-client/README.md)\n- [examples/servers/simple-task-interactive/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-task-interactive/README.md)\n \n\n# 安装与配置\n\n本文档详细说明 Model Context Protocol (MCP) Python SDK 的安装、环境配置以及开发环境搭建流程。\n\n## 环境要求\n\n### 系统依赖\n\n| 依赖项 | 版本要求 | 说明 |\n|--------|----------|------|\n| Python | 3.10+ | 支持 Python 3.10 至 3.14 |\n| uv | 最新稳定版 | 包管理工具，详见 [uv 官方文档](https://docs.astral.sh/uv/getting-started/installation/) |\n\n资料来源：[CONTRIBUTING.md:1-3]()\n\n### 验证 Python 版本\n\n```bash\npython --version\n```\n\n确保输出为 Python 3.10 或更高版本。\n\n## 项目克隆与依赖安装\n\n### 1. Fork 并克隆仓库\n\n```bash\n# 1. 在 GitHub 上 Fork 仓库\n# 2. 克隆你的 Fork\ngit clone https://github.com/YOUR-USERNAME/python-sdk.git\n\n# 3. 进入项目目录\ncd python-sdk\n```\n\n资料来源：[CONTRIBUTING.md:3-6]()\n\n### 2. 安装依赖\n\nMCP Python SDK **仅支持 uv 作为包管理工具**，严格禁止使用 pip 进行安装或依赖管理。\n\n```bash\n# 安装所有依赖（包括开发依赖和可选依赖）\nuv sync --frozen --all-extras --dev\n```\n\n参数说明：\n- `--frozen`：锁定版本，不更新 lock 文件\n- `--all-extras`：安装所有可选依赖\n- `--dev`：安装开发依赖\n\n资料来源：[CONTRIBUTING.md:7]()\n\n### 3. 设置预提交钩子\n\n```bash\nuv tool install pre-commit --with pre-commit-uv --force-reinstall\n```\n\n预提交钩子会自动执行代码格式化、类型检查等操作。\n\n资料来源：[CONTRIBUTING.md:9-11]()\n\n## 开发环境配置\n\n### uv 工具链使用规范\n\n| 操作类型 | 命令格式 | 说明 |\n|----------|----------|------|\n| 运行工具 | `uv run --frozen ` | 始终使用 `--frozen` 避免意外修改 lock 文件 |\n| 添加依赖 | `uv add ` | 仅用于开发环境 |\n| 升级依赖 | `uv lock --upgrade-package ` | 升级指定包版本 |\n| 测试跨版本 | `uv run --frozen --python 3.10 pytest ...` | 指定 Python 版本运行测试 |\n\n**禁止操作：**\n- 禁止使用 `uv pip install`\n- 禁止使用 `@latest` 语法指定版本\n- 不要仅为修复 CVE 而提升依赖版本下限，约束条件 `>=` 已允许用户自行升级\n\n资料来源：[AGENTS.md:1-20]()\n\n### 代码质量检查\n\n开发过程中应运行以下检查：\n\n```bash\n# 运行测试\nuv run pytest\n\n# 类型检查\nuv run pyright\n\n# 代码格式化\nuv run ruff format .\n\n# 代码检查\nuv run ruff check . --fix\n```\n\n全部检查命令可通过预提交钩子一键执行：\n\n```bash\npre-commit run --all-files\n```\n\n资料来源：[CONTRIBUTING.md:20-35]()\n\n## 服务器配置\n\n### 基本配置参数\n\n客户端连接 MCP 服务器时可通过环境变量配置连接参数：\n\n| 环境变量 | 说明 | 默认值 |\n|----------|------|--------|\n| `MCP_SERVER_PORT` | MCP 服务器端口号 | `8000` |\n| `MCP_TRANSPORT_TYPE` | 传输类型：`streamable-http` 或 `sse` | `streamable-http` |\n| `MCP_CLIENT_METADATA_URL` | 客户端元数据 (CIMD) 的可选 URL | `None` |\n\n资料来源：[examples/clients/simple-auth-client/README.md:47-52]()\n\n### 启动服务器示例\n\n#### Streamable HTTP 传输\n\n```bash\n# 基本启动\nuv run mcp-simple-auth --port=8000 --transport=streamable-http\n\n# 带 OAuth 严格模式\nuv run mcp-simple-auth --port=8000 --transport=streamable-http --oauth-strict\n```\n\n#### SSE 传输\n\n```bash\nuv run mcp-simple-auth --port=8000 --transport=sse\n```\n\n资料来源：[examples/servers/simple-auth/README.md:30-45]()\n\n### 任务服务器配置\n\n交互式任务服务器默认启动地址为 `http://localhost:8000/mcp`，可通过 `--port` 参数修改：\n\n```bash\nuv run mcp-simple-task-interactive --port=9000\n```\n\n资料来源：[examples/servers/simple-task-interactive/README.md:8-12]()\n\n## 项目分支模型\n\nMCP SDK 采用双分支维护策略：\n\n| 分支 | 用途 | 变更类型 |\n|------|------|----------|\n| `main` | V2 开发分支 | 新功能、重构，允许破坏性变更 |\n| `v1.x` | V1 稳定分支 | 仅接收安全修复和关键 bug 修复 |\n\n开发新功能或破坏性变更应基于 `main` 分支创建新分支。安全修复和关键 bug 修复应基于 `v1.x` 分支。\n\n资料来源：[AGENTS.md:1-15]()\n\n## 开发工作流\n\n```mermaid\ngraph TD\n A[选择目标分支] --> B[基于目标分支创建新分支]\n B --> C[编写代码]\n C --> D[运行测试: uv run pytest]\n D --> E{测试通过?}\n E -->|否| F[修复问题]\n F --> C\n E -->|是| G[运行类型检查: uv run pyright]\n G --> H[运行代码检查: uv run ruff check]\n H --> I[提交代码]\n I --> J[创建 Pull Request]\n J --> K[等待 Code Review]\n```\n\n### 代码提交检查清单\n\n1. ✅ 更新相关文档\n2. ✅ 为新功能添加测试\n3. ✅ 确保 CI 通过\n4. ✅ 处理代码审查反馈\n\n资料来源：[CONTRIBUTING.md:37-60]()\n\n## 调试与日志\n\n### 异常处理规范\n\n- **必须使用** `logger.exception()` 而非 `logger.error()` 捕获异常\n- **禁止** 在日志消息中包含异常信息：`logger.exception(\"Failed\")` 而非 `logger.exception(f\"Failed: {e}\")`\n- **优先捕获具体异常类型**：\n - 文件操作：`except (OSError, PermissionError):`\n - JSON 解析：`except json.JSONDecodeError:`\n - 网络操作：`except (ConnectionError, TimeoutError):`\n- **禁止使用** `except Exception:`（顶层处理器除外）\n\n资料来源：[AGENTS.md:1-30]()\n\n### 常见配置问题排查\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 连接被拒绝 | 服务器未启动或端口错误 | 检查 `MCP_SERVER_PORT` 环境变量 |\n| 传输类型错误 | 不支持的传输类型 | 确认使用 `streamable-http` 或 `sse` |\n| 依赖冲突 | 使用了 pip 而非 uv | 使用 `uv sync` 重新安装依赖 |\n\n## 验证安装\n\n安装完成后，可通过以下命令验证环境：\n\n```bash\n# 验证 uv 可用\nuv --version\n\n# 验证 Python 版本\npython --version\n\n# 验证 MCP SDK 安装\nuv run python -c \"import mcp; print(mcp.__version__)\"\n\n# 运行项目测试\nuv run pytest -v\n```\n\n## 下一步\n\n- 阅读 [工具开发指南](./tools.md) 了解如何创建 MCP 工具\n- 阅读 [资源管理](./resources.md) 了解如何暴露资源\n- 阅读 [提示模板](./prompts.md) 了解如何定义提示\n\n---\n\n\n\n## 快速开始指南\n\n### 相关页面\n\n相关主题：[FastMCP 服务器框架](#page-fastmcp), [资源、资源模板、提示与工具](#page-resources-prompts-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/snippets/servers/fastmcp_quickstart.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/fastmcp_quickstart.py)\n- [examples/snippets/servers/basic_tool.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_tool.py)\n- [examples/snippets/servers/basic_resource.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_resource.py)\n- [examples/snippets/servers/basic_prompt.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_prompt.py)\n- [src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n- [src/mcp/server/mcpserver/resources/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n \n\n# 快速开始指南\n\n本指南帮助开发者快速上手 Model Context Protocol (MCP) Python SDK，涵盖服务器创建、工具（Tool）、资源（Resource）和提示（Prompt）的定义与注册，以及如何启动服务。\n\n## 环境准备\n\n### 前置要求\n\n| 要求 | 版本说明 |\n|------|----------|\n| Python | 3.10+ |\n| 包管理器 | uv |\n| 操作系统 | Windows、macOS、Linux |\n\n### 安装 SDK\n\n```bash\n# 使用 uv 安装稳定版本\nuv add mcp\n\n# 安装开发版本（包含所有额外依赖和开发工具）\nuv sync --frozen --all-extras --dev\n```\n\n资料来源：[CONTRIBUTING.md:5-8]()\n\n## MCP 服务器架构\n\nMCP 服务器是 MCP 协议的核心组件，负责向客户端提供服务能力。\n\n```mermaid\ngraph TD\n A[客户端] --> B[MCP Server]\n B --> C[工具管理器
Tool Manager]\n B --> D[资源管理器
Resource Manager]\n B --> E[提示管理器
Prompt Manager]\n C --> F[工具函数]\n D --> G[资源数据]\n E --> H[提示模板]\n```\n\nMCPServer 类是 SDK 的主入口，负责管理所有组件的生命周期并处理客户端请求。\n\n资料来源：[src/mcp/server/mcpserver/server.py:1-50]()\n\n## 创建基础服务器\n\n### 最小示例\n\n```python\nfrom mcp.server import MCPServer\n\nserver = MCPServer(\n name=\"my-server\",\n version=\"1.0.0\",\n)\n```\n\n### 完整配置示例\n\n```python\nfrom mcp.server import MCPServer, ServerSettings\n\nsettings = ServerSettings(\n host=\"0.0.0.0\",\n port=8000,\n streamable_http_transport=True,\n)\nserver = MCPServer(\n name=\"example-server\",\n version=\"1.0.0\",\n settings=settings,\n)\n```\n\n| ServerSettings 参数 | 类型 | 默认值 | 说明 |\n|---------------------|------|--------|------|\n| host | str | \"127.0.0.1\" | 监听地址 |\n| port | int | 8000 | 监听端口 |\n| streamable_http_transport | bool | False | 启用流式 HTTP 传输 |\n| oauth_strict | bool | False | 启用严格 OAuth 认证 |\n\n资料来源：[examples/snippets/servers/fastmcp_quickstart.py:1-30]()\n\n## 定义工具（Tool）\n\n工具是服务器暴露给客户端的可调用函数。\n\n### 基本工具定义\n\n```python\nfrom mcp.server import MCPServer\nfrom mcp.types import Tool\n\ndef get_weather(location: str) -> str:\n \"\"\"获取指定位置的天气信息\"\"\"\n return f\"{location} 天气晴朗，温度 25°C\"\n\nserver = MCPServer(name=\"weather-server\")\nserver.add_tool(\n fn=get_weather,\n name=\"get_weather\",\n description=\"获取天气信息\",\n)\n```\n\n### add_tool 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| fn | Callable | 是 | 工具函数 |\n| name | str | 否 | 工具名称，默认为函数名 |\n| title | str | 否 | 工具标题 |\n| description | str | 否 | 工具描述 |\n| annotations | Annotations | 否 | 工具注解 |\n\n函数必须包含类型提示，SDK 会自动验证参数类型。\n\n资料来源：[examples/snippets/servers/basic_tool.py:1-25]()\n\n## 定义资源（Resource）\n\n资源用于向客户端提供数据访问能力。\n\n### 资源类型\n\n| 类型 | 说明 | 用途 |\n|------|------|------|\n| FunctionResource | 函数资源 | 动态生成数据 |\n| FileResource | 文件资源 | 读取本地文件 |\n\n### 函数资源\n\n```python\nfrom mcp.server import MCPServer\nfrom mcp.server.resources import FunctionResource\n\ndef read_config() -> str:\n \"\"\"读取配置数据\"\"\"\n return '{\"debug\": true, \"version\": \"1.0\"}'\n\nserver = MCPServer(name=\"config-server\")\nserver.add_resource(\n FunctionResource.from_function(\n fn=read_config,\n uri=\"config://app\",\n name=\"app_config\",\n title=\"应用配置\",\n description=\"返回当前应用配置\",\n )\n)\n```\n\n### 文件资源\n\n```python\nfrom mcp.server.resources import FileResource\nfrom pathlib import Path\n\nserver.add_resource(\n FileResource(\n path=Path(\"/etc/app/config.json\"),\n name=\"config_file\",\n uri=\"file:///etc/app/config.json\",\n mime_type=\"application/json\",\n )\n)\n```\n\n| FileResource 字段 | 类型 | 说明 |\n|-------------------|------|------|\n| path | Path | 文件路径（必须为绝对路径） |\n| is_binary | bool | 是否以二进制模式读取 |\n| mime_type | str | MIME 类型 |\n\n资料来源：[examples/snippets/servers/basic_resource.py:1-45]()\n\n## 定义提示（Prompt）\n\n提示模板用于生成可复用的对话片段。\n\n```python\nfrom mcp.server import MCPServer\nfrom mcp.server.prompts import Prompt\n\nserver = MCPServer(name=\"prompt-server\")\n\nserver.add_prompt(\n Prompt(\n name=\"code_review\",\n description=\"代码审查提示\",\n arguments=[\n PromptArgument(\n name=\"language\",\n description=\"编程语言\",\n required=True,\n ),\n PromptArgument(\n name=\"code\",\n description=\"待审查代码\",\n required=True,\n ),\n ],\n )\n)\n```\n\n| PromptArgument 字段 | 类型 | 说明 |\n|---------------------|------|------|\n| name | str | 参数名称 |\n| description | str | 参数描述 |\n| required | bool | 是否必填 |\n\n资料来源：[examples/snippets/servers/basic_prompt.py:1-30]()\n\n## 读取资源\n\n### read_resource 方法\n\n```python\nasync def handle_resource_read(server: MCPServer):\n # 使用 URI 读取资源\n contents = await server.read_resource(\"config://app\")\n for content in contents:\n print(content.content)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| uri | AnyUrl \\| str | 资源标识符 |\n| context | Context | 请求上下文 |\n\n异常处理：未知资源返回 `ResourceError`，读取失败时异常被捕获并记录日志。\n\n资料来源：[src/mcp/server/mcpserver/server.py:45-70]()\n\n## 启动服务器\n\n### 运行服务器\n\n```python\nimport uvicorn\n\nif __name__ == \"__main__\":\n uvicorn.run(\n \"my_server:app\",\n host=\"0.0.0.0\",\n port=8000,\n reload=True,\n )\n```\n\n### 命令行启动\n\n```bash\n# 方式一：直接运行模块\nuv run python -m my_server\n\n# 方式二：使用 uvicorn\nuv run uvicorn my_server:app --host 0.0.0.0 --port 8000\n```\n\n### 配置传输方式\n\nMCP 支持多种传输协议：\n\n| 传输类型 | 说明 | 使用场景 |\n|----------|------|----------|\n| streamable-http | 流式 HTTP | 推荐默认选项 |\n| sse | Server-Sent Events | 需要长连接的场景 |\n\n```bash\n# 启动支持 OAuth 的流式 HTTP 服务器\nMCP_TRANSPORT=streamable-http MCP_OAUTH_STRICT=true uv run mcp-my-server\n```\n\n## 项目结构示例\n\n```\nmcp_project/\n├── pyproject.toml\n├── src/\n│ └── my_server/\n│ ├── __init__.py\n│ ├── server.py # 服务器定义\n│ ├── tools.py # 工具实现\n│ ├── resources.py # 资源定义\n│ └── prompts.py # 提示定义\n└── uv.lock\n```\n\n## 常见工作流程\n\n```mermaid\ngraph LR\n A[定义工具] --> B[定义资源]\n B --> C[定义提示]\n C --> D[创建 MCPServer 实例]\n D --> E[注册组件]\n E --> F[启动服务]\n F --> G[客户端连接]\n G --> H[调用工具/访问资源]\n```\n\n## 下一步\n\n- 阅读 [examples/servers/](examples/servers/) 目录下的完整示例\n- 了解 [认证与授权](examples/servers/simple-auth/README.md) 功能\n- 探索 [实验性功能](examples/servers/simple-task/README.md) 如任务支持\n\n---\n\n\n\n## 系统架构与核心组件\n\n### 相关页面\n\n相关主题：[传输协议实现](#page-transports), [上下文与会话管理](#page-context-session)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n- [src/mcp/server/session.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/session.py)\n- [src/mcp/client/session.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/session.py)\n- [src/mcp/shared/session.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/session.py)\n- [src/mcp/shared/message.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/message.py)\n- [src/mcp/types/_types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types/_types.py)\n- [src/mcp/types/jsonrpc.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types/jsonrpc.py)\n- [src/mcp/server/mcpserver/resources/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n- [src/mcp/server/auth/routes.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/auth/routes.py)\n- [src/mcp/server/experimental/task_context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/experimental/task_context.py)\n \n\n# 系统架构与核心组件\n\nModel Context Protocol (MCP) Python SDK 是一个用于构建 Model Context Protocol 客户端和服务器的框架。MCP 是一种标准化协议，使 AI 模型能够与外部数据源和工具进行交互。本文详细介绍 MCP SDK 的系统架构和核心组件。\n\n## 1. 架构概述\n\nMCP 采用客户端-服务器架构，支持多种传输协议（stdio、streamable-http）。协议基于 JSON-RPC 2.0 规范实现双向通信。\n\n```mermaid\ngraph TD\n subgraph 客户端层\n Client[Client 客户端]\n ClientSession[ClientSession 客户端会话]\n end\n \n subgraph 传输层\n Stdio[Stdio 传输]\n Http[Streamable HTTP 传输]\n end\n \n subgraph 服务器层\n Server[Server 服务器]\n MCPServer[MCPServer MCP 服务器]\n ServerSession[ServerSession 服务端会话]\n end\n \n subgraph 核心服务\n ResourceManager[ResourceManager 资源管理]\n PromptManager[PromptManager 提示管理]\n ToolHandler[ToolHandler 工具处理]\n Auth[AuthModule 认证模块]\n end\n \n Client --> ClientSession\n ClientSession <-->|JSON-RPC| Stdio\n ClientSession <-->|JSON-RPC| Http\n Stdio <--> Server\n Http <--> Server\n Server --> ServerSession\n ServerSession --> MCPServer\n MCPServer --> ResourceManager\n MCPServer --> PromptManager\n MCPServer --> ToolHandler\n MCPServer --> Auth\n```\n\n## 2. 核心组件关系\n\n### 2.1 组件层次结构\n\n```mermaid\ngraph TD\n subgraph 高层API\n MCPServer[MCP Server]\n Client[Client]\n end\n \n subgraph 会话层\n ClientSession[ClientSession]\n ServerSession[ServerSession]\n SharedSession[SharedSession]\n end\n \n subgraph 消息层\n MessageHandler[MessageHandler]\n JSONRPCHandler[JSONRPCHandler]\n end\n \n subgraph 传输层\n StdioTransport[StdioTransport]\n StreamableHttpTransport[StreamableHttpTransport]\n end\n \n MCPServer --> ServerSession\n Client --> ClientSession\n ClientSession --> SharedSession\n ServerSession --> SharedSession\n SharedSession --> MessageHandler\n MessageHandler --> JSONRPCHandler\n StdioTransport --> JSONRPCHandler\n StreamableHttpTransport --> JSONRPCHandler\n```\n\n### 2.2 组件职责表\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| `Client` | `src/mcp/client/client.py` | 管理客户端连接生命周期，处理服务端发现和传输协商 |\n| `ClientSession` | `src/mcp/client/session.py` | 客户端会话管理，处理请求/响应、notifications 和 call cancellation |\n| `ServerSession` | `src/mcp/server/session.py` | 服务端会话管理，处理请求路由和响应 |\n| `SharedSession` | `src/mcp/shared/session.py` | 会话基类，封装 JSON-RPC 消息处理逻辑 |\n| `MCPServer` | `src/mcp/server/mcpserver/server.py` | 高层服务器 API，整合资源、工具、提示管理 |\n| `ResourceManager` | `src/mcp/server/mcpserver/resources/` | 资源注册、模板管理和资源读取 |\n| `ToolHandler` | `内置于 MCPServer` | 工具注册、参数验证和执行 |\n\n资料来源：[src/mcp/shared/session.py:1-50](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/session.py)\n\n## 3. 会话层详解\n\n### 3.1 SharedSession 基类\n\n`SharedSession` 是客户端和服务端会话的共同基类，封装了 JSON-RPC 2.0 协议的通用逻辑。\n\n**核心职责：**\n- 消息队列管理\n- 请求-响应对应关系维护\n- Cancellation token 处理\n- 消息发送和接收\n\n```mermaid\ngraph LR\n subgraph SharedSession\n Queue[消息队列]\n Requests[待处理请求]\n Handlers[消息处理器]\n end\n \n subgraph 消息类型\n Request[Request 请求]\n Response[Response 响应]\n Notification[Notification 通知]\n end\n \n Queue --> Handlers\n Requests --> Handlers\n Request -->|等待响应| Requests\n Response -->|匹配请求| Requests\n Notification -->|无需响应| Queue\n```\n\n资料来源：[src/mcp/shared/session.py:50-150](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/session.py)\n\n### 3.2 客户端会话\n\n`ClientSession` 扩展了 SharedSession，添加了客户端特定的功能：\n\n```python\nclass ClientSession(SharedSession):\n # 核心方法\n async def initialize() -> InitializeResult\n async def list_tools() -> list[Tool]\n async def call_tool(name: str, arguments: dict) -> CallToolResult\n async def list_resources() -> list[Resource]\n async def list_resource_templates() -> list[ResourceTemplate]\n async def read_resource(uri: str | AnyUrl) -> ReadResourceResult\n async def list_prompts() -> list[Prompt]\n async def get_prompt(name: str, arguments: dict) -> GetPromptResult\n```\n\n**客户端初始化流程：**\n\n```mermaid\nsequenceDiagram\n participant Client\n participant ClientSession\n participant Server\n \n Client->>ClientSession: 创建会话\n ClientSession->>Server: 发送 initialize 请求\n Server->>ServerSession: 处理初始化\n ServerSession-->>ClientSession: 返回 InitializeResult\n ClientSession->>Client: 通知初始化完成\n Client->>ClientSession: 发送已接收通知\n ClientSession->>Server: 发送 notifications/initialized\n```\n\n资料来源：[src/mcp/client/session.py:100-200](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/session.py)\n\n### 3.3 服务端会话\n\n`ServerSession` 负责处理来自客户端的请求和调用服务端处理器。\n\n```python\nclass ServerSession(SharedSession):\n # 核心回调\n on_list_tools: Optional[Callback[...]]\n on_call_tool: Optional[Callback[...]]\n on_list_resources: Optional[Callback[...]]\n on_read_resource: Optional[Callback[...]]\n on_list_resource_templates: Optional[Callback[...]]\n on_list_prompts: Optional[Callback[...]]\n on_get_prompt: Optional[Callback[...]]\n```\n\n资料来源：[src/mcp/server/session.py:50-120](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/session.py)\n\n## 4. 消息协议\n\n### 4.1 JSON-RPC 2.0 实现\n\nMCP 基于 JSON-RPC 2.0 规范，定义了三类消息：\n\n| 消息类型 | 描述 | 必须包含字段 |\n|---------|------|-------------|\n| `JSONRPCRequest` | 请求消息，需要对方响应 | `jsonrpc`, `id`, `method` |\n| `JSONRPCResponse` | 响应消息 | `jsonrpc`, `id`, `result` |\n| `JSONRPCError` | 错误响应 | `jsonrpc`, `id`, `error` |\n| `JSONRPCNotification` | 通知消息，无需响应 | `jsonrpc`, `method` |\n\n```python\nclass JSONRPCMessage(BaseModel):\n \"\"\"JSON-RPC 消息基类\"\"\"\n jsonrpc: Literal[\"2.0\"] = \"2.0\"\n\nclass JSONRPCRequest(JSONRPCMessage):\n \"\"\"带方法调用的请求\"\"\"\n id: RequestId\n method: str\n params: Optional[dict[str, Any]] = None\n\nclass JSONRPCResponse(JSONRPCMessage):\n \"\"\"成功响应\"\"\"\n id: Union[int, str]\n result: Any\n\nclass JSONRPCError(JSONRPCMessage):\n \"\"\"错误响应\"\"\"\n id: Union[int, str]\n error: ErrorData\n```\n\n资料来源：[src/mcp/types/jsonrpc.py:20-80](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types/jsonrpc.py)\n\n### 4.2 错误代码定义\n\n| 错误码 | 名称 | 用途 |\n|-------|------|------|\n| `-32700` | Parse Error | JSON 解析失败 |\n| `-32600` | Invalid Request | 无效的请求对象 |\n| `-32601` | Method Not Found | 方法不存在 |\n| `-32602` | Invalid Params | 无效的参数 |\n| `-32603` | Internal Error | 内部错误 |\n| `-32000` | Connection Closed | 连接已关闭 |\n| `-32001` | Request Timeout | 请求超时 |\n\n## 5. MCP Server 高级 API\n\n`MCPServer` 是构建 MCP 服务器的高层入口，封装了资源管理、工具处理、提示管理和认证功能。\n\n### 5.1 初始化参数\n\n```python\nclass MCPServer:\n def __init__(\n self,\n name: str = \"mcp-server\",\n version: str = \"1.0.0\",\n settings: ServerSettings | None = None,\n resources: list[Resource] | None = None,\n tools: list[Callable] | None = None,\n prompts: list[Prompt] | None = None,\n instructions: str | None = None,\n lifespan: LifespanContextManager | None = None,\n ) -> None:\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `name` | `str` | 服务器名称 |\n| `version` | `str` | 服务器版本 |\n| `settings` | `ServerSettings` | 服务器配置选项 |\n| `resources` | `list[Resource]` | 初始资源列表 |\n| `tools` | `list[Callable]` | 可调用工具列表 |\n| `prompts` | `list[Prompt]` | 预定义提示列表 |\n| `instructions` | `str` | 服务器使用说明 |\n| `lifespan` | `LifespanContextManager` | 生命周期管理器 |\n\n资料来源：[src/mcp/server/mcpserver/server.py:100-150](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n\n### 5.2 核心方法\n\n```python\nclass MCPServer:\n # 资源管理\n async def list_resources() -> list[MCPResource]\n async def list_resource_templates() -> list[MCPResourceTemplate]\n async def read_resource(uri: AnyUrl | str) -> Iterable[ReadResourceContents]\n \n # 工具管理\n def add_tool(\n fn: Callable[..., Any],\n name: str | None = None,\n title: str | None = None,\n description: str | None = None,\n annotations: Annotations | None = None,\n ) -> None:\n \n # 提示管理\n def add_prompt(prompt: Prompt) -> None\n async def list_prompts() -> list[MCPPrompt]\n async def get_prompt(name: str, arguments: dict | None) -> MCPPrompt\n \n # 生命周期\n async def run_async()\n def streamable_http_app() -> ASGIApp\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py:200-300](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n\n## 6. 资源系统\n\n### 6.1 资源类型\n\nMCP 支持两种主要资源类型：\n\n| 类型 | 文件路径 | 描述 |\n|------|----------|------|\n| `FunctionResource` | `resources/types.py` | 从函数动态生成的资源 |\n| `FileResource` | `resources/types.py` | 读取本地文件的资源 |\n\n```python\nclass FunctionResource(Resource):\n \"\"\"从函数动态生成的资源\"\"\"\n uri: AnyUrl\n name: str\n title: Optional[str] = None\n description: Optional[str] = None\n mime_type: str = \"text/plain\"\n fn: Callable[..., Any] # 实际读取函数\n\nclass FileResource(Resource):\n \"\"\"读取本地文件的资源\"\"\"\n path: Path # 必须是绝对路径\n is_binary: bool = False # 是否二进制读取\n mime_type: str = \"text/plain\"\n```\n\n资料来源：[src/mcp/server/mcpserver/resources/types.py:50-100](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n\n### 6.2 资源读取流程\n\n```mermaid\ngraph TD\n Client[Client] -->|read_resource| ServerSession\n ServerSession -->|路由| MCPServer\n MCPServer -->|获取资源| ResourceManager\n ResourceManager -->|验证URI| URI解析\n URI解析 -->|查找资源| ResourceRegistry\n ResourceRegistry -->|返回| Resource\n Resource -->|调用read方法| FunctionResource\n FunctionResource -->|执行函数| ReadFunction\n ReadFunction -->|返回内容| ReadResourceContents\n```\n\n## 7. 认证系统\n\n### 7.1 OAuth 2.0 支持\n\nMCP 支持 OAuth 2.0 认证流程，包括：\n\n- **授权码流程** (Authorization Code Flow)\n- **客户端凭证流程** (Client Credentials Flow)\n- **令牌刷新** (Token Refresh)\n- **令牌撤销** (Token Revocation)\n\n```mermaid\ngraph LR\n subgraph 认证流程\n Client -->|1. 授权请求| AuthServer\n AuthServer -->|2. 授权码| Client\n Client -->|3. 令牌请求| AuthServer\n AuthServer -->|4. 访问令牌| Client\n Client -->|5. 受保护资源| ResourceServer\n ResourceServer -->|6. 资源| Client\n end\n \n subgraph 组件\n AuthServer[授权服务器]\n ResourceServer[资源服务器]\n end\n```\n\n资料来源：[src/mcp/server/auth/routes.py:50-150](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/auth/routes.py)\n\n### 7.2 认证配置\n\n```python\nclass AuthServerProvider(Protocol):\n \"\"\"认证服务器提供者协议\"\"\"\n async def get_auth_server_metadata(self, issuer_url: AnyHttpUrl) -> OAuthServerMetadata: ...\n async def create_authorization_url(self, ...) -> tuple[str, str]: ... # url, state\n async def handle_authorization_callback(self, ...) -> Tokens: ...\n async def refresh_access_token(self, ...) -> Tokens: ...\n\nclass TokenVerifier(Protocol):\n \"\"\"令牌验证器协议\"\"\"\n async def verify(self, token: str) -> TokenMetadata: ...\n```\n\n### 7.3 受保护资源元数据\n\nRFC 9728 兼容的受保护资源元数据端点：\n\n```python\ndef build_resource_metadata_url(resource_server_url: AnyHttpUrl) -> AnyHttpUrl:\n \"\"\"\n 构建 RFC 9728 合规的受保护资源元数据 URL\n \n 在主机和资源路径之间插入 /.well-known/oauth-protected-resource\n 例如: https://example.com/mcp -> https://example.com/.well-known/oauth-protected-resource/mcp\n \"\"\"\n```\n\n## 8. 交互式任务\n\n### 8.1 Elicitation 与 Sampling\n\nMCP 支持服务端向客户端发起交互请求：\n\n| 交互类型 | 方向 | 用途 |\n|---------|------|------|\n| `Elicitation` | Server → Client | 请求用户确认或输入 |\n| `Sampling` | Server → Client | 请求 LLM 补全 |\n\n```mermaid\ngraph TD\n subgraph Elicitation 流程\n Server -->|task.elicit()| Task\n Task -->|发送请求| Client\n Client -->|用户输入| ElicitResult\n ElicitResult -->|返回| Task\n Task -->|完成| Result\n end\n \n subgraph Sampling 流程\n Server2 -->|task.create_message()| Task2\n Task2 -->|发送请求| Client2\n Client2 -->|LLM响应| CreateMessageResult\n CreateMessageResult -->|返回| Task2\n Task2 -->|完成| Result2\n end\n```\n\n### 8.2 任务上下文\n\n```python\nclass TaskContext:\n \"\"\"任务上下文，用于处理交互式任务\"\"\"\n \n async def elicit(\n self,\n message: str,\n requested_schema: dict[str, Any],\n **kwargs,\n ) -> ElicitResult:\n \"\"\"发送 elicitation 请求给客户端\"\"\"\n \n async def create_message(\n self,\n messages: list[CreateMessageRequestParam],\n **kwargs,\n ) -> CreateMessageResult:\n \"\"\"发送 sampling 请求给客户端的 LLM\"\"\"\n```\n\n资料来源：[src/mcp/server/experimental/task_context.py:100-200](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/experimental/task_context.py)\n\n## 9. 传输层\n\n### 9.1 Stdio 传输\n\n适用于本地进程间通信，通过标准输入/输出流传输 JSON-RPC 消息。\n\n```python\nfrom mcp.server.stdio import stdio_server\n\nasync with stdio_server() as streams:\n await app.run(streams[0], streams[1], app.create_initialization_options())\n```\n\n### 9.2 Streamable HTTP 传输\n\n适用于网络通信，支持长轮询和 Server-Sent Events。\n\n```python\nfrom mcp.server import MCPServer\nimport uvicorn\n\napp = MCPServer(...)\nuvicorn.run(app.streamable_http_app(), host=\"127.0.0.1\", port=8000)\n```\n\n| 传输方式 | 适用场景 | 特点 |\n|---------|---------|------|\n| Stdio | 本地进程、CLI 工具 | 低延迟，简单可靠 |\n| Streamable HTTP | 网络服务、分布式部署 | 支持双向通信，可扩展 |\n\n## 10. 消息类型定义\n\n### 10.1 核心类型\n\n| 类型 | 描述 |\n|------|------|\n| `Tool` | 可调用工具的定义 |\n| `Resource` | 数据资源的定义 |\n| `ResourceTemplate` | 参数化资源模板 |\n| `Prompt` | 预定义提示模板 |\n| `SamplingMessage` | 采样消息 |\n| `Completion` | 自动补全建议 |\n\n```python\nclass Tool(BaseModel):\n name: str\n description: Optional[str] = None\n inputSchema: dict[str, Any]\n annotations: Optional[Annotations] = None\n\nclass Resource(BaseModel):\n uri: AnyUrl\n name: str\n description: Optional[str] = None\n mimeType: Optional[str] = None\n\nclass Prompt(BaseModel):\n name: str\n description: Optional[str] = None\n arguments: Optional[list[PromptArgument]] = None\n```\n\n资料来源：[src/mcp/types/_types.py:50-150](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types/_types.py)\n\n## 11. 服务器设置\n\n```python\nclass ServerSettings(BaseModel):\n \"\"\"服务器配置选项\"\"\"\n \n host: str | None = None\n port: int | None = None\n streamable_http_path: str | None = None\n streamable_http_session_timeout: float = 60.0\n streamable_http_max_session_duration: float | None = None\n streamable_http_session_keepalive: bool = True\n \n # 功能开关\n capabilities: ServerCapabilities = Field(default_factory=ServerCapabilities)\n \n # 重复检测\n warn_on_duplicate_tools: bool = True\n warn_on_duplicate_resources: bool = True\n warn_on_duplicate_prompts: bool = True\n \n # 认证配置\n auth: AuthSettings | None = None\n \n # 生命周期\n lifespan: LifespanContextManager | None = None\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py:50-100](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n\n## 12. 总结\n\nMCP Python SDK 的架构设计遵循以下原则：\n\n1. **分层设计**：清晰的分层架构，从传输层到高层 API\n2. **协议标准化**：基于 JSON-RPC 2.0，确保互操作性\n3. **灵活性**：支持多种传输方式和认证机制\n4. **可扩展性**：通过回调和中间件支持自定义行为\n5. **类型安全**：全面的类型提示和 Pydantic 模型验证\n\n这套架构使得开发者能够快速构建支持外部数据和工具交互的 AI 应用服务器和客户端。\n\n---\n\n\n\n## 传输协议实现\n\n### 相关页面\n\n相关主题：[系统架构与核心组件](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/client/stdio.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/stdio.py)\n- [src/mcp/client/sse.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/sse.py)\n- [src/mcp/client/websocket.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/websocket.py)\n- [src/mcp/client/streamable_http.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/streamable_http.py)\n- [src/mcp/server/stdio.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/stdio.py)\n- [src/mcp/server/sse.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/sse.py)\n- [src/mcp/server/websocket.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/websocket.py)\n- [src/mcp/server/streamable_http.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/streamable_http.py)\n- [src/mcp/server/streamable_http_manager.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/streamable_http_manager.py)\n- [examples/snippets/servers/streamable_http_basic_mounting.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_http_basic_mounting.py)\n- [examples/snippets/servers/streamable_starlette_mount.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_starlette_mount.py)\n \n\n# 传输协议实现\n\n## 概述\n\nMCP (Model Context Protocol) Python SDK 支持多种传输协议实现，用于客户端与服务器之间的通信。这些传输层负责在进程间或网络间传递 MCP 协议消息，支持不同的部署场景和性能需求。\n\n## 支持的传输协议类型\n\n| 传输类型 | 客户端模块 | 服务器模块 | 典型用途 |\n|---------|-----------|-----------|---------|\n| stdio | `mcp.client.stdio` | `mcp.server.stdio` | 本地进程通信 |\n| Streamable HTTP | `mcp.client.streamable_http` | `mcp.server.streamable_http` | HTTP-based 远程通信 |\n| SSE | `mcp.client.sse` | `mcp.server.sse` | 服务端推送事件 |\n| WebSocket | `mcp.client.websocket` | `mcp.server.websocket` | 双向实时通信 |\n\n## 核心传输协议\n\n### Stdio 传输\n\nStdio 传输是最基础的进程间通信方式，适用于本地运行的 MCP 服务器。客户端通过标准输入/输出流与服务器通信，协议消息以 JSON 格式编码。\n\n```mermaid\ngraph LR\n A[Client Process] -->|stdin| B[Server Process]\n B -->|stdout| A\n```\n\n**客户端用法示例：**\n\n```python\nfrom mcp.client.stdio import stdio_client\nfrom mcp.client import ClientSession\n\nasync def main():\n async with stdio_client() as streams:\n async with ClientSession(*streams) as session:\n await session.initialize()\n # 使用 session 进行 RPC 调用\n```\n\n**服务器用法示例：**\n\n```python\nfrom mcp.server.stdio import stdio_server\n\nasync def main():\n async with stdio_server() as streams:\n await app.run(streams[0], streams[1], app.create_initialization_options())\n```\n\n资料来源：[src/mcp/client/stdio.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/stdio.py)，[src/mcp/server/stdio.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/stdio.py)\n\n### Streamable HTTP 传输\n\nStreamable HTTP 是为 Web 环境设计的传输协议，支持通过 HTTP 请求/响应流式传输 MCP 消息。该协议兼容 RESTful 架构，便于与现有 Web 基础设施集成。\n\n**协议特点：**\n\n- 支持分块传输编码 (Chunked Transfer Encoding)\n- 支持 Server-Sent Events 用于服务端推送\n- 与 Starlette、FastAPI 等 ASGI 框架兼容\n- 支持 SSE 作为服务端推送机制\n\n资料来源：[src/mcp/client/streamable_http.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/streamable_http.py)，[src/mcp/server/streamable_http.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/streamable_http.py)\n\n**服务器配置示例：**\n\n```python\nfrom mcp.server import Server\nfrom mcp.server.streamable_http import StreamableHTTPServerHandler\nimport uvicorn\n\napp = Server(\"my-mcp-server\")\n\nif __name__ == \"__main__\":\n uvicorn.run(\n app.streamable_http_app(),\n host=\"127.0.0.1\",\n port=8000\n )\n```\n\n资料来源：[examples/snippets/servers/streamable_http_basic_mounting.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_http_basic_mounting.py)\n\n### SSE 传输\n\nServer-Sent Events (SSE) 传输允许服务器主动向客户端推送消息，适用于需要服务器端实时通知的场景。\n\n```mermaid\ngraph LR\n A[HTTP Client] -->|POST /mcp| B[MCP Server]\n B -->|SSE Stream| A\n A -->|GET /sse| B\n```\n\n资料来源：[src/mcp/client/sse.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/sse.py)，[src/mcp/server/sse.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/sse.py)\n\n### WebSocket 传输\n\nWebSocket 传输提供全双工通信通道，适用于需要低延迟、双向实时交互的应用场景。\n\n**WebSocket 服务器配置：**\n\n```python\nfrom mcp.server.websocket import websocket_server\nimport uvicorn\n\nasync def main():\n async with websocket_server(app) as streams:\n await app.run(streams[0], streams[1], app.create_initialization_options())\n\nif __name__ == \"__main__\":\n uvicorn.run(main, host=\"127.0.0.1\", port=8000)\n```\n\n资料来源：[src/mcp/server/websocket.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/websocket.py)，[src/mcp/client/websocket.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/websocket.py)\n\n## Streamable HTTP 服务器管理\n\n`streamable_http_manager` 模块提供了高级的 HTTP 传输管理功能，包括会话管理、请求路由和生命周期管理。\n\n### 核心组件\n\n| 组件 | 职责 |\n|------|------|\n| `StreamableHTTPServerHandler` | 处理 HTTP 请求，解析 MCP 协议消息 |\n| `HTTPAuthorizationMiddleware` | 处理认证头和授权验证 |\n| `HTTPStreamManager` | 管理流式响应和 SSE 连接 |\n\n资料来源：[src/mcp/server/streamable_http_manager.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/streamable_http_manager.py)\n\n### 挂载到 ASGI 应用\n\nMCP HTTP 服务器可以挂载到现有的 ASGI 应用中：\n\n```python\nfrom starlette.applications import Starlette\nfrom starlette.routing import Route, Mount\nfrom mcp.server.streamable_http_manager import StreamableHTTPManager\n\nasync def app_scope(request):\n # MCP 服务器逻辑\n pass\n\nmcp_app = Starlette(\n routes=[\n Mount(\"/mcp\", app=app_scope),\n ]\n)\n```\n\n资料来源：[examples/snippets/servers/streamable_starlette_mount.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_starlette_mount.py)\n\n## 传输协议选择指南\n\n```mermaid\ngraph TD\n A[选择传输协议] --> B{部署场景}\n B -->|本地进程| C[Stdio]\n B -->|Web 服务| D[Streamable HTTP]\n B -->|实时推送| E[SSE]\n B -->|低延迟交互| F[WebSocket]\n \n C --> G[最简单、最可靠]\n D --> H[兼容性最佳]\n E --> I[单向实时通信]\n F --> J[全双工通信]\n```\n\n**选择建议：**\n\n| 场景 | 推荐协议 | 原因 |\n|------|---------|------|\n| Claude Desktop 集成 | Stdio | 原生支持，最稳定 |\n| Web 应用后端 | Streamable HTTP | 标准化 HTTP 接口 |\n| 实时监控面板 | SSE | 服务端推送能力强 |\n| 游戏/协作工具 | WebSocket | 最低延迟 |\n\n## 协议消息格式\n\n所有传输协议都使用相同的 JSON-RPC 2.0 消息格式：\n\n```json\n// 请求消息\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/list\",\n \"params\": {}\n}\n\n// 响应消息\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"tools\": [...]\n }\n}\n\n// 错误消息\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"error\": {\n \"code\": -32600,\n \"message\": \"Invalid Request\"\n }\n}\n```\n\n## 服务器示例对比\n\n### Stdio 模式\n\n```python\nfrom mcp.server import Server\nfrom mcp.server.stdio import stdio_server\n\napp = Server(\"example-server\")\n\nasync def main():\n async with stdio_server() as streams:\n await app.run(\n streams[0],\n streams[1],\n app.create_initialization_options()\n )\n```\n\n资料来源：[src/mcp/server/stdio.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/stdio.py)\n\n### HTTP 模式\n\n```python\nfrom mcp.server import Server\nfrom mcp.server.streamable_http import streamable_http_server\nimport uvicorn\n\napp = Server(\"example-server\")\n\n@click.command()\n@click.option(\"--port\", default=8000, help=\"Port to listen on\")\n@click.option(\n \"--transport\",\n type=click.Choice([\"stdio\", \"streamable-http\"]),\n default=\"stdio\",\n)\ndef main(port: int, transport: str) -> int:\n if transport == \"streamable-http\":\n uvicorn.run(\n app.streamable_http_app(),\n host=\"127.0.0.1\",\n port=port\n )\n else:\n # stdio 模式\n ...\n```\n\n资料来源：[examples/servers/simple-pagination/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-pagination/server.py)\n\n## 传输层安全性\n\nMCP SDK 的传输层本身不实现加密，安全性依赖于底层传输协议：\n\n| 传输类型 | 安全建议 |\n|---------|---------|\n| Stdio | 仅用于本地通信，使用文件系统权限控制 |\n| Streamable HTTP | 配合 HTTPS/TLS 使用，添加认证中间件 |\n| WebSocket | 使用 WSS (WebSocket Secure) |\n| SSE | 通过 HTTPS 提供服务 |\n\n## 常见问题\n\n### Q: Stdio 和 HTTP 传输可以同时使用吗？\n\n可以。服务器可以同时监听多种传输协议，通过不同的启动参数选择：\n\n```bash\n# Stdio 模式\npython server.py --transport stdio\n\n# HTTP 模式\npython server.py --transport streamable-http --port 8000\n```\n\n### Q: 如何调试传输层问题？\n\n1. 启用调试日志：`export MCP_LOG_LEVEL=debug`\n2. 使用 HTTP 抓包工具查看请求/响应\n3. 对于 stdio，使用 `script` 命令记录会话\n\n## 相关资源\n\n- [MCP 协议规范](https://modelcontextprotocol.io/specification)\n- [Python SDK 源码仓库](https://github.com/modelcontextprotocol/python-sdk)\n- [示例服务器集合](../servers/)\n\n---\n\n\n\n## FastMCP 服务器框架\n\n### 相关页面\n\n相关主题：[资源、资源模板、提示与工具](#page-resources-prompts-tools), [上下文与会话管理](#page-context-session)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n- [src/mcp/server/mcpserver/resources/base.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/base.py)\n- [src/mcp/server/mcpserver/resources/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n- [src/mcp/cli/cli.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/cli/cli.py)\n- [examples/snippets/servers/completion.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/completion.py)\n- [examples/servers/simple-pagination/mcp_simple_pagination/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-pagination/mcp_simple_pagination/server.py)\n- [examples/servers/simple-task-interactive/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-task-interactive/README.md)\n- [examples/servers/simple-task/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-task/README.md)\n- [examples/clients/simple-task-interactive-client/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/clients/simple-task-interactive-client/README.md)\n \n\n# FastMCP 服务器框架\n\nFastMCP 是 MCP (Model Context Protocol) Python SDK 中提供的高级服务器框架，旨在简化 MCP 服务器的开发流程。与底层 `Server` 类相比，FastMCP 提供了更简洁的 API 设计，让开发者能够以更少的代码量快速构建功能完整的 MCP 服务器。\n\n## 框架概述\n\n### 设计目标\n\nFastMCP 框架的核心设计理念是**简化**与**约定优于配置**。它将 MCP 协议中复杂的内部机制抽象化，为开发者提供直观的装饰器和上下文管理器，使服务器开发变得更加直观和高效。\n\n### 架构分层\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ FastMCP API 层 │\n│ (装饰器 @tool, @resource, @prompt, 生命周期管理) │\n├─────────────────────────────────────────────────────────┤\n│ Server 核心层 │\n│ (工具管理、资源管理、提示管理、认证) │\n├─────────────────────────────────────────────────────────┤\n│ 传输层 │\n│ (stdio, streamable-http, SSE) │\n├─────────────────────────────────────────────────────────┤\n│ MCP 协议层 │\n│ (JSON-RPC 消息处理、协议序列化) │\n└─────────────────────────────────────────────────────────┘\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py:1-150]()\n\n## 核心组件\n\n### 1. 服务器实例\n\nFastMCP 服务器通过 `FastMCP` 类进行初始化和配置。该类封装了底层的 `Server` 实例，并提供了便捷的方法来注册工具、资源和提示。\n\n**初始化参数：**\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `name` | `str` | 服务器名称 | `\"fastmcp\"` |\n| `title` | `str \\| None` | 服务器显示标题 | `None` |\n| `description` | `str \\| None` | 服务器描述 | `None` |\n| `version` | `str \\| None` | 服务器版本 | `None` |\n| `lifespan` | `Lifespan \\| None` | 生命周期上下文管理器 | `None` |\n\n资料来源：[src/mcp/server/mcpserver/server.py:80-120]()\n\n### 2. 工具系统 (Tools)\n\n工具是 MCP 服务器中最核心的交互组件。FastMCP 提供了 `@tool` 装饰器来简化工具注册过程。\n\n```python\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"my-server\")\n\n@mcp.tool()\nasync def get_weather(city: str) -> str:\n \"\"\"获取城市天气信息\"\"\"\n return f\"{city} 的天气是晴天\"\n```\n\n**工具装饰器参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `name` | `str \\| None` | 工具名称，默认使用函数名 |\n| `description` | `str \\| None` | 工具描述，来自函数 docstring |\n| `annotations` | `Annotations \\| None` | 工具注解（只读、幂等等） |\n\n资料来源：[src/mcp/server/fastmcp/tools/base.py](), [src/mcp/server/fastmcp/tools/tool_manager.py]()\n\n### 3. 资源系统 (Resources)\n\n资源用于向客户端暴露可读取的数据。FastMCP 支持两种类型的资源：\n\n#### 3.1 静态资源\n\n```python\n@mcp.resource(\"config://app\")\ndef get_config() -> str:\n \"\"\"返回应用配置\"\"\"\n return '{\"version\": \"1.0.0\"}'\n```\n\n#### 3.2 资源模板\n\n```python\n@mcp.resource(\"users://{user_id}/profile\")\nasync def get_user_profile(user_id: str) -> str:\n \"\"\"返回用户资料\"\"\"\n return f'{{\"id\": \"{user_id}\", \"name\": \"User {user_id}\"}}'\n```\n\n资料来源：[src/mcp/server/mcpserver/resources/base.py:1-50](), [src/mcp/server/mcpserver/resources/types.py]()\n\n### 4. 提示系统 (Prompts)\n\n提示用于定义可复用的 LLM 交互模板。\n\n```python\n@mcp.prompt()\ndef code_review_prompt(repo: str, pr: str) -> str:\n \"\"\"代码审查提示模板\"\"\"\n return f\"请审查仓库 {repo} 的 PR #{pr} 中的代码变更\"\n```\n\n资料来源：[src/mcp/server/fastmcp/prompts/base.py](), [src/mcp/server/fastmcp/prompts/manager.py]()\n\n## 上下文管理\n\n### Context 对象\n\n每个工具和资源函数都可以接收一个 `Context` 对象作为第一个参数，该对象提供了访问服务器功能的能力。\n\n```python\n@mcp.tool()\nasync def search_files(\n context: Context,\n pattern: str,\n path: str = \".\"\n) -> list[str]:\n # 访问资源管理器\n resources = await context.list_resources()\n \n # 创建子任务\n task = await context.create_task(\"another_tool\", {\"arg\": \"value\"})\n \n return results\n```\n\n资料来源：[src/mcp/server/fastmcp/context.py]()\n\n### 生命周期管理\n\nFastMCP 支持通过 `lifespan` 参数管理服务器启动和关闭时的资源。\n\n```python\nfrom contextlib import asynccontextmanager\nfrom mcp.server.fastmcp import FastMCP\n\n@asynccontextmanager\nasync def lifespan(server: FastMCP):\n # 启动时初始化资源\n await db.connect()\n await cache.initialize()\n \n yield\n \n # 关闭时清理资源\n await cache.close()\n await db.disconnect()\n\nmcp = FastMCP(\"my-server\", lifespan=lifespan)\n```\n\n资料来源：[examples/snippets/servers/lifespan_example.py](), [src/mcp/server/mcpserver/server.py:100-110]()\n\n## 异常处理\n\nFastMCP 定义了框架专用的异常类型，便于细粒度的错误处理。\n\n| 异常类型 | 说明 |\n|----------|------|\n| `ResourceError` | 资源访问错误 |\n| `ToolError` | 工具执行错误 |\n| `PromptError` | 提示处理错误 |\n| `ValidationError` | 参数验证错误 |\n\n资料来源：[src/mcp/server/fastmcp/exceptions.py]()\n\n## 运行方式\n\n### 标准输入输出模式 (Stdio)\n\n适用于命令行工具和 Claude Desktop 集成：\n\n```python\n# my_server.py\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"my-server\")\n\n@mcp.tool()\nasync def hello(name: str) -> str:\n return f\"Hello, {name}!\"\n\nif __name__ == \"__main__\":\n mcp.run()\n```\n\n运行命令：\n```bash\nmcp run my_server.py\n```\n\n资料来源：[examples/servers/simple-pagination/mcp_simple_pagination/server.py:40-60]()\n\n### HTTP 传输模式\n\n适用于 Web 环境，支持流式响应：\n\n```python\nimport uvicorn\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"my-server\")\n\n# ... 定义工具和资源 ...\n\nif __name__ == \"__main__\":\n uvicorn.run(mcp.streamable_http_app(), host=\"0.0.0.0\", port=8000)\n```\n\n资料来源：[examples/servers/simple-pagination/mcp_simple_pagination/server.py:45-55]()\n\n## 任务系统 (Experimental)\n\nFastMCP 支持实验性的异步任务功能，允许长时间运行的工具返回任务引用而非直接结果。\n\n```python\n@mcp.tool()\nasync def long_running_task(context: Context) -> str:\n # 创建任务\n task = await context.create_task()\n \n # 发送进度更新\n await task.send_progress(\"开始处理...\")\n \n # 模拟长时间操作\n await asyncio.sleep(2)\n \n # 完成任务\n return \"任务完成\"\n```\n\n使用 `call_tool_as_task` 方法调用：\n\n```python\nresult = await session.experimental.call_tool_as_task(\"long_running_task\", {})\ntask_id = result.task.task_id\n\n# 轮询任务状态\nfinal = await session.experimental.get_task_result(task_id, CallToolResult)\n```\n\n资料来源：[examples/servers/simple-task/README.md](), [examples/clients/simple-task-interactive-client/README.md]()\n\n## 高级功能\n\n### 资源订阅与通知\n\nFastMCP 支持资源变更通知机制，服务器可以主动推送更新给客户端：\n\n```python\n@mcp.resource(\"data://stream\")\nasync def streaming_data(context: Context):\n async for update in data_generator():\n # 发送资源更新通知\n await context.notify_resources_changed()\n yield update\n```\n\n### 交互式任务 (Elicitation)\n\n服务器可以请求用户输入确认：\n\n```python\n@mcp.tool()\nasync def confirm_delete(context: Context, filename: str) -> str:\n # 请求用户确认\n result = await context.elicit(\n message=f\"确认删除 {filename}?\",\n actions=[{\"label\": \"确认\", \"value\": \"yes\"}, {\"label\": \"取消\", \"value\": \"no\"}]\n )\n \n if result.action == \"accept\":\n return f\"已删除 {filename}\"\n return \"操作已取消\"\n```\n\n资料来源：[examples/servers/simple-task-interactive/README.md]()\n\n### 采样 (Sampling)\n\n服务器可以请求 LLM 生成内容：\n\n```python\n@mcp.tool()\nasync def generate_text(context: Context, topic: str) -> str:\n result = await context.sample(\n prompt=f\"写一首关于 {topic} 的诗\",\n system=\"你是一位诗人\"\n )\n return result.content\n```\n\n资料来源：[examples/clients/simple-task-interactive-client/README.md]()\n\n## 与底层 Server 类的关系\n\nFastMCP 是对底层 `Server` 类的高级封装。两者的主要区别：\n\n| 特性 | `Server` | `FastMCP` |\n|------|----------|-----------|\n| API 复杂度 | 高 | 低 |\n| 代码量 | 较多 | 简洁 |\n| 灵活性 | 高 | 中等 |\n| 装饰器支持 | 无 | 有 |\n| 适用场景 | 深度定制 | 快速开发 |\n\n资料来源：[src/mcp/server/mcpserver/server.py:80-150]()\n\n## 最佳实践\n\n### 1. 类型注解\n\n所有公共 API 必须包含类型注解：\n\n```python\n@mcp.tool()\nasync def process_data(context: Context, data: list[str], options: dict[str, Any] | None = None) -> dict[str, Any]:\n \"\"\"处理数据并返回结果\"\"\"\n ...\n```\n\n### 2. 错误处理\n\n使用框架定义的异常类型，并在文档中说明可能抛出的异常：\n\n```python\n@mcp.tool()\nasync def read_resource(context: Context, uri: str) -> str:\n \"\"\"读取资源内容\n \n Raises:\n ResourceError: 资源不存在或无法访问\n \"\"\"\n try:\n return await context.read_resource(uri)\n except Exception:\n logger.exception(f\"Error reading resource {uri}\")\n raise ResourceError(f\"Error reading resource {uri}\")\n```\n\n### 3. 资源管理\n\n在 `lifespan` 中正确管理外部资源连接：\n\n```python\n@asynccontextmanager\nasync def lifespan(server: FastMCP):\n # 使用 try/finally 确保清理\n connection = await create_connection()\n try:\n server._connection = connection\n yield\n finally:\n await connection.close()\n```\n\n资料来源：[AGENTS.md - Exception Handling]()\n\n---\n\n\n\n## 资源、资源模板、提示与工具\n\n### 相关页面\n\n相关主题：[FastMCP 服务器框架](#page-fastmcp)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/server/mcpserver/resources/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n- [src/mcp/server/mcpserver/resources/templates.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/templates.py)\n- [src/mcp/server/mcpserver/utilities/func_metadata.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/utilities/func_metadata.py)\n- [examples/snippets/servers/basic_tool.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_tool.py)\n- [examples/snippets/servers/basic_resource.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_resource.py)\n- [examples/snippets/servers/basic_prompt.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_prompt.py)\n- [examples/mcpserver/weather_structured.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/mcpserver/weather_structured.py)\n- [examples/servers/simple-prompt/mcp_simple_prompt/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-prompt/mcp_simple_prompt/server.py)\n \n\n# 资源、资源模板、提示与工具\n\n## 概述\n\nMCP SDK 提供了四类核心功能用于构建 MCP 服务器：**资源（Resources）**、**资源模板（Resource Templates）**、**提示（Prompts）** 和 **工具（Tools）**。这些功能使服务器能够向 LLM 客户端暴露数据、模板和可执行函数，从而实现丰富的工具调用和数据检索能力。\n\n---\n\n## 资源（Resources）\n\n### 定义与作用\n\n资源是 MCP 协议中用于向 LLM 客户端暴露数据的机制。资源可以是静态内容（如文件）或动态生成的内容（如函数返回值）。客户端可以通过 URI 来读取特定的资源内容。\n\n### 资源类型\n\nMCP SDK 支持两种主要的资源类型：\n\n| 类型 | 说明 | 适用场景 |\n|------|------|----------|\n| `FunctionResource` | 由函数动态生成内容 | API 响应、实时数据 |\n| `FileResource` | 读取本地文件内容 | 配置文件、文档、静态资源 |\n\n### FunctionResource\n\n`FunctionResource` 允许将函数作为资源暴露给客户端。服务器调用该函数并返回其结果作为资源内容。\n\n**创建方式：**\n\n```python\nfrom mcp.server.mcpserver.resources.types import FunctionResource\n\nresource = FunctionResource.from_function(\n fn=my_function,\n uri=\"myapp://data\",\n name=\"my_data\",\n title=\"我的数据\",\n description=\"获取应用程序数据\",\n mime_type=\"application/json\"\n)\n```\n\n**关键特性：**\n\n- 自动类型验证：`from_function` 方法内部使用 `validate_call` 验证函数参数 资料来源：[src/mcp/server/mcpserver/resources/types.py:40]()\n\n### FileResource\n\n`FileResource` 用于读取本地文件系统中的文件。路径必须为绝对路径。\n\n```python\nfrom mcp.server.mcpserver.resources.types import FileResource\nfrom pathlib import Path\n\nresource = FileResource(\n path=Path(\"/etc/app/config.json\"),\n name=\"config\",\n mime_type=\"application/json\"\n)\n```\n\n**路径验证：**\n\nFileResource 使用 Pydantic 验证器确保路径是绝对路径：\n\n```python\n@pydantic.field_validator(\"path\")\n@classmethod\ndef validate_absolute_path(cls, path: Path) -> Path:\n \"\"\"确保路径是绝对路径\"\"\"\n if not path.is_absolute():\n raise ValueError(\"Path must be absolute\")\n return path\n```\n\n资料来源：[src/mcp/server/mcpserver/resources/types.py:65-72]()\n\n### 注册资源到服务器\n\n资源通过装饰器或直接方法注册到服务器：\n\n```python\n@server.resource(\n uri=\"myapp://config\",\n name=\"config\",\n title=\"应用程序配置\",\n description=\"获取当前配置\"\n)\ndef get_config():\n return {\"setting\": \"value\"}\n```\n\n---\n\n## 资源模板（Resource Templates）\n\n### 概念\n\n资源模板是带有 URI 参数的资源，允许动态生成资源内容。它们使用 URI 模板语法（如 `github://repos/{owner}/{repo}`）来定义参数化的资源端点。\n\n### 工作原理\n\n```mermaid\ngraph TD\n A[客户端请求] --> B[解析 URI 模板]\n B --> C{参数验证}\n C -->|通过| D[调用处理函数]\n C -->|失败| E[返回错误]\n D --> F[返回资源内容]\n```\n\n### URI 模板与参数验证\n\n资源模板通过比对 URI 参数和函数参数来确保正确性：\n\n```python\nuri_params = extract_uri_params(uri)\nfunc_params = extract_func_params(fn)\n\nif uri_params != func_params:\n raise ValueError(\n f\"Mismatch between URI parameters {uri_params} and function parameters {func_params}\"\n )\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py:95-100]()\n\n### 注册资源模板\n\n```python\n@server.list_resource_templates\nasync def handle_list_resource_templates():\n return [\n types.ResourceTemplate(\n uri_template=\"github://repos/{owner}/{repo}\",\n name=\"github_repo\",\n title=\"GitHub 仓库\",\n description=\"获取 GitHub 仓库信息\",\n arguments=[\n types.PromptArgument(\n name=\"owner\",\n description=\"仓库所有者\",\n required=True,\n ),\n types.PromptArgument(\n name=\"repo\",\n description=\"仓库名称\",\n required=True,\n ),\n ],\n )\n ]\n```\n\n### 模板资源示例\n\n在补全示例中，模板资源可以提供上下文感知的自动补全：\n\n```python\n# 基于 GitHub 资源模板的补全示例\nif isinstance(ref, ResourceTemplateReference):\n if ref.uri == \"github://repos/{owner}/{repo}\" and argument.name == \"repo\":\n if context and context.arguments.get(\"owner\") == \"modelcontextprotocol\":\n repos = [\"python-sdk\", \"typescript-sdk\", \"specification\"]\n return Completion(values=repos, has_more=False)\n```\n\n资料来源：[examples/snippets/servers/completion.py:10-18]()\n\n---\n\n## 提示（Prompts）\n\n### 定义\n\n提示是预定义的模板，可包含消息和参数。它们允许服务器定义可重用的提示模式，客户端可以根据需要调用。\n\n### 提示结构\n\n```mermaid\ngraph LR\n A[Prompt 定义] --> B[名称和描述]\n A --> C[参数列表]\n A --> D[消息模板]\n C --> C1[必需参数]\n C --> C2[可选参数]\n D --> D1[角色]\n D --> D2[内容]\n```\n\n### 提示注册\n\n使用装饰器方式注册提示：\n\n```python\n@server.prompt(\n name=\"simple\",\n title=\"简单提示\",\n description=\"一个基础提示示例\"\n)\ndef simple_prompt(context: str = None, topic: str = None):\n return {\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": {\n \"type\": \"text\",\n \"text\": f\"请帮我{context or ''}关于{topic or '通用'}的内容\"\n }\n }\n ]\n }\n```\n\n资料来源：[examples/snippets/servers/basic_prompt.py:8-30]()\n\n### 提示处理器\n\n对于更复杂的提示逻辑，可以使用处理器函数：\n\n```python\nasync def handle_list_prompts() -> list[types.ListPromptsResult]:\n return [\n types.ListPromptsResult(\n name=\"simple\",\n description=\"一个简单提示\",\n arguments=[\n types.PromptArgument(\n name=\"context\",\n description=\"额外上下文\",\n required=False,\n ),\n types.PromptArgument(\n name=\"topic\",\n description=\"关注的主题\",\n required=False,\n ),\n ],\n )\n ]\n\nasync def handle_get_prompt(\n ctx: ServerRequestContext,\n params: types.GetPromptRequestParams\n) -> types.GetPromptResult:\n if params.name != \"simple\":\n raise ValueError(f\"Unknown prompt: {params.name}\")\n\n arguments = params.arguments or {}\n return types.GetPromptResult(\n messages=create_messages(\n context=arguments.get(\"context\"),\n topic=arguments.get(\"topic\")\n ),\n description=\"一个带有可选参数的简单提示\",\n )\n```\n\n资料来源：[examples/servers/simple-prompt/mcp_simple_prompt/server.py:28-58]()\n\n### 使用 Prompt 类\n\n也可以直接实例化 Prompt 类：\n\n```python\nfrom mcp.types import Prompt\n\nprompt = Prompt(\n name=\"my_prompt\",\n description=\"我的提示\",\n arguments=[\n PromptArgument(\n name=\"param1\",\n description=\"参数说明\",\n required=True\n )\n ]\n)\n\nserver.add_prompt(prompt)\n```\n\n---\n\n## 工具（Tools）\n\n### 概述\n\n工具是服务器暴露给 LLM 客户端的可执行函数。客户端可以调用工具来执行服务器上的操作。\n\n### 工具注册\n\n使用 `@server.tool()` 装饰器注册工具：\n\n```python\n@server.tool(\n name=\"get_weather\",\n description=\"获取指定城市的天气信息\",\n)\nasync def get_weather(city: str, country: str | None = None) -> str:\n \"\"\"获取天气信息\"\"\"\n return f\"城市 {city} 的天气是晴天\"\n```\n\n资料来源：[examples/snippets/servers/basic_tool.py:1-12]()\n\n### 工具方法\n\n#### add_tool()\n\n直接方法添加工具：\n\n```python\nserver.add_tool(\n fn=my_function,\n name=\"tool_name\",\n title=\"工具标题\",\n description=\"工具描述\",\n annotations={\"readOnlyHint\": True}\n)\n```\n\n#### tool() 装饰器\n\n装饰器方式添加工具，支持更多配置：\n\n```python\n@server.tool(\n name=\"custom_tool\",\n title=\"自定义工具\",\n description=\"带参数的工具\",\n annotations={\n \"readOnlyHint\": True,\n \"openWorldHint\": False\n }\n)\nasync def custom_tool(param1: str, param2: int = 10):\n return {\"result\": f\"处理了 {param1} 和 {param2}\"}\n```\n\n### 工具注解（Annotations）\n\n工具可以附带注解来提供额外元数据：\n\n| 注解 | 类型 | 说明 |\n|------|------|------|\n| `readOnlyHint` | bool | 指示工具是否只读 |\n| `openWorldHint` | bool | 指示工具是否访问外部世界 |\n| `idempotentHint` | bool | 指示工具是否幂等 |\n| `interactiveHint` | bool | 指示工具是否需要交互 |\n\n### 工具返回类型\n\n工具可以返回多种格式的内容：\n\n```python\n@server.tool()\nasync def structured_tool():\n \"\"\"返回结构化内容\"\"\"\n return {\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"文本内容\"\n },\n {\n \"type\": \"resource\",\n \"resource\": {\n \"uri\": \"myapp://data\",\n \"mimeType\": \"application/json\",\n \"text\": '{\"key\": \"value\"}'\n }\n }\n ],\n \"isError\": False\n }\n```\n\n资料来源：[examples/mcpserver/weather_structured.py:20-45]()\n\n### 函数元数据提取\n\n工具注册时会自动提取函数元数据：\n\n```python\nfn = validate_call(fn)\nfunc_name = name or fn.__name__\n```\n\n关键元数据包括：\n- **函数名称**：用于标识工具\n- **参数信息**：名称、类型、默认值、文档字符串\n- **返回类型注解**：用于文档和验证\n\n---\n\n## 完整示例\n\n### 集成资源、提示和工具\n\n```python\nfrom mcp.server import Server\nfrom mcp.types import Resource, Tool, Prompt\n\n# 创建服务器实例\napp = Server(\"my-mcp-server\")\n\n# 注册资源\n@app.resource(uri=\"myapp://config\", name=\"config\")\ndef get_config():\n return {\"version\": \"1.0\", \"debug\": True}\n\n# 注册资源模板\n@app.list_resource_templates\nasync def handle_list_templates():\n return [\n types.ResourceTemplate(\n uri_template=\"myapp://users/{user_id}\",\n name=\"user_profile\",\n description=\"获取用户资料\",\n arguments=[\n types.PromptArgument(name=\"user_id\", description=\"用户ID\", required=True)\n ],\n )\n ]\n\n# 注册提示\n@app.prompt(name=\"greet\", title=\"问候语\")\ndef greet_prompt(name: str):\n return {\n \"messages\": [\n {\"role\": \"user\", \"content\": {\"type\": \"text\", \"text\": f\"你好，{name}！\"}}\n ]\n }\n\n# 注册工具\n@app.tool(name=\"calculate\", description=\"执行计算\")\ndef calculate(a: int, b: int, operation: str = \"add\"):\n if operation == \"add\":\n return a + b\n return a - b\n\n# 运行服务器\nasync def main():\n from mcp.server.stdio import stdio_server\n async with stdio_server() as streams:\n await app.run(streams[0], streams[1], app.create_initialization_options())\n```\n\n---\n\n## 架构关系图\n\n```mermaid\ngraph TD\n subgraph MCP服务器\n A[Server 实例]\n \n subgraph 资源层\n B[Resources 资源]\n C[Resource Templates 资源模板]\n end\n \n subgraph 交互层\n D[Prompts 提示]\n E[Tools 工具]\n end\n end\n \n F[LLM 客户端] --> |读取资源| B\n F --> |读取模板| C\n F --> |调用提示| D\n F --> |执行工具| E\n \n B --> |内容| F\n C --> |动态内容| F\n D --> |消息| F\n E --> |结果| F\n \n G[函数] --> |FunctionResource| B\n H[文件] --> |FileResource| B\n```\n\n---\n\n## 最佳实践\n\n### 资源设计\n\n1. **使用有意义的 URI**：资源 URI 应清晰表达资源的用途\n2. **选择正确的 MIME 类型**：确保客户端正确解析资源内容\n3. **提供描述**：为每个资源添加清晰的描述\n\n### 提示设计\n\n1. **保持简洁**：提示应清晰、聚焦\n2. **提供默认值**：可选参数应有合理的默认值\n3. **文档完整**：说明每个参数的用途\n\n### 工具设计\n\n1. **幂等性**：优先设计幂等工具\n2. **错误处理**：使用适当的异常处理，返回有意义的错误信息\n3. **类型注解**：为所有参数和返回值提供类型注解\n4. **使用注解**：通过注解描述工具行为\n\n---\n\n## 错误处理\n\n### 资源错误\n\n```python\nasync def read_resource(self, uri: AnyUrl | str, context: Context | None = None):\n try:\n resource = await self._resource_manager.get_resource(uri, context)\n except ValueError as exc:\n raise ResourceError(f\"Unknown resource: {uri}\") from exc\n\n try:\n content = await resource.read()\n return [ReadResourceContents(content=content, mime_type=resource.mime_type)]\n except Exception as exc:\n logger.exception(f\"Error getting resource {uri}\")\n raise ResourceError(f\"Error reading resource {uri}\") from exc\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py:54-66]()\n\n### 关键原则\n\n- **捕获具体异常**：使用 `except (OSError, PermissionError)` 等具体异常类型\n- **使用 logger.exception()**：记录异常时不包含异常对象在消息中\n- **避免裸 except**：除非在顶级处理器中\n- **转换异常**：将内部异常转换为客户端可理解的错误\n\n---\n\n\n\n## 上下文与会话管理\n\n### 相关页面\n\n相关主题：[FastMCP 服务器框架](#page-fastmcp), [系统架构与核心组件](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/server/context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/context.py)\n- [src/mcp/client/context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/context.py)\n- [src/mcp/shared/_context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/_context.py)\n- [src/mcp/server/fastmcp/utilities/context_injection.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/utilities/context_injection.py)\n- [src/mcp/server/fastmcp/utilities/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/utilities/types.py)\n- [examples/snippets/servers/tool_progress.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/tool_progress.py)\n \n\n# 上下文与会话管理\n\n## 概述\n\n在 Model Context Protocol (MCP) SDK 中，**上下文（Context）** 和 **会话管理** 是连接服务器端与客户端、传递请求元数据、管理生命周期状态的核心机制。上下文对象在请求处理链中携带关键信息，使开发者能够在工具执行、资源访问、提示渲染等场景中访问请求级别的元数据和服务器状态。\n\n上下文管理系统的设计遵循以下原则：\n\n- **请求级别隔离**：每个请求都有独立的上下文实例\n- **类型安全**：通过泛型参数确保上下文类型的一致性\n- **懒加载初始化**：在需要时才创建完整的上下文对象\n- **与生命周期集成**：上下文与服务器的 lifespan 机制协同工作\n\n资料来源：[src/mcp/shared/_context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/_context.py)\n\n---\n\n## 架构设计\n\n### 上下文分层模型\n\nMCP SDK 的上下文系统采用分层架构，不同层次的上下文服务于不同的功能范围：\n\n```mermaid\ngraph TB\n subgraph \"服务端上下文\"\n S1[ServerContext]\n S2[RequestContext]\n S3[ToolContext]\n end\n \n subgraph \"客户端上下文\"\n C1[ClientContext]\n C2[SessionContext]\n end\n \n subgraph \"共享上下文\"\n SH[SharedContext]\n end\n \n S1 --> S2\n S2 --> S3\n C1 --> C2\n S1 -.->|共享基类| SH\n C1 -.->|共享基类| SH\n```\n\n### 核心组件表\n\n| 组件 | 文件位置 | 职责 |\n|------|---------|------|\n| `Context` | `src/mcp/shared/_context.py` | 共享上下文基类，提供通用上下文功能 |\n| `ServerContext` | `src/mcp/server/context.py` | 服务端上下文，包含服务器引用和请求信息 |\n| `ClientContext` | `src/mcp/client/context.py` | 客户端上下文，管理会话状态和请求追踪 |\n| `ContextInjector` | `src/mcp/server/fastmcp/utilities/context_injection.py` | 上下文注入工具，用于 FastMCP 简化开发 |\n| `ProgressToken` | `相关类型定义 | 支持进度回调和长时间运行任务 |\n\n资料来源：[src/mcp/shared/_context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/_context.py)、[src/mcp/server/context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/context.py)\n\n---\n\n## 服务端上下文\n\n### ServerContext 结构\n\n服务端上下文在 `src/mcp/server/context.py` 中定义，包含以下核心属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `mcp_server` | `MCPServer` | 对应的 MCP 服务器实例 |\n| `request_id` | `str \\| None` | 当前请求的唯一标识符 |\n| `session_id` | `str \\| None` | 客户端会话标识符 |\n| `client_info` | `ClientInfo \\| None` | 客户端信息（元数据） |\n| `capabilities` | `ServerCapabilities \\| None` | 客户端支持的能力列表 |\n\n### 上下文创建与管理\n\n在服务端请求处理中，上下文通过以下模式创建：\n\n```python\nasync def read_resource(\n self, uri: AnyUrl | str, context: Context[LifespanResultT, Any] | None = None\n) -> Iterable[ReadResourceContents]:\n \"\"\"通过 URI 读取资源。\"\"\"\n if context is None:\n context = Context(mcp_server=self)\n try:\n resource = await self._resource_manager.get_resource(uri, context)\n except ValueError as exc:\n raise ResourceError(f\"Unknown resource: {uri}\") from exc\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n\n### 生命周期集成\n\n上下文与服务器的 lifespan 机制深度集成，支持泛型类型参数 `LifespanResultT`：\n\n```python\nContext[LifespanResultT, Any]\n```\n\n这种设计允许：\n\n- 在上下文初始化阶段注入特定的生命周期数据\n- 在请求处理过程中访问生命周期状态\n- 类型安全的上下文传递\n\n---\n\n## 客户端上下文\n\n### ClientContext 结构\n\n客户端上下文管理会话状态和请求追踪：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `session` | `ClientSession` | 活跃的客户端会话 |\n| `request_id` | `str` | 当前请求的唯一标识符 |\n| `timeout` | `timedelta \\| None` | 请求超时配置 |\n\n### 会话管理流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Session as ClientSession\n participant Context as ClientContext\n participant Server as MCP Server\n \n Client->>Session: 建立连接\n Session->>Context: 创建上下文\n Context->>Server: 初始化请求\n Server-->>Context: 初始化响应\n Context-->>Session: 会话就绪\n Session-->>Client: 连接就绪\n \n loop 请求处理\n Client->>Context: 发起请求\n Context->>Server: 发送请求\n Server-->>Context: 返回结果\n Context-->>Client: 传递结果\n end\n```\n\n---\n\n## 上下文注入机制\n\n### ContextInjector 用法\n\nFastMCP 提供了 `ContextInjector` 工具类，用于在函数调用时自动注入上下文：\n\n```python\nfrom mcp.server.fastmcp.utilities.context_injection import ContextInjector\n\n# 定义注入器\ninjector = ContextInjector()\n\n# 在工具函数中使用\n@injector.inject\nasync def my_tool(ctx: Context, arg1: str, arg2: int):\n \"\"\"带上下文注入的工具函数。\"\"\"\n # 直接使用 ctx，无需手动传递\n await ctx.info(f\"Processing {arg1} with {arg2}\")\n```\n\n### 注入工作流程\n\n```mermaid\ngraph LR\n A[工具调用] --> B[ContextInjector]\n B --> C{检查上下文参数}\n C -->|已存在| D[使用现有上下文]\n C -->|不存在| E[创建新上下文]\n D --> F[执行业务逻辑]\n E --> F\n F --> G[返回结果]\n```\n\n资料来源：[src/mcp/server/fastmcp/utilities/context_injection.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/utilities/context_injection.py)\n\n---\n\n## 进度令牌与长时间运行任务\n\n### ProgressToken 支持\n\nMCP SDK 通过 `ProgressToken` 支持长时间运行任务的进度报告：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `token` | `str \\| NumberToken` | 进度令牌标识符 |\n| `progress` | `float \\| None` | 当前进度值（0-100） |\n| `total` | `float \\| None` | 任务总量 |\n\n### 工具进度示例\n\n```python\nasync def handle_call_tool(\n ctx: ServerRequestContext, params: types.CallToolRequestParams\n) -> types.CallToolResult:\n \"\"\"处理工具调用，支持进度报告。\"\"\"\n progress_token = ctx.progress_token\n \n if progress_token:\n await progress_token(\n progress=0,\n total=100,\n )\n \n # 模拟长时间任务\n for i in range(10):\n await progress_token(progress=(i + 1) * 10)\n await asyncio.sleep(0.1)\n \n return types.CallToolResult(\n content=[types.TextContent(type=\"text\", text=\"Task completed\")]\n )\n```\n\n资料来源：[examples/snippets/servers/tool_progress.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/tool_progress.py)\n\n### 进度报告时序图\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Server as MCP 服务器\n participant Tool as 工具函数\n \n Client->>Server: call_tool with progressToken\n Server->>Tool: 初始化任务\n Tool->>Tool: 步骤 1\n Tool->>Client: progress(25)\n Tool->>Tool: 步骤 2\n Tool->>Client: progress(50)\n Tool->>Tool: 步骤 3\n Tool->>Client: progress(75)\n Tool->>Tool: 步骤 4\n Tool->>Client: progress(100)\n Tool->>Client: 返回结果\n```\n\n---\n\n## 快速参考\n\n### 上下文获取模式\n\n| 场景 | 推荐方式 |\n|------|---------|\n| 服务端请求处理 | 通过函数参数接收 `Context` |\n| 资源读取 | `context = Context(mcp_server=self)` |\n| FastMCP 工具 | 使用 `@injector.inject` 装饰器 |\n| 客户端调用 | 通过 `ClientSession` 的上下文方法 |\n\n### 常见错误处理\n\n| 错误类型 | 处理方式 |\n|---------|---------|\n| `ValueError: Unknown resource` | 检查 URI 格式是否正确 |\n| `ResourceError` | 资源读取失败，查看日志详情 |\n| `Context not available` | 确保在正确的请求上下文中调用 |\n\n### 日志记录规范\n\n根据项目规范，异常处理必须使用 `logger.exception()`：\n\n```python\nexcept Exception as exc:\n logger.exception(f\"Error getting resource {uri}\")\n raise ResourceError(f\"Error reading resource {uri}\") from exc\n```\n\n资料来源：[AGENTS.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/AGENTS.md)\n\n---\n\n## 最佳实践\n\n1. **始终传递上下文**：在工具函数签名中包含 `Context` 参数，以便访问服务器状态和元数据\n\n2. **避免硬编码依赖**：使用上下文提供的接口而非直接引用全局状态\n\n3. **正确处理异步**：上下文操作可能涉及异步 I/O，确保在 async 函数中使用\n\n4. **利用进度报告**：对于耗时的工具调用，使用 `progress_token` 提供用户反馈\n\n5. **类型安全**：使用泛型参数确保上下文类型的编译时检查\n\n---\n\n## 相关资源\n\n- [MCP 协议规范](https://modelcontextprotocol.io/specification)\n- [FastMCP 文档](./fastmcp.md)\n- [服务器开发指南](./servers.md)\n- [客户端开发指南](./clients.md)\n\n---\n\n\n\n## 客户端开发指南\n\n### 相关页面\n\n相关主题：[客户端 OAuth 认证](#page-client-auth), [传输协议实现](#page-transports)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/client/client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/client.py)\n- [src/mcp/client/session.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/session.py)\n- [src/mcp/client/session_group.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/session_group.py)\n- [src/mcp/shared/response_router.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/response_router.py)\n- [examples/snippets/clients/completion_client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/completion_client.py)\n- [examples/snippets/clients/stdio_client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/stdio_client.py)\n- [examples/snippets/clients/parsing_tool_results.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/parsing_tool_results.py)\n \n\n# 客户端开发指南\n\n本指南详细介绍如何使用 Model Context Protocol (MCP) Python SDK 开发客户端应用程序。MCP 客户端负责连接到 MCP 服务器，发现服务器提供的功能（工具、资源、提示），并通过标准化的协议与服务器进行交互。\n\n## 核心概念\n\n### 客户端架构概述\n\nMCP 客户端采用分层架构设计，主要包含以下组件：\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| `Client` | 连接管理和生命周期控制 | `src/mcp/client/client.py` |\n| `ClientSession` | 会话状态管理和请求处理 | `src/mcp/client/session.py` |\n| `SessionGroup` | 多会话协调管理 | `src/mcp/client/session_group.py` |\n| `ResponseRouter` | 响应路由和请求-响应匹配 | `src/mcp/shared/response_router.py` |\n\n### 传输层支持\n\nMCP SDK 支持多种传输方式，客户端可根据场景选择合适的传输协议：\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B{传输方式选择}\n B --> C[stdio 传输]\n B --> D[streamable-http 传输]\n B --> E[SSE 传输]\n C --> F[标准输入输出通信]\n D --> G[HTTP 流式传输]\n E --> H[Server-Sent Events]\n```\n\n## 连接管理\n\n### 建立 stdio 连接\n\n标准输入输出传输适用于本地进程间通信，是最常用的连接方式之一。\n\n```python\n# 资料来源：examples/snippets/clients/stdio_client.py\nimport asyncio\nfrom mcp.client.stdio import stdio_client\nfrom mcp.client.client import Client\n\nasync def main():\n async with stdio_client() as (read, write):\n async with Client(\n read,\n write,\n client_protocol,\n asyncio.create_task\n ) as client:\n await client.initialize()\n # 使用客户端功能\n```\n\n### 建立 HTTP 连接\n\n对于需要远程访问的场景，可使用 streamable-http 传输方式：\n\n```python\n# 连接到远程 MCP 服务器\nfrom mcp.client.streamable_http import streamable_http_client\n\nasync def connect_to_remote():\n async with streamable_http_client(\n \"http://localhost:8000/mcp\",\n timeout=30\n ) as (read, write, get_next_message):\n # 处理连接\n```\n\n### 客户端初始化流程\n\n```mermaid\nsequenceDiagram\n participant 客户端 as MCP 客户端\n participant 服务器 as MCP 服务器\n \n 客户端->>服务器: 发送 Initialize 请求\n 客户端->>服务器: 包含协议版本和客户端能力\n \n 服务器-->>客户端: 返回服务器信息\n 服务器-->>客户端: 协议版本确认\n 服务器-->>客户端: 服务器能力集\n \n 客户端->>服务器: 发送 Initialized 通知\n Note over 客户端: 连接建立完成\n```\n\n初始化时客户端需要指定支持的协议版本和自身能力集，服务器确认后将返回其能力信息。\n\n## 会话管理\n\n### ClientSession 的核心职责\n\n`ClientSession` 类是客户端与服务器交互的核心抽象，负责管理会话状态和协调各类请求：\n\n```python\n# 资料来源：src/mcp/client/session.py\nclass ClientSession:\n \"\"\"MCP 客户端会话核心类\"\"\"\n \n async def initialize(self) -> InitializeResult:\n \"\"\"初始化与服务器的连接\"\"\"\n \n async def list_tools(self) -> list[Tool]:\n \"\"\"列出服务器提供的所有工具\"\"\"\n \n async def call_tool(\n self, \n name: str, \n arguments: dict[str, Any] | None = None\n ) -> CallToolResult:\n \"\"\"调用服务器上的工具\"\"\"\n \n async def list_resources(self) -> list[Resource]:\n \"\"\"列出服务器提供的资源\"\"\"\n \n async def read_resource(self, uri: AnyUrl | str) -> Iterable[ReadResourceContents]:\n \"\"\"读取指定资源的内容\"\"\"\n \n async def list_prompts(self) -> list[Prompt]:\n \"\"\"列出服务器提供的提示模板\"\"\"\n \n async def get_prompt(\n self, \n name: str, \n arguments: dict[str, Any] | None = None\n ) -> GetPromptResult:\n \"\"\"获取并渲染提示模板\"\"\"\n```\n\n### 调用工具\n\n工具调用是 MCP 协议最核心的功能之一，允许客户端请求服务器执行特定操作：\n\n```python\n# 资料来源：examples/snippets/clients/stdio_client.py\nasync def call_server_tool():\n result = await session.call_tool(\n \"get_time\",\n arguments={\"timezone\": \"UTC\"}\n )\n \n # 处理返回结果\n for content in result.content:\n if content.type == \"text\":\n print(f\"工具返回: {content.text}\")\n```\n\n### 解析工具返回结果\n\n工具调用可能返回多种类型的内容，客户端需要正确处理：\n\n```python\n# 资料来源：examples/snippets/clients/parsing_tool_results.py\nfrom mcp.types import TextContent, ImageContent, EmbeddedResource\n\ndef parse_tool_result(result):\n \"\"\"解析工具调用结果\"\"\"\n for content in result.content:\n # 处理文本内容\n if isinstance(content, TextContent):\n print(f\"文本: {content.text}\")\n \n # 处理图片内容\n elif isinstance(content, ImageContent):\n print(f\"图片 MIME 类型: {content.mimeType}\")\n # content.data 包含 base64 编码的图片数据\n \n # 处理嵌入资源\n elif isinstance(content, EmbeddedResource):\n print(f\"嵌入资源: {content.resource.uri}\")\n```\n\n### 资源管理\n\n#### 列出可用资源\n\n```python\nasync def list_available_resources():\n resources = await session.list_resources()\n for resource in resources:\n print(f\"资源: {resource.name}\")\n print(f\" URI: {resource.uri}\")\n print(f\" 描述: {resource.description}\")\n```\n\n#### 读取资源内容\n\n```python\nasync def read_resource_content(uri: str):\n contents = await session.read_resource(uri)\n for content in contents:\n print(f\"内容类型: {content.mimeType}\")\n print(f\"数据: {content.content}\")\n```\n\n### 提示模板\n\n服务器可以定义可复用的提示模板，客户端可以获取并使用这些模板：\n\n```python\n# 资料来源：examples/snippets/clients/completion_client.py\nasync def use_prompt_template():\n # 列出所有可用提示\n prompts = await session.list_prompts()\n \n # 获取特定提示\n result = await session.get_prompt(\n \"simple\",\n arguments={\"context\": \"额外上下文\", \"topic\": \"技术主题\"}\n )\n \n # result.messages 包含渲染后的消息列表\n for message in result.messages:\n print(f\"角色: {message.role}\")\n print(f\"内容: {message.content}\")\n```\n\n## 自动补全支持\n\nMCP 支持在客户端实现自动补全功能，提升用户体验：\n\n```python\n# 资料来源：examples/snippets/servers/completion.py\nfrom mcp.types import ResourceTemplateReference, Completion\n\nasync def request_completion(ref: ResourceTemplateReference, argument: str):\n \"\"\"请求服务器提供补全建议\"\"\"\n \n # 对于 GitHub 资源模板的特定参数提供补全\n if ref.uri == \"github://repos/{owner}/{repo}\":\n if argument == \"repo\":\n # 返回预定义的补全值\n return Completion(\n values=[\"python-sdk\", \"typescript-sdk\", \"specification\"],\n has_more=False\n )\n```\n\n## 响应路由机制\n\n`ResponseRouter` 负责管理异步请求与响应的匹配，确保请求能够正确路由到对应的处理程序：\n\n```mermaid\ngraph LR\n A[请求发送] --> B[RequestTracker]\n B --> C{匹配响应}\n C -->|找到匹配| D[触发回调]\n C -->|未找到| E[等待响应]\n D --> F[返回结果]\n E --> C\n```\n\n```python\n# 资料来源：src/mcp/shared/response_router.py\nclass ResponseRouter:\n \"\"\"响应路由器，管理请求-响应映射\"\"\"\n \n async def send_request(self, method: str, params: dict) -> Any:\n \"\"\"发送请求并等待响应\"\"\"\n \n def __aiter__(self):\n \"\"\"异步迭代器，用于接收传入的消息\"\"\"\n```\n\n## 多会话管理\n\n### SessionGroup 的使用\n\n当客户端需要同时管理多个服务器连接时，可使用 `SessionGroup` 进行统一管理：\n\n```python\n# 资料来源：src/mcp/client/session_group.py\nfrom mcp.client.session_group import SessionGroup\n\nasync def manage_multiple_sessions():\n async with SessionGroup() as group:\n # 添加多个会话\n session1 = await group.add_server(stdio_server())\n session2 = await group.add_server(http_server(\"http://server2/mcp\"))\n \n # 批量操作\n all_tools = await group.request(\n lambda s: s.list_tools(),\n is_error_ok=True\n )\n```\n\n### SessionGroup 主要方法\n\n| 方法 | 功能 | 源码位置 |\n|------|------|----------|\n| `add_server()` | 添加新服务器会话 | `src/mcp/client/session_group.py` |\n| `remove_session()` | 移除指定会话 | `src/mcp/client/session_group.py` |\n| `request()` | 向所有会话发送请求 | `src/mcp/client/session_group.py` |\n| `notify()` | 向所有会话发送通知 | `src/mcp/client/session_group.py` |\n\n## 错误处理\n\n### 异常处理规范\n\n根据项目开发规范，客户端代码应遵循以下异常处理原则：\n\n```python\n# 资料来源：AGENTS.md\nimport logging\n\nlogger = logging.getLogger(__name__)\n\ntry:\n result = await session.call_tool(\"tool_name\", {})\nexcept Exception as exc:\n # 使用 logger.exception() 而非 logger.error()\n logger.exception(\"工具调用失败\")\n # 不要在日志消息中包含异常详情\n```\n\n### 推荐实践\n\n| 场景 | 异常类型 | 处理方式 |\n|------|----------|----------|\n| JSON 解析 | `json.JSONDecodeError` | 捕获并返回有意义的错误信息 |\n| 网络错误 | `ConnectionError`, `TimeoutError` | 重试或降级处理 |\n| 资源不存在 | `ValueError` | 捕获并提示用户 |\n| 授权失败 | `PermissionError` | 清理会话并重新认证 |\n\n**禁止使用裸的 `except Exception:`** — 应始终捕获具体异常类型。\n\n## 认证集成\n\n### OAuth 认证流程\n\n对于需要认证的 MCP 服务器，客户端需要实现完整的 OAuth 流程：\n\n```python\n# 资料来源：examples/clients/simple-auth-client/mcp_simple_auth_client/main.py\nclass CallbackHandler(BaseHTTPRequestHandler):\n \"\"\"处理 OAuth 回调\"\"\"\n \n def do_GET(self):\n query_params = parse_qs(urlparse(self.path).query)\n \n if \"code\" in query_params and \"state\" in query_params:\n # 获取授权码\n self.callback_data[\"authorization_code\"] = query_params[\"code\"][0]\n self.callback_data[\"state\"] = query_params[\"state\"][0]\n self.send_response(200)\n \n elif \"error\" in query_params:\n # 处理错误\n self.callback_data[\"error\"] = query_params[\"error\"][0]\n self.send_response(400)\n```\n\n### 环境配置\n\n| 环境变量 | 描述 | 默认值 |\n|----------|------|--------|\n| `MCP_SERVER_PORT` | MCP 服务器端口 | `8000` |\n| `MCP_TRANSPORT_TYPE` | 传输类型 | `streamable-http` |\n| `MCP_CLIENT_METADATA_URL` | 客户端元数据地址 | `None` |\n\n## 完整示例\n\n以下是一个功能完整的 MCP 客户端实现示例：\n\n```python\n# 资料来源：examples/snippets/clients/stdio_client.py\nimport asyncio\nfrom mcp.client.stdio import stdio_client\nfrom mcp.client.client import Client\nfrom mcp.protocol import ClientProtocol\n\nasync def run():\n async with stdio_client() as (read, write):\n client_protocol = ClientProtocol(\n read,\n write,\n asyncio.create_task\n )\n \n async with Client(\n read,\n write,\n client_protocol,\n asyncio.create_task\n ) as client:\n session = client_session = await client.create_session()\n await session.initialize()\n \n # 列出并调用工具\n tools = await session.list_tools()\n print(f\"可用工具: {[t.name for t in tools]}\")\n \n # 调用工具并处理结果\n result = await session.call_tool(\"get_time\", {\"a\": 1, \"b\": 3})\n \n # 解析返回内容\n result_unstructured = result.content[0]\n if hasattr(result_unstructured, 'text'):\n print(f\"工具结果: {result_unstructured.text}\")\n\ndef main():\n asyncio.run(run())\n\nif __name__ == \"__main__\":\n main()\n```\n\n## 开发工作流\n\n### 本地开发设置\n\n```bash\n# 克隆仓库\ngit clone https://github.com/modelcontextprotocol/python-sdk.git\n\n# 安装依赖\nuv sync --frozen --all-extras --dev\n\n# 安装预提交钩子\nuv tool install pre-commit --with pre-commit-uv --force-reinstall\n\n# 运行测试\nuv run pytest\n\n# 类型检查\nuv run pyright\n\n# 代码格式化\nuv run ruff format .\nuv run ruff check . --fix\n```\n\n### 调试技巧\n\n1. **启用详细日志**：在开发环境中启用 `logging.DEBUG` 级别可查看完整的协议交互\n2. **使用 stdio 传输**：本地调试时优先使用 stdio 传输，便于观察输入输出\n3. **单元测试**：为客户端代码编写单元测试，确保异常处理路径覆盖\n\n## 最佳实践总结\n\n| 类别 | 建议 |\n|------|------|\n| 连接管理 | 使用上下文管理器自动处理连接生命周期 |\n| 错误处理 | 捕获具体异常类型，使用 `logger.exception()` |\n| 类型提示 | 所有公共 API 必须包含类型注解 |\n| 异步代码 | 使用 `anyio` 而非 `asyncio` 进行测试 |\n| 资源清理 | 确保所有资源在异常情况下也能正确释放 |\n\n通过遵循本指南中的模式和实践，开发者可以构建稳定、可靠的 MCP 客户端应用程序，充分利用 Model Context Protocol 提供的强大功能。\n\n---\n\n\n\n## 客户端 OAuth 认证\n\n### 相关页面\n\n相关主题：[客户端开发指南](#page-client-development)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/client/auth/oauth2.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/auth/oauth2.py)\n- [src/mcp/client/auth/exceptions.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/auth/exceptions.py)\n- [src/mcp/client/auth/extensions/client_credentials.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/auth/extensions/client_credentials.py)\n- [src/mcp/shared/auth.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/auth.py)\n- [src/mcp/shared/auth_utils.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/auth_utils.py)\n- [examples/snippets/clients/oauth_client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/oauth_client.py)\n \n\n# 客户端 OAuth 认证\n\n## 概述\n\nMCP Python SDK 的客户端 OAuth 认证模块为 MCP 客户端提供了完整的 OAuth 2.0 认证支持，包括授权码流程（Authorization Code Flow）和客户端凭证流程（Client Credentials Flow）。该模块基于 [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)、[RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)（PKCE）、[RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)（OAuth 授权服务器元数据）以及 [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)（受保护资源元数据）等标准规范实现。\n\n主要功能包括：\n\n- **动态客户端注册（DCR）**：自动向授权服务器注册客户端\n- **PKCE 支持**：增强授权码流程的安全性\n- **Token 管理**：自动刷新过期 Token\n- **元数据发现**：支持 RFC 8414 和 RFC 9728 规定的标准发现端点\n- **多认证方式**：支持 `client_secret_basic` 和 `client_secret_post`\n- **URL-based Client ID (CIMD)**：支持基于 URL 的客户端标识符\n\n资料来源：[src/mcp/client/auth/oauth2.py:1-50]()\n\n## 架构设计\n\n### 模块结构\n\n```\nsrc/mcp/client/auth/\n├── oauth2.py # 核心 OAuth2 实现\n├── exceptions.py # OAuth 异常定义\n├── utils.py # 工具函数\n└── extensions/\n └── client_credentials.py # 客户端凭证扩展\n\nsrc/mcp/shared/\n├── auth.py # 共享数据模型\n└── auth_utils.py # 共享工具函数\n```\n\n### 核心组件关系图\n\n```mermaid\ngraph TD\n subgraph \"客户端应用层\"\n A[MCP Client]\n B[OAuthClientProvider]\n end\n \n subgraph \"认证核心\"\n C[OAuthContext]\n D[TokenStorage]\n E[PKCEParameters]\n end\n \n subgraph \"认证扩展\"\n F[ClientCredentialsOAuthProvider]\n end\n \n subgraph \"共享模型\"\n G[OAuthClientMetadata]\n H[OAuthToken]\n I[OAuthMetadata]\n J[ProtectedResourceMetadata]\n end\n \n subgraph \"外部服务\"\n K[授权服务器]\n L[资源服务器]\n end\n \n A --> B\n B --> C\n B --> D\n B --> E\n F --> C\n G --> H\n I --> J\n B <--> K\n B <--> L\n```\n\n### OAuth 上下文数据流\n\n```mermaid\ngraph LR\n subgraph \"初始化阶段\"\n A1[server_url] --> C[OAuthContext]\n A2[client_metadata] --> C\n A3[storage] --> C\n end\n \n subgraph \"发现阶段\"\n C --> D1[发现受保护资源元数据]\n C --> D2[发现授权服务器元数据]\n D1 --> E1[protected_resource_metadata]\n D2 --> E2[oauth_metadata]\n end\n \n subgraph \"注册阶段\"\n C --> R1[动态客户端注册]\n R1 --> R2[client_info]\n end\n \n subgraph \"认证阶段\"\n R2 --> A1[授权请求]\n A1 --> T1[Token 交换]\n T1 --> T2[current_tokens]\n end\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:140-200]()\n\n## 核心数据模型\n\n### OAuthClientMetadata\n\n客户端元数据模型，用于动态客户端注册：\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `client_id` | `str` | 是 | 客户端标识符 |\n| `client_secret` | `str` | 否 | 客户端密钥 |\n| `redirect_uris` | `list[AnyUrl]` | 是 | 重定向 URI 列表 |\n| `grant_types` | `list[str]` | 否 | 支持的授权类型 |\n| `token_endpoint_auth_method` | `str` | 否 | Token 端点认证方法 |\n| `scope` | `str` | 否 | 请求的权限范围 |\n\n资料来源：[src/mcp/shared/auth.py:200-260]()\n\n### OAuthToken\n\nToken 数据模型：\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `access_token` | `str` | 是 | 访问令牌 |\n| `token_type` | `str` | 是 | Token 类型，通常为 \"Bearer\" |\n| `expires_at` | `float` | 是 | Token 过期时间戳 |\n| `refresh_token` | `str` | 否 | 刷新令牌 |\n| `expires_in` | `int` | 否 | Token 有效期（秒） |\n| `scope` | `str` | 否 | 授予的权限范围 |\n\n资料来源：[src/mcp/shared/auth.py:300-340]()\n\n### OAuthMetadata\n\n授权服务器元数据模型：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `issuer` | `str` | 授权服务器签发者标识 |\n| `authorization_endpoint` | `str` | 授权端点 URL |\n| `token_endpoint` | `str` | Token 端点 URL |\n| `registration_endpoint` | `str` | 客户端注册端点 |\n| `scopes_supported` | `list[str]` | 支持的权限范围 |\n| `response_types_supported` | `list[str]` | 支持的响应类型 |\n| `grant_types_supported` | `list[str]` | 支持的授权类型 |\n| `code_challenge_methods_supported` | `list[str]` | 支持的 PKCE 方法 |\n\n资料来源：[src/mcp/shared/auth.py:80-150]()\n\n### ProtectedResourceMetadata\n\n受保护资源元数据（RFC 9728）：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `resource` | `str` | 资源服务器标识符 |\n| `authorization_servers` | `list[str]` | 关联的授权服务器列表 |\n| `scopes_supported` | `list[str]` | 资源支持的范围 |\n| `bearer_methods_supported` | `list[str]` | 支持的 Bearer Token 方法 |\n\n资料来源：[src/mcp/shared/auth.py:400-450]()\n\n### OAuthContext\n\nOAuth 流程上下文数据类：\n\n```python\n@dataclass\nclass OAuthContext:\n server_url: str\n client_metadata: OAuthClientMetadata\n storage: TokenStorage\n redirect_handler: Callable[[str], Awaitable[None]] | None\n callback_handler: Callable[[], Awaitable[tuple[str, str | None]]] | None\n timeout: float = 300.0\n client_metadata_url: str | None = None\n \n # 元数据发现结果\n protected_resource_metadata: ProtectedResourceMetadata | None = None\n oauth_metadata: OAuthMetadata | None = None\n auth_server_url: str | None = None\n protocol_version: str | None = None\n \n # 客户端信息\n client_info: OAuthClientInformationFull | None = None\n \n # Token 管理\n current_tokens: OAuthToken | None = None\n token_expiry_time: float | None = None\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:140-185]()\n\n## Token 存储接口\n\n### TokenStorage Protocol\n\n开发者需要实现 `TokenStorage` 接口来持久化 Token：\n\n```python\nclass TokenStorage(Protocol):\n \"\"\"Token 存储接口\"\"\"\n \n async def get_tokens(self) -> OAuthToken | None:\n \"\"\"获取存储的 Token\"\"\"\n ...\n \n async def set_tokens(self, tokens: OAuthToken) -> None:\n \"\"\"存储 Token\"\"\"\n ...\n \n async def get_client_info(self) -> OAuthClientInformationFull | None:\n \"\"\"获取存储的客户端信息\"\"\"\n ...\n \n async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:\n \"\"\"存储客户端信息\"\"\"\n ...\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:100-130]()\n\n## 认证流程详解\n\n### 授权码流程（Authorization Code Flow）\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant AS as 授权服务器\n participant RS as 资源服务器\n\n Note over Client: 1. 元数据发现\n Client->>RS: GET /.well-known/oauth-protected-resource\n RS-->>Client: ProtectedResourceMetadata\n Client->>AS: GET /.well-known/oauth-authorization-server\n AS-->>Client: OAuthMetadata\n\n Note over Client: 2. 客户端注册\n Client->>AS: POST /register (DCR)\n AS-->>Client: client_id, client_secret\n\n Note over Client: 3. PKCE 准备\n Client->>Client: 生成 code_verifier\n Client->>Client: 生成 code_challenge = BASE64URL(SHA256(code_verifier))\n\n Note over Client: 4. 授权请求\n Client->>Client: 构建授权 URL\n Client->>Browser: 重定向到授权页面\n User->>Browser: 用户登录\n\n Note over Client: 5. 回调处理\n Browser->>Client: /callback?code=xxx&state=xxx\n Client->>AS: POST /token (code + code_verifier)\n AS-->>Client: access_token, refresh_token\n\n Note over Client: 6. 资源访问\n Client->>RS: MCP 请求 (Bearer token)\n RS->>AS: Token 内省 (可选)\n RS-->>Client: MCP 响应\n```\n\n#### 第一阶段：元数据发现\n\n```python\n# 发现受保护资源元数据\nprm_discovery_urls = build_protected_resource_metadata_discovery_urls(context.server_url)\nfor url in prm_discovery_urls:\n response = yield create_protected_resource_request(url)\n ok, prm = await handle_protected_resource_response(response)\n if ok and prm:\n context.protected_resource_metadata = prm\n break\n\n# 发现授权服务器元数据\nasm_discovery_urls = build_oauth_authorization_server_metadata_discovery_urls(\n context.auth_server_url, context.server_url\n)\nfor url in asm_discovery_urls:\n response = yield create_oauth_metadata_request(url)\n ok, asm = await handle_auth_metadata_response(response)\n if ok and asm:\n context.oauth_metadata = asm\n break\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:250-310]()\n\n#### 第二阶段：客户端注册\n\n支持两种客户端标识方式：\n\n**方式一：动态客户端注册（DCR）**\n\n```python\nregistration_request = create_client_registration_request(\n context.oauth_metadata,\n context.client_metadata,\n context.get_authorization_base_url(context.server_url),\n)\n# ... 发送注册请求\nclient_info = await handle_registration_response(response)\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:340-360]()\n\n**方式二：URL-based Client ID (CIMD)**\n\n当服务器支持 `client_id_metadata_document_supported` 时使用：\n\n```python\nif should_use_client_metadata_url(context.oauth_metadata, context.client_metadata_url):\n client_information = create_client_info_from_metadata_url(\n context.client_metadata_url,\n redirect_uris=context.client_metadata.redirect_uris,\n )\n```\n\n资料来源：[src/mcp/client/auth/utils.py:80-100]()\n\n#### 第三阶段：授权请求与 Token 交换\n\n```python\n# 生成 PKCE 参数\npkce = PKCEParameters()\n\n# 构建授权 URL\nauthorization_url = build_authorization_url(\n context.oauth_metadata.authorization_endpoint,\n client_id=context.client_info.client_id,\n redirect_uri=redirect_uri,\n scope=selected_scope,\n state=state,\n code_challenge=pkce.code_challenge,\n code_challenge_method=\"S256\",\n)\n\n# 打开浏览器进行授权\nawait context.redirect_handler(authorization_url)\n\n# 处理回调\ncode, state = await context.callback_handler()\n\n# 交换 Token\ntoken_request = create_token_request(\n context.oauth_metadata.token_endpoint,\n grant_type=\"authorization_code\",\n code=code,\n redirect_uri=redirect_uri,\n client_id=context.client_info.client_id,\n client_secret=context.client_info.client_secret,\n code_verifier=pkce.code_verifier,\n)\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:400-480]()\n\n### Token 自动刷新\n\n```mermaid\ngraph TD\n A[MCP 请求] --> B{Token 有效?}\n B -->|是| C[发送请求]\n B -->|否| D{有 Refresh Token?}\n D -->|有| E[刷新 Token]\n D -->|无| F[重新授权]\n E --> G{刷新成功?}\n G -->|是| H[存储新 Token]\n G -->|否| I[重新授权]\n H --> C\n F --> A\n I --> A\n```\n\n```python\nasync def _handle_token_refresh(self, context: OAuthContext) -> bool:\n \"\"\"处理 Token 刷新\"\"\"\n if not context.oauth_metadata or not context.current_tokens:\n return False\n \n refresh_token = context.current_tokens.refresh_token\n if not refresh_token:\n return False\n \n # 创建刷新请求\n token_request = create_token_request(\n context.oauth_metadata.token_endpoint,\n grant_type=\"refresh_token\",\n refresh_token=refresh_token,\n client_id=context.client_info.client_id,\n client_secret=context.client_info.client_secret,\n )\n \n # 发送请求并处理响应\n response = yield token_request\n token_response = await handle_token_response(response, context.current_tokens.scope)\n \n if token_response:\n context.current_tokens = token_response\n await context.storage.set_tokens(token_response)\n return True\n \n return False\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:550-600]()\n\n## PKCE 支持\n\n### PKCEParameters 数据类\n\n```python\nclass PKCEParameters(BaseModel):\n \"\"\"PKCE 参数\"\"\"\n \n code_verifier: str = Field(..., min_length=43, max_length=128)\n code_challenge: str\n code_challenge_method: Literal[\"S256\"] = \"S256\"\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:60-75]()\n\n### Code Verifier 与 Code Challenge 生成\n\n```mermaid\ngraph LR\n A[随机字符串
43-128 字符] --> B[Base64URL 编码]\n B --> C[code_verifier]\n C --> D[SHA256 哈希]\n D --> E[Base64URL 编码]\n E --> F[code_challenge]\n```\n\n## 客户端凭证流程\n\n对于服务端到服务端的认证场景，可以使用简化的客户端凭证流程：\n\n```mermaid\ngraph LR\n A[服务端] -->|client_id + client_secret| B[授权服务器]\n B -->|access_token| A\n A -->|Bearer Token| C[资源服务器]\n```\n\n### ClientCredentialsOAuthProvider\n\n```python\nfrom mcp.client.auth.extensions.client_credentials import ClientCredentialsOAuthProvider\n\n# 初始化\nprovider = ClientCredentialsOAuthProvider(\n server_url=\"http://localhost:8000/mcp\",\n storage=InMemoryTokenStorage(),\n client_id=\"my-service\",\n client_secret=\"secret\",\n scopes=\"tools read resources\",\n)\n\n# 使用 httpx.AsyncClient\nasync with httpx.AsyncClient(auth=provider) as client:\n response = await client.post(\"http://localhost:8000/mcp\", json=request_data)\n```\n\n资料来源：[src/mcp/client/auth/extensions/client_credentials.py:30-80]()\n\n## 异常处理\n\n### OAuthFlowError\n\n授权流程异常：\n\n```python\nclass OAuthFlowError(Exception):\n \"\"\"OAuth 流程错误\"\"\"\n \n error: OAuthErrorCode\n error_description: str | None = None\n```\n\n### OAuthTokenError\n\nToken 相关错误：\n\n```python\nclass OAuthTokenError(Exception):\n \"\"\"Token 处理错误\"\"\"\n \n error: OAuthErrorCode\n error_description: str | None = None\n```\n\n资料来源：[src/mcp/client/auth/exceptions.py:1-30]()\n\n## 使用示例\n\n### 完整授权码流程示例\n\n```python\nimport asyncio\nfrom httpx import AsyncClient\nfrom mcp.client.auth.oauth2 import OAuthClientProvider, OAuthClientMetadata\nfrom mcp.client.auth.in_memory_storage import InMemoryTokenStorage\n\nasync def main():\n # 1. 配置客户端元数据\n client_metadata = OAuthClientMetadata(\n redirect_uris=[\"http://localhost:8000/callback\"],\n grant_types=[\"authorization_code\", \"refresh_token\"],\n token_endpoint_auth_method=\"client_secret_post\",\n scope=\"tools read\",\n )\n \n # 2. 创建 Token 存储\n storage = InMemoryTokenStorage()\n \n # 3. 创建 OAuth 提供者\n oauth_provider = OAuthClientProvider(\n server_url=\"http://localhost:8000/mcp\",\n client_metadata=client_metadata,\n storage=storage,\n redirect_handler=lambda url: print(f\"打开浏览器: {url}\"),\n callback_handler=lambda: input(\"输入授权码: \").split(\",\"),\n )\n \n # 4. 使用 OAuth 认证\n async with AsyncClient(auth=oauth_provider) as client:\n response = await client.post(\n \"http://localhost:8000/mcp\",\n json={\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"id\": 1}\n )\n print(response.json())\n\nasyncio.run(main())\n```\n\n### 带资源验证的示例\n\n```python\nfrom mcp.shared.auth_utils import check_resource_allowed, resource_url_from_server_url\n\n# 验证请求的资源与配置的资源是否匹配\nallowed = check_resource_allowed(\n requested_resource=\"http://localhost:8001\",\n configured_resource=\"http://localhost:8001\"\n)\n\n# 从服务器 URL 提取资源 URL\nresource_url = resource_url_from_server_url(\"http://localhost:8001/mcp\")\n# 结果: \"http://localhost:8001\"\n```\n\n资料来源：[src/mcp/shared/auth_utils.py:50-100]()\n\n## 配置选项\n\n### OAuthClientProvider 初始化参数\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `server_url` | `str` | 是 | - | MCP 服务器 URL |\n| `client_metadata` | `OAuthClientMetadata` | 是 | - | OAuth 客户端元数据 |\n| `storage` | `TokenStorage` | 是 | - | Token 存储实现 |\n| `redirect_handler` | `Callable` | 否 | `None` | 授权重定向处理函数 |\n| `callback_handler` | `Callable` | 否 | `None` | 回调处理函数 |\n| `timeout` | `float` | 否 | `300.0` | OAuth 流程超时时间 |\n| `client_metadata_url` | `str` | 否 | `None` | URL-based Client ID |\n| `validate_resource_url` | `Callable` | 否 | `None` | 自定义资源 URL 验证 |\n\n### AuthSettings 配置\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `issuer_url` | `AnyHttpUrl` | 授权服务器 URL |\n| `resource_server_url` | `AnyHttpUrl` | 资源服务器 URL |\n| `service_documentation_url` | `AnyHttpUrl` | 服务文档 URL |\n| `client_registration_options` | `ClientRegistrationOptions` | 客户端注册选项 |\n| `revocation_options` | `RevocationOptions` | Token 撤销选项 |\n| `required_scopes` | `list[str]` | 必需的权限范围 |\n\n资料来源：[src/mcp/server/auth/settings.py:1-40]()\n\n## 安全考虑\n\n### PKCE 必要性\n\n对于公开客户端（如移动应用或单页应用），强烈建议使用 PKCE。SDK 默认使用 S256 方法进行 code challenge：\n\n```python\ncode_challenge_method: Literal[\"S256\"] = \"S256\"\n```\n\n### Token 安全存储\n\n- 生产环境应使用加密存储（如 `EncryptedTokenStorage`）\n- Refresh Token 应安全保存，防止泄露\n- Token 过期时间应合理设置\n\n### HTTPS 要求\n\nSDK 对客户端元数据 URL 有严格的验证要求：\n\n```python\ndef is_valid_client_metadata_url(url: str | None) -> bool:\n \"\"\"验证客户端元数据 URL 是否有效\"\"\"\n if not url:\n return False\n try:\n parsed = urlparse(url)\n return parsed.scheme == \"https\" and parsed.path not in (\"\", \"/\")\n except Exception:\n return False\n```\n\n资料来源：[src/mcp/client/auth/utils.py:30-50]()\n\n## 相关文档\n\n- [授权服务器实现](../servers/auth/README.md)\n- [Streamable HTTP 传输](../transports/streamable-http.md)\n- [RFC 6749 - OAuth 2.0 授权框架](https://datatracker.ietf.org/doc/html/rfc6749)\n- [RFC 7636 - PKCE](https://datatracker.ietf.org/doc/html/rfc7636)\n- [RFC 8414 - OAuth 授权服务器元数据](https://www.rfc-editor.org/rfc/rfc8414)\n- [RFC 9728 - 受保护资源元数据](https://www.rfc-editor.org/rfc/rfc9728)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：modelcontextprotocol/python-sdk\n\n摘要：发现 22 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：运行坑 - 来源证据：[packit] Pull from upstream failed for release 1.27.1。\n\n## 1. 运行坑 · 来源证据：[packit] Pull from upstream failed for release 1.27.1\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[packit] Pull from upstream failed for release 1.27.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7cd3c6cd2e994e6cbd60b3cbb19c96e6 | https://github.com/modelcontextprotocol/python-sdk/issues/2563 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：MCP client does not retry authenticated request after successful OAuth token exchange\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP client does not retry authenticated request after successful OAuth token exchange\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_437e528a826e41e6ae0d654e0e858cbc | https://github.com/modelcontextprotocol/python-sdk/issues/2577 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f4669be4619541d3bc0001e432fa5416 | https://github.com/modelcontextprotocol/python-sdk/issues/2578 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Race condition between SSE session init and tools/call rejection (-32602)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Race condition between SSE session init and tools/call rejection (-32602)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f707b6204fd541d3aea0e5c1ef97e432 | https://github.com/modelcontextprotocol/python-sdk/issues/2583 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Types-only install option\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Types-only install option\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1582e38e22384d509ffb75f91a25c9d0 | https://github.com/modelcontextprotocol/python-sdk/issues/2581 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：Expose `schema_generator` on `FastMCP` for tool params schema generation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Expose `schema_generator` on `FastMCP` for tool params schema generation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2a614d750d3f4ec59807cdd800d8ff75 | https://github.com/modelcontextprotocol/python-sdk/issues/2582 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 配置坑 · 来源证据：v1.24.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.24.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_51df2611be1e47b586edd80b1adb1cfb | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.24.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 能力坑 · 能力判断依赖假设\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:862584018 | https://github.com/modelcontextprotocol/python-sdk | README/documentation is current enough for a first validation pass.\n\n## 9. 运行坑 · 来源证据：fix: 4 additional raise sites missing exception chaining with 'from'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：fix: 4 additional raise sites missing exception chaining with 'from'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_71303d3f16c942efb8521432eba345a1 | https://github.com/modelcontextprotocol/python-sdk/issues/2575 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · 来源证据：v1.23.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.23.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c7b4addde6a4da3ae29d5f3f01e7455 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在安全注意事项\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:862584018 | https://github.com/modelcontextprotocol/python-sdk | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Claude Code client sends tools/call without initialize handshake — SSE transport rejects with -32602\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Claude Code client sends tools/call without initialize handshake — SSE transport rejects with -32602\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_48d1c0f7a5d040568e55a2fa6ead27d8 | https://github.com/modelcontextprotocol/python-sdk/issues/2579 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v1.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.23.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ca7e48aa359f4c0b86a3ca42172b40d9 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v1.23.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.23.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_202f1fef816145aa912dae7104ecf977 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v1.25.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.25.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9cdf542dc72c4e31998478a1e41b9c8e | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.25.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.27.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.27.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eb0db07c9d9940e8af311c6e3165dada | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.27.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v1.27.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.27.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bcdd360ffa1641fbb2ed4c5be2be5ebe | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.27.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · 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:862584018 | https://github.com/modelcontextprotocol/python-sdk | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | release_recency=unknown\n\n\n",
"markdown_key": "python-sdk",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:862584018",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/modelcontextprotocol/python-sdk"
},
{
"evidence_id": "art_9c66d3a8d8c44996b5513dc2a8e2bcf5",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/modelcontextprotocol/python-sdk#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "python-sdk 说明书",
"toc": [
"https://github.com/modelcontextprotocol/python-sdk 项目说明书",
"目录",
"MCP 协议与 Python 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": "161834d4aee2633c42d3976c8f8751b6c4d947d5",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"docs/authorization.md",
"docs/concepts.md",
"docs/index.md",
"docs/low-level-server.md",
"docs/installation.md",
"docs/testing.md",
"docs/migration.md",
"docs/hooks/gen_ref_pages.py",
"docs/experimental/tasks.md",
"docs/experimental/index.md",
"docs/experimental/tasks-client.md",
"docs/experimental/tasks-server.md",
"examples/README.md",
"examples/snippets/pyproject.toml",
"examples/mcpserver/readme-quickstart.py",
"examples/mcpserver/simple_echo.py",
"examples/mcpserver/logging_and_progress.py",
"examples/mcpserver/weather_structured.py",
"examples/mcpserver/unicode_example.py",
"examples/mcpserver/parameter_descriptions.py",
"examples/mcpserver/icons_demo.py",
"examples/mcpserver/complex_inputs.py",
"examples/mcpserver/desktop.py",
"examples/mcpserver/echo.py",
"examples/mcpserver/screenshot.py",
"examples/mcpserver/memory.py",
"examples/mcpserver/direct_call_tool_result_return.py",
"examples/mcpserver/text_me.py",
"examples/snippets/servers/mcpserver_quickstart.py",
"examples/snippets/servers/oauth_server.py",
"examples/snippets/servers/streamable_starlette_mount.py",
"examples/snippets/servers/notifications.py",
"examples/snippets/servers/elicitation.py",
"examples/snippets/servers/streamable_http_host_mounting.py",
"examples/snippets/servers/lifespan_example.py",
"examples/snippets/servers/direct_execution.py",
"examples/snippets/servers/streamable_http_path_config.py"
],
"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": "# python-sdk - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 python-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- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install \"mcp[cli]\"` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `claude mcp add --transport http my-server http://localhost:8000/mcp` 证据：`README.md` Claim：`clm_0004` supported 0.86\n- `npx -y @modelcontextprotocol/inspector` 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：角色质量和任务匹配不能直接相信。\n- **继续会触碰**：角色选择偏差、命令执行、宿主 AI 配置\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` 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 的默认行为。 证据：`AGENTS.md`, `CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n\n### 继续会触碰什么\n\n- **角色选择偏差**：用户对任务应该由哪个专家角色处理的判断。 原因：选错角色会让 AI 从错误专业视角回答，浪费时间或误导决策。\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`AGENTS.md`, `CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`, `README.v2.md`, `examples/clients/simple-chatbot/README.MD`\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_0006` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0007` 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` Claim：`clm_0001` supported 0.86\n\n### 上下文规模\n\n- 文件总数：437\n- 重要文件覆盖：40/437\n- 证据索引条目：48\n- 角色 / Skill 条目：37\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请基于 python-sdk 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 python-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请基于 python-sdk 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 37 个角色 / Skill / 项目文档条目。\n\n- **Development Guidelines**（project_doc）：- main is currently the V2 rework. Breaking changes are expected here — when removing or replacing an API, delete it outright and document the change in docs/migration.md . Do not add @deprecated shims or backward-compat layers on main . - v1.x is the release branch for the current stable line. Backport PRs target this branch and use a v1.x title prefix. - README.md is frozen at v1 a pre-commit hook rejects edits .… 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`AGENTS.md`\n- **Claude**（project_doc）： 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CLAUDE.md`\n- **MCP Python SDK**（project_doc）：Python implementation of the Model Context Protocol MCP 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **Python SDK Examples**（project_doc）：This folders aims to provide simple examples of using the Python SDK. Please refer to the servers repository https://github.com/modelcontextprotocol/servers for real-world servers. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/README.md`\n- **Simple Auth Client Example**（project_doc）：A demonstration of how to use the MCP Python SDK with OAuth authentication over streamable HTTP or SSE transport. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/clients/simple-auth-client/README.md`\n- **MCP Simple Chatbot**（project_doc）：This example demonstrates how to integrate the Model Context Protocol MCP into a simple CLI chatbot. The implementation showcases MCP's flexibility by supporting multiple tools through MCP servers and is compatible with any LLM provider that follows OpenAI API standards. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/clients/simple-chatbot/README.MD`\n- **Simple Task Client**（project_doc）：A minimal MCP client demonstrating polling for task results over streamable HTTP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/clients/simple-task-client/README.md`\n- **Simple Interactive Task Client**（project_doc）：A minimal MCP client demonstrating responses to interactive tasks elicitation and sampling . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/clients/simple-task-interactive-client/README.md`\n- **MCP SSE Polling Demo Client**（project_doc）：Demonstrates client-side auto-reconnect for the SSE polling pattern SEP-1699 . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/clients/sse-polling-client/README.md`\n- **MCP Everything Server**（project_doc）：A comprehensive MCP server implementing all protocol features for conformance testing. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/everything-server/README.md`\n- **MCP OAuth Authentication Demo**（project_doc）：This example demonstrates OAuth 2.0 authentication with the Model Context Protocol using separate Authorization Server AS and Resource Server RS to comply with the new RFC 9728 specification. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/simple-auth/README.md`\n- **MCP Simple Pagination**（project_doc）：A simple MCP server demonstrating pagination for tools, resources, and prompts using cursor-based pagination. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/simple-pagination/README.md`\n- **MCP Simple Prompt**（project_doc）：A simple MCP server that exposes a customizable prompt template with optional context and topic parameters. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/simple-prompt/README.md`\n- **MCP Simple Resource**（project_doc）：A simple MCP server that exposes sample text files as resources. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/simple-resource/README.md`\n- **MCP Simple StreamableHttp Stateless Server Example**（project_doc）：MCP Simple StreamableHttp Stateless Server Example 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/simple-streamablehttp-stateless/README.md`\n- **MCP Simple StreamableHttp Server Example**（project_doc）：MCP Simple StreamableHttp Server Example 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/simple-streamablehttp/README.md`\n- **Simple Interactive Task Server**（project_doc）：A minimal MCP server demonstrating interactive tasks with elicitation and sampling. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/simple-task-interactive/README.md`\n- **Simple Task Server**（project_doc）：A minimal MCP server demonstrating the experimental tasks feature over streamable HTTP. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/simple-task/README.md`\n- **Usage**（project_doc）：A simple MCP server that exposes a website fetching tool. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/simple-tool/README.md`\n- **MCP SSE Polling Demo Server**（project_doc）：Demonstrates the SSE polling pattern with server-initiated stream close for long-running tasks SEP-1699 . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/sse-polling-demo/README.md`\n- **Contributing**（project_doc）：Thank you for your interest in contributing to the MCP Python SDK! This document provides guidelines and instructions for contributing. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CONTRIBUTING.md`\n- **Authorization**（project_doc）：This page is currently being written. Check back soon for complete documentation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/authorization.md`\n- **Concepts**（project_doc）：This page is currently being written. Check back soon for complete documentation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/concepts.md`\n- **MCP Python SDK**（project_doc）：The Model Context Protocol MCP allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/index.md`\n- **Installation**（project_doc）：The Python SDK is available on PyPI as mcp https://pypi.org/project/mcp/ so installation is as simple as: 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/installation.md`\n- **Low-Level Server**（project_doc）：This page is currently being written. Check back soon for complete documentation. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/low-level-server.md`\n- **Migration Guide: v1 to v2**（project_doc）：This guide covers the breaking changes introduced in v2 of the MCP Python SDK and how to update your code. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/migration.md`\n- **Experimental Features**（project_doc）：The features in this section are experimental and may change without notice. They track the evolving MCP specification and are not yet stable. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/experimental/index.md`\n- **Client Task Usage**（project_doc）：Tasks are an experimental feature. The API may change without notice. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/experimental/tasks-client.md`\n- **Server Task Implementation**（project_doc）：Tasks are an experimental feature. The API may change without notice. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/experimental/tasks-server.md`\n- **Tasks**（project_doc）：Tasks are an experimental feature tracking the draft MCP specification. The API may change without notice. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/experimental/tasks.md`\n- **Testing MCP Servers**（project_doc）：The Python SDK provides a Client class for testing MCP servers with an in-memory transport. This makes it easy to write tests without network overhead. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`docs/testing.md`\n- **Contributor Covenant Code of Conduct**（project_doc）：Contributor Covenant Code of Conduct 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`CODE_OF_CONDUCT.md`\n- **MCP Python SDK**（project_doc）：Python implementation of the Model Context Protocol MCP 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.v2.md`\n- **Release Process**（project_doc）：1. Change dependency version in pyproject.toml 2. Upgrade lock with uv lock --resolution lowest-direct 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`RELEASE.md`\n- **Security Policy**（project_doc）：Thank you for helping keep the Model Context Protocol and its ecosystem secure. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n- **Step 1: Resolve the PR**（project_doc）：Review the pull request: $ARGUMENTS 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`.claude/commands/review-pr.md`\n\n## 证据索引\n\n- 共索引 48 条证据。\n\n- **Development Guidelines**（documentation）：- main is currently the V2 rework. Breaking changes are expected here — when removing or replacing an API, delete it outright and document the change in docs/migration.md . Do not add @deprecated shims or backward-compat layers on main . - v1.x is the release branch for the current stable line. Backport PRs target this branch and use a v1.x title prefix. - README.md is frozen at v1 a pre-commit hook rejects edits . Edit README.v2.md instead. 证据：`AGENTS.md`\n- **Claude**（documentation）：@AGENTS.md 证据：`CLAUDE.md`\n- **MCP Python SDK**（documentation）：Python implementation of the Model Context Protocol MCP 证据：`README.md`\n- **Python SDK Examples**（documentation）：This folders aims to provide simple examples of using the Python SDK. Please refer to the servers repository https://github.com/modelcontextprotocol/servers for real-world servers. 证据：`examples/README.md`\n- **Simple Auth Client Example**（documentation）：A demonstration of how to use the MCP Python SDK with OAuth authentication over streamable HTTP or SSE transport. 证据：`examples/clients/simple-auth-client/README.md`\n- **MCP Simple Chatbot**（documentation）：This example demonstrates how to integrate the Model Context Protocol MCP into a simple CLI chatbot. The implementation showcases MCP's flexibility by supporting multiple tools through MCP servers and is compatible with any LLM provider that follows OpenAI API standards. 证据：`examples/clients/simple-chatbot/README.MD`\n- **Simple Task Client**（documentation）：A minimal MCP client demonstrating polling for task results over streamable HTTP. 证据：`examples/clients/simple-task-client/README.md`\n- **Simple Interactive Task Client**（documentation）：A minimal MCP client demonstrating responses to interactive tasks elicitation and sampling . 证据：`examples/clients/simple-task-interactive-client/README.md`\n- **MCP SSE Polling Demo Client**（documentation）：Demonstrates client-side auto-reconnect for the SSE polling pattern SEP-1699 . 证据：`examples/clients/sse-polling-client/README.md`\n- **MCP Everything Server**（documentation）：A comprehensive MCP server implementing all protocol features for conformance testing. 证据：`examples/servers/everything-server/README.md`\n- **MCP OAuth Authentication Demo**（documentation）：This example demonstrates OAuth 2.0 authentication with the Model Context Protocol using separate Authorization Server AS and Resource Server RS to comply with the new RFC 9728 specification. 证据：`examples/servers/simple-auth/README.md`\n- **MCP Simple Pagination**（documentation）：A simple MCP server demonstrating pagination for tools, resources, and prompts using cursor-based pagination. 证据：`examples/servers/simple-pagination/README.md`\n- **MCP Simple Prompt**（documentation）：A simple MCP server that exposes a customizable prompt template with optional context and topic parameters. 证据：`examples/servers/simple-prompt/README.md`\n- **MCP Simple Resource**（documentation）：A simple MCP server that exposes sample text files as resources. 证据：`examples/servers/simple-resource/README.md`\n- **MCP Simple StreamableHttp Stateless Server Example**（documentation）：MCP Simple StreamableHttp Stateless Server Example 证据：`examples/servers/simple-streamablehttp-stateless/README.md`\n- **MCP Simple StreamableHttp Server Example**（documentation）：MCP Simple StreamableHttp Server Example 证据：`examples/servers/simple-streamablehttp/README.md`\n- **Simple Interactive Task Server**（documentation）：A minimal MCP server demonstrating interactive tasks with elicitation and sampling. 证据：`examples/servers/simple-task-interactive/README.md`\n- **Simple Task Server**（documentation）：A minimal MCP server demonstrating the experimental tasks feature over streamable HTTP. 证据：`examples/servers/simple-task/README.md`\n- **Usage**（documentation）：A simple MCP server that exposes a website fetching tool. 证据：`examples/servers/simple-tool/README.md`\n- **MCP SSE Polling Demo Server**（documentation）：Demonstrates the SSE polling pattern with server-initiated stream close for long-running tasks SEP-1699 . 证据：`examples/servers/sse-polling-demo/README.md`\n- **Contributing**（documentation）：Thank you for your interest in contributing to the MCP Python SDK! This document provides guidelines and instructions for contributing. 证据：`CONTRIBUTING.md`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Authorization**（documentation）：This page is currently being written. Check back soon for complete documentation. 证据：`docs/authorization.md`\n- **Concepts**（documentation）：This page is currently being written. Check back soon for complete documentation. 证据：`docs/concepts.md`\n- **MCP Python SDK**（documentation）：The Model Context Protocol MCP allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction. 证据：`docs/index.md`\n- **Installation**（documentation）：The Python SDK is available on PyPI as mcp https://pypi.org/project/mcp/ so installation is as simple as: 证据：`docs/installation.md`\n- **Low-Level Server**（documentation）：This page is currently being written. Check back soon for complete documentation. 证据：`docs/low-level-server.md`\n- **Migration Guide: v1 to v2**（documentation）：This guide covers the breaking changes introduced in v2 of the MCP Python SDK and how to update your code. 证据：`docs/migration.md`\n- **Experimental Features**（documentation）：The features in this section are experimental and may change without notice. They track the evolving MCP specification and are not yet stable. 证据：`docs/experimental/index.md`\n- **Client Task Usage**（documentation）：Tasks are an experimental feature. The API may change without notice. 证据：`docs/experimental/tasks-client.md`\n- **Server Task Implementation**（documentation）：Tasks are an experimental feature. The API may change without notice. 证据：`docs/experimental/tasks-server.md`\n- **Tasks**（documentation）：Tasks are an experimental feature tracking the draft MCP specification. The API may change without notice. 证据：`docs/experimental/tasks.md`\n- **Testing MCP Servers**（documentation）：The Python SDK provides a Client class for testing MCP servers with an in-memory transport. This makes it easy to write tests without network overhead. 证据：`docs/testing.md`\n- **Contributor Covenant Code of Conduct**（documentation）：Contributor Covenant Code of Conduct 证据：`CODE_OF_CONDUCT.md`\n- **MCP Python SDK**（documentation）：Python implementation of the Model Context Protocol MCP 证据：`README.v2.md`\n- **Release Process**（documentation）：1. Change dependency version in pyproject.toml 2. Upgrade lock with uv lock --resolution lowest-direct 证据：`RELEASE.md`\n- **Security Policy**（documentation）：Thank you for helping keep the Model Context Protocol and its ecosystem secure. 证据：`SECURITY.md`\n- **Step 1: Resolve the PR**（documentation）：Review the pull request: $ARGUMENTS 证据：`.claude/commands/review-pr.md`\n- **Servers Config**（structured_config）：{ \"mcpServers\": { \"sqlite\": { \"command\": \"uvx\", \"args\": \"mcp-server-sqlite\", \"--db-path\", \"./test.db\" }, \"puppeteer\": { \"command\": \"npx\", \"args\": \"-y\", \"@modelcontextprotocol/server-puppeteer\" } } } 证据：`examples/clients/simple-chatbot/mcp_simple_chatbot/servers_config.json`\n- **Applied 120 line-length rule to all files: https://github.com/modelcontextprotocol/python-sdk/pull/856**（source_file）：Applied 120 line-length rule to all files: https://github.com/modelcontextprotocol/python-sdk/pull/856 543961968c0634e93d919d509cce23a1d6a56c21 证据：`.git-blame-ignore-revs`\n- **Generated**（source_file）：Generated uv.lock linguist-generated=true 证据：`.gitattribute`\n- **Dependabot**（source_file）：version: 2 updates: - package-ecosystem: \"github-actions\" directory: \"/\" schedule: interval: monthly groups: github-actions: patterns: - \" \" 证据：`.github/dependabot.yml`\n- **Byte-compiled / optimized / DLL files**（source_file）：Byte-compiled / optimized / DLL files pycache / .py cod $py.class 证据：`.gitignore`\n- **TODO Max : Drop this in v2.**（source_file）：repos: - repo: https://github.com/pre-commit/pre-commit-hooks rev: v6.0.0 hooks: - id: end-of-file-fixer 证据：`.pre-commit-config.yaml`\n- **TODO Marcelo : Add Anthropic copyright?**（source_file）：site name: MCP Server site description: MCP Server strict: true 证据：`mkdocs.yml`\n- **PEP 517 build isolation fetches build-system .requires and transitives at**（source_file）：project name = \"mcp\" dynamic = \"version\" description = \"Model Context Protocol SDK\" readme = \"README.md\" requires-python = \" =3.10\" authors = { name = \"Model Context Protocol a Series of LF Projects, LLC.\" } maintainers = { name = \"David Soria Parra\", email = \"davidsp@anthropic.com\" }, { name = \"Marcelo Trylesinski\", email = \"marcelotryle@gmail.com\" }, { name = \"Max Isbey\", email = \"maxisbey@anthropic.com\" }, { name = \"Felix Weinberger\", email = \"fweinberger@anthropic.com\" }, keywords = \"git\", \"mcp\", \"llm\", \"automation\" license = { text = \"MIT\" } classifiers = \"Development Status :: 4 - Beta\", \"Intended Audience :: Developers\", \"License :: OSI Approved :: MIT License\", \"Programming Language… 证据：`pyproject.toml`\n- **!/usr/bin/env python3**（source_file）：!/usr/bin/env python3 \"\"\"Update README.md with live code snippets from example files. 证据：`scripts/update_readme_snippets.py`\n- **Conftest**（source_file）：@pytest.fixture def anyio backend : return \"asyncio\" 证据：`tests/conftest.py`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`AGENTS.md`, `CLAUDE.md`, `README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`AGENTS.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 协议与 Python SDK 简介**：importance `high`\n - source_paths: README.md, docs/concepts.md, src/mcp/__init__.py\n- **安装与配置**：importance `high`\n - source_paths: docs/installation.md, pyproject.toml\n- **快速开始指南**：importance `high`\n - source_paths: examples/snippets/servers/fastmcp_quickstart.py, examples/snippets/servers/basic_tool.py, examples/snippets/servers/basic_resource.py, examples/snippets/servers/basic_prompt.py\n- **系统架构与核心组件**：importance `high`\n - source_paths: src/mcp/client/client.py, src/mcp/client/session.py, src/mcp/server/session.py, src/mcp/shared/session.py, src/mcp/shared/message.py\n- **传输协议实现**：importance `high`\n - source_paths: src/mcp/client/stdio.py, src/mcp/client/sse.py, src/mcp/client/websocket.py, src/mcp/client/streamable_http.py, src/mcp/server/stdio.py\n- **FastMCP 服务器框架**：importance `high`\n - source_paths: src/mcp/server/fastmcp/__init__.py, src/mcp/server/fastmcp/server.py, src/mcp/server/fastmcp/context.py, src/mcp/server/fastmcp/exceptions.py, src/mcp/server/fastmcp/tools/base.py\n- **资源、资源模板、提示与工具**：importance `high`\n - source_paths: src/mcp/server/fastmcp/resources/types.py, src/mcp/server/fastmcp/resources/templates.py, src/mcp/server/fastmcp/utilities/func_metadata.py, examples/snippets/servers/basic_tool.py, examples/snippets/servers/basic_resource.py\n- **上下文与会话管理**：importance `high`\n - source_paths: src/mcp/server/context.py, src/mcp/client/context.py, src/mcp/shared/_context.py, src/mcp/server/fastmcp/utilities/context_injection.py, src/mcp/server/fastmcp/utilities/types.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `161834d4aee2633c42d3976c8f8751b6c4d947d5`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `docs/authorization.md`, `docs/concepts.md`, `docs/index.md`, `docs/low-level-server.md`, `docs/installation.md`, `docs/testing.md`, `docs/migration.md`, `docs/hooks/gen_ref_pages.py`, `docs/experimental/tasks.md`, `docs/experimental/index.md`, `docs/experimental/tasks-client.md`, `docs/experimental/tasks-server.md`, `examples/README.md`, `examples/snippets/pyproject.toml`, `examples/mcpserver/readme-quickstart.py`, `examples/mcpserver/simple_echo.py`, `examples/mcpserver/logging_and_progress.py`\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: 来源证据：[packit] Pull from upstream failed for release 1.27.1\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[packit] Pull from upstream failed for release 1.27.1\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_7cd3c6cd2e994e6cbd60b3cbb19c96e6 | https://github.com/modelcontextprotocol/python-sdk/issues/2563 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：MCP client does not retry authenticated request after successful OAuth token exchange\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP client does not retry authenticated request after successful OAuth token exchange\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_437e528a826e41e6ae0d654e0e858cbc | https://github.com/modelcontextprotocol/python-sdk/issues/2577 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_f4669be4619541d3bc0001e432fa5416 | https://github.com/modelcontextprotocol/python-sdk/issues/2578 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Race condition between SSE session init and tools/call rejection (-32602)\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Race condition between SSE session init and tools/call rejection (-32602)\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_f707b6204fd541d3aea0e5c1ef97e432 | https://github.com/modelcontextprotocol/python-sdk/issues/2583 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：Types-only install option\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Types-only install option\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_1582e38e22384d509ffb75f91a25c9d0 | https://github.com/modelcontextprotocol/python-sdk/issues/2581 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：Expose `schema_generator` on `FastMCP` for tool params schema generation\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Expose `schema_generator` on `FastMCP` for tool params schema generation\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_2a614d750d3f4ec59807cdd800d8ff75 | https://github.com/modelcontextprotocol/python-sdk/issues/2582 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：v1.24.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.24.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_51df2611be1e47b586edd80b1adb1cfb | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.24.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 能力判断依赖假设\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:862584018 | https://github.com/modelcontextprotocol/python-sdk | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：fix: 4 additional raise sites missing exception chaining with 'from'\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：fix: 4 additional raise sites missing exception chaining with 'from'\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_71303d3f16c942efb8521432eba345a1 | https://github.com/modelcontextprotocol/python-sdk/issues/2575 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：v1.23.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.23.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_3c7b4addde6a4da3ae29d5f3f01e7455 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\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/python-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- 来源证据：[packit] Pull from upstream failed for release 1.27.1（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：MCP client does not retry authenticated request after successful OAuth token exchange（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Race condition between SSE session init and tools/call rejection (-32602)（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Types-only install option（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\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/python-sdk 项目说明书\n\n生成时间：2026-05-13 12:56:39 UTC\n\n## 目录\n\n- [MCP 协议与 Python SDK 简介](#page-introduction)\n- [安装与配置](#page-installation)\n- [快速开始指南](#page-quickstart)\n- [系统架构与核心组件](#page-architecture)\n- [传输协议实现](#page-transports)\n- [FastMCP 服务器框架](#page-fastmcp)\n- [资源、资源模板、提示与工具](#page-resources-prompts-tools)\n- [上下文与会话管理](#page-context-session)\n- [客户端开发指南](#page-client-development)\n- [客户端 OAuth 认证](#page-client-auth)\n\n\n\n## MCP 协议与 Python SDK 简介\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [系统架构与核心组件](#page-architecture), [快速开始指南](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [AGENTS.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/AGENTS.md)\n- [CONTRIBUTING.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/CONTRIBUTING.md)\n- [examples/snippets/servers/completion.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/completion.py)\n- [src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n- [src/mcp/server/mcpserver/resources/base.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/base.py)\n- [src/mcp/server/mcpserver/resources/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n- [examples/servers/simple-prompt/mcp_simple_prompt/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-prompt/mcp_simple_prompt/server.py)\n- [examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py)\n- [RELEASE.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/RELEASE.md)\n \n\n# MCP 协议与 Python SDK 简介\n\n## 概述\n\nMCP（Model Context Protocol，模型上下文协议）是一种开放协议，用于在大型语言模型（LLM）应用程序与外部数据源、工具和服务之间建立标准化的通信桥梁。Python SDK 是该协议的核心实现库，为开发者提供了构建 MCP 服务器和客户端的能力。\n\nMCP 协议的核心价值在于**标准化**——它定义了 LLM 应用与外部世界交互的统一方式，使开发者能够创建可复用的组件，让 AI 系统能够安全、受控地访问本地文件、数据库、API 以及各类服务。\n\n## 核心概念\n\n### 服务器与客户端架构\n\nMCP 采用典型的客户端-服务器架构，支持多种通信传输方式：\n\n| 组件 | 说明 | 支持的传输方式 |\n|------|------|----------------|\n| MCP 服务器 | 托管资源、工具和提示的服务器 | stdio、streamable-http |\n| MCP 客户端 | 连接服务器并调用功能的客户端 | stdio、streamable-http |\n\n```mermaid\ngraph TD\n A[\"MCP 客户端\"] -->|\"stdio/streamable-http\"| B[\"MCP 服务器\"]\n B --> C[\"资源管理器\"]\n B --> D[\"工具管理器\"]\n B --> E[\"提示管理器\"]\n B --> F[\"完成处理器\"]\n C --> G[\"FunctionResource\"]\n C --> H[\"FileResource\"]\n G --> I[\"fn: Callable\"]\n H --> J[\"path: Path\"]\n```\n\n### 资源系统\n\nMCP 的资源系统允许服务器向客户端暴露可读取的数据。SDK 支持两种主要资源类型：\n\n| 资源类型 | 说明 | 关键字段 |\n|----------|------|----------|\n| FunctionResource | 通过函数动态生成的资源内容 | `fn: Callable` |\n| FileResource | 从文件系统读取的静态资源 | `path: Path`, `is_binary: bool` |\n\n所有资源都继承自基类 `Resource`，包含以下通用字段：\n\n- `uri`: 资源的唯一标识符\n- `name`: 资源名称\n- `title`: 人类可读的标题\n- `description`: 资源描述\n- `mime_type`: 资源的 MIME 类型，默认 `text/plain`\n- `annotations`: 资源的注解信息\n- `meta`: 额外的元数据\n\n资料来源：[src/mcp/server/mcpserver/resources/base.py:1-42](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/base.py)\n\n### 工具系统\n\n工具是 MCP 服务器暴露的可执行函数，客户端可以通过 JSON-RPC 调用这些工具。工具系统支持：\n\n- **结构化输出**: 使用 Pydantic 模型定义返回格式\n- **元数据**: 支持标题、描述、图标和注解\n- **异步执行**: 所有工具函数支持异步调用\n\n```python\ndef add_tool(\n self,\n fn: Callable[..., Any],\n name: str | None = None,\n title: str | None = None,\n description: str | None = None,\n annotations: Annotations | None = None,\n icons: list[Icon] | None = None,\n meta: ToolMeta | None = None,\n structured_output: type[BaseModel] | None = None,\n) -> None:\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n\n### 提示系统\n\n提示（Prompts）允许服务器定义可复用的消息模板，这些模板可以接受参数并生成动态内容：\n\n```python\nclass Prompt(BaseModel, abc.ABC):\n name: str\n description: str | None = None\n arguments: list[PromptArgument] | None = None\n icons: list[Icon] | None = None\n```\n\n使用示例：\n\n```python\nreturn types.GetPromptResult(\n messages=create_messages(context=arguments.get(\"context\"), topic=arguments.get(\"topic\")),\n description=\"A simple prompt with optional context and topic arguments\",\n)\n```\n\n资料来源：[examples/servers/simple-prompt/mcp_simple_prompt/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-prompt/mcp_simple_prompt/server.py)\n\n### 完成处理器\n\n完成处理器为资源模板和提示参数提供动态补全建议：\n\n```python\n@mcp.completion()\nasync def handle_completion(ref, argument, context):\n if isinstance(ref, ResourceTemplateReference):\n if ref.uri == \"github://repos/{owner}/{repo}\" and argument.name == \"repo\":\n if context and context.arguments and context.arguments.get(\"owner\") == \"modelcontextprotocol\":\n repos = [\"python-sdk\", \"typescript-sdk\", \"specification\"]\n return Completion(values=repos, has_more=False)\n return None\n```\n\n资料来源：[examples/snippets/servers/completion.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/completion.py)\n\n## 交互式任务系统\n\nMCP 支持长时间运行的任务（Tasks），包括两个关键功能：\n\n### elicitation（征询）\n\n用于在执行过程中请求用户确认或输入：\n\n```mermaid\ngraph LR\n A[\"工具调用\"] --> B[\"task.elicit()\"]\n B --> C[\"input_required 状态\"]\n C --> D[\"用户响应\"]\n D --> E[\"任务完成\"]\n```\n\n### Sampling（采样）\n\n允许服务器请求 LLM 生成内容：\n\n```mermaid\ngraph LR\n A[\"工具调用\"] --> B[\"task.create_message()\"]\n B --> C[\"input_required 状态\"]\n C --> D[\"LLM 响应\"]\n D --> E[\"任务完成\"]\n```\n\n资料来源：[examples/servers/simple-task-interactive/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-task-interactive/README.md)\n\n## 认证系统\n\nSDK 提供了 OAuth 认证支持，包括完整的授权码流程：\n\n```mermaid\ngraph TD\n A[\"客户端\"] --> B[\"授权请求\"]\n B --> C[\"用户登录\"]\n C --> D[\"授权码回调\"]\n D --> E[\"令牌交换\"]\n E --> F[\"认证完成\"]\n```\n\n认证服务器可以返回 HTML 表单进行交互：\n\n```python\nasync def handle_login_callback(self, request: Request) -> Response:\n form = await request.form()\n username = form.get(\"username\")\n password = form.get(\"password\")\n state = form.get(\"state\")\n```\n\n资料来源：[examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-auth/mcp_simple_auth/simple_auth_provider.py)\n\n## 开发指南\n\n### 环境配置\n\n```bash\n# 安装 uv（如果尚未安装）\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# 克隆仓库\ngit clone https://github.com/modelcontextprotocol/python-sdk.git\n\n# 安装依赖\nuv sync --frozen --all-extras --dev\n```\n\n资料来源：[CONTRIBUTING.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/CONTRIBUTING.md)\n\n### 代码质量要求\n\n| 检查项 | 命令 | 说明 |\n|--------|------|------|\n| 格式化 | `uv run --frozen ruff format .` | 使用 ruff 格式化代码 |\n| 静态检查 | `uv run --frozen ruff check . --fix` | 自动修复 lint 问题 |\n| 类型检查 | `uv run --frozen pyright` | 运行 pyright 类型检查 |\n| 测试 | `uv run --frozen pytest` | 执行测试套件 |\n\n### 核心规范\n\n1. **类型提示**: 所有公共 API 必须包含类型提示\n2. **文档字符串**: 公共 API 必须有 docstring，包含 `Raises:` 部分说明可能抛出的异常\n3. **异常处理**: \n - 使用 `logger.exception()` 而非 `logger.error()`\n - 捕获具体异常类型而非通用 `Exception`\n - 禁止在顶级处理器之外使用 `except Exception:`\n4. **导入规范**: 所有导入必须位于文件顶部，禁止内联导入\n\n```python\n# 正确示例\ntry:\n resource = await self._resource_manager.get_resource(uri, context)\nexcept ValueError as exc:\n raise ResourceError(f\"Unknown resource: {uri}\") from exc\n```\n\n资料来源：[AGENTS.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/AGENTS.md)\n\n### 测试规范\n\n- 使用 `anyio` 进行异步测试，而非 `asyncio`\n- 测试应快速且确定性，使用内存异步执行\n- 使用线程仅在必要时，使用子进程作为最后手段\n- 不要使用 `Test` 前缀的类，使用顶层 `test_*` 函数\n\n```python\n# 推荐\ndef test_resource_read():\n assert isinstance(resource, FunctionResource)\n\n# 避免\nclass TestResource:\n def test_read(self):\n ...\n```\n\n## 分支模型\n\n| 分支 | 用途 | 变更类型 |\n|------|------|----------|\n| `main` | V2 开发分支 | 新功能、破坏性变更 |\n| `v1.x` | 稳定版发布分支 | 安全修复、关键 bug 修复 |\n\n资料来源：[AGENTS.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/AGENTS.md)\n\n## 发布流程\n\n1. 在 `pyproject.toml` 中更新依赖版本\n2. 运行 `uv lock --resolution lowest-direct` 升级锁文件\n3. 通过 GitHub UI 创建 Release，标签格式为 `vX.Y.Z`\n4. 版本号将从标签自动设置\n\n资料来源：[RELEASE.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/RELEASE.md)\n\n## 快速开始示例\n\n### 创建简单服务器\n\n```python\nfrom mcp.server.mcpserver import Server\nfrom mcp.server.stdio import stdio_server\n\napp = Server(\"my-mcp-server\")\n\n@app.list_tools()\nasync def handle_list_tools():\n return [types.Tool(\n name=\"greet\",\n description=\"Greet someone\",\n inputSchema={\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"string\"}}}\n )]\n\nasync def main():\n async with stdio_server() as streams:\n await app.run(streams[0], streams[1], app.create_initialization_options())\n```\n\n### 启动 HTTP 服务器\n\n```python\nimport uvicorn\n\nif transport == \"streamable-http\":\n uvicorn.run(app.streamable_http_app(), host=\"127.0.0.1\", port=port)\n```\n\n资料来源：[examples/servers/simple-prompt/mcp_simple_prompt/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-prompt/mcp_simple_prompt/server.py)\n\n## 总结\n\nMCP Python SDK 提供了一套完整、健壮的框架，用于构建与 LLM 应用交互的服务器和客户端。通过标准化的资源、工具、提示和完成处理器接口，开发者可以创建可复用、安全且易于维护的 MCP 组件。SDK 遵循严格的代码质量标准，包括类型提示要求、完整的文档字符串规范以及全面的测试覆盖，确保其稳定性和可维护性。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[MCP 协议与 Python SDK 简介](#page-introduction), [快速开始指南](#page-quickstart)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [CONTRIBUTING.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/CONTRIBUTING.md)\n- [AGENTS.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/AGENTS.md)\n- [examples/clients/simple-auth-client/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/clients/simple-auth-client/README.md)\n- [examples/servers/simple-auth/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-auth/README.md)\n- [examples/clients/simple-task-client/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/clients/simple-task-client/README.md)\n- [examples/servers/simple-task-interactive/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-task-interactive/README.md)\n \n\n# 安装与配置\n\n本文档详细说明 Model Context Protocol (MCP) Python SDK 的安装、环境配置以及开发环境搭建流程。\n\n## 环境要求\n\n### 系统依赖\n\n| 依赖项 | 版本要求 | 说明 |\n|--------|----------|------|\n| Python | 3.10+ | 支持 Python 3.10 至 3.14 |\n| uv | 最新稳定版 | 包管理工具，详见 [uv 官方文档](https://docs.astral.sh/uv/getting-started/installation/) |\n\n资料来源：[CONTRIBUTING.md:1-3]()\n\n### 验证 Python 版本\n\n```bash\npython --version\n```\n\n确保输出为 Python 3.10 或更高版本。\n\n## 项目克隆与依赖安装\n\n### 1. Fork 并克隆仓库\n\n```bash\n# 1. 在 GitHub 上 Fork 仓库\n# 2. 克隆你的 Fork\ngit clone https://github.com/YOUR-USERNAME/python-sdk.git\n\n# 3. 进入项目目录\ncd python-sdk\n```\n\n资料来源：[CONTRIBUTING.md:3-6]()\n\n### 2. 安装依赖\n\nMCP Python SDK **仅支持 uv 作为包管理工具**，严格禁止使用 pip 进行安装或依赖管理。\n\n```bash\n# 安装所有依赖（包括开发依赖和可选依赖）\nuv sync --frozen --all-extras --dev\n```\n\n参数说明：\n- `--frozen`：锁定版本，不更新 lock 文件\n- `--all-extras`：安装所有可选依赖\n- `--dev`：安装开发依赖\n\n资料来源：[CONTRIBUTING.md:7]()\n\n### 3. 设置预提交钩子\n\n```bash\nuv tool install pre-commit --with pre-commit-uv --force-reinstall\n```\n\n预提交钩子会自动执行代码格式化、类型检查等操作。\n\n资料来源：[CONTRIBUTING.md:9-11]()\n\n## 开发环境配置\n\n### uv 工具链使用规范\n\n| 操作类型 | 命令格式 | 说明 |\n|----------|----------|------|\n| 运行工具 | `uv run --frozen ` | 始终使用 `--frozen` 避免意外修改 lock 文件 |\n| 添加依赖 | `uv add ` | 仅用于开发环境 |\n| 升级依赖 | `uv lock --upgrade-package ` | 升级指定包版本 |\n| 测试跨版本 | `uv run --frozen --python 3.10 pytest ...` | 指定 Python 版本运行测试 |\n\n**禁止操作：**\n- 禁止使用 `uv pip install`\n- 禁止使用 `@latest` 语法指定版本\n- 不要仅为修复 CVE 而提升依赖版本下限，约束条件 `>=` 已允许用户自行升级\n\n资料来源：[AGENTS.md:1-20]()\n\n### 代码质量检查\n\n开发过程中应运行以下检查：\n\n```bash\n# 运行测试\nuv run pytest\n\n# 类型检查\nuv run pyright\n\n# 代码格式化\nuv run ruff format .\n\n# 代码检查\nuv run ruff check . --fix\n```\n\n全部检查命令可通过预提交钩子一键执行：\n\n```bash\npre-commit run --all-files\n```\n\n资料来源：[CONTRIBUTING.md:20-35]()\n\n## 服务器配置\n\n### 基本配置参数\n\n客户端连接 MCP 服务器时可通过环境变量配置连接参数：\n\n| 环境变量 | 说明 | 默认值 |\n|----------|------|--------|\n| `MCP_SERVER_PORT` | MCP 服务器端口号 | `8000` |\n| `MCP_TRANSPORT_TYPE` | 传输类型：`streamable-http` 或 `sse` | `streamable-http` |\n| `MCP_CLIENT_METADATA_URL` | 客户端元数据 (CIMD) 的可选 URL | `None` |\n\n资料来源：[examples/clients/simple-auth-client/README.md:47-52]()\n\n### 启动服务器示例\n\n#### Streamable HTTP 传输\n\n```bash\n# 基本启动\nuv run mcp-simple-auth --port=8000 --transport=streamable-http\n\n# 带 OAuth 严格模式\nuv run mcp-simple-auth --port=8000 --transport=streamable-http --oauth-strict\n```\n\n#### SSE 传输\n\n```bash\nuv run mcp-simple-auth --port=8000 --transport=sse\n```\n\n资料来源：[examples/servers/simple-auth/README.md:30-45]()\n\n### 任务服务器配置\n\n交互式任务服务器默认启动地址为 `http://localhost:8000/mcp`，可通过 `--port` 参数修改：\n\n```bash\nuv run mcp-simple-task-interactive --port=9000\n```\n\n资料来源：[examples/servers/simple-task-interactive/README.md:8-12]()\n\n## 项目分支模型\n\nMCP SDK 采用双分支维护策略：\n\n| 分支 | 用途 | 变更类型 |\n|------|------|----------|\n| `main` | V2 开发分支 | 新功能、重构，允许破坏性变更 |\n| `v1.x` | V1 稳定分支 | 仅接收安全修复和关键 bug 修复 |\n\n开发新功能或破坏性变更应基于 `main` 分支创建新分支。安全修复和关键 bug 修复应基于 `v1.x` 分支。\n\n资料来源：[AGENTS.md:1-15]()\n\n## 开发工作流\n\n```mermaid\ngraph TD\n A[选择目标分支] --> B[基于目标分支创建新分支]\n B --> C[编写代码]\n C --> D[运行测试: uv run pytest]\n D --> E{测试通过?}\n E -->|否| F[修复问题]\n F --> C\n E -->|是| G[运行类型检查: uv run pyright]\n G --> H[运行代码检查: uv run ruff check]\n H --> I[提交代码]\n I --> J[创建 Pull Request]\n J --> K[等待 Code Review]\n```\n\n### 代码提交检查清单\n\n1. ✅ 更新相关文档\n2. ✅ 为新功能添加测试\n3. ✅ 确保 CI 通过\n4. ✅ 处理代码审查反馈\n\n资料来源：[CONTRIBUTING.md:37-60]()\n\n## 调试与日志\n\n### 异常处理规范\n\n- **必须使用** `logger.exception()` 而非 `logger.error()` 捕获异常\n- **禁止** 在日志消息中包含异常信息：`logger.exception(\"Failed\")` 而非 `logger.exception(f\"Failed: {e}\")`\n- **优先捕获具体异常类型**：\n - 文件操作：`except (OSError, PermissionError):`\n - JSON 解析：`except json.JSONDecodeError:`\n - 网络操作：`except (ConnectionError, TimeoutError):`\n- **禁止使用** `except Exception:`（顶层处理器除外）\n\n资料来源：[AGENTS.md:1-30]()\n\n### 常见配置问题排查\n\n| 问题 | 可能原因 | 解决方案 |\n|------|----------|----------|\n| 连接被拒绝 | 服务器未启动或端口错误 | 检查 `MCP_SERVER_PORT` 环境变量 |\n| 传输类型错误 | 不支持的传输类型 | 确认使用 `streamable-http` 或 `sse` |\n| 依赖冲突 | 使用了 pip 而非 uv | 使用 `uv sync` 重新安装依赖 |\n\n## 验证安装\n\n安装完成后，可通过以下命令验证环境：\n\n```bash\n# 验证 uv 可用\nuv --version\n\n# 验证 Python 版本\npython --version\n\n# 验证 MCP SDK 安装\nuv run python -c \"import mcp; print(mcp.__version__)\"\n\n# 运行项目测试\nuv run pytest -v\n```\n\n## 下一步\n\n- 阅读 [工具开发指南](./tools.md) 了解如何创建 MCP 工具\n- 阅读 [资源管理](./resources.md) 了解如何暴露资源\n- 阅读 [提示模板](./prompts.md) 了解如何定义提示\n\n---\n\n\n\n## 快速开始指南\n\n### 相关页面\n\n相关主题：[FastMCP 服务器框架](#page-fastmcp), [资源、资源模板、提示与工具](#page-resources-prompts-tools)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [examples/snippets/servers/fastmcp_quickstart.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/fastmcp_quickstart.py)\n- [examples/snippets/servers/basic_tool.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_tool.py)\n- [examples/snippets/servers/basic_resource.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_resource.py)\n- [examples/snippets/servers/basic_prompt.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_prompt.py)\n- [src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n- [src/mcp/server/mcpserver/resources/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n \n\n# 快速开始指南\n\n本指南帮助开发者快速上手 Model Context Protocol (MCP) Python SDK，涵盖服务器创建、工具（Tool）、资源（Resource）和提示（Prompt）的定义与注册，以及如何启动服务。\n\n## 环境准备\n\n### 前置要求\n\n| 要求 | 版本说明 |\n|------|----------|\n| Python | 3.10+ |\n| 包管理器 | uv |\n| 操作系统 | Windows、macOS、Linux |\n\n### 安装 SDK\n\n```bash\n# 使用 uv 安装稳定版本\nuv add mcp\n\n# 安装开发版本（包含所有额外依赖和开发工具）\nuv sync --frozen --all-extras --dev\n```\n\n资料来源：[CONTRIBUTING.md:5-8]()\n\n## MCP 服务器架构\n\nMCP 服务器是 MCP 协议的核心组件，负责向客户端提供服务能力。\n\n```mermaid\ngraph TD\n A[客户端] --> B[MCP Server]\n B --> C[工具管理器
Tool Manager]\n B --> D[资源管理器
Resource Manager]\n B --> E[提示管理器
Prompt Manager]\n C --> F[工具函数]\n D --> G[资源数据]\n E --> H[提示模板]\n```\n\nMCPServer 类是 SDK 的主入口，负责管理所有组件的生命周期并处理客户端请求。\n\n资料来源：[src/mcp/server/mcpserver/server.py:1-50]()\n\n## 创建基础服务器\n\n### 最小示例\n\n```python\nfrom mcp.server import MCPServer\n\nserver = MCPServer(\n name=\"my-server\",\n version=\"1.0.0\",\n)\n```\n\n### 完整配置示例\n\n```python\nfrom mcp.server import MCPServer, ServerSettings\n\nsettings = ServerSettings(\n host=\"0.0.0.0\",\n port=8000,\n streamable_http_transport=True,\n)\nserver = MCPServer(\n name=\"example-server\",\n version=\"1.0.0\",\n settings=settings,\n)\n```\n\n| ServerSettings 参数 | 类型 | 默认值 | 说明 |\n|---------------------|------|--------|------|\n| host | str | \"127.0.0.1\" | 监听地址 |\n| port | int | 8000 | 监听端口 |\n| streamable_http_transport | bool | False | 启用流式 HTTP 传输 |\n| oauth_strict | bool | False | 启用严格 OAuth 认证 |\n\n资料来源：[examples/snippets/servers/fastmcp_quickstart.py:1-30]()\n\n## 定义工具（Tool）\n\n工具是服务器暴露给客户端的可调用函数。\n\n### 基本工具定义\n\n```python\nfrom mcp.server import MCPServer\nfrom mcp.types import Tool\n\ndef get_weather(location: str) -> str:\n \"\"\"获取指定位置的天气信息\"\"\"\n return f\"{location} 天气晴朗，温度 25°C\"\n\nserver = MCPServer(name=\"weather-server\")\nserver.add_tool(\n fn=get_weather,\n name=\"get_weather\",\n description=\"获取天气信息\",\n)\n```\n\n### add_tool 参数说明\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| fn | Callable | 是 | 工具函数 |\n| name | str | 否 | 工具名称，默认为函数名 |\n| title | str | 否 | 工具标题 |\n| description | str | 否 | 工具描述 |\n| annotations | Annotations | 否 | 工具注解 |\n\n函数必须包含类型提示，SDK 会自动验证参数类型。\n\n资料来源：[examples/snippets/servers/basic_tool.py:1-25]()\n\n## 定义资源（Resource）\n\n资源用于向客户端提供数据访问能力。\n\n### 资源类型\n\n| 类型 | 说明 | 用途 |\n|------|------|------|\n| FunctionResource | 函数资源 | 动态生成数据 |\n| FileResource | 文件资源 | 读取本地文件 |\n\n### 函数资源\n\n```python\nfrom mcp.server import MCPServer\nfrom mcp.server.resources import FunctionResource\n\ndef read_config() -> str:\n \"\"\"读取配置数据\"\"\"\n return '{\"debug\": true, \"version\": \"1.0\"}'\n\nserver = MCPServer(name=\"config-server\")\nserver.add_resource(\n FunctionResource.from_function(\n fn=read_config,\n uri=\"config://app\",\n name=\"app_config\",\n title=\"应用配置\",\n description=\"返回当前应用配置\",\n )\n)\n```\n\n### 文件资源\n\n```python\nfrom mcp.server.resources import FileResource\nfrom pathlib import Path\n\nserver.add_resource(\n FileResource(\n path=Path(\"/etc/app/config.json\"),\n name=\"config_file\",\n uri=\"file:///etc/app/config.json\",\n mime_type=\"application/json\",\n )\n)\n```\n\n| FileResource 字段 | 类型 | 说明 |\n|-------------------|------|------|\n| path | Path | 文件路径（必须为绝对路径） |\n| is_binary | bool | 是否以二进制模式读取 |\n| mime_type | str | MIME 类型 |\n\n资料来源：[examples/snippets/servers/basic_resource.py:1-45]()\n\n## 定义提示（Prompt）\n\n提示模板用于生成可复用的对话片段。\n\n```python\nfrom mcp.server import MCPServer\nfrom mcp.server.prompts import Prompt\n\nserver = MCPServer(name=\"prompt-server\")\n\nserver.add_prompt(\n Prompt(\n name=\"code_review\",\n description=\"代码审查提示\",\n arguments=[\n PromptArgument(\n name=\"language\",\n description=\"编程语言\",\n required=True,\n ),\n PromptArgument(\n name=\"code\",\n description=\"待审查代码\",\n required=True,\n ),\n ],\n )\n)\n```\n\n| PromptArgument 字段 | 类型 | 说明 |\n|---------------------|------|------|\n| name | str | 参数名称 |\n| description | str | 参数描述 |\n| required | bool | 是否必填 |\n\n资料来源：[examples/snippets/servers/basic_prompt.py:1-30]()\n\n## 读取资源\n\n### read_resource 方法\n\n```python\nasync def handle_resource_read(server: MCPServer):\n # 使用 URI 读取资源\n contents = await server.read_resource(\"config://app\")\n for content in contents:\n print(content.content)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| uri | AnyUrl \\| str | 资源标识符 |\n| context | Context | 请求上下文 |\n\n异常处理：未知资源返回 `ResourceError`，读取失败时异常被捕获并记录日志。\n\n资料来源：[src/mcp/server/mcpserver/server.py:45-70]()\n\n## 启动服务器\n\n### 运行服务器\n\n```python\nimport uvicorn\n\nif __name__ == \"__main__\":\n uvicorn.run(\n \"my_server:app\",\n host=\"0.0.0.0\",\n port=8000,\n reload=True,\n )\n```\n\n### 命令行启动\n\n```bash\n# 方式一：直接运行模块\nuv run python -m my_server\n\n# 方式二：使用 uvicorn\nuv run uvicorn my_server:app --host 0.0.0.0 --port 8000\n```\n\n### 配置传输方式\n\nMCP 支持多种传输协议：\n\n| 传输类型 | 说明 | 使用场景 |\n|----------|------|----------|\n| streamable-http | 流式 HTTP | 推荐默认选项 |\n| sse | Server-Sent Events | 需要长连接的场景 |\n\n```bash\n# 启动支持 OAuth 的流式 HTTP 服务器\nMCP_TRANSPORT=streamable-http MCP_OAUTH_STRICT=true uv run mcp-my-server\n```\n\n## 项目结构示例\n\n```\nmcp_project/\n├── pyproject.toml\n├── src/\n│ └── my_server/\n│ ├── __init__.py\n│ ├── server.py # 服务器定义\n│ ├── tools.py # 工具实现\n│ ├── resources.py # 资源定义\n│ └── prompts.py # 提示定义\n└── uv.lock\n```\n\n## 常见工作流程\n\n```mermaid\ngraph LR\n A[定义工具] --> B[定义资源]\n B --> C[定义提示]\n C --> D[创建 MCPServer 实例]\n D --> E[注册组件]\n E --> F[启动服务]\n F --> G[客户端连接]\n G --> H[调用工具/访问资源]\n```\n\n## 下一步\n\n- 阅读 [examples/servers/](examples/servers/) 目录下的完整示例\n- 了解 [认证与授权](examples/servers/simple-auth/README.md) 功能\n- 探索 [实验性功能](examples/servers/simple-task/README.md) 如任务支持\n\n---\n\n\n\n## 系统架构与核心组件\n\n### 相关页面\n\n相关主题：[传输协议实现](#page-transports), [上下文与会话管理](#page-context-session)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n- [src/mcp/server/session.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/session.py)\n- [src/mcp/client/session.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/session.py)\n- [src/mcp/shared/session.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/session.py)\n- [src/mcp/shared/message.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/message.py)\n- [src/mcp/types/_types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types/_types.py)\n- [src/mcp/types/jsonrpc.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types/jsonrpc.py)\n- [src/mcp/server/mcpserver/resources/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n- [src/mcp/server/auth/routes.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/auth/routes.py)\n- [src/mcp/server/experimental/task_context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/experimental/task_context.py)\n \n\n# 系统架构与核心组件\n\nModel Context Protocol (MCP) Python SDK 是一个用于构建 Model Context Protocol 客户端和服务器的框架。MCP 是一种标准化协议，使 AI 模型能够与外部数据源和工具进行交互。本文详细介绍 MCP SDK 的系统架构和核心组件。\n\n## 1. 架构概述\n\nMCP 采用客户端-服务器架构，支持多种传输协议（stdio、streamable-http）。协议基于 JSON-RPC 2.0 规范实现双向通信。\n\n```mermaid\ngraph TD\n subgraph 客户端层\n Client[Client 客户端]\n ClientSession[ClientSession 客户端会话]\n end\n \n subgraph 传输层\n Stdio[Stdio 传输]\n Http[Streamable HTTP 传输]\n end\n \n subgraph 服务器层\n Server[Server 服务器]\n MCPServer[MCPServer MCP 服务器]\n ServerSession[ServerSession 服务端会话]\n end\n \n subgraph 核心服务\n ResourceManager[ResourceManager 资源管理]\n PromptManager[PromptManager 提示管理]\n ToolHandler[ToolHandler 工具处理]\n Auth[AuthModule 认证模块]\n end\n \n Client --> ClientSession\n ClientSession <-->|JSON-RPC| Stdio\n ClientSession <-->|JSON-RPC| Http\n Stdio <--> Server\n Http <--> Server\n Server --> ServerSession\n ServerSession --> MCPServer\n MCPServer --> ResourceManager\n MCPServer --> PromptManager\n MCPServer --> ToolHandler\n MCPServer --> Auth\n```\n\n## 2. 核心组件关系\n\n### 2.1 组件层次结构\n\n```mermaid\ngraph TD\n subgraph 高层API\n MCPServer[MCP Server]\n Client[Client]\n end\n \n subgraph 会话层\n ClientSession[ClientSession]\n ServerSession[ServerSession]\n SharedSession[SharedSession]\n end\n \n subgraph 消息层\n MessageHandler[MessageHandler]\n JSONRPCHandler[JSONRPCHandler]\n end\n \n subgraph 传输层\n StdioTransport[StdioTransport]\n StreamableHttpTransport[StreamableHttpTransport]\n end\n \n MCPServer --> ServerSession\n Client --> ClientSession\n ClientSession --> SharedSession\n ServerSession --> SharedSession\n SharedSession --> MessageHandler\n MessageHandler --> JSONRPCHandler\n StdioTransport --> JSONRPCHandler\n StreamableHttpTransport --> JSONRPCHandler\n```\n\n### 2.2 组件职责表\n\n| 组件 | 文件路径 | 职责 |\n|------|----------|------|\n| `Client` | `src/mcp/client/client.py` | 管理客户端连接生命周期，处理服务端发现和传输协商 |\n| `ClientSession` | `src/mcp/client/session.py` | 客户端会话管理，处理请求/响应、notifications 和 call cancellation |\n| `ServerSession` | `src/mcp/server/session.py` | 服务端会话管理，处理请求路由和响应 |\n| `SharedSession` | `src/mcp/shared/session.py` | 会话基类，封装 JSON-RPC 消息处理逻辑 |\n| `MCPServer` | `src/mcp/server/mcpserver/server.py` | 高层服务器 API，整合资源、工具、提示管理 |\n| `ResourceManager` | `src/mcp/server/mcpserver/resources/` | 资源注册、模板管理和资源读取 |\n| `ToolHandler` | `内置于 MCPServer` | 工具注册、参数验证和执行 |\n\n资料来源：[src/mcp/shared/session.py:1-50](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/session.py)\n\n## 3. 会话层详解\n\n### 3.1 SharedSession 基类\n\n`SharedSession` 是客户端和服务端会话的共同基类，封装了 JSON-RPC 2.0 协议的通用逻辑。\n\n**核心职责：**\n- 消息队列管理\n- 请求-响应对应关系维护\n- Cancellation token 处理\n- 消息发送和接收\n\n```mermaid\ngraph LR\n subgraph SharedSession\n Queue[消息队列]\n Requests[待处理请求]\n Handlers[消息处理器]\n end\n \n subgraph 消息类型\n Request[Request 请求]\n Response[Response 响应]\n Notification[Notification 通知]\n end\n \n Queue --> Handlers\n Requests --> Handlers\n Request -->|等待响应| Requests\n Response -->|匹配请求| Requests\n Notification -->|无需响应| Queue\n```\n\n资料来源：[src/mcp/shared/session.py:50-150](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/session.py)\n\n### 3.2 客户端会话\n\n`ClientSession` 扩展了 SharedSession，添加了客户端特定的功能：\n\n```python\nclass ClientSession(SharedSession):\n # 核心方法\n async def initialize() -> InitializeResult\n async def list_tools() -> list[Tool]\n async def call_tool(name: str, arguments: dict) -> CallToolResult\n async def list_resources() -> list[Resource]\n async def list_resource_templates() -> list[ResourceTemplate]\n async def read_resource(uri: str | AnyUrl) -> ReadResourceResult\n async def list_prompts() -> list[Prompt]\n async def get_prompt(name: str, arguments: dict) -> GetPromptResult\n```\n\n**客户端初始化流程：**\n\n```mermaid\nsequenceDiagram\n participant Client\n participant ClientSession\n participant Server\n \n Client->>ClientSession: 创建会话\n ClientSession->>Server: 发送 initialize 请求\n Server->>ServerSession: 处理初始化\n ServerSession-->>ClientSession: 返回 InitializeResult\n ClientSession->>Client: 通知初始化完成\n Client->>ClientSession: 发送已接收通知\n ClientSession->>Server: 发送 notifications/initialized\n```\n\n资料来源：[src/mcp/client/session.py:100-200](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/session.py)\n\n### 3.3 服务端会话\n\n`ServerSession` 负责处理来自客户端的请求和调用服务端处理器。\n\n```python\nclass ServerSession(SharedSession):\n # 核心回调\n on_list_tools: Optional[Callback[...]]\n on_call_tool: Optional[Callback[...]]\n on_list_resources: Optional[Callback[...]]\n on_read_resource: Optional[Callback[...]]\n on_list_resource_templates: Optional[Callback[...]]\n on_list_prompts: Optional[Callback[...]]\n on_get_prompt: Optional[Callback[...]]\n```\n\n资料来源：[src/mcp/server/session.py:50-120](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/session.py)\n\n## 4. 消息协议\n\n### 4.1 JSON-RPC 2.0 实现\n\nMCP 基于 JSON-RPC 2.0 规范，定义了三类消息：\n\n| 消息类型 | 描述 | 必须包含字段 |\n|---------|------|-------------|\n| `JSONRPCRequest` | 请求消息，需要对方响应 | `jsonrpc`, `id`, `method` |\n| `JSONRPCResponse` | 响应消息 | `jsonrpc`, `id`, `result` |\n| `JSONRPCError` | 错误响应 | `jsonrpc`, `id`, `error` |\n| `JSONRPCNotification` | 通知消息，无需响应 | `jsonrpc`, `method` |\n\n```python\nclass JSONRPCMessage(BaseModel):\n \"\"\"JSON-RPC 消息基类\"\"\"\n jsonrpc: Literal[\"2.0\"] = \"2.0\"\n\nclass JSONRPCRequest(JSONRPCMessage):\n \"\"\"带方法调用的请求\"\"\"\n id: RequestId\n method: str\n params: Optional[dict[str, Any]] = None\n\nclass JSONRPCResponse(JSONRPCMessage):\n \"\"\"成功响应\"\"\"\n id: Union[int, str]\n result: Any\n\nclass JSONRPCError(JSONRPCMessage):\n \"\"\"错误响应\"\"\"\n id: Union[int, str]\n error: ErrorData\n```\n\n资料来源：[src/mcp/types/jsonrpc.py:20-80](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types/jsonrpc.py)\n\n### 4.2 错误代码定义\n\n| 错误码 | 名称 | 用途 |\n|-------|------|------|\n| `-32700` | Parse Error | JSON 解析失败 |\n| `-32600` | Invalid Request | 无效的请求对象 |\n| `-32601` | Method Not Found | 方法不存在 |\n| `-32602` | Invalid Params | 无效的参数 |\n| `-32603` | Internal Error | 内部错误 |\n| `-32000` | Connection Closed | 连接已关闭 |\n| `-32001` | Request Timeout | 请求超时 |\n\n## 5. MCP Server 高级 API\n\n`MCPServer` 是构建 MCP 服务器的高层入口，封装了资源管理、工具处理、提示管理和认证功能。\n\n### 5.1 初始化参数\n\n```python\nclass MCPServer:\n def __init__(\n self,\n name: str = \"mcp-server\",\n version: str = \"1.0.0\",\n settings: ServerSettings | None = None,\n resources: list[Resource] | None = None,\n tools: list[Callable] | None = None,\n prompts: list[Prompt] | None = None,\n instructions: str | None = None,\n lifespan: LifespanContextManager | None = None,\n ) -> None:\n```\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `name` | `str` | 服务器名称 |\n| `version` | `str` | 服务器版本 |\n| `settings` | `ServerSettings` | 服务器配置选项 |\n| `resources` | `list[Resource]` | 初始资源列表 |\n| `tools` | `list[Callable]` | 可调用工具列表 |\n| `prompts` | `list[Prompt]` | 预定义提示列表 |\n| `instructions` | `str` | 服务器使用说明 |\n| `lifespan` | `LifespanContextManager` | 生命周期管理器 |\n\n资料来源：[src/mcp/server/mcpserver/server.py:100-150](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n\n### 5.2 核心方法\n\n```python\nclass MCPServer:\n # 资源管理\n async def list_resources() -> list[MCPResource]\n async def list_resource_templates() -> list[MCPResourceTemplate]\n async def read_resource(uri: AnyUrl | str) -> Iterable[ReadResourceContents]\n \n # 工具管理\n def add_tool(\n fn: Callable[..., Any],\n name: str | None = None,\n title: str | None = None,\n description: str | None = None,\n annotations: Annotations | None = None,\n ) -> None:\n \n # 提示管理\n def add_prompt(prompt: Prompt) -> None\n async def list_prompts() -> list[MCPPrompt]\n async def get_prompt(name: str, arguments: dict | None) -> MCPPrompt\n \n # 生命周期\n async def run_async()\n def streamable_http_app() -> ASGIApp\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py:200-300](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n\n## 6. 资源系统\n\n### 6.1 资源类型\n\nMCP 支持两种主要资源类型：\n\n| 类型 | 文件路径 | 描述 |\n|------|----------|------|\n| `FunctionResource` | `resources/types.py` | 从函数动态生成的资源 |\n| `FileResource` | `resources/types.py` | 读取本地文件的资源 |\n\n```python\nclass FunctionResource(Resource):\n \"\"\"从函数动态生成的资源\"\"\"\n uri: AnyUrl\n name: str\n title: Optional[str] = None\n description: Optional[str] = None\n mime_type: str = \"text/plain\"\n fn: Callable[..., Any] # 实际读取函数\n\nclass FileResource(Resource):\n \"\"\"读取本地文件的资源\"\"\"\n path: Path # 必须是绝对路径\n is_binary: bool = False # 是否二进制读取\n mime_type: str = \"text/plain\"\n```\n\n资料来源：[src/mcp/server/mcpserver/resources/types.py:50-100](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n\n### 6.2 资源读取流程\n\n```mermaid\ngraph TD\n Client[Client] -->|read_resource| ServerSession\n ServerSession -->|路由| MCPServer\n MCPServer -->|获取资源| ResourceManager\n ResourceManager -->|验证URI| URI解析\n URI解析 -->|查找资源| ResourceRegistry\n ResourceRegistry -->|返回| Resource\n Resource -->|调用read方法| FunctionResource\n FunctionResource -->|执行函数| ReadFunction\n ReadFunction -->|返回内容| ReadResourceContents\n```\n\n## 7. 认证系统\n\n### 7.1 OAuth 2.0 支持\n\nMCP 支持 OAuth 2.0 认证流程，包括：\n\n- **授权码流程** (Authorization Code Flow)\n- **客户端凭证流程** (Client Credentials Flow)\n- **令牌刷新** (Token Refresh)\n- **令牌撤销** (Token Revocation)\n\n```mermaid\ngraph LR\n subgraph 认证流程\n Client -->|1. 授权请求| AuthServer\n AuthServer -->|2. 授权码| Client\n Client -->|3. 令牌请求| AuthServer\n AuthServer -->|4. 访问令牌| Client\n Client -->|5. 受保护资源| ResourceServer\n ResourceServer -->|6. 资源| Client\n end\n \n subgraph 组件\n AuthServer[授权服务器]\n ResourceServer[资源服务器]\n end\n```\n\n资料来源：[src/mcp/server/auth/routes.py:50-150](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/auth/routes.py)\n\n### 7.2 认证配置\n\n```python\nclass AuthServerProvider(Protocol):\n \"\"\"认证服务器提供者协议\"\"\"\n async def get_auth_server_metadata(self, issuer_url: AnyHttpUrl) -> OAuthServerMetadata: ...\n async def create_authorization_url(self, ...) -> tuple[str, str]: ... # url, state\n async def handle_authorization_callback(self, ...) -> Tokens: ...\n async def refresh_access_token(self, ...) -> Tokens: ...\n\nclass TokenVerifier(Protocol):\n \"\"\"令牌验证器协议\"\"\"\n async def verify(self, token: str) -> TokenMetadata: ...\n```\n\n### 7.3 受保护资源元数据\n\nRFC 9728 兼容的受保护资源元数据端点：\n\n```python\ndef build_resource_metadata_url(resource_server_url: AnyHttpUrl) -> AnyHttpUrl:\n \"\"\"\n 构建 RFC 9728 合规的受保护资源元数据 URL\n \n 在主机和资源路径之间插入 /.well-known/oauth-protected-resource\n 例如: https://example.com/mcp -> https://example.com/.well-known/oauth-protected-resource/mcp\n \"\"\"\n```\n\n## 8. 交互式任务\n\n### 8.1 Elicitation 与 Sampling\n\nMCP 支持服务端向客户端发起交互请求：\n\n| 交互类型 | 方向 | 用途 |\n|---------|------|------|\n| `Elicitation` | Server → Client | 请求用户确认或输入 |\n| `Sampling` | Server → Client | 请求 LLM 补全 |\n\n```mermaid\ngraph TD\n subgraph Elicitation 流程\n Server -->|task.elicit()| Task\n Task -->|发送请求| Client\n Client -->|用户输入| ElicitResult\n ElicitResult -->|返回| Task\n Task -->|完成| Result\n end\n \n subgraph Sampling 流程\n Server2 -->|task.create_message()| Task2\n Task2 -->|发送请求| Client2\n Client2 -->|LLM响应| CreateMessageResult\n CreateMessageResult -->|返回| Task2\n Task2 -->|完成| Result2\n end\n```\n\n### 8.2 任务上下文\n\n```python\nclass TaskContext:\n \"\"\"任务上下文，用于处理交互式任务\"\"\"\n \n async def elicit(\n self,\n message: str,\n requested_schema: dict[str, Any],\n **kwargs,\n ) -> ElicitResult:\n \"\"\"发送 elicitation 请求给客户端\"\"\"\n \n async def create_message(\n self,\n messages: list[CreateMessageRequestParam],\n **kwargs,\n ) -> CreateMessageResult:\n \"\"\"发送 sampling 请求给客户端的 LLM\"\"\"\n```\n\n资料来源：[src/mcp/server/experimental/task_context.py:100-200](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/experimental/task_context.py)\n\n## 9. 传输层\n\n### 9.1 Stdio 传输\n\n适用于本地进程间通信，通过标准输入/输出流传输 JSON-RPC 消息。\n\n```python\nfrom mcp.server.stdio import stdio_server\n\nasync with stdio_server() as streams:\n await app.run(streams[0], streams[1], app.create_initialization_options())\n```\n\n### 9.2 Streamable HTTP 传输\n\n适用于网络通信，支持长轮询和 Server-Sent Events。\n\n```python\nfrom mcp.server import MCPServer\nimport uvicorn\n\napp = MCPServer(...)\nuvicorn.run(app.streamable_http_app(), host=\"127.0.0.1\", port=8000)\n```\n\n| 传输方式 | 适用场景 | 特点 |\n|---------|---------|------|\n| Stdio | 本地进程、CLI 工具 | 低延迟，简单可靠 |\n| Streamable HTTP | 网络服务、分布式部署 | 支持双向通信，可扩展 |\n\n## 10. 消息类型定义\n\n### 10.1 核心类型\n\n| 类型 | 描述 |\n|------|------|\n| `Tool` | 可调用工具的定义 |\n| `Resource` | 数据资源的定义 |\n| `ResourceTemplate` | 参数化资源模板 |\n| `Prompt` | 预定义提示模板 |\n| `SamplingMessage` | 采样消息 |\n| `Completion` | 自动补全建议 |\n\n```python\nclass Tool(BaseModel):\n name: str\n description: Optional[str] = None\n inputSchema: dict[str, Any]\n annotations: Optional[Annotations] = None\n\nclass Resource(BaseModel):\n uri: AnyUrl\n name: str\n description: Optional[str] = None\n mimeType: Optional[str] = None\n\nclass Prompt(BaseModel):\n name: str\n description: Optional[str] = None\n arguments: Optional[list[PromptArgument]] = None\n```\n\n资料来源：[src/mcp/types/_types.py:50-150](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/types/_types.py)\n\n## 11. 服务器设置\n\n```python\nclass ServerSettings(BaseModel):\n \"\"\"服务器配置选项\"\"\"\n \n host: str | None = None\n port: int | None = None\n streamable_http_path: str | None = None\n streamable_http_session_timeout: float = 60.0\n streamable_http_max_session_duration: float | None = None\n streamable_http_session_keepalive: bool = True\n \n # 功能开关\n capabilities: ServerCapabilities = Field(default_factory=ServerCapabilities)\n \n # 重复检测\n warn_on_duplicate_tools: bool = True\n warn_on_duplicate_resources: bool = True\n warn_on_duplicate_prompts: bool = True\n \n # 认证配置\n auth: AuthSettings | None = None\n \n # 生命周期\n lifespan: LifespanContextManager | None = None\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py:50-100](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n\n## 12. 总结\n\nMCP Python SDK 的架构设计遵循以下原则：\n\n1. **分层设计**：清晰的分层架构，从传输层到高层 API\n2. **协议标准化**：基于 JSON-RPC 2.0，确保互操作性\n3. **灵活性**：支持多种传输方式和认证机制\n4. **可扩展性**：通过回调和中间件支持自定义行为\n5. **类型安全**：全面的类型提示和 Pydantic 模型验证\n\n这套架构使得开发者能够快速构建支持外部数据和工具交互的 AI 应用服务器和客户端。\n\n---\n\n\n\n## 传输协议实现\n\n### 相关页面\n\n相关主题：[系统架构与核心组件](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/client/stdio.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/stdio.py)\n- [src/mcp/client/sse.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/sse.py)\n- [src/mcp/client/websocket.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/websocket.py)\n- [src/mcp/client/streamable_http.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/streamable_http.py)\n- [src/mcp/server/stdio.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/stdio.py)\n- [src/mcp/server/sse.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/sse.py)\n- [src/mcp/server/websocket.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/websocket.py)\n- [src/mcp/server/streamable_http.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/streamable_http.py)\n- [src/mcp/server/streamable_http_manager.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/streamable_http_manager.py)\n- [examples/snippets/servers/streamable_http_basic_mounting.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_http_basic_mounting.py)\n- [examples/snippets/servers/streamable_starlette_mount.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_starlette_mount.py)\n \n\n# 传输协议实现\n\n## 概述\n\nMCP (Model Context Protocol) Python SDK 支持多种传输协议实现，用于客户端与服务器之间的通信。这些传输层负责在进程间或网络间传递 MCP 协议消息，支持不同的部署场景和性能需求。\n\n## 支持的传输协议类型\n\n| 传输类型 | 客户端模块 | 服务器模块 | 典型用途 |\n|---------|-----------|-----------|---------|\n| stdio | `mcp.client.stdio` | `mcp.server.stdio` | 本地进程通信 |\n| Streamable HTTP | `mcp.client.streamable_http` | `mcp.server.streamable_http` | HTTP-based 远程通信 |\n| SSE | `mcp.client.sse` | `mcp.server.sse` | 服务端推送事件 |\n| WebSocket | `mcp.client.websocket` | `mcp.server.websocket` | 双向实时通信 |\n\n## 核心传输协议\n\n### Stdio 传输\n\nStdio 传输是最基础的进程间通信方式，适用于本地运行的 MCP 服务器。客户端通过标准输入/输出流与服务器通信，协议消息以 JSON 格式编码。\n\n```mermaid\ngraph LR\n A[Client Process] -->|stdin| B[Server Process]\n B -->|stdout| A\n```\n\n**客户端用法示例：**\n\n```python\nfrom mcp.client.stdio import stdio_client\nfrom mcp.client import ClientSession\n\nasync def main():\n async with stdio_client() as streams:\n async with ClientSession(*streams) as session:\n await session.initialize()\n # 使用 session 进行 RPC 调用\n```\n\n**服务器用法示例：**\n\n```python\nfrom mcp.server.stdio import stdio_server\n\nasync def main():\n async with stdio_server() as streams:\n await app.run(streams[0], streams[1], app.create_initialization_options())\n```\n\n资料来源：[src/mcp/client/stdio.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/stdio.py)，[src/mcp/server/stdio.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/stdio.py)\n\n### Streamable HTTP 传输\n\nStreamable HTTP 是为 Web 环境设计的传输协议，支持通过 HTTP 请求/响应流式传输 MCP 消息。该协议兼容 RESTful 架构，便于与现有 Web 基础设施集成。\n\n**协议特点：**\n\n- 支持分块传输编码 (Chunked Transfer Encoding)\n- 支持 Server-Sent Events 用于服务端推送\n- 与 Starlette、FastAPI 等 ASGI 框架兼容\n- 支持 SSE 作为服务端推送机制\n\n资料来源：[src/mcp/client/streamable_http.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/streamable_http.py)，[src/mcp/server/streamable_http.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/streamable_http.py)\n\n**服务器配置示例：**\n\n```python\nfrom mcp.server import Server\nfrom mcp.server.streamable_http import StreamableHTTPServerHandler\nimport uvicorn\n\napp = Server(\"my-mcp-server\")\n\nif __name__ == \"__main__\":\n uvicorn.run(\n app.streamable_http_app(),\n host=\"127.0.0.1\",\n port=8000\n )\n```\n\n资料来源：[examples/snippets/servers/streamable_http_basic_mounting.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_http_basic_mounting.py)\n\n### SSE 传输\n\nServer-Sent Events (SSE) 传输允许服务器主动向客户端推送消息，适用于需要服务器端实时通知的场景。\n\n```mermaid\ngraph LR\n A[HTTP Client] -->|POST /mcp| B[MCP Server]\n B -->|SSE Stream| A\n A -->|GET /sse| B\n```\n\n资料来源：[src/mcp/client/sse.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/sse.py)，[src/mcp/server/sse.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/sse.py)\n\n### WebSocket 传输\n\nWebSocket 传输提供全双工通信通道，适用于需要低延迟、双向实时交互的应用场景。\n\n**WebSocket 服务器配置：**\n\n```python\nfrom mcp.server.websocket import websocket_server\nimport uvicorn\n\nasync def main():\n async with websocket_server(app) as streams:\n await app.run(streams[0], streams[1], app.create_initialization_options())\n\nif __name__ == \"__main__\":\n uvicorn.run(main, host=\"127.0.0.1\", port=8000)\n```\n\n资料来源：[src/mcp/server/websocket.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/websocket.py)，[src/mcp/client/websocket.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/websocket.py)\n\n## Streamable HTTP 服务器管理\n\n`streamable_http_manager` 模块提供了高级的 HTTP 传输管理功能，包括会话管理、请求路由和生命周期管理。\n\n### 核心组件\n\n| 组件 | 职责 |\n|------|------|\n| `StreamableHTTPServerHandler` | 处理 HTTP 请求，解析 MCP 协议消息 |\n| `HTTPAuthorizationMiddleware` | 处理认证头和授权验证 |\n| `HTTPStreamManager` | 管理流式响应和 SSE 连接 |\n\n资料来源：[src/mcp/server/streamable_http_manager.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/streamable_http_manager.py)\n\n### 挂载到 ASGI 应用\n\nMCP HTTP 服务器可以挂载到现有的 ASGI 应用中：\n\n```python\nfrom starlette.applications import Starlette\nfrom starlette.routing import Route, Mount\nfrom mcp.server.streamable_http_manager import StreamableHTTPManager\n\nasync def app_scope(request):\n # MCP 服务器逻辑\n pass\n\nmcp_app = Starlette(\n routes=[\n Mount(\"/mcp\", app=app_scope),\n ]\n)\n```\n\n资料来源：[examples/snippets/servers/streamable_starlette_mount.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/streamable_starlette_mount.py)\n\n## 传输协议选择指南\n\n```mermaid\ngraph TD\n A[选择传输协议] --> B{部署场景}\n B -->|本地进程| C[Stdio]\n B -->|Web 服务| D[Streamable HTTP]\n B -->|实时推送| E[SSE]\n B -->|低延迟交互| F[WebSocket]\n \n C --> G[最简单、最可靠]\n D --> H[兼容性最佳]\n E --> I[单向实时通信]\n F --> J[全双工通信]\n```\n\n**选择建议：**\n\n| 场景 | 推荐协议 | 原因 |\n|------|---------|------|\n| Claude Desktop 集成 | Stdio | 原生支持，最稳定 |\n| Web 应用后端 | Streamable HTTP | 标准化 HTTP 接口 |\n| 实时监控面板 | SSE | 服务端推送能力强 |\n| 游戏/协作工具 | WebSocket | 最低延迟 |\n\n## 协议消息格式\n\n所有传输协议都使用相同的 JSON-RPC 2.0 消息格式：\n\n```json\n// 请求消息\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"method\": \"tools/list\",\n \"params\": {}\n}\n\n// 响应消息\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"result\": {\n \"tools\": [...]\n }\n}\n\n// 错误消息\n{\n \"jsonrpc\": \"2.0\",\n \"id\": 1,\n \"error\": {\n \"code\": -32600,\n \"message\": \"Invalid Request\"\n }\n}\n```\n\n## 服务器示例对比\n\n### Stdio 模式\n\n```python\nfrom mcp.server import Server\nfrom mcp.server.stdio import stdio_server\n\napp = Server(\"example-server\")\n\nasync def main():\n async with stdio_server() as streams:\n await app.run(\n streams[0],\n streams[1],\n app.create_initialization_options()\n )\n```\n\n资料来源：[src/mcp/server/stdio.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/stdio.py)\n\n### HTTP 模式\n\n```python\nfrom mcp.server import Server\nfrom mcp.server.streamable_http import streamable_http_server\nimport uvicorn\n\napp = Server(\"example-server\")\n\n@click.command()\n@click.option(\"--port\", default=8000, help=\"Port to listen on\")\n@click.option(\n \"--transport\",\n type=click.Choice([\"stdio\", \"streamable-http\"]),\n default=\"stdio\",\n)\ndef main(port: int, transport: str) -> int:\n if transport == \"streamable-http\":\n uvicorn.run(\n app.streamable_http_app(),\n host=\"127.0.0.1\",\n port=port\n )\n else:\n # stdio 模式\n ...\n```\n\n资料来源：[examples/servers/simple-pagination/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-pagination/server.py)\n\n## 传输层安全性\n\nMCP SDK 的传输层本身不实现加密，安全性依赖于底层传输协议：\n\n| 传输类型 | 安全建议 |\n|---------|---------|\n| Stdio | 仅用于本地通信，使用文件系统权限控制 |\n| Streamable HTTP | 配合 HTTPS/TLS 使用，添加认证中间件 |\n| WebSocket | 使用 WSS (WebSocket Secure) |\n| SSE | 通过 HTTPS 提供服务 |\n\n## 常见问题\n\n### Q: Stdio 和 HTTP 传输可以同时使用吗？\n\n可以。服务器可以同时监听多种传输协议，通过不同的启动参数选择：\n\n```bash\n# Stdio 模式\npython server.py --transport stdio\n\n# HTTP 模式\npython server.py --transport streamable-http --port 8000\n```\n\n### Q: 如何调试传输层问题？\n\n1. 启用调试日志：`export MCP_LOG_LEVEL=debug`\n2. 使用 HTTP 抓包工具查看请求/响应\n3. 对于 stdio，使用 `script` 命令记录会话\n\n## 相关资源\n\n- [MCP 协议规范](https://modelcontextprotocol.io/specification)\n- [Python SDK 源码仓库](https://github.com/modelcontextprotocol/python-sdk)\n- [示例服务器集合](../servers/)\n\n---\n\n\n\n## FastMCP 服务器框架\n\n### 相关页面\n\n相关主题：[资源、资源模板、提示与工具](#page-resources-prompts-tools), [上下文与会话管理](#page-context-session)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n- [src/mcp/server/mcpserver/resources/base.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/base.py)\n- [src/mcp/server/mcpserver/resources/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n- [src/mcp/cli/cli.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/cli/cli.py)\n- [examples/snippets/servers/completion.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/completion.py)\n- [examples/servers/simple-pagination/mcp_simple_pagination/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-pagination/mcp_simple_pagination/server.py)\n- [examples/servers/simple-task-interactive/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-task-interactive/README.md)\n- [examples/servers/simple-task/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-task/README.md)\n- [examples/clients/simple-task-interactive-client/README.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/clients/simple-task-interactive-client/README.md)\n \n\n# FastMCP 服务器框架\n\nFastMCP 是 MCP (Model Context Protocol) Python SDK 中提供的高级服务器框架，旨在简化 MCP 服务器的开发流程。与底层 `Server` 类相比，FastMCP 提供了更简洁的 API 设计，让开发者能够以更少的代码量快速构建功能完整的 MCP 服务器。\n\n## 框架概述\n\n### 设计目标\n\nFastMCP 框架的核心设计理念是**简化**与**约定优于配置**。它将 MCP 协议中复杂的内部机制抽象化，为开发者提供直观的装饰器和上下文管理器，使服务器开发变得更加直观和高效。\n\n### 架构分层\n\n```\n┌─────────────────────────────────────────────────────────┐\n│ FastMCP API 层 │\n│ (装饰器 @tool, @resource, @prompt, 生命周期管理) │\n├─────────────────────────────────────────────────────────┤\n│ Server 核心层 │\n│ (工具管理、资源管理、提示管理、认证) │\n├─────────────────────────────────────────────────────────┤\n│ 传输层 │\n│ (stdio, streamable-http, SSE) │\n├─────────────────────────────────────────────────────────┤\n│ MCP 协议层 │\n│ (JSON-RPC 消息处理、协议序列化) │\n└─────────────────────────────────────────────────────────┘\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py:1-150]()\n\n## 核心组件\n\n### 1. 服务器实例\n\nFastMCP 服务器通过 `FastMCP` 类进行初始化和配置。该类封装了底层的 `Server` 实例，并提供了便捷的方法来注册工具、资源和提示。\n\n**初始化参数：**\n\n| 参数 | 类型 | 说明 | 默认值 |\n|------|------|------|--------|\n| `name` | `str` | 服务器名称 | `\"fastmcp\"` |\n| `title` | `str \\| None` | 服务器显示标题 | `None` |\n| `description` | `str \\| None` | 服务器描述 | `None` |\n| `version` | `str \\| None` | 服务器版本 | `None` |\n| `lifespan` | `Lifespan \\| None` | 生命周期上下文管理器 | `None` |\n\n资料来源：[src/mcp/server/mcpserver/server.py:80-120]()\n\n### 2. 工具系统 (Tools)\n\n工具是 MCP 服务器中最核心的交互组件。FastMCP 提供了 `@tool` 装饰器来简化工具注册过程。\n\n```python\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"my-server\")\n\n@mcp.tool()\nasync def get_weather(city: str) -> str:\n \"\"\"获取城市天气信息\"\"\"\n return f\"{city} 的天气是晴天\"\n```\n\n**工具装饰器参数：**\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `name` | `str \\| None` | 工具名称，默认使用函数名 |\n| `description` | `str \\| None` | 工具描述，来自函数 docstring |\n| `annotations` | `Annotations \\| None` | 工具注解（只读、幂等等） |\n\n资料来源：[src/mcp/server/fastmcp/tools/base.py](), [src/mcp/server/fastmcp/tools/tool_manager.py]()\n\n### 3. 资源系统 (Resources)\n\n资源用于向客户端暴露可读取的数据。FastMCP 支持两种类型的资源：\n\n#### 3.1 静态资源\n\n```python\n@mcp.resource(\"config://app\")\ndef get_config() -> str:\n \"\"\"返回应用配置\"\"\"\n return '{\"version\": \"1.0.0\"}'\n```\n\n#### 3.2 资源模板\n\n```python\n@mcp.resource(\"users://{user_id}/profile\")\nasync def get_user_profile(user_id: str) -> str:\n \"\"\"返回用户资料\"\"\"\n return f'{{\"id\": \"{user_id}\", \"name\": \"User {user_id}\"}}'\n```\n\n资料来源：[src/mcp/server/mcpserver/resources/base.py:1-50](), [src/mcp/server/mcpserver/resources/types.py]()\n\n### 4. 提示系统 (Prompts)\n\n提示用于定义可复用的 LLM 交互模板。\n\n```python\n@mcp.prompt()\ndef code_review_prompt(repo: str, pr: str) -> str:\n \"\"\"代码审查提示模板\"\"\"\n return f\"请审查仓库 {repo} 的 PR #{pr} 中的代码变更\"\n```\n\n资料来源：[src/mcp/server/fastmcp/prompts/base.py](), [src/mcp/server/fastmcp/prompts/manager.py]()\n\n## 上下文管理\n\n### Context 对象\n\n每个工具和资源函数都可以接收一个 `Context` 对象作为第一个参数，该对象提供了访问服务器功能的能力。\n\n```python\n@mcp.tool()\nasync def search_files(\n context: Context,\n pattern: str,\n path: str = \".\"\n) -> list[str]:\n # 访问资源管理器\n resources = await context.list_resources()\n \n # 创建子任务\n task = await context.create_task(\"another_tool\", {\"arg\": \"value\"})\n \n return results\n```\n\n资料来源：[src/mcp/server/fastmcp/context.py]()\n\n### 生命周期管理\n\nFastMCP 支持通过 `lifespan` 参数管理服务器启动和关闭时的资源。\n\n```python\nfrom contextlib import asynccontextmanager\nfrom mcp.server.fastmcp import FastMCP\n\n@asynccontextmanager\nasync def lifespan(server: FastMCP):\n # 启动时初始化资源\n await db.connect()\n await cache.initialize()\n \n yield\n \n # 关闭时清理资源\n await cache.close()\n await db.disconnect()\n\nmcp = FastMCP(\"my-server\", lifespan=lifespan)\n```\n\n资料来源：[examples/snippets/servers/lifespan_example.py](), [src/mcp/server/mcpserver/server.py:100-110]()\n\n## 异常处理\n\nFastMCP 定义了框架专用的异常类型，便于细粒度的错误处理。\n\n| 异常类型 | 说明 |\n|----------|------|\n| `ResourceError` | 资源访问错误 |\n| `ToolError` | 工具执行错误 |\n| `PromptError` | 提示处理错误 |\n| `ValidationError` | 参数验证错误 |\n\n资料来源：[src/mcp/server/fastmcp/exceptions.py]()\n\n## 运行方式\n\n### 标准输入输出模式 (Stdio)\n\n适用于命令行工具和 Claude Desktop 集成：\n\n```python\n# my_server.py\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"my-server\")\n\n@mcp.tool()\nasync def hello(name: str) -> str:\n return f\"Hello, {name}!\"\n\nif __name__ == \"__main__\":\n mcp.run()\n```\n\n运行命令：\n```bash\nmcp run my_server.py\n```\n\n资料来源：[examples/servers/simple-pagination/mcp_simple_pagination/server.py:40-60]()\n\n### HTTP 传输模式\n\n适用于 Web 环境，支持流式响应：\n\n```python\nimport uvicorn\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"my-server\")\n\n# ... 定义工具和资源 ...\n\nif __name__ == \"__main__\":\n uvicorn.run(mcp.streamable_http_app(), host=\"0.0.0.0\", port=8000)\n```\n\n资料来源：[examples/servers/simple-pagination/mcp_simple_pagination/server.py:45-55]()\n\n## 任务系统 (Experimental)\n\nFastMCP 支持实验性的异步任务功能，允许长时间运行的工具返回任务引用而非直接结果。\n\n```python\n@mcp.tool()\nasync def long_running_task(context: Context) -> str:\n # 创建任务\n task = await context.create_task()\n \n # 发送进度更新\n await task.send_progress(\"开始处理...\")\n \n # 模拟长时间操作\n await asyncio.sleep(2)\n \n # 完成任务\n return \"任务完成\"\n```\n\n使用 `call_tool_as_task` 方法调用：\n\n```python\nresult = await session.experimental.call_tool_as_task(\"long_running_task\", {})\ntask_id = result.task.task_id\n\n# 轮询任务状态\nfinal = await session.experimental.get_task_result(task_id, CallToolResult)\n```\n\n资料来源：[examples/servers/simple-task/README.md](), [examples/clients/simple-task-interactive-client/README.md]()\n\n## 高级功能\n\n### 资源订阅与通知\n\nFastMCP 支持资源变更通知机制，服务器可以主动推送更新给客户端：\n\n```python\n@mcp.resource(\"data://stream\")\nasync def streaming_data(context: Context):\n async for update in data_generator():\n # 发送资源更新通知\n await context.notify_resources_changed()\n yield update\n```\n\n### 交互式任务 (Elicitation)\n\n服务器可以请求用户输入确认：\n\n```python\n@mcp.tool()\nasync def confirm_delete(context: Context, filename: str) -> str:\n # 请求用户确认\n result = await context.elicit(\n message=f\"确认删除 {filename}?\",\n actions=[{\"label\": \"确认\", \"value\": \"yes\"}, {\"label\": \"取消\", \"value\": \"no\"}]\n )\n \n if result.action == \"accept\":\n return f\"已删除 {filename}\"\n return \"操作已取消\"\n```\n\n资料来源：[examples/servers/simple-task-interactive/README.md]()\n\n### 采样 (Sampling)\n\n服务器可以请求 LLM 生成内容：\n\n```python\n@mcp.tool()\nasync def generate_text(context: Context, topic: str) -> str:\n result = await context.sample(\n prompt=f\"写一首关于 {topic} 的诗\",\n system=\"你是一位诗人\"\n )\n return result.content\n```\n\n资料来源：[examples/clients/simple-task-interactive-client/README.md]()\n\n## 与底层 Server 类的关系\n\nFastMCP 是对底层 `Server` 类的高级封装。两者的主要区别：\n\n| 特性 | `Server` | `FastMCP` |\n|------|----------|-----------|\n| API 复杂度 | 高 | 低 |\n| 代码量 | 较多 | 简洁 |\n| 灵活性 | 高 | 中等 |\n| 装饰器支持 | 无 | 有 |\n| 适用场景 | 深度定制 | 快速开发 |\n\n资料来源：[src/mcp/server/mcpserver/server.py:80-150]()\n\n## 最佳实践\n\n### 1. 类型注解\n\n所有公共 API 必须包含类型注解：\n\n```python\n@mcp.tool()\nasync def process_data(context: Context, data: list[str], options: dict[str, Any] | None = None) -> dict[str, Any]:\n \"\"\"处理数据并返回结果\"\"\"\n ...\n```\n\n### 2. 错误处理\n\n使用框架定义的异常类型，并在文档中说明可能抛出的异常：\n\n```python\n@mcp.tool()\nasync def read_resource(context: Context, uri: str) -> str:\n \"\"\"读取资源内容\n \n Raises:\n ResourceError: 资源不存在或无法访问\n \"\"\"\n try:\n return await context.read_resource(uri)\n except Exception:\n logger.exception(f\"Error reading resource {uri}\")\n raise ResourceError(f\"Error reading resource {uri}\")\n```\n\n### 3. 资源管理\n\n在 `lifespan` 中正确管理外部资源连接：\n\n```python\n@asynccontextmanager\nasync def lifespan(server: FastMCP):\n # 使用 try/finally 确保清理\n connection = await create_connection()\n try:\n server._connection = connection\n yield\n finally:\n await connection.close()\n```\n\n资料来源：[AGENTS.md - Exception Handling]()\n\n---\n\n\n\n## 资源、资源模板、提示与工具\n\n### 相关页面\n\n相关主题：[FastMCP 服务器框架](#page-fastmcp)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/server/mcpserver/resources/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/types.py)\n- [src/mcp/server/mcpserver/resources/templates.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/resources/templates.py)\n- [src/mcp/server/mcpserver/utilities/func_metadata.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/utilities/func_metadata.py)\n- [examples/snippets/servers/basic_tool.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_tool.py)\n- [examples/snippets/servers/basic_resource.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_resource.py)\n- [examples/snippets/servers/basic_prompt.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_prompt.py)\n- [examples/mcpserver/weather_structured.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/mcpserver/weather_structured.py)\n- [examples/servers/simple-prompt/mcp_simple_prompt/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/servers/simple-prompt/mcp_simple_prompt/server.py)\n \n\n# 资源、资源模板、提示与工具\n\n## 概述\n\nMCP SDK 提供了四类核心功能用于构建 MCP 服务器：**资源（Resources）**、**资源模板（Resource Templates）**、**提示（Prompts）** 和 **工具（Tools）**。这些功能使服务器能够向 LLM 客户端暴露数据、模板和可执行函数，从而实现丰富的工具调用和数据检索能力。\n\n---\n\n## 资源（Resources）\n\n### 定义与作用\n\n资源是 MCP 协议中用于向 LLM 客户端暴露数据的机制。资源可以是静态内容（如文件）或动态生成的内容（如函数返回值）。客户端可以通过 URI 来读取特定的资源内容。\n\n### 资源类型\n\nMCP SDK 支持两种主要的资源类型：\n\n| 类型 | 说明 | 适用场景 |\n|------|------|----------|\n| `FunctionResource` | 由函数动态生成内容 | API 响应、实时数据 |\n| `FileResource` | 读取本地文件内容 | 配置文件、文档、静态资源 |\n\n### FunctionResource\n\n`FunctionResource` 允许将函数作为资源暴露给客户端。服务器调用该函数并返回其结果作为资源内容。\n\n**创建方式：**\n\n```python\nfrom mcp.server.mcpserver.resources.types import FunctionResource\n\nresource = FunctionResource.from_function(\n fn=my_function,\n uri=\"myapp://data\",\n name=\"my_data\",\n title=\"我的数据\",\n description=\"获取应用程序数据\",\n mime_type=\"application/json\"\n)\n```\n\n**关键特性：**\n\n- 自动类型验证：`from_function` 方法内部使用 `validate_call` 验证函数参数 资料来源：[src/mcp/server/mcpserver/resources/types.py:40]()\n\n### FileResource\n\n`FileResource` 用于读取本地文件系统中的文件。路径必须为绝对路径。\n\n```python\nfrom mcp.server.mcpserver.resources.types import FileResource\nfrom pathlib import Path\n\nresource = FileResource(\n path=Path(\"/etc/app/config.json\"),\n name=\"config\",\n mime_type=\"application/json\"\n)\n```\n\n**路径验证：**\n\nFileResource 使用 Pydantic 验证器确保路径是绝对路径：\n\n```python\n@pydantic.field_validator(\"path\")\n@classmethod\ndef validate_absolute_path(cls, path: Path) -> Path:\n \"\"\"确保路径是绝对路径\"\"\"\n if not path.is_absolute():\n raise ValueError(\"Path must be absolute\")\n return path\n```\n\n资料来源：[src/mcp/server/mcpserver/resources/types.py:65-72]()\n\n### 注册资源到服务器\n\n资源通过装饰器或直接方法注册到服务器：\n\n```python\n@server.resource(\n uri=\"myapp://config\",\n name=\"config\",\n title=\"应用程序配置\",\n description=\"获取当前配置\"\n)\ndef get_config():\n return {\"setting\": \"value\"}\n```\n\n---\n\n## 资源模板（Resource Templates）\n\n### 概念\n\n资源模板是带有 URI 参数的资源，允许动态生成资源内容。它们使用 URI 模板语法（如 `github://repos/{owner}/{repo}`）来定义参数化的资源端点。\n\n### 工作原理\n\n```mermaid\ngraph TD\n A[客户端请求] --> B[解析 URI 模板]\n B --> C{参数验证}\n C -->|通过| D[调用处理函数]\n C -->|失败| E[返回错误]\n D --> F[返回资源内容]\n```\n\n### URI 模板与参数验证\n\n资源模板通过比对 URI 参数和函数参数来确保正确性：\n\n```python\nuri_params = extract_uri_params(uri)\nfunc_params = extract_func_params(fn)\n\nif uri_params != func_params:\n raise ValueError(\n f\"Mismatch between URI parameters {uri_params} and function parameters {func_params}\"\n )\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py:95-100]()\n\n### 注册资源模板\n\n```python\n@server.list_resource_templates\nasync def handle_list_resource_templates():\n return [\n types.ResourceTemplate(\n uri_template=\"github://repos/{owner}/{repo}\",\n name=\"github_repo\",\n title=\"GitHub 仓库\",\n description=\"获取 GitHub 仓库信息\",\n arguments=[\n types.PromptArgument(\n name=\"owner\",\n description=\"仓库所有者\",\n required=True,\n ),\n types.PromptArgument(\n name=\"repo\",\n description=\"仓库名称\",\n required=True,\n ),\n ],\n )\n ]\n```\n\n### 模板资源示例\n\n在补全示例中，模板资源可以提供上下文感知的自动补全：\n\n```python\n# 基于 GitHub 资源模板的补全示例\nif isinstance(ref, ResourceTemplateReference):\n if ref.uri == \"github://repos/{owner}/{repo}\" and argument.name == \"repo\":\n if context and context.arguments.get(\"owner\") == \"modelcontextprotocol\":\n repos = [\"python-sdk\", \"typescript-sdk\", \"specification\"]\n return Completion(values=repos, has_more=False)\n```\n\n资料来源：[examples/snippets/servers/completion.py:10-18]()\n\n---\n\n## 提示（Prompts）\n\n### 定义\n\n提示是预定义的模板，可包含消息和参数。它们允许服务器定义可重用的提示模式，客户端可以根据需要调用。\n\n### 提示结构\n\n```mermaid\ngraph LR\n A[Prompt 定义] --> B[名称和描述]\n A --> C[参数列表]\n A --> D[消息模板]\n C --> C1[必需参数]\n C --> C2[可选参数]\n D --> D1[角色]\n D --> D2[内容]\n```\n\n### 提示注册\n\n使用装饰器方式注册提示：\n\n```python\n@server.prompt(\n name=\"simple\",\n title=\"简单提示\",\n description=\"一个基础提示示例\"\n)\ndef simple_prompt(context: str = None, topic: str = None):\n return {\n \"messages\": [\n {\n \"role\": \"user\",\n \"content\": {\n \"type\": \"text\",\n \"text\": f\"请帮我{context or ''}关于{topic or '通用'}的内容\"\n }\n }\n ]\n }\n```\n\n资料来源：[examples/snippets/servers/basic_prompt.py:8-30]()\n\n### 提示处理器\n\n对于更复杂的提示逻辑，可以使用处理器函数：\n\n```python\nasync def handle_list_prompts() -> list[types.ListPromptsResult]:\n return [\n types.ListPromptsResult(\n name=\"simple\",\n description=\"一个简单提示\",\n arguments=[\n types.PromptArgument(\n name=\"context\",\n description=\"额外上下文\",\n required=False,\n ),\n types.PromptArgument(\n name=\"topic\",\n description=\"关注的主题\",\n required=False,\n ),\n ],\n )\n ]\n\nasync def handle_get_prompt(\n ctx: ServerRequestContext,\n params: types.GetPromptRequestParams\n) -> types.GetPromptResult:\n if params.name != \"simple\":\n raise ValueError(f\"Unknown prompt: {params.name}\")\n\n arguments = params.arguments or {}\n return types.GetPromptResult(\n messages=create_messages(\n context=arguments.get(\"context\"),\n topic=arguments.get(\"topic\")\n ),\n description=\"一个带有可选参数的简单提示\",\n )\n```\n\n资料来源：[examples/servers/simple-prompt/mcp_simple_prompt/server.py:28-58]()\n\n### 使用 Prompt 类\n\n也可以直接实例化 Prompt 类：\n\n```python\nfrom mcp.types import Prompt\n\nprompt = Prompt(\n name=\"my_prompt\",\n description=\"我的提示\",\n arguments=[\n PromptArgument(\n name=\"param1\",\n description=\"参数说明\",\n required=True\n )\n ]\n)\n\nserver.add_prompt(prompt)\n```\n\n---\n\n## 工具（Tools）\n\n### 概述\n\n工具是服务器暴露给 LLM 客户端的可执行函数。客户端可以调用工具来执行服务器上的操作。\n\n### 工具注册\n\n使用 `@server.tool()` 装饰器注册工具：\n\n```python\n@server.tool(\n name=\"get_weather\",\n description=\"获取指定城市的天气信息\",\n)\nasync def get_weather(city: str, country: str | None = None) -> str:\n \"\"\"获取天气信息\"\"\"\n return f\"城市 {city} 的天气是晴天\"\n```\n\n资料来源：[examples/snippets/servers/basic_tool.py:1-12]()\n\n### 工具方法\n\n#### add_tool()\n\n直接方法添加工具：\n\n```python\nserver.add_tool(\n fn=my_function,\n name=\"tool_name\",\n title=\"工具标题\",\n description=\"工具描述\",\n annotations={\"readOnlyHint\": True}\n)\n```\n\n#### tool() 装饰器\n\n装饰器方式添加工具，支持更多配置：\n\n```python\n@server.tool(\n name=\"custom_tool\",\n title=\"自定义工具\",\n description=\"带参数的工具\",\n annotations={\n \"readOnlyHint\": True,\n \"openWorldHint\": False\n }\n)\nasync def custom_tool(param1: str, param2: int = 10):\n return {\"result\": f\"处理了 {param1} 和 {param2}\"}\n```\n\n### 工具注解（Annotations）\n\n工具可以附带注解来提供额外元数据：\n\n| 注解 | 类型 | 说明 |\n|------|------|------|\n| `readOnlyHint` | bool | 指示工具是否只读 |\n| `openWorldHint` | bool | 指示工具是否访问外部世界 |\n| `idempotentHint` | bool | 指示工具是否幂等 |\n| `interactiveHint` | bool | 指示工具是否需要交互 |\n\n### 工具返回类型\n\n工具可以返回多种格式的内容：\n\n```python\n@server.tool()\nasync def structured_tool():\n \"\"\"返回结构化内容\"\"\"\n return {\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"文本内容\"\n },\n {\n \"type\": \"resource\",\n \"resource\": {\n \"uri\": \"myapp://data\",\n \"mimeType\": \"application/json\",\n \"text\": '{\"key\": \"value\"}'\n }\n }\n ],\n \"isError\": False\n }\n```\n\n资料来源：[examples/mcpserver/weather_structured.py:20-45]()\n\n### 函数元数据提取\n\n工具注册时会自动提取函数元数据：\n\n```python\nfn = validate_call(fn)\nfunc_name = name or fn.__name__\n```\n\n关键元数据包括：\n- **函数名称**：用于标识工具\n- **参数信息**：名称、类型、默认值、文档字符串\n- **返回类型注解**：用于文档和验证\n\n---\n\n## 完整示例\n\n### 集成资源、提示和工具\n\n```python\nfrom mcp.server import Server\nfrom mcp.types import Resource, Tool, Prompt\n\n# 创建服务器实例\napp = Server(\"my-mcp-server\")\n\n# 注册资源\n@app.resource(uri=\"myapp://config\", name=\"config\")\ndef get_config():\n return {\"version\": \"1.0\", \"debug\": True}\n\n# 注册资源模板\n@app.list_resource_templates\nasync def handle_list_templates():\n return [\n types.ResourceTemplate(\n uri_template=\"myapp://users/{user_id}\",\n name=\"user_profile\",\n description=\"获取用户资料\",\n arguments=[\n types.PromptArgument(name=\"user_id\", description=\"用户ID\", required=True)\n ],\n )\n ]\n\n# 注册提示\n@app.prompt(name=\"greet\", title=\"问候语\")\ndef greet_prompt(name: str):\n return {\n \"messages\": [\n {\"role\": \"user\", \"content\": {\"type\": \"text\", \"text\": f\"你好，{name}！\"}}\n ]\n }\n\n# 注册工具\n@app.tool(name=\"calculate\", description=\"执行计算\")\ndef calculate(a: int, b: int, operation: str = \"add\"):\n if operation == \"add\":\n return a + b\n return a - b\n\n# 运行服务器\nasync def main():\n from mcp.server.stdio import stdio_server\n async with stdio_server() as streams:\n await app.run(streams[0], streams[1], app.create_initialization_options())\n```\n\n---\n\n## 架构关系图\n\n```mermaid\ngraph TD\n subgraph MCP服务器\n A[Server 实例]\n \n subgraph 资源层\n B[Resources 资源]\n C[Resource Templates 资源模板]\n end\n \n subgraph 交互层\n D[Prompts 提示]\n E[Tools 工具]\n end\n end\n \n F[LLM 客户端] --> |读取资源| B\n F --> |读取模板| C\n F --> |调用提示| D\n F --> |执行工具| E\n \n B --> |内容| F\n C --> |动态内容| F\n D --> |消息| F\n E --> |结果| F\n \n G[函数] --> |FunctionResource| B\n H[文件] --> |FileResource| B\n```\n\n---\n\n## 最佳实践\n\n### 资源设计\n\n1. **使用有意义的 URI**：资源 URI 应清晰表达资源的用途\n2. **选择正确的 MIME 类型**：确保客户端正确解析资源内容\n3. **提供描述**：为每个资源添加清晰的描述\n\n### 提示设计\n\n1. **保持简洁**：提示应清晰、聚焦\n2. **提供默认值**：可选参数应有合理的默认值\n3. **文档完整**：说明每个参数的用途\n\n### 工具设计\n\n1. **幂等性**：优先设计幂等工具\n2. **错误处理**：使用适当的异常处理，返回有意义的错误信息\n3. **类型注解**：为所有参数和返回值提供类型注解\n4. **使用注解**：通过注解描述工具行为\n\n---\n\n## 错误处理\n\n### 资源错误\n\n```python\nasync def read_resource(self, uri: AnyUrl | str, context: Context | None = None):\n try:\n resource = await self._resource_manager.get_resource(uri, context)\n except ValueError as exc:\n raise ResourceError(f\"Unknown resource: {uri}\") from exc\n\n try:\n content = await resource.read()\n return [ReadResourceContents(content=content, mime_type=resource.mime_type)]\n except Exception as exc:\n logger.exception(f\"Error getting resource {uri}\")\n raise ResourceError(f\"Error reading resource {uri}\") from exc\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py:54-66]()\n\n### 关键原则\n\n- **捕获具体异常**：使用 `except (OSError, PermissionError)` 等具体异常类型\n- **使用 logger.exception()**：记录异常时不包含异常对象在消息中\n- **避免裸 except**：除非在顶级处理器中\n- **转换异常**：将内部异常转换为客户端可理解的错误\n\n---\n\n\n\n## 上下文与会话管理\n\n### 相关页面\n\n相关主题：[FastMCP 服务器框架](#page-fastmcp), [系统架构与核心组件](#page-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/server/context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/context.py)\n- [src/mcp/client/context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/context.py)\n- [src/mcp/shared/_context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/_context.py)\n- [src/mcp/server/fastmcp/utilities/context_injection.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/utilities/context_injection.py)\n- [src/mcp/server/fastmcp/utilities/types.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/utilities/types.py)\n- [examples/snippets/servers/tool_progress.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/tool_progress.py)\n \n\n# 上下文与会话管理\n\n## 概述\n\n在 Model Context Protocol (MCP) SDK 中，**上下文（Context）** 和 **会话管理** 是连接服务器端与客户端、传递请求元数据、管理生命周期状态的核心机制。上下文对象在请求处理链中携带关键信息，使开发者能够在工具执行、资源访问、提示渲染等场景中访问请求级别的元数据和服务器状态。\n\n上下文管理系统的设计遵循以下原则：\n\n- **请求级别隔离**：每个请求都有独立的上下文实例\n- **类型安全**：通过泛型参数确保上下文类型的一致性\n- **懒加载初始化**：在需要时才创建完整的上下文对象\n- **与生命周期集成**：上下文与服务器的 lifespan 机制协同工作\n\n资料来源：[src/mcp/shared/_context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/_context.py)\n\n---\n\n## 架构设计\n\n### 上下文分层模型\n\nMCP SDK 的上下文系统采用分层架构，不同层次的上下文服务于不同的功能范围：\n\n```mermaid\ngraph TB\n subgraph \"服务端上下文\"\n S1[ServerContext]\n S2[RequestContext]\n S3[ToolContext]\n end\n \n subgraph \"客户端上下文\"\n C1[ClientContext]\n C2[SessionContext]\n end\n \n subgraph \"共享上下文\"\n SH[SharedContext]\n end\n \n S1 --> S2\n S2 --> S3\n C1 --> C2\n S1 -.->|共享基类| SH\n C1 -.->|共享基类| SH\n```\n\n### 核心组件表\n\n| 组件 | 文件位置 | 职责 |\n|------|---------|------|\n| `Context` | `src/mcp/shared/_context.py` | 共享上下文基类，提供通用上下文功能 |\n| `ServerContext` | `src/mcp/server/context.py` | 服务端上下文，包含服务器引用和请求信息 |\n| `ClientContext` | `src/mcp/client/context.py` | 客户端上下文，管理会话状态和请求追踪 |\n| `ContextInjector` | `src/mcp/server/fastmcp/utilities/context_injection.py` | 上下文注入工具，用于 FastMCP 简化开发 |\n| `ProgressToken` | `相关类型定义 | 支持进度回调和长时间运行任务 |\n\n资料来源：[src/mcp/shared/_context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/_context.py)、[src/mcp/server/context.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/context.py)\n\n---\n\n## 服务端上下文\n\n### ServerContext 结构\n\n服务端上下文在 `src/mcp/server/context.py` 中定义，包含以下核心属性：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `mcp_server` | `MCPServer` | 对应的 MCP 服务器实例 |\n| `request_id` | `str \\| None` | 当前请求的唯一标识符 |\n| `session_id` | `str \\| None` | 客户端会话标识符 |\n| `client_info` | `ClientInfo \\| None` | 客户端信息（元数据） |\n| `capabilities` | `ServerCapabilities \\| None` | 客户端支持的能力列表 |\n\n### 上下文创建与管理\n\n在服务端请求处理中，上下文通过以下模式创建：\n\n```python\nasync def read_resource(\n self, uri: AnyUrl | str, context: Context[LifespanResultT, Any] | None = None\n) -> Iterable[ReadResourceContents]:\n \"\"\"通过 URI 读取资源。\"\"\"\n if context is None:\n context = Context(mcp_server=self)\n try:\n resource = await self._resource_manager.get_resource(uri, context)\n except ValueError as exc:\n raise ResourceError(f\"Unknown resource: {uri}\") from exc\n```\n\n资料来源：[src/mcp/server/mcpserver/server.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/mcpserver/server.py)\n\n### 生命周期集成\n\n上下文与服务器的 lifespan 机制深度集成，支持泛型类型参数 `LifespanResultT`：\n\n```python\nContext[LifespanResultT, Any]\n```\n\n这种设计允许：\n\n- 在上下文初始化阶段注入特定的生命周期数据\n- 在请求处理过程中访问生命周期状态\n- 类型安全的上下文传递\n\n---\n\n## 客户端上下文\n\n### ClientContext 结构\n\n客户端上下文管理会话状态和请求追踪：\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `session` | `ClientSession` | 活跃的客户端会话 |\n| `request_id` | `str` | 当前请求的唯一标识符 |\n| `timeout` | `timedelta \\| None` | 请求超时配置 |\n\n### 会话管理流程\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Session as ClientSession\n participant Context as ClientContext\n participant Server as MCP Server\n \n Client->>Session: 建立连接\n Session->>Context: 创建上下文\n Context->>Server: 初始化请求\n Server-->>Context: 初始化响应\n Context-->>Session: 会话就绪\n Session-->>Client: 连接就绪\n \n loop 请求处理\n Client->>Context: 发起请求\n Context->>Server: 发送请求\n Server-->>Context: 返回结果\n Context-->>Client: 传递结果\n end\n```\n\n---\n\n## 上下文注入机制\n\n### ContextInjector 用法\n\nFastMCP 提供了 `ContextInjector` 工具类，用于在函数调用时自动注入上下文：\n\n```python\nfrom mcp.server.fastmcp.utilities.context_injection import ContextInjector\n\n# 定义注入器\ninjector = ContextInjector()\n\n# 在工具函数中使用\n@injector.inject\nasync def my_tool(ctx: Context, arg1: str, arg2: int):\n \"\"\"带上下文注入的工具函数。\"\"\"\n # 直接使用 ctx，无需手动传递\n await ctx.info(f\"Processing {arg1} with {arg2}\")\n```\n\n### 注入工作流程\n\n```mermaid\ngraph LR\n A[工具调用] --> B[ContextInjector]\n B --> C{检查上下文参数}\n C -->|已存在| D[使用现有上下文]\n C -->|不存在| E[创建新上下文]\n D --> F[执行业务逻辑]\n E --> F\n F --> G[返回结果]\n```\n\n资料来源：[src/mcp/server/fastmcp/utilities/context_injection.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/server/fastmcp/utilities/context_injection.py)\n\n---\n\n## 进度令牌与长时间运行任务\n\n### ProgressToken 支持\n\nMCP SDK 通过 `ProgressToken` 支持长时间运行任务的进度报告：\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `token` | `str \\| NumberToken` | 进度令牌标识符 |\n| `progress` | `float \\| None` | 当前进度值（0-100） |\n| `total` | `float \\| None` | 任务总量 |\n\n### 工具进度示例\n\n```python\nasync def handle_call_tool(\n ctx: ServerRequestContext, params: types.CallToolRequestParams\n) -> types.CallToolResult:\n \"\"\"处理工具调用，支持进度报告。\"\"\"\n progress_token = ctx.progress_token\n \n if progress_token:\n await progress_token(\n progress=0,\n total=100,\n )\n \n # 模拟长时间任务\n for i in range(10):\n await progress_token(progress=(i + 1) * 10)\n await asyncio.sleep(0.1)\n \n return types.CallToolResult(\n content=[types.TextContent(type=\"text\", text=\"Task completed\")]\n )\n```\n\n资料来源：[examples/snippets/servers/tool_progress.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/tool_progress.py)\n\n### 进度报告时序图\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Server as MCP 服务器\n participant Tool as 工具函数\n \n Client->>Server: call_tool with progressToken\n Server->>Tool: 初始化任务\n Tool->>Tool: 步骤 1\n Tool->>Client: progress(25)\n Tool->>Tool: 步骤 2\n Tool->>Client: progress(50)\n Tool->>Tool: 步骤 3\n Tool->>Client: progress(75)\n Tool->>Tool: 步骤 4\n Tool->>Client: progress(100)\n Tool->>Client: 返回结果\n```\n\n---\n\n## 快速参考\n\n### 上下文获取模式\n\n| 场景 | 推荐方式 |\n|------|---------|\n| 服务端请求处理 | 通过函数参数接收 `Context` |\n| 资源读取 | `context = Context(mcp_server=self)` |\n| FastMCP 工具 | 使用 `@injector.inject` 装饰器 |\n| 客户端调用 | 通过 `ClientSession` 的上下文方法 |\n\n### 常见错误处理\n\n| 错误类型 | 处理方式 |\n|---------|---------|\n| `ValueError: Unknown resource` | 检查 URI 格式是否正确 |\n| `ResourceError` | 资源读取失败，查看日志详情 |\n| `Context not available` | 确保在正确的请求上下文中调用 |\n\n### 日志记录规范\n\n根据项目规范，异常处理必须使用 `logger.exception()`：\n\n```python\nexcept Exception as exc:\n logger.exception(f\"Error getting resource {uri}\")\n raise ResourceError(f\"Error reading resource {uri}\") from exc\n```\n\n资料来源：[AGENTS.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/AGENTS.md)\n\n---\n\n## 最佳实践\n\n1. **始终传递上下文**：在工具函数签名中包含 `Context` 参数，以便访问服务器状态和元数据\n\n2. **避免硬编码依赖**：使用上下文提供的接口而非直接引用全局状态\n\n3. **正确处理异步**：上下文操作可能涉及异步 I/O，确保在 async 函数中使用\n\n4. **利用进度报告**：对于耗时的工具调用，使用 `progress_token` 提供用户反馈\n\n5. **类型安全**：使用泛型参数确保上下文类型的编译时检查\n\n---\n\n## 相关资源\n\n- [MCP 协议规范](https://modelcontextprotocol.io/specification)\n- [FastMCP 文档](./fastmcp.md)\n- [服务器开发指南](./servers.md)\n- [客户端开发指南](./clients.md)\n\n---\n\n\n\n## 客户端开发指南\n\n### 相关页面\n\n相关主题：[客户端 OAuth 认证](#page-client-auth), [传输协议实现](#page-transports)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/client/client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/client.py)\n- [src/mcp/client/session.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/session.py)\n- [src/mcp/client/session_group.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/session_group.py)\n- [src/mcp/shared/response_router.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/response_router.py)\n- [examples/snippets/clients/completion_client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/completion_client.py)\n- [examples/snippets/clients/stdio_client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/stdio_client.py)\n- [examples/snippets/clients/parsing_tool_results.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/parsing_tool_results.py)\n \n\n# 客户端开发指南\n\n本指南详细介绍如何使用 Model Context Protocol (MCP) Python SDK 开发客户端应用程序。MCP 客户端负责连接到 MCP 服务器，发现服务器提供的功能（工具、资源、提示），并通过标准化的协议与服务器进行交互。\n\n## 核心概念\n\n### 客户端架构概述\n\nMCP 客户端采用分层架构设计，主要包含以下组件：\n\n| 组件 | 职责 | 源码位置 |\n|------|------|----------|\n| `Client` | 连接管理和生命周期控制 | `src/mcp/client/client.py` |\n| `ClientSession` | 会话状态管理和请求处理 | `src/mcp/client/session.py` |\n| `SessionGroup` | 多会话协调管理 | `src/mcp/client/session_group.py` |\n| `ResponseRouter` | 响应路由和请求-响应匹配 | `src/mcp/shared/response_router.py` |\n\n### 传输层支持\n\nMCP SDK 支持多种传输方式，客户端可根据场景选择合适的传输协议：\n\n```mermaid\ngraph TD\n A[MCP 客户端] --> B{传输方式选择}\n B --> C[stdio 传输]\n B --> D[streamable-http 传输]\n B --> E[SSE 传输]\n C --> F[标准输入输出通信]\n D --> G[HTTP 流式传输]\n E --> H[Server-Sent Events]\n```\n\n## 连接管理\n\n### 建立 stdio 连接\n\n标准输入输出传输适用于本地进程间通信，是最常用的连接方式之一。\n\n```python\n# 资料来源：examples/snippets/clients/stdio_client.py\nimport asyncio\nfrom mcp.client.stdio import stdio_client\nfrom mcp.client.client import Client\n\nasync def main():\n async with stdio_client() as (read, write):\n async with Client(\n read,\n write,\n client_protocol,\n asyncio.create_task\n ) as client:\n await client.initialize()\n # 使用客户端功能\n```\n\n### 建立 HTTP 连接\n\n对于需要远程访问的场景，可使用 streamable-http 传输方式：\n\n```python\n# 连接到远程 MCP 服务器\nfrom mcp.client.streamable_http import streamable_http_client\n\nasync def connect_to_remote():\n async with streamable_http_client(\n \"http://localhost:8000/mcp\",\n timeout=30\n ) as (read, write, get_next_message):\n # 处理连接\n```\n\n### 客户端初始化流程\n\n```mermaid\nsequenceDiagram\n participant 客户端 as MCP 客户端\n participant 服务器 as MCP 服务器\n \n 客户端->>服务器: 发送 Initialize 请求\n 客户端->>服务器: 包含协议版本和客户端能力\n \n 服务器-->>客户端: 返回服务器信息\n 服务器-->>客户端: 协议版本确认\n 服务器-->>客户端: 服务器能力集\n \n 客户端->>服务器: 发送 Initialized 通知\n Note over 客户端: 连接建立完成\n```\n\n初始化时客户端需要指定支持的协议版本和自身能力集，服务器确认后将返回其能力信息。\n\n## 会话管理\n\n### ClientSession 的核心职责\n\n`ClientSession` 类是客户端与服务器交互的核心抽象，负责管理会话状态和协调各类请求：\n\n```python\n# 资料来源：src/mcp/client/session.py\nclass ClientSession:\n \"\"\"MCP 客户端会话核心类\"\"\"\n \n async def initialize(self) -> InitializeResult:\n \"\"\"初始化与服务器的连接\"\"\"\n \n async def list_tools(self) -> list[Tool]:\n \"\"\"列出服务器提供的所有工具\"\"\"\n \n async def call_tool(\n self, \n name: str, \n arguments: dict[str, Any] | None = None\n ) -> CallToolResult:\n \"\"\"调用服务器上的工具\"\"\"\n \n async def list_resources(self) -> list[Resource]:\n \"\"\"列出服务器提供的资源\"\"\"\n \n async def read_resource(self, uri: AnyUrl | str) -> Iterable[ReadResourceContents]:\n \"\"\"读取指定资源的内容\"\"\"\n \n async def list_prompts(self) -> list[Prompt]:\n \"\"\"列出服务器提供的提示模板\"\"\"\n \n async def get_prompt(\n self, \n name: str, \n arguments: dict[str, Any] | None = None\n ) -> GetPromptResult:\n \"\"\"获取并渲染提示模板\"\"\"\n```\n\n### 调用工具\n\n工具调用是 MCP 协议最核心的功能之一，允许客户端请求服务器执行特定操作：\n\n```python\n# 资料来源：examples/snippets/clients/stdio_client.py\nasync def call_server_tool():\n result = await session.call_tool(\n \"get_time\",\n arguments={\"timezone\": \"UTC\"}\n )\n \n # 处理返回结果\n for content in result.content:\n if content.type == \"text\":\n print(f\"工具返回: {content.text}\")\n```\n\n### 解析工具返回结果\n\n工具调用可能返回多种类型的内容，客户端需要正确处理：\n\n```python\n# 资料来源：examples/snippets/clients/parsing_tool_results.py\nfrom mcp.types import TextContent, ImageContent, EmbeddedResource\n\ndef parse_tool_result(result):\n \"\"\"解析工具调用结果\"\"\"\n for content in result.content:\n # 处理文本内容\n if isinstance(content, TextContent):\n print(f\"文本: {content.text}\")\n \n # 处理图片内容\n elif isinstance(content, ImageContent):\n print(f\"图片 MIME 类型: {content.mimeType}\")\n # content.data 包含 base64 编码的图片数据\n \n # 处理嵌入资源\n elif isinstance(content, EmbeddedResource):\n print(f\"嵌入资源: {content.resource.uri}\")\n```\n\n### 资源管理\n\n#### 列出可用资源\n\n```python\nasync def list_available_resources():\n resources = await session.list_resources()\n for resource in resources:\n print(f\"资源: {resource.name}\")\n print(f\" URI: {resource.uri}\")\n print(f\" 描述: {resource.description}\")\n```\n\n#### 读取资源内容\n\n```python\nasync def read_resource_content(uri: str):\n contents = await session.read_resource(uri)\n for content in contents:\n print(f\"内容类型: {content.mimeType}\")\n print(f\"数据: {content.content}\")\n```\n\n### 提示模板\n\n服务器可以定义可复用的提示模板，客户端可以获取并使用这些模板：\n\n```python\n# 资料来源：examples/snippets/clients/completion_client.py\nasync def use_prompt_template():\n # 列出所有可用提示\n prompts = await session.list_prompts()\n \n # 获取特定提示\n result = await session.get_prompt(\n \"simple\",\n arguments={\"context\": \"额外上下文\", \"topic\": \"技术主题\"}\n )\n \n # result.messages 包含渲染后的消息列表\n for message in result.messages:\n print(f\"角色: {message.role}\")\n print(f\"内容: {message.content}\")\n```\n\n## 自动补全支持\n\nMCP 支持在客户端实现自动补全功能，提升用户体验：\n\n```python\n# 资料来源：examples/snippets/servers/completion.py\nfrom mcp.types import ResourceTemplateReference, Completion\n\nasync def request_completion(ref: ResourceTemplateReference, argument: str):\n \"\"\"请求服务器提供补全建议\"\"\"\n \n # 对于 GitHub 资源模板的特定参数提供补全\n if ref.uri == \"github://repos/{owner}/{repo}\":\n if argument == \"repo\":\n # 返回预定义的补全值\n return Completion(\n values=[\"python-sdk\", \"typescript-sdk\", \"specification\"],\n has_more=False\n )\n```\n\n## 响应路由机制\n\n`ResponseRouter` 负责管理异步请求与响应的匹配，确保请求能够正确路由到对应的处理程序：\n\n```mermaid\ngraph LR\n A[请求发送] --> B[RequestTracker]\n B --> C{匹配响应}\n C -->|找到匹配| D[触发回调]\n C -->|未找到| E[等待响应]\n D --> F[返回结果]\n E --> C\n```\n\n```python\n# 资料来源：src/mcp/shared/response_router.py\nclass ResponseRouter:\n \"\"\"响应路由器，管理请求-响应映射\"\"\"\n \n async def send_request(self, method: str, params: dict) -> Any:\n \"\"\"发送请求并等待响应\"\"\"\n \n def __aiter__(self):\n \"\"\"异步迭代器，用于接收传入的消息\"\"\"\n```\n\n## 多会话管理\n\n### SessionGroup 的使用\n\n当客户端需要同时管理多个服务器连接时，可使用 `SessionGroup` 进行统一管理：\n\n```python\n# 资料来源：src/mcp/client/session_group.py\nfrom mcp.client.session_group import SessionGroup\n\nasync def manage_multiple_sessions():\n async with SessionGroup() as group:\n # 添加多个会话\n session1 = await group.add_server(stdio_server())\n session2 = await group.add_server(http_server(\"http://server2/mcp\"))\n \n # 批量操作\n all_tools = await group.request(\n lambda s: s.list_tools(),\n is_error_ok=True\n )\n```\n\n### SessionGroup 主要方法\n\n| 方法 | 功能 | 源码位置 |\n|------|------|----------|\n| `add_server()` | 添加新服务器会话 | `src/mcp/client/session_group.py` |\n| `remove_session()` | 移除指定会话 | `src/mcp/client/session_group.py` |\n| `request()` | 向所有会话发送请求 | `src/mcp/client/session_group.py` |\n| `notify()` | 向所有会话发送通知 | `src/mcp/client/session_group.py` |\n\n## 错误处理\n\n### 异常处理规范\n\n根据项目开发规范，客户端代码应遵循以下异常处理原则：\n\n```python\n# 资料来源：AGENTS.md\nimport logging\n\nlogger = logging.getLogger(__name__)\n\ntry:\n result = await session.call_tool(\"tool_name\", {})\nexcept Exception as exc:\n # 使用 logger.exception() 而非 logger.error()\n logger.exception(\"工具调用失败\")\n # 不要在日志消息中包含异常详情\n```\n\n### 推荐实践\n\n| 场景 | 异常类型 | 处理方式 |\n|------|----------|----------|\n| JSON 解析 | `json.JSONDecodeError` | 捕获并返回有意义的错误信息 |\n| 网络错误 | `ConnectionError`, `TimeoutError` | 重试或降级处理 |\n| 资源不存在 | `ValueError` | 捕获并提示用户 |\n| 授权失败 | `PermissionError` | 清理会话并重新认证 |\n\n**禁止使用裸的 `except Exception:`** — 应始终捕获具体异常类型。\n\n## 认证集成\n\n### OAuth 认证流程\n\n对于需要认证的 MCP 服务器，客户端需要实现完整的 OAuth 流程：\n\n```python\n# 资料来源：examples/clients/simple-auth-client/mcp_simple_auth_client/main.py\nclass CallbackHandler(BaseHTTPRequestHandler):\n \"\"\"处理 OAuth 回调\"\"\"\n \n def do_GET(self):\n query_params = parse_qs(urlparse(self.path).query)\n \n if \"code\" in query_params and \"state\" in query_params:\n # 获取授权码\n self.callback_data[\"authorization_code\"] = query_params[\"code\"][0]\n self.callback_data[\"state\"] = query_params[\"state\"][0]\n self.send_response(200)\n \n elif \"error\" in query_params:\n # 处理错误\n self.callback_data[\"error\"] = query_params[\"error\"][0]\n self.send_response(400)\n```\n\n### 环境配置\n\n| 环境变量 | 描述 | 默认值 |\n|----------|------|--------|\n| `MCP_SERVER_PORT` | MCP 服务器端口 | `8000` |\n| `MCP_TRANSPORT_TYPE` | 传输类型 | `streamable-http` |\n| `MCP_CLIENT_METADATA_URL` | 客户端元数据地址 | `None` |\n\n## 完整示例\n\n以下是一个功能完整的 MCP 客户端实现示例：\n\n```python\n# 资料来源：examples/snippets/clients/stdio_client.py\nimport asyncio\nfrom mcp.client.stdio import stdio_client\nfrom mcp.client.client import Client\nfrom mcp.protocol import ClientProtocol\n\nasync def run():\n async with stdio_client() as (read, write):\n client_protocol = ClientProtocol(\n read,\n write,\n asyncio.create_task\n )\n \n async with Client(\n read,\n write,\n client_protocol,\n asyncio.create_task\n ) as client:\n session = client_session = await client.create_session()\n await session.initialize()\n \n # 列出并调用工具\n tools = await session.list_tools()\n print(f\"可用工具: {[t.name for t in tools]}\")\n \n # 调用工具并处理结果\n result = await session.call_tool(\"get_time\", {\"a\": 1, \"b\": 3})\n \n # 解析返回内容\n result_unstructured = result.content[0]\n if hasattr(result_unstructured, 'text'):\n print(f\"工具结果: {result_unstructured.text}\")\n\ndef main():\n asyncio.run(run())\n\nif __name__ == \"__main__\":\n main()\n```\n\n## 开发工作流\n\n### 本地开发设置\n\n```bash\n# 克隆仓库\ngit clone https://github.com/modelcontextprotocol/python-sdk.git\n\n# 安装依赖\nuv sync --frozen --all-extras --dev\n\n# 安装预提交钩子\nuv tool install pre-commit --with pre-commit-uv --force-reinstall\n\n# 运行测试\nuv run pytest\n\n# 类型检查\nuv run pyright\n\n# 代码格式化\nuv run ruff format .\nuv run ruff check . --fix\n```\n\n### 调试技巧\n\n1. **启用详细日志**：在开发环境中启用 `logging.DEBUG` 级别可查看完整的协议交互\n2. **使用 stdio 传输**：本地调试时优先使用 stdio 传输，便于观察输入输出\n3. **单元测试**：为客户端代码编写单元测试，确保异常处理路径覆盖\n\n## 最佳实践总结\n\n| 类别 | 建议 |\n|------|------|\n| 连接管理 | 使用上下文管理器自动处理连接生命周期 |\n| 错误处理 | 捕获具体异常类型，使用 `logger.exception()` |\n| 类型提示 | 所有公共 API 必须包含类型注解 |\n| 异步代码 | 使用 `anyio` 而非 `asyncio` 进行测试 |\n| 资源清理 | 确保所有资源在异常情况下也能正确释放 |\n\n通过遵循本指南中的模式和实践，开发者可以构建稳定、可靠的 MCP 客户端应用程序，充分利用 Model Context Protocol 提供的强大功能。\n\n---\n\n\n\n## 客户端 OAuth 认证\n\n### 相关页面\n\n相关主题：[客户端开发指南](#page-client-development)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/client/auth/oauth2.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/auth/oauth2.py)\n- [src/mcp/client/auth/exceptions.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/auth/exceptions.py)\n- [src/mcp/client/auth/extensions/client_credentials.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/client/auth/extensions/client_credentials.py)\n- [src/mcp/shared/auth.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/auth.py)\n- [src/mcp/shared/auth_utils.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/src/mcp/shared/auth_utils.py)\n- [examples/snippets/clients/oauth_client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/oauth_client.py)\n \n\n# 客户端 OAuth 认证\n\n## 概述\n\nMCP Python SDK 的客户端 OAuth 认证模块为 MCP 客户端提供了完整的 OAuth 2.0 认证支持，包括授权码流程（Authorization Code Flow）和客户端凭证流程（Client Credentials Flow）。该模块基于 [RFC 6749](https://datatracker.ietf.org/doc/html/rfc6749)、[RFC 7636](https://datatracker.ietf.org/doc/html/rfc7636)（PKCE）、[RFC 8414](https://www.rfc-editor.org/rfc/rfc8414)（OAuth 授权服务器元数据）以及 [RFC 9728](https://www.rfc-editor.org/rfc/rfc9728)（受保护资源元数据）等标准规范实现。\n\n主要功能包括：\n\n- **动态客户端注册（DCR）**：自动向授权服务器注册客户端\n- **PKCE 支持**：增强授权码流程的安全性\n- **Token 管理**：自动刷新过期 Token\n- **元数据发现**：支持 RFC 8414 和 RFC 9728 规定的标准发现端点\n- **多认证方式**：支持 `client_secret_basic` 和 `client_secret_post`\n- **URL-based Client ID (CIMD)**：支持基于 URL 的客户端标识符\n\n资料来源：[src/mcp/client/auth/oauth2.py:1-50]()\n\n## 架构设计\n\n### 模块结构\n\n```\nsrc/mcp/client/auth/\n├── oauth2.py # 核心 OAuth2 实现\n├── exceptions.py # OAuth 异常定义\n├── utils.py # 工具函数\n└── extensions/\n └── client_credentials.py # 客户端凭证扩展\n\nsrc/mcp/shared/\n├── auth.py # 共享数据模型\n└── auth_utils.py # 共享工具函数\n```\n\n### 核心组件关系图\n\n```mermaid\ngraph TD\n subgraph \"客户端应用层\"\n A[MCP Client]\n B[OAuthClientProvider]\n end\n \n subgraph \"认证核心\"\n C[OAuthContext]\n D[TokenStorage]\n E[PKCEParameters]\n end\n \n subgraph \"认证扩展\"\n F[ClientCredentialsOAuthProvider]\n end\n \n subgraph \"共享模型\"\n G[OAuthClientMetadata]\n H[OAuthToken]\n I[OAuthMetadata]\n J[ProtectedResourceMetadata]\n end\n \n subgraph \"外部服务\"\n K[授权服务器]\n L[资源服务器]\n end\n \n A --> B\n B --> C\n B --> D\n B --> E\n F --> C\n G --> H\n I --> J\n B <--> K\n B <--> L\n```\n\n### OAuth 上下文数据流\n\n```mermaid\ngraph LR\n subgraph \"初始化阶段\"\n A1[server_url] --> C[OAuthContext]\n A2[client_metadata] --> C\n A3[storage] --> C\n end\n \n subgraph \"发现阶段\"\n C --> D1[发现受保护资源元数据]\n C --> D2[发现授权服务器元数据]\n D1 --> E1[protected_resource_metadata]\n D2 --> E2[oauth_metadata]\n end\n \n subgraph \"注册阶段\"\n C --> R1[动态客户端注册]\n R1 --> R2[client_info]\n end\n \n subgraph \"认证阶段\"\n R2 --> A1[授权请求]\n A1 --> T1[Token 交换]\n T1 --> T2[current_tokens]\n end\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:140-200]()\n\n## 核心数据模型\n\n### OAuthClientMetadata\n\n客户端元数据模型，用于动态客户端注册：\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `client_id` | `str` | 是 | 客户端标识符 |\n| `client_secret` | `str` | 否 | 客户端密钥 |\n| `redirect_uris` | `list[AnyUrl]` | 是 | 重定向 URI 列表 |\n| `grant_types` | `list[str]` | 否 | 支持的授权类型 |\n| `token_endpoint_auth_method` | `str` | 否 | Token 端点认证方法 |\n| `scope` | `str` | 否 | 请求的权限范围 |\n\n资料来源：[src/mcp/shared/auth.py:200-260]()\n\n### OAuthToken\n\nToken 数据模型：\n\n| 字段 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `access_token` | `str` | 是 | 访问令牌 |\n| `token_type` | `str` | 是 | Token 类型，通常为 \"Bearer\" |\n| `expires_at` | `float` | 是 | Token 过期时间戳 |\n| `refresh_token` | `str` | 否 | 刷新令牌 |\n| `expires_in` | `int` | 否 | Token 有效期（秒） |\n| `scope` | `str` | 否 | 授予的权限范围 |\n\n资料来源：[src/mcp/shared/auth.py:300-340]()\n\n### OAuthMetadata\n\n授权服务器元数据模型：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `issuer` | `str` | 授权服务器签发者标识 |\n| `authorization_endpoint` | `str` | 授权端点 URL |\n| `token_endpoint` | `str` | Token 端点 URL |\n| `registration_endpoint` | `str` | 客户端注册端点 |\n| `scopes_supported` | `list[str]` | 支持的权限范围 |\n| `response_types_supported` | `list[str]` | 支持的响应类型 |\n| `grant_types_supported` | `list[str]` | 支持的授权类型 |\n| `code_challenge_methods_supported` | `list[str]` | 支持的 PKCE 方法 |\n\n资料来源：[src/mcp/shared/auth.py:80-150]()\n\n### ProtectedResourceMetadata\n\n受保护资源元数据（RFC 9728）：\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `resource` | `str` | 资源服务器标识符 |\n| `authorization_servers` | `list[str]` | 关联的授权服务器列表 |\n| `scopes_supported` | `list[str]` | 资源支持的范围 |\n| `bearer_methods_supported` | `list[str]` | 支持的 Bearer Token 方法 |\n\n资料来源：[src/mcp/shared/auth.py:400-450]()\n\n### OAuthContext\n\nOAuth 流程上下文数据类：\n\n```python\n@dataclass\nclass OAuthContext:\n server_url: str\n client_metadata: OAuthClientMetadata\n storage: TokenStorage\n redirect_handler: Callable[[str], Awaitable[None]] | None\n callback_handler: Callable[[], Awaitable[tuple[str, str | None]]] | None\n timeout: float = 300.0\n client_metadata_url: str | None = None\n \n # 元数据发现结果\n protected_resource_metadata: ProtectedResourceMetadata | None = None\n oauth_metadata: OAuthMetadata | None = None\n auth_server_url: str | None = None\n protocol_version: str | None = None\n \n # 客户端信息\n client_info: OAuthClientInformationFull | None = None\n \n # Token 管理\n current_tokens: OAuthToken | None = None\n token_expiry_time: float | None = None\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:140-185]()\n\n## Token 存储接口\n\n### TokenStorage Protocol\n\n开发者需要实现 `TokenStorage` 接口来持久化 Token：\n\n```python\nclass TokenStorage(Protocol):\n \"\"\"Token 存储接口\"\"\"\n \n async def get_tokens(self) -> OAuthToken | None:\n \"\"\"获取存储的 Token\"\"\"\n ...\n \n async def set_tokens(self, tokens: OAuthToken) -> None:\n \"\"\"存储 Token\"\"\"\n ...\n \n async def get_client_info(self) -> OAuthClientInformationFull | None:\n \"\"\"获取存储的客户端信息\"\"\"\n ...\n \n async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:\n \"\"\"存储客户端信息\"\"\"\n ...\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:100-130]()\n\n## 认证流程详解\n\n### 授权码流程（Authorization Code Flow）\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant AS as 授权服务器\n participant RS as 资源服务器\n\n Note over Client: 1. 元数据发现\n Client->>RS: GET /.well-known/oauth-protected-resource\n RS-->>Client: ProtectedResourceMetadata\n Client->>AS: GET /.well-known/oauth-authorization-server\n AS-->>Client: OAuthMetadata\n\n Note over Client: 2. 客户端注册\n Client->>AS: POST /register (DCR)\n AS-->>Client: client_id, client_secret\n\n Note over Client: 3. PKCE 准备\n Client->>Client: 生成 code_verifier\n Client->>Client: 生成 code_challenge = BASE64URL(SHA256(code_verifier))\n\n Note over Client: 4. 授权请求\n Client->>Client: 构建授权 URL\n Client->>Browser: 重定向到授权页面\n User->>Browser: 用户登录\n\n Note over Client: 5. 回调处理\n Browser->>Client: /callback?code=xxx&state=xxx\n Client->>AS: POST /token (code + code_verifier)\n AS-->>Client: access_token, refresh_token\n\n Note over Client: 6. 资源访问\n Client->>RS: MCP 请求 (Bearer token)\n RS->>AS: Token 内省 (可选)\n RS-->>Client: MCP 响应\n```\n\n#### 第一阶段：元数据发现\n\n```python\n# 发现受保护资源元数据\nprm_discovery_urls = build_protected_resource_metadata_discovery_urls(context.server_url)\nfor url in prm_discovery_urls:\n response = yield create_protected_resource_request(url)\n ok, prm = await handle_protected_resource_response(response)\n if ok and prm:\n context.protected_resource_metadata = prm\n break\n\n# 发现授权服务器元数据\nasm_discovery_urls = build_oauth_authorization_server_metadata_discovery_urls(\n context.auth_server_url, context.server_url\n)\nfor url in asm_discovery_urls:\n response = yield create_oauth_metadata_request(url)\n ok, asm = await handle_auth_metadata_response(response)\n if ok and asm:\n context.oauth_metadata = asm\n break\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:250-310]()\n\n#### 第二阶段：客户端注册\n\n支持两种客户端标识方式：\n\n**方式一：动态客户端注册（DCR）**\n\n```python\nregistration_request = create_client_registration_request(\n context.oauth_metadata,\n context.client_metadata,\n context.get_authorization_base_url(context.server_url),\n)\n# ... 发送注册请求\nclient_info = await handle_registration_response(response)\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:340-360]()\n\n**方式二：URL-based Client ID (CIMD)**\n\n当服务器支持 `client_id_metadata_document_supported` 时使用：\n\n```python\nif should_use_client_metadata_url(context.oauth_metadata, context.client_metadata_url):\n client_information = create_client_info_from_metadata_url(\n context.client_metadata_url,\n redirect_uris=context.client_metadata.redirect_uris,\n )\n```\n\n资料来源：[src/mcp/client/auth/utils.py:80-100]()\n\n#### 第三阶段：授权请求与 Token 交换\n\n```python\n# 生成 PKCE 参数\npkce = PKCEParameters()\n\n# 构建授权 URL\nauthorization_url = build_authorization_url(\n context.oauth_metadata.authorization_endpoint,\n client_id=context.client_info.client_id,\n redirect_uri=redirect_uri,\n scope=selected_scope,\n state=state,\n code_challenge=pkce.code_challenge,\n code_challenge_method=\"S256\",\n)\n\n# 打开浏览器进行授权\nawait context.redirect_handler(authorization_url)\n\n# 处理回调\ncode, state = await context.callback_handler()\n\n# 交换 Token\ntoken_request = create_token_request(\n context.oauth_metadata.token_endpoint,\n grant_type=\"authorization_code\",\n code=code,\n redirect_uri=redirect_uri,\n client_id=context.client_info.client_id,\n client_secret=context.client_info.client_secret,\n code_verifier=pkce.code_verifier,\n)\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:400-480]()\n\n### Token 自动刷新\n\n```mermaid\ngraph TD\n A[MCP 请求] --> B{Token 有效?}\n B -->|是| C[发送请求]\n B -->|否| D{有 Refresh Token?}\n D -->|有| E[刷新 Token]\n D -->|无| F[重新授权]\n E --> G{刷新成功?}\n G -->|是| H[存储新 Token]\n G -->|否| I[重新授权]\n H --> C\n F --> A\n I --> A\n```\n\n```python\nasync def _handle_token_refresh(self, context: OAuthContext) -> bool:\n \"\"\"处理 Token 刷新\"\"\"\n if not context.oauth_metadata or not context.current_tokens:\n return False\n \n refresh_token = context.current_tokens.refresh_token\n if not refresh_token:\n return False\n \n # 创建刷新请求\n token_request = create_token_request(\n context.oauth_metadata.token_endpoint,\n grant_type=\"refresh_token\",\n refresh_token=refresh_token,\n client_id=context.client_info.client_id,\n client_secret=context.client_info.client_secret,\n )\n \n # 发送请求并处理响应\n response = yield token_request\n token_response = await handle_token_response(response, context.current_tokens.scope)\n \n if token_response:\n context.current_tokens = token_response\n await context.storage.set_tokens(token_response)\n return True\n \n return False\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:550-600]()\n\n## PKCE 支持\n\n### PKCEParameters 数据类\n\n```python\nclass PKCEParameters(BaseModel):\n \"\"\"PKCE 参数\"\"\"\n \n code_verifier: str = Field(..., min_length=43, max_length=128)\n code_challenge: str\n code_challenge_method: Literal[\"S256\"] = \"S256\"\n```\n\n资料来源：[src/mcp/client/auth/oauth2.py:60-75]()\n\n### Code Verifier 与 Code Challenge 生成\n\n```mermaid\ngraph LR\n A[随机字符串
43-128 字符] --> B[Base64URL 编码]\n B --> C[code_verifier]\n C --> D[SHA256 哈希]\n D --> E[Base64URL 编码]\n E --> F[code_challenge]\n```\n\n## 客户端凭证流程\n\n对于服务端到服务端的认证场景，可以使用简化的客户端凭证流程：\n\n```mermaid\ngraph LR\n A[服务端] -->|client_id + client_secret| B[授权服务器]\n B -->|access_token| A\n A -->|Bearer Token| C[资源服务器]\n```\n\n### ClientCredentialsOAuthProvider\n\n```python\nfrom mcp.client.auth.extensions.client_credentials import ClientCredentialsOAuthProvider\n\n# 初始化\nprovider = ClientCredentialsOAuthProvider(\n server_url=\"http://localhost:8000/mcp\",\n storage=InMemoryTokenStorage(),\n client_id=\"my-service\",\n client_secret=\"secret\",\n scopes=\"tools read resources\",\n)\n\n# 使用 httpx.AsyncClient\nasync with httpx.AsyncClient(auth=provider) as client:\n response = await client.post(\"http://localhost:8000/mcp\", json=request_data)\n```\n\n资料来源：[src/mcp/client/auth/extensions/client_credentials.py:30-80]()\n\n## 异常处理\n\n### OAuthFlowError\n\n授权流程异常：\n\n```python\nclass OAuthFlowError(Exception):\n \"\"\"OAuth 流程错误\"\"\"\n \n error: OAuthErrorCode\n error_description: str | None = None\n```\n\n### OAuthTokenError\n\nToken 相关错误：\n\n```python\nclass OAuthTokenError(Exception):\n \"\"\"Token 处理错误\"\"\"\n \n error: OAuthErrorCode\n error_description: str | None = None\n```\n\n资料来源：[src/mcp/client/auth/exceptions.py:1-30]()\n\n## 使用示例\n\n### 完整授权码流程示例\n\n```python\nimport asyncio\nfrom httpx import AsyncClient\nfrom mcp.client.auth.oauth2 import OAuthClientProvider, OAuthClientMetadata\nfrom mcp.client.auth.in_memory_storage import InMemoryTokenStorage\n\nasync def main():\n # 1. 配置客户端元数据\n client_metadata = OAuthClientMetadata(\n redirect_uris=[\"http://localhost:8000/callback\"],\n grant_types=[\"authorization_code\", \"refresh_token\"],\n token_endpoint_auth_method=\"client_secret_post\",\n scope=\"tools read\",\n )\n \n # 2. 创建 Token 存储\n storage = InMemoryTokenStorage()\n \n # 3. 创建 OAuth 提供者\n oauth_provider = OAuthClientProvider(\n server_url=\"http://localhost:8000/mcp\",\n client_metadata=client_metadata,\n storage=storage,\n redirect_handler=lambda url: print(f\"打开浏览器: {url}\"),\n callback_handler=lambda: input(\"输入授权码: \").split(\",\"),\n )\n \n # 4. 使用 OAuth 认证\n async with AsyncClient(auth=oauth_provider) as client:\n response = await client.post(\n \"http://localhost:8000/mcp\",\n json={\"jsonrpc\": \"2.0\", \"method\": \"tools/list\", \"id\": 1}\n )\n print(response.json())\n\nasyncio.run(main())\n```\n\n### 带资源验证的示例\n\n```python\nfrom mcp.shared.auth_utils import check_resource_allowed, resource_url_from_server_url\n\n# 验证请求的资源与配置的资源是否匹配\nallowed = check_resource_allowed(\n requested_resource=\"http://localhost:8001\",\n configured_resource=\"http://localhost:8001\"\n)\n\n# 从服务器 URL 提取资源 URL\nresource_url = resource_url_from_server_url(\"http://localhost:8001/mcp\")\n# 结果: \"http://localhost:8001\"\n```\n\n资料来源：[src/mcp/shared/auth_utils.py:50-100]()\n\n## 配置选项\n\n### OAuthClientProvider 初始化参数\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `server_url` | `str` | 是 | - | MCP 服务器 URL |\n| `client_metadata` | `OAuthClientMetadata` | 是 | - | OAuth 客户端元数据 |\n| `storage` | `TokenStorage` | 是 | - | Token 存储实现 |\n| `redirect_handler` | `Callable` | 否 | `None` | 授权重定向处理函数 |\n| `callback_handler` | `Callable` | 否 | `None` | 回调处理函数 |\n| `timeout` | `float` | 否 | `300.0` | OAuth 流程超时时间 |\n| `client_metadata_url` | `str` | 否 | `None` | URL-based Client ID |\n| `validate_resource_url` | `Callable` | 否 | `None` | 自定义资源 URL 验证 |\n\n### AuthSettings 配置\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `issuer_url` | `AnyHttpUrl` | 授权服务器 URL |\n| `resource_server_url` | `AnyHttpUrl` | 资源服务器 URL |\n| `service_documentation_url` | `AnyHttpUrl` | 服务文档 URL |\n| `client_registration_options` | `ClientRegistrationOptions` | 客户端注册选项 |\n| `revocation_options` | `RevocationOptions` | Token 撤销选项 |\n| `required_scopes` | `list[str]` | 必需的权限范围 |\n\n资料来源：[src/mcp/server/auth/settings.py:1-40]()\n\n## 安全考虑\n\n### PKCE 必要性\n\n对于公开客户端（如移动应用或单页应用），强烈建议使用 PKCE。SDK 默认使用 S256 方法进行 code challenge：\n\n```python\ncode_challenge_method: Literal[\"S256\"] = \"S256\"\n```\n\n### Token 安全存储\n\n- 生产环境应使用加密存储（如 `EncryptedTokenStorage`）\n- Refresh Token 应安全保存，防止泄露\n- Token 过期时间应合理设置\n\n### HTTPS 要求\n\nSDK 对客户端元数据 URL 有严格的验证要求：\n\n```python\ndef is_valid_client_metadata_url(url: str | None) -> bool:\n \"\"\"验证客户端元数据 URL 是否有效\"\"\"\n if not url:\n return False\n try:\n parsed = urlparse(url)\n return parsed.scheme == \"https\" and parsed.path not in (\"\", \"/\")\n except Exception:\n return False\n```\n\n资料来源：[src/mcp/client/auth/utils.py:30-50]()\n\n## 相关文档\n\n- [授权服务器实现](../servers/auth/README.md)\n- [Streamable HTTP 传输](../transports/streamable-http.md)\n- [RFC 6749 - OAuth 2.0 授权框架](https://datatracker.ietf.org/doc/html/rfc6749)\n- [RFC 7636 - PKCE](https://datatracker.ietf.org/doc/html/rfc7636)\n- [RFC 8414 - OAuth 授权服务器元数据](https://www.rfc-editor.org/rfc/rfc8414)\n- [RFC 9728 - 受保护资源元数据](https://www.rfc-editor.org/rfc/rfc9728)\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：modelcontextprotocol/python-sdk\n\n摘要：发现 22 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：运行坑 - 来源证据：[packit] Pull from upstream failed for release 1.27.1。\n\n## 1. 运行坑 · 来源证据：[packit] Pull from upstream failed for release 1.27.1\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[packit] Pull from upstream failed for release 1.27.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7cd3c6cd2e994e6cbd60b3cbb19c96e6 | https://github.com/modelcontextprotocol/python-sdk/issues/2563 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：MCP client does not retry authenticated request after successful OAuth token exchange\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP client does not retry authenticated request after successful OAuth token exchange\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_437e528a826e41e6ae0d654e0e858cbc | https://github.com/modelcontextprotocol/python-sdk/issues/2577 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f4669be4619541d3bc0001e432fa5416 | https://github.com/modelcontextprotocol/python-sdk/issues/2578 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Race condition between SSE session init and tools/call rejection (-32602)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Race condition between SSE session init and tools/call rejection (-32602)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f707b6204fd541d3aea0e5c1ef97e432 | https://github.com/modelcontextprotocol/python-sdk/issues/2583 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Types-only install option\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Types-only install option\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1582e38e22384d509ffb75f91a25c9d0 | https://github.com/modelcontextprotocol/python-sdk/issues/2581 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：Expose `schema_generator` on `FastMCP` for tool params schema generation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Expose `schema_generator` on `FastMCP` for tool params schema generation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2a614d750d3f4ec59807cdd800d8ff75 | https://github.com/modelcontextprotocol/python-sdk/issues/2582 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 配置坑 · 来源证据：v1.24.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.24.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_51df2611be1e47b586edd80b1adb1cfb | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.24.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 能力坑 · 能力判断依赖假设\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:862584018 | https://github.com/modelcontextprotocol/python-sdk | README/documentation is current enough for a first validation pass.\n\n## 9. 运行坑 · 来源证据：fix: 4 additional raise sites missing exception chaining with 'from'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：fix: 4 additional raise sites missing exception chaining with 'from'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_71303d3f16c942efb8521432eba345a1 | https://github.com/modelcontextprotocol/python-sdk/issues/2575 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · 来源证据：v1.23.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.23.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c7b4addde6a4da3ae29d5f3f01e7455 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在安全注意事项\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:862584018 | https://github.com/modelcontextprotocol/python-sdk | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Claude Code client sends tools/call without initialize handshake — SSE transport rejects with -32602\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Claude Code client sends tools/call without initialize handshake — SSE transport rejects with -32602\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_48d1c0f7a5d040568e55a2fa6ead27d8 | https://github.com/modelcontextprotocol/python-sdk/issues/2579 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v1.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.23.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ca7e48aa359f4c0b86a3ca42172b40d9 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v1.23.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.23.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_202f1fef816145aa912dae7104ecf977 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v1.25.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.25.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9cdf542dc72c4e31998478a1e41b9c8e | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.25.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.27.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.27.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eb0db07c9d9940e8af311c6e3165dada | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.27.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v1.27.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.27.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bcdd360ffa1641fbb2ed4c5be2be5ebe | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.27.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · 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:862584018 | https://github.com/modelcontextprotocol/python-sdk | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:862584018 | https://github.com/modelcontextprotocol/python-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/python-sdk\n\n摘要：发现 22 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：运行坑 - 来源证据：[packit] Pull from upstream failed for release 1.27.1。\n\n## 1. 运行坑 · 来源证据：[packit] Pull from upstream failed for release 1.27.1\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[packit] Pull from upstream failed for release 1.27.1\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_7cd3c6cd2e994e6cbd60b3cbb19c96e6 | https://github.com/modelcontextprotocol/python-sdk/issues/2563 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安全/权限坑 · 来源证据：MCP client does not retry authenticated request after successful OAuth token exchange\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：MCP client does not retry authenticated request after successful OAuth token exchange\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_437e528a826e41e6ae0d654e0e858cbc | https://github.com/modelcontextprotocol/python-sdk/issues/2577 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 安全/权限坑 · 来源证据：OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：OAuth token refresh sends RFC 8707 resource parameter that Entra ID v2.0 rejects (AADSTS9010010)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f4669be4619541d3bc0001e432fa5416 | https://github.com/modelcontextprotocol/python-sdk/issues/2578 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 4. 安装坑 · 来源证据：Race condition between SSE session init and tools/call rejection (-32602)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Race condition between SSE session init and tools/call rejection (-32602)\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_f707b6204fd541d3aea0e5c1ef97e432 | https://github.com/modelcontextprotocol/python-sdk/issues/2583 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 5. 安装坑 · 来源证据：Types-only install option\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Types-only install option\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_1582e38e22384d509ffb75f91a25c9d0 | https://github.com/modelcontextprotocol/python-sdk/issues/2581 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 配置坑 · 来源证据：Expose `schema_generator` on `FastMCP` for tool params schema generation\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Expose `schema_generator` on `FastMCP` for tool params schema generation\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_2a614d750d3f4ec59807cdd800d8ff75 | https://github.com/modelcontextprotocol/python-sdk/issues/2582 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 7. 配置坑 · 来源证据：v1.24.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：v1.24.0\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_51df2611be1e47b586edd80b1adb1cfb | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.24.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 8. 能力坑 · 能力判断依赖假设\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:862584018 | https://github.com/modelcontextprotocol/python-sdk | README/documentation is current enough for a first validation pass.\n\n## 9. 运行坑 · 来源证据：fix: 4 additional raise sites missing exception chaining with 'from'\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：fix: 4 additional raise sites missing exception chaining with 'from'\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_71303d3f16c942efb8521432eba345a1 | https://github.com/modelcontextprotocol/python-sdk/issues/2575 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 10. 维护坑 · 来源证据：v1.23.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：v1.23.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3c7b4addde6a4da3ae29d5f3f01e7455 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.2 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 11. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | last_activity_observed missing\n\n## 12. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | no_demo; severity=medium\n\n## 13. 安全/权限坑 · 存在安全注意事项\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:862584018 | https://github.com/modelcontextprotocol/python-sdk | No sandbox install has been executed yet; downstream must verify before user use.\n\n## 14. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Claude Code client sends tools/call without initialize handshake — SSE transport rejects with -32602\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Claude Code client sends tools/call without initialize handshake — SSE transport rejects with -32602\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_48d1c0f7a5d040568e55a2fa6ead27d8 | https://github.com/modelcontextprotocol/python-sdk/issues/2579 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 安全/权限坑 · 来源证据：v1.23.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.23.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ca7e48aa359f4c0b86a3ca42172b40d9 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 17. 安全/权限坑 · 来源证据：v1.23.3\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.23.3\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_202f1fef816145aa912dae7104ecf977 | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.23.3 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：v1.25.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.25.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9cdf542dc72c4e31998478a1e41b9c8e | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.25.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 19. 安全/权限坑 · 来源证据：v1.27.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.27.0\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_eb0db07c9d9940e8af311c6e3165dada | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.27.0 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 20. 安全/权限坑 · 来源证据：v1.27.1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：v1.27.1\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bcdd360ffa1641fbb2ed4c5be2be5ebe | https://github.com/modelcontextprotocol/python-sdk/releases/tag/v1.27.1 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · 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:862584018 | https://github.com/modelcontextprotocol/python-sdk | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:862584018 | https://github.com/modelcontextprotocol/python-sdk | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# python-sdk - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 python-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 Python SDK for Model Context Protocol servers and clients 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-introduction：MCP 协议与 Python SDK 简介。围绕“MCP 协议与 Python SDK 简介”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-quickstart：快速开始指南。围绕“快速开始指南”模拟一次用户任务，不展示安装或运行结果。\n4. page-architecture：系统架构与核心组件。围绕“系统架构与核心组件”模拟一次用户任务，不展示安装或运行结果。\n5. page-transports：传输协议实现。围绕“传输协议实现”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-introduction\n输入：用户提供的“MCP 协议与 Python SDK 简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-quickstart\n输入：用户提供的“快速开始指南”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-architecture\n输入：用户提供的“系统架构与核心组件”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-transports\n输入：用户提供的“传输协议实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-introduction：Step 1 必须围绕“MCP 协议与 Python SDK 简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-quickstart：Step 3 必须围绕“快速开始指南”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-architecture：Step 4 必须围绕“系统架构与核心组件”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-transports：Step 5 必须围绕“传输协议实现”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/modelcontextprotocol/python-sdk\n- https://github.com/modelcontextprotocol/python-sdk#readme\n- README.md\n- docs/concepts.md\n- src/mcp/__init__.py\n- docs/installation.md\n- pyproject.toml\n- examples/snippets/servers/fastmcp_quickstart.py\n- examples/snippets/servers/basic_tool.py\n- examples/snippets/servers/basic_resource.py\n- examples/snippets/servers/basic_prompt.py\n- src/mcp/client/client.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 python-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/python-sdk\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx -y @modelcontextprotocol/inspector\n```\n\n来源：https://github.com/modelcontextprotocol/python-sdk#readme\n\n## 来源\n\n- repo: https://github.com/modelcontextprotocol/python-sdk\n- docs: https://github.com/modelcontextprotocol/python-sdk#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_1fed190163f04f2688cefc073878d95c"
}