{
"canonical_name": "langchain-ai/langchain-mcp-adapters",
"compilation_id": "pack_65db3856a1764e3da97676275b313285",
"created_at": "2026-05-12T17:44:23.741151+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 `pip install langchain-mcp-adapters` 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": "pip install langchain-mcp-adapters",
"sandbox_container_image": "python:3.12-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_38a1e0e8dcbd448e89200a517839d5cc"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_c36b23311c130812d6b225416dd1d1c7",
"canonical_name": "langchain-ai/langchain-mcp-adapters",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/langchain-ai/langchain-mcp-adapters",
"slug": "langchain-mcp-adapters",
"source_packet_id": "phit_0d0ed02354f040b2b380a766555e2976",
"source_validation_id": "dval_3abacb7c691849fc8f2ee8ca09a88b62"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 425,
"github_stars": 3527,
"one_liner_en": "LangChain 🔌 MCP",
"one_liner_zh": "LangChain 🔌 MCP",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "medium",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, github"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "langchain-mcp-adapters",
"title_zh": "langchain-mcp-adapters 能力包",
"visible_tags": [
{
"label_en": "MCP Tools",
"label_zh": "MCP 工具",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-mcp-tools",
"type": "product_domain"
},
{
"label_en": "Visual Workflow Orchestration",
"label_zh": "视觉工作流编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-visual-workflow-orchestration",
"type": "user_job"
},
{
"label_en": "Retrieval Augmentation",
"label_zh": "检索增强",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-retrieval-augmentation",
"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_0d0ed02354f040b2b380a766555e2976",
"page_model": {
"artifacts": {
"artifact_slug": "langchain-mcp-adapters",
"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": "pip install langchain-mcp-adapters",
"label": "Python / pip · 官方安装入口",
"source": "https://github.com/langchain-ai/langchain-mcp-adapters#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"视觉工作流编排",
"检索增强",
"节点式流程编排",
"本地优先"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "LangChain 🔌 MCP"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host",
"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 社区证据显示该项目存在一个安装相关的待验证问题：Prompts and Resources auto-discovery",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_bf1812b74caa4e989767a9307a8ffc16 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/62 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Prompts and Resources auto-discovery",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`MultiServerMCPClient.get_tools()` silently returns no tools when any single server fails to connect",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_a5093182914b4df0b7ad2cd560bacdf2 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/492 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：`MultiServerMCPClient.get_tools()` silently returns no tools when any single server fails to connect",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Fix TypeError in resources.py and make __aexit__ an async coroutine in client.py",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_ac102050dd4841d6954559a3413e0b92 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/496 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "high",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Fix TypeError in resources.py and make __aexit__ an async coroutine in client.py",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安装相关的待验证问题：langchain-mcp-adapters==0.2.2",
"category": "安装坑",
"evidence": [
"community_evidence:github | cevd_0c6ca0722ab046379d28ecf30f8d2bcf | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.2 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：langchain-mcp-adapters==0.2.2",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个配置相关的待验证问题：langchain-mcp-adapters==0.1.10",
"category": "配置坑",
"evidence": [
"community_evidence:github | cevd_8b18dbf32ccd41e38b272a458f4040f5 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：langchain-mcp-adapters==0.1.10",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：langchain-mcp-adapters==0.1.14",
"category": "能力坑",
"evidence": [
"community_evidence:github | cevd_6727e0d698e54fc38d7c60e262978ac2 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.14 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：langchain-mcp-adapters==0.1.14",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：langchain-mcp-adapters==0.1.12",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_e71a46a9e0374d139555a78f229b0469 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.12 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：langchain-mcp-adapters==0.1.12",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：langchain-mcp-adapters==0.2.0",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_59483f9a6a16414c9087b1751fba8efc | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：langchain-mcp-adapters==0.2.0",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：langchain-mcp-adapters==0.2.0a1",
"category": "维护坑",
"evidence": [
"community_evidence:github | cevd_4e7fcda1716948898295279af95f8f96 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0a1 | 来源类型 github_release 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。",
"title": "来源证据：langchain-mcp-adapters==0.2.0a1",
"user_impact": "可能影响升级、迁移或版本选择。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Support passing server-defined params extensions (e.g. LangGraph `context`) through tools/call",
"category": "安全/权限坑",
"evidence": [
"community_evidence:github | cevd_8c46dab4b6dd4a6e92c96af49ea47647 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/502 | 来源讨论提到 python 相关条件，需在安装/试用前复核。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：Feature Request: Support passing server-defined params extensions (e.g. LangGraph `context`) through tools/call",
"user_impact": "可能影响授权、密钥配置或安全边界。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 17 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Prompts and Resources auto-discovery。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 27,
"forks": 425,
"license": "unknown",
"note": "GitHub API 快照，非实时质量证明；用于开工前背景判断。",
"stars": 3527,
"open_issues": 90,
"pushed_at": null
},
"source_url": "https://github.com/langchain-ai/langchain-mcp-adapters",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "LangChain 🔌 MCP",
"title": "langchain-mcp-adapters 能力包",
"trial_prompt": "# langchain-mcp-adapters - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 langchain-mcp-adapters 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: LangChain 🔌 MCP 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-core-modules：核心模块结构。围绕“核心模块结构”模拟一次用户任务，不展示安装或运行结果。\n4. page-multiserver-client：MultiServerMCPClient 客户端。围绕“MultiServerMCPClient 客户端”模拟一次用户任务，不展示安装或运行结果。\n5. page-tools-conversion：工具转换机制。围绕“工具转换机制”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-core-modules\n输入：用户提供的“核心模块结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-multiserver-client\n输入：用户提供的“MultiServerMCPClient 客户端”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-tools-conversion\n输入：用户提供的“工具转换机制”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-core-modules：Step 3 必须围绕“核心模块结构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-multiserver-client：Step 4 必须围绕“MultiServerMCPClient 客户端”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-tools-conversion：Step 5 必须围绕“工具转换机制”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/langchain-ai/langchain-mcp-adapters\n- https://github.com/langchain-ai/langchain-mcp-adapters#readme\n- README.md\n- langchain_mcp_adapters/__init__.py\n- pyproject.toml\n- langchain_mcp_adapters/tools.py\n- langchain_mcp_adapters/client.py\n- langchain_mcp_adapters/sessions.py\n- langchain_mcp_adapters/callbacks.py\n- langchain_mcp_adapters/interceptors.py\n- langchain_mcp_adapters/prompts.py\n- langchain_mcp_adapters/resources.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 langchain-mcp-adapters 的核心服务。\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: `MultiServerMCPClient.get_tools()` silently returns no tools when any si（https://github.com/langchain-ai/langchain-mcp-adapters/issues/492）；github/github_issue: Feature Request: Support passing server-defined params extensions (e.g. （https://github.com/langchain-ai/langchain-mcp-adapters/issues/502）；github/github_issue: Prompts and Resources auto-discovery（https://github.com/langchain-ai/langchain-mcp-adapters/issues/62）；github/github_issue: Fix TypeError in resources.py and make __aexit__ an async coroutine in c（https://github.com/langchain-ai/langchain-mcp-adapters/issues/496）；github/github_release: langchain-mcp-adapters==0.2.2（https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.2）；github/github_release: langchain-mcp-adapters==0.2.1（https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.1）；github/github_release: langchain-mcp-adapters==0.2.0（https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0）；github/github_release: langchain-mcp-adapters==0.2.0a1（https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0a1）；github/github_release: langchain-mcp-adapters==0.1.14（https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.14）；github/github_release: langchain-mcp-adapters==0.1.13（https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.13）；github/github_release: langchain-mcp-adapters==0.1.12（https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.12）；github/github_release: langchain-mcp-adapters==0.1.10（https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.10）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "`MultiServerMCPClient.get_tools()` silently returns no tools when any si",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/issues/492"
},
{
"kind": "github_issue",
"source": "github",
"title": "Feature Request: Support passing server-defined params extensions (e.g. ",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/issues/502"
},
{
"kind": "github_issue",
"source": "github",
"title": "Prompts and Resources auto-discovery",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/issues/62"
},
{
"kind": "github_issue",
"source": "github",
"title": "Fix TypeError in resources.py and make __aexit__ an async coroutine in c",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/issues/496"
},
{
"kind": "github_release",
"source": "github",
"title": "langchain-mcp-adapters==0.2.2",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.2"
},
{
"kind": "github_release",
"source": "github",
"title": "langchain-mcp-adapters==0.2.1",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.1"
},
{
"kind": "github_release",
"source": "github",
"title": "langchain-mcp-adapters==0.2.0",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0"
},
{
"kind": "github_release",
"source": "github",
"title": "langchain-mcp-adapters==0.2.0a1",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0a1"
},
{
"kind": "github_release",
"source": "github",
"title": "langchain-mcp-adapters==0.1.14",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.14"
},
{
"kind": "github_release",
"source": "github",
"title": "langchain-mcp-adapters==0.1.13",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.13"
},
{
"kind": "github_release",
"source": "github",
"title": "langchain-mcp-adapters==0.1.12",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.12"
},
{
"kind": "github_release",
"source": "github",
"title": "langchain-mcp-adapters==0.1.10",
"url": "https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.10"
}
],
"status": "已收录 12 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "LangChain 🔌 MCP",
"effort": "安装已验证",
"forks": 424,
"icon": "link",
"name": "langchain-mcp-adapters 能力包",
"risk": "可发布",
"slug": "langchain-mcp-adapters",
"stars": 3525,
"tags": [
"MCP 工具",
"视觉工作流编排",
"检索增强",
"节点式流程编排",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/langchain-ai/langchain-mcp-adapters 项目说明书\n\n生成时间：2026-05-11 16:35:38 UTC\n\n## 目录\n\n- [项目介绍](#page-project-introduction)\n- [安装与配置](#page-installation)\n- [核心模块结构](#page-core-modules)\n- [数据流与转换机制](#page-data-flow)\n- [MultiServerMCPClient 客户端](#page-multiserver-client)\n- [工具转换机制](#page-tools-conversion)\n- [传输协议类型](#page-transport-types)\n- [工具调用拦截器](#page-interceptors)\n- [回调机制](#page-callbacks)\n- [提示词与资源转换](#page-prompts-resources)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [核心模块结构](#page-core-modules)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/README.md)\n- [langchain_mcp_adapters/__init__.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/__init__.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n \n\n# 项目介绍\n\n## 项目概述\n\nlangchain-mcp-adapters 是一个轻量级适配器库，用于将 [Anthropic Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 工具转换为 [LangChain](https://github.com/langchain-ai/langchain) 和 [LangGraph](https://github.com/langchain-ai/langgraph) 兼容的格式。该项目使开发者能够在 LangChain/LangGraph 应用中无缝使用 MCP 协议定义的各种工具。\n\n资料来源：[langchain_mcp_adapters/__init__.py:1-9]()\n\n## 核心定位\n\n该项目充当 MCP 协议与 LangChain 生态之间的桥梁，解决两个协议栈之间的互操作性问题。\n\n```mermaid\ngraph LR\n A[MCP 服务器] --> B[langchain-mcp-adapters]\n B --> C[LangChain/LangGraph]\n C --> D[AI Agent]\n \n style B fill:#e1f5fe\n```\n\n资料来源：[README.md:1-1]()\n\n## 核心功能特性\n\n| 功能模块 | 说明 |\n|---------|------|\n| **工具适配** | 将 MCP 工具转换为 LangChain 工具，可与 LangGraph agents 配合使用 |\n| **多服务器客户端** | 支持连接多个 MCP 服务器并从中加载工具 |\n| **资源转换** | 将 MCP 资源转换为 LangChain Blob 对象 |\n| **拦截器机制** | 提供工具调用生命周期管理能力 |\n| **多传输协议支持** | 支持 stdio、HTTP、SSE、WebSocket 等多种传输方式 |\n\n资料来源：[README.md:10-16]()\n\n## 系统架构\n\n### 核心组件\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n A[MultiServerMCPClient]\n end\n \n subgraph \"会话管理层\"\n B[sessions.py]\n C[Connection 抽象]\n D[StdioConnection]\n E[StreamableHttpConnection]\n F[SSEConnection]\n G[WebsocketConnection]\n end\n \n subgraph \"适配器层\"\n H[tools.py]\n I[resources.py]\n J[prompts.py]\n end\n \n subgraph \"拦截器层\"\n K[interceptors.py]\n L[ToolCallInterceptor]\n end\n \n A --> B\n B --> C\n C --> D\n C --> E\n C --> F\n C --> G\n \n A --> H\n A --> I\n A --> J\n \n H --> K\n```\n\n### 工具转换流程\n\n```mermaid\nsequenceDiagram\n participant Client as MultiServerMCPClient\n participant Session as MCP ClientSession\n participant Adapter as tools.py\n participant Interceptor as ToolCallInterceptor\n participant LC as LangChain Tool\n \n Client->>Session: list_tools()\n Session-->>Client: List[MCPTool]\n Client->>Adapter: convert_to_langchain_tool(MCPTool)\n Adapter->>Interceptor: 包装拦截器链\n Adapter->>LC: StructuredTool\n Client-->>Client: 返回 LangChain 工具列表\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:1-50]()\n\n## 模块详解\n\n### tools.py - 工具适配模块\n\n该模块负责将 MCP 工具转换为 LangChain 工具，核心功能包括：\n\n- **内容块转换**：支持 TextContent、ImageContent、FileContent 等多种内容类型转换\n- **工具调用执行**：通过拦截器链执行工具调用并处理结果\n- **错误处理**：将 MCP 错误转换为 ToolException\n- **结构化内容包装**：通过 MCPToolArtifact 包装结构化返回内容\n\n| 转换类型 | MCP 输入 | LangChain 输出 |\n|---------|---------|---------------|\n| 文本内容 | TextContent | {\"type\": \"text\", \"text\": ...} |\n| 图片内容 | ImageContent | {\"type\": \"image\", \"base64\": ..., \"mime_type\": ...} |\n| 图片链接 | ResourceLink(image/*) | {\"type\": \"image\", \"url\": ...} |\n| 文件链接 | ResourceLink(other) | {\"type\": \"file\", \"url\": ...} |\n| 内嵌资源 | EmbeddedResource | 同上映射规则 |\n\n资料来源：[langchain_mcp_adapters/tools.py:100-150]()\n\n### resources.py - 资源适配模块\n\n该模块处理 MCP 资源的转换，将 MCP 资源内容转换为 LangChain Blob 对象：\n\n- **文本资源**：直接提取 text 内容\n- **二进制资源**：Base64 解码后封装为 Blob\n- **动态资源**：支持按 URI 列表加载特定资源\n\n资料来源：[langchain_mcp_adapters/resources.py:1-60]()\n\n### interceptors.py - 拦截器模块\n\n提供工具调用生命周期管理能力，采用洋葱模式构建拦截器链：\n\n```mermaid\ngraph TD\n A[请求入口] --> B[拦截器 1]\n B --> C[拦截器 2]\n C --> D[拦截器 N]\n D --> E[实际工具执行]\n E --> D\n D --> C\n C --> B\n B --> A[响应返回]\n \n style E fill:#c8e6c9\n```\n\n| 组件 | 说明 |\n|-----|------|\n| MCPToolCallRequest | 工具调用请求数据结构 |\n| MCPToolCallResult | 工具调用结果，支持 Command 格式 |\n| ToolCallInterceptor | 拦截器接口定义 |\n\n资料来源：[langchain_mcp_adapters/interceptors.py:1-50]()\n\n### client.py - 多服务器客户端\n\nMultiServerMCPClient 是核心入口类，提供以下能力：\n\n- 同时管理多个 MCP 服务器连接\n- 支持按服务器名获取工具列表\n- 支持显式会话管理和上下文管理器会话\n- 集成回调和拦截器配置\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| connections | dict | 服务器连接配置映射 |\n| callbacks | Callbacks | 事件回调处理器 |\n| tool_interceptors | list | 工具调用拦截器列表 |\n| tool_name_prefix | bool | 是否为工具名添加服务器前缀 |\n\n资料来源：[langchain_mcp_adapters/client.py:1-100]()\n\n### sessions.py - 会话管理层\n\n负责创建和管理 MCP ClientSession，支持多种传输协议：\n\n| 传输类型 | 适用场景 | 配置方式 |\n|---------|---------|---------|\n| StdioConnection | 本地进程通信 | command + args |\n| StreamableHttpConnection | 无状态 HTTP 服务器 | url |\n| SSEConnection | Server-Sent Events | url + headers |\n| WebsocketConnection | WebSocket 通信 | url + headers |\n\n资料来源：[langchain_mcp_adapters/sessions.py:1-100]()\n\n## 快速开始\n\n### 安装依赖\n\n```bash\npip install langchain-mcp-adapters\n```\n\n资料来源：[README.md:22-24]()\n\n### 创建 MCP 服务器\n\n```python\n# math_server.py\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"Math\")\n\n@mcp.tool()\ndef add(a: int, b: int) -> int:\n \"\"\"Add two numbers\"\"\"\n return a + b\n\n@mcp.tool()\ndef multiply(a: int, b: int) -> int:\n \"\"\"Multiply two numbers\"\"\"\n return a * b\n```\n\n资料来源：[README.md:30-50]()\n\n### 使用 MultiServerMCPClient\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"./math_server.py\"],\n \"transport\": \"stdio\",\n }\n }\n)\ntools = await client.get_tools()\n```\n\n资料来源：[README.md:70-85]()\n\n### 集成 LangGraph Agent\n\n```python\nfrom langgraph.graph import StateGraph, MessagesState, START\nfrom langgraph.prebuilt import ToolNode, tools_condition\n\nbuilder = StateGraph(MessagesState)\nbuilder.add_node(call_model)\nbuilder.add_node(ToolNode(tools))\nbuilder.add_edge(START, \"call_model\")\nbuilder.add_conditional_edges(\n \"call_model\",\n tools_condition,\n)\n```\n\n资料来源：[README.md:110-125]()\n\n## 数据类型定义\n\n### MCPToolArtifact\n\n```python\nclass MCPToolArtifact(TypedDict):\n \"\"\"MCP 工具调用返回的工件\"\"\"\n structured_content: dict[str, Any]\n```\n\n用于包装 MCP 工具的结构化返回内容，支持未来扩展。\n\n资料来源：[langchain_mcp_adapters/tools.py:75-90]()\n\n### ConvertedToolResult\n\n根据 langgraph 安装状态，返回类型有所不同：\n\n| LangGraph 状态 | 返回类型 |\n|---------------|---------|\n| 已安装 | `list[ToolMessageContentBlock] \\| ToolMessage \\| Command` |\n| 未安装 | `list[ToolMessageContentBlock] \\| ToolMessage` |\n\n资料来源：[langchain_mcp_adapters/tools.py:60-70]()\n\n## 生态关联\n\n该项目与以下项目形成完整的 MCP 工具生态：\n\n```mermaid\ngraph TD\n A[langchain-mcp-adapters] --> B[LangChain]\n A --> C[LangGraph]\n A --> D[MCP SDK]\n \n E[langchainjs] --> A\n E --> F[JavaScript/TypeScript 版本]\n \n style A fill:#fff9c4\n```\n\n> 注意：该库的 JavaScript/TypeScript 版本也可在 [langchainjs](https://github.com/langchain-ai/langchainjs/tree/main/libs/langchain-mcp-adapters/) 获取。\n\n资料来源：[README.md:20-21]()\n\n## 总结\n\nlangchain-mcp-adapters 作为 MCP 协议与 LangChain 生态之间的关键适配层，提供：\n\n1. **开箱即用的工具转换**：零配置将 MCP 工具转换为 LangChain 工具\n2. **灵活的拦截机制**：支持在工具调用生命周期中注入自定义逻辑\n3. **强大的多服务器支持**：单客户端管理多个 MCP 服务器\n4. **完善的类型安全**：全面使用 Pydantic 和 TypedDict 确保类型安全\n\n该库使开发者能够充分利用 MCP 协议丰富的工具生态，同时享受 LangChain/LangGraph 带来的强大 Agent 开发能力。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[项目介绍](#page-project-introduction), [MultiServerMCPClient 客户端](#page-multiserver-client)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/pyproject.toml)\n- [README.md](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/README.md)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n \n\n# 安装与配置\n\n## 概述\n\n`langchain-mcp-adapters` 是一个轻量级适配器库，用于将 Anthropic 的 Model Context Protocol (MCP) 工具转换为 LangChain 和 LangGraph 兼容的工具格式。该库的主要功能包括：\n\n- 将 MCP 工具转换为 LangChain 工具，使其能够与 LangGraph 代理配合使用\n- 提供客户端实现，支持连接多个 MCP 服务器并加载其工具\n\n资料来源：[README.md:1-12]()\n\n## 环境要求\n\n### 系统要求\n\n| 组件 | 最低版本要求 | 说明 |\n|------|-------------|------|\n| Python | 3.10+ | 推荐使用 Python 3.10 或更高版本 |\n| pip | 最新版本 | 用于安装 Python 包 |\n\n### 核心依赖\n\n| 依赖包 | 版本要求 | 用途 |\n|--------|---------|------|\n| langchain-core | 最新稳定版 | LangChain 核心功能 |\n| mcp | 最新稳定版 | MCP 协议客户端支持 |\n| pydantic | 2.x | 数据验证和模型定义 |\n\n### 可选依赖\n\n| 依赖包 | 用途 |\n|--------|------|\n| langgraph | 用于 LangGraph StateGraph 集成 |\n| langchain[openai] | OpenAI 模型支持 |\n| httpx | HTTP 传输协议支持 |\n\n## 安装方法\n\n### 基础安装\n\n使用 pip 安装 langchain-mcp-adapters 的基本功能：\n\n```bash\npip install langchain-mcp-adapters\n```\n\n资料来源：[README.md:14]()\n\n### 完整安装（包含所有依赖）\n\n为了使用完整功能，包括与 LangGraph 和 OpenAI 的集成：\n\n```bash\npip install langchain-mcp-adapters langgraph \"langchain[openai]\"\n```\n\n资料来源：[README.md:20-21]()\n\n### 设置 API 密钥\n\n安装完成后，需要设置相应的 API 密钥环境变量：\n\n```bash\nexport OPENAI_API_KEY=\n```\n\n资料来源：[README.md:22]()\n\n## 客户端配置\n\n### MultiServerMCPClient 概述\n\n`MultiServerMCPClient` 是连接多个 MCP 服务器的主要接口，允许你从多个服务器同时加载工具。\n\n资料来源：[client.py:1-50]()\n\n### 连接配置参数\n\n#### 支持的传输协议\n\n| 传输类型 | 配置方式 | 说明 |\n|----------|----------|------|\n| `stdio` | 通过 command 和 args 参数 | 适用于本地子进程通信 |\n| `http` | 通过 url 参数 | 适用于远程 HTTP 服务器 |\n| `sse` | 通过 url 参数 | 支持 Server-Sent Events |\n\n资料来源：[sessions.py:1-200]()\n\n#### stdio 传输配置\n\nstdio 传输适用于本地 MCP 服务器进程：\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n }\n)\n```\n\n**配置参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `command` | str | 是 | 要执行的命令（如 `python`、`node`） |\n| `args` | list[str] | 是 | 命令行参数列表 |\n| `transport` | str | 是 | 必须设置为 `\"stdio\"` |\n| `env` | dict | 否 | 环境变量字典，支持变量展开 |\n| `cwd` | str | 否 | 命令执行的工作目录 |\n| `encoding` | str | 否 | 字符编码方式 |\n| `encoding_error_handler` | str | 否 | 编码错误处理策略 |\n\n资料来源：[sessions.py:1-100]()\n\n#### HTTP 传输配置\n\nHTTP 传输适用于远程 MCP 服务器：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n \"headers\": {\n \"Authorization\": \"Bearer custom-value\"\n }\n }\n }\n)\n```\n\n**HTTP 配置参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `url` | str | 是 | MCP 服务器的完整 URL |\n| `transport` | str | 是 | 必须设置为 `\"http\"` 或 `\"sse\"` |\n| `headers` | dict | 否 | HTTP 请求头，仅支持 `http` 和 `sse` 传输 |\n\n资料来源：[client.py:50-100]()\n\n### 工具名称前缀配置\n\n当多个 MCP 服务器存在相同名称的工具时，可以使用 `tool_name_prefix` 参数为工具名称添加服务器前缀：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n },\n tool_name_prefix=True # 启用工具名称前缀\n)\n```\n\n启用后，工具名称将从 `\"search\"` 变为 `\"weather_search\"`。\n\n资料来源：[client.py:40-45]()\n\n## MCP 服务器配置\n\n### 创建 MCP 服务器\n\n使用 FastMCP 框架创建 MCP 服务器：\n\n```python\n# math_server.py\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"Math\")\n\n@mcp.tool()\ndef add(a: int, b: int) -> int:\n \"\"\"Add two numbers\"\"\"\n return a + b\n\n@mcp.tool()\ndef multiply(a: int, b: int) -> int:\n \"\"\"Multiply two numbers\"\"\"\n return a * b\n\nif __name__ == \"__main__\":\n mcp.run(transport=\"stdio\")\n```\n\n资料来源：[README.md:30-55]()\n\n### HTTP 传输服务器\n\n对于 HTTP 传输模式的服务器：\n\n```python\n# weather_server.py\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"Weather\")\n\n@mcp.tool()\nasync def get_weather(location: str) -> str:\n \"\"\"Get weather for location.\"\"\"\n return \"It's always sunny in New York\"\n\nif __name__ == \"__main__\":\n mcp.run(transport=\"http\")\n```\n\n运行服务器：\n\n```bash\npython weather_server.py\n```\n\n资料来源：[README.md:60-75]()\n\n### 无状态 HTTP 流式服务器\n\n对于可扩展的 HTTP 服务，可以使用无状态流式传输：\n\n```bash\ncd examples/servers/streamable-http-stateless/\nuv run mcp-simple-streamablehttp-stateless --port 3000\n```\n\n资料来源：[README.md:2-8]()\n\n## 会话管理配置\n\n### 显式会话管理\n\n虽然 `MultiServerMCPClient` 默认在每次工具调用时自动创建新会话，但也支持显式会话管理：\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\nclient = MultiServerMCPClient({...})\nasync with client.session(\"math\") as session:\n tools = await load_mcp_tools(session)\n```\n\n资料来源：[client.py:60-70]()\n\n### 连接对象配置\n\n`Connection` 对象用于配置与 MCP 服务器的连接细节：\n\n```python\nfrom langchain_mcp_adapters.sessions import create_session\n\nasync with create_session(\n command=\"python\",\n args=[\"math_server.py\"],\n transport=\"stdio\"\n) as session:\n tools = await load_mcp_tools(session)\n```\n\n## 工具加载配置\n\n### load_mcp_tools 函数参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `session` | ClientSession | 否 | MCP 客户端会话，与 connection 二选一 |\n| `connection` | Connection | 否 | 连接配置，用于创建新会话 |\n| `callbacks` | Callbacks | 否 | 通知和事件处理回调 |\n| `tool_interceptors` | list[ToolCallInterceptor] | 否 | 工具调用拦截器列表 |\n| `server_name` | str | 否 | 服务器名称 |\n| `tool_name_prefix` | bool | 否 | 是否为工具名称添加前缀 |\n\n资料来源：[tools.py:100-150]()\n\n## 架构流程图\n\n### 客户端-服务器通信架构\n\n```mermaid\ngraph TD\n A[MultiServerMCPClient] --> B[Connection 配置]\n B --> C[stdio 传输]\n B --> D[HTTP 传输]\n B --> E[SSE 传输]\n \n C --> F[子进程 MCP 服务器]\n D --> G[远程 HTTP 服务器]\n E --> H[SSE 服务器]\n \n F --> I[ClientSession]\n G --> I\n H --> I\n \n I --> J[load_mcp_tools]\n J --> K[LangChain StructuredTool]\n K --> L[LangGraph Agent]\n```\n\n### 工具调用流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant LC as LangChain Agent\n participant MCP as MCP Adapter\n participant Server as MCP Server\n \n User->>LC: 调用工具\n LC->>MCP: call_tool(args)\n MCP->>MCP: 应用拦截器链\n MCP->>Server: session.call_tool()\n Server-->>MCP: CallToolResult\n MCP->>MCP: 转换结果格式\n MCP-->>LC: ToolMessage + Artifact\n LC-->>User: 返回结果\n```\n\n## 环境变量与密钥管理\n\n### 必需的环境变量\n\n| 变量名 | 说明 | 示例 |\n|--------|------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 | `sk-xxx...` |\n\n### 传输配置中的环境变量\n\n在 stdio 传输配置中，可以使用环境变量展开语法：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"server\": {\n \"command\": \"python\",\n \"args\": [\"script.py\"],\n \"env\": {\n \"API_KEY\": \"${API_KEY}\", # 从当前环境展开\n \"CUSTOM_VAR\": \"fixed-value\"\n },\n \"transport\": \"stdio\"\n }\n }\n)\n```\n\n> [!warning]\n> 如果环境变量值包含 `${variable}` 语法但无法展开，库会发出警告。\n\n资料来源：[sessions.py:80-95]()\n\n## 完整配置示例\n\n### 多服务器配置\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\n# 初始化客户端，连接多个 MCP 服务器\nclient = MultiServerMCPClient(\n {\n # 本地 stdio 服务器\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/absolute/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n # 远程 HTTP 服务器\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n \"headers\": {\n \"Authorization\": \"Bearer token123\"\n }\n }\n },\n tool_name_prefix=True # 避免工具名冲突\n)\n\n# 获取所有工具\ntools = await client.get_tools()\n```\n\n资料来源：[README.md:85-110]()\n\n### 与 LangGraph 集成配置\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.graph import StateGraph, MessagesState, START\nfrom langgraph.prebuilt import ToolNode, tools_condition\nfrom langchain.chat_models import init_chat_model\n\n# 配置 MCP 客户端\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"./examples/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\n\n# 加载工具\ntools = await client.get_tools()\n\n# 初始化模型\nmodel = init_chat_model(\"openai:gpt-4.1\")\n\n# 定义模型调用节点\ndef call_model(state: MessagesState):\n response = model.bind_tools(tools).invoke(state[\"messages\"])\n return {\"messages\": response}\n\n# 构建状态图\nbuilder = StateGraph(MessagesState)\nbuilder.add_node(call_model)\nbuilder.add_node(ToolNode(tools))\nbuilder.add_edge(START, \"call_model\")\nbuilder.add_conditional_edges(\n \"call_model\",\n tools_condition,\n)\n```\n\n资料来源：[README.md:120-165]()\n\n## 故障排除\n\n### 常见配置错误\n\n| 错误 | 原因 | 解决方案 |\n|------|------|----------|\n| `ValueError: Either session or connection must be provided` | 未提供 session 或 connection 参数 | 确保传递有效的 session 或 connection 对象 |\n| 工具名冲突 | 多服务器有同名工具 | 设置 `tool_name_prefix=True` |\n| 连接超时 | HTTP 服务器未启动或地址错误 | 确认服务器运行状态和 URL |\n| 环境变量未展开 | 变量语法错误 | 检查 `${variable}` 格式是否正确 |\n\n### 调试建议\n\n1. **验证 MCP 服务器**：确保服务器可以独立运行\n2. **检查传输类型**：stdio 需要命令和参数，HTTP 需要 URL\n3. **查看工具列表**：使用 `client.get_tools()` 确认工具加载成功\n4. **环境变量检查**：确保必需的 API 密钥已设置\n\n---\n\n\n\n## 核心模块结构\n\n### 相关页面\n\n相关主题：[工具转换机制](#page-tools-conversion), [MultiServerMCPClient 客户端](#page-multiserver-client), [数据流与转换机制](#page-data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n- [langchain_mcp_adapters/callbacks.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/callbacks.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [langchain_mcp_adapters/prompts.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/prompts.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n \n\n# 核心模块结构\n\n## 概述\n\nlangchain-mcp-adapters 是一个轻量级适配器库，用于将 Anthropic 的 Model Context Protocol (MCP) 服务器与 LangChain/LangGraph 应用集成。该库的核心设计围绕**工具适配**、**会话管理**、**资源转换**和**拦截器机制**四大支柱展开，通过模块化架构实现 MCP 工具向 LangChain 工具的透明转换。\n\n项目采用异步优先的设计理念，充分利用 Python 的 `asyncio` 能力处理 MCP 通信，同时通过 LangGraph 条件判断实现智能的工具路由。资料来源：[README.md]()\n\n## 架构总览\n\n```mermaid\ngraph TD\n A[MultiServerMCPClient] --> B[Connection 管理]\n A --> C[Session 管理]\n B --> D[StdioConnection]\n B --> E[StreamableHttpConnection]\n B --> F[SSEConnection]\n B --> G[WebsocketConnection]\n C --> H[ClientSession]\n H --> I[load_mcp_tools]\n H --> J[load_mcp_resources]\n H --> K[load_mcp_prompt]\n I --> L[StructuredTool]\n J --> M[Blob]\n K --> N[ChatPromptValue]\n L --> O[ToolCallInterceptor]\n O --> P[MCPToolCallRequest]\n P --> Q[MCPToolCallResult]\n```\n\n## 核心模块划分\n\n| 模块 | 文件 | 主要职责 |\n|------|------|----------|\n| 客户端入口 | `client.py` | 多服务器连接管理、工具资源加载 |\n| 会话管理 | `sessions.py` | 不同传输层连接创建 |\n| 工具适配 | `tools.py` | MCP工具→LangChain工具转换 |\n| 资源适配 | `resources.py` | MCP资源→LangChain Blob转换 |\n| 提示加载 | `prompts.py` | MCP提示→LangChain提示转换 |\n| 拦截器 | `interceptors.py` | 工具调用拦截与修改 |\n| 回调 | `callbacks.py` | 进度通知与事件处理 |\n\n资料来源：[langchain_mcp_adapters/client.py:1-50]()\n\n## MultiServerMCPClient 客户端模块\n\n### 功能定位\n\n`MultiServerMCPClient` 是库的入口点，负责管理对多个 MCP 服务器的连接。它支持通过配置字典同时连接到多个不同类型的服务器（stdio、HTTP SSE、WebSocket 等），并提供统一的工具、资源和提示加载接口。\n\n资料来源：[langchain_mcp_adapters/client.py:1-80]()\n\n### 连接配置\n\n客户端接受服务器配置字典，键为服务器名称，值为连接参数字典：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"./math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `command` | `str` | 执行命令（stdio传输必需） |\n| `args` | `list[str]` | 命令行参数 |\n| `transport` | `str` | 传输类型：`stdio`、`http`、`sse`、`websocket` |\n| `url` | `str` | 服务器URL（HTTP类传输必需） |\n| `headers` | `dict` | HTTP请求头（仅sse/http传输支持） |\n| `timeout` | `float` | HTTP超时时间 |\n| `env` | `dict` | 环境变量 |\n\n资料来源：[langchain_mcp_adapters/client.py:1-100]()\n\n### 上下文管理器使用方式\n\n版本 0.1.0 后，`MultiServerMCPClient` 不再支持作为异步上下文管理器直接使用：\n\n```python\n# 推荐方式一：直接调用\nclient = MultiServerMCPClient({...})\ntools = await client.get_tools()\n\n# 推荐方式二：显式会话管理\nclient = MultiServerMCPClient({...})\nasync with client.session(\"math\") as session:\n tools = await load_mcp_tools(session)\n```\n\n资料来源：[langchain_mcp_adapters/client.py:80-120]()\n\n## sessions.py 会话管理模块\n\n### 传输层抽象\n\n`sessions.py` 模块定义了多种连接类型，每种类型对应不同的 MCP 传输协议：\n\n```mermaid\ngraph LR\n A[Connection 抽象] --> B[StdioConnection]\n A --> C[StreamableHttpConnection]\n A --> D[SSEConnection]\n A --> E[WebsocketConnection]\n```\n\n资料来源：[langchain_mcp_adapters/sessions.py:1-100]()\n\n### StdioConnection\n\n通过标准输入/输出与本地进程通信，适用于本地 MCP 服务器：\n\n```python\nasync with stdio_client(server_params) as (read, write):\n async with ClientSession(read, write) as session:\n yield session\n```\n\n| 参数 | 说明 |\n|------|------|\n| `command` | 可执行命令路径 |\n| `args` | 命令行参数列表 |\n| `env` | 环境变量（支持`${...}`变量展开） |\n| `cwd` | 工作目录 |\n| `encoding` | 字符编码 |\n\n资料来源：[langchain_mcp_adapters/sessions.py:100-200]()\n\n### StreamableHttpConnection\n\n支持流式 HTTP 传输的连接类型，适用于无状态的 HTTP MCP 服务器：\n\n```python\nasync with streamablehttp_client(url, ...) as (read, write, _):\n async with ClientSession(read, write) as session:\n await session.initialize()\n```\n\n资料来源：[langchain_mcp_adapters/sessions.py:200-300]()\n\n### SSEConnection\n\n服务器发送事件（Server-Sent Events）传输连接，支持实时事件推送：\n\n```python\nasync with sse_client(url, headers=headers) as sessions:\n for session in sessions:\n # 处理每个SSE会话\n```\n\n资料来源：[langchain_mcp_adapters/sessions.py:300-400]()\n\n### WebsocketConnection\n\nWebSocket 传输连接，支持双向通信：\n\n```python\nasync with websocket_client(url) as (read, write):\n async with ClientSession(read, write) as session:\n yield session\n```\n\n资料来源：[langchain_mcp_adapters/sessions.py:400-500]()\n\n## tools.py 工具适配模块\n\n### 核心转换流程\n\n`tools.py` 模块负责将 MCP 工具转换为 LangChain 的 `StructuredTool` 对象，支持工具执行、参数验证和结果转换：\n\n```mermaid\ngraph TD\n A[MCP Tool] --> B[load_mcp_tools]\n B --> C[convert_mcp_tool_to_langchain_tool]\n C --> D[StructuredTool]\n E[工具调用] --> F[call_tool 函数]\n F --> G[拦截器链处理]\n G --> H[MCPToolCallRequest]\n H --> I[session.call_tool]\n I --> J[MCPToolCallResult]\n J --> K[_convert_call_tool_result]\n K --> L[Content + Artifact]\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:1-100]()\n\n### 工具加载函数\n\n#### load_mcp_tools\n\n加载 MCP 服务器上的所有工具：\n\n```python\nasync def load_mcp_tools(\n session: ClientSession | None,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None,\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> list[BaseTool]\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `session` | `ClientSession` | MCP客户端会话 |\n| `connection` | `Connection` | 连接配置（session为空时使用） |\n| `callbacks` | `Callbacks` | 回调处理器 |\n| `tool_interceptors` | `list[ToolCallInterceptor]` | 工具调用拦截器列表 |\n| `server_name` | `str` | 服务器名称 |\n| `tool_name_prefix` | `bool` | 是否将服务器名作为工具名前缀 |\n\n资料来源：[langchain_mcp_adapters/tools.py:200-280]()\n\n#### convert_mcp_tool_to_langchain_tool\n\n转换单个 MCP 工具为 LangChain 工具：\n\n```python\nasync def convert_mcp_tool_to_langchain_tool(\n session: ClientSession | None,\n tool: MCPTool,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None,\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> BaseTool\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:150-200]()\n\n### 内容块转换\n\n`_convert_mcp_content_to_lc_block` 函数将 MCP 内容块转换为 LangChain 内容块格式：\n\n| MCP 内容类型 | LangChain 输出 |\n|-------------|----------------|\n| `TextContent` | `{\"type\": \"text\", \"text\": ...}` |\n| `ImageContent` | `{\"type\": \"image\", \"base64\": ..., \"mime_type\": ...}` |\n| `ResourceLink` (图片) | `{\"type\": \"image\", \"url\": ...}` |\n| `ResourceLink` (其他) | `{\"type\": \"file\", \"url\": ...}` |\n| `EmbeddedResource` (文本) | `{\"type\": \"text\", \"text\": ...}` |\n| `EmbeddedResource` (二进制) | `{\"type\": \"image\"}` 或 `{\"type\": \"file\"}` |\n| `AudioContent` | 抛出 `NotImplementedError` |\n\n资料来源：[langchain_mcp_adapters/tools.py:100-150]()\n\n### 工具调用结果类型\n\n```python\n# 根据 LangGraph 可用性条件定义\nif LANGGRAPH_PRESENT:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage | Command\nelse:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage\n\n# MCP 工具工件类型\nclass MCPToolArtifact(TypedDict):\n structured_content: dict[str, Any]\n```\n\n返回结果为元组 `(content, artifact)`，其中 `artifact` 包含 MCP 服务器返回的结构化内容。\n\n资料来源：[langchain_mcp_adapters/tools.py:50-80]()\n\n## interceptors.py 拦截器模块\n\n### 拦截器模式\n\n拦截器采用洋葱模型（Onion Pattern）包装工具调用处理器，允许在调用前后进行拦截和修改：\n\n```mermaid\ngraph TD\n A[调用者] --> B[拦截器1 包装]\n B --> C[拦截器2 包装]\n C --> D[拦截器N 包装]\n D --> E[execute_tool 实际执行]\n E --> D\n D --> C\n C --> B\n B --> A\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py:1-50]()\n\n### 核心数据结构\n\n#### MCPToolCallRequest\n\n工具调用请求数据结构：\n\n```python\n@dataclass\nclass MCPToolCallRequest:\n name: str # 工具名称\n args: dict[str, Any] # 工具参数\n server_name: str # 服务器名称\n headers: dict[str, Any] | None # HTTP请求头\n runtime: Any # 运行时上下文\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py:50-100]()\n\n#### MCPToolCallResult\n\n工具调用结果类型，根据 LangGraph 可用性条件定义：\n\n```python\nif LANGGRAPH_PRESENT:\n MCPToolCallResult = CallToolResult | ToolMessage | Command\nelse:\n MCPToolCallResult = CallToolResult | ToolMessage\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py:20-40]()\n\n### ToolCallInterceptor 接口\n\n```python\n@runtime_checkable\nclass ToolCallInterceptor(Protocol):\n async def intercept(\n self,\n request: MCPToolCallRequest,\n call_next: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n ) -> MCPToolCallResult:\n ...\n```\n\n拦截器可以：\n- 在调用前修改 `request`（通过 `request.override()` 方法）\n- 跳过实际执行，直接返回结果\n- 修改或增强返回结果\n- 在调用前后执行副作用（如日志记录）\n\n资料来源：[langchain_mcp_adapters/interceptors.py:100-150]()\n\n### 请求覆盖机制\n\n`MCPToolCallRequest` 提供 `override` 方法支持部分字段修改：\n\n```python\nclass _MCPToolCallRequestOverrides(TypedDict, total=False):\n name: NotRequired[str]\n args: NotRequired[dict[str, Any]]\n headers: NotRequired[dict[str, Any] | None]\n\ndef override(self, **overrides: Unpack[_MCPToolCallRequestOverrides]) -> MCPToolCallRequest:\n \"\"\"返回修改后的请求副本\"\"\"\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py:40-50]()\n\n## callbacks.py 回调模块\n\n### 回调接口设计\n\n回调系统用于处理 MCP 服务器的通知和进度事件：\n\n```mermaid\ngraph LR\n A[MCP Server] -->|进度通知| B[Callbacks]\n A -->|日志消息| B\n A -->|资源列表变更| B\n B --> C[工具级别回调]\n```\n\n资料来源：[langchain_mcp_adapters/callbacks.py:1-50]()\n\n### CallbackContext\n\n回调上下文包含服务器信息：\n\n```python\n@dataclass\nclass CallbackContext:\n server_name: str | None = None\n tool_name: str | None = None\n```\n\n### Callbacks 类\n\n核心回调接口定义，支持多种事件类型：\n\n| 方法 | 触发时机 |\n|------|----------|\n| `progress_callback` | 服务器发送进度更新 |\n| `logger` | 服务器发送日志消息 |\n| `list_changed` | 资源/工具列表变更 |\n\n资料来源：[langchain_mcp_adapters/callbacks.py:50-100]()\n\n## resources.py 资源模块\n\n### 资源转换流程\n\n`resources.py` 模块将 MCP 资源转换为 LangChain 的 `Blob` 对象：\n\n```mermaid\ngraph LR\n A[MCP Resource URI] --> B[session.read_resource]\n B --> C[ResourceContents]\n C --> D[convert_mcp_resource_to_langchain_blob]\n D --> E[Blob]\n```\n\n资料来源：[langchain_mcp_adapters/resources.py:1-50]()\n\n### 内容类型支持\n\n| MCP 内容类型 | Blob 处理方式 |\n|-------------|---------------|\n| `TextResourceContents` | 直接使用文本内容 |\n| `BlobResourceContents` | Base64 解码后存储 |\n\n资料来源：[langchain_mcp_adapters/resources.py:50-80]()\n\n### 资源加载函数\n\n#### load_mcp_resources\n\n```python\nasync def load_mcp_resources(\n session: ClientSession,\n *,\n uris: str | list[str] | None = None,\n) -> list[Blob]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `uris=None` | 加载所有资源 |\n| `uris=str` | 加载指定 URI 的资源 |\n| `uris=list[str]` | 批量加载指定 URI 的资源 |\n\n> 注意：动态资源在 `uris=None` 时不会被加载，因为它们需要参数。\n\n资料来源：[langchain_mcp_adapters/resources.py:80-120]()\n\n## prompts.py 提示模块\n\n### 提示加载功能\n\n`prompts.py` 模块负责将 MCP 服务器上的提示模板加载为 LangChain 的聊天提示值对象，支持参数化提示生成。\n\n资料来源：[langchain_mcp_adapters/prompts.py:1-50]()\n\n## 数据流集成图\n\n### 完整工具调用流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户/LangGraph\n participant Client as MultiServerMCPClient\n participant Interceptor as ToolCallInterceptor\n participant Session as ClientSession\n participant Server as MCP Server\n \n User->>Client: get_tools()\n Client->>Session: create_session(connection)\n Session->>Server: list_tools()\n Server-->>Session: List[McpTool]\n Session-->>Client: List[BaseTool]\n Client-->>User: List[StructuredTool]\n \n User->>Client: tool.invoke(args)\n Client->>Interceptor: intercept(request)\n Interceptor->>Interceptor: request.override(...)\n Interceptor->>Session: call_tool(name, args)\n Session->>Server: call_tool()\n Server-->>Session: CallToolResult\n Session-->>Interceptor: MCPToolCallResult\n Interceptor-->>Client: MCPToolCallResult\n Client-->>User: (Content, Artifact)\n```\n\n## 配置与扩展\n\n### 工具名称前缀\n\n当连接多个服务器时，可使用 `tool_name_prefix=True` 避免工具名冲突：\n\n```python\nclient = MultiServerMCPClient(\n {\"math\": {...}, \"weather\": {...}},\n tool_name_prefix=True\n)\n# 工具名变为: math_add, weather_get_weather\n```\n\n### 拦截器链配置\n\n```python\nasync def my_interceptor(\n request: MCPToolCallRequest,\n call_next: Callable,\n) -> MCPToolCallResult:\n # 在调用前记录日志\n logger.info(f\"Calling {request.name}\")\n \n # 可以修改参数\n if request.name == \"add\":\n modified_request = request.override(args={\"a\": 1, \"b\": 2})\n return await call_next(modified_request)\n \n return await call_next(request)\n\nclient = MultiServerMCPClient(\n {...},\n tool_interceptors=[my_interceptor]\n)\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:250-300]()\n\n### HTTP 运行时头\n\n仅 `sse` 和 `http` 传输支持运行时头：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"weather\": {\n \"transport\": \"http\",\n \"url\": \"http://localhost:8000/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer custom-value\"\n }\n }\n }\n)\n```\n\n资料来源：[README.md:1-50]()\n\n## 错误处理\n\n### 工具执行异常\n\n当 MCP 工具返回错误时，`_convert_call_tool_result` 会抛出 `ToolException`：\n\n```python\nif call_tool_result.isError:\n error_parts = []\n for item in tool_content:\n if isinstance(item, dict) and item.get(\"type\") == \"text\":\n error_parts.append(item.get(\"text\", \"\"))\n error_msg = \"\\n\".join(error_parts)\n raise ToolException(error_msg)\n```\n\n### 不支持的内容类型\n\n`AudioContent` 转换尚未支持，会抛出 `NotImplementedError`：\n\n```python\nif isinstance(content, AudioContent):\n raise NotImplementedError(\n f\"AudioContent conversion not supported. \"\n f\"Mime type: {content.mimeType}\"\n )\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:100-130]()\n\n## 依赖关系\n\n| 依赖包 | 用途 |\n|--------|------|\n| `langchain-core` | LangChain 核心工具和消息类型 |\n| `mcp` | Model Context Protocol SDK |\n| `pydantic` | 数据模型验证 |\n| `langgraph` (可选) | LangGraph 集成支持 |\n\n可选依赖 `langgraph` 用于支持 `Command` 类型返回值，提供 LangGraph 特有的控制流能力。\n\n资料来源：[langchain_mcp_adapters/tools.py:1-30]()\n\n## 总结\n\nlangchain-mcp-adapters 的核心模块结构展现了清晰的分层架构设计：\n\n1. **会话层** (`sessions.py`) 屏蔽了不同传输协议的差异\n2. **适配层** (`tools.py`、`resources.py`、`prompts.py`) 处理 MCP 与 LangChain 类型系统间的转换\n3. **控制层** (`interceptors.py`) 提供了灵活的扩展机制\n4. **入口层** (`client.py`) 整合所有能力，提供统一的用户体验\n\n这种设计使得库能够在保持简洁 API 的同时，支持复杂的 MCP 服务器集成场景。\n\n---\n\n\n\n## 数据流与转换机制\n\n### 相关页面\n\n相关主题：[核心模块结构](#page-core-modules), [工具转换机制](#page-tools-conversion)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n \n\n# 数据流与转换机制\n\n本页面详细说明 langchain-mcp-adapters 库中数据如何在 MCP（Model Context Protocol）与 LangChain 之间流转与转换。核心转换逻辑涵盖工具（Tools）、资源（Resources）和内容块（Content Blocks）三种数据类型。\n\n---\n\n## 1. 整体架构概览\n\n该库采用分层架构，通过适配器模式将 MCP 服务器的功能桥接到 LangChain 生态。数据流遵循以下基本原则：\n\n```mermaid\ngraph TD\n subgraph MCP服务器层\n A[MCP Server]\n A1[Tools]\n A2[Resources]\n A3[Prompts]\n end\n\n subgraph 适配器层\n B[ClientSession]\n C[tools.py]\n D[resources.py]\n E[prompts.py]\n end\n\n subgraph LangChain层\n F[BaseTool]\n G[Blob]\n H[Prompt]\n end\n\n A1 --> B --> C --> F\n A2 --> B --> D --> G\n A3 --> B --> E --> H\n\n style C fill:#e1f5fe\n style D fill:#e8f5e8\n style E fill:#fff3e0\n```\n\n---\n\n## 2. 内容块转换机制\n\n### 2.1 核心转换函数\n\n`_convert_mcp_content_to_lc_block()` 函数负责将 MCP 内容块转换为 LangChain 内容块格式 资料来源：[langchain_mcp_adapters/tools.py:60-102]()\n\n```python\ndef _convert_mcp_content_to_lc_block(content: ContentBlock) -> ToolMessageContentBlock:\n \"\"\"Convert any MCP content block to a LangChain content block.\"\"\"\n```\n\n### 2.2 支持的内容类型映射\n\n| MCP 内容类型 | LangChain 内容块类型 | 转换逻辑 |\n|-------------|---------------------|---------|\n| `TextContent` | `{\"type\": \"text\", \"text\": ...}` | 直接提取 `text` 字段 |\n| `ImageContent` | `{\"type\": \"image\", \"base64\": ..., \"mime_type\": ...}` | 提取 `data` 和 `mimeType` |\n| `AudioContent` | - | 抛出 `NotImplementedError` |\n| `ResourceLink` (image/*) | `{\"type\": \"image\", \"url\": ...}` | 提取 URI 和 mimeType |\n| `ResourceLink` (其他) | `{\"type\": \"file\", \"url\": ...}` | 提取 URI 和 mimeType |\n| `EmbeddedResource` (text) | `{\"type\": \"text\", \"text\": ...}` | 提取内部 resource.text |\n| `EmbeddedResource` (blob) | `{\"type\": \"image\"}` 或 `{\"type\": \"file\"}` | 根据 mimeType 判断 |\n\n### 2.3 内容块转换流程图\n\n```mermaid\ngraph LR\n A[ContentBlock 输入] --> B{类型判断}\n\n B -->|TextContent| C[create_text_block]\n B -->|ImageContent| D[create_image_block]\n B -->|AudioContent| E[NotImplementedError]\n B -->|ResourceLink| F{image/* ?}\n B -->|EmbeddedResource| G{resource类型}\n\n F -->|是| H[create_image_block]\n F -->|否| I[create_file_block]\n\n G -->|TextResourceContents| J[create_text_block]\n G -->|BlobResourceContents| K{image/* ?}\n K -->|是| L[create_image_block]\n K -->|否| M[create_file_block]\n\n C --> N[ToolMessageContentBlock]\n D --> N\n H --> N\n I --> N\n J --> N\n L --> N\n M --> N\n```\n\n---\n\n## 3. 工具转换机制\n\n### 3.1 工具加载入口\n\n`load_mcp_tools()` 函数是加载 MCP 工具的核心入口，负责列出并转换所有可用工具 资料来源：[langchain_mcp_adapters/tools.py:240-290]()\n\n```python\nasync def load_mcp_tools(\n session: ClientSession | None,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None,\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> list[BaseTool]:\n```\n\n### 3.2 单个工具转换\n\n`convert_mcp_tool_to_langchain_tool()` 函数将单个 MCP 工具转换为 LangChain `StructuredTool` 资料来源：[langchain_mcp_adapters/tools.py:165-238]()\n\n```python\ndef convert_mcp_tool_to_langchain_tool(\n session: ClientSession | None,\n tool: MCPTool,\n *,\n connection: Connection | None = None,\n # ... 其他参数\n) -> BaseTool:\n```\n\n**返回的 StructuredTool 配置：**\n\n| 参数 | 来源 | 说明 |\n|-----|------|-----|\n| `name` | `tool.name` 或 `server_name + tool.name` | 可选前缀 |\n| `description` | `tool.description` | 工具描述 |\n| `args_schema` | `tool.inputSchema` | Pydantic 模型 |\n| `coroutine` | `call_tool` 协程 | 异步执行函数 |\n| `response_format` | `\"content_and_artifact\"` | 返回格式 |\n| `metadata` | 工具注解 | 包含元数据 |\n\n### 3.3 工具转换流程\n\n```mermaid\ngraph TD\n A[MCP Tool 输入] --> B[创建 MCP ClientSession]\n B --> C[构建 MCPToolCallRequest]\n C --> D{是否配置拦截器?}\n\n D -->|是| E[执行拦截器链]\n D -->|否| F[直接执行工具]\n\n E --> G[洋葱模型执行]\n F --> H[session.call_tool]\n G --> H\n\n H --> I[MCPToolCallResult]\n I --> J[_convert_call_tool_result]\n\n J --> K[ConvertedToolResult]\n J --> L[MCPToolArtifact]\n\n K --> M[StructuredTool.content]\n L --> M\n```\n\n### 3.4 工具结果转换\n\n`_convert_call_tool_result()` 处理工具调用结果，支持多种返回类型 资料来源：[langchain_mcp_adapters/tools.py:104-164]()\n\n```python\ndef _convert_call_tool_result(\n call_tool_result: MCPToolCallResult,\n) -> tuple[ConvertedToolResult, MCPToolArtifact | None]:\n```\n\n**返回值类型定义：**\n\n```python\nif LANGGRAPH_PRESENT:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage | Command\nelse:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage\n```\n\n**特殊返回值处理：**\n\n| 输入类型 | 行为 |\n|---------|------|\n| `ToolMessage` | 直接返回，不转换 |\n| `Command` (LangGraph) | 直接返回，支持图执行 |\n| `CallToolResult` + `isError=True` | 抛出 `ToolException` |\n| `CallToolResult` + `structuredContent` | 包装为 `MCPToolArtifact` |\n\n### 3.5 MCPToolArtifact 数据结构\n\n```python\nclass MCPToolArtifact(TypedDict):\n \"\"\"Artifact returned from MCP tool calls.\"\"\"\n structured_content: dict[str, Any]\n```\n\n---\n\n## 4. 拦截器链机制\n\n### 4.1 拦截器模式\n\n拦截器采用洋葱模型（Onion Pattern）构建处理链，允许在工具调用前后插入自定义逻辑 资料来源：[langchain_mcp_adapters/interceptors.py]()\n\n```python\ndef _build_interceptor_chain(\n base_handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n tool_interceptors: list[ToolCallInterceptor] | None,\n) -> Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]]:\n```\n\n### 4.2 拦截器请求类型\n\n```python\n@dataclass\nclass MCPToolCallRequest:\n \"\"\"Tool execution request passed to MCP tool call interceptors.\"\"\"\n name: str\n args: dict[str, Any]\n server_name: str\n headers: dict[str, Any] | None\n runtime: Any\n```\n\n### 4.3 拦截器链执行顺序\n\n```mermaid\ngraph TD\n subgraph 拦截器链\n A[请求入口] --> B[拦截器 1 外层]\n B --> C[拦截器 2]\n C --> D[...]\n D --> E[拦截器 N]\n E --> F[base_handler]\n end\n\n subgraph 返回路径\n F --> G[拦截器 N 处理]\n G --> H[拦截器 2 处理]\n H --> I[拦截器 1 处理]\n I --> J[最终结果]\n end\n\n style F fill:#c8e6c9\n```\n\n---\n\n## 5. 资源转换机制\n\n### 5.1 资源到 Blob 的转换\n\n`convert_mcp_resource_to_langchain_blob()` 将 MCP 资源内容转换为 LangChain Blob 对象 资料来源：[langchain_mcp_adapters/resources.py:19-41]()\n\n```python\ndef convert_mcp_resource_to_langchain_blob(\n resource_uri: str, contents: ResourceContents\n) -> Blob:\n \"\"\"Convert an MCP resource content to a LangChain Blob.\"\"\"\n```\n\n**转换逻辑：**\n\n| 资源类型 | 数据处理 |\n|---------|---------|\n| `TextResourceContents` | 直接使用 `text` 字段 |\n| `BlobResourceContents` | `base64.b64decode(blob)` 解码 |\n\n**返回的 Blob 配置：**\n\n```python\nreturn Blob.from_data(\n data=data,\n mime_type=contents.mimeType,\n metadata={\"uri\": resource_uri}\n)\n```\n\n### 5.2 资源加载函数\n\n```mermaid\ngraph LR\n A[load_mcp_resources] --> B{uris 参数?}\n\n B -->|None| C[session.list_resources]\n B -->|str| D[单个 URI]\n B -->|list| E[多个 URI]\n\n C --> F[获取 URI 列表]\n D --> G[session.read_resource]\n E --> G\n F --> G\n\n G --> H[convert_mcp_resource_to_langchain_blob]\n H --> I[Blob 列表]\n```\n\n---\n\n## 6. 会话与连接管理\n\n### 6.1 连接类型支持\n\n`MultiServerMCPClient` 支持多种传输协议连接 资料来源：[langchain_mcp_adapters/client.py]()：\n\n| 传输类型 | 实现类 | 说明 |\n|---------|--------|------|\n| `stdio` | `StdioConnection` | 标准输入输出进程通信 |\n| `sse` | `SSEConnection` | Server-Sent Events |\n| `http` | `StreamableHttpConnection` | HTTP 流式传输 |\n| `websocket` | `WebsocketConnection` | WebSocket 通信 |\n\n### 6.2 会话创建流程\n\n```mermaid\ngraph TD\n A[MultiServerMCPClient.get_tools] --> B{连接类型}\n\n B -->|Stdio| C[StdioServerParameters]\n B -->|SSE| D[SSE 参数]\n B -->|HTTP| E[HTTP 参数]\n B -->|WebSocket| F[WebSocket 参数]\n\n C --> G[stdio_client]\n D --> H[mcp.client.sse]\n E --> I[streamablehttp_client]\n F --> J[websocket_client]\n\n G --> K[ClientSession]\n H --> K\n I --> K\n J --> K\n\n K --> L[load_mcp_tools]\n L --> M[LangChain Tools]\n```\n\n---\n\n## 7. 完整数据流示例\n\n### 7.1 工具调用完整流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户/Agent\n participant LC as LangChain Tool\n participant Adapter as langchain-mcp-adapters\n participant MCP as MCP ClientSession\n participant Server as MCP Server\n\n User->>LC: 调用工具 (name, args)\n LC->>Adapter: call_tool(request)\n Adapter->>Adapter: 构建 MCPToolCallRequest\n Adapter->>Adapter: 执行拦截器链\n Adapter->>MCP: session.call_tool(name, args)\n MCP->>Server: MCP 协议调用\n Server-->>MCP: CallToolResult\n MCP-->>Adapter: CallToolResult\n Adapter->>Adapter: _convert_call_tool_result\n Adapter-->>LC: (ConvertedToolResult, Artifact)\n LC-->>User: ToolMessage / Command\n```\n\n### 7.2 资源访问完整流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Adapter as langchain-mcp-adapters\n participant MCP as MCP ClientSession\n participant Server as MCP Server\n\n User->>Adapter: load_mcp_resources(session, uris)\n Adapter->>MCP: session.list_resources()\n MCP-->>Adapter: 资源列表\n Adapter->>MCP: session.read_resource(uri)\n MCP->>Server: 读取资源请求\n Server-->>MCP: ResourceContents\n MCP-->>Adapter: ResourceContents\n Adapter->>Adapter: 转换内容块\n Adapter-->>User: Blob 对象列表\n```\n\n---\n\n## 8. 类型转换参考\n\n### 8.1 导入的 MCP 类型\n\n| 类型 | 来源 | 用途 |\n|-----|------|-----|\n| `Tool` | `mcp.types` | MCP 工具定义 |\n| `CallToolResult` | `mcp.types` | 工具调用结果 |\n| `ContentBlock` | `mcp.types` | 内容块基类 |\n| `TextContent` | `mcp.types` | 文本内容 |\n| `ImageContent` | `mcp.types` | 图片内容 |\n| `AudioContent` | `mcp.types` | 音频内容 |\n| `ResourceLink` | `mcp.types` | 资源链接 |\n| `EmbeddedResource` | `mcp.types` | 嵌入式资源 |\n\n### 8.2 导入的 LangChain 类型\n\n| 类型 | 来源 | 用途 |\n|-----|------|-----|\n| `BaseTool` | `langchain_core.tools` | LangChain 工具基类 |\n| `StructuredTool` | `langchain_core.tools` | 结构化工具 |\n| `ToolMessage` | `langchain_core.messages` | 工具消息 |\n| `ToolMessageContentBlock` | 自定义类型别名 | 内容块联合类型 |\n| `Blob` | `langchain_core.documents.base` | LangChain Blob |\n\n---\n\n## 9. 错误处理\n\n### 9.1 已实现的异常\n\n| 异常类型 | 触发条件 | 处理位置 |\n|---------|---------|---------|\n| `ToolException` | 工具返回 `isError=True` | `_convert_call_tool_result()` |\n| `NotImplementedError` | 遇到 `AudioContent` | `_convert_mcp_content_to_lc_block()` |\n| `ValueError` | 未知内容类型 | `_convert_mcp_content_to_lc_block()` |\n| `TypeError` | 不支持的资源类型 | `convert_mcp_resource_to_langchain_blob()` |\n\n### 9.2 错误处理流程\n\n```mermaid\ngraph TD\n A[工具调用结果] --> B{isError?}\n B -->|是| C[收集所有文本块]\n C --> D[拼接错误消息]\n D --> E[抛出 ToolException]\n\n B -->|否| F{structuredContent?}\n F -->|有| G[创建 MCPToolArtifact]\n F -->|无| H[返回 None artifact]\n\n G --> I[返回结果和 artifact]\n H --> I\n```\n\n---\n\n## 10. 关键配置参数\n\n### 10.1 load_mcp_tools 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|--------|-----|\n| `session` | `ClientSession` | 必填 | MCP 客户端会话 |\n| `connection` | `Connection` | `None` | 连接配置（无 session 时使用） |\n| `callbacks` | `Callbacks` | `None` | 回调处理器 |\n| `tool_interceptors` | `list[ToolCallInterceptor]` | `None` | 拦截器列表 |\n| `server_name` | `str` | `None` | 服务器名称 |\n| `tool_name_prefix` | `bool` | `False` | 是否为工具名添加前缀 |\n\n### 10.2 MultiServerMCPClient 配置结构\n\n```python\nclient = MultiServerMCPClient({\n \"server_name\": {\n \"transport\": \"stdio\" | \"sse\" | \"http\" | \"websocket\",\n \"command\": \"python\",\n \"args\": [\"/path/to/server.py\"],\n \"env\": {\"KEY\": \"value\"},\n \"url\": \"http://localhost:8000/mcp\",\n \"headers\": {\"Authorization\": \"Bearer xxx\"},\n }\n})\n```\n\n---\n\n本页面涵盖了 langchain-mcp-adapters 库中数据流与转换机制的核心实现，理解这些机制有助于深度定制工具调用流程和构建复杂的多服务器 MCP 集成方案。\n\n---\n\n\n\n## MultiServerMCPClient 客户端\n\n### 相关页面\n\n相关主题：[传输协议类型](#page-transport-types), [工具转换机制](#page-tools-conversion)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n- [langchain_mcp_adapters/prompts.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/prompts.py)\n- [langchain_mcp_adapters/callbacks.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/callbacks.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [README.md](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/README.md)\n \n\n# MultiServerMCPClient 客户端\n\n## 概述\n\n`MultiServerMCPClient` 是 langchain-mcp-adapters 库的核心客户端类，用于连接多个 MCP（Model Context Protocol）服务器并从中加载 LangChain 兼容的工具、提示词和资源。\n\n该客户端的主要作用是将 MCP 服务器提供的工具转换为 LangChain 工具格式，使其能够与 LangChain 和 LangGraph 代理无缝集成。`MultiServerMCPClient` 支持同时连接多个 MCP 服务器，并提供了灵活的配置选项来管理连接、回调和工具调用拦截。\n\n资料来源：[langchain_mcp_adapters/client.py:40-50]()\n\n## 架构设计\n\n### 组件关系图\n\n```mermaid\ngraph TD\n Client[MultiServerMCPClient]\n Conn[connections
dict[str, Connection]]\n Callbacks[Callbacks]\n Interceptors[tool_interceptors
list[ToolCallInterceptor]]\n Prefix[tool_name_prefix
bool]\n \n Client --> Conn\n Client --> Callbacks\n Client --> Interceptors\n Client --> Prefix\n \n Conn --> Stdio[StdioConnection]\n Conn --> SSE[SSEConnection]\n Conn --> HTTP[StreamableHttpConnection]\n Conn --> WS[WebsocketConnection]\n \n Client --> Tools[load_mcp_tools]\n Client --> Resources[load_mcp_resources]\n Client --> Prompts[load_mcp_prompt]\n```\n\n### 核心数据流\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Client as MultiServerMCPClient\n participant Session as ClientSession\n participant Interceptor as ToolCallInterceptor\n participant Server as MCP Server\n \n User->>Client: get_tools()\n Client->>Client: create_session()\n Client->>Session: 初始化连接\n Client->>Session: list_tools()\n Session->>Server: 请求工具列表\n Server-->>Session: 返回工具定义\n Session-->>Client: MCP Tools\n Client->>Interceptor: 链式包装\n Client-->>User: LangChain BaseTools\n```\n\n## 初始化参数\n\n`MultiServerMCPClient` 的构造函数接受以下参数：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `connections` | `dict[str, Connection] \\| None` | `None` | 服务器名称到连接配置的映射字典 |\n| `callbacks` | `Callbacks \\| None` | `None` | 处理通知和事件的回调函数 |\n| `tool_interceptors` | `list[ToolCallInterceptor] \\| None` | `None` | 工具调用拦截器列表 |\n| `tool_name_prefix` | `bool` | `False` | 是否将工具名称前缀服务器名称 |\n\n### connections 配置结构\n\n```python\nconnections: dict[str, Connection] = {\n \"server_name\": {\n # 标准传输配置\n \"command\": \"python\",\n \"args\": [\"/path/to/server.py\"],\n \"transport\": \"stdio\",\n \n # 或 HTTP 传输配置\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n \"headers\": {\"Authorization\": \"Bearer token\"},\n \n # 或其他连接选项...\n }\n}\n```\n\n资料来源：[langchain_mcp_adapters/client.py:50-90]()\n\n## 连接类型\n\n`sessions.py` 模块定义了多种连接类型，支持不同的 MCP 服务器部署方式：\n\n| 连接类型 | 传输协议 | 说明 |\n|----------|----------|------|\n| `StdioConnection` | stdio | 通过标准输入/输出通信，适用于本地进程 |\n| `SSEConnection` | SSE | Server-Sent Events，适用于长连接场景 |\n| `StreamableHttpConnection` | HTTP | 可流式传输的 HTTP 连接 |\n| `WebsocketConnection` | WebSocket | WebSocket 协议连接 |\n\n### StdioConnection 配置\n\n```python\n{\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n \"env\": {\"KEY\": \"value\"}, # 可选：传递给进程的环境变量\n \"cwd\": \"/working/directory\", # 可选：工作目录\n}\n```\n\n资料来源：[langchain_mcp_adapters/sessions.py]()\n\n### HTTP/StreamableHttpConnection 配置\n\n```python\n{\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\", # 或 \"streamable_http\"\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"X-Custom-Header\": \"custom-value\"\n },\n \"timeout\": 60.0, # HTTP 请求超时时间\n}\n```\n\n> 仅 `sse` 和 `http` 传输支持运行时 headers\n\n资料来源：[README.md]()\n\n## 核心方法\n\n### get_tools()\n\n获取所有已连接 MCP 服务器的工具列表。\n\n```python\nasync def get_tools(\n self,\n server_name: str | None = None\n) -> list[BaseTool]\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `server_name` | `str \\| None` | 可选，指定服务器名称过滤工具 |\n\n**返回值**: LangChain `BaseTool` 对象列表\n\n资料来源：[langchain_mcp_adapters/client.py]()\n\n### session()\n\n建立与特定 MCP 服务器的会话连接。\n\n```python\n@asynccontextmanager\nasync def session(\n self,\n server_name: str\n) -> AsyncIterator[ClientSession]\n```\n\n**用法示例**:\n```python\nclient = MultiServerMCPClient({...})\nasync with client.session(\"math\") as session:\n tools = await load_mcp_tools(session)\n```\n\n资料来源：[langchain_mcp_adapters/client.py]()\n\n## 使用示例\n\n### 基础用法\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\nall_tools = await client.get_tools()\n```\n\n资料来源：[langchain_mcp_adapters/client.py:75-90]()\n\n### 多服务器连接\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain.agents import create_agent\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\ntools = await client.get_tools()\nagent = create_agent(\"openai:gpt-4.1\", tools)\nresponse = await agent.ainvoke({\"messages\": \"what's (3 + 5) x 12?\"})\n```\n\n资料来源：[README.md]()\n\n### 工具名称前缀\n\n当多个服务器有相同名称的工具时，可使用 `tool_name_prefix` 避免冲突：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n },\n tool_name_prefix=True # 工具名变为 \"weather_search\" 而非 \"search\"\n)\ntools = await client.get_tools()\n```\n\n资料来源：[langchain_mcp_adapters/client.py:61-65]()\n\n## 与 LangGraph 集成\n\n`MultiServerMCPClient` 可与 LangGraph 的 `StateGraph` 结合使用构建复杂代理：\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.graph import StateGraph, MessagesState, START\nfrom langgraph.prebuilt import ToolNode, tools_condition\n\nfrom langchain.chat_models import init_chat_model\n\nmodel = init_chat_model(\"openai:gpt-4.1\")\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"./examples/math_server.py\"],\n \"transport\": \"stdio\",\n },\n }\n)\ntools = await client.get_tools()\n\ndef call_model(state: MessagesState):\n response = model.bind_tools(tools).invoke(state[\"messages\"])\n return {\"messages\": response}\n\nbuilder = StateGraph(MessagesState)\nbuilder.add_node(\"call_model\", call_model)\nbuilder.add_node(\"tools\", ToolNode(tools))\nbuilder.add_edge(START, \"call_model\")\nbuilder.add_conditional_edges(\n \"call_model\",\n tools_condition,\n)\nbuilder.add_edge(\"tools\", \"call_model\")\ngraph = builder.compile()\n```\n\n资料来源：[README.md]()\n\n## 回调机制\n\n`Callbacks` 类提供了处理 MCP 事件的接口：\n\n```python\n@dataclass\nclass Callbacks:\n \"\"\"LangChain MCP 客户端回调\"\"\"\n \n on_logging_message: LoggingMessageCallback | None = None\n on_progress: ProgressCallback | None = None\n on_elicitation: ElicitationCallback | None = None\n```\n\n| 回调类型 | 说明 |\n|----------|------|\n| `on_logging_message` | 日志消息回调 |\n| `on_progress` | 进度通知回调 |\n| `on_elicitation` | 追问/确认请求回调 |\n\n### 回调使用示例\n\n```python\nfrom langchain_mcp_adapters.callbacks import Callbacks, CallbackContext\n\nasync def my_logging_callback(params, context: CallbackContext):\n print(f\"Log: {params}\")\n\ncallbacks = Callbacks(on_logging_message=my_logging_callback)\n\nclient = MultiServerMCPClient(\n {...},\n callbacks=callbacks\n)\n```\n\n资料来源：[langchain_mcp_adapters/callbacks.py]()\n\n## 工具拦截器\n\n`ToolCallInterceptor` 接口允许在工具调用前后进行拦截和处理：\n\n```mermaid\ngraph TD\n Request[MCPToolCallRequest] -->|洋葱模型| I1[Interceptor 1]\n I1 --> I2[Interceptor 2]\n I2 --> I3[Interceptor N]\n I3 --> Handler[Base Handler]\n Handler --> R1[Result 1]\n R1 --> R2[Result 2]\n R2 --> R3[Result N]\n R3 --> Response[MCPToolCallResult]\n```\n\n### 拦截器链构建\n\n```python\ndef _build_interceptor_chain(\n base_handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n tool_interceptors: list[ToolCallInterceptor] | None,\n) -> Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]]\n```\n\n拦截器列表中的第一个拦截器成为最外层，以洋葱模式层层包裹。\n\n### 使用拦截器\n\n```python\nfrom langchain_mcp_adapters.interceptors import (\n MCPToolCallRequest,\n MCPToolCallResult,\n ToolCallInterceptor,\n)\n\nclass LoggingInterceptor(ToolCallInterceptor):\n async def intercept(\n self, request: MCPToolCallRequest, handler\n ) -> MCPToolCallResult:\n print(f\"Calling tool: {request.name}\")\n result = await handler(request)\n print(f\"Tool result: {result}\")\n return result\n\nclient = MultiServerMCPClient(\n {...},\n tool_interceptors=[LoggingInterceptor()]\n)\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py]()\n资料来源：[langchain_mcp_adapters/tools.py:145-175]()\n\n## 注意事项\n\n### 上下文管理器使用限制\n\n> [!warning]\n> 从 langchain-mcp-adapters 0.1.0 版本开始，`MultiServerMCPClient` 不能作为异步上下文管理器使用。\n\n**正确用法**:\n```python\n# 方法 1：直接获取工具\nclient = MultiServerMCPClient(...)\ntools = await client.get_tools()\n\n# 方法 2：显式创建会话\nclient = MultiServerMCPClient(...)\nasync with client.session(server_name) as session:\n tools = await load_mcp_tools(session)\n```\n\n资料来源：[langchain_mcp_adapters/client.py:38-55]()\n\n## 资源与提示词加载\n\n除了工具，`MultiServerMCPClient` 还支持加载 MCP 资源（Blob）和提示词：\n\n### 资源加载\n\n```python\nfrom langchain_mcp_adapters.resources import load_mcp_resources\n\nasync with client.session(\"server_name\") as session:\n blobs = await load_mcp_resources(session)\n```\n\n资料来源：[langchain_mcp_adapters/resources.py]()\n\n### 提示词加载\n\n```python\nfrom langchain_mcp_adapters.prompts import load_mcp_prompt\n\nasync with client.session(\"server_name\") as session:\n messages = await load_mcp_prompt(session, \"prompt_name\", arguments)\n```\n\n资料来源：[langchain_mcp_adapters/prompts.py]()\n\n## 配置参考\n\n### 完整配置示例\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain_mcp_adapters.callbacks import Callbacks\n\nclient = MultiServerMCPClient(\n connections={\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n \"env\": {\"DEBUG\": \"true\"},\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n \"headers\": {\"Authorization\": \"Bearer token\"},\n },\n },\n callbacks=Callbacks(\n on_logging_message=my_logging_callback,\n on_progress=my_progress_callback,\n ),\n tool_interceptors=[LoggingInterceptor()],\n tool_name_prefix=True,\n)\n```\n\n## 总结\n\n`MultiServerMCPClient` 是连接 MCP 服务器与 LangChain 生态系统的桥梁，提供：\n\n- 多服务器并发连接管理\n- 统一的工具转换机制\n- 灵活的回调和拦截器支持\n- 多种传输协议兼容（stdio、HTTP、SSE、WebSocket）\n- 与 LangGraph 的深度集成\n\n---\n\n\n\n## 工具转换机制\n\n### 相关页面\n\n相关主题：[MultiServerMCPClient 客户端](#page-multiserver-client), [数据流与转换机制](#page-data-flow), [工具调用拦截器](#page-interceptors)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [README.md](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/README.md)\n \n\n# 工具转换机制\n\n## 概述\n\n工具转换机制是 langchain-mcp-adapters 库的核心功能，负责将 MCP（Model Context Protocol）工具转换为 LangChain 兼容的工具格式。该机制使得 MCP 服务器提供的工具能够无缝集成到 LangChain 和 LangGraph 智能体应用中。\n\n主要职责包括：\n- 将 MCP 工具声明转换为 LangChain StructuredTool\n- 处理工具调用请求和响应的格式转换\n- 支持内容块的类型转换（文本、图像、音频等）\n- 提供拦截器链模式用于工具调用的扩展处理\n\n资料来源：[tools.py:1-30]()\n\n## 核心类型定义\n\n### 内容块类型\n\n工具转换机制定义了一系列类型别名用于处理不同格式的内容：\n\n```python\n# Type alias for LangChain content blocks used in ToolMessage\nToolMessageContentBlock = TextContentBlock | ImageContentBlock | FileContentBlock\n```\n\n### 转换结果类型\n\n根据 langgraph 是否安装，返回类型有所不同：\n\n```python\nif LANGGRAPH_PRESENT:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage | Command\nelse:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage\n```\n\n### 工具调用产物\n\n```python\nclass MCPToolArtifact(TypedDict):\n \"\"\"Artifact returned from MCP tool calls.\"\"\"\n structured_content: dict[str, Any]\n```\n\nMCPToolArtifact 是一个 TypedDict，用于包装 MCP 工具调用返回的结构化内容，允许未来扩展更多字段。\n\n资料来源：[tools.py:44-68]()\n\n## 核心转换函数\n\n### 内容块转换\n\n`_convert_mcp_content_to_lc_block()` 函数负责将 MCP 内容块转换为 LangChain 内容块格式：\n\n```mermaid\ngraph TD\n A[MCP ContentBlock] --> B{内容类型判断}\n B -->|TextContent| C[create_text_block]\n B -->|ImageContent| D[create_image_block]\n B -->|AudioContent| E[NotImplementedError]\n B -->|ResourceLink| F{是否为图像类型}\n B -->|EmbeddedResource| G{资源类型判断}\n F -->|是| H[create_image_block]\n F -->|否| I[create_file_block]\n G -->|TextResourceContents| J[create_text_block]\n G -->|BlobResourceContents| K{是否为图像}\n K -->|是| L[create_image_block]\n K -->|否| M[create_file_block]\n```\n\n支持的转换映射关系：\n\n| MCP 内容类型 | LangChain 内容块 | 说明 |\n|-------------|-----------------|------|\n| TextContent | {\"type\": \"text\", \"text\": ...} | 文本内容直接转换 |\n| ImageContent | {\"type\": \"image\", \"base64\": ..., \"mime_type\": ...} | 图像内容带 MIME 类型 |\n| ResourceLink (image/*) | {\"type\": \"image\", \"url\": ..., \"mime_type\": ...} | 图像资源链接 |\n| ResourceLink (other) | {\"type\": \"file\", \"url\": ..., \"mime_type\": ...} | 非图像资源链接 |\n| EmbeddedResource (text) | {\"type\": \"text\", \"text\": ...} | 内嵌文本资源 |\n| EmbeddedResource (blob) | {\"type\": \"image/file\", ...} | 内嵌二进制资源 |\n| AudioContent | 抛出 NotImplementedError | 暂不支持 |\n\n资料来源：[tools.py:71-133]()\n\n### 工具调用结果转换\n\n`_convert_call_tool_result()` 函数将 MCP 的 CallToolResult 转换为 LangChain 格式：\n\n```python\ndef _convert_call_tool_result(\n call_tool_result: MCPToolCallResult,\n) -> tuple[ConvertedToolResult, MCPToolArtifact | None]:\n```\n\n处理逻辑：\n1. 如果返回的是 ToolMessage，直接返回并设置 artifact 为 None\n2. 如果返回的是 Command（LangGraph），直接返回并设置 artifact 为 None\n3. 将所有 MCP 内容块转换为 LangChain 内容块\n4. 如果工具调用出错，抛出 ToolException\n5. 如果存在 structuredContent，包装为 MCPToolArtifact\n\n资料来源：[tools.py:166-216]()\n\n## 工具加载与转换\n\n### 加载所有 MCP 工具\n\n`load_mcp_tools()` 函数从 MCP 会话加载所有可用工具：\n\n```python\nasync def load_mcp_tools(\n session: ClientSession | None,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None,\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> list[BaseTool]:\n```\n\n参数说明：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| session | ClientSession | 必填 | MCP 客户端会话 |\n| connection | Connection | None | 用于创建新会话的连接配置 |\n| callbacks | Callbacks | None | 处理通知和事件的回调 |\n| tool_interceptors | list[ToolCallInterceptor] | None | 工具调用拦截器列表 |\n| server_name | str | None | 服务器名称 |\n| tool_name_prefix | bool | False | 是否将工具名添加服务器前缀 |\n\n该函数支持分页加载工具，处理最大 1000 次迭代的循环：\n\n```python\nMAX_ITERATIONS = 1000\n```\n\n资料来源：[tools.py:240-295]()\n\n### 单个工具转换\n\n`convert_mcp_tool_to_langchain_tool()` 函数将单个 MCP 工具转换为 LangChain StructuredTool：\n\n```python\ndef convert_mcp_tool_to_langchain_tool(\n session: ClientSession | None,\n tool: MCPTool,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None,\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> BaseTool:\n```\n\n转换后的工具配置：\n\n| 属性 | 来源 | 说明 |\n|------|------|------|\n| name | tool.name 或 f\"{server_name}_{tool.name}\" | 工具名称 |\n| description | tool.description | 工具描述 |\n| args_schema | tool.inputSchema | 参数模式定义 |\n| coroutine | call_tool | 异步执行函数 |\n| response_format | \"content_and_artifact\" | 响应格式 |\n| metadata | tool.annotations.model_dump() | 元数据信息 |\n\n资料来源：[tools.py:297-370]()\n\n## 工具调用执行机制\n\n### 拦截器链模式\n\n工具调用采用洋葱模式（Onion Pattern）构建拦截器链：\n\n```mermaid\ngraph LR\n A[请求] --> B[拦截器 N]\n B --> C[拦截器 N-1]\n C --> D[...]\n D --> E[拦截器 1]\n E --> F[实际工具执行]\n F --> G[拦截器 1]\n G --> H[...]\n H --> I[拦截器 N-1]\n I --> J[响应]\n```\n\n`_build_interceptor_chain()` 函数实现该模式：\n\n```python\ndef _build_interceptor_chain(\n base_handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n tool_interceptors: list[ToolCallInterceptor] | None,\n) -> Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]]:\n \"\"\"Build composed handler chain with interceptors in onion pattern.\"\"\"\n handler = base_handler\n if tool_interceptors:\n for interceptor in reversed(tool_interceptors):\n current_handler = handler\n # 包装逻辑\n return handler\n```\n\n资料来源：[tools.py:136-160](), [interceptors.py:1-45]()\n\n### 工具调用请求\n\nMCPToolCallRequest 是拦截器系统中定义的请求类型：\n\n```python\n@dataclass\nclass MCPToolCallRequest:\n \"\"\"Tool execution request passed to MCP tool call interceptors.\"\"\"\n name: str # 工具名称\n args: dict[str, Any] # 工具参数\n server_name: str # 服务器名称\n headers: dict[str, Any] | None # HTTP 请求头\n runtime: object | None # LangGraph 运行时\n```\n\n### 工具调用响应\n\nMCPToolCallResult 的类型定义：\n\n```python\nif LANGGRAPH_PRESENT:\n MCPToolCallResult = CallToolResult | ToolMessage | Command\nelse:\n MCPToolCallResult = CallToolResult | ToolMessage\n```\n\n资料来源：[interceptors.py:40-55]()\n\n## 错误处理机制\n\n工具转换机制实现了多层错误处理：\n\n### 工具调用错误\n\n当 MCP 工具调用返回错误时：\n\n```python\nif call_tool_result.isError:\n error_parts = []\n for item in tool_content:\n if isinstance(item, str):\n error_parts.append(item)\n elif isinstance(item, dict) and item.get(\"type\") == \"text\":\n error_parts.append(item.get(\"text\", \"\"))\n error_msg = \"\\n\".join(error_parts) if error_parts else str(tool_content)\n raise ToolException(error_msg)\n```\n\n### 内容类型错误\n\n不支持的内容类型会抛出相应异常：\n\n| 内容类型 | 异常类型 | 错误信息 |\n|---------|---------|---------|\n| AudioContent | NotImplementedError | \"AudioContent conversion to LangChain content blocks is not yet supported\" |\n| 未知内容类型 | ValueError | \"Unknown MCP content type: {type}\" |\n| 未知嵌入资源 | ValueError | \"Unknown embedded resource type: {type}\" |\n\n资料来源：[tools.py:88-95](), [tools.py:125-133]()\n\n## 使用示例\n\n### 基础用法\n\n```python\nfrom mcp import ClientSession\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\n# 通过现有会话加载工具\ntools = await load_mcp_tools(session)\n```\n\n### 完整客户端示例\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain.agents import create_agent\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\ntools = await client.get_tools()\n```\n\n### 带拦截器的用法\n\n```python\nfrom langchain_mcp_adapters.interceptors import ToolCallInterceptor\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\nclass LoggingInterceptor(ToolCallInterceptor):\n async def intercept(\n self,\n request: MCPToolCallRequest,\n handler: Callable,\n ) -> MCPToolCallResult:\n print(f\"Calling tool: {request.name}\")\n result = await handler(request)\n print(f\"Tool result: {result}\")\n return result\n\ntools = await load_mcp_tools(\n session,\n tool_interceptors=[LoggingInterceptor()]\n)\n```\n\n资料来源：[README.md:1-100]()\n\n## 架构总结\n\n```mermaid\ngraph TD\n subgraph \"MCP 服务器层\"\n A[MCP Tools]\n B[MCP Resources]\n C[MCP Prompts]\n end\n \n subgraph \"转换适配层\"\n D[load_mcp_tools]\n E[load_mcp_resources]\n F[load_mcp_prompt]\n end\n \n subgraph \"拦截器层\"\n G[ToolCallInterceptor]\n H[MCPToolCallRequest]\n I[MCPToolCallResult]\n end\n \n subgraph \"LangChain/LangGraph 层\"\n J[StructuredTool]\n K[BaseTool]\n L[ToolNode]\n end\n \n A --> D\n D --> G\n G --> H\n H --> I\n I --> J\n J --> K\n J --> L\n```\n\n工具转换机制作为 MCP 与 LangChain 之间的桥梁，通过标准化的转换接口和灵活的拦截器模式，实现了两种协议生态的无缝集成。\n\n---\n\n\n\n## 传输协议类型\n\n### 相关页面\n\n相关主题：[MultiServerMCPClient 客户端](#page-multiserver-client)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [examples/servers/streamable-http-stateless/server.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/examples/servers/streamable-http-stateless/server.py)\n- [README.md](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/README.md)\n \n\n# 传输协议类型\n\n## 概述\n\n`langchain-mcp-adapters` 库支持多种 MCP (Model Context Protocol) 传输协议，用于在不同场景下连接 MCP 服务器与 LangChain 应用。每种传输协议都有其特定的适用环境和配置方式，库通过统一的抽象接口隐藏了底层差异，使得开发者可以灵活选择最适合的传输方式。\n\n传输协议在架构中扮演着客户端与服务器之间通信桥梁的角色，负责建立连接、传输请求和响应。库支持 stdio、HTTP、SSE (Server-Sent Events)、Streamable HTTP 和 WebSocket 五种传输类型。\n\n资料来源：[langchain_mcp_adapters/sessions.py:1-50]()\n\n## 传输协议架构\n\n```mermaid\ngraph TD\n A[MultiServerMCPClient] --> B[Connection 抽象层]\n B --> C[StdioConnection]\n B --> D[McpHttpClientFactory]\n B --> E[SSEConnection]\n B --> F[StreamableHttpConnection]\n B --> G[WebsocketConnection]\n C --> H[stdio transport]\n D --> I[http transport]\n E --> J[sse transport]\n F --> K[streamable-http transport]\n G --> L[websocket transport]\n```\n\n## 支持的传输协议类型\n\n### 1. stdio 传输\n\n**适用场景**：本地进程通信，适用于同一机器上的 MCP 服务器。\n\nstdio 传输通过标准输入/输出流进行进程间通信，是最简单的连接方式。当 MCP 服务器作为子进程运行时，使用此传输协议。\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n }\n }\n)\n```\n\n**配置参数**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `command` | `str` | 是 | 要执行的命令 |\n| `args` | `list[str]` | 是 | 命令行参数列表 |\n| `env` | `dict[str, str]` | 否 | 环境变量 |\n| `cwd` | `str` | 否 | 工作目录 |\n| `encoding` | `str` | 否 | 字符编码 |\n\n资料来源：[README.md:85-95]()\n\n### 2. HTTP 传输\n\n**适用场景**：远程服务器通信，支持跨网络访问 MCP 服务。\n\nHTTP 传输基于传统的请求/响应模式，适用于可以发起 HTTP 请求的环境。客户端通过 RESTful API 与 MCP 服务器通信。\n\n```python\nclient = MultiServerMCPClient(\n {\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\n```\n\n**配置参数**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `url` | `str` | 是 | MCP 服务器的 HTTP 端点 URL |\n| `headers` | `dict[str, str]` | 否 | HTTP 请求头 |\n\n资料来源：[langchain_mcp_adapters/client.py:60-75]()\n\n### 3. SSE 传输\n\n**适用场景**：需要服务器推送更新的场景，支持长连接。\n\nSSE (Server-Sent Events) 传输允许服务器主动向客户端推送事件，实现单向实时通信。\n\n```python\nfrom langchain_mcp_adapters.sessions import SSEConnection\n\nconnection = SSEConnection(\n url=\"http://localhost:8000/sse\",\n headers={\"Authorization\": \"Bearer token\"}\n)\n```\n\n**配置参数**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `url` | `str` | 是 | SSE 端点 URL |\n| `headers` | `dict[str, Any]` | 否 | 请求头 |\n| `timeout` | `float` | 否 | 超时时间，默认 5.0 秒 |\n\n资料来源：[langchain_mcp_adapters/sessions.py:180-200]()\n\n### 4. Streamable HTTP 传输\n\n**适用场景**：现代 MCP 应用，需要支持流式响应和会话管理。\n\nStreamable HTTP 是 MCP 规范推荐的传输方式，支持流式响应和会话状态管理。它结合了 HTTP 的请求/响应模式和流式传输的能力。\n\n**启动服务器示例**：\n\n```bash\ncd examples/servers/streamable-http-stateless/\nuv run mcp-simple-streamablehttp-stateless --port 3000\n```\n\n**客户端使用方式**：\n\n```python\nfrom mcp import ClientSession\nfrom mcp.client.streamable_http import streamablehttp_client\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\nasync with streamablehttp_client(\"http://localhost:3000/mcp\") as (read, write, _):\n async with ClientSession(read, write) as session:\n await session.initialize()\n tools = await load_mcp_tools(session)\n```\n\n资料来源：[examples/servers/streamable-http-stateless/server.py:1-30]()\n\n**服务器端实现示例**：\n\n```python\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"StreamableHTTP\")\n\n@mcp.tool()\ndef add(a: int, b: int) -> int:\n \"\"\"Add two numbers\"\"\"\n return a + b\n\nif __name__ == \"__main__\":\n mcp.run(transport=\"http\")\n```\n\n**配置参数**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `url` | `str` | 是 | Streamable HTTP 端点 URL |\n| `headers` | `dict[str, Any]` | 否 | 请求头 |\n| `timeout` | `float` | 否 | 超时时间 |\n\n> 注意：SSE 和 HTTP 传输支持运行时 headers，这些 headers 会随每个 HTTP 请求一起发送到 MCP 服务器。\n\n资料来源：[README.md:45-60]()\n\n### 5. WebSocket 传输\n\n**适用场景**：需要双向实时通信的低延迟应用。\n\nWebSocket 传输提供全双工通信通道，适用于需要频繁双向交互的场景。\n\n**配置参数**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `url` | `str` | 是 | WebSocket 服务器 URL |\n| `headers` | `dict[str, Any]` | 否 | 连接头 |\n\n资料来源：[langchain_mcp_adapters/sessions.py:220-240]()\n\n## 连接类型映射表\n\n| 传输协议 | Connection 类 | 内部传输类型 | 支持 Headers |\n|---------|--------------|-------------|-------------|\n| stdio | `StdioConnection` | `stdio` | ❌ |\n| http | `McpHttpClientFactory` | `http` | ✅ |\n| sse | `SSEConnection` | `sse` | ✅ |\n| streamable-http | `StreamableHttpConnection` | `http` | ✅ |\n| websocket | `WebsocketConnection` | `websocket` | ✅ |\n\n资料来源：[langchain_mcp_adapters/sessions.py:50-150]()\n\n## 多服务器传输配置\n\n`MultiServerMCPClient` 支持同时连接多个使用不同传输协议的 MCP 服务器：\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n },\n \"realtime\": {\n \"url\": \"ws://localhost:9000/mcp\",\n \"transport\": \"websocket\",\n }\n }\n)\ntools = await client.get_tools()\n```\n\n资料来源：[README.md:95-115]()\n\n## 传输协议选择指南\n\n```mermaid\ngraph TD\n A[选择传输协议] --> B{通信场景}\n B --> C{本地进程}\n C -->|是| D[stdio]\n C -->|否| E{需要远程访问}\n E -->|是| F{需要流式响应}\n F -->|是| G[streamable-http]\n F -->|否| H{需要实时推送}\n H -->|是| I[SSE]\n H -->|否| J{需要双向通信}\n J -->|是| K[WebSocket]\n J -->|否| L[HTTP]\n```\n\n**选择建议**：\n\n- **本地开发测试**：使用 `stdio`，配置简单，无需启动独立服务器\n- **生产环境部署**：使用 `streamable-http`，符合 MCP 规范推荐\n- **需要实时更新**：使用 `SSE` 或 `WebSocket`\n- **跨网络访问**：使用 `HTTP` 或 `streamable-http`\n\n## 运行时 Headers 配置\n\n对于支持 headers 的传输协议（HTTP、SSE、streamable-http），可以在配置中指定自定义请求头：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"secure_api\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n \"headers\": {\n \"Authorization\": \"Bearer custom-value\",\n \"X-Custom-Header\": \"custom-value\"\n },\n }\n }\n)\n```\n\n> 仅 `sse` 和 `http` 传输支持运行时 headers。这些 headers 会随每个 HTTP 请求传递到 MCP 服务器。\n\n资料来源：[README.md:35-50]()\n\n## 会话管理\n\n### 默认会话行为\n\n默认情况下，每次工具调用都会启动一个新的 `ClientSession`。这简化了使用方式，但在高频调用场景下可能影响性能。\n\n```python\ntools = await client.get_tools()\nresponse = await agent.ainvoke({\"messages\": \"what's (3 + 5) x 12?\"})\n```\n\n资料来源：[README.md:110-120]()\n\n### 显式会话管理\n\n对于需要显式控制会话生命周期的场景，可以使用上下文管理器：\n\n```python\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\nclient = MultiServerMCPClient({...})\nasync with client.session(\"math\") as session:\n tools = await load_mcp_tools(session)\n # 在此上下文中复用同一会话\n```\n\n```python\nasync with client.session(server_name) as session:\n resources = await load_mcp_resources(session, uris=uris)\n```\n\n资料来源：[README.md:120-130]()\n\n## 工具名称前缀\n\n当多个服务器具有相同名称的工具时，可以启用工具名称前缀来避免冲突：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n },\n tool_name_prefix=True # 启用前缀\n)\ntools = await client.get_tools()\n# 工具名称将变为 \"math_add\", \"weather_search\" 等\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `tool_name_prefix` | `bool` | `False` | 是否在工具名称前添加服务器名称前缀 |\n\n资料来源：[langchain_mcp_adapters/client.py:45-55]()\n\n## 环境变量扩展\n\n在 stdio 传输中，支持环境变量的展开功能：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"server\": {\n \"command\": \"python\",\n \"args\": [\"${SCRIPT_PATH}\"], # 将被展开\n \"transport\": \"stdio\",\n \"env\": {\n \"API_KEY\": \"${API_KEY}\" # 引用环境变量\n }\n }\n }\n)\n```\n\n> 只有值（而非键）会被展开；`${command}` 和 `${args}` 保持不变。如果未指定 `env`，则会继承当前环境变量的一个子集。\n\n资料来源：[langchain_mcp_adapters/sessions.py:100-130]()\n\n## 错误处理\n\n不同传输协议的错误处理遵循统一的模式：\n\n```python\ntry:\n async with client.session(\"server_name\") as session:\n tools = await load_mcp_tools(session)\nexcept ConnectionError:\n # 处理连接错误\n pass\nexcept ValueError as e:\n # 处理配置错误\n pass\n```\n\n工具调用错误会被包装为 `ToolException`：\n\n```python\nfrom langchain_core.tools import ToolException\n\ntry:\n result = await tool.ainvoke({\"arg\": \"value\"})\nexcept ToolException as e:\n # 处理工具执行错误\n pass\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:80-120]()\n\n---\n\n\n\n## 工具调用拦截器\n\n### 相关页面\n\n相关主题：[回调机制](#page-callbacks), [工具转换机制](#page-tools-conversion)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n \n\n# 工具调用拦截器\n\n## 概述\n\n工具调用拦截器（Tool Call Interceptor）是 langchain-mcp-adapters 框架中用于拦截和控制 MCP 工具调用生命周期的核心机制。它采用**洋葱模式（Onion Pattern）**构建可组合的处理器链，允许开发者在工具调用的请求和响应阶段注入自定义逻辑。\n\n拦截器的主要作用包括：\n\n- 在工具执行前后添加日志记录和监控\n- 修改工具调用的参数或请求头\n- 验证或转换工具返回结果\n- 实现重试逻辑和错误处理\n- 支持 LangGraph Command 的特殊返回类型处理\n\n资料来源：[langchain_mcp_adapters/interceptors.py:1-10]()\n\n## 架构设计\n\n### 洋葱模式处理器链\n\n拦截器通过洋葱模式组织，形成多层嵌套的处理器链。当工具调用时，请求从外到内逐层传递，执行完成后结果再从内到外逐层返回。\n\n```mermaid\ngraph TD\n subgraph 拦截器链\n A[\"拦截器 1 (最外层)\"] --> B[\"拦截器 2\"]\n B --> C[\"拦截器 N\"]\n C --> D[\"实际工具执行器\"]\n end\n \n E[\"MCPToolCallRequest\"] --> A\n D --> F[\"MCPToolCallResult\"]\n \n style A fill:#e1f5fe\n style D fill:#c8e6c9\n style F fill:#fff3e0\n```\n\n### 核心类型体系\n\n| 类型 | 说明 | 资料来源 |\n|------|------|----------|\n| `MCPToolCallRequest` | 工具调用请求的数据类，包含名称、参数、服务器名、请求头等信息 | [interceptors.py:38-56]() |\n| `MCPToolCallResult` | 工具调用结果的类型别名，支持 `CallToolResult`、`ToolMessage` 或 `Command` | [interceptors.py:28-33]() |\n| `ToolCallInterceptor` | 拦截器接口协议，定义异步调用方法 | [interceptors.py:70-75]() |\n| `_MCPToolCallRequestOverrides` | 可覆盖的请求字段类型定义 | [interceptors.py:35-37]() |\n\n## MCPToolCallRequest 数据结构\n\n`MCPToolCallRequest` 是拦截器接收到的工具调用请求对象，采用 dataclass 模式定义：\n\n```python\n@dataclass\nclass MCPToolCallRequest:\n \"\"\"工具执行请求的请求对象\"\"\"\n name: str # 工具名称\n args: dict[str, Any] # 工具参数\n server_name: str # 服务器名称\n headers: dict[str, Any] | None # HTTP 请求头\n runtime: object | None # LangGraph 运行时对象\n```\n\n### 请求覆盖机制\n\n通过 `override()` 方法可以创建修改后的请求副本：\n\n```python\ndef override(\n self, **overrides: Unpack[_MCPToolCallRequestOverrides]\n) -> MCPToolCallRequest:\n \"\"\"创建带有指定覆盖字段的新请求实例\"\"\"\n```\n\n支持覆盖的字段：\n\n| 字段名 | 类型 | 说明 |\n|--------|------|------|\n| `name` | `str` | 工具名称 |\n| `args` | `dict[str, Any]` | 工具参数 |\n| `headers` | `dict[str, Any] \\| None` | HTTP 请求头 |\n\n资料来源：[interceptors.py:56-66]()\n\n## ToolCallInterceptor 接口\n\n拦截器必须实现 `ToolCallInterceptor` 协议：\n\n```python\n@runtime_checkable\nclass ToolCallInterceptor(Protocol):\n \"\"\"拦截器接口协议\"\"\"\n \n async def __call__(\n self,\n request: MCPToolCallRequest,\n handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n ) -> MCPToolCallResult:\n \"\"\"拦截并处理工具调用\"\"\"\n ...\n```\n\n### 接口参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `request` | `MCPToolCallRequest` | 工具调用请求对象 |\n| `handler` | `Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]]` | 下一个处理器（调用链中的下一个拦截器或实际执行器） |\n\n### 返回值\n\n返回类型为 `MCPToolCallResult`，支持以下三种格式：\n\n| 类型 | 说明 | 使用场景 |\n|------|------|----------|\n| `CallToolResult` | MCP 协议标准结果 | 标准工具调用返回 |\n| `ToolMessage` | LangChain 消息格式 | LangChain 集成 |\n| `Command` | LangGraph 命令 | LangGraph 工作流控制 |\n\n资料来源：[interceptors.py:28-33]()\n\n## 拦截器链构建\n\n拦截器链通过 `_build_interceptor_chain()` 函数构建，采用反向迭代方式将拦截器层层包装：\n\n```python\ndef _build_interceptor_chain(\n base_handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n tool_interceptors: list[ToolCallInterceptor] | None,\n) -> Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]]:\n \"\"\"构建带有拦截器的洋葱模式处理器链\"\"\"\n \n handler = base_handler\n \n if tool_interceptors:\n for interceptor in reversed(tool_interceptors):\n current_handler = handler\n async def wrapped(request, next_handler=current_handler):\n return await interceptor(request, next_handler)\n handler = wrapped\n \n return handler\n```\n\n### 构建流程说明\n\n1. **基础处理器** (`base_handler`)：最内层的实际工具执行函数\n2. **反向迭代**：从列表最后一个拦截器开始向前包装\n3. **闭包捕获**：每个拦截器通过闭包持有对下一个处理器的引用\n4. **返回组合处理器**：最终返回最外层的处理器\n\n资料来源：[langchain_mcp_adapters/tools.py:75-95]()\n\n## 拦截器在工具加载中的应用\n\n### load_mcp_tools 函数集成\n\n`load_mcp_tools()` 函数接受 `tool_interceptors` 参数，将拦截器链注入到工具调用流程中：\n\n```python\nasync def load_mcp_tools(\n session: ClientSession | None,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None, # 拦截器列表\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> list[BaseTool]:\n```\n\n### 工具调用执行流程\n\n```mermaid\nsequenceDiagram\n participant 调用者\n participant 工具 as LangChain 工具\n participant 拦截器链 as 拦截器链\n participant 执行器 as 实际执行器\n participant MCP as MCP Session\n\n 调用者->>工具: 调用工具函数\n 工具->>拦截器链: MCPToolCallRequest\n 拦截器链->>执行器: 传递请求\n 执行器->>MCP: session.call_tool()\n MCP-->>执行器: CallToolResult\n 执行器-->>拦截器链: MCPToolCallResult\n 拦截器链-->>工具: MCPToolCallResult\n 工具-->>调用者: (content, artifact)\n```\n\n### 拦截器链的执行环境\n\n在工具的 `call_tool` 内部函数中，拦截器链被创建和应用：\n\n```python\nasync def call_tool(\n runtime: Annotated[object | None, InjectedToolArg()] = None,\n **arguments: dict[str, Any],\n) -> tuple[ConvertedToolResult, MCPToolArtifact | None]:\n # ... 参数验证和回调处理 ...\n\n # 创建最内层处理器 - 实际执行 MCP 工具调用\n async def execute_tool(request: MCPToolCallRequest) -> MCPToolCallResult:\n return await session.call_tool(\n tool_name,\n tool_args,\n progress_callback=mcp_callbacks.progress_callback,\n )\n\n # 构建并执行拦截器链\n handler = _build_interceptor_chain(execute_tool, tool_interceptors)\n request = MCPToolCallRequest(\n name=tool.name,\n args=arguments,\n server_name=server_name or \"unknown\",\n headers=None,\n runtime=runtime,\n )\n call_tool_result = await handler(request)\n\n return _convert_call_tool_result(call_tool_result)\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:98-130]()\n\n## 使用示例\n\n### 基本拦截器实现\n\n```python\nfrom langchain_mcp_adapters.interceptors import (\n MCPToolCallRequest,\n MCPToolCallResult,\n ToolCallInterceptor,\n)\n\nclass LoggingInterceptor:\n \"\"\"日志记录拦截器\"\"\"\n \n async def __call__(\n self,\n request: MCPToolCallRequest,\n handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n ) -> MCPToolCallResult:\n print(f\"调用工具: {request.name}, 参数: {request.args}\")\n result = await handler(request)\n print(f\"工具 {request.name} 执行完成\")\n return result\n\nclass ValidationInterceptor:\n \"\"\"参数验证拦截器\"\"\"\n \n async def __call__(\n self,\n request: MCPToolCallRequest,\n handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n ) -> MCPToolCallResult:\n # 修改请求参数\n if request.name == \"search\" and \"query\" in request.args:\n modified_request = request.override(\n args={**request.args, \"query\": request.args[\"query\"].strip()}\n )\n return await handler(modified_request)\n return await handler(request)\n```\n\n### 多拦截器组合使用\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n }\n)\n\n# 按照配置顺序，最前面的拦截器成为最外层\ninterceptors = [\n LoggingInterceptor(), # 最外层 - 首先执行\n ValidationInterceptor(), # 次外层 - 第二执行\n]\n\ntools = await client.get_tools(tool_interceptors=interceptors)\n```\n\n### 拦截器在 LangGraph 中的使用\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.graph import StateGraph, MessagesState\nfrom langgraph.prebuilt import ToolNode\n\nclient = MultiServerMCPClient({...})\ntools = await client.get_tools(\n tool_interceptors=[LoggingInterceptor()],\n server_name=\"math\"\n)\n\n# 拦截器可以返回 Command 对象控制 LangGraph 流程\nclass ConditionalInterceptor:\n async def __call__(\n self,\n request: MCPToolCallRequest,\n handler: Callable,\n ) -> MCPToolCallResult:\n result = await handler(request)\n # 根据结果决定是否路由到其他节点\n return result\n```\n\n## MultiServerMCPClient 中的拦截器支持\n\n`MultiServerMCPClient` 类在初始化时接受全局拦截器配置：\n\n```python\nclass MultiServerMCPClient:\n def __init__(\n self,\n connections: dict[str, dict[str, Any]] | None = None,\n *,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None, # 全局拦截器\n tool_name_prefix: bool = False,\n ) -> None:\n self.tool_interceptors = tool_interceptors or []\n```\n\n### 配置参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `connections` | `dict[str, dict[str, Any]]` | `None` | 服务器连接配置映射 |\n| `callbacks` | `Callbacks \\| None` | `None` | 回调处理器 |\n| `tool_interceptors` | `list[ToolCallInterceptor]` | `[]` | 全局拦截器列表 |\n| `tool_name_prefix` | `bool` | `False` | 是否为工具名添加服务器前缀 |\n\n资料来源：[langchain_mcp_adapters/client.py:50-60]()\n\n## 最佳实践\n\n### 1. 拦截器顺序\n\n拦截器的执行顺序与其在列表中的顺序一致：\n\n- **列表首位** → **最外层** → **最先收到请求，最后收到响应**\n- **列表末位** → **最内层** → **最后收到请求，最先收到响应**\n\n### 2. 错误处理\n\n建议在最外层拦截器中实现统一的错误处理：\n\n```python\nclass ErrorHandlingInterceptor:\n async def __call__(\n self,\n request: MCPToolCallRequest,\n handler: Callable,\n ) -> MCPToolCallResult:\n try:\n return await handler(request)\n except Exception as e:\n # 统一错误处理和日志记录\n return CallToolResult(\n content=[TextContent(text=f\"Error: {str(e)}\")],\n isError=True,\n )\n```\n\n### 3. 请求修改\n\n使用 `override()` 方法进行不可变请求修改：\n\n```python\n# 正确：创建新实例\nmodified = request.override(args={\"query\": \"new value\"})\n\n# 错误：直接修改（不应该这样做）\nrequest.args[\"query\"] = \"new value\"\n```\n\n### 4. 性能考量\n\n- 避免在拦截器中执行耗时的同步操作\n- 使用异步处理保持非阻塞执行\n- 对于高频调用，考虑拦截器的性能开销\n\n---\n\n\n\n## 回调机制\n\n### 相关页面\n\n相关主题：[工具调用拦截器](#page-interceptors), [MultiServerMCPClient 客户端](#page-multiserver-client)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n \n\n# 回调机制\n\n## 概述\n\n回调机制是 langchain-mcp-adapters 中用于处理 MCP 工具调用生命周期事件的核心组件。该机制允许开发者在工具执行的不同阶段插入自定义逻辑，实现进度监控、事件通知、错误处理等高级功能。\n\n回调系统在 MCP 客户端与 LangChain 工具之间建立了桥梁，使得 MCP 服务器发出的通知（notifications）能够被 LangChain 端正确处理和响应。\n\n## 核心组件\n\n### 组件架构\n\n```mermaid\ngraph TD\n A[MCP 服务器] -->|通知/进度| B[ClientSession]\n B --> C[Callbacks]\n C --> D[CallbackContext]\n D --> E[工具执行]\n E --> F[_MCPCallbacks]\n F --> G[进度回调]\n \n H[开发者代码] -->|自定义回调| C\n```\n\n### CallbackContext\n\n`CallbackContext` 是回调上下文的载体，用于在回调处理过程中传递工具调用的关键信息。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `server_name` | `str` | 工具所属的 MCP 服务器名称 |\n| `tool_name` | `str` | 被调用的工具名称 |\n\n资料来源：[langchain_mcp_adapters/tools.py:1-1]()\n\n### Callbacks\n\n`Callbacks` 类是回调机制的主要入口点，封装了所有与 MCP 服务器通信的回调处理逻辑。\n\n```python\nclass Callbacks:\n \"\"\"用于处理 MCP 通知和事件的回调接口\"\"\"\n```\n\n开发者通过实例化 `Callbacks` 并传递给 `MultiServerMCPClient` 或 `load_mcp_tools` 来启用自定义回调处理。\n\n资料来源：[langchain_mcp_adapters/client.py:1-1]()\n\n### _MCPCallbacks\n\n`_MCPCallbacks` 是内部默认回调实现类，用于将 LangChain 格式的回调转换为 MCP SDK 所需的格式。\n\n```python\nclass _MCPCallbacks:\n \"\"\"内部回调实现，桥接 LangChain 和 MCP SDK\"\"\"\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:1-1]()\n\n## 工作流程\n\n### 回调初始化流程\n\n```mermaid\nsequenceDiagram\n participant 用户 as 用户代码\n participant 客户端 as MultiServerMCPClient\n participant 回调 as Callbacks\n participant 上下文 as CallbackContext\n participant 工具 as load_mcp_tools\n\n 用户->>客户端: 传入 Callbacks 实例\n 客户端->>工具: 传递 callbacks 参数\n 工具->>回调: to_mcp_format(context)\n 回调->>上下文: 创建 CallbackContext\n Note over 上下文: 包含 server_name, tool_name\n```\n\n### 工具调用中的回调处理\n\n```mermaid\ngraph LR\n A[工具调用请求] --> B[call_tool 函数]\n B --> C{已有 Callbacks?}\n C -->|是| D[to_mcp_format]\n C -->|否| E[_MCPCallbacks]\n D --> F[CallbackContext]\n E --> F\n F --> G[progress_callback]\n G --> H[MCP Session.call_tool]\n```\n\n在 `call_tool` 函数中，回调按以下方式使用：\n\n```python\nmcp_callbacks = (\n callbacks.to_mcp_format(\n context=CallbackContext(server_name=server_name, tool_name=tool.name)\n )\n if callbacks is not None\n else _MCPCallbacks()\n)\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:145-156]()\n\n## API 参考\n\n### load_mcp_tools 参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `session` | `ClientSession` | 否 | MCP 客户端会话 |\n| `connection` | `Connection` | 否 | 连接配置 |\n| `callbacks` | `Callbacks` | 否 | 回调处理器 |\n| `tool_interceptors` | `list[ToolCallInterceptor]` | 否 | 工具调用拦截器 |\n| `server_name` | `str` | 否 | 服务器名称 |\n| `tool_name_prefix` | `bool` | 否 | 工具名称前缀 |\n\n资料来源：[langchain_mcp_adapters/tools.py:199-230]()\n\n### convert_mcp_tool_to_langchain_tool 参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `session` | `ClientSession` | 否 | MCP 客户端会话 |\n| `tool` | `MCPTool` | 是 | 待转换的 MCP 工具 |\n| `callbacks` | `Callbacks` | 否 | 回调处理器 |\n| `tool_interceptors` | `list[ToolCallInterceptor]` | 否 | 拦截器列表 |\n| `server_name` | `str` | 否 | 服务器名称 |\n| `tool_name_prefix` | `bool` | 否 | 是否添加前缀 |\n\n资料来源：[langchain_mcp_adapters/tools.py:232-290]()\n\n## 使用示例\n\n### 基本用法\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain_mcp_adapters.callbacks import Callbacks\n\n# 定义自定义回调处理\nclass MyCallbacks(Callbacks):\n def __init__(self):\n super().__init__()\n \n def to_mcp_format(self, context):\n # 实现自定义转换逻辑\n return super().to_mcp_format(context)\n\n# 使用回调客户端\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n },\n callbacks=MyCallbacks()\n)\n\ntools = await client.get_tools()\n```\n\n### 与拦截器配合使用\n\n回调机制可以与拦截器（interceptors）配合使用，实现更复杂的工具调用控制：\n\n```mermaid\ngraph TD\n A[请求] --> B[拦截器1]\n B --> C[拦截器2]\n C --> D[拦截器N]\n D --> E[execute_tool]\n E --> D\n D --> C\n C --> B\n B --> F[响应]\n```\n\n```python\nfrom langchain_mcp_adapters.interceptors import ToolCallInterceptor\n\nasync def my_interceptor(\n request: MCPToolCallRequest,\n handler: Callable\n) -> MCPToolCallResult:\n # 前置处理\n print(f\"调用工具: {request.name}\")\n result = await handler(request)\n # 后置处理\n print(f\"工具返回: {result}\")\n return result\n\ntools = await load_mcp_tools(\n session,\n callbacks=custom_callbacks,\n tool_interceptors=[my_interceptor]\n)\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:61-95]()\n\n## 高级功能\n\n### 进度回调\n\n回调系统支持 MCP 协议的进度通知机制。当 MCP 服务器通过 `progress_callback` 发送进度更新时，系统会将其传递给 LangChain 端处理。\n\n```python\ncall_tool_result = await session.call_tool(\n tool_name,\n tool_args,\n progress_callback=mcp_callbacks.progress_callback,\n)\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:157-165]()\n\n### 工具调用请求拦截\n\n通过 `MCPToolCallRequest` 和 `MCPToolCallResult` 类型，回调系统支持对工具调用请求和响应进行完整的拦截处理：\n\n```python\n@dataclass\nclass MCPToolCallRequest:\n \"\"\"工具执行请求，传递给拦截器\"\"\"\n name: str\n args: dict[str, Any]\n server_name: str\n headers: dict[str, Any] | None\n runtime: Any # LangGraph 运行时上下文\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py:1-1]()\n\n## 最佳实践\n\n1. **始终传递 server_name**：确保回调上下文能够正确识别工具所属的服务器\n2. **合理使用拦截器链**：多个拦截器按洋葱模型执行，避免过度嵌套\n3. **处理异常情况**：在回调中实现适当的错误处理逻辑\n4. **性能考虑**：避免在回调中执行耗时操作，以免阻塞工具调用\n\n## 与 LangGraph 集成\n\n当项目中安装了 `langgraph` 时，回调机制支持额外的 `runtime` 参数，用于传递 LangGraph 的执行上下文：\n\n```python\nasync def call_tool(\n runtime: Annotated[object | None, InjectedToolArg()] = None,\n **arguments: dict[str, Any],\n) -> tuple[ConvertedToolResult, MCPToolArtifact | None]:\n request = MCPToolCallRequest(\n name=tool.name,\n args=arguments,\n server_name=server_name or \"unknown\",\n headers=None,\n runtime=runtime, # LangGraph 运行时上下文\n )\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:126-142]()\n\n## 相关模块\n\n| 模块 | 功能 |\n|------|------|\n| `langchain_mcp_adapters.callbacks` | 回调接口定义和实现 |\n| `langchain_mcp_adapters.interceptors` | 工具调用拦截器接口 |\n| `langchain_mcp_adapters.tools` | 工具加载和转换，含回调集成 |\n| `langchain_mcp_adapters.client` | 多服务器客户端，回调配置入口 |\n\n---\n\n\n\n## 提示词与资源转换\n\n### 相关页面\n\n相关主题：[数据流与转换机制](#page-data-flow), [核心模块结构](#page-core-modules)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/prompts.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/prompts.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n \n\n# 提示词与资源转换\n\n## 概述\n\n`langchain-mcp-adapters` 库提供了两大核心转换模块，用于将 MCP（Model Context Protocol）的提示词（Prompts）和资源（Resources）转换为 LangChain 兼容的格式。这些模块使得 MCP 服务器可以作为 LangChain 和 LangGraph 应用的外部工具和数据来源。\n\n| 模块 | 源文件 | 功能描述 |\n|------|--------|----------|\n| 提示词转换 | `prompts.py` | 将 MCP 提示词消息转换为 LangChain 消息对象 |\n| 资源转换 | `resources.py` | 将 MCP 资源内容转换为 LangChain Blob 对象 |\n\n资料来源：[langchain_mcp_adapters/prompts.py:1-10]()，[langchain_mcp_adapters/resources.py:1-15]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph MCP服务器端\n MCP[MCP Server]\n Prompts[MCP Prompts]\n Resources[MCP Resources]\n end\n\n subgraph langchain_mcp_adapters\n prompts_module[prompts.py]\n resources_module[resources.py]\n end\n\n subgraph LangChain端\n LCMessages[LangChain Messages
HumanMessage/AIMessage]\n LCBlobs[LangChain Blobs]\n end\n\n Prompts -->|get_prompt| prompts_module\n Resources -->|read_resource| resources_module\n prompts_module --> LCMessages\n resources_module --> LCBlobs\n\n style MCP服务器端 fill:#e1f5fe\n style LangChain端 fill:#f3e5f5\n style langchain_mcp_adapters fill:#fff3e0\n```\n\n## 提示词转换模块\n\n### 模块定位\n\n`prompts.py` 模块负责将 MCP 服务器提供的提示词（Prompts）转换为 LangChain 的消息对象。提示词是 MCP 协议中用于定义预定义对话模板的机制，允许服务器提供结构化的提示内容。\n\n资料来源：[langchain_mcp_adapters/prompts.py:1-10]()\n\n### 核心函数\n\n#### `convert_mcp_prompt_message_to_langchain_message()`\n\n该函数将单个 MCP 提示词消息转换为 LangChain 消息对象。\n\n**函数签名：**\n\n```python\ndef convert_mcp_prompt_message_to_langchain_message(\n message: PromptMessage,\n) -> HumanMessage | AIMessage:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `message` | `PromptMessage` | MCP 提示词消息对象 |\n\n**支持的转换规则：**\n\n| MCP 消息类型 | LangChain 消息类型 |\n|-------------|-------------------|\n| `role: user, content.type: text` | `HumanMessage` |\n| `role: assistant, content.type: text` | `AIMessage` |\n\n**异常处理：**\n\n| 错误条件 | 抛出异常 |\n|---------|----------|\n| `content.type` 非 `text` | `ValueError` |\n| `role` 非 `user` 或 `assistant` | `ValueError` |\n\n资料来源：[langchain_mcp_adapters/prompts.py:12-35]()\n\n#### `load_mcp_prompt()`\n\n异步函数，用于从 MCP 会话加载提示词并转换为 LangChain 消息列表。\n\n**函数签名：**\n\n```python\nasync def load_mcp_prompt(\n session: ClientSession,\n name: str,\n *,\n arguments: dict[str, Any] | None = None,\n) -> list[HumanMessage | AIMessage]:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `session` | `ClientSession` | 是 | MCP 客户端会话 |\n| `name` | `str` | 是 | 提示词名称 |\n| `arguments` | `dict[str, Any] \\| None` | 否 | 传递给提示词的参数 |\n\n**返回值：**\n\n返回转换后的 LangChain 消息列表，消息类型为 `HumanMessage` 或 `AIMessage`。\n\n**工作流程：**\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Session as MCP ClientSession\n participant Adapter as prompts.py\n participant LC as LangChain Messages\n\n Client->>Adapter: load_mcp_prompt(session, name, arguments)\n Adapter->>Session: get_prompt(name, arguments)\n Session-->>Adapter: PromptMessage[]\n Loop 遍历每条消息\n Adapter->>Adapter: convert_mcp_prompt_message_to_langchain_message()\n end\n Adapter-->>Client: list[HumanMessage | AIMessage]\n```\n\n资料来源：[langchain_mcp_adapters/prompts.py:38-60]()\n\n## 资源转换模块\n\n### 模块定位\n\n`resources.py` 模块负责将 MCP 协议中的资源（Resources）转换为 LangChain 的 Blob 对象。资源可以是文本内容或二进制数据（如图片、文件等），Blob 对象提供了统一的数据包装接口。\n\n资料来源：[langchain_mcp_adapters/resources.py:1-18]()\n\n### 核心函数\n\n#### `convert_mcp_resource_to_langchain_blob()`\n\n将单个 MCP 资源内容转换为 LangChain Blob 对象。\n\n**函数签名：**\n\n```python\ndef convert_mcp_resource_to_langchain_blob(\n resource_uri: str, contents: ResourceContents\n) -> Blob:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `resource_uri` | `str` | 资源的 URI 标识符 |\n| `contents` | `ResourceContents` | 资源内容（TextResourceContents 或 BlobResourceContents） |\n\n**支持的资源类型：**\n\n| MCP 资源类型 | LangChain 处理方式 |\n|-------------|-------------------|\n| `TextResourceContents` | 直接使用文本数据 |\n| `BlobResourceContents` | Base64 解码后使用 |\n\n**Blob 元数据：**\n\n转换后的 Blob 对象包含以下元数据：\n\n| 元数据键 | 值 |\n|---------|-----|\n| `uri` | 资源的 URI |\n\n**异常处理：**\n\n| 错误条件 | 抛出异常 |\n|---------|----------|\n| 不支持的资源内容类型 | `TypeError` |\n\n资料来源：[langchain_mcp_adapters/resources.py:20-42]()\n\n#### `get_mcp_resource()`\n\n异步函数，用于获取单个 MCP 资源并转换为 LangChain Blob 对象列表。\n\n**函数签名：**\n\n```python\nasync def get_mcp_resource(session: ClientSession, uri: str) -> list[Blob]:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `session` | `ClientSession` | MCP 客户端会话 |\n| `uri` | `str` | 要获取的资源 URI |\n\n**返回值：**\n\n返回 LangChain Blob 对象列表。如果资源内容为空，则返回空列表。\n\n资料来源：[langchain_mcp_adapters/resources.py:44-61]()\n\n#### `load_mcp_resources()`\n\n异步函数，用于批量加载 MCP 资源。\n\n**函数签名：**\n\n```python\nasync def load_mcp_resources(\n session: ClientSession,\n *,\n uris: str | list[str] | None = None,\n) -> list[Blob]:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `session` | `ClientSession` | 是 | MCP 客户端会话 |\n| `uris` | `str \\| list[str] \\| None` | 否 | 要加载的 URI 列表，`None` 表示加载所有资源 |\n\n**加载行为：**\n\n| `uris` 值 | 行为 |\n|----------|------|\n| `None` | 调用 `session.list_resources()` 获取所有资源 URI |\n| `str` | 仅加载指定的单个 URI |\n| `list[str]` | 加载指定的 URI 列表 |\n\n> [!note]\n> 动态资源（Dynamic Resources）在 `uris` 为 `None` 时**不会**被加载，因为它们需要参数，而 MCP SDK 的 `session.list_resources()` 方法无法处理这类资源。\n\n资料来源：[langchain_mcp_adapters/resources.py:64-90]()\n\n## 数据模型\n\n### MCP 类型引用\n\n```mermaid\nclassDiagram\n class PromptMessage {\n +str role\n +Content content\n }\n\n class ResourceContents {\n <>\n }\n\n class TextResourceContents {\n +str uri\n +str text\n +str mimeType\n }\n\n class BlobResourceContents {\n +str uri\n +str blob\n +str mimeType\n }\n\n class TextContent {\n +str type\n +str text\n }\n\n class BlobResourceContents {\n +str uri\n +str blob\n +str mimeType\n }\n\n ResourceContents <|-- TextResourceContents\n ResourceContents <|-- BlobResourceContents\n\n note for ResourceContents \"MCP types from mcp.types\"\n```\n\n### LangChain 类型对应\n\n| MCP 类型 | LangChain 类型 | 说明 |\n|---------|---------------|------|\n| `PromptMessage` | `HumanMessage \\| AIMessage` | 提示词消息 |\n| `TextResourceContents` | `Blob` (文本数据) | 文本资源 |\n| `BlobResourceContents` | `Blob` (二进制数据) | 二进制资源 |\n\n## 客户端集成\n\n`MultiServerMCPClient` 提供了对提示词和资源转换的统一访问接口。\n\n资料来源：[langchain_mcp_adapters/client.py:1-60]()\n\n### 核心方法\n\n| 方法 | 功能 |\n|------|------|\n| `get_tools()` | 获取所有 MCP 工具并转换为 LangChain 工具 |\n| `get_prompts()` | 获取所有 MCP 提示词 |\n| `get_resources()` | 获取所有 MCP 资源 |\n| `session(server_name)` | 获取指定服务器的会话上下文管理器 |\n\n### 使用示例\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"./math_server.py\"],\n \"transport\": \"stdio\",\n },\n }\n)\n\n# 获取工具\ntools = await client.get_tools()\n\n# 获取资源\nresources = await client.get_resources()\n```\n\n## 会话管理\n\n提示词和资源的加载依赖于 `ClientSession` 对象，该对象通过 `sessions.py` 模块创建和管理。\n\n资料来源：[langchain_mcp_adapters/sessions.py:1-100]()\n\n### 支持的传输类型\n\n| 传输类型 | 说明 | 支持状态 |\n|---------|------|----------|\n| `stdio` | 标准输入输出传输 | ✅ 完全支持 |\n| `sse` | Server-Sent Events | ✅ 完全支持 |\n| `http` | Streamable HTTP | ✅ 完全支持 |\n| `websocket` | WebSocket | ✅ 完全支持 |\n\n## 类型转换流程\n\n### 提示词转换流程\n\n```mermaid\nflowchart LR\n subgraph MCP层\n MCP_Prompt[MCP get_prompt]\n PM[PromptMessage]\n end\n\n subgraph 转换层\n convert[convert_mcp_prompt_message_to_langchain_message]\n end\n\n subgraph LangChain层\n HM[HumanMessage]\n AM[AIMessage]\n end\n\n MCP_Prompt --> PM\n PM --> convert\n convert -->|role=user| HM\n convert -->|role=assistant| AM\n```\n\n### 资源转换流程\n\n```mermaid\nflowchart LR\n subgraph MCP层\n MCP_Resource[MCP read_resource]\n TRC[TextResourceContents]\n BRC[BlobResourceContents]\n end\n\n subgraph 转换层\n convert[convert_mcp_resource_to_langchain_blob]\n decode[base64.b64decode]\n end\n\n subgraph LangChain层\n Blob[Blob]\n end\n\n MCP_Resource --> TRC\n MCP_Resource --> BRC\n TRC --> convert\n BRC --> decode\n decode --> convert\n convert --> Blob\n```\n\n## 错误处理\n\n### 提示词转换错误\n\n| 错误类型 | 条件 | 处理方式 |\n|---------|------|----------|\n| `ValueError` | 不支持的 `content.type` | 抛出异常 |\n| `ValueError` | 不支持的 `role` 值 | 抛出异常 |\n\n### 资源转换错误\n\n| 错误类型 | 条件 | 处理方式 |\n|---------|------|----------|\n| `TypeError` | 不支持的资源内容类型 | 抛出异常 |\n| `RuntimeError` | 获取资源时发生错误 | 由调用方处理 |\n\n## 与工具转换的关系\n\n提示词和资源转换与 `tools.py` 中的工具转换模块共同构成了 MCP 到 LangChain 的完整适配体系。\n\n```mermaid\ngraph TD\n subgraph MCP协议\n MCP_Tools[Tools]\n MCP_Prompts[Prompts]\n MCP_Resources[Resources]\n end\n\n subgraph langchain_mcp_adapters\n tools_module[tools.py]\n prompts_module[prompts.py]\n resources_module[resources.py]\n end\n\n subgraph LangChain\n LC_Tools[StructuredTool]\n LC_Messages[Messages]\n LC_Blobs[Blobs]\n end\n\n MCP_Tools --> tools_module\n MCP_Prompts --> prompts_module\n MCP_Resources --> resources_module\n\n tools_module --> LC_Tools\n prompts_module --> LC_Messages\n resources_module --> LC_Blobs\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:1-100]()\n\n## 最佳实践\n\n### 1. 资源批量加载\n\n当需要加载多个资源时，使用 `load_mcp_resources()` 的 `uris` 参数指定资源列表，避免多次调用 `get_mcp_resource()`：\n\n```python\n# 推荐方式\nresources = await load_mcp_resources(session, uris=[\"uri1\", \"uri2\", \"uri3\"])\n\n# 不推荐方式（多次网络往返）\nres1 = await get_mcp_resource(session, \"uri1\")\nres2 = await get_mcp_resource(session, \"uri2\")\nres3 = await get_mcp_resource(session, \"uri3\")\n```\n\n### 2. 提示词参数传递\n\n使用 `arguments` 参数为提示词提供上下文信息：\n\n```python\nmessages = await load_mcp_prompt(\n session,\n name=\"code_review\",\n arguments={\"repo\": \"langchain-mcp-adapters\", \"pr\": 123}\n)\n```\n\n### 3. 错误处理\n\n实现适当的错误处理以应对资源不可用或格式不支持的情况：\n\n```python\ntry:\n resources = await load_mcp_resources(session, uris=uri_list)\nexcept TypeError as e:\n logger.error(f\"Unsupported resource type: {e}\")\n```\n\n## 总结\n\n`langchain-mcp-adapters` 的提示词和资源转换模块为 LangChain 应用提供了访问 MCP 服务器结构和数据的能力：\n\n| 组件 | 文件 | 核心功能 |\n|------|------|----------|\n| 提示词转换 | `prompts.py` | 将 MCP Prompts 转换为 `HumanMessage`/`AIMessage` |\n| 资源转换 | `resources.py` | 将 MCP Resources 转换为 LangChain `Blob` 对象 |\n\n这两个模块与工具转换模块（`tools.py`）一起，构成了 MCP 到 LangChain 的完整适配层，使得开发者可以在 LangChain 和 LangGraph 应用中无缝使用 MCP 服务器提供的各种功能。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：langchain-ai/langchain-mcp-adapters\n\n摘要：发现 17 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Prompts and Resources auto-discovery。\n\n## 1. 安装坑 · 来源证据：Prompts and Resources auto-discovery\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Prompts and Resources auto-discovery\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bf1812b74caa4e989767a9307a8ffc16 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/62 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：`MultiServerMCPClient.get_tools()` silently returns no tools when any single server fails to connect\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`MultiServerMCPClient.get_tools()` silently returns no tools when any single server fails to connect\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a5093182914b4df0b7ad2cd560bacdf2 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/492 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 运行坑 · 来源证据：Fix TypeError in resources.py and make __aexit__ an async coroutine in client.py\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Fix TypeError in resources.py and make __aexit__ an async coroutine in client.py\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac102050dd4841d6954559a3413e0b92 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/496 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：langchain-mcp-adapters==0.2.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：langchain-mcp-adapters==0.2.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0c6ca0722ab046379d28ecf30f8d2bcf | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：langchain-mcp-adapters==0.1.10\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：langchain-mcp-adapters==0.1.10\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b18dbf32ccd41e38b272a458f4040f5 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 来源证据：langchain-mcp-adapters==0.1.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：langchain-mcp-adapters==0.1.14\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6727e0d698e54fc38d7c60e262978ac2 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.14 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：langchain-mcp-adapters==0.1.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：langchain-mcp-adapters==0.1.12\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e71a46a9e0374d139555a78f229b0469 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.12 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：langchain-mcp-adapters==0.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：langchain-mcp-adapters==0.2.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_59483f9a6a16414c9087b1751fba8efc | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 来源证据：langchain-mcp-adapters==0.2.0a1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：langchain-mcp-adapters==0.2.0a1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e7fcda1716948898295279af95f8f96 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0a1 | 来源类型 github_release 暴露的待验证使用条件。\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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Feature Request: Support passing server-defined params extensions (e.g. LangGraph `context`) through tools/call\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Support passing server-defined params extensions (e.g. LangGraph `context`) through tools/call\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8c46dab4b6dd4a6e92c96af49ea47647 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/502 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | release_recency=unknown\n\n\n",
"markdown_key": "langchain-mcp-adapters",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:929158279",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/langchain-ai/langchain-mcp-adapters"
},
{
"evidence_id": "art_19ca1ab453cc40588fce6af16d6ad367",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/langchain-ai/langchain-mcp-adapters#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "langchain-mcp-adapters 说明书",
"toc": [
"https://github.com/langchain-ai/langchain-mcp-adapters 项目说明书",
"目录",
"项目介绍",
"项目概述",
"核心定位",
"核心功能特性",
"系统架构",
"模块详解",
"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": "174c48e85c59d227f1b57c1c5dedd00c341e8086",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"README.md",
"uv.lock",
"examples/servers/streamable-http-stateless/pyproject.toml",
"examples/servers/streamable-http-stateless/README.md",
"examples/servers/streamable-http-stateless/mcp_simple_streamablehttp_stateless/server.py",
"examples/servers/streamable-http-stateless/mcp_simple_streamablehttp_stateless/__init__.py",
"examples/servers/streamable-http-stateless/mcp_simple_streamablehttp_stateless/__main__.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": "# langchain-mcp-adapters - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 langchain-mcp-adapters 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 它能做什么\n\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86\n\n## 怎么开始\n\n- `pip install langchain-mcp-adapters` 证据：`README.md` Claim：`clm_0003` supported 0.86, `clm_0004` supported 0.86\n- `pip install langchain-mcp-adapters langgraph \"langchain[openai]\"` 证据：`README.md` Claim：`clm_0004` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、本地环境或项目文件、环境变量 / API Key\n\n### 现在可以相信\n\n- **适合人群线索：想在安装前理解开源项目价值和边界的用户**（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, `clm_0004` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`README.md`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\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_0005` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0006` 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- 文件总数：42\n- 重要文件覆盖：20/42\n- 证据索引条目：18\n- 角色 / Skill 条目：3\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请基于 langchain-mcp-adapters 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 langchain-mcp-adapters 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 langchain-mcp-adapters 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 3 个角色 / Skill / 项目文档条目。\n\n- **LangChain MCP Adapters**（project_doc）：This library provides a lightweight wrapper that makes Anthropic Model Context Protocol MCP https://modelcontextprotocol.io/introduction tools compatible with LangChain https://github.com/langchain-ai/langchain and LangGraph https://github.com/langchain-ai/langgraph . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n- **MCP Simple StreamableHttp Stateless Server Example**（project_doc）：MCP Simple StreamableHttp Stateless Server Example 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/servers/streamable-http-stateless/README.md`\n- **Security Policy**（project_doc）：For any other security concerns, please contact us at security@langchain.dev . 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`SECURITY.md`\n\n## 证据索引\n\n- 共索引 18 条证据。\n\n- **LangChain MCP Adapters**（documentation）：This library provides a lightweight wrapper that makes Anthropic Model Context Protocol MCP https://modelcontextprotocol.io/introduction tools compatible with LangChain https://github.com/langchain-ai/langchain and LangGraph https://github.com/langchain-ai/langgraph . 证据：`README.md`\n- **MCP Simple StreamableHttp Stateless Server Example**（documentation）：MCP Simple StreamableHttp Stateless Server Example 证据：`examples/servers/streamable-http-stateless/README.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- **Security Policy**（documentation）：For any other security concerns, please contact us at security@langchain.dev . 证据：`SECURITY.md`\n- **Please see the documentation for all configuration options:**（source_file）：Please see the documentation for all configuration options: https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates and https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file 证据：`.github/dependabot.yml`\n- **Pyenv**（source_file）：Byte-compiled / optimized / DLL files pycache / .py cod $py.class 证据：`.gitignore`\n- **Default target executed when no arguments are given to make.**（source_file）：Default target executed when no arguments are given to make. all: help 证据：`Makefile`\n- **Init**（source_file）：\"\"\"LangChain MCP Adapters - Connect MCP servers with LangChain applications. 证据：`langchain_mcp_adapters/__init__.py`\n- **Type aliases to avoid direct MCP type dependencies**（source_file）：from dataclasses import dataclass from typing import Protocol, runtime checkable 证据：`langchain_mcp_adapters/callbacks.py`\n- **Make sure to update to the full absolute path to your**（source_file）：\"\"\"Client for connecting to multiple MCP servers and loading LC tools/resources. 证据：`langchain_mcp_adapters/client.py`\n- **langgraph installed**（source_file）：\"\"\"Interceptor interfaces and types for MCP client tool call lifecycle management. 证据：`langchain_mcp_adapters/interceptors.py`\n- **Prompts**（source_file）：\"\"\"Prompts adapter for converting MCP prompts to LangChain messages https://docs.langchain.com/oss/python/langchain/messages . 证据：`langchain_mcp_adapters/prompts.py`\n- **Resources**（source_file）：\"\"\"Resources adapter for converting MCP resources to LangChain Blob objects langchain core.documents.base.Blob . 证据：`langchain_mcp_adapters/resources.py`\n- **Create and store the connection**（source_file）：\"\"\"Session management for different MCP transport types. 证据：`langchain_mcp_adapters/sessions.py`\n- **langgraph installed**（source_file）：\"\"\"Tools adapter for converting MCP tools to LangChain tools. 证据：`langchain_mcp_adapters/tools.py`\n- **-ra: Report all extra test outcomes passed, skipped, failed, etc.**（source_file）：build-system requires = \"pdm-backend\" build-backend = \"pdm.backend\" 证据：`pyproject.toml`\n- **Wait for server to be running**（source_file）：import multiprocessing import socket import time from collections.abc import Generator 证据：`tests/conftest.py`\n- **Helper for matching auto-generated LangChain content block IDs**（source_file）：import contextlib import multiprocessing import socket import time from collections.abc import Generator 证据：`tests/utils.py`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `examples/servers/streamable-http-stateless/README.md`, `LICENSE`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `examples/servers/streamable-http-stateless/README.md`, `LICENSE`\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- **项目介绍**：importance `high`\n - source_paths: README.md, langchain_mcp_adapters/__init__.py\n- **安装与配置**：importance `high`\n - source_paths: pyproject.toml, README.md\n- **核心模块结构**：importance `high`\n - source_paths: langchain_mcp_adapters/tools.py, langchain_mcp_adapters/client.py, langchain_mcp_adapters/sessions.py, langchain_mcp_adapters/callbacks.py, langchain_mcp_adapters/interceptors.py\n- **数据流与转换机制**：importance `medium`\n - source_paths: langchain_mcp_adapters/tools.py, langchain_mcp_adapters/resources.py, langchain_mcp_adapters/prompts.py\n- **MultiServerMCPClient 客户端**：importance `high`\n - source_paths: langchain_mcp_adapters/client.py, README.md\n- **工具转换机制**：importance `high`\n - source_paths: langchain_mcp_adapters/tools.py, README.md\n- **传输协议类型**：importance `high`\n - source_paths: langchain_mcp_adapters/sessions.py, examples/servers/streamable-http-stateless/server.py, README.md\n- **工具调用拦截器**：importance `medium`\n - source_paths: langchain_mcp_adapters/interceptors.py\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `174c48e85c59d227f1b57c1c5dedd00c341e8086`\n- inspected_files: `pyproject.toml`, `README.md`, `uv.lock`, `examples/servers/streamable-http-stateless/pyproject.toml`, `examples/servers/streamable-http-stateless/README.md`, `examples/servers/streamable-http-stateless/mcp_simple_streamablehttp_stateless/server.py`, `examples/servers/streamable-http-stateless/mcp_simple_streamablehttp_stateless/__init__.py`, `examples/servers/streamable-http-stateless/mcp_simple_streamablehttp_stateless/__main__.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: 来源证据：Prompts and Resources auto-discovery\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Prompts and Resources auto-discovery\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_bf1812b74caa4e989767a9307a8ffc16 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/62 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：`MultiServerMCPClient.get_tools()` silently returns no tools when any single server fails to connect\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`MultiServerMCPClient.get_tools()` silently returns no tools when any single server fails to connect\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_a5093182914b4df0b7ad2cd560bacdf2 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/492 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Fix TypeError in resources.py and make __aexit__ an async coroutine in client.py\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Fix TypeError in resources.py and make __aexit__ an async coroutine in client.py\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_ac102050dd4841d6954559a3413e0b92 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/496 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：langchain-mcp-adapters==0.2.2\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：langchain-mcp-adapters==0.2.2\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_0c6ca0722ab046379d28ecf30f8d2bcf | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.2 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：langchain-mcp-adapters==0.1.10\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：langchain-mcp-adapters==0.1.10\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_8b18dbf32ccd41e38b272a458f4040f5 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 来源证据：langchain-mcp-adapters==0.1.14\n\n- Trigger: GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：langchain-mcp-adapters==0.1.14\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_6727e0d698e54fc38d7c60e262978ac2 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.14 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 能力判断依赖假设\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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：langchain-mcp-adapters==0.1.12\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：langchain-mcp-adapters==0.1.12\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_e71a46a9e0374d139555a78f229b0469 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.12 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：langchain-mcp-adapters==0.2.0\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：langchain-mcp-adapters==0.2.0\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_59483f9a6a16414c9087b1751fba8efc | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0 | 来源类型 github_release 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：langchain-mcp-adapters==0.2.0a1\n\n- Trigger: GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：langchain-mcp-adapters==0.2.0a1\n- Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_4e7fcda1716948898295279af95f8f96 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0a1 | 来源类型 github_release 暴露的待验证使用条件。\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项目：langchain-ai/langchain-mcp-adapters\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 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：Prompts and Resources auto-discovery（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：`MultiServerMCPClient.get_tools()` silently returns no tools when any single server fails to connect（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Fix TypeError in resources.py and make __aexit__ an async coroutine in client.py（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：langchain-mcp-adapters==0.2.2（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 来源证据：langchain-mcp-adapters==0.1.10（medium）：可能增加新用户试用和生产接入成本。 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/langchain-ai/langchain-mcp-adapters 项目说明书\n\n生成时间：2026-05-11 16:35:38 UTC\n\n## 目录\n\n- [项目介绍](#page-project-introduction)\n- [安装与配置](#page-installation)\n- [核心模块结构](#page-core-modules)\n- [数据流与转换机制](#page-data-flow)\n- [MultiServerMCPClient 客户端](#page-multiserver-client)\n- [工具转换机制](#page-tools-conversion)\n- [传输协议类型](#page-transport-types)\n- [工具调用拦截器](#page-interceptors)\n- [回调机制](#page-callbacks)\n- [提示词与资源转换](#page-prompts-resources)\n\n\n\n## 项目介绍\n\n### 相关页面\n\n相关主题：[安装与配置](#page-installation), [核心模块结构](#page-core-modules)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/README.md)\n- [langchain_mcp_adapters/__init__.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/__init__.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n \n\n# 项目介绍\n\n## 项目概述\n\nlangchain-mcp-adapters 是一个轻量级适配器库，用于将 [Anthropic Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) 工具转换为 [LangChain](https://github.com/langchain-ai/langchain) 和 [LangGraph](https://github.com/langchain-ai/langgraph) 兼容的格式。该项目使开发者能够在 LangChain/LangGraph 应用中无缝使用 MCP 协议定义的各种工具。\n\n资料来源：[langchain_mcp_adapters/__init__.py:1-9]()\n\n## 核心定位\n\n该项目充当 MCP 协议与 LangChain 生态之间的桥梁，解决两个协议栈之间的互操作性问题。\n\n```mermaid\ngraph LR\n A[MCP 服务器] --> B[langchain-mcp-adapters]\n B --> C[LangChain/LangGraph]\n C --> D[AI Agent]\n \n style B fill:#e1f5fe\n```\n\n资料来源：[README.md:1-1]()\n\n## 核心功能特性\n\n| 功能模块 | 说明 |\n|---------|------|\n| **工具适配** | 将 MCP 工具转换为 LangChain 工具，可与 LangGraph agents 配合使用 |\n| **多服务器客户端** | 支持连接多个 MCP 服务器并从中加载工具 |\n| **资源转换** | 将 MCP 资源转换为 LangChain Blob 对象 |\n| **拦截器机制** | 提供工具调用生命周期管理能力 |\n| **多传输协议支持** | 支持 stdio、HTTP、SSE、WebSocket 等多种传输方式 |\n\n资料来源：[README.md:10-16]()\n\n## 系统架构\n\n### 核心组件\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n A[MultiServerMCPClient]\n end\n \n subgraph \"会话管理层\"\n B[sessions.py]\n C[Connection 抽象]\n D[StdioConnection]\n E[StreamableHttpConnection]\n F[SSEConnection]\n G[WebsocketConnection]\n end\n \n subgraph \"适配器层\"\n H[tools.py]\n I[resources.py]\n J[prompts.py]\n end\n \n subgraph \"拦截器层\"\n K[interceptors.py]\n L[ToolCallInterceptor]\n end\n \n A --> B\n B --> C\n C --> D\n C --> E\n C --> F\n C --> G\n \n A --> H\n A --> I\n A --> J\n \n H --> K\n```\n\n### 工具转换流程\n\n```mermaid\nsequenceDiagram\n participant Client as MultiServerMCPClient\n participant Session as MCP ClientSession\n participant Adapter as tools.py\n participant Interceptor as ToolCallInterceptor\n participant LC as LangChain Tool\n \n Client->>Session: list_tools()\n Session-->>Client: List[MCPTool]\n Client->>Adapter: convert_to_langchain_tool(MCPTool)\n Adapter->>Interceptor: 包装拦截器链\n Adapter->>LC: StructuredTool\n Client-->>Client: 返回 LangChain 工具列表\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:1-50]()\n\n## 模块详解\n\n### tools.py - 工具适配模块\n\n该模块负责将 MCP 工具转换为 LangChain 工具，核心功能包括：\n\n- **内容块转换**：支持 TextContent、ImageContent、FileContent 等多种内容类型转换\n- **工具调用执行**：通过拦截器链执行工具调用并处理结果\n- **错误处理**：将 MCP 错误转换为 ToolException\n- **结构化内容包装**：通过 MCPToolArtifact 包装结构化返回内容\n\n| 转换类型 | MCP 输入 | LangChain 输出 |\n|---------|---------|---------------|\n| 文本内容 | TextContent | {\"type\": \"text\", \"text\": ...} |\n| 图片内容 | ImageContent | {\"type\": \"image\", \"base64\": ..., \"mime_type\": ...} |\n| 图片链接 | ResourceLink(image/*) | {\"type\": \"image\", \"url\": ...} |\n| 文件链接 | ResourceLink(other) | {\"type\": \"file\", \"url\": ...} |\n| 内嵌资源 | EmbeddedResource | 同上映射规则 |\n\n资料来源：[langchain_mcp_adapters/tools.py:100-150]()\n\n### resources.py - 资源适配模块\n\n该模块处理 MCP 资源的转换，将 MCP 资源内容转换为 LangChain Blob 对象：\n\n- **文本资源**：直接提取 text 内容\n- **二进制资源**：Base64 解码后封装为 Blob\n- **动态资源**：支持按 URI 列表加载特定资源\n\n资料来源：[langchain_mcp_adapters/resources.py:1-60]()\n\n### interceptors.py - 拦截器模块\n\n提供工具调用生命周期管理能力，采用洋葱模式构建拦截器链：\n\n```mermaid\ngraph TD\n A[请求入口] --> B[拦截器 1]\n B --> C[拦截器 2]\n C --> D[拦截器 N]\n D --> E[实际工具执行]\n E --> D\n D --> C\n C --> B\n B --> A[响应返回]\n \n style E fill:#c8e6c9\n```\n\n| 组件 | 说明 |\n|-----|------|\n| MCPToolCallRequest | 工具调用请求数据结构 |\n| MCPToolCallResult | 工具调用结果，支持 Command 格式 |\n| ToolCallInterceptor | 拦截器接口定义 |\n\n资料来源：[langchain_mcp_adapters/interceptors.py:1-50]()\n\n### client.py - 多服务器客户端\n\nMultiServerMCPClient 是核心入口类，提供以下能力：\n\n- 同时管理多个 MCP 服务器连接\n- 支持按服务器名获取工具列表\n- 支持显式会话管理和上下文管理器会话\n- 集成回调和拦截器配置\n\n| 配置项 | 类型 | 说明 |\n|-------|------|------|\n| connections | dict | 服务器连接配置映射 |\n| callbacks | Callbacks | 事件回调处理器 |\n| tool_interceptors | list | 工具调用拦截器列表 |\n| tool_name_prefix | bool | 是否为工具名添加服务器前缀 |\n\n资料来源：[langchain_mcp_adapters/client.py:1-100]()\n\n### sessions.py - 会话管理层\n\n负责创建和管理 MCP ClientSession，支持多种传输协议：\n\n| 传输类型 | 适用场景 | 配置方式 |\n|---------|---------|---------|\n| StdioConnection | 本地进程通信 | command + args |\n| StreamableHttpConnection | 无状态 HTTP 服务器 | url |\n| SSEConnection | Server-Sent Events | url + headers |\n| WebsocketConnection | WebSocket 通信 | url + headers |\n\n资料来源：[langchain_mcp_adapters/sessions.py:1-100]()\n\n## 快速开始\n\n### 安装依赖\n\n```bash\npip install langchain-mcp-adapters\n```\n\n资料来源：[README.md:22-24]()\n\n### 创建 MCP 服务器\n\n```python\n# math_server.py\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"Math\")\n\n@mcp.tool()\ndef add(a: int, b: int) -> int:\n \"\"\"Add two numbers\"\"\"\n return a + b\n\n@mcp.tool()\ndef multiply(a: int, b: int) -> int:\n \"\"\"Multiply two numbers\"\"\"\n return a * b\n```\n\n资料来源：[README.md:30-50]()\n\n### 使用 MultiServerMCPClient\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"./math_server.py\"],\n \"transport\": \"stdio\",\n }\n }\n)\ntools = await client.get_tools()\n```\n\n资料来源：[README.md:70-85]()\n\n### 集成 LangGraph Agent\n\n```python\nfrom langgraph.graph import StateGraph, MessagesState, START\nfrom langgraph.prebuilt import ToolNode, tools_condition\n\nbuilder = StateGraph(MessagesState)\nbuilder.add_node(call_model)\nbuilder.add_node(ToolNode(tools))\nbuilder.add_edge(START, \"call_model\")\nbuilder.add_conditional_edges(\n \"call_model\",\n tools_condition,\n)\n```\n\n资料来源：[README.md:110-125]()\n\n## 数据类型定义\n\n### MCPToolArtifact\n\n```python\nclass MCPToolArtifact(TypedDict):\n \"\"\"MCP 工具调用返回的工件\"\"\"\n structured_content: dict[str, Any]\n```\n\n用于包装 MCP 工具的结构化返回内容，支持未来扩展。\n\n资料来源：[langchain_mcp_adapters/tools.py:75-90]()\n\n### ConvertedToolResult\n\n根据 langgraph 安装状态，返回类型有所不同：\n\n| LangGraph 状态 | 返回类型 |\n|---------------|---------|\n| 已安装 | `list[ToolMessageContentBlock] \\| ToolMessage \\| Command` |\n| 未安装 | `list[ToolMessageContentBlock] \\| ToolMessage` |\n\n资料来源：[langchain_mcp_adapters/tools.py:60-70]()\n\n## 生态关联\n\n该项目与以下项目形成完整的 MCP 工具生态：\n\n```mermaid\ngraph TD\n A[langchain-mcp-adapters] --> B[LangChain]\n A --> C[LangGraph]\n A --> D[MCP SDK]\n \n E[langchainjs] --> A\n E --> F[JavaScript/TypeScript 版本]\n \n style A fill:#fff9c4\n```\n\n> 注意：该库的 JavaScript/TypeScript 版本也可在 [langchainjs](https://github.com/langchain-ai/langchainjs/tree/main/libs/langchain-mcp-adapters/) 获取。\n\n资料来源：[README.md:20-21]()\n\n## 总结\n\nlangchain-mcp-adapters 作为 MCP 协议与 LangChain 生态之间的关键适配层，提供：\n\n1. **开箱即用的工具转换**：零配置将 MCP 工具转换为 LangChain 工具\n2. **灵活的拦截机制**：支持在工具调用生命周期中注入自定义逻辑\n3. **强大的多服务器支持**：单客户端管理多个 MCP 服务器\n4. **完善的类型安全**：全面使用 Pydantic 和 TypedDict 确保类型安全\n\n该库使开发者能够充分利用 MCP 协议丰富的工具生态，同时享受 LangChain/LangGraph 带来的强大 Agent 开发能力。\n\n---\n\n\n\n## 安装与配置\n\n### 相关页面\n\n相关主题：[项目介绍](#page-project-introduction), [MultiServerMCPClient 客户端](#page-multiserver-client)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [pyproject.toml](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/pyproject.toml)\n- [README.md](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/README.md)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n \n\n# 安装与配置\n\n## 概述\n\n`langchain-mcp-adapters` 是一个轻量级适配器库，用于将 Anthropic 的 Model Context Protocol (MCP) 工具转换为 LangChain 和 LangGraph 兼容的工具格式。该库的主要功能包括：\n\n- 将 MCP 工具转换为 LangChain 工具，使其能够与 LangGraph 代理配合使用\n- 提供客户端实现，支持连接多个 MCP 服务器并加载其工具\n\n资料来源：[README.md:1-12]()\n\n## 环境要求\n\n### 系统要求\n\n| 组件 | 最低版本要求 | 说明 |\n|------|-------------|------|\n| Python | 3.10+ | 推荐使用 Python 3.10 或更高版本 |\n| pip | 最新版本 | 用于安装 Python 包 |\n\n### 核心依赖\n\n| 依赖包 | 版本要求 | 用途 |\n|--------|---------|------|\n| langchain-core | 最新稳定版 | LangChain 核心功能 |\n| mcp | 最新稳定版 | MCP 协议客户端支持 |\n| pydantic | 2.x | 数据验证和模型定义 |\n\n### 可选依赖\n\n| 依赖包 | 用途 |\n|--------|------|\n| langgraph | 用于 LangGraph StateGraph 集成 |\n| langchain[openai] | OpenAI 模型支持 |\n| httpx | HTTP 传输协议支持 |\n\n## 安装方法\n\n### 基础安装\n\n使用 pip 安装 langchain-mcp-adapters 的基本功能：\n\n```bash\npip install langchain-mcp-adapters\n```\n\n资料来源：[README.md:14]()\n\n### 完整安装（包含所有依赖）\n\n为了使用完整功能，包括与 LangGraph 和 OpenAI 的集成：\n\n```bash\npip install langchain-mcp-adapters langgraph \"langchain[openai]\"\n```\n\n资料来源：[README.md:20-21]()\n\n### 设置 API 密钥\n\n安装完成后，需要设置相应的 API 密钥环境变量：\n\n```bash\nexport OPENAI_API_KEY=\n```\n\n资料来源：[README.md:22]()\n\n## 客户端配置\n\n### MultiServerMCPClient 概述\n\n`MultiServerMCPClient` 是连接多个 MCP 服务器的主要接口，允许你从多个服务器同时加载工具。\n\n资料来源：[client.py:1-50]()\n\n### 连接配置参数\n\n#### 支持的传输协议\n\n| 传输类型 | 配置方式 | 说明 |\n|----------|----------|------|\n| `stdio` | 通过 command 和 args 参数 | 适用于本地子进程通信 |\n| `http` | 通过 url 参数 | 适用于远程 HTTP 服务器 |\n| `sse` | 通过 url 参数 | 支持 Server-Sent Events |\n\n资料来源：[sessions.py:1-200]()\n\n#### stdio 传输配置\n\nstdio 传输适用于本地 MCP 服务器进程：\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n }\n)\n```\n\n**配置参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `command` | str | 是 | 要执行的命令（如 `python`、`node`） |\n| `args` | list[str] | 是 | 命令行参数列表 |\n| `transport` | str | 是 | 必须设置为 `\"stdio\"` |\n| `env` | dict | 否 | 环境变量字典，支持变量展开 |\n| `cwd` | str | 否 | 命令执行的工作目录 |\n| `encoding` | str | 否 | 字符编码方式 |\n| `encoding_error_handler` | str | 否 | 编码错误处理策略 |\n\n资料来源：[sessions.py:1-100]()\n\n#### HTTP 传输配置\n\nHTTP 传输适用于远程 MCP 服务器：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n \"headers\": {\n \"Authorization\": \"Bearer custom-value\"\n }\n }\n }\n)\n```\n\n**HTTP 配置参数说明：**\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `url` | str | 是 | MCP 服务器的完整 URL |\n| `transport` | str | 是 | 必须设置为 `\"http\"` 或 `\"sse\"` |\n| `headers` | dict | 否 | HTTP 请求头，仅支持 `http` 和 `sse` 传输 |\n\n资料来源：[client.py:50-100]()\n\n### 工具名称前缀配置\n\n当多个 MCP 服务器存在相同名称的工具时，可以使用 `tool_name_prefix` 参数为工具名称添加服务器前缀：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n },\n tool_name_prefix=True # 启用工具名称前缀\n)\n```\n\n启用后，工具名称将从 `\"search\"` 变为 `\"weather_search\"`。\n\n资料来源：[client.py:40-45]()\n\n## MCP 服务器配置\n\n### 创建 MCP 服务器\n\n使用 FastMCP 框架创建 MCP 服务器：\n\n```python\n# math_server.py\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"Math\")\n\n@mcp.tool()\ndef add(a: int, b: int) -> int:\n \"\"\"Add two numbers\"\"\"\n return a + b\n\n@mcp.tool()\ndef multiply(a: int, b: int) -> int:\n \"\"\"Multiply two numbers\"\"\"\n return a * b\n\nif __name__ == \"__main__\":\n mcp.run(transport=\"stdio\")\n```\n\n资料来源：[README.md:30-55]()\n\n### HTTP 传输服务器\n\n对于 HTTP 传输模式的服务器：\n\n```python\n# weather_server.py\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"Weather\")\n\n@mcp.tool()\nasync def get_weather(location: str) -> str:\n \"\"\"Get weather for location.\"\"\"\n return \"It's always sunny in New York\"\n\nif __name__ == \"__main__\":\n mcp.run(transport=\"http\")\n```\n\n运行服务器：\n\n```bash\npython weather_server.py\n```\n\n资料来源：[README.md:60-75]()\n\n### 无状态 HTTP 流式服务器\n\n对于可扩展的 HTTP 服务，可以使用无状态流式传输：\n\n```bash\ncd examples/servers/streamable-http-stateless/\nuv run mcp-simple-streamablehttp-stateless --port 3000\n```\n\n资料来源：[README.md:2-8]()\n\n## 会话管理配置\n\n### 显式会话管理\n\n虽然 `MultiServerMCPClient` 默认在每次工具调用时自动创建新会话，但也支持显式会话管理：\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\nclient = MultiServerMCPClient({...})\nasync with client.session(\"math\") as session:\n tools = await load_mcp_tools(session)\n```\n\n资料来源：[client.py:60-70]()\n\n### 连接对象配置\n\n`Connection` 对象用于配置与 MCP 服务器的连接细节：\n\n```python\nfrom langchain_mcp_adapters.sessions import create_session\n\nasync with create_session(\n command=\"python\",\n args=[\"math_server.py\"],\n transport=\"stdio\"\n) as session:\n tools = await load_mcp_tools(session)\n```\n\n## 工具加载配置\n\n### load_mcp_tools 函数参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `session` | ClientSession | 否 | MCP 客户端会话，与 connection 二选一 |\n| `connection` | Connection | 否 | 连接配置，用于创建新会话 |\n| `callbacks` | Callbacks | 否 | 通知和事件处理回调 |\n| `tool_interceptors` | list[ToolCallInterceptor] | 否 | 工具调用拦截器列表 |\n| `server_name` | str | 否 | 服务器名称 |\n| `tool_name_prefix` | bool | 否 | 是否为工具名称添加前缀 |\n\n资料来源：[tools.py:100-150]()\n\n## 架构流程图\n\n### 客户端-服务器通信架构\n\n```mermaid\ngraph TD\n A[MultiServerMCPClient] --> B[Connection 配置]\n B --> C[stdio 传输]\n B --> D[HTTP 传输]\n B --> E[SSE 传输]\n \n C --> F[子进程 MCP 服务器]\n D --> G[远程 HTTP 服务器]\n E --> H[SSE 服务器]\n \n F --> I[ClientSession]\n G --> I\n H --> I\n \n I --> J[load_mcp_tools]\n J --> K[LangChain StructuredTool]\n K --> L[LangGraph Agent]\n```\n\n### 工具调用流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户代码\n participant LC as LangChain Agent\n participant MCP as MCP Adapter\n participant Server as MCP Server\n \n User->>LC: 调用工具\n LC->>MCP: call_tool(args)\n MCP->>MCP: 应用拦截器链\n MCP->>Server: session.call_tool()\n Server-->>MCP: CallToolResult\n MCP->>MCP: 转换结果格式\n MCP-->>LC: ToolMessage + Artifact\n LC-->>User: 返回结果\n```\n\n## 环境变量与密钥管理\n\n### 必需的环境变量\n\n| 变量名 | 说明 | 示例 |\n|--------|------|------|\n| `OPENAI_API_KEY` | OpenAI API 密钥 | `sk-xxx...` |\n\n### 传输配置中的环境变量\n\n在 stdio 传输配置中，可以使用环境变量展开语法：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"server\": {\n \"command\": \"python\",\n \"args\": [\"script.py\"],\n \"env\": {\n \"API_KEY\": \"${API_KEY}\", # 从当前环境展开\n \"CUSTOM_VAR\": \"fixed-value\"\n },\n \"transport\": \"stdio\"\n }\n }\n)\n```\n\n> [!warning]\n> 如果环境变量值包含 `${variable}` 语法但无法展开，库会发出警告。\n\n资料来源：[sessions.py:80-95]()\n\n## 完整配置示例\n\n### 多服务器配置\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\n# 初始化客户端，连接多个 MCP 服务器\nclient = MultiServerMCPClient(\n {\n # 本地 stdio 服务器\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/absolute/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n # 远程 HTTP 服务器\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n \"headers\": {\n \"Authorization\": \"Bearer token123\"\n }\n }\n },\n tool_name_prefix=True # 避免工具名冲突\n)\n\n# 获取所有工具\ntools = await client.get_tools()\n```\n\n资料来源：[README.md:85-110]()\n\n### 与 LangGraph 集成配置\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.graph import StateGraph, MessagesState, START\nfrom langgraph.prebuilt import ToolNode, tools_condition\nfrom langchain.chat_models import init_chat_model\n\n# 配置 MCP 客户端\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"./examples/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\n\n# 加载工具\ntools = await client.get_tools()\n\n# 初始化模型\nmodel = init_chat_model(\"openai:gpt-4.1\")\n\n# 定义模型调用节点\ndef call_model(state: MessagesState):\n response = model.bind_tools(tools).invoke(state[\"messages\"])\n return {\"messages\": response}\n\n# 构建状态图\nbuilder = StateGraph(MessagesState)\nbuilder.add_node(call_model)\nbuilder.add_node(ToolNode(tools))\nbuilder.add_edge(START, \"call_model\")\nbuilder.add_conditional_edges(\n \"call_model\",\n tools_condition,\n)\n```\n\n资料来源：[README.md:120-165]()\n\n## 故障排除\n\n### 常见配置错误\n\n| 错误 | 原因 | 解决方案 |\n|------|------|----------|\n| `ValueError: Either session or connection must be provided` | 未提供 session 或 connection 参数 | 确保传递有效的 session 或 connection 对象 |\n| 工具名冲突 | 多服务器有同名工具 | 设置 `tool_name_prefix=True` |\n| 连接超时 | HTTP 服务器未启动或地址错误 | 确认服务器运行状态和 URL |\n| 环境变量未展开 | 变量语法错误 | 检查 `${variable}` 格式是否正确 |\n\n### 调试建议\n\n1. **验证 MCP 服务器**：确保服务器可以独立运行\n2. **检查传输类型**：stdio 需要命令和参数，HTTP 需要 URL\n3. **查看工具列表**：使用 `client.get_tools()` 确认工具加载成功\n4. **环境变量检查**：确保必需的 API 密钥已设置\n\n---\n\n\n\n## 核心模块结构\n\n### 相关页面\n\n相关主题：[工具转换机制](#page-tools-conversion), [MultiServerMCPClient 客户端](#page-multiserver-client), [数据流与转换机制](#page-data-flow)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n- [langchain_mcp_adapters/callbacks.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/callbacks.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [langchain_mcp_adapters/prompts.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/prompts.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n \n\n# 核心模块结构\n\n## 概述\n\nlangchain-mcp-adapters 是一个轻量级适配器库，用于将 Anthropic 的 Model Context Protocol (MCP) 服务器与 LangChain/LangGraph 应用集成。该库的核心设计围绕**工具适配**、**会话管理**、**资源转换**和**拦截器机制**四大支柱展开，通过模块化架构实现 MCP 工具向 LangChain 工具的透明转换。\n\n项目采用异步优先的设计理念，充分利用 Python 的 `asyncio` 能力处理 MCP 通信，同时通过 LangGraph 条件判断实现智能的工具路由。资料来源：[README.md]()\n\n## 架构总览\n\n```mermaid\ngraph TD\n A[MultiServerMCPClient] --> B[Connection 管理]\n A --> C[Session 管理]\n B --> D[StdioConnection]\n B --> E[StreamableHttpConnection]\n B --> F[SSEConnection]\n B --> G[WebsocketConnection]\n C --> H[ClientSession]\n H --> I[load_mcp_tools]\n H --> J[load_mcp_resources]\n H --> K[load_mcp_prompt]\n I --> L[StructuredTool]\n J --> M[Blob]\n K --> N[ChatPromptValue]\n L --> O[ToolCallInterceptor]\n O --> P[MCPToolCallRequest]\n P --> Q[MCPToolCallResult]\n```\n\n## 核心模块划分\n\n| 模块 | 文件 | 主要职责 |\n|------|------|----------|\n| 客户端入口 | `client.py` | 多服务器连接管理、工具资源加载 |\n| 会话管理 | `sessions.py` | 不同传输层连接创建 |\n| 工具适配 | `tools.py` | MCP工具→LangChain工具转换 |\n| 资源适配 | `resources.py` | MCP资源→LangChain Blob转换 |\n| 提示加载 | `prompts.py` | MCP提示→LangChain提示转换 |\n| 拦截器 | `interceptors.py` | 工具调用拦截与修改 |\n| 回调 | `callbacks.py` | 进度通知与事件处理 |\n\n资料来源：[langchain_mcp_adapters/client.py:1-50]()\n\n## MultiServerMCPClient 客户端模块\n\n### 功能定位\n\n`MultiServerMCPClient` 是库的入口点，负责管理对多个 MCP 服务器的连接。它支持通过配置字典同时连接到多个不同类型的服务器（stdio、HTTP SSE、WebSocket 等），并提供统一的工具、资源和提示加载接口。\n\n资料来源：[langchain_mcp_adapters/client.py:1-80]()\n\n### 连接配置\n\n客户端接受服务器配置字典，键为服务器名称，值为连接参数字典：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"./math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `command` | `str` | 执行命令（stdio传输必需） |\n| `args` | `list[str]` | 命令行参数 |\n| `transport` | `str` | 传输类型：`stdio`、`http`、`sse`、`websocket` |\n| `url` | `str` | 服务器URL（HTTP类传输必需） |\n| `headers` | `dict` | HTTP请求头（仅sse/http传输支持） |\n| `timeout` | `float` | HTTP超时时间 |\n| `env` | `dict` | 环境变量 |\n\n资料来源：[langchain_mcp_adapters/client.py:1-100]()\n\n### 上下文管理器使用方式\n\n版本 0.1.0 后，`MultiServerMCPClient` 不再支持作为异步上下文管理器直接使用：\n\n```python\n# 推荐方式一：直接调用\nclient = MultiServerMCPClient({...})\ntools = await client.get_tools()\n\n# 推荐方式二：显式会话管理\nclient = MultiServerMCPClient({...})\nasync with client.session(\"math\") as session:\n tools = await load_mcp_tools(session)\n```\n\n资料来源：[langchain_mcp_adapters/client.py:80-120]()\n\n## sessions.py 会话管理模块\n\n### 传输层抽象\n\n`sessions.py` 模块定义了多种连接类型，每种类型对应不同的 MCP 传输协议：\n\n```mermaid\ngraph LR\n A[Connection 抽象] --> B[StdioConnection]\n A --> C[StreamableHttpConnection]\n A --> D[SSEConnection]\n A --> E[WebsocketConnection]\n```\n\n资料来源：[langchain_mcp_adapters/sessions.py:1-100]()\n\n### StdioConnection\n\n通过标准输入/输出与本地进程通信，适用于本地 MCP 服务器：\n\n```python\nasync with stdio_client(server_params) as (read, write):\n async with ClientSession(read, write) as session:\n yield session\n```\n\n| 参数 | 说明 |\n|------|------|\n| `command` | 可执行命令路径 |\n| `args` | 命令行参数列表 |\n| `env` | 环境变量（支持`${...}`变量展开） |\n| `cwd` | 工作目录 |\n| `encoding` | 字符编码 |\n\n资料来源：[langchain_mcp_adapters/sessions.py:100-200]()\n\n### StreamableHttpConnection\n\n支持流式 HTTP 传输的连接类型，适用于无状态的 HTTP MCP 服务器：\n\n```python\nasync with streamablehttp_client(url, ...) as (read, write, _):\n async with ClientSession(read, write) as session:\n await session.initialize()\n```\n\n资料来源：[langchain_mcp_adapters/sessions.py:200-300]()\n\n### SSEConnection\n\n服务器发送事件（Server-Sent Events）传输连接，支持实时事件推送：\n\n```python\nasync with sse_client(url, headers=headers) as sessions:\n for session in sessions:\n # 处理每个SSE会话\n```\n\n资料来源：[langchain_mcp_adapters/sessions.py:300-400]()\n\n### WebsocketConnection\n\nWebSocket 传输连接，支持双向通信：\n\n```python\nasync with websocket_client(url) as (read, write):\n async with ClientSession(read, write) as session:\n yield session\n```\n\n资料来源：[langchain_mcp_adapters/sessions.py:400-500]()\n\n## tools.py 工具适配模块\n\n### 核心转换流程\n\n`tools.py` 模块负责将 MCP 工具转换为 LangChain 的 `StructuredTool` 对象，支持工具执行、参数验证和结果转换：\n\n```mermaid\ngraph TD\n A[MCP Tool] --> B[load_mcp_tools]\n B --> C[convert_mcp_tool_to_langchain_tool]\n C --> D[StructuredTool]\n E[工具调用] --> F[call_tool 函数]\n F --> G[拦截器链处理]\n G --> H[MCPToolCallRequest]\n H --> I[session.call_tool]\n I --> J[MCPToolCallResult]\n J --> K[_convert_call_tool_result]\n K --> L[Content + Artifact]\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:1-100]()\n\n### 工具加载函数\n\n#### load_mcp_tools\n\n加载 MCP 服务器上的所有工具：\n\n```python\nasync def load_mcp_tools(\n session: ClientSession | None,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None,\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> list[BaseTool]\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `session` | `ClientSession` | MCP客户端会话 |\n| `connection` | `Connection` | 连接配置（session为空时使用） |\n| `callbacks` | `Callbacks` | 回调处理器 |\n| `tool_interceptors` | `list[ToolCallInterceptor]` | 工具调用拦截器列表 |\n| `server_name` | `str` | 服务器名称 |\n| `tool_name_prefix` | `bool` | 是否将服务器名作为工具名前缀 |\n\n资料来源：[langchain_mcp_adapters/tools.py:200-280]()\n\n#### convert_mcp_tool_to_langchain_tool\n\n转换单个 MCP 工具为 LangChain 工具：\n\n```python\nasync def convert_mcp_tool_to_langchain_tool(\n session: ClientSession | None,\n tool: MCPTool,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None,\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> BaseTool\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:150-200]()\n\n### 内容块转换\n\n`_convert_mcp_content_to_lc_block` 函数将 MCP 内容块转换为 LangChain 内容块格式：\n\n| MCP 内容类型 | LangChain 输出 |\n|-------------|----------------|\n| `TextContent` | `{\"type\": \"text\", \"text\": ...}` |\n| `ImageContent` | `{\"type\": \"image\", \"base64\": ..., \"mime_type\": ...}` |\n| `ResourceLink` (图片) | `{\"type\": \"image\", \"url\": ...}` |\n| `ResourceLink` (其他) | `{\"type\": \"file\", \"url\": ...}` |\n| `EmbeddedResource` (文本) | `{\"type\": \"text\", \"text\": ...}` |\n| `EmbeddedResource` (二进制) | `{\"type\": \"image\"}` 或 `{\"type\": \"file\"}` |\n| `AudioContent` | 抛出 `NotImplementedError` |\n\n资料来源：[langchain_mcp_adapters/tools.py:100-150]()\n\n### 工具调用结果类型\n\n```python\n# 根据 LangGraph 可用性条件定义\nif LANGGRAPH_PRESENT:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage | Command\nelse:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage\n\n# MCP 工具工件类型\nclass MCPToolArtifact(TypedDict):\n structured_content: dict[str, Any]\n```\n\n返回结果为元组 `(content, artifact)`，其中 `artifact` 包含 MCP 服务器返回的结构化内容。\n\n资料来源：[langchain_mcp_adapters/tools.py:50-80]()\n\n## interceptors.py 拦截器模块\n\n### 拦截器模式\n\n拦截器采用洋葱模型（Onion Pattern）包装工具调用处理器，允许在调用前后进行拦截和修改：\n\n```mermaid\ngraph TD\n A[调用者] --> B[拦截器1 包装]\n B --> C[拦截器2 包装]\n C --> D[拦截器N 包装]\n D --> E[execute_tool 实际执行]\n E --> D\n D --> C\n C --> B\n B --> A\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py:1-50]()\n\n### 核心数据结构\n\n#### MCPToolCallRequest\n\n工具调用请求数据结构：\n\n```python\n@dataclass\nclass MCPToolCallRequest:\n name: str # 工具名称\n args: dict[str, Any] # 工具参数\n server_name: str # 服务器名称\n headers: dict[str, Any] | None # HTTP请求头\n runtime: Any # 运行时上下文\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py:50-100]()\n\n#### MCPToolCallResult\n\n工具调用结果类型，根据 LangGraph 可用性条件定义：\n\n```python\nif LANGGRAPH_PRESENT:\n MCPToolCallResult = CallToolResult | ToolMessage | Command\nelse:\n MCPToolCallResult = CallToolResult | ToolMessage\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py:20-40]()\n\n### ToolCallInterceptor 接口\n\n```python\n@runtime_checkable\nclass ToolCallInterceptor(Protocol):\n async def intercept(\n self,\n request: MCPToolCallRequest,\n call_next: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n ) -> MCPToolCallResult:\n ...\n```\n\n拦截器可以：\n- 在调用前修改 `request`（通过 `request.override()` 方法）\n- 跳过实际执行，直接返回结果\n- 修改或增强返回结果\n- 在调用前后执行副作用（如日志记录）\n\n资料来源：[langchain_mcp_adapters/interceptors.py:100-150]()\n\n### 请求覆盖机制\n\n`MCPToolCallRequest` 提供 `override` 方法支持部分字段修改：\n\n```python\nclass _MCPToolCallRequestOverrides(TypedDict, total=False):\n name: NotRequired[str]\n args: NotRequired[dict[str, Any]]\n headers: NotRequired[dict[str, Any] | None]\n\ndef override(self, **overrides: Unpack[_MCPToolCallRequestOverrides]) -> MCPToolCallRequest:\n \"\"\"返回修改后的请求副本\"\"\"\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py:40-50]()\n\n## callbacks.py 回调模块\n\n### 回调接口设计\n\n回调系统用于处理 MCP 服务器的通知和进度事件：\n\n```mermaid\ngraph LR\n A[MCP Server] -->|进度通知| B[Callbacks]\n A -->|日志消息| B\n A -->|资源列表变更| B\n B --> C[工具级别回调]\n```\n\n资料来源：[langchain_mcp_adapters/callbacks.py:1-50]()\n\n### CallbackContext\n\n回调上下文包含服务器信息：\n\n```python\n@dataclass\nclass CallbackContext:\n server_name: str | None = None\n tool_name: str | None = None\n```\n\n### Callbacks 类\n\n核心回调接口定义，支持多种事件类型：\n\n| 方法 | 触发时机 |\n|------|----------|\n| `progress_callback` | 服务器发送进度更新 |\n| `logger` | 服务器发送日志消息 |\n| `list_changed` | 资源/工具列表变更 |\n\n资料来源：[langchain_mcp_adapters/callbacks.py:50-100]()\n\n## resources.py 资源模块\n\n### 资源转换流程\n\n`resources.py` 模块将 MCP 资源转换为 LangChain 的 `Blob` 对象：\n\n```mermaid\ngraph LR\n A[MCP Resource URI] --> B[session.read_resource]\n B --> C[ResourceContents]\n C --> D[convert_mcp_resource_to_langchain_blob]\n D --> E[Blob]\n```\n\n资料来源：[langchain_mcp_adapters/resources.py:1-50]()\n\n### 内容类型支持\n\n| MCP 内容类型 | Blob 处理方式 |\n|-------------|---------------|\n| `TextResourceContents` | 直接使用文本内容 |\n| `BlobResourceContents` | Base64 解码后存储 |\n\n资料来源：[langchain_mcp_adapters/resources.py:50-80]()\n\n### 资源加载函数\n\n#### load_mcp_resources\n\n```python\nasync def load_mcp_resources(\n session: ClientSession,\n *,\n uris: str | list[str] | None = None,\n) -> list[Blob]\n```\n\n| 参数 | 说明 |\n|------|------|\n| `uris=None` | 加载所有资源 |\n| `uris=str` | 加载指定 URI 的资源 |\n| `uris=list[str]` | 批量加载指定 URI 的资源 |\n\n> 注意：动态资源在 `uris=None` 时不会被加载，因为它们需要参数。\n\n资料来源：[langchain_mcp_adapters/resources.py:80-120]()\n\n## prompts.py 提示模块\n\n### 提示加载功能\n\n`prompts.py` 模块负责将 MCP 服务器上的提示模板加载为 LangChain 的聊天提示值对象，支持参数化提示生成。\n\n资料来源：[langchain_mcp_adapters/prompts.py:1-50]()\n\n## 数据流集成图\n\n### 完整工具调用流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户/LangGraph\n participant Client as MultiServerMCPClient\n participant Interceptor as ToolCallInterceptor\n participant Session as ClientSession\n participant Server as MCP Server\n \n User->>Client: get_tools()\n Client->>Session: create_session(connection)\n Session->>Server: list_tools()\n Server-->>Session: List[McpTool]\n Session-->>Client: List[BaseTool]\n Client-->>User: List[StructuredTool]\n \n User->>Client: tool.invoke(args)\n Client->>Interceptor: intercept(request)\n Interceptor->>Interceptor: request.override(...)\n Interceptor->>Session: call_tool(name, args)\n Session->>Server: call_tool()\n Server-->>Session: CallToolResult\n Session-->>Interceptor: MCPToolCallResult\n Interceptor-->>Client: MCPToolCallResult\n Client-->>User: (Content, Artifact)\n```\n\n## 配置与扩展\n\n### 工具名称前缀\n\n当连接多个服务器时，可使用 `tool_name_prefix=True` 避免工具名冲突：\n\n```python\nclient = MultiServerMCPClient(\n {\"math\": {...}, \"weather\": {...}},\n tool_name_prefix=True\n)\n# 工具名变为: math_add, weather_get_weather\n```\n\n### 拦截器链配置\n\n```python\nasync def my_interceptor(\n request: MCPToolCallRequest,\n call_next: Callable,\n) -> MCPToolCallResult:\n # 在调用前记录日志\n logger.info(f\"Calling {request.name}\")\n \n # 可以修改参数\n if request.name == \"add\":\n modified_request = request.override(args={\"a\": 1, \"b\": 2})\n return await call_next(modified_request)\n \n return await call_next(request)\n\nclient = MultiServerMCPClient(\n {...},\n tool_interceptors=[my_interceptor]\n)\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:250-300]()\n\n### HTTP 运行时头\n\n仅 `sse` 和 `http` 传输支持运行时头：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"weather\": {\n \"transport\": \"http\",\n \"url\": \"http://localhost:8000/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer custom-value\"\n }\n }\n }\n)\n```\n\n资料来源：[README.md:1-50]()\n\n## 错误处理\n\n### 工具执行异常\n\n当 MCP 工具返回错误时，`_convert_call_tool_result` 会抛出 `ToolException`：\n\n```python\nif call_tool_result.isError:\n error_parts = []\n for item in tool_content:\n if isinstance(item, dict) and item.get(\"type\") == \"text\":\n error_parts.append(item.get(\"text\", \"\"))\n error_msg = \"\\n\".join(error_parts)\n raise ToolException(error_msg)\n```\n\n### 不支持的内容类型\n\n`AudioContent` 转换尚未支持，会抛出 `NotImplementedError`：\n\n```python\nif isinstance(content, AudioContent):\n raise NotImplementedError(\n f\"AudioContent conversion not supported. \"\n f\"Mime type: {content.mimeType}\"\n )\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:100-130]()\n\n## 依赖关系\n\n| 依赖包 | 用途 |\n|--------|------|\n| `langchain-core` | LangChain 核心工具和消息类型 |\n| `mcp` | Model Context Protocol SDK |\n| `pydantic` | 数据模型验证 |\n| `langgraph` (可选) | LangGraph 集成支持 |\n\n可选依赖 `langgraph` 用于支持 `Command` 类型返回值，提供 LangGraph 特有的控制流能力。\n\n资料来源：[langchain_mcp_adapters/tools.py:1-30]()\n\n## 总结\n\nlangchain-mcp-adapters 的核心模块结构展现了清晰的分层架构设计：\n\n1. **会话层** (`sessions.py`) 屏蔽了不同传输协议的差异\n2. **适配层** (`tools.py`、`resources.py`、`prompts.py`) 处理 MCP 与 LangChain 类型系统间的转换\n3. **控制层** (`interceptors.py`) 提供了灵活的扩展机制\n4. **入口层** (`client.py`) 整合所有能力，提供统一的用户体验\n\n这种设计使得库能够在保持简洁 API 的同时，支持复杂的 MCP 服务器集成场景。\n\n---\n\n\n\n## 数据流与转换机制\n\n### 相关页面\n\n相关主题：[核心模块结构](#page-core-modules), [工具转换机制](#page-tools-conversion)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n \n\n# 数据流与转换机制\n\n本页面详细说明 langchain-mcp-adapters 库中数据如何在 MCP（Model Context Protocol）与 LangChain 之间流转与转换。核心转换逻辑涵盖工具（Tools）、资源（Resources）和内容块（Content Blocks）三种数据类型。\n\n---\n\n## 1. 整体架构概览\n\n该库采用分层架构，通过适配器模式将 MCP 服务器的功能桥接到 LangChain 生态。数据流遵循以下基本原则：\n\n```mermaid\ngraph TD\n subgraph MCP服务器层\n A[MCP Server]\n A1[Tools]\n A2[Resources]\n A3[Prompts]\n end\n\n subgraph 适配器层\n B[ClientSession]\n C[tools.py]\n D[resources.py]\n E[prompts.py]\n end\n\n subgraph LangChain层\n F[BaseTool]\n G[Blob]\n H[Prompt]\n end\n\n A1 --> B --> C --> F\n A2 --> B --> D --> G\n A3 --> B --> E --> H\n\n style C fill:#e1f5fe\n style D fill:#e8f5e8\n style E fill:#fff3e0\n```\n\n---\n\n## 2. 内容块转换机制\n\n### 2.1 核心转换函数\n\n`_convert_mcp_content_to_lc_block()` 函数负责将 MCP 内容块转换为 LangChain 内容块格式 资料来源：[langchain_mcp_adapters/tools.py:60-102]()\n\n```python\ndef _convert_mcp_content_to_lc_block(content: ContentBlock) -> ToolMessageContentBlock:\n \"\"\"Convert any MCP content block to a LangChain content block.\"\"\"\n```\n\n### 2.2 支持的内容类型映射\n\n| MCP 内容类型 | LangChain 内容块类型 | 转换逻辑 |\n|-------------|---------------------|---------|\n| `TextContent` | `{\"type\": \"text\", \"text\": ...}` | 直接提取 `text` 字段 |\n| `ImageContent` | `{\"type\": \"image\", \"base64\": ..., \"mime_type\": ...}` | 提取 `data` 和 `mimeType` |\n| `AudioContent` | - | 抛出 `NotImplementedError` |\n| `ResourceLink` (image/*) | `{\"type\": \"image\", \"url\": ...}` | 提取 URI 和 mimeType |\n| `ResourceLink` (其他) | `{\"type\": \"file\", \"url\": ...}` | 提取 URI 和 mimeType |\n| `EmbeddedResource` (text) | `{\"type\": \"text\", \"text\": ...}` | 提取内部 resource.text |\n| `EmbeddedResource` (blob) | `{\"type\": \"image\"}` 或 `{\"type\": \"file\"}` | 根据 mimeType 判断 |\n\n### 2.3 内容块转换流程图\n\n```mermaid\ngraph LR\n A[ContentBlock 输入] --> B{类型判断}\n\n B -->|TextContent| C[create_text_block]\n B -->|ImageContent| D[create_image_block]\n B -->|AudioContent| E[NotImplementedError]\n B -->|ResourceLink| F{image/* ?}\n B -->|EmbeddedResource| G{resource类型}\n\n F -->|是| H[create_image_block]\n F -->|否| I[create_file_block]\n\n G -->|TextResourceContents| J[create_text_block]\n G -->|BlobResourceContents| K{image/* ?}\n K -->|是| L[create_image_block]\n K -->|否| M[create_file_block]\n\n C --> N[ToolMessageContentBlock]\n D --> N\n H --> N\n I --> N\n J --> N\n L --> N\n M --> N\n```\n\n---\n\n## 3. 工具转换机制\n\n### 3.1 工具加载入口\n\n`load_mcp_tools()` 函数是加载 MCP 工具的核心入口，负责列出并转换所有可用工具 资料来源：[langchain_mcp_adapters/tools.py:240-290]()\n\n```python\nasync def load_mcp_tools(\n session: ClientSession | None,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None,\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> list[BaseTool]:\n```\n\n### 3.2 单个工具转换\n\n`convert_mcp_tool_to_langchain_tool()` 函数将单个 MCP 工具转换为 LangChain `StructuredTool` 资料来源：[langchain_mcp_adapters/tools.py:165-238]()\n\n```python\ndef convert_mcp_tool_to_langchain_tool(\n session: ClientSession | None,\n tool: MCPTool,\n *,\n connection: Connection | None = None,\n # ... 其他参数\n) -> BaseTool:\n```\n\n**返回的 StructuredTool 配置：**\n\n| 参数 | 来源 | 说明 |\n|-----|------|-----|\n| `name` | `tool.name` 或 `server_name + tool.name` | 可选前缀 |\n| `description` | `tool.description` | 工具描述 |\n| `args_schema` | `tool.inputSchema` | Pydantic 模型 |\n| `coroutine` | `call_tool` 协程 | 异步执行函数 |\n| `response_format` | `\"content_and_artifact\"` | 返回格式 |\n| `metadata` | 工具注解 | 包含元数据 |\n\n### 3.3 工具转换流程\n\n```mermaid\ngraph TD\n A[MCP Tool 输入] --> B[创建 MCP ClientSession]\n B --> C[构建 MCPToolCallRequest]\n C --> D{是否配置拦截器?}\n\n D -->|是| E[执行拦截器链]\n D -->|否| F[直接执行工具]\n\n E --> G[洋葱模型执行]\n F --> H[session.call_tool]\n G --> H\n\n H --> I[MCPToolCallResult]\n I --> J[_convert_call_tool_result]\n\n J --> K[ConvertedToolResult]\n J --> L[MCPToolArtifact]\n\n K --> M[StructuredTool.content]\n L --> M\n```\n\n### 3.4 工具结果转换\n\n`_convert_call_tool_result()` 处理工具调用结果，支持多种返回类型 资料来源：[langchain_mcp_adapters/tools.py:104-164]()\n\n```python\ndef _convert_call_tool_result(\n call_tool_result: MCPToolCallResult,\n) -> tuple[ConvertedToolResult, MCPToolArtifact | None]:\n```\n\n**返回值类型定义：**\n\n```python\nif LANGGRAPH_PRESENT:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage | Command\nelse:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage\n```\n\n**特殊返回值处理：**\n\n| 输入类型 | 行为 |\n|---------|------|\n| `ToolMessage` | 直接返回，不转换 |\n| `Command` (LangGraph) | 直接返回，支持图执行 |\n| `CallToolResult` + `isError=True` | 抛出 `ToolException` |\n| `CallToolResult` + `structuredContent` | 包装为 `MCPToolArtifact` |\n\n### 3.5 MCPToolArtifact 数据结构\n\n```python\nclass MCPToolArtifact(TypedDict):\n \"\"\"Artifact returned from MCP tool calls.\"\"\"\n structured_content: dict[str, Any]\n```\n\n---\n\n## 4. 拦截器链机制\n\n### 4.1 拦截器模式\n\n拦截器采用洋葱模型（Onion Pattern）构建处理链，允许在工具调用前后插入自定义逻辑 资料来源：[langchain_mcp_adapters/interceptors.py]()\n\n```python\ndef _build_interceptor_chain(\n base_handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n tool_interceptors: list[ToolCallInterceptor] | None,\n) -> Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]]:\n```\n\n### 4.2 拦截器请求类型\n\n```python\n@dataclass\nclass MCPToolCallRequest:\n \"\"\"Tool execution request passed to MCP tool call interceptors.\"\"\"\n name: str\n args: dict[str, Any]\n server_name: str\n headers: dict[str, Any] | None\n runtime: Any\n```\n\n### 4.3 拦截器链执行顺序\n\n```mermaid\ngraph TD\n subgraph 拦截器链\n A[请求入口] --> B[拦截器 1 外层]\n B --> C[拦截器 2]\n C --> D[...]\n D --> E[拦截器 N]\n E --> F[base_handler]\n end\n\n subgraph 返回路径\n F --> G[拦截器 N 处理]\n G --> H[拦截器 2 处理]\n H --> I[拦截器 1 处理]\n I --> J[最终结果]\n end\n\n style F fill:#c8e6c9\n```\n\n---\n\n## 5. 资源转换机制\n\n### 5.1 资源到 Blob 的转换\n\n`convert_mcp_resource_to_langchain_blob()` 将 MCP 资源内容转换为 LangChain Blob 对象 资料来源：[langchain_mcp_adapters/resources.py:19-41]()\n\n```python\ndef convert_mcp_resource_to_langchain_blob(\n resource_uri: str, contents: ResourceContents\n) -> Blob:\n \"\"\"Convert an MCP resource content to a LangChain Blob.\"\"\"\n```\n\n**转换逻辑：**\n\n| 资源类型 | 数据处理 |\n|---------|---------|\n| `TextResourceContents` | 直接使用 `text` 字段 |\n| `BlobResourceContents` | `base64.b64decode(blob)` 解码 |\n\n**返回的 Blob 配置：**\n\n```python\nreturn Blob.from_data(\n data=data,\n mime_type=contents.mimeType,\n metadata={\"uri\": resource_uri}\n)\n```\n\n### 5.2 资源加载函数\n\n```mermaid\ngraph LR\n A[load_mcp_resources] --> B{uris 参数?}\n\n B -->|None| C[session.list_resources]\n B -->|str| D[单个 URI]\n B -->|list| E[多个 URI]\n\n C --> F[获取 URI 列表]\n D --> G[session.read_resource]\n E --> G\n F --> G\n\n G --> H[convert_mcp_resource_to_langchain_blob]\n H --> I[Blob 列表]\n```\n\n---\n\n## 6. 会话与连接管理\n\n### 6.1 连接类型支持\n\n`MultiServerMCPClient` 支持多种传输协议连接 资料来源：[langchain_mcp_adapters/client.py]()：\n\n| 传输类型 | 实现类 | 说明 |\n|---------|--------|------|\n| `stdio` | `StdioConnection` | 标准输入输出进程通信 |\n| `sse` | `SSEConnection` | Server-Sent Events |\n| `http` | `StreamableHttpConnection` | HTTP 流式传输 |\n| `websocket` | `WebsocketConnection` | WebSocket 通信 |\n\n### 6.2 会话创建流程\n\n```mermaid\ngraph TD\n A[MultiServerMCPClient.get_tools] --> B{连接类型}\n\n B -->|Stdio| C[StdioServerParameters]\n B -->|SSE| D[SSE 参数]\n B -->|HTTP| E[HTTP 参数]\n B -->|WebSocket| F[WebSocket 参数]\n\n C --> G[stdio_client]\n D --> H[mcp.client.sse]\n E --> I[streamablehttp_client]\n F --> J[websocket_client]\n\n G --> K[ClientSession]\n H --> K\n I --> K\n J --> K\n\n K --> L[load_mcp_tools]\n L --> M[LangChain Tools]\n```\n\n---\n\n## 7. 完整数据流示例\n\n### 7.1 工具调用完整流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户/Agent\n participant LC as LangChain Tool\n participant Adapter as langchain-mcp-adapters\n participant MCP as MCP ClientSession\n participant Server as MCP Server\n\n User->>LC: 调用工具 (name, args)\n LC->>Adapter: call_tool(request)\n Adapter->>Adapter: 构建 MCPToolCallRequest\n Adapter->>Adapter: 执行拦截器链\n Adapter->>MCP: session.call_tool(name, args)\n MCP->>Server: MCP 协议调用\n Server-->>MCP: CallToolResult\n MCP-->>Adapter: CallToolResult\n Adapter->>Adapter: _convert_call_tool_result\n Adapter-->>LC: (ConvertedToolResult, Artifact)\n LC-->>User: ToolMessage / Command\n```\n\n### 7.2 资源访问完整流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Adapter as langchain-mcp-adapters\n participant MCP as MCP ClientSession\n participant Server as MCP Server\n\n User->>Adapter: load_mcp_resources(session, uris)\n Adapter->>MCP: session.list_resources()\n MCP-->>Adapter: 资源列表\n Adapter->>MCP: session.read_resource(uri)\n MCP->>Server: 读取资源请求\n Server-->>MCP: ResourceContents\n MCP-->>Adapter: ResourceContents\n Adapter->>Adapter: 转换内容块\n Adapter-->>User: Blob 对象列表\n```\n\n---\n\n## 8. 类型转换参考\n\n### 8.1 导入的 MCP 类型\n\n| 类型 | 来源 | 用途 |\n|-----|------|-----|\n| `Tool` | `mcp.types` | MCP 工具定义 |\n| `CallToolResult` | `mcp.types` | 工具调用结果 |\n| `ContentBlock` | `mcp.types` | 内容块基类 |\n| `TextContent` | `mcp.types` | 文本内容 |\n| `ImageContent` | `mcp.types` | 图片内容 |\n| `AudioContent` | `mcp.types` | 音频内容 |\n| `ResourceLink` | `mcp.types` | 资源链接 |\n| `EmbeddedResource` | `mcp.types` | 嵌入式资源 |\n\n### 8.2 导入的 LangChain 类型\n\n| 类型 | 来源 | 用途 |\n|-----|------|-----|\n| `BaseTool` | `langchain_core.tools` | LangChain 工具基类 |\n| `StructuredTool` | `langchain_core.tools` | 结构化工具 |\n| `ToolMessage` | `langchain_core.messages` | 工具消息 |\n| `ToolMessageContentBlock` | 自定义类型别名 | 内容块联合类型 |\n| `Blob` | `langchain_core.documents.base` | LangChain Blob |\n\n---\n\n## 9. 错误处理\n\n### 9.1 已实现的异常\n\n| 异常类型 | 触发条件 | 处理位置 |\n|---------|---------|---------|\n| `ToolException` | 工具返回 `isError=True` | `_convert_call_tool_result()` |\n| `NotImplementedError` | 遇到 `AudioContent` | `_convert_mcp_content_to_lc_block()` |\n| `ValueError` | 未知内容类型 | `_convert_mcp_content_to_lc_block()` |\n| `TypeError` | 不支持的资源类型 | `convert_mcp_resource_to_langchain_blob()` |\n\n### 9.2 错误处理流程\n\n```mermaid\ngraph TD\n A[工具调用结果] --> B{isError?}\n B -->|是| C[收集所有文本块]\n C --> D[拼接错误消息]\n D --> E[抛出 ToolException]\n\n B -->|否| F{structuredContent?}\n F -->|有| G[创建 MCPToolArtifact]\n F -->|无| H[返回 None artifact]\n\n G --> I[返回结果和 artifact]\n H --> I\n```\n\n---\n\n## 10. 关键配置参数\n\n### 10.1 load_mcp_tools 参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|-----|------|--------|-----|\n| `session` | `ClientSession` | 必填 | MCP 客户端会话 |\n| `connection` | `Connection` | `None` | 连接配置（无 session 时使用） |\n| `callbacks` | `Callbacks` | `None` | 回调处理器 |\n| `tool_interceptors` | `list[ToolCallInterceptor]` | `None` | 拦截器列表 |\n| `server_name` | `str` | `None` | 服务器名称 |\n| `tool_name_prefix` | `bool` | `False` | 是否为工具名添加前缀 |\n\n### 10.2 MultiServerMCPClient 配置结构\n\n```python\nclient = MultiServerMCPClient({\n \"server_name\": {\n \"transport\": \"stdio\" | \"sse\" | \"http\" | \"websocket\",\n \"command\": \"python\",\n \"args\": [\"/path/to/server.py\"],\n \"env\": {\"KEY\": \"value\"},\n \"url\": \"http://localhost:8000/mcp\",\n \"headers\": {\"Authorization\": \"Bearer xxx\"},\n }\n})\n```\n\n---\n\n本页面涵盖了 langchain-mcp-adapters 库中数据流与转换机制的核心实现，理解这些机制有助于深度定制工具调用流程和构建复杂的多服务器 MCP 集成方案。\n\n---\n\n\n\n## MultiServerMCPClient 客户端\n\n### 相关页面\n\n相关主题：[传输协议类型](#page-transport-types), [工具转换机制](#page-tools-conversion)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n- [langchain_mcp_adapters/prompts.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/prompts.py)\n- [langchain_mcp_adapters/callbacks.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/callbacks.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [README.md](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/README.md)\n \n\n# MultiServerMCPClient 客户端\n\n## 概述\n\n`MultiServerMCPClient` 是 langchain-mcp-adapters 库的核心客户端类，用于连接多个 MCP（Model Context Protocol）服务器并从中加载 LangChain 兼容的工具、提示词和资源。\n\n该客户端的主要作用是将 MCP 服务器提供的工具转换为 LangChain 工具格式，使其能够与 LangChain 和 LangGraph 代理无缝集成。`MultiServerMCPClient` 支持同时连接多个 MCP 服务器，并提供了灵活的配置选项来管理连接、回调和工具调用拦截。\n\n资料来源：[langchain_mcp_adapters/client.py:40-50]()\n\n## 架构设计\n\n### 组件关系图\n\n```mermaid\ngraph TD\n Client[MultiServerMCPClient]\n Conn[connections
dict[str, Connection]]\n Callbacks[Callbacks]\n Interceptors[tool_interceptors
list[ToolCallInterceptor]]\n Prefix[tool_name_prefix
bool]\n \n Client --> Conn\n Client --> Callbacks\n Client --> Interceptors\n Client --> Prefix\n \n Conn --> Stdio[StdioConnection]\n Conn --> SSE[SSEConnection]\n Conn --> HTTP[StreamableHttpConnection]\n Conn --> WS[WebsocketConnection]\n \n Client --> Tools[load_mcp_tools]\n Client --> Resources[load_mcp_resources]\n Client --> Prompts[load_mcp_prompt]\n```\n\n### 核心数据流\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Client as MultiServerMCPClient\n participant Session as ClientSession\n participant Interceptor as ToolCallInterceptor\n participant Server as MCP Server\n \n User->>Client: get_tools()\n Client->>Client: create_session()\n Client->>Session: 初始化连接\n Client->>Session: list_tools()\n Session->>Server: 请求工具列表\n Server-->>Session: 返回工具定义\n Session-->>Client: MCP Tools\n Client->>Interceptor: 链式包装\n Client-->>User: LangChain BaseTools\n```\n\n## 初始化参数\n\n`MultiServerMCPClient` 的构造函数接受以下参数：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `connections` | `dict[str, Connection] \\| None` | `None` | 服务器名称到连接配置的映射字典 |\n| `callbacks` | `Callbacks \\| None` | `None` | 处理通知和事件的回调函数 |\n| `tool_interceptors` | `list[ToolCallInterceptor] \\| None` | `None` | 工具调用拦截器列表 |\n| `tool_name_prefix` | `bool` | `False` | 是否将工具名称前缀服务器名称 |\n\n### connections 配置结构\n\n```python\nconnections: dict[str, Connection] = {\n \"server_name\": {\n # 标准传输配置\n \"command\": \"python\",\n \"args\": [\"/path/to/server.py\"],\n \"transport\": \"stdio\",\n \n # 或 HTTP 传输配置\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n \"headers\": {\"Authorization\": \"Bearer token\"},\n \n # 或其他连接选项...\n }\n}\n```\n\n资料来源：[langchain_mcp_adapters/client.py:50-90]()\n\n## 连接类型\n\n`sessions.py` 模块定义了多种连接类型，支持不同的 MCP 服务器部署方式：\n\n| 连接类型 | 传输协议 | 说明 |\n|----------|----------|------|\n| `StdioConnection` | stdio | 通过标准输入/输出通信，适用于本地进程 |\n| `SSEConnection` | SSE | Server-Sent Events，适用于长连接场景 |\n| `StreamableHttpConnection` | HTTP | 可流式传输的 HTTP 连接 |\n| `WebsocketConnection` | WebSocket | WebSocket 协议连接 |\n\n### StdioConnection 配置\n\n```python\n{\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n \"env\": {\"KEY\": \"value\"}, # 可选：传递给进程的环境变量\n \"cwd\": \"/working/directory\", # 可选：工作目录\n}\n```\n\n资料来源：[langchain_mcp_adapters/sessions.py]()\n\n### HTTP/StreamableHttpConnection 配置\n\n```python\n{\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\", # 或 \"streamable_http\"\n \"headers\": {\n \"Authorization\": \"Bearer YOUR_TOKEN\",\n \"X-Custom-Header\": \"custom-value\"\n },\n \"timeout\": 60.0, # HTTP 请求超时时间\n}\n```\n\n> 仅 `sse` 和 `http` 传输支持运行时 headers\n\n资料来源：[README.md]()\n\n## 核心方法\n\n### get_tools()\n\n获取所有已连接 MCP 服务器的工具列表。\n\n```python\nasync def get_tools(\n self,\n server_name: str | None = None\n) -> list[BaseTool]\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `server_name` | `str \\| None` | 可选，指定服务器名称过滤工具 |\n\n**返回值**: LangChain `BaseTool` 对象列表\n\n资料来源：[langchain_mcp_adapters/client.py]()\n\n### session()\n\n建立与特定 MCP 服务器的会话连接。\n\n```python\n@asynccontextmanager\nasync def session(\n self,\n server_name: str\n) -> AsyncIterator[ClientSession]\n```\n\n**用法示例**:\n```python\nclient = MultiServerMCPClient({...})\nasync with client.session(\"math\") as session:\n tools = await load_mcp_tools(session)\n```\n\n资料来源：[langchain_mcp_adapters/client.py]()\n\n## 使用示例\n\n### 基础用法\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\nall_tools = await client.get_tools()\n```\n\n资料来源：[langchain_mcp_adapters/client.py:75-90]()\n\n### 多服务器连接\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain.agents import create_agent\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\ntools = await client.get_tools()\nagent = create_agent(\"openai:gpt-4.1\", tools)\nresponse = await agent.ainvoke({\"messages\": \"what's (3 + 5) x 12?\"})\n```\n\n资料来源：[README.md]()\n\n### 工具名称前缀\n\n当多个服务器有相同名称的工具时，可使用 `tool_name_prefix` 避免冲突：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n },\n tool_name_prefix=True # 工具名变为 \"weather_search\" 而非 \"search\"\n)\ntools = await client.get_tools()\n```\n\n资料来源：[langchain_mcp_adapters/client.py:61-65]()\n\n## 与 LangGraph 集成\n\n`MultiServerMCPClient` 可与 LangGraph 的 `StateGraph` 结合使用构建复杂代理：\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.graph import StateGraph, MessagesState, START\nfrom langgraph.prebuilt import ToolNode, tools_condition\n\nfrom langchain.chat_models import init_chat_model\n\nmodel = init_chat_model(\"openai:gpt-4.1\")\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"./examples/math_server.py\"],\n \"transport\": \"stdio\",\n },\n }\n)\ntools = await client.get_tools()\n\ndef call_model(state: MessagesState):\n response = model.bind_tools(tools).invoke(state[\"messages\"])\n return {\"messages\": response}\n\nbuilder = StateGraph(MessagesState)\nbuilder.add_node(\"call_model\", call_model)\nbuilder.add_node(\"tools\", ToolNode(tools))\nbuilder.add_edge(START, \"call_model\")\nbuilder.add_conditional_edges(\n \"call_model\",\n tools_condition,\n)\nbuilder.add_edge(\"tools\", \"call_model\")\ngraph = builder.compile()\n```\n\n资料来源：[README.md]()\n\n## 回调机制\n\n`Callbacks` 类提供了处理 MCP 事件的接口：\n\n```python\n@dataclass\nclass Callbacks:\n \"\"\"LangChain MCP 客户端回调\"\"\"\n \n on_logging_message: LoggingMessageCallback | None = None\n on_progress: ProgressCallback | None = None\n on_elicitation: ElicitationCallback | None = None\n```\n\n| 回调类型 | 说明 |\n|----------|------|\n| `on_logging_message` | 日志消息回调 |\n| `on_progress` | 进度通知回调 |\n| `on_elicitation` | 追问/确认请求回调 |\n\n### 回调使用示例\n\n```python\nfrom langchain_mcp_adapters.callbacks import Callbacks, CallbackContext\n\nasync def my_logging_callback(params, context: CallbackContext):\n print(f\"Log: {params}\")\n\ncallbacks = Callbacks(on_logging_message=my_logging_callback)\n\nclient = MultiServerMCPClient(\n {...},\n callbacks=callbacks\n)\n```\n\n资料来源：[langchain_mcp_adapters/callbacks.py]()\n\n## 工具拦截器\n\n`ToolCallInterceptor` 接口允许在工具调用前后进行拦截和处理：\n\n```mermaid\ngraph TD\n Request[MCPToolCallRequest] -->|洋葱模型| I1[Interceptor 1]\n I1 --> I2[Interceptor 2]\n I2 --> I3[Interceptor N]\n I3 --> Handler[Base Handler]\n Handler --> R1[Result 1]\n R1 --> R2[Result 2]\n R2 --> R3[Result N]\n R3 --> Response[MCPToolCallResult]\n```\n\n### 拦截器链构建\n\n```python\ndef _build_interceptor_chain(\n base_handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n tool_interceptors: list[ToolCallInterceptor] | None,\n) -> Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]]\n```\n\n拦截器列表中的第一个拦截器成为最外层，以洋葱模式层层包裹。\n\n### 使用拦截器\n\n```python\nfrom langchain_mcp_adapters.interceptors import (\n MCPToolCallRequest,\n MCPToolCallResult,\n ToolCallInterceptor,\n)\n\nclass LoggingInterceptor(ToolCallInterceptor):\n async def intercept(\n self, request: MCPToolCallRequest, handler\n ) -> MCPToolCallResult:\n print(f\"Calling tool: {request.name}\")\n result = await handler(request)\n print(f\"Tool result: {result}\")\n return result\n\nclient = MultiServerMCPClient(\n {...},\n tool_interceptors=[LoggingInterceptor()]\n)\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py]()\n资料来源：[langchain_mcp_adapters/tools.py:145-175]()\n\n## 注意事项\n\n### 上下文管理器使用限制\n\n> [!warning]\n> 从 langchain-mcp-adapters 0.1.0 版本开始，`MultiServerMCPClient` 不能作为异步上下文管理器使用。\n\n**正确用法**:\n```python\n# 方法 1：直接获取工具\nclient = MultiServerMCPClient(...)\ntools = await client.get_tools()\n\n# 方法 2：显式创建会话\nclient = MultiServerMCPClient(...)\nasync with client.session(server_name) as session:\n tools = await load_mcp_tools(session)\n```\n\n资料来源：[langchain_mcp_adapters/client.py:38-55]()\n\n## 资源与提示词加载\n\n除了工具，`MultiServerMCPClient` 还支持加载 MCP 资源（Blob）和提示词：\n\n### 资源加载\n\n```python\nfrom langchain_mcp_adapters.resources import load_mcp_resources\n\nasync with client.session(\"server_name\") as session:\n blobs = await load_mcp_resources(session)\n```\n\n资料来源：[langchain_mcp_adapters/resources.py]()\n\n### 提示词加载\n\n```python\nfrom langchain_mcp_adapters.prompts import load_mcp_prompt\n\nasync with client.session(\"server_name\") as session:\n messages = await load_mcp_prompt(session, \"prompt_name\", arguments)\n```\n\n资料来源：[langchain_mcp_adapters/prompts.py]()\n\n## 配置参考\n\n### 完整配置示例\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain_mcp_adapters.callbacks import Callbacks\n\nclient = MultiServerMCPClient(\n connections={\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n \"env\": {\"DEBUG\": \"true\"},\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n \"headers\": {\"Authorization\": \"Bearer token\"},\n },\n },\n callbacks=Callbacks(\n on_logging_message=my_logging_callback,\n on_progress=my_progress_callback,\n ),\n tool_interceptors=[LoggingInterceptor()],\n tool_name_prefix=True,\n)\n```\n\n## 总结\n\n`MultiServerMCPClient` 是连接 MCP 服务器与 LangChain 生态系统的桥梁，提供：\n\n- 多服务器并发连接管理\n- 统一的工具转换机制\n- 灵活的回调和拦截器支持\n- 多种传输协议兼容（stdio、HTTP、SSE、WebSocket）\n- 与 LangGraph 的深度集成\n\n---\n\n\n\n## 工具转换机制\n\n### 相关页面\n\n相关主题：[MultiServerMCPClient 客户端](#page-multiserver-client), [数据流与转换机制](#page-data-flow), [工具调用拦截器](#page-interceptors)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [README.md](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/README.md)\n \n\n# 工具转换机制\n\n## 概述\n\n工具转换机制是 langchain-mcp-adapters 库的核心功能，负责将 MCP（Model Context Protocol）工具转换为 LangChain 兼容的工具格式。该机制使得 MCP 服务器提供的工具能够无缝集成到 LangChain 和 LangGraph 智能体应用中。\n\n主要职责包括：\n- 将 MCP 工具声明转换为 LangChain StructuredTool\n- 处理工具调用请求和响应的格式转换\n- 支持内容块的类型转换（文本、图像、音频等）\n- 提供拦截器链模式用于工具调用的扩展处理\n\n资料来源：[tools.py:1-30]()\n\n## 核心类型定义\n\n### 内容块类型\n\n工具转换机制定义了一系列类型别名用于处理不同格式的内容：\n\n```python\n# Type alias for LangChain content blocks used in ToolMessage\nToolMessageContentBlock = TextContentBlock | ImageContentBlock | FileContentBlock\n```\n\n### 转换结果类型\n\n根据 langgraph 是否安装，返回类型有所不同：\n\n```python\nif LANGGRAPH_PRESENT:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage | Command\nelse:\n ConvertedToolResult = list[ToolMessageContentBlock] | ToolMessage\n```\n\n### 工具调用产物\n\n```python\nclass MCPToolArtifact(TypedDict):\n \"\"\"Artifact returned from MCP tool calls.\"\"\"\n structured_content: dict[str, Any]\n```\n\nMCPToolArtifact 是一个 TypedDict，用于包装 MCP 工具调用返回的结构化内容，允许未来扩展更多字段。\n\n资料来源：[tools.py:44-68]()\n\n## 核心转换函数\n\n### 内容块转换\n\n`_convert_mcp_content_to_lc_block()` 函数负责将 MCP 内容块转换为 LangChain 内容块格式：\n\n```mermaid\ngraph TD\n A[MCP ContentBlock] --> B{内容类型判断}\n B -->|TextContent| C[create_text_block]\n B -->|ImageContent| D[create_image_block]\n B -->|AudioContent| E[NotImplementedError]\n B -->|ResourceLink| F{是否为图像类型}\n B -->|EmbeddedResource| G{资源类型判断}\n F -->|是| H[create_image_block]\n F -->|否| I[create_file_block]\n G -->|TextResourceContents| J[create_text_block]\n G -->|BlobResourceContents| K{是否为图像}\n K -->|是| L[create_image_block]\n K -->|否| M[create_file_block]\n```\n\n支持的转换映射关系：\n\n| MCP 内容类型 | LangChain 内容块 | 说明 |\n|-------------|-----------------|------|\n| TextContent | {\"type\": \"text\", \"text\": ...} | 文本内容直接转换 |\n| ImageContent | {\"type\": \"image\", \"base64\": ..., \"mime_type\": ...} | 图像内容带 MIME 类型 |\n| ResourceLink (image/*) | {\"type\": \"image\", \"url\": ..., \"mime_type\": ...} | 图像资源链接 |\n| ResourceLink (other) | {\"type\": \"file\", \"url\": ..., \"mime_type\": ...} | 非图像资源链接 |\n| EmbeddedResource (text) | {\"type\": \"text\", \"text\": ...} | 内嵌文本资源 |\n| EmbeddedResource (blob) | {\"type\": \"image/file\", ...} | 内嵌二进制资源 |\n| AudioContent | 抛出 NotImplementedError | 暂不支持 |\n\n资料来源：[tools.py:71-133]()\n\n### 工具调用结果转换\n\n`_convert_call_tool_result()` 函数将 MCP 的 CallToolResult 转换为 LangChain 格式：\n\n```python\ndef _convert_call_tool_result(\n call_tool_result: MCPToolCallResult,\n) -> tuple[ConvertedToolResult, MCPToolArtifact | None]:\n```\n\n处理逻辑：\n1. 如果返回的是 ToolMessage，直接返回并设置 artifact 为 None\n2. 如果返回的是 Command（LangGraph），直接返回并设置 artifact 为 None\n3. 将所有 MCP 内容块转换为 LangChain 内容块\n4. 如果工具调用出错，抛出 ToolException\n5. 如果存在 structuredContent，包装为 MCPToolArtifact\n\n资料来源：[tools.py:166-216]()\n\n## 工具加载与转换\n\n### 加载所有 MCP 工具\n\n`load_mcp_tools()` 函数从 MCP 会话加载所有可用工具：\n\n```python\nasync def load_mcp_tools(\n session: ClientSession | None,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None,\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> list[BaseTool]:\n```\n\n参数说明：\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| session | ClientSession | 必填 | MCP 客户端会话 |\n| connection | Connection | None | 用于创建新会话的连接配置 |\n| callbacks | Callbacks | None | 处理通知和事件的回调 |\n| tool_interceptors | list[ToolCallInterceptor] | None | 工具调用拦截器列表 |\n| server_name | str | None | 服务器名称 |\n| tool_name_prefix | bool | False | 是否将工具名添加服务器前缀 |\n\n该函数支持分页加载工具，处理最大 1000 次迭代的循环：\n\n```python\nMAX_ITERATIONS = 1000\n```\n\n资料来源：[tools.py:240-295]()\n\n### 单个工具转换\n\n`convert_mcp_tool_to_langchain_tool()` 函数将单个 MCP 工具转换为 LangChain StructuredTool：\n\n```python\ndef convert_mcp_tool_to_langchain_tool(\n session: ClientSession | None,\n tool: MCPTool,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None,\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> BaseTool:\n```\n\n转换后的工具配置：\n\n| 属性 | 来源 | 说明 |\n|------|------|------|\n| name | tool.name 或 f\"{server_name}_{tool.name}\" | 工具名称 |\n| description | tool.description | 工具描述 |\n| args_schema | tool.inputSchema | 参数模式定义 |\n| coroutine | call_tool | 异步执行函数 |\n| response_format | \"content_and_artifact\" | 响应格式 |\n| metadata | tool.annotations.model_dump() | 元数据信息 |\n\n资料来源：[tools.py:297-370]()\n\n## 工具调用执行机制\n\n### 拦截器链模式\n\n工具调用采用洋葱模式（Onion Pattern）构建拦截器链：\n\n```mermaid\ngraph LR\n A[请求] --> B[拦截器 N]\n B --> C[拦截器 N-1]\n C --> D[...]\n D --> E[拦截器 1]\n E --> F[实际工具执行]\n F --> G[拦截器 1]\n G --> H[...]\n H --> I[拦截器 N-1]\n I --> J[响应]\n```\n\n`_build_interceptor_chain()` 函数实现该模式：\n\n```python\ndef _build_interceptor_chain(\n base_handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n tool_interceptors: list[ToolCallInterceptor] | None,\n) -> Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]]:\n \"\"\"Build composed handler chain with interceptors in onion pattern.\"\"\"\n handler = base_handler\n if tool_interceptors:\n for interceptor in reversed(tool_interceptors):\n current_handler = handler\n # 包装逻辑\n return handler\n```\n\n资料来源：[tools.py:136-160](), [interceptors.py:1-45]()\n\n### 工具调用请求\n\nMCPToolCallRequest 是拦截器系统中定义的请求类型：\n\n```python\n@dataclass\nclass MCPToolCallRequest:\n \"\"\"Tool execution request passed to MCP tool call interceptors.\"\"\"\n name: str # 工具名称\n args: dict[str, Any] # 工具参数\n server_name: str # 服务器名称\n headers: dict[str, Any] | None # HTTP 请求头\n runtime: object | None # LangGraph 运行时\n```\n\n### 工具调用响应\n\nMCPToolCallResult 的类型定义：\n\n```python\nif LANGGRAPH_PRESENT:\n MCPToolCallResult = CallToolResult | ToolMessage | Command\nelse:\n MCPToolCallResult = CallToolResult | ToolMessage\n```\n\n资料来源：[interceptors.py:40-55]()\n\n## 错误处理机制\n\n工具转换机制实现了多层错误处理：\n\n### 工具调用错误\n\n当 MCP 工具调用返回错误时：\n\n```python\nif call_tool_result.isError:\n error_parts = []\n for item in tool_content:\n if isinstance(item, str):\n error_parts.append(item)\n elif isinstance(item, dict) and item.get(\"type\") == \"text\":\n error_parts.append(item.get(\"text\", \"\"))\n error_msg = \"\\n\".join(error_parts) if error_parts else str(tool_content)\n raise ToolException(error_msg)\n```\n\n### 内容类型错误\n\n不支持的内容类型会抛出相应异常：\n\n| 内容类型 | 异常类型 | 错误信息 |\n|---------|---------|---------|\n| AudioContent | NotImplementedError | \"AudioContent conversion to LangChain content blocks is not yet supported\" |\n| 未知内容类型 | ValueError | \"Unknown MCP content type: {type}\" |\n| 未知嵌入资源 | ValueError | \"Unknown embedded resource type: {type}\" |\n\n资料来源：[tools.py:88-95](), [tools.py:125-133]()\n\n## 使用示例\n\n### 基础用法\n\n```python\nfrom mcp import ClientSession\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\n# 通过现有会话加载工具\ntools = await load_mcp_tools(session)\n```\n\n### 完整客户端示例\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain.agents import create_agent\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\ntools = await client.get_tools()\n```\n\n### 带拦截器的用法\n\n```python\nfrom langchain_mcp_adapters.interceptors import ToolCallInterceptor\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\nclass LoggingInterceptor(ToolCallInterceptor):\n async def intercept(\n self,\n request: MCPToolCallRequest,\n handler: Callable,\n ) -> MCPToolCallResult:\n print(f\"Calling tool: {request.name}\")\n result = await handler(request)\n print(f\"Tool result: {result}\")\n return result\n\ntools = await load_mcp_tools(\n session,\n tool_interceptors=[LoggingInterceptor()]\n)\n```\n\n资料来源：[README.md:1-100]()\n\n## 架构总结\n\n```mermaid\ngraph TD\n subgraph \"MCP 服务器层\"\n A[MCP Tools]\n B[MCP Resources]\n C[MCP Prompts]\n end\n \n subgraph \"转换适配层\"\n D[load_mcp_tools]\n E[load_mcp_resources]\n F[load_mcp_prompt]\n end\n \n subgraph \"拦截器层\"\n G[ToolCallInterceptor]\n H[MCPToolCallRequest]\n I[MCPToolCallResult]\n end\n \n subgraph \"LangChain/LangGraph 层\"\n J[StructuredTool]\n K[BaseTool]\n L[ToolNode]\n end\n \n A --> D\n D --> G\n G --> H\n H --> I\n I --> J\n J --> K\n J --> L\n```\n\n工具转换机制作为 MCP 与 LangChain 之间的桥梁，通过标准化的转换接口和灵活的拦截器模式，实现了两种协议生态的无缝集成。\n\n---\n\n\n\n## 传输协议类型\n\n### 相关页面\n\n相关主题：[MultiServerMCPClient 客户端](#page-multiserver-client)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [examples/servers/streamable-http-stateless/server.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/examples/servers/streamable-http-stateless/server.py)\n- [README.md](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/README.md)\n \n\n# 传输协议类型\n\n## 概述\n\n`langchain-mcp-adapters` 库支持多种 MCP (Model Context Protocol) 传输协议，用于在不同场景下连接 MCP 服务器与 LangChain 应用。每种传输协议都有其特定的适用环境和配置方式，库通过统一的抽象接口隐藏了底层差异，使得开发者可以灵活选择最适合的传输方式。\n\n传输协议在架构中扮演着客户端与服务器之间通信桥梁的角色，负责建立连接、传输请求和响应。库支持 stdio、HTTP、SSE (Server-Sent Events)、Streamable HTTP 和 WebSocket 五种传输类型。\n\n资料来源：[langchain_mcp_adapters/sessions.py:1-50]()\n\n## 传输协议架构\n\n```mermaid\ngraph TD\n A[MultiServerMCPClient] --> B[Connection 抽象层]\n B --> C[StdioConnection]\n B --> D[McpHttpClientFactory]\n B --> E[SSEConnection]\n B --> F[StreamableHttpConnection]\n B --> G[WebsocketConnection]\n C --> H[stdio transport]\n D --> I[http transport]\n E --> J[sse transport]\n F --> K[streamable-http transport]\n G --> L[websocket transport]\n```\n\n## 支持的传输协议类型\n\n### 1. stdio 传输\n\n**适用场景**：本地进程通信，适用于同一机器上的 MCP 服务器。\n\nstdio 传输通过标准输入/输出流进行进程间通信，是最简单的连接方式。当 MCP 服务器作为子进程运行时，使用此传输协议。\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n }\n }\n)\n```\n\n**配置参数**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `command` | `str` | 是 | 要执行的命令 |\n| `args` | `list[str]` | 是 | 命令行参数列表 |\n| `env` | `dict[str, str]` | 否 | 环境变量 |\n| `cwd` | `str` | 否 | 工作目录 |\n| `encoding` | `str` | 否 | 字符编码 |\n\n资料来源：[README.md:85-95]()\n\n### 2. HTTP 传输\n\n**适用场景**：远程服务器通信，支持跨网络访问 MCP 服务。\n\nHTTP 传输基于传统的请求/响应模式，适用于可以发起 HTTP 请求的环境。客户端通过 RESTful API 与 MCP 服务器通信。\n\n```python\nclient = MultiServerMCPClient(\n {\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n }\n)\n```\n\n**配置参数**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `url` | `str` | 是 | MCP 服务器的 HTTP 端点 URL |\n| `headers` | `dict[str, str]` | 否 | HTTP 请求头 |\n\n资料来源：[langchain_mcp_adapters/client.py:60-75]()\n\n### 3. SSE 传输\n\n**适用场景**：需要服务器推送更新的场景，支持长连接。\n\nSSE (Server-Sent Events) 传输允许服务器主动向客户端推送事件，实现单向实时通信。\n\n```python\nfrom langchain_mcp_adapters.sessions import SSEConnection\n\nconnection = SSEConnection(\n url=\"http://localhost:8000/sse\",\n headers={\"Authorization\": \"Bearer token\"}\n)\n```\n\n**配置参数**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `url` | `str` | 是 | SSE 端点 URL |\n| `headers` | `dict[str, Any]` | 否 | 请求头 |\n| `timeout` | `float` | 否 | 超时时间，默认 5.0 秒 |\n\n资料来源：[langchain_mcp_adapters/sessions.py:180-200]()\n\n### 4. Streamable HTTP 传输\n\n**适用场景**：现代 MCP 应用，需要支持流式响应和会话管理。\n\nStreamable HTTP 是 MCP 规范推荐的传输方式，支持流式响应和会话状态管理。它结合了 HTTP 的请求/响应模式和流式传输的能力。\n\n**启动服务器示例**：\n\n```bash\ncd examples/servers/streamable-http-stateless/\nuv run mcp-simple-streamablehttp-stateless --port 3000\n```\n\n**客户端使用方式**：\n\n```python\nfrom mcp import ClientSession\nfrom mcp.client.streamable_http import streamablehttp_client\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\nasync with streamablehttp_client(\"http://localhost:3000/mcp\") as (read, write, _):\n async with ClientSession(read, write) as session:\n await session.initialize()\n tools = await load_mcp_tools(session)\n```\n\n资料来源：[examples/servers/streamable-http-stateless/server.py:1-30]()\n\n**服务器端实现示例**：\n\n```python\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"StreamableHTTP\")\n\n@mcp.tool()\ndef add(a: int, b: int) -> int:\n \"\"\"Add two numbers\"\"\"\n return a + b\n\nif __name__ == \"__main__\":\n mcp.run(transport=\"http\")\n```\n\n**配置参数**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `url` | `str` | 是 | Streamable HTTP 端点 URL |\n| `headers` | `dict[str, Any]` | 否 | 请求头 |\n| `timeout` | `float` | 否 | 超时时间 |\n\n> 注意：SSE 和 HTTP 传输支持运行时 headers，这些 headers 会随每个 HTTP 请求一起发送到 MCP 服务器。\n\n资料来源：[README.md:45-60]()\n\n### 5. WebSocket 传输\n\n**适用场景**：需要双向实时通信的低延迟应用。\n\nWebSocket 传输提供全双工通信通道，适用于需要频繁双向交互的场景。\n\n**配置参数**：\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `url` | `str` | 是 | WebSocket 服务器 URL |\n| `headers` | `dict[str, Any]` | 否 | 连接头 |\n\n资料来源：[langchain_mcp_adapters/sessions.py:220-240]()\n\n## 连接类型映射表\n\n| 传输协议 | Connection 类 | 内部传输类型 | 支持 Headers |\n|---------|--------------|-------------|-------------|\n| stdio | `StdioConnection` | `stdio` | ❌ |\n| http | `McpHttpClientFactory` | `http` | ✅ |\n| sse | `SSEConnection` | `sse` | ✅ |\n| streamable-http | `StreamableHttpConnection` | `http` | ✅ |\n| websocket | `WebsocketConnection` | `websocket` | ✅ |\n\n资料来源：[langchain_mcp_adapters/sessions.py:50-150]()\n\n## 多服务器传输配置\n\n`MultiServerMCPClient` 支持同时连接多个使用不同传输协议的 MCP 服务器：\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n },\n \"realtime\": {\n \"url\": \"ws://localhost:9000/mcp\",\n \"transport\": \"websocket\",\n }\n }\n)\ntools = await client.get_tools()\n```\n\n资料来源：[README.md:95-115]()\n\n## 传输协议选择指南\n\n```mermaid\ngraph TD\n A[选择传输协议] --> B{通信场景}\n B --> C{本地进程}\n C -->|是| D[stdio]\n C -->|否| E{需要远程访问}\n E -->|是| F{需要流式响应}\n F -->|是| G[streamable-http]\n F -->|否| H{需要实时推送}\n H -->|是| I[SSE]\n H -->|否| J{需要双向通信}\n J -->|是| K[WebSocket]\n J -->|否| L[HTTP]\n```\n\n**选择建议**：\n\n- **本地开发测试**：使用 `stdio`，配置简单，无需启动独立服务器\n- **生产环境部署**：使用 `streamable-http`，符合 MCP 规范推荐\n- **需要实时更新**：使用 `SSE` 或 `WebSocket`\n- **跨网络访问**：使用 `HTTP` 或 `streamable-http`\n\n## 运行时 Headers 配置\n\n对于支持 headers 的传输协议（HTTP、SSE、streamable-http），可以在配置中指定自定义请求头：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"secure_api\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n \"headers\": {\n \"Authorization\": \"Bearer custom-value\",\n \"X-Custom-Header\": \"custom-value\"\n },\n }\n }\n)\n```\n\n> 仅 `sse` 和 `http` 传输支持运行时 headers。这些 headers 会随每个 HTTP 请求传递到 MCP 服务器。\n\n资料来源：[README.md:35-50]()\n\n## 会话管理\n\n### 默认会话行为\n\n默认情况下，每次工具调用都会启动一个新的 `ClientSession`。这简化了使用方式，但在高频调用场景下可能影响性能。\n\n```python\ntools = await client.get_tools()\nresponse = await agent.ainvoke({\"messages\": \"what's (3 + 5) x 12?\"})\n```\n\n资料来源：[README.md:110-120]()\n\n### 显式会话管理\n\n对于需要显式控制会话生命周期的场景，可以使用上下文管理器：\n\n```python\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\nclient = MultiServerMCPClient({...})\nasync with client.session(\"math\") as session:\n tools = await load_mcp_tools(session)\n # 在此上下文中复用同一会话\n```\n\n```python\nasync with client.session(server_name) as session:\n resources = await load_mcp_resources(session, uris=uris)\n```\n\n资料来源：[README.md:120-130]()\n\n## 工具名称前缀\n\n当多个服务器具有相同名称的工具时，可以启用工具名称前缀来避免冲突：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n \"weather\": {\n \"url\": \"http://localhost:8000/mcp\",\n \"transport\": \"http\",\n }\n },\n tool_name_prefix=True # 启用前缀\n)\ntools = await client.get_tools()\n# 工具名称将变为 \"math_add\", \"weather_search\" 等\n```\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `tool_name_prefix` | `bool` | `False` | 是否在工具名称前添加服务器名称前缀 |\n\n资料来源：[langchain_mcp_adapters/client.py:45-55]()\n\n## 环境变量扩展\n\n在 stdio 传输中，支持环境变量的展开功能：\n\n```python\nclient = MultiServerMCPClient(\n {\n \"server\": {\n \"command\": \"python\",\n \"args\": [\"${SCRIPT_PATH}\"], # 将被展开\n \"transport\": \"stdio\",\n \"env\": {\n \"API_KEY\": \"${API_KEY}\" # 引用环境变量\n }\n }\n }\n)\n```\n\n> 只有值（而非键）会被展开；`${command}` 和 `${args}` 保持不变。如果未指定 `env`，则会继承当前环境变量的一个子集。\n\n资料来源：[langchain_mcp_adapters/sessions.py:100-130]()\n\n## 错误处理\n\n不同传输协议的错误处理遵循统一的模式：\n\n```python\ntry:\n async with client.session(\"server_name\") as session:\n tools = await load_mcp_tools(session)\nexcept ConnectionError:\n # 处理连接错误\n pass\nexcept ValueError as e:\n # 处理配置错误\n pass\n```\n\n工具调用错误会被包装为 `ToolException`：\n\n```python\nfrom langchain_core.tools import ToolException\n\ntry:\n result = await tool.ainvoke({\"arg\": \"value\"})\nexcept ToolException as e:\n # 处理工具执行错误\n pass\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:80-120]()\n\n---\n\n\n\n## 工具调用拦截器\n\n### 相关页面\n\n相关主题：[回调机制](#page-callbacks), [工具转换机制](#page-tools-conversion)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n \n\n# 工具调用拦截器\n\n## 概述\n\n工具调用拦截器（Tool Call Interceptor）是 langchain-mcp-adapters 框架中用于拦截和控制 MCP 工具调用生命周期的核心机制。它采用**洋葱模式（Onion Pattern）**构建可组合的处理器链，允许开发者在工具调用的请求和响应阶段注入自定义逻辑。\n\n拦截器的主要作用包括：\n\n- 在工具执行前后添加日志记录和监控\n- 修改工具调用的参数或请求头\n- 验证或转换工具返回结果\n- 实现重试逻辑和错误处理\n- 支持 LangGraph Command 的特殊返回类型处理\n\n资料来源：[langchain_mcp_adapters/interceptors.py:1-10]()\n\n## 架构设计\n\n### 洋葱模式处理器链\n\n拦截器通过洋葱模式组织，形成多层嵌套的处理器链。当工具调用时，请求从外到内逐层传递，执行完成后结果再从内到外逐层返回。\n\n```mermaid\ngraph TD\n subgraph 拦截器链\n A[\"拦截器 1 (最外层)\"] --> B[\"拦截器 2\"]\n B --> C[\"拦截器 N\"]\n C --> D[\"实际工具执行器\"]\n end\n \n E[\"MCPToolCallRequest\"] --> A\n D --> F[\"MCPToolCallResult\"]\n \n style A fill:#e1f5fe\n style D fill:#c8e6c9\n style F fill:#fff3e0\n```\n\n### 核心类型体系\n\n| 类型 | 说明 | 资料来源 |\n|------|------|----------|\n| `MCPToolCallRequest` | 工具调用请求的数据类，包含名称、参数、服务器名、请求头等信息 | [interceptors.py:38-56]() |\n| `MCPToolCallResult` | 工具调用结果的类型别名，支持 `CallToolResult`、`ToolMessage` 或 `Command` | [interceptors.py:28-33]() |\n| `ToolCallInterceptor` | 拦截器接口协议，定义异步调用方法 | [interceptors.py:70-75]() |\n| `_MCPToolCallRequestOverrides` | 可覆盖的请求字段类型定义 | [interceptors.py:35-37]() |\n\n## MCPToolCallRequest 数据结构\n\n`MCPToolCallRequest` 是拦截器接收到的工具调用请求对象，采用 dataclass 模式定义：\n\n```python\n@dataclass\nclass MCPToolCallRequest:\n \"\"\"工具执行请求的请求对象\"\"\"\n name: str # 工具名称\n args: dict[str, Any] # 工具参数\n server_name: str # 服务器名称\n headers: dict[str, Any] | None # HTTP 请求头\n runtime: object | None # LangGraph 运行时对象\n```\n\n### 请求覆盖机制\n\n通过 `override()` 方法可以创建修改后的请求副本：\n\n```python\ndef override(\n self, **overrides: Unpack[_MCPToolCallRequestOverrides]\n) -> MCPToolCallRequest:\n \"\"\"创建带有指定覆盖字段的新请求实例\"\"\"\n```\n\n支持覆盖的字段：\n\n| 字段名 | 类型 | 说明 |\n|--------|------|------|\n| `name` | `str` | 工具名称 |\n| `args` | `dict[str, Any]` | 工具参数 |\n| `headers` | `dict[str, Any] \\| None` | HTTP 请求头 |\n\n资料来源：[interceptors.py:56-66]()\n\n## ToolCallInterceptor 接口\n\n拦截器必须实现 `ToolCallInterceptor` 协议：\n\n```python\n@runtime_checkable\nclass ToolCallInterceptor(Protocol):\n \"\"\"拦截器接口协议\"\"\"\n \n async def __call__(\n self,\n request: MCPToolCallRequest,\n handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n ) -> MCPToolCallResult:\n \"\"\"拦截并处理工具调用\"\"\"\n ...\n```\n\n### 接口参数说明\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| `request` | `MCPToolCallRequest` | 工具调用请求对象 |\n| `handler` | `Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]]` | 下一个处理器（调用链中的下一个拦截器或实际执行器） |\n\n### 返回值\n\n返回类型为 `MCPToolCallResult`，支持以下三种格式：\n\n| 类型 | 说明 | 使用场景 |\n|------|------|----------|\n| `CallToolResult` | MCP 协议标准结果 | 标准工具调用返回 |\n| `ToolMessage` | LangChain 消息格式 | LangChain 集成 |\n| `Command` | LangGraph 命令 | LangGraph 工作流控制 |\n\n资料来源：[interceptors.py:28-33]()\n\n## 拦截器链构建\n\n拦截器链通过 `_build_interceptor_chain()` 函数构建，采用反向迭代方式将拦截器层层包装：\n\n```python\ndef _build_interceptor_chain(\n base_handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n tool_interceptors: list[ToolCallInterceptor] | None,\n) -> Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]]:\n \"\"\"构建带有拦截器的洋葱模式处理器链\"\"\"\n \n handler = base_handler\n \n if tool_interceptors:\n for interceptor in reversed(tool_interceptors):\n current_handler = handler\n async def wrapped(request, next_handler=current_handler):\n return await interceptor(request, next_handler)\n handler = wrapped\n \n return handler\n```\n\n### 构建流程说明\n\n1. **基础处理器** (`base_handler`)：最内层的实际工具执行函数\n2. **反向迭代**：从列表最后一个拦截器开始向前包装\n3. **闭包捕获**：每个拦截器通过闭包持有对下一个处理器的引用\n4. **返回组合处理器**：最终返回最外层的处理器\n\n资料来源：[langchain_mcp_adapters/tools.py:75-95]()\n\n## 拦截器在工具加载中的应用\n\n### load_mcp_tools 函数集成\n\n`load_mcp_tools()` 函数接受 `tool_interceptors` 参数，将拦截器链注入到工具调用流程中：\n\n```python\nasync def load_mcp_tools(\n session: ClientSession | None,\n *,\n connection: Connection | None = None,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None, # 拦截器列表\n server_name: str | None = None,\n tool_name_prefix: bool = False,\n) -> list[BaseTool]:\n```\n\n### 工具调用执行流程\n\n```mermaid\nsequenceDiagram\n participant 调用者\n participant 工具 as LangChain 工具\n participant 拦截器链 as 拦截器链\n participant 执行器 as 实际执行器\n participant MCP as MCP Session\n\n 调用者->>工具: 调用工具函数\n 工具->>拦截器链: MCPToolCallRequest\n 拦截器链->>执行器: 传递请求\n 执行器->>MCP: session.call_tool()\n MCP-->>执行器: CallToolResult\n 执行器-->>拦截器链: MCPToolCallResult\n 拦截器链-->>工具: MCPToolCallResult\n 工具-->>调用者: (content, artifact)\n```\n\n### 拦截器链的执行环境\n\n在工具的 `call_tool` 内部函数中，拦截器链被创建和应用：\n\n```python\nasync def call_tool(\n runtime: Annotated[object | None, InjectedToolArg()] = None,\n **arguments: dict[str, Any],\n) -> tuple[ConvertedToolResult, MCPToolArtifact | None]:\n # ... 参数验证和回调处理 ...\n\n # 创建最内层处理器 - 实际执行 MCP 工具调用\n async def execute_tool(request: MCPToolCallRequest) -> MCPToolCallResult:\n return await session.call_tool(\n tool_name,\n tool_args,\n progress_callback=mcp_callbacks.progress_callback,\n )\n\n # 构建并执行拦截器链\n handler = _build_interceptor_chain(execute_tool, tool_interceptors)\n request = MCPToolCallRequest(\n name=tool.name,\n args=arguments,\n server_name=server_name or \"unknown\",\n headers=None,\n runtime=runtime,\n )\n call_tool_result = await handler(request)\n\n return _convert_call_tool_result(call_tool_result)\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:98-130]()\n\n## 使用示例\n\n### 基本拦截器实现\n\n```python\nfrom langchain_mcp_adapters.interceptors import (\n MCPToolCallRequest,\n MCPToolCallResult,\n ToolCallInterceptor,\n)\n\nclass LoggingInterceptor:\n \"\"\"日志记录拦截器\"\"\"\n \n async def __call__(\n self,\n request: MCPToolCallRequest,\n handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n ) -> MCPToolCallResult:\n print(f\"调用工具: {request.name}, 参数: {request.args}\")\n result = await handler(request)\n print(f\"工具 {request.name} 执行完成\")\n return result\n\nclass ValidationInterceptor:\n \"\"\"参数验证拦截器\"\"\"\n \n async def __call__(\n self,\n request: MCPToolCallRequest,\n handler: Callable[[MCPToolCallRequest], Awaitable[MCPToolCallResult]],\n ) -> MCPToolCallResult:\n # 修改请求参数\n if request.name == \"search\" and \"query\" in request.args:\n modified_request = request.override(\n args={**request.args, \"query\": request.args[\"query\"].strip()}\n )\n return await handler(modified_request)\n return await handler(request)\n```\n\n### 多拦截器组合使用\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain_mcp_adapters.tools import load_mcp_tools\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n }\n)\n\n# 按照配置顺序，最前面的拦截器成为最外层\ninterceptors = [\n LoggingInterceptor(), # 最外层 - 首先执行\n ValidationInterceptor(), # 次外层 - 第二执行\n]\n\ntools = await client.get_tools(tool_interceptors=interceptors)\n```\n\n### 拦截器在 LangGraph 中的使用\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.graph import StateGraph, MessagesState\nfrom langgraph.prebuilt import ToolNode\n\nclient = MultiServerMCPClient({...})\ntools = await client.get_tools(\n tool_interceptors=[LoggingInterceptor()],\n server_name=\"math\"\n)\n\n# 拦截器可以返回 Command 对象控制 LangGraph 流程\nclass ConditionalInterceptor:\n async def __call__(\n self,\n request: MCPToolCallRequest,\n handler: Callable,\n ) -> MCPToolCallResult:\n result = await handler(request)\n # 根据结果决定是否路由到其他节点\n return result\n```\n\n## MultiServerMCPClient 中的拦截器支持\n\n`MultiServerMCPClient` 类在初始化时接受全局拦截器配置：\n\n```python\nclass MultiServerMCPClient:\n def __init__(\n self,\n connections: dict[str, dict[str, Any]] | None = None,\n *,\n callbacks: Callbacks | None = None,\n tool_interceptors: list[ToolCallInterceptor] | None = None, # 全局拦截器\n tool_name_prefix: bool = False,\n ) -> None:\n self.tool_interceptors = tool_interceptors or []\n```\n\n### 配置参数说明\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `connections` | `dict[str, dict[str, Any]]` | `None` | 服务器连接配置映射 |\n| `callbacks` | `Callbacks \\| None` | `None` | 回调处理器 |\n| `tool_interceptors` | `list[ToolCallInterceptor]` | `[]` | 全局拦截器列表 |\n| `tool_name_prefix` | `bool` | `False` | 是否为工具名添加服务器前缀 |\n\n资料来源：[langchain_mcp_adapters/client.py:50-60]()\n\n## 最佳实践\n\n### 1. 拦截器顺序\n\n拦截器的执行顺序与其在列表中的顺序一致：\n\n- **列表首位** → **最外层** → **最先收到请求，最后收到响应**\n- **列表末位** → **最内层** → **最后收到请求，最先收到响应**\n\n### 2. 错误处理\n\n建议在最外层拦截器中实现统一的错误处理：\n\n```python\nclass ErrorHandlingInterceptor:\n async def __call__(\n self,\n request: MCPToolCallRequest,\n handler: Callable,\n ) -> MCPToolCallResult:\n try:\n return await handler(request)\n except Exception as e:\n # 统一错误处理和日志记录\n return CallToolResult(\n content=[TextContent(text=f\"Error: {str(e)}\")],\n isError=True,\n )\n```\n\n### 3. 请求修改\n\n使用 `override()` 方法进行不可变请求修改：\n\n```python\n# 正确：创建新实例\nmodified = request.override(args={\"query\": \"new value\"})\n\n# 错误：直接修改（不应该这样做）\nrequest.args[\"query\"] = \"new value\"\n```\n\n### 4. 性能考量\n\n- 避免在拦截器中执行耗时的同步操作\n- 使用异步处理保持非阻塞执行\n- 对于高频调用，考虑拦截器的性能开销\n\n---\n\n\n\n## 回调机制\n\n### 相关页面\n\n相关主题：[工具调用拦截器](#page-interceptors), [MultiServerMCPClient 客户端](#page-multiserver-client)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/interceptors.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/interceptors.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n \n\n# 回调机制\n\n## 概述\n\n回调机制是 langchain-mcp-adapters 中用于处理 MCP 工具调用生命周期事件的核心组件。该机制允许开发者在工具执行的不同阶段插入自定义逻辑，实现进度监控、事件通知、错误处理等高级功能。\n\n回调系统在 MCP 客户端与 LangChain 工具之间建立了桥梁，使得 MCP 服务器发出的通知（notifications）能够被 LangChain 端正确处理和响应。\n\n## 核心组件\n\n### 组件架构\n\n```mermaid\ngraph TD\n A[MCP 服务器] -->|通知/进度| B[ClientSession]\n B --> C[Callbacks]\n C --> D[CallbackContext]\n D --> E[工具执行]\n E --> F[_MCPCallbacks]\n F --> G[进度回调]\n \n H[开发者代码] -->|自定义回调| C\n```\n\n### CallbackContext\n\n`CallbackContext` 是回调上下文的载体，用于在回调处理过程中传递工具调用的关键信息。\n\n| 属性 | 类型 | 说明 |\n|------|------|------|\n| `server_name` | `str` | 工具所属的 MCP 服务器名称 |\n| `tool_name` | `str` | 被调用的工具名称 |\n\n资料来源：[langchain_mcp_adapters/tools.py:1-1]()\n\n### Callbacks\n\n`Callbacks` 类是回调机制的主要入口点，封装了所有与 MCP 服务器通信的回调处理逻辑。\n\n```python\nclass Callbacks:\n \"\"\"用于处理 MCP 通知和事件的回调接口\"\"\"\n```\n\n开发者通过实例化 `Callbacks` 并传递给 `MultiServerMCPClient` 或 `load_mcp_tools` 来启用自定义回调处理。\n\n资料来源：[langchain_mcp_adapters/client.py:1-1]()\n\n### _MCPCallbacks\n\n`_MCPCallbacks` 是内部默认回调实现类，用于将 LangChain 格式的回调转换为 MCP SDK 所需的格式。\n\n```python\nclass _MCPCallbacks:\n \"\"\"内部回调实现，桥接 LangChain 和 MCP SDK\"\"\"\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:1-1]()\n\n## 工作流程\n\n### 回调初始化流程\n\n```mermaid\nsequenceDiagram\n participant 用户 as 用户代码\n participant 客户端 as MultiServerMCPClient\n participant 回调 as Callbacks\n participant 上下文 as CallbackContext\n participant 工具 as load_mcp_tools\n\n 用户->>客户端: 传入 Callbacks 实例\n 客户端->>工具: 传递 callbacks 参数\n 工具->>回调: to_mcp_format(context)\n 回调->>上下文: 创建 CallbackContext\n Note over 上下文: 包含 server_name, tool_name\n```\n\n### 工具调用中的回调处理\n\n```mermaid\ngraph LR\n A[工具调用请求] --> B[call_tool 函数]\n B --> C{已有 Callbacks?}\n C -->|是| D[to_mcp_format]\n C -->|否| E[_MCPCallbacks]\n D --> F[CallbackContext]\n E --> F\n F --> G[progress_callback]\n G --> H[MCP Session.call_tool]\n```\n\n在 `call_tool` 函数中，回调按以下方式使用：\n\n```python\nmcp_callbacks = (\n callbacks.to_mcp_format(\n context=CallbackContext(server_name=server_name, tool_name=tool.name)\n )\n if callbacks is not None\n else _MCPCallbacks()\n)\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:145-156]()\n\n## API 参考\n\n### load_mcp_tools 参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `session` | `ClientSession` | 否 | MCP 客户端会话 |\n| `connection` | `Connection` | 否 | 连接配置 |\n| `callbacks` | `Callbacks` | 否 | 回调处理器 |\n| `tool_interceptors` | `list[ToolCallInterceptor]` | 否 | 工具调用拦截器 |\n| `server_name` | `str` | 否 | 服务器名称 |\n| `tool_name_prefix` | `bool` | 否 | 工具名称前缀 |\n\n资料来源：[langchain_mcp_adapters/tools.py:199-230]()\n\n### convert_mcp_tool_to_langchain_tool 参数\n\n| 参数 | 类型 | 必填 | 说明 |\n|------|------|------|------|\n| `session` | `ClientSession` | 否 | MCP 客户端会话 |\n| `tool` | `MCPTool` | 是 | 待转换的 MCP 工具 |\n| `callbacks` | `Callbacks` | 否 | 回调处理器 |\n| `tool_interceptors` | `list[ToolCallInterceptor]` | 否 | 拦截器列表 |\n| `server_name` | `str` | 否 | 服务器名称 |\n| `tool_name_prefix` | `bool` | 否 | 是否添加前缀 |\n\n资料来源：[langchain_mcp_adapters/tools.py:232-290]()\n\n## 使用示例\n\n### 基本用法\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langchain_mcp_adapters.callbacks import Callbacks\n\n# 定义自定义回调处理\nclass MyCallbacks(Callbacks):\n def __init__(self):\n super().__init__()\n \n def to_mcp_format(self, context):\n # 实现自定义转换逻辑\n return super().to_mcp_format(context)\n\n# 使用回调客户端\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"/path/to/math_server.py\"],\n \"transport\": \"stdio\",\n },\n },\n callbacks=MyCallbacks()\n)\n\ntools = await client.get_tools()\n```\n\n### 与拦截器配合使用\n\n回调机制可以与拦截器（interceptors）配合使用，实现更复杂的工具调用控制：\n\n```mermaid\ngraph TD\n A[请求] --> B[拦截器1]\n B --> C[拦截器2]\n C --> D[拦截器N]\n D --> E[execute_tool]\n E --> D\n D --> C\n C --> B\n B --> F[响应]\n```\n\n```python\nfrom langchain_mcp_adapters.interceptors import ToolCallInterceptor\n\nasync def my_interceptor(\n request: MCPToolCallRequest,\n handler: Callable\n) -> MCPToolCallResult:\n # 前置处理\n print(f\"调用工具: {request.name}\")\n result = await handler(request)\n # 后置处理\n print(f\"工具返回: {result}\")\n return result\n\ntools = await load_mcp_tools(\n session,\n callbacks=custom_callbacks,\n tool_interceptors=[my_interceptor]\n)\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:61-95]()\n\n## 高级功能\n\n### 进度回调\n\n回调系统支持 MCP 协议的进度通知机制。当 MCP 服务器通过 `progress_callback` 发送进度更新时，系统会将其传递给 LangChain 端处理。\n\n```python\ncall_tool_result = await session.call_tool(\n tool_name,\n tool_args,\n progress_callback=mcp_callbacks.progress_callback,\n)\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:157-165]()\n\n### 工具调用请求拦截\n\n通过 `MCPToolCallRequest` 和 `MCPToolCallResult` 类型，回调系统支持对工具调用请求和响应进行完整的拦截处理：\n\n```python\n@dataclass\nclass MCPToolCallRequest:\n \"\"\"工具执行请求，传递给拦截器\"\"\"\n name: str\n args: dict[str, Any]\n server_name: str\n headers: dict[str, Any] | None\n runtime: Any # LangGraph 运行时上下文\n```\n\n资料来源：[langchain_mcp_adapters/interceptors.py:1-1]()\n\n## 最佳实践\n\n1. **始终传递 server_name**：确保回调上下文能够正确识别工具所属的服务器\n2. **合理使用拦截器链**：多个拦截器按洋葱模型执行，避免过度嵌套\n3. **处理异常情况**：在回调中实现适当的错误处理逻辑\n4. **性能考虑**：避免在回调中执行耗时操作，以免阻塞工具调用\n\n## 与 LangGraph 集成\n\n当项目中安装了 `langgraph` 时，回调机制支持额外的 `runtime` 参数，用于传递 LangGraph 的执行上下文：\n\n```python\nasync def call_tool(\n runtime: Annotated[object | None, InjectedToolArg()] = None,\n **arguments: dict[str, Any],\n) -> tuple[ConvertedToolResult, MCPToolArtifact | None]:\n request = MCPToolCallRequest(\n name=tool.name,\n args=arguments,\n server_name=server_name or \"unknown\",\n headers=None,\n runtime=runtime, # LangGraph 运行时上下文\n )\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:126-142]()\n\n## 相关模块\n\n| 模块 | 功能 |\n|------|------|\n| `langchain_mcp_adapters.callbacks` | 回调接口定义和实现 |\n| `langchain_mcp_adapters.interceptors` | 工具调用拦截器接口 |\n| `langchain_mcp_adapters.tools` | 工具加载和转换，含回调集成 |\n| `langchain_mcp_adapters.client` | 多服务器客户端，回调配置入口 |\n\n---\n\n\n\n## 提示词与资源转换\n\n### 相关页面\n\n相关主题：[数据流与转换机制](#page-data-flow), [核心模块结构](#page-core-modules)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [langchain_mcp_adapters/prompts.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/prompts.py)\n- [langchain_mcp_adapters/resources.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/resources.py)\n- [langchain_mcp_adapters/tools.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/tools.py)\n- [langchain_mcp_adapters/client.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/client.py)\n- [langchain_mcp_adapters/sessions.py](https://github.com/langchain-ai/langchain-mcp-adapters/blob/main/langchain_mcp_adapters/sessions.py)\n \n\n# 提示词与资源转换\n\n## 概述\n\n`langchain-mcp-adapters` 库提供了两大核心转换模块，用于将 MCP（Model Context Protocol）的提示词（Prompts）和资源（Resources）转换为 LangChain 兼容的格式。这些模块使得 MCP 服务器可以作为 LangChain 和 LangGraph 应用的外部工具和数据来源。\n\n| 模块 | 源文件 | 功能描述 |\n|------|--------|----------|\n| 提示词转换 | `prompts.py` | 将 MCP 提示词消息转换为 LangChain 消息对象 |\n| 资源转换 | `resources.py` | 将 MCP 资源内容转换为 LangChain Blob 对象 |\n\n资料来源：[langchain_mcp_adapters/prompts.py:1-10]()，[langchain_mcp_adapters/resources.py:1-15]()\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph MCP服务器端\n MCP[MCP Server]\n Prompts[MCP Prompts]\n Resources[MCP Resources]\n end\n\n subgraph langchain_mcp_adapters\n prompts_module[prompts.py]\n resources_module[resources.py]\n end\n\n subgraph LangChain端\n LCMessages[LangChain Messages
HumanMessage/AIMessage]\n LCBlobs[LangChain Blobs]\n end\n\n Prompts -->|get_prompt| prompts_module\n Resources -->|read_resource| resources_module\n prompts_module --> LCMessages\n resources_module --> LCBlobs\n\n style MCP服务器端 fill:#e1f5fe\n style LangChain端 fill:#f3e5f5\n style langchain_mcp_adapters fill:#fff3e0\n```\n\n## 提示词转换模块\n\n### 模块定位\n\n`prompts.py` 模块负责将 MCP 服务器提供的提示词（Prompts）转换为 LangChain 的消息对象。提示词是 MCP 协议中用于定义预定义对话模板的机制，允许服务器提供结构化的提示内容。\n\n资料来源：[langchain_mcp_adapters/prompts.py:1-10]()\n\n### 核心函数\n\n#### `convert_mcp_prompt_message_to_langchain_message()`\n\n该函数将单个 MCP 提示词消息转换为 LangChain 消息对象。\n\n**函数签名：**\n\n```python\ndef convert_mcp_prompt_message_to_langchain_message(\n message: PromptMessage,\n) -> HumanMessage | AIMessage:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `message` | `PromptMessage` | MCP 提示词消息对象 |\n\n**支持的转换规则：**\n\n| MCP 消息类型 | LangChain 消息类型 |\n|-------------|-------------------|\n| `role: user, content.type: text` | `HumanMessage` |\n| `role: assistant, content.type: text` | `AIMessage` |\n\n**异常处理：**\n\n| 错误条件 | 抛出异常 |\n|---------|----------|\n| `content.type` 非 `text` | `ValueError` |\n| `role` 非 `user` 或 `assistant` | `ValueError` |\n\n资料来源：[langchain_mcp_adapters/prompts.py:12-35]()\n\n#### `load_mcp_prompt()`\n\n异步函数，用于从 MCP 会话加载提示词并转换为 LangChain 消息列表。\n\n**函数签名：**\n\n```python\nasync def load_mcp_prompt(\n session: ClientSession,\n name: str,\n *,\n arguments: dict[str, Any] | None = None,\n) -> list[HumanMessage | AIMessage]:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `session` | `ClientSession` | 是 | MCP 客户端会话 |\n| `name` | `str` | 是 | 提示词名称 |\n| `arguments` | `dict[str, Any] \\| None` | 否 | 传递给提示词的参数 |\n\n**返回值：**\n\n返回转换后的 LangChain 消息列表，消息类型为 `HumanMessage` 或 `AIMessage`。\n\n**工作流程：**\n\n```mermaid\nsequenceDiagram\n participant Client as 客户端\n participant Session as MCP ClientSession\n participant Adapter as prompts.py\n participant LC as LangChain Messages\n\n Client->>Adapter: load_mcp_prompt(session, name, arguments)\n Adapter->>Session: get_prompt(name, arguments)\n Session-->>Adapter: PromptMessage[]\n Loop 遍历每条消息\n Adapter->>Adapter: convert_mcp_prompt_message_to_langchain_message()\n end\n Adapter-->>Client: list[HumanMessage | AIMessage]\n```\n\n资料来源：[langchain_mcp_adapters/prompts.py:38-60]()\n\n## 资源转换模块\n\n### 模块定位\n\n`resources.py` 模块负责将 MCP 协议中的资源（Resources）转换为 LangChain 的 Blob 对象。资源可以是文本内容或二进制数据（如图片、文件等），Blob 对象提供了统一的数据包装接口。\n\n资料来源：[langchain_mcp_adapters/resources.py:1-18]()\n\n### 核心函数\n\n#### `convert_mcp_resource_to_langchain_blob()`\n\n将单个 MCP 资源内容转换为 LangChain Blob 对象。\n\n**函数签名：**\n\n```python\ndef convert_mcp_resource_to_langchain_blob(\n resource_uri: str, contents: ResourceContents\n) -> Blob:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `resource_uri` | `str` | 资源的 URI 标识符 |\n| `contents` | `ResourceContents` | 资源内容（TextResourceContents 或 BlobResourceContents） |\n\n**支持的资源类型：**\n\n| MCP 资源类型 | LangChain 处理方式 |\n|-------------|-------------------|\n| `TextResourceContents` | 直接使用文本数据 |\n| `BlobResourceContents` | Base64 解码后使用 |\n\n**Blob 元数据：**\n\n转换后的 Blob 对象包含以下元数据：\n\n| 元数据键 | 值 |\n|---------|-----|\n| `uri` | 资源的 URI |\n\n**异常处理：**\n\n| 错误条件 | 抛出异常 |\n|---------|----------|\n| 不支持的资源内容类型 | `TypeError` |\n\n资料来源：[langchain_mcp_adapters/resources.py:20-42]()\n\n#### `get_mcp_resource()`\n\n异步函数，用于获取单个 MCP 资源并转换为 LangChain Blob 对象列表。\n\n**函数签名：**\n\n```python\nasync def get_mcp_resource(session: ClientSession, uri: str) -> list[Blob]:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 描述 |\n|------|------|------|\n| `session` | `ClientSession` | MCP 客户端会话 |\n| `uri` | `str` | 要获取的资源 URI |\n\n**返回值：**\n\n返回 LangChain Blob 对象列表。如果资源内容为空，则返回空列表。\n\n资料来源：[langchain_mcp_adapters/resources.py:44-61]()\n\n#### `load_mcp_resources()`\n\n异步函数，用于批量加载 MCP 资源。\n\n**函数签名：**\n\n```python\nasync def load_mcp_resources(\n session: ClientSession,\n *,\n uris: str | list[str] | None = None,\n) -> list[Blob]:\n```\n\n**参数说明：**\n\n| 参数 | 类型 | 必填 | 描述 |\n|------|------|------|------|\n| `session` | `ClientSession` | 是 | MCP 客户端会话 |\n| `uris` | `str \\| list[str] \\| None` | 否 | 要加载的 URI 列表，`None` 表示加载所有资源 |\n\n**加载行为：**\n\n| `uris` 值 | 行为 |\n|----------|------|\n| `None` | 调用 `session.list_resources()` 获取所有资源 URI |\n| `str` | 仅加载指定的单个 URI |\n| `list[str]` | 加载指定的 URI 列表 |\n\n> [!note]\n> 动态资源（Dynamic Resources）在 `uris` 为 `None` 时**不会**被加载，因为它们需要参数，而 MCP SDK 的 `session.list_resources()` 方法无法处理这类资源。\n\n资料来源：[langchain_mcp_adapters/resources.py:64-90]()\n\n## 数据模型\n\n### MCP 类型引用\n\n```mermaid\nclassDiagram\n class PromptMessage {\n +str role\n +Content content\n }\n\n class ResourceContents {\n <>\n }\n\n class TextResourceContents {\n +str uri\n +str text\n +str mimeType\n }\n\n class BlobResourceContents {\n +str uri\n +str blob\n +str mimeType\n }\n\n class TextContent {\n +str type\n +str text\n }\n\n class BlobResourceContents {\n +str uri\n +str blob\n +str mimeType\n }\n\n ResourceContents <|-- TextResourceContents\n ResourceContents <|-- BlobResourceContents\n\n note for ResourceContents \"MCP types from mcp.types\"\n```\n\n### LangChain 类型对应\n\n| MCP 类型 | LangChain 类型 | 说明 |\n|---------|---------------|------|\n| `PromptMessage` | `HumanMessage \\| AIMessage` | 提示词消息 |\n| `TextResourceContents` | `Blob` (文本数据) | 文本资源 |\n| `BlobResourceContents` | `Blob` (二进制数据) | 二进制资源 |\n\n## 客户端集成\n\n`MultiServerMCPClient` 提供了对提示词和资源转换的统一访问接口。\n\n资料来源：[langchain_mcp_adapters/client.py:1-60]()\n\n### 核心方法\n\n| 方法 | 功能 |\n|------|------|\n| `get_tools()` | 获取所有 MCP 工具并转换为 LangChain 工具 |\n| `get_prompts()` | 获取所有 MCP 提示词 |\n| `get_resources()` | 获取所有 MCP 资源 |\n| `session(server_name)` | 获取指定服务器的会话上下文管理器 |\n\n### 使用示例\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient(\n {\n \"math\": {\n \"command\": \"python\",\n \"args\": [\"./math_server.py\"],\n \"transport\": \"stdio\",\n },\n }\n)\n\n# 获取工具\ntools = await client.get_tools()\n\n# 获取资源\nresources = await client.get_resources()\n```\n\n## 会话管理\n\n提示词和资源的加载依赖于 `ClientSession` 对象，该对象通过 `sessions.py` 模块创建和管理。\n\n资料来源：[langchain_mcp_adapters/sessions.py:1-100]()\n\n### 支持的传输类型\n\n| 传输类型 | 说明 | 支持状态 |\n|---------|------|----------|\n| `stdio` | 标准输入输出传输 | ✅ 完全支持 |\n| `sse` | Server-Sent Events | ✅ 完全支持 |\n| `http` | Streamable HTTP | ✅ 完全支持 |\n| `websocket` | WebSocket | ✅ 完全支持 |\n\n## 类型转换流程\n\n### 提示词转换流程\n\n```mermaid\nflowchart LR\n subgraph MCP层\n MCP_Prompt[MCP get_prompt]\n PM[PromptMessage]\n end\n\n subgraph 转换层\n convert[convert_mcp_prompt_message_to_langchain_message]\n end\n\n subgraph LangChain层\n HM[HumanMessage]\n AM[AIMessage]\n end\n\n MCP_Prompt --> PM\n PM --> convert\n convert -->|role=user| HM\n convert -->|role=assistant| AM\n```\n\n### 资源转换流程\n\n```mermaid\nflowchart LR\n subgraph MCP层\n MCP_Resource[MCP read_resource]\n TRC[TextResourceContents]\n BRC[BlobResourceContents]\n end\n\n subgraph 转换层\n convert[convert_mcp_resource_to_langchain_blob]\n decode[base64.b64decode]\n end\n\n subgraph LangChain层\n Blob[Blob]\n end\n\n MCP_Resource --> TRC\n MCP_Resource --> BRC\n TRC --> convert\n BRC --> decode\n decode --> convert\n convert --> Blob\n```\n\n## 错误处理\n\n### 提示词转换错误\n\n| 错误类型 | 条件 | 处理方式 |\n|---------|------|----------|\n| `ValueError` | 不支持的 `content.type` | 抛出异常 |\n| `ValueError` | 不支持的 `role` 值 | 抛出异常 |\n\n### 资源转换错误\n\n| 错误类型 | 条件 | 处理方式 |\n|---------|------|----------|\n| `TypeError` | 不支持的资源内容类型 | 抛出异常 |\n| `RuntimeError` | 获取资源时发生错误 | 由调用方处理 |\n\n## 与工具转换的关系\n\n提示词和资源转换与 `tools.py` 中的工具转换模块共同构成了 MCP 到 LangChain 的完整适配体系。\n\n```mermaid\ngraph TD\n subgraph MCP协议\n MCP_Tools[Tools]\n MCP_Prompts[Prompts]\n MCP_Resources[Resources]\n end\n\n subgraph langchain_mcp_adapters\n tools_module[tools.py]\n prompts_module[prompts.py]\n resources_module[resources.py]\n end\n\n subgraph LangChain\n LC_Tools[StructuredTool]\n LC_Messages[Messages]\n LC_Blobs[Blobs]\n end\n\n MCP_Tools --> tools_module\n MCP_Prompts --> prompts_module\n MCP_Resources --> resources_module\n\n tools_module --> LC_Tools\n prompts_module --> LC_Messages\n resources_module --> LC_Blobs\n```\n\n资料来源：[langchain_mcp_adapters/tools.py:1-100]()\n\n## 最佳实践\n\n### 1. 资源批量加载\n\n当需要加载多个资源时，使用 `load_mcp_resources()` 的 `uris` 参数指定资源列表，避免多次调用 `get_mcp_resource()`：\n\n```python\n# 推荐方式\nresources = await load_mcp_resources(session, uris=[\"uri1\", \"uri2\", \"uri3\"])\n\n# 不推荐方式（多次网络往返）\nres1 = await get_mcp_resource(session, \"uri1\")\nres2 = await get_mcp_resource(session, \"uri2\")\nres3 = await get_mcp_resource(session, \"uri3\")\n```\n\n### 2. 提示词参数传递\n\n使用 `arguments` 参数为提示词提供上下文信息：\n\n```python\nmessages = await load_mcp_prompt(\n session,\n name=\"code_review\",\n arguments={\"repo\": \"langchain-mcp-adapters\", \"pr\": 123}\n)\n```\n\n### 3. 错误处理\n\n实现适当的错误处理以应对资源不可用或格式不支持的情况：\n\n```python\ntry:\n resources = await load_mcp_resources(session, uris=uri_list)\nexcept TypeError as e:\n logger.error(f\"Unsupported resource type: {e}\")\n```\n\n## 总结\n\n`langchain-mcp-adapters` 的提示词和资源转换模块为 LangChain 应用提供了访问 MCP 服务器结构和数据的能力：\n\n| 组件 | 文件 | 核心功能 |\n|------|------|----------|\n| 提示词转换 | `prompts.py` | 将 MCP Prompts 转换为 `HumanMessage`/`AIMessage` |\n| 资源转换 | `resources.py` | 将 MCP Resources 转换为 LangChain `Blob` 对象 |\n\n这两个模块与工具转换模块（`tools.py`）一起，构成了 MCP 到 LangChain 的完整适配层，使得开发者可以在 LangChain 和 LangGraph 应用中无缝使用 MCP 服务器提供的各种功能。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：langchain-ai/langchain-mcp-adapters\n\n摘要：发现 17 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Prompts and Resources auto-discovery。\n\n## 1. 安装坑 · 来源证据：Prompts and Resources auto-discovery\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Prompts and Resources auto-discovery\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bf1812b74caa4e989767a9307a8ffc16 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/62 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：`MultiServerMCPClient.get_tools()` silently returns no tools when any single server fails to connect\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`MultiServerMCPClient.get_tools()` silently returns no tools when any single server fails to connect\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a5093182914b4df0b7ad2cd560bacdf2 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/492 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 运行坑 · 来源证据：Fix TypeError in resources.py and make __aexit__ an async coroutine in client.py\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Fix TypeError in resources.py and make __aexit__ an async coroutine in client.py\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac102050dd4841d6954559a3413e0b92 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/496 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：langchain-mcp-adapters==0.2.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：langchain-mcp-adapters==0.2.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0c6ca0722ab046379d28ecf30f8d2bcf | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：langchain-mcp-adapters==0.1.10\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：langchain-mcp-adapters==0.1.10\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b18dbf32ccd41e38b272a458f4040f5 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 来源证据：langchain-mcp-adapters==0.1.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：langchain-mcp-adapters==0.1.14\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6727e0d698e54fc38d7c60e262978ac2 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.14 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：langchain-mcp-adapters==0.1.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：langchain-mcp-adapters==0.1.12\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e71a46a9e0374d139555a78f229b0469 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.12 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：langchain-mcp-adapters==0.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：langchain-mcp-adapters==0.2.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_59483f9a6a16414c9087b1751fba8efc | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 来源证据：langchain-mcp-adapters==0.2.0a1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：langchain-mcp-adapters==0.2.0a1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e7fcda1716948898295279af95f8f96 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0a1 | 来源类型 github_release 暴露的待验证使用条件。\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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Feature Request: Support passing server-defined params extensions (e.g. LangGraph `context`) through tools/call\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Support passing server-defined params extensions (e.g. LangGraph `context`) through tools/call\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8c46dab4b6dd4a6e92c96af49ea47647 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/502 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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项目：langchain-ai/langchain-mcp-adapters\n\n摘要：发现 17 个潜在踩坑项，其中 3 个为 high/blocking；最高优先级：安装坑 - 来源证据：Prompts and Resources auto-discovery。\n\n## 1. 安装坑 · 来源证据：Prompts and Resources auto-discovery\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Prompts and Resources auto-discovery\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_bf1812b74caa4e989767a9307a8ffc16 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/62 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 2. 安装坑 · 来源证据：`MultiServerMCPClient.get_tools()` silently returns no tools when any single server fails to connect\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：`MultiServerMCPClient.get_tools()` silently returns no tools when any single server fails to connect\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_a5093182914b4df0b7ad2cd560bacdf2 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/492 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 3. 运行坑 · 来源证据：Fix TypeError in resources.py and make __aexit__ an async coroutine in client.py\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：Fix TypeError in resources.py and make __aexit__ an async coroutine in client.py\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_ac102050dd4841d6954559a3413e0b92 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/496 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安装坑 · 来源证据：langchain-mcp-adapters==0.2.2\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：langchain-mcp-adapters==0.2.2\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_0c6ca0722ab046379d28ecf30f8d2bcf | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.2 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 5. 配置坑 · 来源证据：langchain-mcp-adapters==0.1.10\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：langchain-mcp-adapters==0.1.10\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b18dbf32ccd41e38b272a458f4040f5 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.10 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 6. 能力坑 · 来源证据：langchain-mcp-adapters==0.1.14\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：langchain-mcp-adapters==0.1.14\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6727e0d698e54fc38d7c60e262978ac2 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.14 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 7. 能力坑 · 能力判断依赖假设\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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | README/documentation is current enough for a first validation pass.\n\n## 8. 运行坑 · 来源证据：langchain-mcp-adapters==0.1.12\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：langchain-mcp-adapters==0.1.12\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_e71a46a9e0374d139555a78f229b0469 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.1.12 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 9. 维护坑 · 来源证据：langchain-mcp-adapters==0.2.0\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：langchain-mcp-adapters==0.2.0\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_59483f9a6a16414c9087b1751fba8efc | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0 | 来源类型 github_release 暴露的待验证使用条件。\n\n## 10. 维护坑 · 来源证据：langchain-mcp-adapters==0.2.0a1\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个维护/版本相关的待验证问题：langchain-mcp-adapters==0.2.0a1\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_4e7fcda1716948898295279af95f8f96 | https://github.com/langchain-ai/langchain-mcp-adapters/releases/tag/langchain-mcp-adapters%3D%3D0.2.0a1 | 来源类型 github_release 暴露的待验证使用条件。\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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | no_demo; severity=medium\n\n## 15. 安全/权限坑 · 来源证据：Feature Request: Support passing server-defined params extensions (e.g. LangGraph `context`) through tools/call\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Feature Request: Support passing server-defined params extensions (e.g. LangGraph `context`) through tools/call\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8c46dab4b6dd4a6e92c96af49ea47647 | https://github.com/langchain-ai/langchain-mcp-adapters/issues/502 | 来源讨论提到 python 相关条件，需在安装/试用前复核。\n\n## 16. 维护坑 · 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:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | issue_or_pr_quality=unknown\n\n## 17. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:929158279 | https://github.com/langchain-ai/langchain-mcp-adapters | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# langchain-mcp-adapters - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 langchain-mcp-adapters 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: LangChain 🔌 MCP 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-project-introduction：项目介绍。围绕“项目介绍”模拟一次用户任务，不展示安装或运行结果。\n2. page-installation：安装与配置。围绕“安装与配置”模拟一次用户任务，不展示安装或运行结果。\n3. page-core-modules：核心模块结构。围绕“核心模块结构”模拟一次用户任务，不展示安装或运行结果。\n4. page-multiserver-client：MultiServerMCPClient 客户端。围绕“MultiServerMCPClient 客户端”模拟一次用户任务，不展示安装或运行结果。\n5. page-tools-conversion：工具转换机制。围绕“工具转换机制”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-project-introduction\n输入：用户提供的“项目介绍”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-installation\n输入：用户提供的“安装与配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-core-modules\n输入：用户提供的“核心模块结构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-multiserver-client\n输入：用户提供的“MultiServerMCPClient 客户端”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-tools-conversion\n输入：用户提供的“工具转换机制”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-project-introduction：Step 1 必须围绕“项目介绍”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-installation：Step 2 必须围绕“安装与配置”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-core-modules：Step 3 必须围绕“核心模块结构”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-multiserver-client：Step 4 必须围绕“MultiServerMCPClient 客户端”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-tools-conversion：Step 5 必须围绕“工具转换机制”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/langchain-ai/langchain-mcp-adapters\n- https://github.com/langchain-ai/langchain-mcp-adapters#readme\n- README.md\n- langchain_mcp_adapters/__init__.py\n- pyproject.toml\n- langchain_mcp_adapters/tools.py\n- langchain_mcp_adapters/client.py\n- langchain_mcp_adapters/sessions.py\n- langchain_mcp_adapters/callbacks.py\n- langchain_mcp_adapters/interceptors.py\n- langchain_mcp_adapters/prompts.py\n- langchain_mcp_adapters/resources.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 langchain-mcp-adapters 的核心服务。\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项目：langchain-ai/langchain-mcp-adapters\n\n## 官方安装入口\n\n### Python / pip · 官方安装入口\n\n```bash\npip install langchain-mcp-adapters\n```\n\n来源：https://github.com/langchain-ai/langchain-mcp-adapters#readme\n\n## 来源\n\n- repo: https://github.com/langchain-ai/langchain-mcp-adapters\n- docs: https://github.com/langchain-ai/langchain-mcp-adapters#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_3abacb7c691849fc8f2ee8ca09a88b62"
}