{
"canonical_name": "LeelaissakAttota/mcp-ai-agent",
"compilation_id": "pack_4ac1960484824534b98bb60495500e22",
"created_at": "2026-05-15T05:27:05.544762+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx metmuseum-mcp` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx metmuseum-mcp",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "llm_execute_isolated_install",
"sandbox_validation_id": "sbx_ccdb5337e58a4efa940bd0efa5441305"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_9c93cf81c5d4c68e58c1726d77770728",
"canonical_name": "LeelaissakAttota/mcp-ai-agent",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/LeelaissakAttota/mcp-ai-agent",
"slug": "mcp-ai-agent",
"source_packet_id": "phit_eb5664b8920445c19f82f29bffba7a1e",
"source_validation_id": "dval_f6686d472c4548ada16c6e08363cb8f5"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": 0,
"github_stars": 1,
"one_liner_en": "Multi-server MCP AI agent — LangGraph ReAct + GPT-5 Nano connecting Context7 docs (HTTP) & MetMuseum 400K artworks (STDIO) with persistent conversation memory",
"one_liner_zh": "Multi-server MCP AI agent — LangGraph ReAct + GPT-5 Nano connecting Context7 docs (HTTP) & MetMuseum 400K artworks (STDIO) with persistent conversation memory",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host 等宿主 AI 的用户",
"title_en": "mcp-ai-agent",
"title_zh": "mcp-ai-agent 能力包",
"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": "Local AI Workspace",
"label_zh": "本地 AI 工作台",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-local-ai-workspace",
"type": "user_job"
},
{
"label_en": "Durable Memory",
"label_zh": "长期记忆",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-durable-memory",
"type": "core_capability"
},
{
"label_en": "Checkpoint Resume",
"label_zh": "断点恢复流程",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-checkpoint-resume",
"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_eb5664b8920445c19f82f29bffba7a1e",
"page_model": {
"artifacts": {
"artifact_slug": "mcp-ai-agent",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx metmuseum-mcp",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/LeelaissakAttota/mcp-ai-agent#readme",
"verified": true
}
],
"display_tags": [
"MCP 工具",
"本地 AI 工作台",
"长期记忆",
"断点恢复流程",
"本地优先"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "Multi-server MCP AI agent — LangGraph ReAct + GPT-5 Nano connecting Context7 docs (HTTP) & MetMuseum 400K artworks (STDIO) with persistent conversation memory"
},
{
"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": "仓库名 `mcp-ai-agent` 与安装入口 `metmuseum-mcp` 不完全一致。",
"category": "身份坑",
"evidence": [
"identity.distribution | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | repo=mcp-ai-agent; install=metmuseum-mcp"
],
"severity": "medium",
"suggested_check": "在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。",
"title": "仓库名和安装名不一致",
"user_impact": "用户照着仓库名搜索包或照着包名找仓库时容易走错入口。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | 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:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": 1,
"forks": 0,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": 1
},
"source_url": "https://github.com/LeelaissakAttota/mcp-ai-agent",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "Multi-server MCP AI agent — LangGraph ReAct + GPT-5 Nano connecting Context7 docs (HTTP) & MetMuseum 400K artworks (STDIO) with persistent conversation memory",
"title": "mcp-ai-agent 能力包",
"trial_prompt": "# mcp-ai-agent - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcp-ai-agent 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Multi-server MCP AI agent — LangGraph ReAct + GPT-5 Nano connecting Context7 docs (HTTP) & MetMuseum 400K artworks (STDIO) with persistent conversation memory 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：技术栈详解。围绕“技术栈详解”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：LangGraph ReAct代理实现。围绕“LangGraph ReAct代理实现”模拟一次用户任务，不展示安装或运行结果。\n5. page-5：持久化对话记忆机制。围绕“持久化对话记忆机制”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“技术栈详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“LangGraph ReAct代理实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-5\n输入：用户提供的“持久化对话记忆机制”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“技术栈详解”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“LangGraph ReAct代理实现”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-5：Step 5 必须围绕“持久化对话记忆机制”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/LeelaissakAttota/mcp-ai-agent\n- https://github.com/LeelaissakAttota/mcp-ai-agent#readme\n- README.md\n- main.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcp-ai-agent 的核心服务。\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": "当前没有项目级社区来源；不会把未抓取讨论包装成社会证明。",
"items": [],
"status": "待发现 Agent 补证",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "Multi-server MCP AI agent — LangGraph ReAct + GPT-5 Nano connecting Context7 docs (HTTP) & MetMuseum 400K artworks (STDIO) with persistent conversation memory",
"effort": "安装已验证",
"forks": 0,
"icon": "link",
"name": "mcp-ai-agent 能力包",
"risk": "需复核",
"slug": "mcp-ai-agent",
"stars": 1,
"tags": [
"MCP 工具",
"本地 AI 工作台",
"长期记忆",
"断点恢复流程",
"本地优先"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/LeelaissakAttota/mcp-ai-agent 项目说明书\n\n生成时间：2026-05-13 03:43:18 UTC\n\n## 目录\n\n- [项目概览](#page-1)\n- [技术栈详解](#page-2)\n- [系统架构设计](#page-3)\n- [LangGraph ReAct代理实现](#page-4)\n- [持久化对话记忆机制](#page-5)\n- [MultiServerMCPClient配置](#page-6)\n- [集成MCP服务器详解](#page-7)\n- [安装与配置指南](#page-8)\n- [运行与交互指南](#page-9)\n- [扩展与定制指南](#page-10)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[技术栈详解](#page-2), [系统架构设计](#page-3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n \n\n# 项目概览\n\n## 项目简介\n\nmcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器智能代理项目，扮演着 AI 应用与外部工具服务之间的 **\"Universal Interface\"**（通用接口）角色，类似于 USB-C 在硬件连接中的地位。该项目实现了同时连接多个 MCP 服务器、跨协议传输管理、持久化对话记忆以及由 GPT-5 Nano 驱动的自主工具选择能力。\n\n**技术定位：** Agentic AI — 多服务器 MCP 代理 \n**编程语言：** Python 3.10+ \n**核心模型：** OpenAI GPT-5 Nano \n**代理框架：** LangGraph ReAct \n**协议支持：** STDIO + HTTP 双传输层\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 核心架构\n\n### 系统架构图\n\n```mermaid\ngraph TB\n subgraph 用户层[\"用户层 (CLI 界面)\"]\n U[用户输入查询]\n end\n \n subgraph 代理层[\"LangGraph ReAct 代理\"]\n LLM[GPT-5 Nano
推理引擎]\n MEM[InMemorySaver
对话记忆]\n TOOL[自主工具选择]\n end\n \n subgraph 传输层[\"MCP 传输层\"]\n HTTP[HTTP Transport
远程云端]\n STDIO[STDIO Transport
本地 npx]\n end\n \n subgraph 服务层[\"MCP 服务器\"]\n C7[Context7 Server
文档搜索]\n MET[MetMuseum Server
艺术馆数据]\n end\n \n U --> LLM\n LLM --> TOOL\n TOOL --> HTTP\n TOOL --> STDIO\n HTTP --> C7\n STDIO --> MET\n LLM <--> MEM\n```\n\n### 技术组件表\n\n| 组件类别 | 技术实现 | 功能说明 |\n|---------|---------|---------|\n| **MCP 客户端** | MultiServerMCPClient (langchain-mcp-adapters) | 多服务器并发连接管理 |\n| **代理框架** | LangGraph ReAct | 推理+行动一体化代理 |\n| **语言模型** | ChatOpenAI (gpt-5-nano) | 自然语言理解和生成 |\n| **记忆系统** | InMemorySaver | 线程化对话持久化 |\n| **异步运行时** | asyncio | 并发任务执行 |\n| **HTTP 服务器** | Context7 (streamable_http) | 远程文档检索 |\n| **STDIO 服务器** | metmuseum-mcp (npx) | 本地艺术馆数据访问 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 工作流程\n\n### 代理决策流程\n\n```mermaid\ngraph TD\n A[用户自然语言查询] --> B{GPT-5 Nano 推理}\n B --> C{判断查询类型}\n C -->|代码/文档类| D[调用 Context7 HTTP]\n C -->|艺术/博物馆类| E[调用 MetMuseum STDIO]\n D --> F[获取文档数据]\n E --> G[获取艺术品数据]\n F --> H[LLM 生成响应]\n G --> H\n H --> I[存储至 InMemorySaver]\n I --> J[返回用户响应]\n```\n\n### 典型交互流程\n\n| 步骤 | 阶段 | 说明 |\n|-----|------|------|\n| 1 | 用户输入 | 通过 CLI 输入自然语言问题 |\n| 2 | LLM 推理 | GPT-5 Nano 分析查询意图 |\n| 3 | 工具选择 | 自动决定调用哪个 MCP 服务器 |\n| 4 | 工具执行 | 跨协议执行对应工具调用 |\n| 5 | 结果处理 | 工具结果返回给 LLM |\n| 6 | 响应生成 | LLM 生成自然语言回复 |\n| 7 | 记忆存储 | 完整对话存入线程化存储 |\n| 8 | 用户展示 | 显示最终响应给用户 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 集成 MCP 服务器\n\n### 服务器配置表\n\n| 服务器名称 | 传输协议 | 端点/命令 | 数据类型 | 用途 |\n|-----------|---------|----------|---------|------|\n| **Context7** | HTTP (streamable_http) | `https://mcp.context7.com/mcp` | 软件框架文档 | LLM 优化的多框架文档搜索 |\n| **MetMuseum-MCP** | STDIO | `npx -y metmuseum-mcp` | 艺术品元数据 | 40万+ 大都会艺术博物馆藏品 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n### 多服务器连接实现\n\n```python\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\", # 远程 HTTP\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\", # 本地 STDIO\n }\n})\ntools = await client.get_tools() # 聚合所有服务器工具\n```\n\n资料来源：[main.py:22-35](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n## 核心功能特性\n\n### 1. LangGraph ReAct 代理\n\n代理采用 ReAct（Reasoning + Acting）模式，结合 GPT-5 Nano 的推理能力与工具调用能力：\n\n```python\nagent = create_react_agent(\n model=openai_model, # GPT-5 Nano 推理引擎\n tools=tools, # 聚合的 MCP 工具集\n checkpointer=checkpointer # 持久化记忆\n)\n```\n\n### 2. 持久化对话记忆\n\n通过 InMemorySaver 实现线程化的对话状态保持：\n\n```python\ncheckpointer = InMemorySaver()\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n每个线程（thread_id）维护独立的对话上下文，支持跨轮次上下文理解。\n\n### 3. 自主工具选择\n\nLLM 根据用户查询语义自动判断应调用哪个服务器：\n\n| 用户查询示例 | 调用的服务器 | 返回内容 |\n|-------------|-------------|---------|\n| \"LangChain 代理文档\" | Context7 | 框架文档检索结果 |\n| \"梵高的画作\" | MetMuseum | 艺术品元数据+图片 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 项目结构\n\n```\nmcp-ai-agent/\n│\n├── main.py # 完整的多服务器 MCP 代理实现\n│ ├── 导入模块 (第1-6行)\n│ ├── MCP 客户端配置 (第22-35行)\n│ ├── OpenAI 模型初始化 (第42-44行)\n│ ├── 工具获取 (第47行)\n│ ├── 记忆系统配置 (第50-53行)\n│ └── 代理创建与交互循环 (第56-86行)\n│\n└── README.md # 项目文档\n```\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 快速开始\n\n### 环境准备\n\n| 依赖项 | 安装命令 |\n|-------|---------|\n| langchain-mcp-adapters | `pip install langchain-mcp-adapters` |\n| langgraph | `pip install langgraph` |\n| langchain-openai | `pip install langchain-openai` |\n| npx | `npm install -g npx` |\n\n### 运行步骤\n\n1. **安装依赖**\n ```bash\n pip install langchain-mcp-adapters langgraph langchain-openai\n npm install -g npx\n ```\n\n2. **配置环境变量**\n ```bash\n export OPENAI_API_KEY=\"your-api-key-here\"\n ```\n\n3. **启动代理**\n ```bash\n python main.py\n ```\n\n4. **交互操作**\n ```\n Menu:\n 1. Ask the agent a question\n 2. Quit\n Enter your choice (1 or 2): 1\n \n Your question\n > What LangGraph tools are available?\n → 代理调用 Context7 → 返回文档\n ```\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 关键技术亮点\n\n| 特性 | 技术实现 | 优势 |\n|-----|---------|-----|\n| 多协议并发 | STDIO + HTTP 同时管理 | 灵活连接本地/远程服务 |\n| 对话持久化 | InMemorySaver + thread_id | 跨会话上下文保持 |\n| 异步架构 | asyncio + await | 高效并发任务处理 |\n| 自主决策 | LLM 推理引擎 | 无需人工指定工具 |\n| 跨域查询 | 多 MCP 服务器聚合 | 统一的自然语言接口 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 适用场景\n\n- **文档智能问答**：通过 Context7 检索编程框架文档并回答技术问题\n- **艺术藏品探索**：查询大都会艺术博物馆的藏品信息和图像\n- **多源数据整合**：聚合不同领域的外部数据源\n- **智能助手开发**：构建具有工具调用能力的对话代理\n\n---\n\n\n\n## 技术栈详解\n\n### 相关页面\n\n相关主题：[项目概览](#page-1), [系统架构设计](#page-3), [LangGraph ReAct代理实现](#page-4)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n \n\n# 技术栈详解\n\n## 概述\n\nmcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器 AI 智能体项目，通过集成多个 MCP 服务器实现跨域查询能力。该项目采用 Python 3.10+ 开发，核心架构围绕 LangGraph ReAct 智能体构建，结合 OpenAI GPT-5 Nano 模型进行推理决策，并通过 InMemorySaver 实现会话持久化管理。\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 核心技术组件\n\n### 2.1 编程语言与运行环境\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | 3.10+ | 主要开发语言 |\n| Node.js | 需安装 | 用于运行 MetMuseum-MCP 服务器 |\n| npm/npx | 需全局安装 | 包管理和 MCP 服务器启动 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n### 2.2 核心依赖库\n\n| 库名称 | 版本要求 | 功能描述 |\n|--------|----------|----------|\n| langchain-mcp-adapters | 最新版 | MCP 多服务器客户端适配器 |\n| langgraph | 最新版 | ReAct 智能体构建框架 |\n| langchain-openai | 最新版 | OpenAI 语言模型集成 |\n| asyncio | 标准库 | 异步编程支持 |\n\n资料来源：[main.py:1-7](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 2.3 语言模型\n\n项目采用 OpenAI GPT-5 Nano 模型作为推理引擎，负责以下核心任务：\n\n- 理解用户自然语言查询意图\n- 自主决策调用哪个 MCP 服务器\n- 生成最终的自然语言响应\n\n```python\nopenai_model = ChatOpenAI(\n model=\"gpt-5-nano\", # 使用 OpenAI GPT-5 Nano 模型\n)\n```\n\n资料来源：[main.py:49-51](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n## 架构设计\n\n### 3.1 系统架构图\n\n```mermaid\ngraph TD\n User[用户 CLI 界面] --> Agent[LangGraph ReAct 智能体]\n Agent --> LLM[GPT-5 Nano 推理引擎]\n LLM --> Decision[自主工具选择]\n Decision --> Context7[Context7 服务器
HTTP 传输]\n Decision --> MetMuseum[MetMuseum-MCP 服务器
STDIO 传输]\n Context7 --> DocsResult[库/代码文档]\n MetMuseum --> ArtResult[艺术品元数据/图片]\n Agent --> Memory[InMemorySaver
会话记忆]\n \n subgraph 传输层\n Context7\n MetMuseum\n end\n```\n\n### 3.2 分层职责\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 表现层 | CLI 用户交互界面 | 接收用户输入，展示智能体响应 |\n| 智能体层 | LangGraph ReAct Agent | 协调推理、工具调用、响应生成 |\n| 推理层 | GPT-5 Nano | 理解意图、决策路由、生成回复 |\n| 工具层 | MCP Servers | 提供外部数据查询能力 |\n| 持久化层 | InMemorySaver | 维护会话线程记忆 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## MCP 多服务器架构\n\n### 4.1 MultiServerMCPClient 配置\n\n项目使用 `MultiServerMCPClient` 同时管理两个不同传输协议的 MCP 服务器：\n\n```python\nclient = MultiServerMCPClient({\n # Context7 服务器 - 提供库文档访问\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\", # 远程 HTTP 传输\n },\n # Met Museum 服务器 - 提供博物馆藏品数据\n \"met-museum\": {\n \"command\": \"npx\", # Node.js 包运行器\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\", # 标准输入/输出传输\n }\n})\n```\n\n资料来源：[main.py:26-42](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 4.2 集成 MCP 服务器对比\n\n| 服务器名称 | 传输协议 | 连接类型 | 主要功能 | 工具数量 |\n|-----------|---------|----------|---------|----------|\n| Context7 | streamable_http | 远程/云端 | LLM 优化文档搜索，覆盖主流框架库 | 多工具 |\n| MetMuseum-MCP | stdio | 本地/npx | 访问大都会艺术博物馆 40 万+藏品 | 多工具 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n### 4.3 传输协议详解\n\n#### HTTP 流式传输 (streamable_http)\n\n- **适用场景**：远程云端 MCP 服务器\n- **优势**：低延迟、易穿越防火墙、支持流式响应\n- **配置参数**：\n - `url`: 服务器端点 URL\n - `transport`: 必须设为 `streamable_http`\n\n#### STDIO 传输 (stdio)\n\n- **适用场景**：本地 MCP 服务器\n- **优势**：简单可靠、无需网络配置\n- **配置参数**：\n - `command`: 执行命令（通常为 `npx`）\n - `args`: 命令参数列表\n - `transport`: 必须设为 `stdio`\n\n## LangGraph ReAct 智能体\n\n### 5.1 智能体创建\n\n```python\nagent = create_react_agent(\n model=openai_model, # 语言模型\n tools=tools, # MCP 服务器工具\n checkpointer=checkpointer # 会话记忆检查点\n)\n```\n\n资料来源：[main.py:60-64](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 5.2 ReAct 工作流程\n\n```mermaid\ngraph LR\n A[用户查询] --> B[Reasoning
推理阶段]\n B --> C[Action
行动阶段]\n C --> D[Observation
观察阶段]\n D --> E{完成?}\n E -->|否| B\n E -->|是| F[最终响应]\n```\n\n### 5.3 ReAct 模式特点\n\n| 阶段 | 描述 | 执行者 |\n|------|------|--------|\n| Reasoning | 分析用户意图，决定是否调用工具 | GPT-5 Nano |\n| Action | 调用选定的 MCP 工具 | 工具执行器 |\n| Observation | 接收工具返回结果 | 智能体 |\n| Response | 基于观察结果生成自然语言回复 | GPT-5 Nano |\n\n## 会话记忆系统\n\n### 6.1 InMemorySaver 检查点器\n\n```python\ncheckpointer = InMemorySaver() # 内存会话检查点\n\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n资料来源：[main.py:53-67](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 6.2 线程管理机制\n\n| 参数 | 说明 | 用途 |\n|------|------|------|\n| thread_id | 线程标识符 | 区分不同会话 |\n| configurable | 可配置参数容器 | 传递线程 ID |\n| messages | 消息历史 | 维护对话上下文 |\n\n### 6.3 记忆持久化流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as ReAct Agent\n participant Checkpointer as InMemorySaver\n participant LLM as GPT-5 Nano\n \n User->>Agent: 发送问题\n Agent->>Checkpointer: 加载历史消息\n Checkpointer-->>Agent: 返回对话历史\n Agent->>LLM: 发送完整上下文\n LLM-->>Agent: 生成响应\n Agent->>Checkpointer: 保存新消息\n Agent-->>User: 返回响应\n```\n\n## 异步编程模式\n\n### 7.1 异步入口点\n\n```python\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[main.py:92-94](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 7.2 异步调用模式\n\n| 操作 | 异步关键字 | 说明 |\n|------|-----------|------|\n| MCP 客户端初始化 | `await client` | 连接多个 MCP 服务器 |\n| 获取工具 | `await client.get_tools()` | 异步获取可用工具列表 |\n| 智能体调用 | `await agent.ainvoke()` | 异步执行智能体推理 |\n\n### 7.3 事件循环管理\n\n```mermaid\ngraph TD\n A[asyncio.run] --> B[创建事件循环]\n B --> C[执行 main 协程]\n C --> D[MCP 客户端连接]\n D --> E[工具初始化]\n E --> F[ReAct 智能体运行]\n F --> G[用户交互循环]\n G --> F\n```\n\n## 工具集成与自主选择\n\n### 8.1 工具获取\n\n```python\ntools = await client.get_tools() # 获取所有 MCP 服务器工具\n```\n\n资料来源：[main.py:53](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 8.2 自主工具选择逻辑\n\n| 用户查询类型 | 智能体决策 | 调用服务器 | 返回内容 |\n|-------------|-----------|-----------|---------|\n| 代码/库文档问题 | \"需要文档\" | Context7 | LLM 优化文档 |\n| 艺术/博物馆查询 | \"需要藏品数据\" | MetMuseum | 艺术品元数据/图片 |\n\n### 8.3 工具选择流程图\n\n```mermaid\ngraph TD\n A[用户自然语言查询] --> B{GPT-5 Nano 意图分析}\n B -->|代码/框架文档| C[Context7 工具]\n B -->|艺术品/博物馆| D[MetMuseum 工具]\n B -->|其他| E[无工具调用]\n C --> F[返回文档内容]\n D --> G[返回艺术品数据]\n E --> H[直接生成回复]\n```\n\n## 系统消息配置\n\n### 9.1 智能体角色定义\n\n```python\n{\"role\": \"system\", \"content\": \"You are a smart, useful agent with tools to access code library documentation and the Met Museum collection.\"}\n```\n\n资料来源：[main.py:72-73](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 9.2 消息类型\n\n| 消息角色 | 来源 | 内容示例 |\n|---------|------|---------|\n| system | 系统定义 | 智能体角色设定 |\n| user | 用户输入 | 用户的自然语言问题 |\n| assistant | 智能体生成 | 最终响应内容 |\n\n## 依赖安装\n\n### 10.1 Python 依赖\n\n```bash\npip install langchain-mcp-adapters langgraph langchain-openai\n```\n\n### 10.2 Node.js 环境\n\n```bash\nnpm install -g npx\n```\n\n### 10.3 环境变量配置\n\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 版本 | 关键作用 |\n|------|---------|------|---------|\n| 运行时 | Python 3.10+ | 3.10+ | 主要开发语言 |\n| 智能体框架 | LangGraph ReAct | 最新 | 推理与工具调用编排 |\n| 大语言模型 | GPT-5 Nano | - | 自然语言理解和生成 |\n| MCP 客户端 | MultiServerMCPClient | 最新 | 多服务器连接管理 |\n| 会话持久化 | InMemorySaver | 最新 | 对话历史记忆 |\n| 异步框架 | asyncio | 标准库 | 非阻塞 I/O 操作 |\n| 文档服务器 | Context7 | HTTP | 库文档查询 |\n| 博物馆服务器 | MetMuseum-MCP | STDIO | 艺术品数据查询 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md), [main.py:1-7](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目概览](#page-1), [LangGraph ReAct代理实现](#page-4), [MultiServerMCPClient配置](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n \n\n# 系统架构设计\n\n## 概述\n\nmcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器 AI 代理系统，旨在为用户提供统一的接口来访问多个外部服务。该系统利用 LangGraph ReAct 架构实现自主工具选择，并支持 STDIO 和 HTTP 两种传输协议的并发管理。资料来源：[README.md:1]()、[main.py:1-10]()\n\n### 项目定位\n\n该系统被定位为 **\"通用接口\"**，类似于 USB-C 在硬件连接中的作用，能够同时连接多个 MCP 服务器，支持持久化对话记忆，并基于 GPT-5 Nano 模型实现自主工具调用能力。资料来源：[README.md:3]()\n\n### 技术领域\n\n| 领域 | 说明 |\n|------|------|\n| 代理类型 | 多服务器 MCP 代理 |\n| 编程语言 | Python 3.10+ |\n| LLM 模型 | OpenAI GPT-5 Nano |\n| 代理框架 | LangGraph ReAct with 持久化内存 |\n\n## 核心架构组件\n\n### 系统层级结构\n\n```\n┌──────────────────────────────────────────────────────┐\n│ 用户层 (CLI 交互界面) │\n│ \"梵高创作了哪些画作？\" │\n│ \"展示 LangChain 文档\" │\n└───────────────────────┬──────────────────────────────┘\n │\n┌───────────────────────▼──────────────────────────────┐\n│ LangGraph ReAct 代理层 │\n│ • GPT-5 Nano 推理引擎 │\n│ • InMemorySaver 线程级对话记忆 │\n│ • 自主选择调用哪个 MCP 服务器 │\n└──────────┬────────────────────────┬──────────────────┘\n │ │\n HTTP 传输 STDIO 传输\n │ │\n┌──────────▼──────────┐ ┌─────────▼──────────────────┐\n│ Context7 服务器 │ │ MetMuseum-MCP 服务器 │\n│ (远程/云端) │ │ (本地通过 npx 运行) │\n│ │ │ │\n│ 主流框架/库的 LLM │ │ 大都会艺术博物馆 │\n│ 优化文档搜索 │ │ 400,000+ 艺术品 │\n└─────────────────────┘ └─────────────────────────────┘\n```\n\n### 技术栈明细\n\n| 组件类别 | 技术选型 | 版本要求 |\n|----------|----------|----------|\n| 编程语言 | Python | 3.10+ |\n| MCP 客户端 | MultiServerMCPClient (langchain-mcp-adapters) | 最新稳定版 |\n| 代理框架 | LangGraph ReAct | 最新稳定版 |\n| LLM | ChatOpenAI (GPT-5 Nano) | OpenAI API |\n| 对话记忆 | InMemorySaver | LangGraph 内置 |\n| 异步支持 | asyncio | Python 标准库 |\n| MCP 服务器 1 | Context7 | HTTP 流式传输 |\n| MCP 服务器 2 | MetMuseum-MCP | STDIO 本地执行 |\n\n资料来源：[README.md:56-66]()\n\n## 通信传输机制\n\n### HTTP 传输 (Context7)\n\nContext7 服务器通过 `streamable_http` 协议实现远程通信。这种方式适合云端部署的文档服务，具有以下特点：\n\n- **传输协议**：`streamable_http`\n- **端点地址**：`https://mcp.context7.com/mcp`\n- **部署模式**：远程/云端\n- **适用场景**：需要访问大型软件框架文档库的场景\n\n```python\n\"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n}\n```\n\n资料来源：[main.py:21-24]()\n\n### STDIO 传输 (MetMuseum)\n\nMetMuseum MCP 服务器通过标准输入输出（STDIO）协议实现本地通信：\n\n- **传输协议**：`stdio`\n- **执行命令**：`npx -y metmuseum-mcp`\n- **部署模式**：本地通过 Node.js npx 执行\n- **适用场景**：本地艺术品数据查询\n\n```python\n\"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n}\n```\n\n资料来源：[main.py:25-29]()\n\n## 代理工作流程\n\n### 完整请求处理流程\n\n```mermaid\ngraph TD\n A[用户输入查询] --> B{GPT-5 Nano 推理}\n B --> C[\"判断查询类型\"]\n C -->|代码/库文档| D[Context7 HTTP 调用]\n C -->|艺术品/博物馆| E[MetMuseum STDIO 调用]\n D --> F[获取文档数据]\n E --> G[获取艺术品元数据]\n F --> H[结果返回 LLM]\n G --> H\n H --> I[LLM 生成自然语言响应]\n I --> J[InMemorySaver 保存对话]\n J --> K[用户接收响应]\n```\n\n### 工具自主选择机制\n\n代理能够根据用户查询内容自主判断应调用哪个 MCP 服务器：\n\n| 用户查询示例 | 调用服务器 | 返回数据类型 |\n|--------------|------------|--------------|\n| \"LangChain 代理工具是什么？\" | Context7 | LLM 优化文档 |\n| \"展示大都会博物馆的印象派画作\" | MetMuseum | 艺术品元数据及图片 |\n\n资料来源：[README.md:42-51]()\n\n## 核心模块设计\n\n### MCP 客户端模块\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n }\n})\n\ntools = await client.get_tools()\n```\n\n该模块负责同时连接多个 MCP 服务器，并聚合所有可用的工具供代理使用。资料来源：[main.py:13-29]()\n\n### LLM 模型配置\n\n```python\nfrom langchain_openai import ChatOpenAI\n\nopenai_model = ChatOpenAI(\n model=\"gpt-5-nano\",\n)\n```\n\n使用 OpenAI 的 GPT-5 Nano 模型作为推理引擎，该模型负责理解用户意图并进行工具调用决策。资料来源：[main.py:37-39]()\n\n### ReAct 代理创建\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.checkpoint.memory import InMemorySaver\n\ncheckpointer = InMemorySaver()\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer,\n)\n```\n\nReAct 代理结合了推理（Reasoning）和行动（Acting）能力，通过 checkpointer 实现对话记忆持久化。资料来源：[main.py:42-52]()\n\n### 对话记忆系统\n\n```python\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n\nresponse = await agent.ainvoke(\n {\"messages\": query},\n config=config\n)\n```\n\nInMemorySaver 提供了线程级别的对话历史持久化，确保代理在多轮对话中保持上下文理解能力。资料来源：[main.py:72-77]()\n\n## 交互流程设计\n\n### 启动与初始化\n\n1. 配置 MultiServerMCPClient 连接两个 MCP 服务器\n2. 初始化 ChatOpenAI 模型\n3. 获取所有可用工具\n4. 创建 InMemorySaver 检查点\n5. 构建 ReAct 代理实例\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as LangGraph Agent\n participant Client as MCP Client\n participant Context7 as Context7 Server\n participant MetMuseum as MetMuseum Server\n\n User->>Agent: 启动程序\n Client->>Context7: 建立 HTTP 连接\n Client->>MetMuseum: 启动 npx 进程 (STDIO)\n Client->>Agent: 获取工具列表\n Agent->>User: 显示初始介绍\n\n loop 主交互循环\n User->>Agent: 输入问题\n Agent->>Agent: GPT-5 Nano 推理\n Agent->>Client: 调用工具\n Client->>Context7: 查询文档 (可选)\n Client->>MetMuseum: 查询艺术品 (可选)\n Context7-->>Client: 返回文档数据\n MetMuseum-->>Client: 返回艺术品数据\n Client-->>Agent: 工具执行结果\n Agent->>Agent: 生成自然语言响应\n Agent-->>User: 返回最终回答\n end\n```\n\n### 菜单交互模式\n\n系统提供基于菜单的交互方式：\n\n```\nMenu:\n1. Ask the agent a question\n2. Quit\nEnter your choice (1 or 2):\n```\n\n- 选择 \"1\"：进入问答模式，代理接收并处理用户查询\n- 选择 \"2\"：退出程序\n\n资料来源：[main.py:57-85]()\n\n## 数据流设计\n\n### 消息传递机制\n\n```mermaid\ngraph LR\n A[用户消息] --> B[系统消息配置]\n B --> C[消息数组]\n C --> D[agent.ainvoke 调用]\n D --> E[LangGraph 状态机]\n E --> F[工具执行]\n F --> G[结果聚合]\n G --> H[LLM 响应生成]\n H --> I[最终输出]\n```\n\n### 配置参数表\n\n| 参数名称 | 类型 | 说明 | 默认值 |\n|----------|------|------|--------|\n| thread_id | string | 对话线程标识符 | \"conversation_id\" |\n| model | string | LLM 模型名称 | \"gpt-5-nano\" |\n| transport | string | 通信传输协议 | streamable_http / stdio |\n\n资料来源：[main.py:45-47]()\n\n## 系统初始化代码结构\n\n```python\nasync def main():\n \"\"\"主函数：设置并运行具有多个 MCP 服务器访问权限的 AI 代理\"\"\"\n\n # 1. 配置 MCP 服务器\n client = MultiServerMCPClient({...})\n\n # 2. 初始化 OpenAI 语言模型\n openai_model = ChatOpenAI(model=\"gpt-5-nano\")\n\n # 3. 获取所有可用工具\n tools = await client.get_tools()\n\n # 4. 设置对话记忆\n checkpointer = InMemorySaver()\n config = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n\n # 5. 创建 ReAct 代理\n agent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer,\n )\n\n # 6. 发送初始介绍消息\n response = await agent.ainvoke({...}, config=config)\n\n # 7. 主交互循环\n while True:\n choice = input(\"Menu:...\")\n if choice == \"1\":\n query = input(\"> \")\n response = await agent.ainvoke({\"messages\": query}, config=config)\n print(response['messages'][-1].content)\n```\n\n资料来源：[main.py:12-85]()\n\n## 关键设计决策\n\n### 多服务器架构优势\n\n| 优势 | 说明 |\n|------|------|\n| 能力扩展性 | 可通过添加新 MCP 服务器无缝扩展功能 |\n| 协议兼容性 | 同时支持 STDIO 和 HTTP 两种传输协议 |\n| 自主路由 | LLM 自动选择最合适的服务器处理查询 |\n| 持久化记忆 | InMemorySaver 确保多轮对话上下文连贯 |\n\n### 技术选型理由\n\n| 组件 | 选型理由 |\n|------|----------|\n| LangGraph | 提供成熟的 ReAct 代理实现和状态管理 |\n| MultiServerMCPClient | 原生支持多服务器并发连接 |\n| InMemorySaver | 轻量级内存存储，适合演示和小规模部署 |\n| GPT-5 Nano | 成本效益高的推理模型，适合工具调用场景 |\n\n资料来源：[README.md:4-12]()\n\n## 依赖安装指南\n\n### Python 依赖\n\n```bash\npip install langchain-mcp-adapters langgraph langchain-openai\n```\n\n### Node.js 依赖\n\n```bash\nnpm install -g npx\n```\n\n### 环境变量配置\n\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n资料来源：[README.md:30-36]()\n\n## 启动与运行\n\n### 运行命令\n\n```bash\npython main.py\n```\n\n### 执行流程\n\n1. 初始化 MCP 客户端连接\n2. 加载可用的工具\n3. 代理自我介绍\n4. 进入主菜单循环\n5. 处理用户查询并返回结果\n\n资料来源：[main.py:88-91]()\n\n---\n\n\n\n## LangGraph ReAct代理实现\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-3), [持久化对话记忆机制](#page-5), [MultiServerMCPClient配置](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n \n\n# LangGraph ReAct代理实现\n\n## 概述\n\nLangGraph ReAct代理是该项目的核心智能组件，负责协调用户查询、MCP服务器工具调用以及对话记忆管理。该代理基于LangGraph框架的ReAct（Reasoning + Acting）设计模式构建，结合OpenAI GPT-5 Nano模型实现自主工具选择和自然语言响应生成功能。\n\n## 核心架构\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n A[用户 CLI 交互] --> B[LangGraph ReAct Agent]\n B --> C[GPT-5 Nano 模型]\n C --> D{自主工具选择}\n D --> E[Context7 HTTP]\n D --> F[MetMuseum STDIO]\n E --> G[工具执行结果]\n F --> G\n G --> C\n C --> H[自然语言响应]\n H --> I[InMemorySaver 记忆存储]\n I --> B\n```\n\n### 技术栈概览\n\n| 组件 | 技术实现 | 版本要求 |\n|------|----------|----------|\n| 代理框架 | `create_react_agent` | langgraph |\n| 语言模型 | `ChatOpenAI` | langchain-openai |\n| MCP客户端 | `MultiServerMCPClient` | langchain-mcp-adapters |\n| 对话记忆 | `InMemorySaver` | langgraph.checkpoint.memory |\n| 传输协议 | STDIO + streamable_http | 混合模式 |\n\n## 代理初始化流程\n\n### 源码实现解析\n\n代理的初始化过程包含四个关键步骤：\n\n```python\n# 第一步：配置MCP服务器连接\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n }\n})\n```\n\n资料来源：[main.py:33-45]()\n\n```python\n# 第二步：初始化OpenAI语言模型\nopenai_model = ChatOpenAI(model=\"gpt-5-nano\")\n```\n\n资料来源：[main.py:49-50]()\n\n```python\n# 第三步：获取所有MCP服务器工具\ntools = await client.get_tools()\n```\n\n资料来源：[main.py:52]()\n\n```python\n# 第四步：创建ReAct代理\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=InMemorySaver()\n)\n```\n\n资料来源：[main.py:58-62]()\n\n### 初始化参数说明\n\n| 参数 | 类型 | 说明 | 来源配置 |\n|------|------|------|----------|\n| model | ChatOpenAI | 提供推理和响应生成能力 | 必须 |\n| tools | List[BaseTool] | 从MCP服务器获取的工具集合 | 必须 |\n| checkpointer | InMemorySaver | 持久化对话历史记录 | 可选 |\n\n## ReAct执行机制\n\n### 推理与行动循环\n\nLangGraph ReAct代理采用\"推理-行动\"循环模式处理用户查询：\n\n```mermaid\ngraph TD\n A[用户查询输入] --> B[Reasoning: 分析查询意图]\n B --> C{判断是否需要调用工具?}\n C -->|是| D[Action: 选择合适工具]\n D --> E[Execute: 执行工具调用]\n E --> F[Observation: 获取工具返回结果]\n F --> B\n C -->|否| G[Final Response: 直接生成响应]\n```\n\n### 对话上下文管理\n\n代理通过线程ID机制维护多轮对话上下文：\n\n```python\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n\nresponse = await agent.ainvoke(\n {\"messages\": query},\n config=config\n)\n```\n\n资料来源：[main.py:54-60]()\n\n**上下文管理特点：**\n\n- 每个会话拥有唯一thread_id\n- 所有历史消息自动持久化到InMemorySaver\n- 后续查询自动携带完整对话上下文\n\n## MCP服务器集成\n\n### 多服务器连接架构\n\n```mermaid\ngraph LR\n A[ReAct Agent] <-->|统一工具接口| B[MultiServerMCPClient]\n B -->|streamable_http| C[Context7 Server]\n B -->|stdio| D[MetMuseum MCP]\n```\n\n### 服务器配置对比\n\n| 服务器 | 传输协议 | 用途 | 连接参数 |\n|--------|----------|------|----------|\n| Context7 | HTTP | 代码库文档检索 | URL: https://mcp.context7.com/mcp |\n| MetMuseum | STDIO | 博物馆藏品查询 | command: npx, args: metmuseum-mcp |\n\n### 工具自动路由\n\n代理根据查询内容自动选择目标服务器：\n\n```\n用户: \"LangChain代理相关文档\" → Context7服务器\n用户: \"梵高的绘画作品\" → MetMuseum服务器\n```\n\n## 对话流程实现\n\n### 主交互循环\n\n```python\nwhile True:\n choice = input(\"\"\"\nMenu:\n1. Ask the agent a question\n2. Quit\nEnter your choice (1 or 2): \"\"\")\n\n if choice == \"1\":\n query = input(\"> \")\n response = await agent.ainvoke(\n {\"messages\": query},\n config=config\n )\n print(response['messages'][-1].content)\n else:\n break\n```\n\n资料来源：[main.py:71-84]()\n\n### 异步执行模式\n\n整个应用采用异步架构，通过asyncio事件循环驱动：\n\n```python\nasync def main():\n # 异步初始化和代理执行\n ...\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[main.py:24-89]()\n\n## 代理系统提示\n\n代理初始化时注入系统级提示词，定义其角色定位：\n\n```python\n{\"role\": \"system\", \"content\": \"You are a smart, useful agent with tools to access code library documentation and the Met Museum collection.\"}\n```\n\n资料来源：[main.py:67]()\n\n## 关键特性总结\n\n### 核心能力矩阵\n\n| 特性 | 实现方式 | 技术依赖 |\n|------|----------|----------|\n| 多服务器并发 | MultiServerMCPClient | langchain-mcp-adapters |\n| 持久化记忆 | InMemorySaver | langgraph.checkpoint.memory |\n| 自主工具选择 | LLM推理 | GPT-5 Nano |\n| 对话连续性 | thread_id配置 | LangGraph checkpointer |\n| 异步通信 | asyncio | Python标准库 |\n\n### 执行流程总览\n\n```mermaid\ngraph LR\n A[CLI Input] --> B[ReAct Agent]\n B --> C[LLM Reasoning]\n C --> D[Tool Selection]\n D --> E[MCP Tool Call]\n E --> F[Result Aggregation]\n F --> G[LLM Response]\n G --> H[Memory Update]\n H --> I[User Output]\n```\n\n## 扩展与定制\n\n### 修改系统提示\n\n如需自定义代理行为，修改main.py中的system message内容：\n\n```python\n{\"role\": \"system\", \"content\": \"自定义代理描述\"}\n```\n\n### 添加新MCP服务器\n\n在MultiServerMCPClient配置中追加新的服务器条目：\n\n```python\nclient = MultiServerMCPClient({\n \"context7\": {...},\n \"met-museum\": {...},\n \"new-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"new-mcp-package\"],\n \"transport\": \"stdio\",\n }\n})\n```\n\n### 更换语言模型\n\n调整ChatOpenAI初始化参数以使用其他模型：\n\n```python\nopenai_model = ChatOpenAI(model=\"gpt-4\")\n\n---\n\n\n\n## 持久化对话记忆机制\n\n### 相关页面\n\n相关主题：[LangGraph ReAct代理实现](#page-4), [运行与交互指南](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n \n\n# 持久化对话记忆机制\n\n## 概述\n\n持久化对话记忆机制是 mcp-ai-agent 项目中的核心功能模块，负责在多轮对话场景下维护用户与智能体之间的完整交流上下文。该机制基于 LangGraph 框架的 Checkpointer 实现，通过线程（Thread）隔离不同会话，确保每次对话交互都能回溯历史消息并进行连贯推理。\n\n## 核心组件\n\n### 1. InMemorySaver\n\n`InMemorySaver` 是 LangGraph 框架提供的内存检查点保存器，负责存储对话状态快照。\n\n| 属性 | 说明 |\n|------|------|\n| 类型 | 内存存储 |\n| 来源 | `langgraph.checkpoint.memory` |\n| 用途 | 持久化对话历史记录 |\n| 生命周期 | 进程运行期间有效 |\n\n```python\nfrom langgraph.checkpoint.memory import InMemorySaver\n\ncheckpointer = InMemorySaver()\n```\n\n资料来源：[main.py:28]()\n\n### 2. 会话配置（Config）\n\n会话配置定义了对话线程的唯一标识符，是实现多会话隔离的关键参数。\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `thread_id` | string | \"conversation_id\" | 会话线程唯一标识 |\n\n```python\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n资料来源：[main.py:67]()\n\n### 3. ReAct Agent 集成\n\n检查点保存器通过 `create_react_agent` 函数注入到智能体中，使智能体具备状态持久化能力。\n\n```python\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer\n)\n```\n\n资料来源：[main.py:70-74]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[用户提问] --> B[构建查询消息]\n B --> C[调用 agent.ainvoke]\n C --> D{检查 thread_id}\n D -->|新会话| E[创建新线程]\n D -->|已有会话| F[加载历史状态]\n E --> G[执行推理与工具调用]\n F --> G\n G --> H[生成响应]\n H --> I[保存状态到 InMemorySaver]\n I --> J[返回响应给用户]\n J --> K[等待下一轮交互]\n K --> A\n```\n\n## 状态持久化流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as ReAct Agent\n participant C as InMemorySaver\n participant M as LLM\n\n U->>A: 第一轮: 查询消息\n A->>C: 保存状态快照\n C-->>A: 确认保存\n A-->>U: 返回响应\n\n U->>A: 第二轮: 新查询\n A->>C: 加载 thread_id 对应状态\n C-->>A: 返回历史消息\n A->>M: 发送完整上下文\n M-->>A: 生成响应\n A->>C: 更新状态快照\n A-->>U: 返回响应\n```\n\n## 核心代码解析\n\n### 主函数入口\n\n```python\nasync def main():\n # 初始化 MCP 服务器客户端\n client = MultiServerMCPClient({...})\n\n # 初始化 LLM 模型\n openai_model = ChatOpenAI(model=\"gpt-5-nano\")\n\n # 获取 MCP 服务器提供的工具\n tools = await client.get_tools()\n\n # 创建内存检查点保存器\n checkpointer = InMemorySaver()\n\n # 配置会话参数\n config = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n\n # 创建带持久化功能的 ReAct Agent\n agent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer\n )\n```\n\n资料来源：[main.py:31-75]()\n\n### 智能体调用\n\n```python\n # 发送用户查询，附带会话配置\n response = await agent.ainvoke(\n {\"messages\": query},\n config=config\n )\n\n # 输出智能体响应\n print(response['messages'][-1].content)\n```\n\n资料来源：[main.py:88-94]()\n\n## 会话状态管理\n\n```mermaid\ngraph LR\n subgraph 状态结构\n S1[消息列表] --> S2[System 消息]\n S1 --> S3[User 消息]\n S1 --> S4[Assistant 消息]\n S1 --> S5[Tool 调用记录]\n end\n\n subgraph 持久化存储\n P1[InMemorySaver]\n P1 -.->|存储| S1\n P1 -.->|检索| S2\n P1 -.->|检索| S3\n P1 -.->|检索| S4\n P1 -.->|检索| S5\n end\n```\n\n## 消息格式\n\n对话中的消息采用标准角色格式存储：\n\n| 角色 | 说明 | 示例 |\n|------|------|------|\n| `system` | 系统级指令 | 定义智能体角色定位 |\n| `user` | 用户输入 | 用户提出的问题 |\n| `assistant` | 智能体响应 | 包含文本和工具调用 |\n| `tool` | 工具执行结果 | MCP 服务器返回的数据 |\n\n```python\n{\"messages\": [\n {\"role\": \"system\", \"content\": \"You are a smart, useful agent...\"},\n {\"role\": \"user\", \"content\": \"用户问题内容\"},\n]}\n```\n\n资料来源：[main.py:77-82]()\n\n## 初始化流程\n\n智能体启动时会执行自我介绍，让用户了解其能力范围：\n\n```python\nresponse = await agent.ainvoke(\n {\"messages\": [\n {\"role\": \"system\", \"content\": \"You are a smart, useful agent with tools to access code library documentation and the Met Museum collection.\"},\n {\"role\": \"user\", \"content\": \"Give a brief introduction of what you do and the tools you can access.\"},\n ]},\n config=config\n)\nprint(response['messages'][-1].content)\n```\n\n资料来源：[main.py:77-86]()\n\n## 应用场景\n\n### 单会话连续对话\n\n用户在同一会话中提出多个相关问题，智能体能够理解上下文关联：\n\n```\n用户: \"LangGraph 的工具调用是什么？\"\n智能体: [调用 Context7 获取文档]\n\n用户: \"能给我一个代码示例吗？\"\n智能体: [基于上一轮上下文生成示例]\n```\n\n### 上下文关联推理\n\n记忆机制使智能体能够：\n\n- 记住用户之前提到的技术栈或偏好\n- 基于历史查询提供个性化响应\n- 在多轮调试场景中理解问题演进过程\n\n## 限制与注意事项\n\n| 限制项 | 说明 |\n|--------|------|\n| 内存依赖 | 进程重启后记忆丢失 |\n| 并发限制 | 多进程需要外部存储后端 |\n| 线程隔离 | 不同 `thread_id` 完全独立 |\n\n如需生产环境持久化，应替换为 `PostgresSaver` 或 `RedisSaver` 等外部存储适配器。\n\n## 依赖关系\n\n```mermaid\ngraph TD\n A[main.py] --> B[langgraph.checkpoint.memory]\n A --> C[langgraph.prebuilt.create_react_agent]\n A --> D[langchain_openai.ChatOpenAI]\n B --> E[InMemorySaver 类]\n C --> F[ReAct Agent 工厂函数]\n```\n\n## 扩展建议\n\n如需增强持久化能力，可考虑以下方案：\n\n1. **数据库持久化**：集成 PostgreSQL 或 SQLite\n2. **分布式存储**：使用 Redis 实现跨进程共享\n3. **会话管理**：实现会话超时自动清理机制\n4. **状态序列化**：支持对话历史导出与恢复\n\n---\n\n\n\n## MultiServerMCPClient配置\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-3), [集成MCP服务器详解](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n \n\n# MultiServerMCPClient配置\n\n## 概述\n\nMultiServerMCPClient 是 langchain-mcp-adapters 库提供的核心客户端类，用于同时连接多个 MCP（Model Context Protocol）服务器。在本项目中，该客户端被配置为同时管理 HTTP 和 STDIO 两种传输协议的 MCP 服务器连接，使 LangGraph ReAct Agent 能够自主选择并调用来自不同域的工具。\n\n**核心作用：**\n\n- 统一管理多个 MCP 服务器的连接生命周期\n- 支持异构传输协议（HTTP/STDIO）的并发连接\n- 聚合来自不同服务器的可用工具，供 Agent 调用\n\n资料来源：[main.py:12]()\n\n## 架构设计\n\n### 多服务器连接架构\n\n```mermaid\ngraph TD\n A[\"LangGraph ReAct Agent\"] --> B[\"MultiServerMCPClient\"]\n B --> C[\"Context7 Server
(HTTP)\"]\n B --> D[\"MetMuseum Server
(STDIO)\"]\n C --> E[\"远程云端
文档搜索服务\"]\n D --> F[\"本地 npx
博物馆数据服务\"]\n \n style A fill:#e1f5fe\n style B fill:#fff3e0\n```\n\n### 传输协议对比\n\n| 传输协议 | 实现方式 | 适用场景 | 延迟特性 |\n|---------|---------|---------|---------|\n| **streamable_http** | HTTP 长连接 | 远程云服务 | 中等延迟 |\n| **stdio** | 标准输入输出 | 本地 Node.js 服务 | 低延迟 |\n\n资料来源：[main.py:38-47]()\n\n## 配置参数详解\n\n### MultiServerMCPClient 构造函数参数\n\n```python\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n }\n})\n```\n\n### 服务器配置结构\n\n| 参数名 | 类型 | 说明 | 必填 |\n|-------|------|------|-----|\n| `command` | string | 进程启动命令 | STDIO 传输时必填 |\n| `args` | list[string] | 命令行参数列表 | STDIO 传输时必填 |\n| `url` | string | 服务器端点 URL | HTTP 传输时必填 |\n| `transport` | string | 传输协议类型 | 是 |\n\n### Context7 服务器配置\n\n```python\n\"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\", # 服务器端点\n \"transport\": \"streamable_http\", # HTTP 流式传输\n}\n```\n\n**配置说明：**\n\n- 该服务器提供 LLM 优化的软件框架文档搜索能力\n- 传输协议使用 `streamable_http`，适合与远程云端服务通信\n- 无需本地进程管理，服务端自动处理连接\n\n### MetMuseum 服务器配置\n\n```python\n\"met-museum\": {\n \"command\": \"npx\", # Node.js 包运行器\n \"args\": [\"-y\", \"metmuseum-mcp\"], # 自动安装并运行\n \"transport\": \"stdio\", # 标准输入输出传输\n}\n```\n\n**配置说明：**\n\n- 使用 npx 自动安装并运行 `metmuseum-mcp` 包\n- STDIO 传输通过标准输入输出与本地 Node.js 进程通信\n- 适合需要本地执行环境的工具服务\n\n## 工具获取与使用\n\n### 获取所有工具\n\n```python\ntools = await client.get_tools()\n```\n\n该方法异步获取所有已配置 MCP 服务器提供的工具集合，返回的 `tools` 列表包含来自 Context7 和 MetMuseum 两个服务器的所有可用工具。\n\n### 工具聚合机制\n\n```mermaid\ngraph LR\n A[\"Context7 Tools\"] --> C[\"统一 Tools 列表\"]\n B[\"MetMuseum Tools\"] --> C\n C --> D[\"ReAct Agent\"]\n```\n\n## 与 LangGraph Agent 集成\n\n### 完整集成流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as LangGraph ReAct\n participant Client as MultiServerMCPClient\n participant Servers as MCP Servers\n\n User->>Agent: 发送查询\n Agent->>Client: await client.get_tools()\n Client->>Servers: 获取工具定义\n Servers-->>Client: 返回工具列表\n Client-->>Agent: 聚合工具集\n Agent->>Servers: 调用选中工具\n Servers-->>Agent: 返回结果\n Agent-->>User: 自然语言响应\n```\n\n### Agent 创建代码\n\n```python\n# 初始化 OpenAI 模型\nopenai_model = ChatOpenAI(model=\"gpt-5-nano\")\n\n# 获取工具\ntools = await client.get_tools()\n\n# 创建 ReAct Agent\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=InMemorySaver()\n)\n```\n\n## 异步编程模式\n\n### main 函数异步设计\n\n```python\nasync def main():\n client = MultiServerMCPClient({...})\n tools = await client.get_tools()\n agent = create_react_agent(model, tools, checkpointer)\n # 异步调用\n response = await agent.ainvoke({\"messages\": query}, config=config)\n```\n\n### 事件循环执行\n\n```python\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n**要点说明：**\n\n- 所有涉及 MCP 客户端的操作必须使用 `async/await` 模式\n- 顶层入口通过 `asyncio.run()` 启动事件循环\n- Agent 调用同样采用异步方式 `await agent.ainvoke()`\n\n## 生命周期管理\n\n### 连接初始化\n\n| 阶段 | 操作 | 说明 |\n|-----|------|-----|\n| 1 | 创建 MultiServerMCPClient 实例 | 配置服务器参数 |\n| 2 | 获取工具集 | `await client.get_tools()` |\n| 3 | 创建 Agent | 绑定模型和工具 |\n| 4 | 启动交互循环 | 处理用户查询 |\n\n### 资源清理\n\nMultiServerMCPClient 在上下文管理器退出或程序终止时自动关闭所有服务器连接。\n\n## 配置最佳实践\n\n### 开发环境配置建议\n\n| 场景 | 推荐配置 |\n|-----|---------|\n| 本地开发 | 使用 STDIO 传输，便于调试 |\n| 生产部署 | 优先使用 HTTP 传输，稳定性更高 |\n| 混合场景 | 按服务特性选择传输协议 |\n\n### 扩展新服务器\n\n添加新 MCP 服务器只需在配置字典中增加条目：\n\n```python\nclient = MultiServerMCPClient({\n \"context7\": {...},\n \"met-museum\": {...},\n \"新服务器名称\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"新服务包名\"],\n \"transport\": \"stdio\",\n }\n})\n```\n\nAgent 会自动发现并聚合新增服务器的工具，无需修改 Agent 创建代码。\n\n## 依赖项\n\n| 依赖包 | 版本要求 | 用途 |\n|-------|---------|------|\n| langchain-mcp-adapters | 最新版 | MultiServerMCPClient |\n| langgraph | 最新版 | ReAct Agent 框架 |\n| langchain-openai | 最新版 | OpenAI 模型集成 |\n| asyncio | Python 3.10+ 内置 | 异步编程支持 |\n\n资料来源：[main.py:1-11]()\n\n---\n\n\n\n## 集成MCP服务器详解\n\n### 相关页面\n\n相关主题：[MultiServerMCPClient配置](#page-6), [扩展与定制指南](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n \n\n# 集成MCP服务器详解\n\n## 概述\n\n`集成MCP服务器详解`是本项目的核心功能模块，展示了如何构建一个**多服务器MCP（Model Context Protocol）客户端代理**系统。该系统能够同时连接多个不同传输协议的MCP服务器，实现跨域工具调用与智能工具选择能力。\n\n本项目通过`MultiServerMCPClient`同时管理HTTP和STDIO两种传输协议的MCP服务器，结合LangGraph ReAct Agent架构和OpenAI GPT-5 Nano模型，构建了一个具有持久化会话记忆的多功能AI代理。\n\n资料来源：[main.py:1-20](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L1-L20)\n\n---\n\n## 架构设计\n\n### 系统整体架构\n\n本项目采用分层架构设计，从上至下依次为：用户交互层、Agent推理层、MCP客户端层和服务器连接层。\n\n```mermaid\ngraph TD\n A[\"用户 CLI 交互层\"] --> B[\"LangGraph ReAct Agent\"]\n B --> C[\"MultiServerMCPClient 客户端\"]\n C --> D1[\"Context7 Server
HTTP 传输\"]\n C --> D2[\"MetMuseum-MCP Server
STDIO 传输\"]\n E[\"OpenAI GPT-5 Nano\"] --> B\n F[\"InMemorySaver 记忆系统\"] --> B\n```\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n### 核心组件职责\n\n| 组件层 | 组件名称 | 职责描述 |\n|--------|----------|----------|\n| 用户层 | CLI交互界面 | 提供菜单选择和问题输入功能 |\n| 推理层 | LangGraph ReAct Agent | 负责推理决策和工具调用编排 |\n| 模型层 | ChatOpenAI (GPT-5 Nano) | 提供LLM推理能力 |\n| 记忆层 | InMemorySaver | 维护会话历史和线程状态 |\n| 客户端层 | MultiServerMCPClient | 管理多个MCP服务器连接 |\n| 服务器层 | Context7 / MetMuseum | 提供具体业务工具 |\n\n资料来源：[main.py:1-20](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L1-L20)\n\n---\n\n## MCP服务器配置详解\n\n### 配置文件结构\n\n`MultiServerMCPClient`接受一个字典参数，键为服务器标识名，值为服务器配置对象。配置对象必须包含`transport`字段来指定传输类型。\n\n```python\nclient = MultiServerMCPClient({\n \"服务器标识名\": {\n \"transport\": \"传输类型\",\n # 其他配置项...\n }\n})\n```\n\n资料来源：[main.py:22-40](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L22-L40)\n\n### Context7服务器配置（HTTP传输）\n\nContext7是一个远程云端MCP服务器，提供主流软件框架和库的文档搜索功能。\n\n| 参数 | 值 | 说明 |\n|------|-----|------|\n| 传输协议 | `streamable_http` | 支持流式HTTP通信 |\n| 端点URL | `https://mcp.context7.com/mcp` | 服务器远程地址 |\n| 连接类型 | 远程/云端 | 无需本地安装 |\n\n```python\n\"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n}\n```\n\n资料来源：[main.py:23-26](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L23-L26)\n\n### MetMuseum服务器配置（STDIO传输）\n\nMetMuseum是一个本地MCP服务器，通过npx执行，提供大都会艺术博物馆的藏品数据访问。\n\n| 参数 | 值 | 说明 |\n|------|-----|------|\n| 传输协议 | `stdio` | 通过标准输入输出通信 |\n| 执行命令 | `npx` | Node.js包执行器 |\n| 启动参数 | `[\"-y\", \"metmuseum-mcp\"]` | 自动确认安装并运行 |\n| 连接类型 | 本地/STDIO | 需Node.js环境支持 |\n\n```python\n\"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n}\n```\n\n资料来源：[main.py:28-32](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L28-L32)\n\n### 传输协议对比\n\n| 特性 | HTTP传输（streamable_http） | STDIO传输 |\n|------|----------------------------|----------|\n| 通信方式 | 基于HTTP的请求响应/流式 | 标准输入输出管道 |\n| 部署模式 | 远程云服务 | 本地进程 |\n| 依赖 | 网络连接 | Node.js + npm |\n| 延迟 | 依赖网络质量 | 本地进程，延迟低 |\n| 适用场景 | 公共服务、文档查询 | 本地工具、数据访问 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n---\n\n## Agent构建流程\n\n### 初始化步骤总览\n\nAgent的构建分为五个主要步骤：导入依赖、配置MCP客户端、初始化LLM、获取工具集、创建ReAct代理。\n\n```mermaid\ngraph LR\n A[\"导入依赖\"] --> B[\"配置MultiServerMCPClient\"]\n B --> C[\"初始化ChatOpenAI模型\"]\n C --> D[\"获取所有工具 await client.get_tools()\"]\n D --> E[\"配置InMemorySaver\"]\n E --> F[\"创建create_react_agent\"]\n```\n\n资料来源：[main.py:44-70](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L44-L70)\n\n### 第一步：导入依赖\n\n```python\nimport asyncio\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.checkpoint.memory import InMemorySaver\nfrom langchain_openai import ChatOpenAI\n```\n\n资料来源：[main.py:1-6](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L1-L6)\n\n| 导入模块 | 来源库 | 用途 |\n|----------|--------|------|\n| `MultiServerMCPClient` | langchain-mcp-adapters | 多服务器MCP客户端 |\n| `create_react_agent` | langgraph.prebuilt | 创建预置ReAct代理 |\n| `InMemorySaver` | langgraph.checkpoint.memory | 内存会话持久化 |\n| `ChatOpenAI` | langchain-openai | OpenAI聊天模型封装 |\n\n### 第二步：配置OpenAI模型\n\n```python\nopenai_model = ChatOpenAI(\n model=\"gpt-5-nano\",\n)\n```\n\n| 参数 | 值 | 说明 |\n|------|-----|------|\n| model | `gpt-5-nano` | 使用OpenAI的GPT-5 Nano模型 |\n| 默认端点 | OpenAI API | 需设置OPENAI_API_KEY环境变量 |\n\n资料来源：[main.py:46-48](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L46-L48)\n\n### 第三步：获取MCP工具\n\n```python\ntools = await client.get_tools()\n```\n\n`get_tools()`方法会异步获取所有已配置MCP服务器提供的工具集合，这些工具将作为ReAct Agent的可调用资源。\n\n资料来源：[main.py:50](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L50)\n\n### 第四步：配置会话记忆系统\n\n```python\ncheckpointer = InMemorySaver()\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n| 参数 | 配置键 | 值 | 说明 |\n|------|--------|-----|------|\n| checkpointer | - | InMemorySaver实例 | 内存会话检查点 |\n| config | configurable.thread_id | \"conversation_id\" | 会话线程标识 |\n\n资料来源：[main.py:52-55](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L52-L55)\n\n### 第五步：创建ReAct Agent\n\n```python\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer\n)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| model | ChatOpenAI | LLM推理引擎 |\n| tools | List[BaseTool] | MCP服务器工具集 |\n| checkpointer | BaseCheckpointSaver | 会话记忆持久化 |\n\n资料来源：[main.py:57-61](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L57-L61)\n\n---\n\n## 自主工具选择机制\n\n### 工具选择工作流\n\nReAct Agent的核心能力之一是根据用户问题自主选择合适的MCP服务器和工具。\n\n```mermaid\ngraph TD\n A[\"用户问题\"] --> B{\"LLM推理判断\"}\n B -->|代码/文档相关| C[\"调用Context7工具\"]\n B -->|艺术/博物馆相关| D[\"调用MetMuseum工具\"]\n C --> E[\"返回文档数据\"]\n D --> F[\"返回艺术品数据\"]\n E --> G[\"LLM生成自然语言响应\"]\n F --> G\n G --> H[\"用户收到响应\"]\n```\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n### 工具选择示例\n\n| 用户问题 | 调用服务器 | 返回内容 |\n|----------|-----------|----------|\n| \"LangGraph工具是什么？\" | Context7 | 框架文档内容 |\n| \"展示莫奈的画作\" | MetMuseum | 艺术品元数据和图片 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n---\n\n## 会话管理机制\n\n### 线程化会话模型\n\n项目采用基于thread_id的线程化会话管理，每个会话拥有独立的上下文记忆。\n\n```mermaid\ngraph TD\n A[\"Session 1
thread_id=conversation_1\"] --> B[\"消息历史 1\"]\n A --> C[\"工具调用历史 1\"]\n D[\"Session 2
thread_id=conversation_2\"] --> E[\"消息历史 2\"]\n D --> F[\"工具调用历史 2\"]\n```\n\n资料来源：[main.py:52-55](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L52-L55)\n\n### 配置参数详解\n\n```python\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n| 配置层级 | 键名 | 值类型 | 说明 |\n|----------|------|--------|------|\n| configurable | thread_id | string | 会话唯一标识符 |\n\n在Agent调用时传入config参数，确保同一thread_id的所有交互共享会话记忆：\n\n```python\nresponse = await agent.ainvoke(\n {\"messages\": query},\n config=config\n)\n```\n\n资料来源：[main.py:92-96](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L92-L96)\n\n---\n\n## 主交互流程\n\n### 程序执行流程图\n\n```mermaid\nflowchart TD\n A[\"启动程序\"] --> B[\"初始化MCP客户端\"]\n B --> C[\"获取所有工具\"]\n C --> D[\"创建ReAct Agent\"]\n D --> E[\"发送初始介绍请求\"]\n E --> F{\"用户选择\"}\n F -->|\"1. 提问\"| G[\"获取用户问题\"]\n G --> H[\"Agent推理并调用工具\"]\n H --> I[\"返回响应给用户\"]\n I --> F\n F -->|\"2. 退出\"| J[\"打印 Goodbye!\"]\n J --> K[\"程序结束\"]\n```\n\n资料来源：[main.py:63-110](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L63-L110)\n\n### 主函数异步设计\n\n```python\nasync def main():\n # 初始化和Agent创建\n client = MultiServerMCPClient({...})\n openai_model = ChatOpenAI(model=\"gpt-5-nano\")\n tools = await client.get_tools()\n checkpointer = InMemorySaver()\n agent = create_react_agent(model=openai_model, tools=tools, checkpointer=checkpointer)\n \n # 初始介绍\n response = await agent.ainvoke({...}, config=config)\n print(response['messages'][-1].content)\n \n # 交互循环\n while True:\n choice = input(\"Menu: 1. Ask 2. Quit: \")\n if choice == \"1\":\n query = input(\"> \")\n response = await agent.ainvoke({\"messages\": query}, config=config)\n print(response['messages'][-1].content)\n else:\n break\n```\n\n资料来源：[main.py:15-110](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L15-L110)\n\n---\n\n## 系统消息配置\n\n### Agent角色定义\n\n通过系统消息（System Message）定义Agent的角色定位和行为规范：\n\n```python\n{\"role\": \"system\", \"content\": \"You are a smart, useful agent with tools to access code library documentation and the Met Museum collection.\"}\n```\n\n| 字段 | 值 | 说明 |\n|------|-----|------|\n| role | \"system\" | 系统角色消息 |\n| content | Agent角色描述 | 声明Agent能力范围 |\n\n资料来源：[main.py:68-71](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L68-L71)\n\n---\n\n## 运行环境要求\n\n### 依赖项\n\n| 依赖包 | 版本要求 | 说明 |\n|--------|----------|------|\n| Python | 3.10+ | 主程序运行环境 |\n| langchain-mcp-adapters | 最新版 | MCP客户端适配器 |\n| langgraph | 最新版 | Agent框架 |\n| langchain-openai | 最新版 | OpenAI模型集成 |\n\n```bash\npip install langchain-mcp-adapters langgraph langchain-openai\n```\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| OPENAI_API_KEY | 是 | OpenAI API访问密钥 |\n\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n### 额外要求\n\n| 组件 | 用途 | 安装命令 |\n|------|------|----------|\n| npm | 运行MetMuseum STDIO服务器 | `npm install -g npx` |\n| npx | 包执行器 | 随npm自动安装 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n---\n\n## 执行方式\n\n### 运行程序\n\n```bash\npython main.py\n```\n\n### 交互示例\n\n```\nAgent introduces itself and available tools...\n\nMenu:\n1. Ask the agent a question\n2. Quit\nEnter your choice (1 or 2): 1\n\nYour question\n> What LangGraph tools are available for building agents?\n→ Agent queries Context7 → Returns documentation\n\n> Show me Impressionist paintings from the Met Museum\n→ Agent queries MetMuseum → Returns artwork data\n```\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n---\n\n## 技术亮点总结\n\n| 技术特性 | 实现方式 | 优势 |\n|----------|----------|------|\n| 多传输协议支持 | HTTP + STDIO | 灵活接入远程和本地服务 |\n| 自主工具选择 | LLM推理判断 | 无需手动指定工具 |\n| 持久化会话记忆 | InMemorySaver + thread_id | 跨轮次上下文保持 |\n| 异步架构 | asyncio + await | 高效并发处理 |\n| ReAct推理模式 | LangGraph预置Agent | 可靠的工具调用推理 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n---\n\n\n\n## 安装与配置指南\n\n### 相关页面\n\n相关主题：[运行与交互指南](#page-9), [扩展与定制指南](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n \n\n# 安装与配置指南\n\n## 概述\n\n本项目是一个基于 Model Context Protocol (MCP) 的多服务器 AI Agent 实现，通过 LangGraph ReAct 架构连接多个 MCP 服务器，并利用 OpenAI GPT-5 Nano 模型进行推理与响应生成。安装与配置指南旨在帮助开发者完整搭建运行环境，包括依赖安装、环境变量配置、多服务器连接设置以及运行验证等关键步骤。\n\n本指南覆盖的范围包括：系统环境要求、Python 依赖安装、Node.js 环境准备、API 密钥配置、MCP 服务器连接配置以及运行测试。通过本指南，开发者可以在本地环境成功部署并运行该多服务器 MCP Agent。\n\n## 系统环境要求\n\n### 硬件与操作系统\n\n| 项目 | 最低要求 | 推荐配置 |\n|------|----------|----------|\n| 操作系统 | macOS / Linux / Windows | macOS / Linux |\n| 内存 | 4GB RAM | 8GB RAM |\n| 存储空间 | 500MB 可用空间 | 1GB 可用空间 |\n| 网络 | 互联网连接 | 稳定的互联网连接 |\n\n### 软件依赖\n\n| 组件 | 版本要求 | 说明 | 资料来源 |\n|------|----------|------|----------|\n| Python | 3.10+ | 主要运行环境 | README.md |\n| Node.js | 14.0+ | npx 包管理器需要 | README.md |\n| pip | 最新版本 | Python 包管理器 | - |\n\n## 安装步骤\n\n### 第一步：安装 Python 依赖\n\n本项目依赖三个核心 Python 包，分别负责 MCP 客户端、LangGraph Agent 框架和 OpenAI 模型集成。执行以下命令完成依赖安装：\n\n```bash\npip install langchain-mcp-adapters langgraph langchain-openai\n```\n\n安装说明如下：\n\n| 包名 | 用途 | 说明 |\n|------|------|------|\n| langchain-mcp-adapters | MCP 客户端 | 提供 MultiServerMCPClient，支持多服务器连接 |\n| langgraph | Agent 框架 | 提供 create_react_agent 创建 ReAct 风格 Agent |\n| langchain-openai | OpenAI 集成 | 提供 ChatOpenAI 模型接口 |\n\n### 第二步：安装 Node.js 和 npm\n\n由于 MetMuseum-MCP 服务器通过 npx 本地运行，需要确保 Node.js 和 npm 已安装。npm 通常随 Node.js 一起安装。\n\n```bash\n# 检查 Node.js 和 npm 版本\nnode --version\nnpm --version\n\n# 如果未安装，通过包管理器安装\n# macOS 使用 Homebrew\nbrew install node\n\n# Ubuntu/Debian\nsudo apt-get install nodejs npm\n\n# Windows 使用 Chocolatey\nchoco install nodejs\n```\n\n对于 MetMuseum 服务器的 STDIO 连接，项目使用 npx 命令直接运行 `metmuseum-mcp` 包，无需全局安装该包，npx 会自动下载并执行。\n\n### 第三步：设置 OpenAI API 密钥\n\nAgent 使用 OpenAI GPT-5 Nano 模型进行推理，需要配置有效的 API 密钥。\n\n```bash\n# Linux/macOS\nexport OPENAI_API_KEY=\"your-api-key-here\"\n\n# Windows (Command Prompt)\nset OPENAI_API_KEY=your-api-key-here\n\n# Windows (PowerShell)\n$env:OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n**注意**：API 密钥应妥善保管，切勿提交到版本控制系统。建议将密钥存储在环境变量文件中，如 `.env` 文件，并确保该文件在 `.gitignore` 中被忽略。\n\n## MCP 服务器配置\n\n### 服务器概述\n\n本项目同时连接两个 MCP 服务器，分别提供不同的服务能力：\n\n| 服务器名称 | 传输协议 | 类型 | 主要功能 |\n|------------|----------|------|----------|\n| Context7 | HTTP (streamable_http) | 远程云端 | 提供主流软件框架的文档搜索 |\n| MetMuseum-MCP | STDIO | 本地 (npx) | 提供大都会艺术博物馆 40 万+ 藏品访问 |\n\n### 配置参数详解\n\n根据 main.py 中的代码实现，MCP 客户端配置如下：\n\n```python\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n }\n})\n```\n\n配置参数详细说明：\n\n| 服务器 | 参数 | 类型 | 说明 | 必填 |\n|--------|------|------|------|------|\n| context7 | url | string | Context7 服务器端点 | 是 |\n| context7 | transport | string | 传输协议类型，固定为 streamable_http | 是 |\n| met-museum | command | string | 执行命令，此处为 npx | 是 |\n| met-museum | args | list | 命令参数，`-y` 表示自动确认，`metmuseum-mcp` 为包名 | 是 |\n| met-museum | transport | string | 传输协议类型，固定为 stdio | 是 |\n\n## 运行 Agent\n\n### 启动命令\n\n完成所有配置后，执行以下命令启动 Agent：\n\n```bash\npython main.py\n```\n\n### 交互流程\n\n```mermaid\ngraph TD\n A[启动 main.py] --> B[初始化 MCP 客户端]\n B --> C[连接 Context7 服务器 HTTP]\n B --> D[连接 MetMuseum-MCP 服务器 STDIO]\n C --> E[获取所有可用工具]\n D --> E\n E --> F[初始化 GPT-5 Nano 模型]\n F --> G[创建 LangGraph ReAct Agent]\n G --> H[初始化 InMemorySaver 内存]\n H --> I[Agent 自我介绍]\n I --> J{用户选择}\n J -->|选择 1| K[用户输入问题]\n K --> L[Agent 推理并调用工具]\n L --> M[返回响应结果]\n M --> J\n J -->|选择 2| N[退出程序]\n```\n\n### 会话管理\n\nAgent 使用 InMemorySaver 实现会话记忆功能，所有消息通过 thread_id 进行关联：\n\n```python\ncheckpointer = InMemorySaver()\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n这确保了多轮对话中 Agent 能够记住之前的上下文信息。\n\n## 架构组件关系\n\n```mermaid\ngraph TD\n subgraph 应用层\n A[main.py] --> B[MultiServerMCPClient]\n B --> C[create_react_agent]\n C --> D[ChatOpenAI GPT-5 Nano]\n end\n \n subgraph 连接层\n B --> E[HTTP Transport]\n B --> F[STDIO Transport]\n end\n \n subgraph 服务层\n E --> G[Context7 Server]\n F --> H[MetMuseum-MCP Server]\n end\n \n subgraph 数据层\n G --> I[框架文档数据]\n H --> J[艺术藏品数据]\n end\n```\n\n## 常见问题排查\n\n### 依赖安装失败\n\n| 问题 | 解决方案 |\n|------|----------|\n| pip 版本过旧 | 升级 pip: `pip install --upgrade pip` |\n| 权限错误 | 使用虚拟环境或添加 `--user` 参数 |\n| SSL 证书错误 | 更新 certifi 包: `pip install --upgrade certifi` |\n\n### MCP 服务器连接问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| Context7 连接超时 | 检查网络连接，确认 https://mcp.context7.com/mcp 可访问 |\n| MetMuseum npx 失败 | 确保 Node.js 和 npm 已正确安装，运行 `npx -y metmuseum-mcp` 测试 |\n| 工具获取失败 | 检查 API 密钥是否有效，确认网络连接正常 |\n\n### API 密钥问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 密钥未设置 | 执行 `export OPENAI_API_KEY=\"your-key\"` |\n| 密钥无效 | 前往 OpenAI 平台检查并生成新密钥 |\n| 余额不足 | 检查 OpenAI 账户余额 |\n\n## 项目文件结构\n\n```\nmcp-ai-agent/\n│\n├── main.py # 主程序入口，包含完整的多服务器 MCP Agent 实现\n├── README.md # 项目说明文档\n└── .gitignore # Git 忽略文件（需创建，包含 .env 等）\n```\n\n## 后续步骤\n\n安装配置完成后，建议按以下顺序验证系统：\n\n1. 验证 Python 依赖已正确安装\n2. 验证 OpenAI API 密钥有效\n3. 运行 `python main.py` 启动 Agent\n4. 输入测试问题验证工具调用功能\n5. 测试多轮对话确认会话记忆正常\n\n---\n\n\n\n## 运行与交互指南\n\n### 相关页面\n\n相关主题：[安装与配置指南](#page-8), [持久化对话记忆机制](#page-5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n \n\n# 运行与交互指南\n\n## 概述\n\n本指南详细介绍 `mcp-ai-agent` 项目的运行方法与用户交互流程。该项目是一个基于 Model Context Protocol (MCP) 的多服务器 AI Agent，采用 LangGraph ReAct 架构，能够同时连接多个 MCP 服务器并提供持久化对话记忆功能。资料来源：[main.py:1-95]()\n\n## 系统要求\n\n### 运行环境\n\n| 组件 | 最低要求 |\n|------|----------|\n| Python 版本 | 3.10+ |\n| Node.js | 用于 npx 运行本地 MCP 服务器 |\n| OpenAI API Key | 必需 |\n\n### 依赖安装\n\n在运行项目前，需要安装以下 Python 依赖包：\n\n```bash\npip install langchain-mcp-adapters langgraph langchain-openai\n```\n\n对于本地 MCP 服务器（如 MetMuseum），需要确保 npm 可用：\n\n```bash\nnpm install -g npx\n```\n\n## 配置步骤\n\n### 环境变量配置\n\n运行项目前，必须设置 OpenAI API 密钥：\n\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n### MCP 服务器配置\n\n`main.py` 中配置了两个 MCP 服务器连接，详情见下表：\n\n| 服务器名称 | 传输协议 | 端点/命令 | 功能描述 |\n|-----------|---------|----------|----------|\n| context7 | streamable_http | https://mcp.context7.com/mcp | 提供代码库文档搜索能力 |\n| met-museum | stdio | npx -y metmuseum-mcp | 提供大都会艺术博物馆藏品访问 |\n\n资料来源：[main.py:37-52]()\n\n## 核心组件架构\n\n### 组件交互流程\n\n```mermaid\ngraph TD\n A[用户 CLI 交互] --> B[LangGraph ReAct Agent]\n B --> C{GPT-5 Nano 推理}\n C --> D[自动工具选择]\n D --> E[Context7 HTTP]\n D --> F[MetMuseum STDIO]\n E --> G[返回结果]\n F --> G\n G --> B\n H[InMemorySaver] --> B\n I[thread_id 持久化] --> H\n```\n\n### 关键组件说明\n\n| 组件 | 类/模块 | 作用 |\n|------|---------|------|\n| MCP 客户端 | MultiServerMCPClient | 同时管理多个 MCP 服务器连接 |\n| Agent 引擎 | create_react_agent | 创建 ReAct 风格代理，整合推理与工具调用 |\n| 对话记忆 | InMemorySaver | 维护会话线程内的对话历史 |\n| 语言模型 | ChatOpenAI | GPT-5 Nano 提供推理能力 |\n\n资料来源：[main.py:37](), [main.py:68](), [main.py:72](), [main.py:60]()\n\n## 运行流程详解\n\n### 启动序列\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as AI Agent\n participant Client as MCP Client\n participant Servers as MCP Servers\n\n User->>Agent: python main.py\n Agent->>Client: 初始化 MultiServerMCPClient\n Client->>Servers: 建立 HTTP + STDIO 连接\n Servers-->Client: 返回可用工具列表\n Client-->Agent: tools = await client.get_tools()\n Agent->>Agent: 创建 InMemorySaver\n Agent->>Agent: create_react_agent\n Agent->>User: 显示自我介绍与工具列表\n```\n\n### 主程序执行逻辑\n\n```python\n# 标准库导入\nimport asyncio\n\n# MCP 和 LangGraph 导入\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.checkpoint.memory import InMemorySaver\nfrom langchain_openai import ChatOpenAI\n\nasync def main():\n # 1. 配置并初始化 MCP 客户端\n client = MultiServerMCPClient({...})\n \n # 2. 初始化 OpenAI 模型\n openai_model = ChatOpenAI(model=\"gpt-5-nano\")\n \n # 3. 获取所有可用工具\n tools = await client.get_tools()\n \n # 4. 设置对话记忆系统\n checkpointer = InMemorySaver()\n config = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n \n # 5. 创建 ReAct Agent\n agent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer\n )\n \n # 6. 发送初始介绍消息\n response = await agent.ainvoke({...}, config=config)\n \n # 7. 进入交互循环\n while True:\n # 处理用户输入...\n```\n\n资料来源：[main.py:18-95]()\n\n## 用户交互流程\n\n### 交互菜单系统\n\n项目采用简单的命令行菜单界面，用户通过输入数字选择操作：\n\n```\nMenu:\n1. Ask the agent a question\n2. Quit\nEnter your choice (1 or 2): \n```\n\n### 交互状态机\n\n```mermaid\nstateDiagram-v2\n [*] --> 启动: python main.py\n 启动 --> 初始化: asyncio.run(main)\n 初始化 --> 自我介绍: Agent 介绍工具能力\n 自我介绍 --> 等待选择: 显示菜单\n 等待选择 --> 提问: 用户选择 1\n 等待选择 --> 退出: 用户选择 2\n 提问 --> 调用Agent: 输入问题\n 调用Agent --> 等待选择: 显示响应\n 退出 --> [*]: print(\"Goodbye!\")\n```\n\n### 消息处理流程\n\n当用户提出问题时，系统按以下步骤处理：\n\n1. **接收用户查询** — 获取用户输入的问题内容\n2. **调用 Agent** — 使用 `agent.ainvoke()` 发送查询\n3. **传递会话配置** — config 中的 thread_id 维持对话上下文\n4. **返回响应** — 显示 agent 的最后一条消息内容\n\n```python\n# 发送用户问题并获取响应\nquery = input(\"> \")\nresponse = await agent.ainvoke(\n {\"messages\": query},\n config=config\n)\n# 显示 agent 的回复\nprint(response['messages'][-1].content)\n```\n\n资料来源：[main.py:86-92]()\n\n## 对话记忆机制\n\n### 持久化原理\n\n系统使用 `InMemorySaver` 和 `thread_id` 实现对话记忆：\n\n| 参数 | 值 | 说明 |\n|------|-----|------|\n| thread_id | \"conversation_id\" | 会话唯一标识符 |\n| checkpointer | InMemorySaver 实例 | 内存中的对话历史存储 |\n\n所有在同一 thread_id 下的消息都会被持久化保存，Agent 能够记住之前的对话内容。\n\n资料来源：[main.py:72-75]()\n\n### 消息结构\n\n```python\n# 系统消息定义 Agent 角色\n{\"role\": \"system\", \"content\": \"You are a smart, useful agent...\"}\n\n# 用户消息\n{\"role\": \"user\", \"content\": \"用户输入的问题\"}\n\n# Agent 响应\n{\"role\": \"assistant\", \"content\": \"Agent 的回复内容\"}\n```\n\n## MCP 服务器工具调用\n\n### 自主工具选择\n\nAgent 具备自动选择工具的能力，根据用户问题判断应调用哪个服务器：\n\n```mermaid\ngraph LR\n A[用户问题] --> B{GPT-5 Nano 推理}\n B -->|代码/库文档| C[Context7 HTTP]\n B -->|艺术/博物馆| D[MetMuseum STDIO]\n C --> E[返回文档数据]\n D --> F[返回艺术品数据]\n```\n\n### 示例场景\n\n| 用户问题类型 | 调用服务器 | 返回内容 |\n|-------------|-----------|----------|\n| \"LangChain 代理文档\" | Context7 | 代码库文档 |\n| \"梵高 paintings\" | MetMuseum | 艺术品元数据与图片 |\n\n## 快速启动命令汇总\n\n| 步骤 | 命令 | 说明 |\n|------|------|------|\n| 1 | `pip install langchain-mcp-adapters langgraph langchain-openai` | 安装 Python 依赖 |\n| 2 | `export OPENAI_API_KEY=\"your-api-key-here\"` | 设置 API 密钥 |\n| 3 | `python main.py` | 启动 Agent |\n\n## 异常处理\n\n程序对用户输入采用宽松处理策略：\n\n- 输入 `1` → 进入提问模式\n- 输入其他任何值 → 退出程序\n\n```python\nif choice == \"1\":\n # 处理提问逻辑\nelse:\n print(\"Goodbye!\")\n break\n```\n\n资料来源：[main.py:93-94]()\n\n## 项目结构\n\n```\nmcp-ai-agent/\n├── main.py # 完整的 MCP Agent 实现\n└── README.md # 项目说明文档\n```\n\n当前项目结构简洁，所有核心逻辑均包含在 `main.py` 中，便于快速理解与部署。\n\n---\n\n\n\n## 扩展与定制指南\n\n### 相关页面\n\n相关主题：[MultiServerMCPClient配置](#page-6), [集成MCP服务器详解](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n \n\n# 扩展与定制指南\n\n本指南详细说明如何扩展和定制 mcp-ai-agent 项目，涵盖 MCP 服务器配置、LLM 模型替换、记忆系统升级、代理架构调整以及传输协议选择等关键定制方向。通过本指南，开发者可以根据实际业务需求灵活调整系统组件，构建符合特定场景的智能代理应用。\n\n## 1. 系统架构概述\n\nmcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器代理系统，核心架构采用 LangGraph ReAct 模式实现自主工具调用和推理。系统通过 MultiServerMCPClient 同时管理多个 MCP 服务器，连接不同传输协议的外部服务，并利用 GPT-5 Nano 模型进行自然语言理解和工具选择决策。代理运行时维护会话记忆，确保多轮对话的上下文连贯性。\n\n```mermaid\ngraph TD\n A[用户 CLI 交互界面] --> B[LangGraph ReAct 代理引擎]\n B --> C[GPT-5 Nano 推理引擎]\n C --> D{工具选择决策}\n D --> E[Context7 服务器
HTTP 传输]\n D --> F[MetMuseum 服务器
STDIO 传输]\n E --> G[外部文档库检索]\n F --> H[大都会艺术博物馆数据]\n B <--> I[InMemorySaver
会话记忆存储]\n G --> J[LLM 优化文档结果]\n H --> K[艺术品元数据与图片]\n J --> L[自然语言响应生成]\n K --> L\n L --> A\n```\n\n系统核心组件包括：MultiServerMCPClient 负责多服务器连接管理，create_react_agent 构建 ReAct 推理代理，InMemorySaver 提供进程内会话持久化，ChatOpenAI 封装语言模型调用接口。各组件通过异步机制协同工作，支持高并发工具调用场景。资料来源：[main.py:1-30]()\n\n## 2. MCP 服务器扩展\n\n### 2.1 MCP 服务器配置结构\n\nMCP 服务器通过 MultiServerMCPClient 的配置字典进行注册，支持 HTTP 流式传输和 STDIO 本地进程两种主要协议类型。每台服务器配置包含传输协议类型、连接参数和认证信息三个核心维度。HTTP 服务器适合远程云端服务，STDIO 服务器适合本地 Node.js 运行时环境。\n\n| 配置字段 | 类型 | 说明 | 示例值 |\n|---------|------|------|--------|\n| transport | string | 传输协议类型 | `streamable_http`、`stdio` |\n| url | string | HTTP 服务器端点 | `https://mcp.context7.com/mcp` |\n| command | string | STDIO 执行命令 | `npx`、`node` |\n| args | array | 命令行参数列表 | `[\"-y\", \"metmuseum-mcp\"]` |\n| headers | object | HTTP 请求头 | `{\"Authorization\": \"Bearer xxx\"}` |\n\n资料来源：[main.py:28-42]()\n\n### 2.2 添加 HTTP 远程服务器\n\nHTTP 传输协议基于 streamable_http 实现，支持远程 MCP 服务器的云端部署。配置时需指定服务器的 URL 端点，可选配置自定义请求头用于认证。远程服务器的优势在于无需在本地安装依赖，可直接调用云端提供的工具能力。\n\n```python\nclient = MultiServerMCPClient({\n \"custom-remote-server\": {\n \"url\": \"https://your-mcp-server.com/mcp\",\n \"transport\": \"streamable_http\",\n \"headers\": {\n \"Authorization\": \"Bearer your-api-key\",\n \"X-Custom-Header\": \"custom-value\"\n }\n }\n})\n```\n\nHTTP 服务器适用于以下场景：API 密钥管理的云服务、需要大规模计算资源的工具、跨组织数据共享、以及需要频繁更新的服务实例。配置时建议设置合理的超时参数，避免长时间等待响应。资料来源：[main.py:33-36]()\n\n### 2.3 添加 STDIO 本地服务器\n\nSTDIO 传输协议通过标准输入输出与本地进程通信，适用于通过 npx 或 node 命令启动的 Node.js MCP 服务器。配置时需指定可执行命令和参数列表，系统会自动管理子进程的启动和生命周期。\n\n```python\nclient = MultiServerMCPClient({\n \"local-mcp-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"your-local-mcp-package\"],\n \"transport\": \"stdio\"\n }\n})\n```\n\n本地 STDIO 服务器的优势包括：无网络延迟的工具调用、本地文件系统和数据库的直接访问、以及完全可控的执行环境。开发时可通过本地服务器快速迭代工具定义。资料来源：[main.py:37-41]()\n\n### 2.4 多服务器并发管理\n\nMultiServerMCPClient 支持同时连接多个不同协议的 MCP 服务器，所有服务器的工具会在调用时自动聚合。代理引擎无需感知底层传输差异，统一通过工具名称进行调用。并发连接管理由底层适配器自动处理，开发者只需在配置中声明服务器列表。\n\n```python\nclient = MultiServerMCPClient({\n \"server-a\": {\n \"url\": \"https://server-a.com/mcp\",\n \"transport\": \"streamable_http\"\n },\n \"server-b\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"server-b-package\"],\n \"transport\": \"stdio\"\n },\n \"server-c\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/server-c.js\"],\n \"transport\": \"stdio\"\n }\n})\ntools = await client.get_tools() # 聚合所有服务器工具\n```\n\n资料来源：[main.py:28-47]()\n\n## 3. 大语言模型定制\n\n### 3.1 模型提供商切换\n\n系统默认使用 OpenAI 的 GPT-5 Nano 模型，可通过替换 ChatOpenAI 实例切换到其他兼容提供商。LangChain 生态支持多种 LLM 实现，包括 Anthropic、Google VertexAI、Azure OpenAI 等。模型选择影响代理的推理能力、响应速度和运行成本。\n\n```python\nfrom langchain_openai import ChatOpenAI\nfrom langchain_anthropic import ChatAnthropic\nfrom langchain_google_vertexai import ChatVertexAI\n\n# OpenAI 配置\nopenai_model = ChatOpenAI(\n model=\"gpt-5-nano\",\n api_key=\"your-openai-key\",\n temperature=0.7\n)\n\n# Anthropic Claude 配置\nclaude_model = ChatAnthropic(\n model=\"claude-sonnet-4-20250514\",\n anthropic_api_key=\"your-anthropic-key\"\n)\n```\n\n资料来源：[main.py:44-48]()\n\n### 3.2 模型参数调优\n\nChatOpenAI 初始化支持多个关键参数控制模型行为。temperature 控制输出随机性，数值越高越具创造性；max_tokens 限制单次响应长度；top_p 和 frequency_penalty 提供更细粒度的采样控制。\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|--------|------|\n| model | string | gpt-5-nano | 模型标识符 |\n| temperature | float | 0.7 | 采样温度，0-2 之间 |\n| max_tokens | int | None | 最大生成 token 数 |\n| top_p | float | 1.0 | 核采样概率阈值 |\n| frequency_penalty | float | 0.0 | 频率惩罚系数 |\n| presence_penalty | float | 0.0 | 存在惩罚系数 |\n\n调优建议：代码生成任务建议使用较低的 temperature（0.2-0.5）；创意写作和头脑风暴适合较高的 temperature（0.7-1.0）；需要确定性输出的场景可设为 0。资料来源：[main.py:44-48]()\n\n### 3.3 自定义系统提示词\n\n系统提示词定义代理的角色定位、行为规范和能力边界。通过修改 create_react_agent 调用时的 messages 参数，可以定制代理的专业领域、响应风格和工具使用策略。\n\n```python\nresponse = await agent.ainvoke(\n {\"messages\": [\n {\"role\": \"system\", \"content\": \"\"\"你是一位专业的金融分析助手，专注于：\n 1. 股票市场数据分析和趋势预测\n 2. 投资组合风险评估\n 3. 财务报表解读\n 4. 使用可用的金融数据工具获取实时信息\n \n 回复时使用简洁专业的语言，提供数据支撑的分析结论。\"\"\"},\n {\"role\": \"user\", \"content\": \"介绍你自己和可用工具\"},\n ]},\n config=config\n)\n```\n\n资料来源：[main.py:59-68]()\n\n## 4. 代理架构定制\n\n### 4.1 代理类型选择\n\nLangGraph 提供了多种预构建代理类型，除了默认的 ReAct 代理外，还支持 create_structured_chat_agent、create_conversational_agent 等变体。不同代理类型适用于不同交互模式：ReAct 适合需要复杂推理的工具调用场景，Conversational 适合聊天式问答，Structured Chat 适合需要结构化输出的场景。\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.prebuilt import create_structured_chat_agent\n\n# ReAct 代理 - 适合工具调用\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer,\n state_modifier=\"你是一个有帮助的助手\"\n)\n\n# 结构化聊天代理 - 适合需要 JSON 输出\nagent = create_structured_chat_agent(\n model=openai_model,\n tools=tools\n)\n```\n\n### 4.2 ReAct 推理循环定制\n\nReAct（Reasoning + Acting）代理的核心是思考-行动-观察循环。LangGraph 预构建代理封装了这一逻辑，但可通过 state_modifier 和 prompt 自定义影响推理过程。state_modifier 在每轮推理前修改状态，用于注入额外上下文或约束。\n\n```mermaid\ngraph TD\n A[用户输入] --> B[构建消息历史]\n B --> C[LLM 推理阶段]\n C --> D{是否调用工具?}\n D -->|是| E[执行工具调用]\n E --> F[收集工具结果]\n F --> B\n D -->|否| G[生成最终响应]\n G --> H[返回给用户]\n C -->|思考过程| I[记录推理步骤]\n I --> D\n```\n\n资料来源：[main.py:51-57]()\n\n### 4.3 工具过滤与白名单\n\n出于安全和性能考虑，可通过工具过滤机制限制代理可用的工具范围。get_tools() 返回的完整工具列表可按名称模式或分类标签进行筛选，只将必要的工具暴露给代理。\n\n```python\ntools = await client.get_tools()\n\n# 按名称前缀过滤\nfiltered_tools = [\n tool for tool in tools \n if tool.name.startswith(\"context7_\")\n]\n\n# 按工具类型过滤\ndocument_tools = [\n tool for tool in tools \n if hasattr(tool, 'tags') and 'document' in tool.tags\n]\n\nagent = create_react_agent(\n model=openai_model,\n tools=filtered_tools, # 使用过滤后的工具列表\n checkpointer=checkpointer\n)\n```\n\n## 5. 记忆系统升级\n\n### 5.1 内存检查点器对比\n\n默认的 InMemorySaver 将对话历史存储在进程内存中，适用于单实例部署和快速原型开发。生产环境建议使用持久化检查点器，避免进程重启后对话历史丢失。\n\n| 检查点器类型 | 存储介质 | 持久化 | 并发支持 | 适用场景 |\n|------------|---------|--------|---------|---------|\n| InMemorySaver | 进程内存 | 否 | 单进程 | 开发调试、原型 |\n| PostgresSaver | PostgreSQL | 是 | 高并发 | 生产环境 |\n| RedisSaver | Redis | 是 | 高并发 | 分布式部署 |\n| SQLiteSaver | SQLite | 是 | 低并发 | 轻量级部署 |\n\n资料来源：[main.py:49-50]()\n\n### 5.2 PostgreSQL 检查点器配置\n\nPostgreSQL 检查点器支持多实例并发访问，适合生产环境大规模部署。需提前创建数据库表结构，LangGraph 提供自动迁移功能。\n\n```python\nfrom langgraph.checkpoint.postgres import PostgresSaver\nfrom langchain_postgres import PostgresChatMessageHistory\n\n# PostgreSQL 检查点器配置\ncheckpointer = PostgresSaver.from_conn_string(\n \"postgresql://user:password@localhost:5432/langgraph\"\n)\ncheckpointer.setup() # 创建必要的表结构\n\nconfig = {\"configurable\": {\"thread_id\": \"user_session_123\"}}\n```\n\n### 5.3 多会话隔离管理\n\n通过 thread_id 实现多用户会话隔离，每个会话维护独立的对话历史。config 字典的可配置参数用于指定线程标识符，系统自动为每个线程维护独立的状态快照。\n\n```python\n# 用户 A 的会话\nconfig_a = {\"configurable\": {\"thread_id\": \"user_a_session\"}}\n\n# 用户 B 的会话\nconfig_b = {\"configurable\": {\"thread_id\": \"user_b_session\"}}\n\n# 独立调用，互不影响\nresponse_a = await agent.ainvoke({\"messages\": query}, config=config_a)\nresponse_b = await agent.ainvoke({\"messages\": query}, config=config_b)\n```\n\n资料来源：[main.py:52-53]()\n\n## 6. 传输协议深度定制\n\n### 6.1 HTTP 流式传输配置\n\nstreamable_http 传输支持流式响应模式，减少首次响应延迟。配置选项包括连接超时、读取超时和自动重试策略。对于需要实时反馈的工具调用场景，建议启用流式传输。\n\n```python\nclient = MultiServerMCPClient({\n \"streaming-server\": {\n \"url\": \"https://streaming-mcp.example.com/mcp\",\n \"transport\": \"streamable_http\",\n \"timeout\": 30, # 超时时间（秒）\n \"max_retries\": 3, # 最大重试次数\n \"verify_ssl\": True # SSL 证书验证\n }\n})\n```\n\n### 6.2 STDIO 进程生命周期管理\n\nSTDIO 服务器由 MCP 客户端自动管理进程启动和终止。当客户端关闭时，所有 STDIO 子进程会自动清理。必要时可通过客户端上下文管理器手动控制进程生命周期。\n\n```python\nasync with MultiServerMCPClient({...}) as client:\n tools = await client.get_tools()\n # 使用工具...\n# 超出上下文范围时自动清理进程\n```\n\n### 6.3 混合传输架构\n\n在复杂企业场景中，可采用混合传输架构：核心业务逻辑使用 HTTP 服务器保证可用性，敏感数据操作使用本地 STDIO 服务器确保数据安全。\n\n```mermaid\ngraph LR\n A[代理引擎] --> B[HTTP 网关]\n A --> C[本地 STDIO 桥接]\n B --> D[云端 MCP 服务]\n B --> E[第三方 API 服务]\n C --> F[本地数据库服务器]\n C --> G[文件系统]\n D --> H[文档检索]\n E --> I[外部数据源]\n F --> J[业务数据]\n G --> K[附件存储]\n```\n\n## 7. 错误处理与容错\n\n### 7.1 工具调用错误捕获\n\n代理运行时可能遇到工具执行失败、网络超时或服务器不可用等情况。建议在外层封装错误处理逻辑，为用户提供友好的错误提示。\n\n```python\ntry:\n response = await agent.ainvoke(\n {\"messages\": query},\n config=config\n )\n print(response['messages'][-1].content)\nexcept Exception as e:\n print(f\"处理请求时发生错误: {str(e)}\")\n # 可选：降级到无工具模式重试\n```\n\n### 7.2 重试策略配置\n\n对于临时性故障，可实现自动重试机制。指数退避策略可避免重试风暴，同时给予服务恢复时间。\n\n```python\nimport asyncio\nfrom tenacity import retry, stop_after_attempt, wait_exponential\n\n@retry(\n stop=stop_after_attempt(3),\n wait=wait_exponential(multiplier=1, min=2, max=10)\n)\nasync def call_agent_with_retry(agent, query, config):\n return await agent.ainvoke({\"messages\": query}, config=config)\n```\n\n### 7.3 降级策略设计\n\n当部分 MCP 服务器不可用时，系统应能优雅降级。可实现工具可用性检查，在初始化阶段过滤不可用工具，并通知代理哪些工具可用。\n\n```python\ntools = await client.get_tools()\navailable_tools = []\n\nfor tool in tools:\n try:\n # 健康检查\n await tool.invoke({\"type\": \"ping\"})\n available_tools.append(tool)\n except Exception:\n print(f\"工具 {tool.name} 不可用，已跳过\")\n\nagent = create_react_agent(\n model=openai_model,\n tools=available_tools,\n checkpointer=checkpointer\n)\n```\n\n## 8. 生产环境部署\n\n### 8.1 环境变量管理\n\n生产部署应使用环境变量管理敏感配置，避免硬编码 API 密钥。建议使用 python-dotenv 或 docker-secrets 管理变量。\n\n```python\nimport os\nfrom dotenv import load_dotenv\n\nload_dotenv() # 从 .env 文件加载\n\nopenai_model = ChatOpenAI(\n model=\"gpt-5-nano\",\n api_key=os.environ.get(\"OPENAI_API_KEY\")\n)\n\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": os.environ.get(\"CONTEXT7_URL\"),\n \"transport\": \"streamable_http\"\n }\n})\n```\n\n资料来源：[main.py:44-48]()\n\n### 8.2 异步入口点设计\n\nmain() 函数使用 asyncio.run() 启动异步事件循环。生产环境建议使用 uvicorn 或 gunicorn 配合 ASGI 应用封装，实现真正的并发处理。\n\n```python\nfrom fastapi import FastAPI\nimport asyncio\n\napp = FastAPI()\n\n@app.post(\"/chat\")\nasync def chat_endpoint(request: ChatRequest):\n response = await agent.ainvoke(\n {\"messages\": request.messages},\n config={\"configurable\": {\"thread_id\": request.session_id}}\n )\n return {\"response\": response['messages'][-1].content}\n\nif __name__ == \"__main__\":\n import uvicorn\n uvicorn.run(app, host=\"0.0.0.0\", port=8000)\n```\n\n### 8.3 容器化部署配置\n\nDocker 容器化部署需考虑 MCP 服务器的依赖。STDIO 服务器需要 Node.js 运行时，HTTP 服务器则只需 Python 环境。\n\n```dockerfile\n# 多阶段构建 Dockerfile\nFROM node:18-slim AS npx-server\nWORKDIR /app\nRUN npm install -g metmuseum-mcp\n\nFROM python:3.10-slim\nWORKDIR /app\nCOPY requirements.txt .\nRUN pip install --no-cache-dir -r requirements.txt\nCOPY --from=npx-server /usr/local/bin/npx /usr/local/bin/\nCOPY main.py .\nCMD [\"python\", \"main.py\"]\n```\n\n## 9. 监控与日志\n\n### 9.1 LangSmith 集成\n\nLangChain 生态提供 LangSmith 用于追踪代理执行过程，包括 LLM 调用、工具执行和状态转换。\n\n```python\nos.environ[\"LANGCHAIN_TRACING_V2\"] = \"true\"\nos.environ[\"LANGCHAIN_API_KEY\"] = \"your-langsmith-key\"\nos.environ[\"LANGCHAIN_PROJECT\"] = \"mcp-agent-production\"\n```\n\n### 9.2 自定义日志记录\n\n使用 Python logging 模块配置结构化日志，便于生产环境问题排查。\n\n```python\nimport logging\nimport json\n\nlogging.basicConfig(level=logging.INFO)\nlogger = logging.getLogger(\"mcp-agent\")\n\nasync def log_agent_invocation(query, response):\n logger.info(json.dumps({\n \"event\": \"agent_invocation\",\n \"query\": str(query),\n \"response_length\": len(str(response))\n }))\n```\n\n## 10. 快速参考\n\n### 10.1 完整定制配置模板\n\n```python\nimport asyncio\nimport os\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.checkpoint.postgres import PostgresSaver\nfrom langchain_openai import ChatOpenAI\nfrom langchain_anthropic import ChatAnthropic\n\nasync def main():\n # 1. MCP 服务器配置\n client = MultiServerMCPClient({\n \"context7\": {\n \"url\": os.environ.get(\"CONTEXT7_URL\"),\n \"transport\": \"streamable_http\"\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\"\n }\n })\n \n # 2. LLM 模型配置\n model = ChatAnthropic(\n model=\"claude-sonnet-4-20250514\",\n anthropic_api_key=os.environ.get(\"ANTHROPIC_API_KEY\")\n )\n \n # 3. 工具与记忆配置\n tools = await client.get_tools()\n checkpointer = PostgresSaver.from_conn_string(\n os.environ.get(\"DATABASE_URL\")\n )\n \n # 4. 创建代理\n agent = create_react_agent(\n model=model,\n tools=tools,\n checkpointer=checkpointer\n )\n \n # 5. 运行代理\n config = {\"configurable\": {\"thread_id\": \"main\"}}\n response = await agent.ainvoke(\n {\"messages\": [{\"role\": \"user\", \"content\": \"你好\"}]},\n config=config\n )\n print(response['messages'][-1].content)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### 10.2 关键文件位置\n\n| 功能模块 | 文件路径 | 行号范围 |\n|---------|---------|---------|\n| MCP 客户端初始化 | main.py | 28-47 |\n| LLM 模型配置 | main.py | 44-48 |\n| 工具获取 | main.py | 50 |\n| 记忆系统配置 | main.py | 49-50 |\n| 代理创建 | main.py | 51-57 |\n| 初始对话调用 | main.py | 59-78 |\n| 主循环交互 | main.py | 80-95 |\n\n资料来源：[main.py:1-95]()\n\n本指南涵盖 mcp-ai-agent 的主要扩展和定制方向。开发者可根据实际需求组合不同模块，构建满足特定业务场景的智能代理系统。建议从单服务器简单配置开始，逐步添加复杂功能，并在开发过程中使用 InMemorySaver 便于调试，生产环境切换到持久化检查点器确保会话可靠性。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：LeelaissakAttota/mcp-ai-agent\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `mcp-ai-agent` 与安装入口 `metmuseum-mcp` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx metmuseum-mcp`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | repo=mcp-ai-agent; install=metmuseum-mcp\n\n## 2. 能力坑 · 能力判断依赖假设\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:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium\n\n## 6. 维护坑 · 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:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | release_recency=unknown\n\n\n",
"markdown_key": "mcp-ai-agent",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:1158386431",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/LeelaissakAttota/mcp-ai-agent"
},
{
"evidence_id": "art_6aec6127b3d24e2bb6a472ea87d4ecf4",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/LeelaissakAttota/mcp-ai-agent#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "mcp-ai-agent 说明书",
"toc": [
"https://github.com/LeelaissakAttota/mcp-ai-agent 项目说明书",
"目录",
"项目概览",
"项目简介",
"核心架构",
"工作流程",
"集成 MCP 服务器",
"核心功能特性",
"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": false,
"repo_commit": null,
"repo_inspection_error": null,
"repo_inspection_files": [],
"repo_inspection_verified": false,
"review_reasons": [
"community_discussion_evidence_below_public_threshold"
],
"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": "# mcp-ai-agent - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 mcp-ai-agent 编译的 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 langgraph langchain-openai` 证据：`README.md` Claim：`clm_0003` supported 0.86\n- `npm install -g npx # For MetMuseum STDIO server` 证据：`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\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- 文件总数：3\n- 重要文件覆盖：3/3\n- 证据索引条目：3\n- 角色 / Skill 条目：1\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请基于 mcp-ai-agent 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 mcp-ai-agent 当作安装前体验资产，而不是已安装工具或真实运行环境。\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请基于 mcp-ai-agent 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **🤖 Multi-Server AI Agent with Model Context Protocol MCP**（project_doc）：🤖 Multi-Server AI Agent with Model Context Protocol MCP 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md`\n\n## 证据索引\n\n- 共索引 3 条证据。\n\n- **🤖 Multi-Server AI Agent with Model Context Protocol MCP**（documentation）：🤖 Multi-Server AI Agent with Model Context Protocol MCP 证据：`README.md`\n- **Settings**（structured_config）：{ \"php.suggest.basic\": false, \"java.errors.incompleteClasspath.severity\": \"ignore\", \"security.workspace.trust.enabled\": true, \"security.workspace.trust.startupPrompt\": \"never\", \"security.workspace.trust.untrustedFiles\": \"open\", \"liveServer.settings.donotShowInfoMsg\": false, } 证据：`.theia/settings.json`\n- **Standard library imports**（source_file）：Standard library imports import asyncio Third-party imports for MCP Model Context Protocol and LangGraph from langchain mcp adapters.client import MultiServerMCPClient Connects to MCP servers from langgraph.prebuilt import create react agent Creates ReAct-style agents from langgraph.checkpoint.memory import InMemorySaver Provides conversation memory from langchain openai import ChatOpenAI OpenAI chat model integration 证据：`main.py`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `.theia/settings.json`, `main.py`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `.theia/settings.json`, `main.py`\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\n- **技术栈详解**：importance `high`\n - source_paths: main.py\n- **系统架构设计**：importance `high`\n - source_paths: main.py, README.md\n- **LangGraph ReAct代理实现**：importance `high`\n - source_paths: main.py\n- **持久化对话记忆机制**：importance `high`\n - source_paths: main.py\n- **MultiServerMCPClient配置**：importance `high`\n - source_paths: main.py\n- **集成MCP服务器详解**：importance `medium`\n - source_paths: main.py, README.md\n- **安装与配置指南**：importance `high`\n - source_paths: main.py, README.md\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: false\n- repo_inspection_verified: false\n- repo_commit: `unknown`\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: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `mcp-ai-agent` 与安装入口 `metmuseum-mcp` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | repo=mcp-ai-agent; install=metmuseum-mcp\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 能力判断依赖假设\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:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | README/documentation is current enough for a first validation pass.\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | last_activity_observed missing\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | issue_or_pr_quality=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | release_recency=unknown\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：LeelaissakAttota/mcp-ai-agent\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- review_required: community_discussion_evidence_below_public_threshold\n\n## 项目专属踩坑\n\n- 仓库名和安装名不一致（medium）：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 能力判断依赖假设（medium）：假设不成立时，用户拿不到承诺的能力。 建议检查：将假设转成下游验证清单。\n- 维护活跃度未知（medium）：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项（medium）：下游已经要求复核，不能在页面中弱化。 建议检查：进入安全/权限治理复核队列。\n- 存在评分风险（medium）：风险会影响是否适合普通用户安装。 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/LeelaissakAttota/mcp-ai-agent 项目说明书\n\n生成时间：2026-05-13 03:43:18 UTC\n\n## 目录\n\n- [项目概览](#page-1)\n- [技术栈详解](#page-2)\n- [系统架构设计](#page-3)\n- [LangGraph ReAct代理实现](#page-4)\n- [持久化对话记忆机制](#page-5)\n- [MultiServerMCPClient配置](#page-6)\n- [集成MCP服务器详解](#page-7)\n- [安装与配置指南](#page-8)\n- [运行与交互指南](#page-9)\n- [扩展与定制指南](#page-10)\n\n\n\n## 项目概览\n\n### 相关页面\n\n相关主题：[技术栈详解](#page-2), [系统架构设计](#page-3)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n \n\n# 项目概览\n\n## 项目简介\n\nmcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器智能代理项目，扮演着 AI 应用与外部工具服务之间的 **\"Universal Interface\"**（通用接口）角色，类似于 USB-C 在硬件连接中的地位。该项目实现了同时连接多个 MCP 服务器、跨协议传输管理、持久化对话记忆以及由 GPT-5 Nano 驱动的自主工具选择能力。\n\n**技术定位：** Agentic AI — 多服务器 MCP 代理 \n**编程语言：** Python 3.10+ \n**核心模型：** OpenAI GPT-5 Nano \n**代理框架：** LangGraph ReAct \n**协议支持：** STDIO + HTTP 双传输层\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 核心架构\n\n### 系统架构图\n\n```mermaid\ngraph TB\n subgraph 用户层[\"用户层 (CLI 界面)\"]\n U[用户输入查询]\n end\n \n subgraph 代理层[\"LangGraph ReAct 代理\"]\n LLM[GPT-5 Nano
推理引擎]\n MEM[InMemorySaver
对话记忆]\n TOOL[自主工具选择]\n end\n \n subgraph 传输层[\"MCP 传输层\"]\n HTTP[HTTP Transport
远程云端]\n STDIO[STDIO Transport
本地 npx]\n end\n \n subgraph 服务层[\"MCP 服务器\"]\n C7[Context7 Server
文档搜索]\n MET[MetMuseum Server
艺术馆数据]\n end\n \n U --> LLM\n LLM --> TOOL\n TOOL --> HTTP\n TOOL --> STDIO\n HTTP --> C7\n STDIO --> MET\n LLM <--> MEM\n```\n\n### 技术组件表\n\n| 组件类别 | 技术实现 | 功能说明 |\n|---------|---------|---------|\n| **MCP 客户端** | MultiServerMCPClient (langchain-mcp-adapters) | 多服务器并发连接管理 |\n| **代理框架** | LangGraph ReAct | 推理+行动一体化代理 |\n| **语言模型** | ChatOpenAI (gpt-5-nano) | 自然语言理解和生成 |\n| **记忆系统** | InMemorySaver | 线程化对话持久化 |\n| **异步运行时** | asyncio | 并发任务执行 |\n| **HTTP 服务器** | Context7 (streamable_http) | 远程文档检索 |\n| **STDIO 服务器** | metmuseum-mcp (npx) | 本地艺术馆数据访问 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 工作流程\n\n### 代理决策流程\n\n```mermaid\ngraph TD\n A[用户自然语言查询] --> B{GPT-5 Nano 推理}\n B --> C{判断查询类型}\n C -->|代码/文档类| D[调用 Context7 HTTP]\n C -->|艺术/博物馆类| E[调用 MetMuseum STDIO]\n D --> F[获取文档数据]\n E --> G[获取艺术品数据]\n F --> H[LLM 生成响应]\n G --> H\n H --> I[存储至 InMemorySaver]\n I --> J[返回用户响应]\n```\n\n### 典型交互流程\n\n| 步骤 | 阶段 | 说明 |\n|-----|------|------|\n| 1 | 用户输入 | 通过 CLI 输入自然语言问题 |\n| 2 | LLM 推理 | GPT-5 Nano 分析查询意图 |\n| 3 | 工具选择 | 自动决定调用哪个 MCP 服务器 |\n| 4 | 工具执行 | 跨协议执行对应工具调用 |\n| 5 | 结果处理 | 工具结果返回给 LLM |\n| 6 | 响应生成 | LLM 生成自然语言回复 |\n| 7 | 记忆存储 | 完整对话存入线程化存储 |\n| 8 | 用户展示 | 显示最终响应给用户 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 集成 MCP 服务器\n\n### 服务器配置表\n\n| 服务器名称 | 传输协议 | 端点/命令 | 数据类型 | 用途 |\n|-----------|---------|----------|---------|------|\n| **Context7** | HTTP (streamable_http) | `https://mcp.context7.com/mcp` | 软件框架文档 | LLM 优化的多框架文档搜索 |\n| **MetMuseum-MCP** | STDIO | `npx -y metmuseum-mcp` | 艺术品元数据 | 40万+ 大都会艺术博物馆藏品 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n### 多服务器连接实现\n\n```python\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\", # 远程 HTTP\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\", # 本地 STDIO\n }\n})\ntools = await client.get_tools() # 聚合所有服务器工具\n```\n\n资料来源：[main.py:22-35](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n## 核心功能特性\n\n### 1. LangGraph ReAct 代理\n\n代理采用 ReAct（Reasoning + Acting）模式，结合 GPT-5 Nano 的推理能力与工具调用能力：\n\n```python\nagent = create_react_agent(\n model=openai_model, # GPT-5 Nano 推理引擎\n tools=tools, # 聚合的 MCP 工具集\n checkpointer=checkpointer # 持久化记忆\n)\n```\n\n### 2. 持久化对话记忆\n\n通过 InMemorySaver 实现线程化的对话状态保持：\n\n```python\ncheckpointer = InMemorySaver()\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n每个线程（thread_id）维护独立的对话上下文，支持跨轮次上下文理解。\n\n### 3. 自主工具选择\n\nLLM 根据用户查询语义自动判断应调用哪个服务器：\n\n| 用户查询示例 | 调用的服务器 | 返回内容 |\n|-------------|-------------|---------|\n| \"LangChain 代理文档\" | Context7 | 框架文档检索结果 |\n| \"梵高的画作\" | MetMuseum | 艺术品元数据+图片 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 项目结构\n\n```\nmcp-ai-agent/\n│\n├── main.py # 完整的多服务器 MCP 代理实现\n│ ├── 导入模块 (第1-6行)\n│ ├── MCP 客户端配置 (第22-35行)\n│ ├── OpenAI 模型初始化 (第42-44行)\n│ ├── 工具获取 (第47行)\n│ ├── 记忆系统配置 (第50-53行)\n│ └── 代理创建与交互循环 (第56-86行)\n│\n└── README.md # 项目文档\n```\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 快速开始\n\n### 环境准备\n\n| 依赖项 | 安装命令 |\n|-------|---------|\n| langchain-mcp-adapters | `pip install langchain-mcp-adapters` |\n| langgraph | `pip install langgraph` |\n| langchain-openai | `pip install langchain-openai` |\n| npx | `npm install -g npx` |\n\n### 运行步骤\n\n1. **安装依赖**\n ```bash\n pip install langchain-mcp-adapters langgraph langchain-openai\n npm install -g npx\n ```\n\n2. **配置环境变量**\n ```bash\n export OPENAI_API_KEY=\"your-api-key-here\"\n ```\n\n3. **启动代理**\n ```bash\n python main.py\n ```\n\n4. **交互操作**\n ```\n Menu:\n 1. Ask the agent a question\n 2. Quit\n Enter your choice (1 or 2): 1\n \n Your question\n > What LangGraph tools are available?\n → 代理调用 Context7 → 返回文档\n ```\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 关键技术亮点\n\n| 特性 | 技术实现 | 优势 |\n|-----|---------|-----|\n| 多协议并发 | STDIO + HTTP 同时管理 | 灵活连接本地/远程服务 |\n| 对话持久化 | InMemorySaver + thread_id | 跨会话上下文保持 |\n| 异步架构 | asyncio + await | 高效并发任务处理 |\n| 自主决策 | LLM 推理引擎 | 无需人工指定工具 |\n| 跨域查询 | 多 MCP 服务器聚合 | 统一的自然语言接口 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 适用场景\n\n- **文档智能问答**：通过 Context7 检索编程框架文档并回答技术问题\n- **艺术藏品探索**：查询大都会艺术博物馆的藏品信息和图像\n- **多源数据整合**：聚合不同领域的外部数据源\n- **智能助手开发**：构建具有工具调用能力的对话代理\n\n---\n\n\n\n## 技术栈详解\n\n### 相关页面\n\n相关主题：[项目概览](#page-1), [系统架构设计](#page-3), [LangGraph ReAct代理实现](#page-4)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n \n\n# 技术栈详解\n\n## 概述\n\nmcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器 AI 智能体项目，通过集成多个 MCP 服务器实现跨域查询能力。该项目采用 Python 3.10+ 开发，核心架构围绕 LangGraph ReAct 智能体构建，结合 OpenAI GPT-5 Nano 模型进行推理决策，并通过 InMemorySaver 实现会话持久化管理。\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## 核心技术组件\n\n### 2.1 编程语言与运行环境\n\n| 组件 | 版本要求 | 说明 |\n|------|----------|------|\n| Python | 3.10+ | 主要开发语言 |\n| Node.js | 需安装 | 用于运行 MetMuseum-MCP 服务器 |\n| npm/npx | 需全局安装 | 包管理和 MCP 服务器启动 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n### 2.2 核心依赖库\n\n| 库名称 | 版本要求 | 功能描述 |\n|--------|----------|----------|\n| langchain-mcp-adapters | 最新版 | MCP 多服务器客户端适配器 |\n| langgraph | 最新版 | ReAct 智能体构建框架 |\n| langchain-openai | 最新版 | OpenAI 语言模型集成 |\n| asyncio | 标准库 | 异步编程支持 |\n\n资料来源：[main.py:1-7](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 2.3 语言模型\n\n项目采用 OpenAI GPT-5 Nano 模型作为推理引擎，负责以下核心任务：\n\n- 理解用户自然语言查询意图\n- 自主决策调用哪个 MCP 服务器\n- 生成最终的自然语言响应\n\n```python\nopenai_model = ChatOpenAI(\n model=\"gpt-5-nano\", # 使用 OpenAI GPT-5 Nano 模型\n)\n```\n\n资料来源：[main.py:49-51](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n## 架构设计\n\n### 3.1 系统架构图\n\n```mermaid\ngraph TD\n User[用户 CLI 界面] --> Agent[LangGraph ReAct 智能体]\n Agent --> LLM[GPT-5 Nano 推理引擎]\n LLM --> Decision[自主工具选择]\n Decision --> Context7[Context7 服务器
HTTP 传输]\n Decision --> MetMuseum[MetMuseum-MCP 服务器
STDIO 传输]\n Context7 --> DocsResult[库/代码文档]\n MetMuseum --> ArtResult[艺术品元数据/图片]\n Agent --> Memory[InMemorySaver
会话记忆]\n \n subgraph 传输层\n Context7\n MetMuseum\n end\n```\n\n### 3.2 分层职责\n\n| 层级 | 组件 | 职责 |\n|------|------|------|\n| 表现层 | CLI 用户交互界面 | 接收用户输入，展示智能体响应 |\n| 智能体层 | LangGraph ReAct Agent | 协调推理、工具调用、响应生成 |\n| 推理层 | GPT-5 Nano | 理解意图、决策路由、生成回复 |\n| 工具层 | MCP Servers | 提供外部数据查询能力 |\n| 持久化层 | InMemorySaver | 维护会话线程记忆 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n## MCP 多服务器架构\n\n### 4.1 MultiServerMCPClient 配置\n\n项目使用 `MultiServerMCPClient` 同时管理两个不同传输协议的 MCP 服务器：\n\n```python\nclient = MultiServerMCPClient({\n # Context7 服务器 - 提供库文档访问\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\", # 远程 HTTP 传输\n },\n # Met Museum 服务器 - 提供博物馆藏品数据\n \"met-museum\": {\n \"command\": \"npx\", # Node.js 包运行器\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\", # 标准输入/输出传输\n }\n})\n```\n\n资料来源：[main.py:26-42](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 4.2 集成 MCP 服务器对比\n\n| 服务器名称 | 传输协议 | 连接类型 | 主要功能 | 工具数量 |\n|-----------|---------|----------|---------|----------|\n| Context7 | streamable_http | 远程/云端 | LLM 优化文档搜索，覆盖主流框架库 | 多工具 |\n| MetMuseum-MCP | stdio | 本地/npx | 访问大都会艺术博物馆 40 万+藏品 | 多工具 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n### 4.3 传输协议详解\n\n#### HTTP 流式传输 (streamable_http)\n\n- **适用场景**：远程云端 MCP 服务器\n- **优势**：低延迟、易穿越防火墙、支持流式响应\n- **配置参数**：\n - `url`: 服务器端点 URL\n - `transport`: 必须设为 `streamable_http`\n\n#### STDIO 传输 (stdio)\n\n- **适用场景**：本地 MCP 服务器\n- **优势**：简单可靠、无需网络配置\n- **配置参数**：\n - `command`: 执行命令（通常为 `npx`）\n - `args`: 命令参数列表\n - `transport`: 必须设为 `stdio`\n\n## LangGraph ReAct 智能体\n\n### 5.1 智能体创建\n\n```python\nagent = create_react_agent(\n model=openai_model, # 语言模型\n tools=tools, # MCP 服务器工具\n checkpointer=checkpointer # 会话记忆检查点\n)\n```\n\n资料来源：[main.py:60-64](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 5.2 ReAct 工作流程\n\n```mermaid\ngraph LR\n A[用户查询] --> B[Reasoning
推理阶段]\n B --> C[Action
行动阶段]\n C --> D[Observation
观察阶段]\n D --> E{完成?}\n E -->|否| B\n E -->|是| F[最终响应]\n```\n\n### 5.3 ReAct 模式特点\n\n| 阶段 | 描述 | 执行者 |\n|------|------|--------|\n| Reasoning | 分析用户意图，决定是否调用工具 | GPT-5 Nano |\n| Action | 调用选定的 MCP 工具 | 工具执行器 |\n| Observation | 接收工具返回结果 | 智能体 |\n| Response | 基于观察结果生成自然语言回复 | GPT-5 Nano |\n\n## 会话记忆系统\n\n### 6.1 InMemorySaver 检查点器\n\n```python\ncheckpointer = InMemorySaver() # 内存会话检查点\n\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n资料来源：[main.py:53-67](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 6.2 线程管理机制\n\n| 参数 | 说明 | 用途 |\n|------|------|------|\n| thread_id | 线程标识符 | 区分不同会话 |\n| configurable | 可配置参数容器 | 传递线程 ID |\n| messages | 消息历史 | 维护对话上下文 |\n\n### 6.3 记忆持久化流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as ReAct Agent\n participant Checkpointer as InMemorySaver\n participant LLM as GPT-5 Nano\n \n User->>Agent: 发送问题\n Agent->>Checkpointer: 加载历史消息\n Checkpointer-->>Agent: 返回对话历史\n Agent->>LLM: 发送完整上下文\n LLM-->>Agent: 生成响应\n Agent->>Checkpointer: 保存新消息\n Agent-->>User: 返回响应\n```\n\n## 异步编程模式\n\n### 7.1 异步入口点\n\n```python\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[main.py:92-94](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 7.2 异步调用模式\n\n| 操作 | 异步关键字 | 说明 |\n|------|-----------|------|\n| MCP 客户端初始化 | `await client` | 连接多个 MCP 服务器 |\n| 获取工具 | `await client.get_tools()` | 异步获取可用工具列表 |\n| 智能体调用 | `await agent.ainvoke()` | 异步执行智能体推理 |\n\n### 7.3 事件循环管理\n\n```mermaid\ngraph TD\n A[asyncio.run] --> B[创建事件循环]\n B --> C[执行 main 协程]\n C --> D[MCP 客户端连接]\n D --> E[工具初始化]\n E --> F[ReAct 智能体运行]\n F --> G[用户交互循环]\n G --> F\n```\n\n## 工具集成与自主选择\n\n### 8.1 工具获取\n\n```python\ntools = await client.get_tools() # 获取所有 MCP 服务器工具\n```\n\n资料来源：[main.py:53](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 8.2 自主工具选择逻辑\n\n| 用户查询类型 | 智能体决策 | 调用服务器 | 返回内容 |\n|-------------|-----------|-----------|---------|\n| 代码/库文档问题 | \"需要文档\" | Context7 | LLM 优化文档 |\n| 艺术/博物馆查询 | \"需要藏品数据\" | MetMuseum | 艺术品元数据/图片 |\n\n### 8.3 工具选择流程图\n\n```mermaid\ngraph TD\n A[用户自然语言查询] --> B{GPT-5 Nano 意图分析}\n B -->|代码/框架文档| C[Context7 工具]\n B -->|艺术品/博物馆| D[MetMuseum 工具]\n B -->|其他| E[无工具调用]\n C --> F[返回文档内容]\n D --> G[返回艺术品数据]\n E --> H[直接生成回复]\n```\n\n## 系统消息配置\n\n### 9.1 智能体角色定义\n\n```python\n{\"role\": \"system\", \"content\": \"You are a smart, useful agent with tools to access code library documentation and the Met Museum collection.\"}\n```\n\n资料来源：[main.py:72-73](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n### 9.2 消息类型\n\n| 消息角色 | 来源 | 内容示例 |\n|---------|------|---------|\n| system | 系统定义 | 智能体角色设定 |\n| user | 用户输入 | 用户的自然语言问题 |\n| assistant | 智能体生成 | 最终响应内容 |\n\n## 依赖安装\n\n### 10.1 Python 依赖\n\n```bash\npip install langchain-mcp-adapters langgraph langchain-openai\n```\n\n### 10.2 Node.js 环境\n\n```bash\nnpm install -g npx\n```\n\n### 10.3 环境变量配置\n\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n## 技术栈总结\n\n| 层级 | 技术选型 | 版本 | 关键作用 |\n|------|---------|------|---------|\n| 运行时 | Python 3.10+ | 3.10+ | 主要开发语言 |\n| 智能体框架 | LangGraph ReAct | 最新 | 推理与工具调用编排 |\n| 大语言模型 | GPT-5 Nano | - | 自然语言理解和生成 |\n| MCP 客户端 | MultiServerMCPClient | 最新 | 多服务器连接管理 |\n| 会话持久化 | InMemorySaver | 最新 | 对话历史记忆 |\n| 异步框架 | asyncio | 标准库 | 非阻塞 I/O 操作 |\n| 文档服务器 | Context7 | HTTP | 库文档查询 |\n| 博物馆服务器 | MetMuseum-MCP | STDIO | 艺术品数据查询 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md), [main.py:1-7](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n\n---\n\n\n\n## 系统架构设计\n\n### 相关页面\n\n相关主题：[项目概览](#page-1), [LangGraph ReAct代理实现](#page-4), [MultiServerMCPClient配置](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n \n\n# 系统架构设计\n\n## 概述\n\nmcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器 AI 代理系统，旨在为用户提供统一的接口来访问多个外部服务。该系统利用 LangGraph ReAct 架构实现自主工具选择，并支持 STDIO 和 HTTP 两种传输协议的并发管理。资料来源：[README.md:1]()、[main.py:1-10]()\n\n### 项目定位\n\n该系统被定位为 **\"通用接口\"**，类似于 USB-C 在硬件连接中的作用，能够同时连接多个 MCP 服务器，支持持久化对话记忆，并基于 GPT-5 Nano 模型实现自主工具调用能力。资料来源：[README.md:3]()\n\n### 技术领域\n\n| 领域 | 说明 |\n|------|------|\n| 代理类型 | 多服务器 MCP 代理 |\n| 编程语言 | Python 3.10+ |\n| LLM 模型 | OpenAI GPT-5 Nano |\n| 代理框架 | LangGraph ReAct with 持久化内存 |\n\n## 核心架构组件\n\n### 系统层级结构\n\n```\n┌──────────────────────────────────────────────────────┐\n│ 用户层 (CLI 交互界面) │\n│ \"梵高创作了哪些画作？\" │\n│ \"展示 LangChain 文档\" │\n└───────────────────────┬──────────────────────────────┘\n │\n┌───────────────────────▼──────────────────────────────┐\n│ LangGraph ReAct 代理层 │\n│ • GPT-5 Nano 推理引擎 │\n│ • InMemorySaver 线程级对话记忆 │\n│ • 自主选择调用哪个 MCP 服务器 │\n└──────────┬────────────────────────┬──────────────────┘\n │ │\n HTTP 传输 STDIO 传输\n │ │\n┌──────────▼──────────┐ ┌─────────▼──────────────────┐\n│ Context7 服务器 │ │ MetMuseum-MCP 服务器 │\n│ (远程/云端) │ │ (本地通过 npx 运行) │\n│ │ │ │\n│ 主流框架/库的 LLM │ │ 大都会艺术博物馆 │\n│ 优化文档搜索 │ │ 400,000+ 艺术品 │\n└─────────────────────┘ └─────────────────────────────┘\n```\n\n### 技术栈明细\n\n| 组件类别 | 技术选型 | 版本要求 |\n|----------|----------|----------|\n| 编程语言 | Python | 3.10+ |\n| MCP 客户端 | MultiServerMCPClient (langchain-mcp-adapters) | 最新稳定版 |\n| 代理框架 | LangGraph ReAct | 最新稳定版 |\n| LLM | ChatOpenAI (GPT-5 Nano) | OpenAI API |\n| 对话记忆 | InMemorySaver | LangGraph 内置 |\n| 异步支持 | asyncio | Python 标准库 |\n| MCP 服务器 1 | Context7 | HTTP 流式传输 |\n| MCP 服务器 2 | MetMuseum-MCP | STDIO 本地执行 |\n\n资料来源：[README.md:56-66]()\n\n## 通信传输机制\n\n### HTTP 传输 (Context7)\n\nContext7 服务器通过 `streamable_http` 协议实现远程通信。这种方式适合云端部署的文档服务，具有以下特点：\n\n- **传输协议**：`streamable_http`\n- **端点地址**：`https://mcp.context7.com/mcp`\n- **部署模式**：远程/云端\n- **适用场景**：需要访问大型软件框架文档库的场景\n\n```python\n\"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n}\n```\n\n资料来源：[main.py:21-24]()\n\n### STDIO 传输 (MetMuseum)\n\nMetMuseum MCP 服务器通过标准输入输出（STDIO）协议实现本地通信：\n\n- **传输协议**：`stdio`\n- **执行命令**：`npx -y metmuseum-mcp`\n- **部署模式**：本地通过 Node.js npx 执行\n- **适用场景**：本地艺术品数据查询\n\n```python\n\"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n}\n```\n\n资料来源：[main.py:25-29]()\n\n## 代理工作流程\n\n### 完整请求处理流程\n\n```mermaid\ngraph TD\n A[用户输入查询] --> B{GPT-5 Nano 推理}\n B --> C[\"判断查询类型\"]\n C -->|代码/库文档| D[Context7 HTTP 调用]\n C -->|艺术品/博物馆| E[MetMuseum STDIO 调用]\n D --> F[获取文档数据]\n E --> G[获取艺术品元数据]\n F --> H[结果返回 LLM]\n G --> H\n H --> I[LLM 生成自然语言响应]\n I --> J[InMemorySaver 保存对话]\n J --> K[用户接收响应]\n```\n\n### 工具自主选择机制\n\n代理能够根据用户查询内容自主判断应调用哪个 MCP 服务器：\n\n| 用户查询示例 | 调用服务器 | 返回数据类型 |\n|--------------|------------|--------------|\n| \"LangChain 代理工具是什么？\" | Context7 | LLM 优化文档 |\n| \"展示大都会博物馆的印象派画作\" | MetMuseum | 艺术品元数据及图片 |\n\n资料来源：[README.md:42-51]()\n\n## 核心模块设计\n\n### MCP 客户端模块\n\n```python\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\n\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n }\n})\n\ntools = await client.get_tools()\n```\n\n该模块负责同时连接多个 MCP 服务器，并聚合所有可用的工具供代理使用。资料来源：[main.py:13-29]()\n\n### LLM 模型配置\n\n```python\nfrom langchain_openai import ChatOpenAI\n\nopenai_model = ChatOpenAI(\n model=\"gpt-5-nano\",\n)\n```\n\n使用 OpenAI 的 GPT-5 Nano 模型作为推理引擎，该模型负责理解用户意图并进行工具调用决策。资料来源：[main.py:37-39]()\n\n### ReAct 代理创建\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.checkpoint.memory import InMemorySaver\n\ncheckpointer = InMemorySaver()\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer,\n)\n```\n\nReAct 代理结合了推理（Reasoning）和行动（Acting）能力，通过 checkpointer 实现对话记忆持久化。资料来源：[main.py:42-52]()\n\n### 对话记忆系统\n\n```python\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n\nresponse = await agent.ainvoke(\n {\"messages\": query},\n config=config\n)\n```\n\nInMemorySaver 提供了线程级别的对话历史持久化，确保代理在多轮对话中保持上下文理解能力。资料来源：[main.py:72-77]()\n\n## 交互流程设计\n\n### 启动与初始化\n\n1. 配置 MultiServerMCPClient 连接两个 MCP 服务器\n2. 初始化 ChatOpenAI 模型\n3. 获取所有可用工具\n4. 创建 InMemorySaver 检查点\n5. 构建 ReAct 代理实例\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as LangGraph Agent\n participant Client as MCP Client\n participant Context7 as Context7 Server\n participant MetMuseum as MetMuseum Server\n\n User->>Agent: 启动程序\n Client->>Context7: 建立 HTTP 连接\n Client->>MetMuseum: 启动 npx 进程 (STDIO)\n Client->>Agent: 获取工具列表\n Agent->>User: 显示初始介绍\n\n loop 主交互循环\n User->>Agent: 输入问题\n Agent->>Agent: GPT-5 Nano 推理\n Agent->>Client: 调用工具\n Client->>Context7: 查询文档 (可选)\n Client->>MetMuseum: 查询艺术品 (可选)\n Context7-->>Client: 返回文档数据\n MetMuseum-->>Client: 返回艺术品数据\n Client-->>Agent: 工具执行结果\n Agent->>Agent: 生成自然语言响应\n Agent-->>User: 返回最终回答\n end\n```\n\n### 菜单交互模式\n\n系统提供基于菜单的交互方式：\n\n```\nMenu:\n1. Ask the agent a question\n2. Quit\nEnter your choice (1 or 2):\n```\n\n- 选择 \"1\"：进入问答模式，代理接收并处理用户查询\n- 选择 \"2\"：退出程序\n\n资料来源：[main.py:57-85]()\n\n## 数据流设计\n\n### 消息传递机制\n\n```mermaid\ngraph LR\n A[用户消息] --> B[系统消息配置]\n B --> C[消息数组]\n C --> D[agent.ainvoke 调用]\n D --> E[LangGraph 状态机]\n E --> F[工具执行]\n F --> G[结果聚合]\n G --> H[LLM 响应生成]\n H --> I[最终输出]\n```\n\n### 配置参数表\n\n| 参数名称 | 类型 | 说明 | 默认值 |\n|----------|------|------|--------|\n| thread_id | string | 对话线程标识符 | \"conversation_id\" |\n| model | string | LLM 模型名称 | \"gpt-5-nano\" |\n| transport | string | 通信传输协议 | streamable_http / stdio |\n\n资料来源：[main.py:45-47]()\n\n## 系统初始化代码结构\n\n```python\nasync def main():\n \"\"\"主函数：设置并运行具有多个 MCP 服务器访问权限的 AI 代理\"\"\"\n\n # 1. 配置 MCP 服务器\n client = MultiServerMCPClient({...})\n\n # 2. 初始化 OpenAI 语言模型\n openai_model = ChatOpenAI(model=\"gpt-5-nano\")\n\n # 3. 获取所有可用工具\n tools = await client.get_tools()\n\n # 4. 设置对话记忆\n checkpointer = InMemorySaver()\n config = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n\n # 5. 创建 ReAct 代理\n agent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer,\n )\n\n # 6. 发送初始介绍消息\n response = await agent.ainvoke({...}, config=config)\n\n # 7. 主交互循环\n while True:\n choice = input(\"Menu:...\")\n if choice == \"1\":\n query = input(\"> \")\n response = await agent.ainvoke({\"messages\": query}, config=config)\n print(response['messages'][-1].content)\n```\n\n资料来源：[main.py:12-85]()\n\n## 关键设计决策\n\n### 多服务器架构优势\n\n| 优势 | 说明 |\n|------|------|\n| 能力扩展性 | 可通过添加新 MCP 服务器无缝扩展功能 |\n| 协议兼容性 | 同时支持 STDIO 和 HTTP 两种传输协议 |\n| 自主路由 | LLM 自动选择最合适的服务器处理查询 |\n| 持久化记忆 | InMemorySaver 确保多轮对话上下文连贯 |\n\n### 技术选型理由\n\n| 组件 | 选型理由 |\n|------|----------|\n| LangGraph | 提供成熟的 ReAct 代理实现和状态管理 |\n| MultiServerMCPClient | 原生支持多服务器并发连接 |\n| InMemorySaver | 轻量级内存存储，适合演示和小规模部署 |\n| GPT-5 Nano | 成本效益高的推理模型，适合工具调用场景 |\n\n资料来源：[README.md:4-12]()\n\n## 依赖安装指南\n\n### Python 依赖\n\n```bash\npip install langchain-mcp-adapters langgraph langchain-openai\n```\n\n### Node.js 依赖\n\n```bash\nnpm install -g npx\n```\n\n### 环境变量配置\n\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n资料来源：[README.md:30-36]()\n\n## 启动与运行\n\n### 运行命令\n\n```bash\npython main.py\n```\n\n### 执行流程\n\n1. 初始化 MCP 客户端连接\n2. 加载可用的工具\n3. 代理自我介绍\n4. 进入主菜单循环\n5. 处理用户查询并返回结果\n\n资料来源：[main.py:88-91]()\n\n---\n\n\n\n## LangGraph ReAct代理实现\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-3), [持久化对话记忆机制](#page-5), [MultiServerMCPClient配置](#page-6)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n \n\n# LangGraph ReAct代理实现\n\n## 概述\n\nLangGraph ReAct代理是该项目的核心智能组件，负责协调用户查询、MCP服务器工具调用以及对话记忆管理。该代理基于LangGraph框架的ReAct（Reasoning + Acting）设计模式构建，结合OpenAI GPT-5 Nano模型实现自主工具选择和自然语言响应生成功能。\n\n## 核心架构\n\n### 系统组件关系\n\n```mermaid\ngraph TD\n A[用户 CLI 交互] --> B[LangGraph ReAct Agent]\n B --> C[GPT-5 Nano 模型]\n C --> D{自主工具选择}\n D --> E[Context7 HTTP]\n D --> F[MetMuseum STDIO]\n E --> G[工具执行结果]\n F --> G\n G --> C\n C --> H[自然语言响应]\n H --> I[InMemorySaver 记忆存储]\n I --> B\n```\n\n### 技术栈概览\n\n| 组件 | 技术实现 | 版本要求 |\n|------|----------|----------|\n| 代理框架 | `create_react_agent` | langgraph |\n| 语言模型 | `ChatOpenAI` | langchain-openai |\n| MCP客户端 | `MultiServerMCPClient` | langchain-mcp-adapters |\n| 对话记忆 | `InMemorySaver` | langgraph.checkpoint.memory |\n| 传输协议 | STDIO + streamable_http | 混合模式 |\n\n## 代理初始化流程\n\n### 源码实现解析\n\n代理的初始化过程包含四个关键步骤：\n\n```python\n# 第一步：配置MCP服务器连接\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n }\n})\n```\n\n资料来源：[main.py:33-45]()\n\n```python\n# 第二步：初始化OpenAI语言模型\nopenai_model = ChatOpenAI(model=\"gpt-5-nano\")\n```\n\n资料来源：[main.py:49-50]()\n\n```python\n# 第三步：获取所有MCP服务器工具\ntools = await client.get_tools()\n```\n\n资料来源：[main.py:52]()\n\n```python\n# 第四步：创建ReAct代理\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=InMemorySaver()\n)\n```\n\n资料来源：[main.py:58-62]()\n\n### 初始化参数说明\n\n| 参数 | 类型 | 说明 | 来源配置 |\n|------|------|------|----------|\n| model | ChatOpenAI | 提供推理和响应生成能力 | 必须 |\n| tools | List[BaseTool] | 从MCP服务器获取的工具集合 | 必须 |\n| checkpointer | InMemorySaver | 持久化对话历史记录 | 可选 |\n\n## ReAct执行机制\n\n### 推理与行动循环\n\nLangGraph ReAct代理采用\"推理-行动\"循环模式处理用户查询：\n\n```mermaid\ngraph TD\n A[用户查询输入] --> B[Reasoning: 分析查询意图]\n B --> C{判断是否需要调用工具?}\n C -->|是| D[Action: 选择合适工具]\n D --> E[Execute: 执行工具调用]\n E --> F[Observation: 获取工具返回结果]\n F --> B\n C -->|否| G[Final Response: 直接生成响应]\n```\n\n### 对话上下文管理\n\n代理通过线程ID机制维护多轮对话上下文：\n\n```python\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n\nresponse = await agent.ainvoke(\n {\"messages\": query},\n config=config\n)\n```\n\n资料来源：[main.py:54-60]()\n\n**上下文管理特点：**\n\n- 每个会话拥有唯一thread_id\n- 所有历史消息自动持久化到InMemorySaver\n- 后续查询自动携带完整对话上下文\n\n## MCP服务器集成\n\n### 多服务器连接架构\n\n```mermaid\ngraph LR\n A[ReAct Agent] <-->|统一工具接口| B[MultiServerMCPClient]\n B -->|streamable_http| C[Context7 Server]\n B -->|stdio| D[MetMuseum MCP]\n```\n\n### 服务器配置对比\n\n| 服务器 | 传输协议 | 用途 | 连接参数 |\n|--------|----------|------|----------|\n| Context7 | HTTP | 代码库文档检索 | URL: https://mcp.context7.com/mcp |\n| MetMuseum | STDIO | 博物馆藏品查询 | command: npx, args: metmuseum-mcp |\n\n### 工具自动路由\n\n代理根据查询内容自动选择目标服务器：\n\n```\n用户: \"LangChain代理相关文档\" → Context7服务器\n用户: \"梵高的绘画作品\" → MetMuseum服务器\n```\n\n## 对话流程实现\n\n### 主交互循环\n\n```python\nwhile True:\n choice = input(\"\"\"\nMenu:\n1. Ask the agent a question\n2. Quit\nEnter your choice (1 or 2): \"\"\")\n\n if choice == \"1\":\n query = input(\"> \")\n response = await agent.ainvoke(\n {\"messages\": query},\n config=config\n )\n print(response['messages'][-1].content)\n else:\n break\n```\n\n资料来源：[main.py:71-84]()\n\n### 异步执行模式\n\n整个应用采用异步架构，通过asyncio事件循环驱动：\n\n```python\nasync def main():\n # 异步初始化和代理执行\n ...\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n资料来源：[main.py:24-89]()\n\n## 代理系统提示\n\n代理初始化时注入系统级提示词，定义其角色定位：\n\n```python\n{\"role\": \"system\", \"content\": \"You are a smart, useful agent with tools to access code library documentation and the Met Museum collection.\"}\n```\n\n资料来源：[main.py:67]()\n\n## 关键特性总结\n\n### 核心能力矩阵\n\n| 特性 | 实现方式 | 技术依赖 |\n|------|----------|----------|\n| 多服务器并发 | MultiServerMCPClient | langchain-mcp-adapters |\n| 持久化记忆 | InMemorySaver | langgraph.checkpoint.memory |\n| 自主工具选择 | LLM推理 | GPT-5 Nano |\n| 对话连续性 | thread_id配置 | LangGraph checkpointer |\n| 异步通信 | asyncio | Python标准库 |\n\n### 执行流程总览\n\n```mermaid\ngraph LR\n A[CLI Input] --> B[ReAct Agent]\n B --> C[LLM Reasoning]\n C --> D[Tool Selection]\n D --> E[MCP Tool Call]\n E --> F[Result Aggregation]\n F --> G[LLM Response]\n G --> H[Memory Update]\n H --> I[User Output]\n```\n\n## 扩展与定制\n\n### 修改系统提示\n\n如需自定义代理行为，修改main.py中的system message内容：\n\n```python\n{\"role\": \"system\", \"content\": \"自定义代理描述\"}\n```\n\n### 添加新MCP服务器\n\n在MultiServerMCPClient配置中追加新的服务器条目：\n\n```python\nclient = MultiServerMCPClient({\n \"context7\": {...},\n \"met-museum\": {...},\n \"new-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"new-mcp-package\"],\n \"transport\": \"stdio\",\n }\n})\n```\n\n### 更换语言模型\n\n调整ChatOpenAI初始化参数以使用其他模型：\n\n```python\nopenai_model = ChatOpenAI(model=\"gpt-4\")\n\n---\n\n\n\n## 持久化对话记忆机制\n\n### 相关页面\n\n相关主题：[LangGraph ReAct代理实现](#page-4), [运行与交互指南](#page-9)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n \n\n# 持久化对话记忆机制\n\n## 概述\n\n持久化对话记忆机制是 mcp-ai-agent 项目中的核心功能模块，负责在多轮对话场景下维护用户与智能体之间的完整交流上下文。该机制基于 LangGraph 框架的 Checkpointer 实现，通过线程（Thread）隔离不同会话，确保每次对话交互都能回溯历史消息并进行连贯推理。\n\n## 核心组件\n\n### 1. InMemorySaver\n\n`InMemorySaver` 是 LangGraph 框架提供的内存检查点保存器，负责存储对话状态快照。\n\n| 属性 | 说明 |\n|------|------|\n| 类型 | 内存存储 |\n| 来源 | `langgraph.checkpoint.memory` |\n| 用途 | 持久化对话历史记录 |\n| 生命周期 | 进程运行期间有效 |\n\n```python\nfrom langgraph.checkpoint.memory import InMemorySaver\n\ncheckpointer = InMemorySaver()\n```\n\n资料来源：[main.py:28]()\n\n### 2. 会话配置（Config）\n\n会话配置定义了对话线程的唯一标识符，是实现多会话隔离的关键参数。\n\n| 参数 | 类型 | 默认值 | 说明 |\n|------|------|--------|------|\n| `thread_id` | string | \"conversation_id\" | 会话线程唯一标识 |\n\n```python\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n资料来源：[main.py:67]()\n\n### 3. ReAct Agent 集成\n\n检查点保存器通过 `create_react_agent` 函数注入到智能体中，使智能体具备状态持久化能力。\n\n```python\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer\n)\n```\n\n资料来源：[main.py:70-74]()\n\n## 工作流程\n\n```mermaid\ngraph TD\n A[用户提问] --> B[构建查询消息]\n B --> C[调用 agent.ainvoke]\n C --> D{检查 thread_id}\n D -->|新会话| E[创建新线程]\n D -->|已有会话| F[加载历史状态]\n E --> G[执行推理与工具调用]\n F --> G\n G --> H[生成响应]\n H --> I[保存状态到 InMemorySaver]\n I --> J[返回响应给用户]\n J --> K[等待下一轮交互]\n K --> A\n```\n\n## 状态持久化流程\n\n```mermaid\nsequenceDiagram\n participant U as 用户\n participant A as ReAct Agent\n participant C as InMemorySaver\n participant M as LLM\n\n U->>A: 第一轮: 查询消息\n A->>C: 保存状态快照\n C-->>A: 确认保存\n A-->>U: 返回响应\n\n U->>A: 第二轮: 新查询\n A->>C: 加载 thread_id 对应状态\n C-->>A: 返回历史消息\n A->>M: 发送完整上下文\n M-->>A: 生成响应\n A->>C: 更新状态快照\n A-->>U: 返回响应\n```\n\n## 核心代码解析\n\n### 主函数入口\n\n```python\nasync def main():\n # 初始化 MCP 服务器客户端\n client = MultiServerMCPClient({...})\n\n # 初始化 LLM 模型\n openai_model = ChatOpenAI(model=\"gpt-5-nano\")\n\n # 获取 MCP 服务器提供的工具\n tools = await client.get_tools()\n\n # 创建内存检查点保存器\n checkpointer = InMemorySaver()\n\n # 配置会话参数\n config = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n\n # 创建带持久化功能的 ReAct Agent\n agent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer\n )\n```\n\n资料来源：[main.py:31-75]()\n\n### 智能体调用\n\n```python\n # 发送用户查询，附带会话配置\n response = await agent.ainvoke(\n {\"messages\": query},\n config=config\n )\n\n # 输出智能体响应\n print(response['messages'][-1].content)\n```\n\n资料来源：[main.py:88-94]()\n\n## 会话状态管理\n\n```mermaid\ngraph LR\n subgraph 状态结构\n S1[消息列表] --> S2[System 消息]\n S1 --> S3[User 消息]\n S1 --> S4[Assistant 消息]\n S1 --> S5[Tool 调用记录]\n end\n\n subgraph 持久化存储\n P1[InMemorySaver]\n P1 -.->|存储| S1\n P1 -.->|检索| S2\n P1 -.->|检索| S3\n P1 -.->|检索| S4\n P1 -.->|检索| S5\n end\n```\n\n## 消息格式\n\n对话中的消息采用标准角色格式存储：\n\n| 角色 | 说明 | 示例 |\n|------|------|------|\n| `system` | 系统级指令 | 定义智能体角色定位 |\n| `user` | 用户输入 | 用户提出的问题 |\n| `assistant` | 智能体响应 | 包含文本和工具调用 |\n| `tool` | 工具执行结果 | MCP 服务器返回的数据 |\n\n```python\n{\"messages\": [\n {\"role\": \"system\", \"content\": \"You are a smart, useful agent...\"},\n {\"role\": \"user\", \"content\": \"用户问题内容\"},\n]}\n```\n\n资料来源：[main.py:77-82]()\n\n## 初始化流程\n\n智能体启动时会执行自我介绍，让用户了解其能力范围：\n\n```python\nresponse = await agent.ainvoke(\n {\"messages\": [\n {\"role\": \"system\", \"content\": \"You are a smart, useful agent with tools to access code library documentation and the Met Museum collection.\"},\n {\"role\": \"user\", \"content\": \"Give a brief introduction of what you do and the tools you can access.\"},\n ]},\n config=config\n)\nprint(response['messages'][-1].content)\n```\n\n资料来源：[main.py:77-86]()\n\n## 应用场景\n\n### 单会话连续对话\n\n用户在同一会话中提出多个相关问题，智能体能够理解上下文关联：\n\n```\n用户: \"LangGraph 的工具调用是什么？\"\n智能体: [调用 Context7 获取文档]\n\n用户: \"能给我一个代码示例吗？\"\n智能体: [基于上一轮上下文生成示例]\n```\n\n### 上下文关联推理\n\n记忆机制使智能体能够：\n\n- 记住用户之前提到的技术栈或偏好\n- 基于历史查询提供个性化响应\n- 在多轮调试场景中理解问题演进过程\n\n## 限制与注意事项\n\n| 限制项 | 说明 |\n|--------|------|\n| 内存依赖 | 进程重启后记忆丢失 |\n| 并发限制 | 多进程需要外部存储后端 |\n| 线程隔离 | 不同 `thread_id` 完全独立 |\n\n如需生产环境持久化，应替换为 `PostgresSaver` 或 `RedisSaver` 等外部存储适配器。\n\n## 依赖关系\n\n```mermaid\ngraph TD\n A[main.py] --> B[langgraph.checkpoint.memory]\n A --> C[langgraph.prebuilt.create_react_agent]\n A --> D[langchain_openai.ChatOpenAI]\n B --> E[InMemorySaver 类]\n C --> F[ReAct Agent 工厂函数]\n```\n\n## 扩展建议\n\n如需增强持久化能力，可考虑以下方案：\n\n1. **数据库持久化**：集成 PostgreSQL 或 SQLite\n2. **分布式存储**：使用 Redis 实现跨进程共享\n3. **会话管理**：实现会话超时自动清理机制\n4. **状态序列化**：支持对话历史导出与恢复\n\n---\n\n\n\n## MultiServerMCPClient配置\n\n### 相关页面\n\n相关主题：[系统架构设计](#page-3), [集成MCP服务器详解](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n \n\n# MultiServerMCPClient配置\n\n## 概述\n\nMultiServerMCPClient 是 langchain-mcp-adapters 库提供的核心客户端类，用于同时连接多个 MCP（Model Context Protocol）服务器。在本项目中，该客户端被配置为同时管理 HTTP 和 STDIO 两种传输协议的 MCP 服务器连接，使 LangGraph ReAct Agent 能够自主选择并调用来自不同域的工具。\n\n**核心作用：**\n\n- 统一管理多个 MCP 服务器的连接生命周期\n- 支持异构传输协议（HTTP/STDIO）的并发连接\n- 聚合来自不同服务器的可用工具，供 Agent 调用\n\n资料来源：[main.py:12]()\n\n## 架构设计\n\n### 多服务器连接架构\n\n```mermaid\ngraph TD\n A[\"LangGraph ReAct Agent\"] --> B[\"MultiServerMCPClient\"]\n B --> C[\"Context7 Server
(HTTP)\"]\n B --> D[\"MetMuseum Server
(STDIO)\"]\n C --> E[\"远程云端
文档搜索服务\"]\n D --> F[\"本地 npx
博物馆数据服务\"]\n \n style A fill:#e1f5fe\n style B fill:#fff3e0\n```\n\n### 传输协议对比\n\n| 传输协议 | 实现方式 | 适用场景 | 延迟特性 |\n|---------|---------|---------|---------|\n| **streamable_http** | HTTP 长连接 | 远程云服务 | 中等延迟 |\n| **stdio** | 标准输入输出 | 本地 Node.js 服务 | 低延迟 |\n\n资料来源：[main.py:38-47]()\n\n## 配置参数详解\n\n### MultiServerMCPClient 构造函数参数\n\n```python\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n }\n})\n```\n\n### 服务器配置结构\n\n| 参数名 | 类型 | 说明 | 必填 |\n|-------|------|------|-----|\n| `command` | string | 进程启动命令 | STDIO 传输时必填 |\n| `args` | list[string] | 命令行参数列表 | STDIO 传输时必填 |\n| `url` | string | 服务器端点 URL | HTTP 传输时必填 |\n| `transport` | string | 传输协议类型 | 是 |\n\n### Context7 服务器配置\n\n```python\n\"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\", # 服务器端点\n \"transport\": \"streamable_http\", # HTTP 流式传输\n}\n```\n\n**配置说明：**\n\n- 该服务器提供 LLM 优化的软件框架文档搜索能力\n- 传输协议使用 `streamable_http`，适合与远程云端服务通信\n- 无需本地进程管理，服务端自动处理连接\n\n### MetMuseum 服务器配置\n\n```python\n\"met-museum\": {\n \"command\": \"npx\", # Node.js 包运行器\n \"args\": [\"-y\", \"metmuseum-mcp\"], # 自动安装并运行\n \"transport\": \"stdio\", # 标准输入输出传输\n}\n```\n\n**配置说明：**\n\n- 使用 npx 自动安装并运行 `metmuseum-mcp` 包\n- STDIO 传输通过标准输入输出与本地 Node.js 进程通信\n- 适合需要本地执行环境的工具服务\n\n## 工具获取与使用\n\n### 获取所有工具\n\n```python\ntools = await client.get_tools()\n```\n\n该方法异步获取所有已配置 MCP 服务器提供的工具集合，返回的 `tools` 列表包含来自 Context7 和 MetMuseum 两个服务器的所有可用工具。\n\n### 工具聚合机制\n\n```mermaid\ngraph LR\n A[\"Context7 Tools\"] --> C[\"统一 Tools 列表\"]\n B[\"MetMuseum Tools\"] --> C\n C --> D[\"ReAct Agent\"]\n```\n\n## 与 LangGraph Agent 集成\n\n### 完整集成流程\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as LangGraph ReAct\n participant Client as MultiServerMCPClient\n participant Servers as MCP Servers\n\n User->>Agent: 发送查询\n Agent->>Client: await client.get_tools()\n Client->>Servers: 获取工具定义\n Servers-->>Client: 返回工具列表\n Client-->>Agent: 聚合工具集\n Agent->>Servers: 调用选中工具\n Servers-->>Agent: 返回结果\n Agent-->>User: 自然语言响应\n```\n\n### Agent 创建代码\n\n```python\n# 初始化 OpenAI 模型\nopenai_model = ChatOpenAI(model=\"gpt-5-nano\")\n\n# 获取工具\ntools = await client.get_tools()\n\n# 创建 ReAct Agent\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=InMemorySaver()\n)\n```\n\n## 异步编程模式\n\n### main 函数异步设计\n\n```python\nasync def main():\n client = MultiServerMCPClient({...})\n tools = await client.get_tools()\n agent = create_react_agent(model, tools, checkpointer)\n # 异步调用\n response = await agent.ainvoke({\"messages\": query}, config=config)\n```\n\n### 事件循环执行\n\n```python\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n**要点说明：**\n\n- 所有涉及 MCP 客户端的操作必须使用 `async/await` 模式\n- 顶层入口通过 `asyncio.run()` 启动事件循环\n- Agent 调用同样采用异步方式 `await agent.ainvoke()`\n\n## 生命周期管理\n\n### 连接初始化\n\n| 阶段 | 操作 | 说明 |\n|-----|------|-----|\n| 1 | 创建 MultiServerMCPClient 实例 | 配置服务器参数 |\n| 2 | 获取工具集 | `await client.get_tools()` |\n| 3 | 创建 Agent | 绑定模型和工具 |\n| 4 | 启动交互循环 | 处理用户查询 |\n\n### 资源清理\n\nMultiServerMCPClient 在上下文管理器退出或程序终止时自动关闭所有服务器连接。\n\n## 配置最佳实践\n\n### 开发环境配置建议\n\n| 场景 | 推荐配置 |\n|-----|---------|\n| 本地开发 | 使用 STDIO 传输，便于调试 |\n| 生产部署 | 优先使用 HTTP 传输，稳定性更高 |\n| 混合场景 | 按服务特性选择传输协议 |\n\n### 扩展新服务器\n\n添加新 MCP 服务器只需在配置字典中增加条目：\n\n```python\nclient = MultiServerMCPClient({\n \"context7\": {...},\n \"met-museum\": {...},\n \"新服务器名称\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"新服务包名\"],\n \"transport\": \"stdio\",\n }\n})\n```\n\nAgent 会自动发现并聚合新增服务器的工具，无需修改 Agent 创建代码。\n\n## 依赖项\n\n| 依赖包 | 版本要求 | 用途 |\n|-------|---------|------|\n| langchain-mcp-adapters | 最新版 | MultiServerMCPClient |\n| langgraph | 最新版 | ReAct Agent 框架 |\n| langchain-openai | 最新版 | OpenAI 模型集成 |\n| asyncio | Python 3.10+ 内置 | 异步编程支持 |\n\n资料来源：[main.py:1-11]()\n\n---\n\n\n\n## 集成MCP服务器详解\n\n### 相关页面\n\n相关主题：[MultiServerMCPClient配置](#page-6), [扩展与定制指南](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n \n\n# 集成MCP服务器详解\n\n## 概述\n\n`集成MCP服务器详解`是本项目的核心功能模块，展示了如何构建一个**多服务器MCP（Model Context Protocol）客户端代理**系统。该系统能够同时连接多个不同传输协议的MCP服务器，实现跨域工具调用与智能工具选择能力。\n\n本项目通过`MultiServerMCPClient`同时管理HTTP和STDIO两种传输协议的MCP服务器，结合LangGraph ReAct Agent架构和OpenAI GPT-5 Nano模型，构建了一个具有持久化会话记忆的多功能AI代理。\n\n资料来源：[main.py:1-20](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L1-L20)\n\n---\n\n## 架构设计\n\n### 系统整体架构\n\n本项目采用分层架构设计，从上至下依次为：用户交互层、Agent推理层、MCP客户端层和服务器连接层。\n\n```mermaid\ngraph TD\n A[\"用户 CLI 交互层\"] --> B[\"LangGraph ReAct Agent\"]\n B --> C[\"MultiServerMCPClient 客户端\"]\n C --> D1[\"Context7 Server
HTTP 传输\"]\n C --> D2[\"MetMuseum-MCP Server
STDIO 传输\"]\n E[\"OpenAI GPT-5 Nano\"] --> B\n F[\"InMemorySaver 记忆系统\"] --> B\n```\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n### 核心组件职责\n\n| 组件层 | 组件名称 | 职责描述 |\n|--------|----------|----------|\n| 用户层 | CLI交互界面 | 提供菜单选择和问题输入功能 |\n| 推理层 | LangGraph ReAct Agent | 负责推理决策和工具调用编排 |\n| 模型层 | ChatOpenAI (GPT-5 Nano) | 提供LLM推理能力 |\n| 记忆层 | InMemorySaver | 维护会话历史和线程状态 |\n| 客户端层 | MultiServerMCPClient | 管理多个MCP服务器连接 |\n| 服务器层 | Context7 / MetMuseum | 提供具体业务工具 |\n\n资料来源：[main.py:1-20](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L1-L20)\n\n---\n\n## MCP服务器配置详解\n\n### 配置文件结构\n\n`MultiServerMCPClient`接受一个字典参数，键为服务器标识名，值为服务器配置对象。配置对象必须包含`transport`字段来指定传输类型。\n\n```python\nclient = MultiServerMCPClient({\n \"服务器标识名\": {\n \"transport\": \"传输类型\",\n # 其他配置项...\n }\n})\n```\n\n资料来源：[main.py:22-40](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L22-L40)\n\n### Context7服务器配置（HTTP传输）\n\nContext7是一个远程云端MCP服务器，提供主流软件框架和库的文档搜索功能。\n\n| 参数 | 值 | 说明 |\n|------|-----|------|\n| 传输协议 | `streamable_http` | 支持流式HTTP通信 |\n| 端点URL | `https://mcp.context7.com/mcp` | 服务器远程地址 |\n| 连接类型 | 远程/云端 | 无需本地安装 |\n\n```python\n\"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n}\n```\n\n资料来源：[main.py:23-26](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L23-L26)\n\n### MetMuseum服务器配置（STDIO传输）\n\nMetMuseum是一个本地MCP服务器，通过npx执行，提供大都会艺术博物馆的藏品数据访问。\n\n| 参数 | 值 | 说明 |\n|------|-----|------|\n| 传输协议 | `stdio` | 通过标准输入输出通信 |\n| 执行命令 | `npx` | Node.js包执行器 |\n| 启动参数 | `[\"-y\", \"metmuseum-mcp\"]` | 自动确认安装并运行 |\n| 连接类型 | 本地/STDIO | 需Node.js环境支持 |\n\n```python\n\"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n}\n```\n\n资料来源：[main.py:28-32](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L28-L32)\n\n### 传输协议对比\n\n| 特性 | HTTP传输（streamable_http） | STDIO传输 |\n|------|----------------------------|----------|\n| 通信方式 | 基于HTTP的请求响应/流式 | 标准输入输出管道 |\n| 部署模式 | 远程云服务 | 本地进程 |\n| 依赖 | 网络连接 | Node.js + npm |\n| 延迟 | 依赖网络质量 | 本地进程，延迟低 |\n| 适用场景 | 公共服务、文档查询 | 本地工具、数据访问 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n---\n\n## Agent构建流程\n\n### 初始化步骤总览\n\nAgent的构建分为五个主要步骤：导入依赖、配置MCP客户端、初始化LLM、获取工具集、创建ReAct代理。\n\n```mermaid\ngraph LR\n A[\"导入依赖\"] --> B[\"配置MultiServerMCPClient\"]\n B --> C[\"初始化ChatOpenAI模型\"]\n C --> D[\"获取所有工具 await client.get_tools()\"]\n D --> E[\"配置InMemorySaver\"]\n E --> F[\"创建create_react_agent\"]\n```\n\n资料来源：[main.py:44-70](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L44-L70)\n\n### 第一步：导入依赖\n\n```python\nimport asyncio\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.checkpoint.memory import InMemorySaver\nfrom langchain_openai import ChatOpenAI\n```\n\n资料来源：[main.py:1-6](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L1-L6)\n\n| 导入模块 | 来源库 | 用途 |\n|----------|--------|------|\n| `MultiServerMCPClient` | langchain-mcp-adapters | 多服务器MCP客户端 |\n| `create_react_agent` | langgraph.prebuilt | 创建预置ReAct代理 |\n| `InMemorySaver` | langgraph.checkpoint.memory | 内存会话持久化 |\n| `ChatOpenAI` | langchain-openai | OpenAI聊天模型封装 |\n\n### 第二步：配置OpenAI模型\n\n```python\nopenai_model = ChatOpenAI(\n model=\"gpt-5-nano\",\n)\n```\n\n| 参数 | 值 | 说明 |\n|------|-----|------|\n| model | `gpt-5-nano` | 使用OpenAI的GPT-5 Nano模型 |\n| 默认端点 | OpenAI API | 需设置OPENAI_API_KEY环境变量 |\n\n资料来源：[main.py:46-48](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L46-L48)\n\n### 第三步：获取MCP工具\n\n```python\ntools = await client.get_tools()\n```\n\n`get_tools()`方法会异步获取所有已配置MCP服务器提供的工具集合，这些工具将作为ReAct Agent的可调用资源。\n\n资料来源：[main.py:50](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L50)\n\n### 第四步：配置会话记忆系统\n\n```python\ncheckpointer = InMemorySaver()\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n| 参数 | 配置键 | 值 | 说明 |\n|------|--------|-----|------|\n| checkpointer | - | InMemorySaver实例 | 内存会话检查点 |\n| config | configurable.thread_id | \"conversation_id\" | 会话线程标识 |\n\n资料来源：[main.py:52-55](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L52-L55)\n\n### 第五步：创建ReAct Agent\n\n```python\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer\n)\n```\n\n| 参数 | 类型 | 说明 |\n|------|------|------|\n| model | ChatOpenAI | LLM推理引擎 |\n| tools | List[BaseTool] | MCP服务器工具集 |\n| checkpointer | BaseCheckpointSaver | 会话记忆持久化 |\n\n资料来源：[main.py:57-61](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L57-L61)\n\n---\n\n## 自主工具选择机制\n\n### 工具选择工作流\n\nReAct Agent的核心能力之一是根据用户问题自主选择合适的MCP服务器和工具。\n\n```mermaid\ngraph TD\n A[\"用户问题\"] --> B{\"LLM推理判断\"}\n B -->|代码/文档相关| C[\"调用Context7工具\"]\n B -->|艺术/博物馆相关| D[\"调用MetMuseum工具\"]\n C --> E[\"返回文档数据\"]\n D --> F[\"返回艺术品数据\"]\n E --> G[\"LLM生成自然语言响应\"]\n F --> G\n G --> H[\"用户收到响应\"]\n```\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n### 工具选择示例\n\n| 用户问题 | 调用服务器 | 返回内容 |\n|----------|-----------|----------|\n| \"LangGraph工具是什么？\" | Context7 | 框架文档内容 |\n| \"展示莫奈的画作\" | MetMuseum | 艺术品元数据和图片 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n---\n\n## 会话管理机制\n\n### 线程化会话模型\n\n项目采用基于thread_id的线程化会话管理，每个会话拥有独立的上下文记忆。\n\n```mermaid\ngraph TD\n A[\"Session 1
thread_id=conversation_1\"] --> B[\"消息历史 1\"]\n A --> C[\"工具调用历史 1\"]\n D[\"Session 2
thread_id=conversation_2\"] --> E[\"消息历史 2\"]\n D --> F[\"工具调用历史 2\"]\n```\n\n资料来源：[main.py:52-55](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L52-L55)\n\n### 配置参数详解\n\n```python\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n| 配置层级 | 键名 | 值类型 | 说明 |\n|----------|------|--------|------|\n| configurable | thread_id | string | 会话唯一标识符 |\n\n在Agent调用时传入config参数，确保同一thread_id的所有交互共享会话记忆：\n\n```python\nresponse = await agent.ainvoke(\n {\"messages\": query},\n config=config\n)\n```\n\n资料来源：[main.py:92-96](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L92-L96)\n\n---\n\n## 主交互流程\n\n### 程序执行流程图\n\n```mermaid\nflowchart TD\n A[\"启动程序\"] --> B[\"初始化MCP客户端\"]\n B --> C[\"获取所有工具\"]\n C --> D[\"创建ReAct Agent\"]\n D --> E[\"发送初始介绍请求\"]\n E --> F{\"用户选择\"}\n F -->|\"1. 提问\"| G[\"获取用户问题\"]\n G --> H[\"Agent推理并调用工具\"]\n H --> I[\"返回响应给用户\"]\n I --> F\n F -->|\"2. 退出\"| J[\"打印 Goodbye!\"]\n J --> K[\"程序结束\"]\n```\n\n资料来源：[main.py:63-110](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L63-L110)\n\n### 主函数异步设计\n\n```python\nasync def main():\n # 初始化和Agent创建\n client = MultiServerMCPClient({...})\n openai_model = ChatOpenAI(model=\"gpt-5-nano\")\n tools = await client.get_tools()\n checkpointer = InMemorySaver()\n agent = create_react_agent(model=openai_model, tools=tools, checkpointer=checkpointer)\n \n # 初始介绍\n response = await agent.ainvoke({...}, config=config)\n print(response['messages'][-1].content)\n \n # 交互循环\n while True:\n choice = input(\"Menu: 1. Ask 2. Quit: \")\n if choice == \"1\":\n query = input(\"> \")\n response = await agent.ainvoke({\"messages\": query}, config=config)\n print(response['messages'][-1].content)\n else:\n break\n```\n\n资料来源：[main.py:15-110](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L15-L110)\n\n---\n\n## 系统消息配置\n\n### Agent角色定义\n\n通过系统消息（System Message）定义Agent的角色定位和行为规范：\n\n```python\n{\"role\": \"system\", \"content\": \"You are a smart, useful agent with tools to access code library documentation and the Met Museum collection.\"}\n```\n\n| 字段 | 值 | 说明 |\n|------|-----|------|\n| role | \"system\" | 系统角色消息 |\n| content | Agent角色描述 | 声明Agent能力范围 |\n\n资料来源：[main.py:68-71](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L68-L71)\n\n---\n\n## 运行环境要求\n\n### 依赖项\n\n| 依赖包 | 版本要求 | 说明 |\n|--------|----------|------|\n| Python | 3.10+ | 主程序运行环境 |\n| langchain-mcp-adapters | 最新版 | MCP客户端适配器 |\n| langgraph | 最新版 | Agent框架 |\n| langchain-openai | 最新版 | OpenAI模型集成 |\n\n```bash\npip install langchain-mcp-adapters langgraph langchain-openai\n```\n\n### 环境变量\n\n| 变量名 | 必填 | 说明 |\n|--------|------|------|\n| OPENAI_API_KEY | 是 | OpenAI API访问密钥 |\n\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n### 额外要求\n\n| 组件 | 用途 | 安装命令 |\n|------|------|----------|\n| npm | 运行MetMuseum STDIO服务器 | `npm install -g npx` |\n| npx | 包执行器 | 随npm自动安装 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n---\n\n## 执行方式\n\n### 运行程序\n\n```bash\npython main.py\n```\n\n### 交互示例\n\n```\nAgent introduces itself and available tools...\n\nMenu:\n1. Ask the agent a question\n2. Quit\nEnter your choice (1 or 2): 1\n\nYour question\n> What LangGraph tools are available for building agents?\n→ Agent queries Context7 → Returns documentation\n\n> Show me Impressionist paintings from the Met Museum\n→ Agent queries MetMuseum → Returns artwork data\n```\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n---\n\n## 技术亮点总结\n\n| 技术特性 | 实现方式 | 优势 |\n|----------|----------|------|\n| 多传输协议支持 | HTTP + STDIO | 灵活接入远程和本地服务 |\n| 自主工具选择 | LLM推理判断 | 无需手动指定工具 |\n| 持久化会话记忆 | InMemorySaver + thread_id | 跨轮次上下文保持 |\n| 异步架构 | asyncio + await | 高效并发处理 |\n| ReAct推理模式 | LangGraph预置Agent | 可靠的工具调用推理 |\n\n资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n\n---\n\n\n\n## 安装与配置指南\n\n### 相关页面\n\n相关主题：[运行与交互指南](#page-9), [扩展与定制指南](#page-10)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n \n\n# 安装与配置指南\n\n## 概述\n\n本项目是一个基于 Model Context Protocol (MCP) 的多服务器 AI Agent 实现，通过 LangGraph ReAct 架构连接多个 MCP 服务器，并利用 OpenAI GPT-5 Nano 模型进行推理与响应生成。安装与配置指南旨在帮助开发者完整搭建运行环境，包括依赖安装、环境变量配置、多服务器连接设置以及运行验证等关键步骤。\n\n本指南覆盖的范围包括：系统环境要求、Python 依赖安装、Node.js 环境准备、API 密钥配置、MCP 服务器连接配置以及运行测试。通过本指南，开发者可以在本地环境成功部署并运行该多服务器 MCP Agent。\n\n## 系统环境要求\n\n### 硬件与操作系统\n\n| 项目 | 最低要求 | 推荐配置 |\n|------|----------|----------|\n| 操作系统 | macOS / Linux / Windows | macOS / Linux |\n| 内存 | 4GB RAM | 8GB RAM |\n| 存储空间 | 500MB 可用空间 | 1GB 可用空间 |\n| 网络 | 互联网连接 | 稳定的互联网连接 |\n\n### 软件依赖\n\n| 组件 | 版本要求 | 说明 | 资料来源 |\n|------|----------|------|----------|\n| Python | 3.10+ | 主要运行环境 | README.md |\n| Node.js | 14.0+ | npx 包管理器需要 | README.md |\n| pip | 最新版本 | Python 包管理器 | - |\n\n## 安装步骤\n\n### 第一步：安装 Python 依赖\n\n本项目依赖三个核心 Python 包，分别负责 MCP 客户端、LangGraph Agent 框架和 OpenAI 模型集成。执行以下命令完成依赖安装：\n\n```bash\npip install langchain-mcp-adapters langgraph langchain-openai\n```\n\n安装说明如下：\n\n| 包名 | 用途 | 说明 |\n|------|------|------|\n| langchain-mcp-adapters | MCP 客户端 | 提供 MultiServerMCPClient，支持多服务器连接 |\n| langgraph | Agent 框架 | 提供 create_react_agent 创建 ReAct 风格 Agent |\n| langchain-openai | OpenAI 集成 | 提供 ChatOpenAI 模型接口 |\n\n### 第二步：安装 Node.js 和 npm\n\n由于 MetMuseum-MCP 服务器通过 npx 本地运行，需要确保 Node.js 和 npm 已安装。npm 通常随 Node.js 一起安装。\n\n```bash\n# 检查 Node.js 和 npm 版本\nnode --version\nnpm --version\n\n# 如果未安装，通过包管理器安装\n# macOS 使用 Homebrew\nbrew install node\n\n# Ubuntu/Debian\nsudo apt-get install nodejs npm\n\n# Windows 使用 Chocolatey\nchoco install nodejs\n```\n\n对于 MetMuseum 服务器的 STDIO 连接，项目使用 npx 命令直接运行 `metmuseum-mcp` 包，无需全局安装该包，npx 会自动下载并执行。\n\n### 第三步：设置 OpenAI API 密钥\n\nAgent 使用 OpenAI GPT-5 Nano 模型进行推理，需要配置有效的 API 密钥。\n\n```bash\n# Linux/macOS\nexport OPENAI_API_KEY=\"your-api-key-here\"\n\n# Windows (Command Prompt)\nset OPENAI_API_KEY=your-api-key-here\n\n# Windows (PowerShell)\n$env:OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n**注意**：API 密钥应妥善保管，切勿提交到版本控制系统。建议将密钥存储在环境变量文件中，如 `.env` 文件，并确保该文件在 `.gitignore` 中被忽略。\n\n## MCP 服务器配置\n\n### 服务器概述\n\n本项目同时连接两个 MCP 服务器，分别提供不同的服务能力：\n\n| 服务器名称 | 传输协议 | 类型 | 主要功能 |\n|------------|----------|------|----------|\n| Context7 | HTTP (streamable_http) | 远程云端 | 提供主流软件框架的文档搜索 |\n| MetMuseum-MCP | STDIO | 本地 (npx) | 提供大都会艺术博物馆 40 万+ 藏品访问 |\n\n### 配置参数详解\n\n根据 main.py 中的代码实现，MCP 客户端配置如下：\n\n```python\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": \"https://mcp.context7.com/mcp\",\n \"transport\": \"streamable_http\",\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\",\n }\n})\n```\n\n配置参数详细说明：\n\n| 服务器 | 参数 | 类型 | 说明 | 必填 |\n|--------|------|------|------|------|\n| context7 | url | string | Context7 服务器端点 | 是 |\n| context7 | transport | string | 传输协议类型，固定为 streamable_http | 是 |\n| met-museum | command | string | 执行命令，此处为 npx | 是 |\n| met-museum | args | list | 命令参数，`-y` 表示自动确认，`metmuseum-mcp` 为包名 | 是 |\n| met-museum | transport | string | 传输协议类型，固定为 stdio | 是 |\n\n## 运行 Agent\n\n### 启动命令\n\n完成所有配置后，执行以下命令启动 Agent：\n\n```bash\npython main.py\n```\n\n### 交互流程\n\n```mermaid\ngraph TD\n A[启动 main.py] --> B[初始化 MCP 客户端]\n B --> C[连接 Context7 服务器 HTTP]\n B --> D[连接 MetMuseum-MCP 服务器 STDIO]\n C --> E[获取所有可用工具]\n D --> E\n E --> F[初始化 GPT-5 Nano 模型]\n F --> G[创建 LangGraph ReAct Agent]\n G --> H[初始化 InMemorySaver 内存]\n H --> I[Agent 自我介绍]\n I --> J{用户选择}\n J -->|选择 1| K[用户输入问题]\n K --> L[Agent 推理并调用工具]\n L --> M[返回响应结果]\n M --> J\n J -->|选择 2| N[退出程序]\n```\n\n### 会话管理\n\nAgent 使用 InMemorySaver 实现会话记忆功能，所有消息通过 thread_id 进行关联：\n\n```python\ncheckpointer = InMemorySaver()\nconfig = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n```\n\n这确保了多轮对话中 Agent 能够记住之前的上下文信息。\n\n## 架构组件关系\n\n```mermaid\ngraph TD\n subgraph 应用层\n A[main.py] --> B[MultiServerMCPClient]\n B --> C[create_react_agent]\n C --> D[ChatOpenAI GPT-5 Nano]\n end\n \n subgraph 连接层\n B --> E[HTTP Transport]\n B --> F[STDIO Transport]\n end\n \n subgraph 服务层\n E --> G[Context7 Server]\n F --> H[MetMuseum-MCP Server]\n end\n \n subgraph 数据层\n G --> I[框架文档数据]\n H --> J[艺术藏品数据]\n end\n```\n\n## 常见问题排查\n\n### 依赖安装失败\n\n| 问题 | 解决方案 |\n|------|----------|\n| pip 版本过旧 | 升级 pip: `pip install --upgrade pip` |\n| 权限错误 | 使用虚拟环境或添加 `--user` 参数 |\n| SSL 证书错误 | 更新 certifi 包: `pip install --upgrade certifi` |\n\n### MCP 服务器连接问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| Context7 连接超时 | 检查网络连接，确认 https://mcp.context7.com/mcp 可访问 |\n| MetMuseum npx 失败 | 确保 Node.js 和 npm 已正确安装，运行 `npx -y metmuseum-mcp` 测试 |\n| 工具获取失败 | 检查 API 密钥是否有效，确认网络连接正常 |\n\n### API 密钥问题\n\n| 问题 | 解决方案 |\n|------|----------|\n| 密钥未设置 | 执行 `export OPENAI_API_KEY=\"your-key\"` |\n| 密钥无效 | 前往 OpenAI 平台检查并生成新密钥 |\n| 余额不足 | 检查 OpenAI 账户余额 |\n\n## 项目文件结构\n\n```\nmcp-ai-agent/\n│\n├── main.py # 主程序入口，包含完整的多服务器 MCP Agent 实现\n├── README.md # 项目说明文档\n└── .gitignore # Git 忽略文件（需创建，包含 .env 等）\n```\n\n## 后续步骤\n\n安装配置完成后，建议按以下顺序验证系统：\n\n1. 验证 Python 依赖已正确安装\n2. 验证 OpenAI API 密钥有效\n3. 运行 `python main.py` 启动 Agent\n4. 输入测试问题验证工具调用功能\n5. 测试多轮对话确认会话记忆正常\n\n---\n\n\n\n## 运行与交互指南\n\n### 相关页面\n\n相关主题：[安装与配置指南](#page-8), [持久化对话记忆机制](#page-5)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n \n\n# 运行与交互指南\n\n## 概述\n\n本指南详细介绍 `mcp-ai-agent` 项目的运行方法与用户交互流程。该项目是一个基于 Model Context Protocol (MCP) 的多服务器 AI Agent，采用 LangGraph ReAct 架构，能够同时连接多个 MCP 服务器并提供持久化对话记忆功能。资料来源：[main.py:1-95]()\n\n## 系统要求\n\n### 运行环境\n\n| 组件 | 最低要求 |\n|------|----------|\n| Python 版本 | 3.10+ |\n| Node.js | 用于 npx 运行本地 MCP 服务器 |\n| OpenAI API Key | 必需 |\n\n### 依赖安装\n\n在运行项目前，需要安装以下 Python 依赖包：\n\n```bash\npip install langchain-mcp-adapters langgraph langchain-openai\n```\n\n对于本地 MCP 服务器（如 MetMuseum），需要确保 npm 可用：\n\n```bash\nnpm install -g npx\n```\n\n## 配置步骤\n\n### 环境变量配置\n\n运行项目前，必须设置 OpenAI API 密钥：\n\n```bash\nexport OPENAI_API_KEY=\"your-api-key-here\"\n```\n\n### MCP 服务器配置\n\n`main.py` 中配置了两个 MCP 服务器连接，详情见下表：\n\n| 服务器名称 | 传输协议 | 端点/命令 | 功能描述 |\n|-----------|---------|----------|----------|\n| context7 | streamable_http | https://mcp.context7.com/mcp | 提供代码库文档搜索能力 |\n| met-museum | stdio | npx -y metmuseum-mcp | 提供大都会艺术博物馆藏品访问 |\n\n资料来源：[main.py:37-52]()\n\n## 核心组件架构\n\n### 组件交互流程\n\n```mermaid\ngraph TD\n A[用户 CLI 交互] --> B[LangGraph ReAct Agent]\n B --> C{GPT-5 Nano 推理}\n C --> D[自动工具选择]\n D --> E[Context7 HTTP]\n D --> F[MetMuseum STDIO]\n E --> G[返回结果]\n F --> G\n G --> B\n H[InMemorySaver] --> B\n I[thread_id 持久化] --> H\n```\n\n### 关键组件说明\n\n| 组件 | 类/模块 | 作用 |\n|------|---------|------|\n| MCP 客户端 | MultiServerMCPClient | 同时管理多个 MCP 服务器连接 |\n| Agent 引擎 | create_react_agent | 创建 ReAct 风格代理，整合推理与工具调用 |\n| 对话记忆 | InMemorySaver | 维护会话线程内的对话历史 |\n| 语言模型 | ChatOpenAI | GPT-5 Nano 提供推理能力 |\n\n资料来源：[main.py:37](), [main.py:68](), [main.py:72](), [main.py:60]()\n\n## 运行流程详解\n\n### 启动序列\n\n```mermaid\nsequenceDiagram\n participant User as 用户\n participant Agent as AI Agent\n participant Client as MCP Client\n participant Servers as MCP Servers\n\n User->>Agent: python main.py\n Agent->>Client: 初始化 MultiServerMCPClient\n Client->>Servers: 建立 HTTP + STDIO 连接\n Servers-->Client: 返回可用工具列表\n Client-->Agent: tools = await client.get_tools()\n Agent->>Agent: 创建 InMemorySaver\n Agent->>Agent: create_react_agent\n Agent->>User: 显示自我介绍与工具列表\n```\n\n### 主程序执行逻辑\n\n```python\n# 标准库导入\nimport asyncio\n\n# MCP 和 LangGraph 导入\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.checkpoint.memory import InMemorySaver\nfrom langchain_openai import ChatOpenAI\n\nasync def main():\n # 1. 配置并初始化 MCP 客户端\n client = MultiServerMCPClient({...})\n \n # 2. 初始化 OpenAI 模型\n openai_model = ChatOpenAI(model=\"gpt-5-nano\")\n \n # 3. 获取所有可用工具\n tools = await client.get_tools()\n \n # 4. 设置对话记忆系统\n checkpointer = InMemorySaver()\n config = {\"configurable\": {\"thread_id\": \"conversation_id\"}}\n \n # 5. 创建 ReAct Agent\n agent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer\n )\n \n # 6. 发送初始介绍消息\n response = await agent.ainvoke({...}, config=config)\n \n # 7. 进入交互循环\n while True:\n # 处理用户输入...\n```\n\n资料来源：[main.py:18-95]()\n\n## 用户交互流程\n\n### 交互菜单系统\n\n项目采用简单的命令行菜单界面，用户通过输入数字选择操作：\n\n```\nMenu:\n1. Ask the agent a question\n2. Quit\nEnter your choice (1 or 2): \n```\n\n### 交互状态机\n\n```mermaid\nstateDiagram-v2\n [*] --> 启动: python main.py\n 启动 --> 初始化: asyncio.run(main)\n 初始化 --> 自我介绍: Agent 介绍工具能力\n 自我介绍 --> 等待选择: 显示菜单\n 等待选择 --> 提问: 用户选择 1\n 等待选择 --> 退出: 用户选择 2\n 提问 --> 调用Agent: 输入问题\n 调用Agent --> 等待选择: 显示响应\n 退出 --> [*]: print(\"Goodbye!\")\n```\n\n### 消息处理流程\n\n当用户提出问题时，系统按以下步骤处理：\n\n1. **接收用户查询** — 获取用户输入的问题内容\n2. **调用 Agent** — 使用 `agent.ainvoke()` 发送查询\n3. **传递会话配置** — config 中的 thread_id 维持对话上下文\n4. **返回响应** — 显示 agent 的最后一条消息内容\n\n```python\n# 发送用户问题并获取响应\nquery = input(\"> \")\nresponse = await agent.ainvoke(\n {\"messages\": query},\n config=config\n)\n# 显示 agent 的回复\nprint(response['messages'][-1].content)\n```\n\n资料来源：[main.py:86-92]()\n\n## 对话记忆机制\n\n### 持久化原理\n\n系统使用 `InMemorySaver` 和 `thread_id` 实现对话记忆：\n\n| 参数 | 值 | 说明 |\n|------|-----|------|\n| thread_id | \"conversation_id\" | 会话唯一标识符 |\n| checkpointer | InMemorySaver 实例 | 内存中的对话历史存储 |\n\n所有在同一 thread_id 下的消息都会被持久化保存，Agent 能够记住之前的对话内容。\n\n资料来源：[main.py:72-75]()\n\n### 消息结构\n\n```python\n# 系统消息定义 Agent 角色\n{\"role\": \"system\", \"content\": \"You are a smart, useful agent...\"}\n\n# 用户消息\n{\"role\": \"user\", \"content\": \"用户输入的问题\"}\n\n# Agent 响应\n{\"role\": \"assistant\", \"content\": \"Agent 的回复内容\"}\n```\n\n## MCP 服务器工具调用\n\n### 自主工具选择\n\nAgent 具备自动选择工具的能力，根据用户问题判断应调用哪个服务器：\n\n```mermaid\ngraph LR\n A[用户问题] --> B{GPT-5 Nano 推理}\n B -->|代码/库文档| C[Context7 HTTP]\n B -->|艺术/博物馆| D[MetMuseum STDIO]\n C --> E[返回文档数据]\n D --> F[返回艺术品数据]\n```\n\n### 示例场景\n\n| 用户问题类型 | 调用服务器 | 返回内容 |\n|-------------|-----------|----------|\n| \"LangChain 代理文档\" | Context7 | 代码库文档 |\n| \"梵高 paintings\" | MetMuseum | 艺术品元数据与图片 |\n\n## 快速启动命令汇总\n\n| 步骤 | 命令 | 说明 |\n|------|------|------|\n| 1 | `pip install langchain-mcp-adapters langgraph langchain-openai` | 安装 Python 依赖 |\n| 2 | `export OPENAI_API_KEY=\"your-api-key-here\"` | 设置 API 密钥 |\n| 3 | `python main.py` | 启动 Agent |\n\n## 异常处理\n\n程序对用户输入采用宽松处理策略：\n\n- 输入 `1` → 进入提问模式\n- 输入其他任何值 → 退出程序\n\n```python\nif choice == \"1\":\n # 处理提问逻辑\nelse:\n print(\"Goodbye!\")\n break\n```\n\n资料来源：[main.py:93-94]()\n\n## 项目结构\n\n```\nmcp-ai-agent/\n├── main.py # 完整的 MCP Agent 实现\n└── README.md # 项目说明文档\n```\n\n当前项目结构简洁，所有核心逻辑均包含在 `main.py` 中，便于快速理解与部署。\n\n---\n\n\n\n## 扩展与定制指南\n\n### 相关页面\n\n相关主题：[MultiServerMCPClient配置](#page-6), [集成MCP服务器详解](#page-7)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)\n- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)\n \n\n# 扩展与定制指南\n\n本指南详细说明如何扩展和定制 mcp-ai-agent 项目，涵盖 MCP 服务器配置、LLM 模型替换、记忆系统升级、代理架构调整以及传输协议选择等关键定制方向。通过本指南，开发者可以根据实际业务需求灵活调整系统组件，构建符合特定场景的智能代理应用。\n\n## 1. 系统架构概述\n\nmcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器代理系统，核心架构采用 LangGraph ReAct 模式实现自主工具调用和推理。系统通过 MultiServerMCPClient 同时管理多个 MCP 服务器，连接不同传输协议的外部服务，并利用 GPT-5 Nano 模型进行自然语言理解和工具选择决策。代理运行时维护会话记忆，确保多轮对话的上下文连贯性。\n\n```mermaid\ngraph TD\n A[用户 CLI 交互界面] --> B[LangGraph ReAct 代理引擎]\n B --> C[GPT-5 Nano 推理引擎]\n C --> D{工具选择决策}\n D --> E[Context7 服务器
HTTP 传输]\n D --> F[MetMuseum 服务器
STDIO 传输]\n E --> G[外部文档库检索]\n F --> H[大都会艺术博物馆数据]\n B <--> I[InMemorySaver
会话记忆存储]\n G --> J[LLM 优化文档结果]\n H --> K[艺术品元数据与图片]\n J --> L[自然语言响应生成]\n K --> L\n L --> A\n```\n\n系统核心组件包括：MultiServerMCPClient 负责多服务器连接管理，create_react_agent 构建 ReAct 推理代理，InMemorySaver 提供进程内会话持久化，ChatOpenAI 封装语言模型调用接口。各组件通过异步机制协同工作，支持高并发工具调用场景。资料来源：[main.py:1-30]()\n\n## 2. MCP 服务器扩展\n\n### 2.1 MCP 服务器配置结构\n\nMCP 服务器通过 MultiServerMCPClient 的配置字典进行注册，支持 HTTP 流式传输和 STDIO 本地进程两种主要协议类型。每台服务器配置包含传输协议类型、连接参数和认证信息三个核心维度。HTTP 服务器适合远程云端服务，STDIO 服务器适合本地 Node.js 运行时环境。\n\n| 配置字段 | 类型 | 说明 | 示例值 |\n|---------|------|------|--------|\n| transport | string | 传输协议类型 | `streamable_http`、`stdio` |\n| url | string | HTTP 服务器端点 | `https://mcp.context7.com/mcp` |\n| command | string | STDIO 执行命令 | `npx`、`node` |\n| args | array | 命令行参数列表 | `[\"-y\", \"metmuseum-mcp\"]` |\n| headers | object | HTTP 请求头 | `{\"Authorization\": \"Bearer xxx\"}` |\n\n资料来源：[main.py:28-42]()\n\n### 2.2 添加 HTTP 远程服务器\n\nHTTP 传输协议基于 streamable_http 实现，支持远程 MCP 服务器的云端部署。配置时需指定服务器的 URL 端点，可选配置自定义请求头用于认证。远程服务器的优势在于无需在本地安装依赖，可直接调用云端提供的工具能力。\n\n```python\nclient = MultiServerMCPClient({\n \"custom-remote-server\": {\n \"url\": \"https://your-mcp-server.com/mcp\",\n \"transport\": \"streamable_http\",\n \"headers\": {\n \"Authorization\": \"Bearer your-api-key\",\n \"X-Custom-Header\": \"custom-value\"\n }\n }\n})\n```\n\nHTTP 服务器适用于以下场景：API 密钥管理的云服务、需要大规模计算资源的工具、跨组织数据共享、以及需要频繁更新的服务实例。配置时建议设置合理的超时参数，避免长时间等待响应。资料来源：[main.py:33-36]()\n\n### 2.3 添加 STDIO 本地服务器\n\nSTDIO 传输协议通过标准输入输出与本地进程通信，适用于通过 npx 或 node 命令启动的 Node.js MCP 服务器。配置时需指定可执行命令和参数列表，系统会自动管理子进程的启动和生命周期。\n\n```python\nclient = MultiServerMCPClient({\n \"local-mcp-server\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"your-local-mcp-package\"],\n \"transport\": \"stdio\"\n }\n})\n```\n\n本地 STDIO 服务器的优势包括：无网络延迟的工具调用、本地文件系统和数据库的直接访问、以及完全可控的执行环境。开发时可通过本地服务器快速迭代工具定义。资料来源：[main.py:37-41]()\n\n### 2.4 多服务器并发管理\n\nMultiServerMCPClient 支持同时连接多个不同协议的 MCP 服务器，所有服务器的工具会在调用时自动聚合。代理引擎无需感知底层传输差异，统一通过工具名称进行调用。并发连接管理由底层适配器自动处理，开发者只需在配置中声明服务器列表。\n\n```python\nclient = MultiServerMCPClient({\n \"server-a\": {\n \"url\": \"https://server-a.com/mcp\",\n \"transport\": \"streamable_http\"\n },\n \"server-b\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"server-b-package\"],\n \"transport\": \"stdio\"\n },\n \"server-c\": {\n \"command\": \"node\",\n \"args\": [\"/path/to/server-c.js\"],\n \"transport\": \"stdio\"\n }\n})\ntools = await client.get_tools() # 聚合所有服务器工具\n```\n\n资料来源：[main.py:28-47]()\n\n## 3. 大语言模型定制\n\n### 3.1 模型提供商切换\n\n系统默认使用 OpenAI 的 GPT-5 Nano 模型，可通过替换 ChatOpenAI 实例切换到其他兼容提供商。LangChain 生态支持多种 LLM 实现，包括 Anthropic、Google VertexAI、Azure OpenAI 等。模型选择影响代理的推理能力、响应速度和运行成本。\n\n```python\nfrom langchain_openai import ChatOpenAI\nfrom langchain_anthropic import ChatAnthropic\nfrom langchain_google_vertexai import ChatVertexAI\n\n# OpenAI 配置\nopenai_model = ChatOpenAI(\n model=\"gpt-5-nano\",\n api_key=\"your-openai-key\",\n temperature=0.7\n)\n\n# Anthropic Claude 配置\nclaude_model = ChatAnthropic(\n model=\"claude-sonnet-4-20250514\",\n anthropic_api_key=\"your-anthropic-key\"\n)\n```\n\n资料来源：[main.py:44-48]()\n\n### 3.2 模型参数调优\n\nChatOpenAI 初始化支持多个关键参数控制模型行为。temperature 控制输出随机性，数值越高越具创造性；max_tokens 限制单次响应长度；top_p 和 frequency_penalty 提供更细粒度的采样控制。\n\n| 参数名 | 类型 | 默认值 | 说明 |\n|-------|------|--------|------|\n| model | string | gpt-5-nano | 模型标识符 |\n| temperature | float | 0.7 | 采样温度，0-2 之间 |\n| max_tokens | int | None | 最大生成 token 数 |\n| top_p | float | 1.0 | 核采样概率阈值 |\n| frequency_penalty | float | 0.0 | 频率惩罚系数 |\n| presence_penalty | float | 0.0 | 存在惩罚系数 |\n\n调优建议：代码生成任务建议使用较低的 temperature（0.2-0.5）；创意写作和头脑风暴适合较高的 temperature（0.7-1.0）；需要确定性输出的场景可设为 0。资料来源：[main.py:44-48]()\n\n### 3.3 自定义系统提示词\n\n系统提示词定义代理的角色定位、行为规范和能力边界。通过修改 create_react_agent 调用时的 messages 参数，可以定制代理的专业领域、响应风格和工具使用策略。\n\n```python\nresponse = await agent.ainvoke(\n {\"messages\": [\n {\"role\": \"system\", \"content\": \"\"\"你是一位专业的金融分析助手，专注于：\n 1. 股票市场数据分析和趋势预测\n 2. 投资组合风险评估\n 3. 财务报表解读\n 4. 使用可用的金融数据工具获取实时信息\n \n 回复时使用简洁专业的语言，提供数据支撑的分析结论。\"\"\"},\n {\"role\": \"user\", \"content\": \"介绍你自己和可用工具\"},\n ]},\n config=config\n)\n```\n\n资料来源：[main.py:59-68]()\n\n## 4. 代理架构定制\n\n### 4.1 代理类型选择\n\nLangGraph 提供了多种预构建代理类型，除了默认的 ReAct 代理外，还支持 create_structured_chat_agent、create_conversational_agent 等变体。不同代理类型适用于不同交互模式：ReAct 适合需要复杂推理的工具调用场景，Conversational 适合聊天式问答，Structured Chat 适合需要结构化输出的场景。\n\n```python\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.prebuilt import create_structured_chat_agent\n\n# ReAct 代理 - 适合工具调用\nagent = create_react_agent(\n model=openai_model,\n tools=tools,\n checkpointer=checkpointer,\n state_modifier=\"你是一个有帮助的助手\"\n)\n\n# 结构化聊天代理 - 适合需要 JSON 输出\nagent = create_structured_chat_agent(\n model=openai_model,\n tools=tools\n)\n```\n\n### 4.2 ReAct 推理循环定制\n\nReAct（Reasoning + Acting）代理的核心是思考-行动-观察循环。LangGraph 预构建代理封装了这一逻辑，但可通过 state_modifier 和 prompt 自定义影响推理过程。state_modifier 在每轮推理前修改状态，用于注入额外上下文或约束。\n\n```mermaid\ngraph TD\n A[用户输入] --> B[构建消息历史]\n B --> C[LLM 推理阶段]\n C --> D{是否调用工具?}\n D -->|是| E[执行工具调用]\n E --> F[收集工具结果]\n F --> B\n D -->|否| G[生成最终响应]\n G --> H[返回给用户]\n C -->|思考过程| I[记录推理步骤]\n I --> D\n```\n\n资料来源：[main.py:51-57]()\n\n### 4.3 工具过滤与白名单\n\n出于安全和性能考虑，可通过工具过滤机制限制代理可用的工具范围。get_tools() 返回的完整工具列表可按名称模式或分类标签进行筛选，只将必要的工具暴露给代理。\n\n```python\ntools = await client.get_tools()\n\n# 按名称前缀过滤\nfiltered_tools = [\n tool for tool in tools \n if tool.name.startswith(\"context7_\")\n]\n\n# 按工具类型过滤\ndocument_tools = [\n tool for tool in tools \n if hasattr(tool, 'tags') and 'document' in tool.tags\n]\n\nagent = create_react_agent(\n model=openai_model,\n tools=filtered_tools, # 使用过滤后的工具列表\n checkpointer=checkpointer\n)\n```\n\n## 5. 记忆系统升级\n\n### 5.1 内存检查点器对比\n\n默认的 InMemorySaver 将对话历史存储在进程内存中，适用于单实例部署和快速原型开发。生产环境建议使用持久化检查点器，避免进程重启后对话历史丢失。\n\n| 检查点器类型 | 存储介质 | 持久化 | 并发支持 | 适用场景 |\n|------------|---------|--------|---------|---------|\n| InMemorySaver | 进程内存 | 否 | 单进程 | 开发调试、原型 |\n| PostgresSaver | PostgreSQL | 是 | 高并发 | 生产环境 |\n| RedisSaver | Redis | 是 | 高并发 | 分布式部署 |\n| SQLiteSaver | SQLite | 是 | 低并发 | 轻量级部署 |\n\n资料来源：[main.py:49-50]()\n\n### 5.2 PostgreSQL 检查点器配置\n\nPostgreSQL 检查点器支持多实例并发访问，适合生产环境大规模部署。需提前创建数据库表结构，LangGraph 提供自动迁移功能。\n\n```python\nfrom langgraph.checkpoint.postgres import PostgresSaver\nfrom langchain_postgres import PostgresChatMessageHistory\n\n# PostgreSQL 检查点器配置\ncheckpointer = PostgresSaver.from_conn_string(\n \"postgresql://user:password@localhost:5432/langgraph\"\n)\ncheckpointer.setup() # 创建必要的表结构\n\nconfig = {\"configurable\": {\"thread_id\": \"user_session_123\"}}\n```\n\n### 5.3 多会话隔离管理\n\n通过 thread_id 实现多用户会话隔离，每个会话维护独立的对话历史。config 字典的可配置参数用于指定线程标识符，系统自动为每个线程维护独立的状态快照。\n\n```python\n# 用户 A 的会话\nconfig_a = {\"configurable\": {\"thread_id\": \"user_a_session\"}}\n\n# 用户 B 的会话\nconfig_b = {\"configurable\": {\"thread_id\": \"user_b_session\"}}\n\n# 独立调用，互不影响\nresponse_a = await agent.ainvoke({\"messages\": query}, config=config_a)\nresponse_b = await agent.ainvoke({\"messages\": query}, config=config_b)\n```\n\n资料来源：[main.py:52-53]()\n\n## 6. 传输协议深度定制\n\n### 6.1 HTTP 流式传输配置\n\nstreamable_http 传输支持流式响应模式，减少首次响应延迟。配置选项包括连接超时、读取超时和自动重试策略。对于需要实时反馈的工具调用场景，建议启用流式传输。\n\n```python\nclient = MultiServerMCPClient({\n \"streaming-server\": {\n \"url\": \"https://streaming-mcp.example.com/mcp\",\n \"transport\": \"streamable_http\",\n \"timeout\": 30, # 超时时间（秒）\n \"max_retries\": 3, # 最大重试次数\n \"verify_ssl\": True # SSL 证书验证\n }\n})\n```\n\n### 6.2 STDIO 进程生命周期管理\n\nSTDIO 服务器由 MCP 客户端自动管理进程启动和终止。当客户端关闭时，所有 STDIO 子进程会自动清理。必要时可通过客户端上下文管理器手动控制进程生命周期。\n\n```python\nasync with MultiServerMCPClient({...}) as client:\n tools = await client.get_tools()\n # 使用工具...\n# 超出上下文范围时自动清理进程\n```\n\n### 6.3 混合传输架构\n\n在复杂企业场景中，可采用混合传输架构：核心业务逻辑使用 HTTP 服务器保证可用性，敏感数据操作使用本地 STDIO 服务器确保数据安全。\n\n```mermaid\ngraph LR\n A[代理引擎] --> B[HTTP 网关]\n A --> C[本地 STDIO 桥接]\n B --> D[云端 MCP 服务]\n B --> E[第三方 API 服务]\n C --> F[本地数据库服务器]\n C --> G[文件系统]\n D --> H[文档检索]\n E --> I[外部数据源]\n F --> J[业务数据]\n G --> K[附件存储]\n```\n\n## 7. 错误处理与容错\n\n### 7.1 工具调用错误捕获\n\n代理运行时可能遇到工具执行失败、网络超时或服务器不可用等情况。建议在外层封装错误处理逻辑，为用户提供友好的错误提示。\n\n```python\ntry:\n response = await agent.ainvoke(\n {\"messages\": query},\n config=config\n )\n print(response['messages'][-1].content)\nexcept Exception as e:\n print(f\"处理请求时发生错误: {str(e)}\")\n # 可选：降级到无工具模式重试\n```\n\n### 7.2 重试策略配置\n\n对于临时性故障，可实现自动重试机制。指数退避策略可避免重试风暴，同时给予服务恢复时间。\n\n```python\nimport asyncio\nfrom tenacity import retry, stop_after_attempt, wait_exponential\n\n@retry(\n stop=stop_after_attempt(3),\n wait=wait_exponential(multiplier=1, min=2, max=10)\n)\nasync def call_agent_with_retry(agent, query, config):\n return await agent.ainvoke({\"messages\": query}, config=config)\n```\n\n### 7.3 降级策略设计\n\n当部分 MCP 服务器不可用时，系统应能优雅降级。可实现工具可用性检查，在初始化阶段过滤不可用工具，并通知代理哪些工具可用。\n\n```python\ntools = await client.get_tools()\navailable_tools = []\n\nfor tool in tools:\n try:\n # 健康检查\n await tool.invoke({\"type\": \"ping\"})\n available_tools.append(tool)\n except Exception:\n print(f\"工具 {tool.name} 不可用，已跳过\")\n\nagent = create_react_agent(\n model=openai_model,\n tools=available_tools,\n checkpointer=checkpointer\n)\n```\n\n## 8. 生产环境部署\n\n### 8.1 环境变量管理\n\n生产部署应使用环境变量管理敏感配置，避免硬编码 API 密钥。建议使用 python-dotenv 或 docker-secrets 管理变量。\n\n```python\nimport os\nfrom dotenv import load_dotenv\n\nload_dotenv() # 从 .env 文件加载\n\nopenai_model = ChatOpenAI(\n model=\"gpt-5-nano\",\n api_key=os.environ.get(\"OPENAI_API_KEY\")\n)\n\nclient = MultiServerMCPClient({\n \"context7\": {\n \"url\": os.environ.get(\"CONTEXT7_URL\"),\n \"transport\": \"streamable_http\"\n }\n})\n```\n\n资料来源：[main.py:44-48]()\n\n### 8.2 异步入口点设计\n\nmain() 函数使用 asyncio.run() 启动异步事件循环。生产环境建议使用 uvicorn 或 gunicorn 配合 ASGI 应用封装，实现真正的并发处理。\n\n```python\nfrom fastapi import FastAPI\nimport asyncio\n\napp = FastAPI()\n\n@app.post(\"/chat\")\nasync def chat_endpoint(request: ChatRequest):\n response = await agent.ainvoke(\n {\"messages\": request.messages},\n config={\"configurable\": {\"thread_id\": request.session_id}}\n )\n return {\"response\": response['messages'][-1].content}\n\nif __name__ == \"__main__\":\n import uvicorn\n uvicorn.run(app, host=\"0.0.0.0\", port=8000)\n```\n\n### 8.3 容器化部署配置\n\nDocker 容器化部署需考虑 MCP 服务器的依赖。STDIO 服务器需要 Node.js 运行时，HTTP 服务器则只需 Python 环境。\n\n```dockerfile\n# 多阶段构建 Dockerfile\nFROM node:18-slim AS npx-server\nWORKDIR /app\nRUN npm install -g metmuseum-mcp\n\nFROM python:3.10-slim\nWORKDIR /app\nCOPY requirements.txt .\nRUN pip install --no-cache-dir -r requirements.txt\nCOPY --from=npx-server /usr/local/bin/npx /usr/local/bin/\nCOPY main.py .\nCMD [\"python\", \"main.py\"]\n```\n\n## 9. 监控与日志\n\n### 9.1 LangSmith 集成\n\nLangChain 生态提供 LangSmith 用于追踪代理执行过程，包括 LLM 调用、工具执行和状态转换。\n\n```python\nos.environ[\"LANGCHAIN_TRACING_V2\"] = \"true\"\nos.environ[\"LANGCHAIN_API_KEY\"] = \"your-langsmith-key\"\nos.environ[\"LANGCHAIN_PROJECT\"] = \"mcp-agent-production\"\n```\n\n### 9.2 自定义日志记录\n\n使用 Python logging 模块配置结构化日志，便于生产环境问题排查。\n\n```python\nimport logging\nimport json\n\nlogging.basicConfig(level=logging.INFO)\nlogger = logging.getLogger(\"mcp-agent\")\n\nasync def log_agent_invocation(query, response):\n logger.info(json.dumps({\n \"event\": \"agent_invocation\",\n \"query\": str(query),\n \"response_length\": len(str(response))\n }))\n```\n\n## 10. 快速参考\n\n### 10.1 完整定制配置模板\n\n```python\nimport asyncio\nimport os\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\nfrom langgraph.prebuilt import create_react_agent\nfrom langgraph.checkpoint.postgres import PostgresSaver\nfrom langchain_openai import ChatOpenAI\nfrom langchain_anthropic import ChatAnthropic\n\nasync def main():\n # 1. MCP 服务器配置\n client = MultiServerMCPClient({\n \"context7\": {\n \"url\": os.environ.get(\"CONTEXT7_URL\"),\n \"transport\": \"streamable_http\"\n },\n \"met-museum\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"metmuseum-mcp\"],\n \"transport\": \"stdio\"\n }\n })\n \n # 2. LLM 模型配置\n model = ChatAnthropic(\n model=\"claude-sonnet-4-20250514\",\n anthropic_api_key=os.environ.get(\"ANTHROPIC_API_KEY\")\n )\n \n # 3. 工具与记忆配置\n tools = await client.get_tools()\n checkpointer = PostgresSaver.from_conn_string(\n os.environ.get(\"DATABASE_URL\")\n )\n \n # 4. 创建代理\n agent = create_react_agent(\n model=model,\n tools=tools,\n checkpointer=checkpointer\n )\n \n # 5. 运行代理\n config = {\"configurable\": {\"thread_id\": \"main\"}}\n response = await agent.ainvoke(\n {\"messages\": [{\"role\": \"user\", \"content\": \"你好\"}]},\n config=config\n )\n print(response['messages'][-1].content)\n\nif __name__ == \"__main__\":\n asyncio.run(main())\n```\n\n### 10.2 关键文件位置\n\n| 功能模块 | 文件路径 | 行号范围 |\n|---------|---------|---------|\n| MCP 客户端初始化 | main.py | 28-47 |\n| LLM 模型配置 | main.py | 44-48 |\n| 工具获取 | main.py | 50 |\n| 记忆系统配置 | main.py | 49-50 |\n| 代理创建 | main.py | 51-57 |\n| 初始对话调用 | main.py | 59-78 |\n| 主循环交互 | main.py | 80-95 |\n\n资料来源：[main.py:1-95]()\n\n本指南涵盖 mcp-ai-agent 的主要扩展和定制方向。开发者可根据实际需求组合不同模块，构建满足特定业务场景的智能代理系统。建议从单服务器简单配置开始，逐步添加复杂功能，并在开发过程中使用 InMemorySaver 便于调试，生产环境切换到持久化检查点器确保会话可靠性。\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：LeelaissakAttota/mcp-ai-agent\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `mcp-ai-agent` 与安装入口 `metmuseum-mcp` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx metmuseum-mcp`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | repo=mcp-ai-agent; install=metmuseum-mcp\n\n## 2. 能力坑 · 能力判断依赖假设\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:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium\n\n## 6. 维护坑 · 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:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | 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项目：LeelaissakAttota/mcp-ai-agent\n\n摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。\n\n## 1. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `mcp-ai-agent` 与安装入口 `metmuseum-mcp` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令：`npx metmuseum-mcp`\n- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | repo=mcp-ai-agent; install=metmuseum-mcp\n\n## 2. 能力坑 · 能力判断依赖假设\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:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | README/documentation is current enough for a first validation pass.\n\n## 3. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | last_activity_observed missing\n\n## 4. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作：下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium\n\n## 5. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium\n\n## 6. 维护坑 · 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:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | issue_or_pr_quality=unknown\n\n## 7. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# mcp-ai-agent - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 mcp-ai-agent 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 示例引导, 判断线索。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- 安装前能力预览: Multi-server MCP AI agent — LangGraph ReAct + GPT-5 Nano connecting Context7 docs (HTTP) & MetMuseum 400K artworks (STDIO) with persistent conversation memory 输入：用户任务, 当前 AI 对话上下文；输出：示例引导, 判断线索。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. page-1：项目概览。围绕“项目概览”模拟一次用户任务，不展示安装或运行结果。\n2. page-2：技术栈详解。围绕“技术栈详解”模拟一次用户任务，不展示安装或运行结果。\n3. page-3：系统架构设计。围绕“系统架构设计”模拟一次用户任务，不展示安装或运行结果。\n4. page-4：LangGraph ReAct代理实现。围绕“LangGraph ReAct代理实现”模拟一次用户任务，不展示安装或运行结果。\n5. page-5：持久化对话记忆机制。围绕“持久化对话记忆机制”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. page-1\n输入：用户提供的“项目概览”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. page-2\n输入：用户提供的“技术栈详解”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. page-3\n输入：用户提供的“系统架构设计”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. page-4\n输入：用户提供的“LangGraph ReAct代理实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. page-5\n输入：用户提供的“持久化对话记忆机制”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / page-1：Step 1 必须围绕“项目概览”形成一个小中间产物，并等待用户确认。\n- Step 2 / page-2：Step 2 必须围绕“技术栈详解”形成一个小中间产物，并等待用户确认。\n- Step 3 / page-3：Step 3 必须围绕“系统架构设计”形成一个小中间产物，并等待用户确认。\n- Step 4 / page-4：Step 4 必须围绕“LangGraph ReAct代理实现”形成一个小中间产物，并等待用户确认。\n- Step 5 / page-5：Step 5 必须围绕“持久化对话记忆机制”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/LeelaissakAttota/mcp-ai-agent\n- https://github.com/LeelaissakAttota/mcp-ai-agent#readme\n- README.md\n- main.py\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 mcp-ai-agent 的核心服务。\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项目：LeelaissakAttota/mcp-ai-agent\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx metmuseum-mcp\n```\n\n来源：https://github.com/LeelaissakAttota/mcp-ai-agent#readme\n\n## 来源\n\n- repo: https://github.com/LeelaissakAttota/mcp-ai-agent\n- docs: https://github.com/LeelaissakAttota/mcp-ai-agent#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_f6686d472c4548ada16c6e08363cb8f5"
}