# https://github.com/LeelaissakAttota/mcp-ai-agent 项目说明书

生成时间：2026-05-13 03:43:18 UTC

## 目录

- [项目概览](#page-1)
- [技术栈详解](#page-2)
- [系统架构设计](#page-3)
- [LangGraph ReAct代理实现](#page-4)
- [持久化对话记忆机制](#page-5)
- [MultiServerMCPClient配置](#page-6)
- [集成MCP服务器详解](#page-7)
- [安装与配置指南](#page-8)
- [运行与交互指南](#page-9)
- [扩展与定制指南](#page-10)

<a id='page-1'></a>

## 项目概览

### 相关页面

相关主题：[技术栈详解](#page-2), [系统架构设计](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)
- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)
</details>

# 项目概览

## 项目简介

mcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器智能代理项目，扮演着 AI 应用与外部工具服务之间的 **"Universal Interface"**（通用接口）角色，类似于 USB-C 在硬件连接中的地位。该项目实现了同时连接多个 MCP 服务器、跨协议传输管理、持久化对话记忆以及由 GPT-5 Nano 驱动的自主工具选择能力。

**技术定位：** Agentic AI — 多服务器 MCP 代理  
**编程语言：** Python 3.10+  
**核心模型：** OpenAI GPT-5 Nano  
**代理框架：** LangGraph ReAct  
**协议支持：** STDIO + HTTP 双传输层

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

## 核心架构

### 系统架构图

```mermaid
graph TB
    subgraph 用户层["用户层 (CLI 界面)"]
        U[用户输入查询]
    end
    
    subgraph 代理层["LangGraph ReAct 代理"]
        LLM[GPT-5 Nano<br/>推理引擎]
        MEM[InMemorySaver<br/>对话记忆]
        TOOL[自主工具选择]
    end
    
    subgraph 传输层["MCP 传输层"]
        HTTP[HTTP Transport<br/>远程云端]
        STDIO[STDIO Transport<br/>本地 npx]
    end
    
    subgraph 服务层["MCP 服务器"]
        C7[Context7 Server<br/>文档搜索]
        MET[MetMuseum Server<br/>艺术馆数据]
    end
    
    U --> LLM
    LLM --> TOOL
    TOOL --> HTTP
    TOOL --> STDIO
    HTTP --> C7
    STDIO --> MET
    LLM <--> MEM
```

### 技术组件表

| 组件类别 | 技术实现 | 功能说明 |
|---------|---------|---------|
| **MCP 客户端** | MultiServerMCPClient (langchain-mcp-adapters) | 多服务器并发连接管理 |
| **代理框架** | LangGraph ReAct | 推理+行动一体化代理 |
| **语言模型** | ChatOpenAI (gpt-5-nano) | 自然语言理解和生成 |
| **记忆系统** | InMemorySaver | 线程化对话持久化 |
| **异步运行时** | asyncio | 并发任务执行 |
| **HTTP 服务器** | Context7 (streamable_http) | 远程文档检索 |
| **STDIO 服务器** | metmuseum-mcp (npx) | 本地艺术馆数据访问 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

## 工作流程

### 代理决策流程

```mermaid
graph TD
    A[用户自然语言查询] --> B{GPT-5 Nano 推理}
    B --> C{判断查询类型}
    C -->|代码/文档类| D[调用 Context7 HTTP]
    C -->|艺术/博物馆类| E[调用 MetMuseum STDIO]
    D --> F[获取文档数据]
    E --> G[获取艺术品数据]
    F --> H[LLM 生成响应]
    G --> H
    H --> I[存储至 InMemorySaver]
    I --> J[返回用户响应]
```

### 典型交互流程

| 步骤 | 阶段 | 说明 |
|-----|------|------|
| 1 | 用户输入 | 通过 CLI 输入自然语言问题 |
| 2 | LLM 推理 | GPT-5 Nano 分析查询意图 |
| 3 | 工具选择 | 自动决定调用哪个 MCP 服务器 |
| 4 | 工具执行 | 跨协议执行对应工具调用 |
| 5 | 结果处理 | 工具结果返回给 LLM |
| 6 | 响应生成 | LLM 生成自然语言回复 |
| 7 | 记忆存储 | 完整对话存入线程化存储 |
| 8 | 用户展示 | 显示最终响应给用户 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

## 集成 MCP 服务器

### 服务器配置表

| 服务器名称 | 传输协议 | 端点/命令 | 数据类型 | 用途 |
|-----------|---------|----------|---------|------|
| **Context7** | HTTP (streamable_http) | `https://mcp.context7.com/mcp` | 软件框架文档 | LLM 优化的多框架文档搜索 |
| **MetMuseum-MCP** | STDIO | `npx -y metmuseum-mcp` | 艺术品元数据 | 40万+ 大都会艺术博物馆藏品 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

### 多服务器连接实现

```python
client = MultiServerMCPClient({
    "context7": {
        "url": "https://mcp.context7.com/mcp",
        "transport": "streamable_http",  # 远程 HTTP
    },
    "met-museum": {
        "command": "npx",
        "args": ["-y", "metmuseum-mcp"],
        "transport": "stdio",            # 本地 STDIO
    }
})
tools = await client.get_tools()  # 聚合所有服务器工具
```

资料来源：[main.py:22-35](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)

## 核心功能特性

### 1. LangGraph ReAct 代理

代理采用 ReAct（Reasoning + Acting）模式，结合 GPT-5 Nano 的推理能力与工具调用能力：

```python
agent = create_react_agent(
    model=openai_model,      # GPT-5 Nano 推理引擎
    tools=tools,              # 聚合的 MCP 工具集
    checkpointer=checkpointer # 持久化记忆
)
```

### 2. 持久化对话记忆

通过 InMemorySaver 实现线程化的对话状态保持：

```python
checkpointer = InMemorySaver()
config = {"configurable": {"thread_id": "conversation_id"}}
```

每个线程（thread_id）维护独立的对话上下文，支持跨轮次上下文理解。

### 3. 自主工具选择

LLM 根据用户查询语义自动判断应调用哪个服务器：

| 用户查询示例 | 调用的服务器 | 返回内容 |
|-------------|-------------|---------|
| "LangChain 代理文档" | Context7 | 框架文档检索结果 |
| "梵高的画作" | MetMuseum | 艺术品元数据+图片 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

## 项目结构

```
mcp-ai-agent/
│
├── main.py          # 完整的多服务器 MCP 代理实现
│   ├── 导入模块 (第1-6行)
│   ├── MCP 客户端配置 (第22-35行)
│   ├── OpenAI 模型初始化 (第42-44行)
│   ├── 工具获取 (第47行)
│   ├── 记忆系统配置 (第50-53行)
│   └── 代理创建与交互循环 (第56-86行)
│
└── README.md        # 项目文档
```

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

## 快速开始

### 环境准备

| 依赖项 | 安装命令 |
|-------|---------|
| langchain-mcp-adapters | `pip install langchain-mcp-adapters` |
| langgraph | `pip install langgraph` |
| langchain-openai | `pip install langchain-openai` |
| npx | `npm install -g npx` |

### 运行步骤

1. **安装依赖**
   ```bash
   pip install langchain-mcp-adapters langgraph langchain-openai
   npm install -g npx
   ```

2. **配置环境变量**
   ```bash
   export OPENAI_API_KEY="your-api-key-here"
   ```

3. **启动代理**
   ```bash
   python main.py
   ```

4. **交互操作**
   ```
   Menu:
   1. Ask the agent a question
   2. Quit
   Enter your choice (1 or 2): 1
   
   Your question
   > What LangGraph tools are available?
   → 代理调用 Context7 → 返回文档
   ```

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

## 关键技术亮点

| 特性 | 技术实现 | 优势 |
|-----|---------|-----|
| 多协议并发 | STDIO + HTTP 同时管理 | 灵活连接本地/远程服务 |
| 对话持久化 | InMemorySaver + thread_id | 跨会话上下文保持 |
| 异步架构 | asyncio + await | 高效并发任务处理 |
| 自主决策 | LLM 推理引擎 | 无需人工指定工具 |
| 跨域查询 | 多 MCP 服务器聚合 | 统一的自然语言接口 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

## 适用场景

- **文档智能问答**：通过 Context7 检索编程框架文档并回答技术问题
- **艺术藏品探索**：查询大都会艺术博物馆的藏品信息和图像
- **多源数据整合**：聚合不同领域的外部数据源
- **智能助手开发**：构建具有工具调用能力的对话代理

---

<a id='page-2'></a>

## 技术栈详解

### 相关页面

相关主题：[项目概览](#page-1), [系统架构设计](#page-3), [LangGraph ReAct代理实现](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)
- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)
</details>

# 技术栈详解

## 概述

mcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器 AI 智能体项目，通过集成多个 MCP 服务器实现跨域查询能力。该项目采用 Python 3.10+ 开发，核心架构围绕 LangGraph ReAct 智能体构建，结合 OpenAI GPT-5 Nano 模型进行推理决策，并通过 InMemorySaver 实现会话持久化管理。

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

## 核心技术组件

### 2.1 编程语言与运行环境

| 组件 | 版本要求 | 说明 |
|------|----------|------|
| Python | 3.10+ | 主要开发语言 |
| Node.js | 需安装 | 用于运行 MetMuseum-MCP 服务器 |
| npm/npx | 需全局安装 | 包管理和 MCP 服务器启动 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

### 2.2 核心依赖库

| 库名称 | 版本要求 | 功能描述 |
|--------|----------|----------|
| langchain-mcp-adapters | 最新版 | MCP 多服务器客户端适配器 |
| langgraph | 最新版 | ReAct 智能体构建框架 |
| langchain-openai | 最新版 | OpenAI 语言模型集成 |
| asyncio | 标准库 | 异步编程支持 |

资料来源：[main.py:1-7](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)

### 2.3 语言模型

项目采用 OpenAI GPT-5 Nano 模型作为推理引擎，负责以下核心任务：

- 理解用户自然语言查询意图
- 自主决策调用哪个 MCP 服务器
- 生成最终的自然语言响应

```python
openai_model = ChatOpenAI(
    model="gpt-5-nano",  # 使用 OpenAI GPT-5 Nano 模型
)
```

资料来源：[main.py:49-51](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)

## 架构设计

### 3.1 系统架构图

```mermaid
graph TD
    User[用户 CLI 界面] --> Agent[LangGraph ReAct 智能体]
    Agent --> LLM[GPT-5 Nano 推理引擎]
    LLM --> Decision[自主工具选择]
    Decision --> Context7[Context7 服务器<br/>HTTP 传输]
    Decision --> MetMuseum[MetMuseum-MCP 服务器<br/>STDIO 传输]
    Context7 --> DocsResult[库/代码文档]
    MetMuseum --> ArtResult[艺术品元数据/图片]
    Agent --> Memory[InMemorySaver<br/>会话记忆]
    
    subgraph 传输层
        Context7
        MetMuseum
    end
```

### 3.2 分层职责

| 层级 | 组件 | 职责 |
|------|------|------|
| 表现层 | CLI 用户交互界面 | 接收用户输入，展示智能体响应 |
| 智能体层 | LangGraph ReAct Agent | 协调推理、工具调用、响应生成 |
| 推理层 | GPT-5 Nano | 理解意图、决策路由、生成回复 |
| 工具层 | MCP Servers | 提供外部数据查询能力 |
| 持久化层 | InMemorySaver | 维护会话线程记忆 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

## MCP 多服务器架构

### 4.1 MultiServerMCPClient 配置

项目使用 `MultiServerMCPClient` 同时管理两个不同传输协议的 MCP 服务器：

```python
client = MultiServerMCPClient({
    # Context7 服务器 - 提供库文档访问
    "context7": {
        "url": "https://mcp.context7.com/mcp",
        "transport": "streamable_http",  # 远程 HTTP 传输
    },
    # Met Museum 服务器 - 提供博物馆藏品数据
    "met-museum": {
        "command": "npx",  # Node.js 包运行器
        "args": ["-y", "metmuseum-mcp"],
        "transport": "stdio",  # 标准输入/输出传输
    }
})
```

资料来源：[main.py:26-42](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)

### 4.2 集成 MCP 服务器对比

| 服务器名称 | 传输协议 | 连接类型 | 主要功能 | 工具数量 |
|-----------|---------|----------|---------|----------|
| Context7 | streamable_http | 远程/云端 | LLM 优化文档搜索，覆盖主流框架库 | 多工具 |
| MetMuseum-MCP | stdio | 本地/npx | 访问大都会艺术博物馆 40 万+藏品 | 多工具 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

### 4.3 传输协议详解

#### HTTP 流式传输 (streamable_http)

- **适用场景**：远程云端 MCP 服务器
- **优势**：低延迟、易穿越防火墙、支持流式响应
- **配置参数**：
  - `url`: 服务器端点 URL
  - `transport`: 必须设为 `streamable_http`

#### STDIO 传输 (stdio)

- **适用场景**：本地 MCP 服务器
- **优势**：简单可靠、无需网络配置
- **配置参数**：
  - `command`: 执行命令（通常为 `npx`）
  - `args`: 命令参数列表
  - `transport`: 必须设为 `stdio`

## LangGraph ReAct 智能体

### 5.1 智能体创建

```python
agent = create_react_agent(
    model=openai_model,         # 语言模型
    tools=tools,                # MCP 服务器工具
    checkpointer=checkpointer  # 会话记忆检查点
)
```

资料来源：[main.py:60-64](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)

### 5.2 ReAct 工作流程

```mermaid
graph LR
    A[用户查询] --> B[Reasoning<br/>推理阶段]
    B --> C[Action<br/>行动阶段]
    C --> D[Observation<br/>观察阶段]
    D --> E{完成?}
    E -->|否| B
    E -->|是| F[最终响应]
```

### 5.3 ReAct 模式特点

| 阶段 | 描述 | 执行者 |
|------|------|--------|
| Reasoning | 分析用户意图，决定是否调用工具 | GPT-5 Nano |
| Action | 调用选定的 MCP 工具 | 工具执行器 |
| Observation | 接收工具返回结果 | 智能体 |
| Response | 基于观察结果生成自然语言回复 | GPT-5 Nano |

## 会话记忆系统

### 6.1 InMemorySaver 检查点器

```python
checkpointer = InMemorySaver()  # 内存会话检查点

config = {"configurable": {"thread_id": "conversation_id"}}
```

资料来源：[main.py:53-67](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)

### 6.2 线程管理机制

| 参数 | 说明 | 用途 |
|------|------|------|
| thread_id | 线程标识符 | 区分不同会话 |
| configurable | 可配置参数容器 | 传递线程 ID |
| messages | 消息历史 | 维护对话上下文 |

### 6.3 记忆持久化流程

```mermaid
sequenceDiagram
    participant User as 用户
    participant Agent as ReAct Agent
    participant Checkpointer as InMemorySaver
    participant LLM as GPT-5 Nano
    
    User->>Agent: 发送问题
    Agent->>Checkpointer: 加载历史消息
    Checkpointer-->>Agent: 返回对话历史
    Agent->>LLM: 发送完整上下文
    LLM-->>Agent: 生成响应
    Agent->>Checkpointer: 保存新消息
    Agent-->>User: 返回响应
```

## 异步编程模式

### 7.1 异步入口点

```python
if __name__ == "__main__":
    asyncio.run(main())
```

资料来源：[main.py:92-94](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)

### 7.2 异步调用模式

| 操作 | 异步关键字 | 说明 |
|------|-----------|------|
| MCP 客户端初始化 | `await client` | 连接多个 MCP 服务器 |
| 获取工具 | `await client.get_tools()` | 异步获取可用工具列表 |
| 智能体调用 | `await agent.ainvoke()` | 异步执行智能体推理 |

### 7.3 事件循环管理

```mermaid
graph TD
    A[asyncio.run] --> B[创建事件循环]
    B --> C[执行 main 协程]
    C --> D[MCP 客户端连接]
    D --> E[工具初始化]
    E --> F[ReAct 智能体运行]
    F --> G[用户交互循环]
    G --> F
```

## 工具集成与自主选择

### 8.1 工具获取

```python
tools = await client.get_tools()  # 获取所有 MCP 服务器工具
```

资料来源：[main.py:53](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)

### 8.2 自主工具选择逻辑

| 用户查询类型 | 智能体决策 | 调用服务器 | 返回内容 |
|-------------|-----------|-----------|---------|
| 代码/库文档问题 | "需要文档" | Context7 | LLM 优化文档 |
| 艺术/博物馆查询 | "需要藏品数据" | MetMuseum | 艺术品元数据/图片 |

### 8.3 工具选择流程图

```mermaid
graph TD
    A[用户自然语言查询] --> B{GPT-5 Nano 意图分析}
    B -->|代码/框架文档| C[Context7 工具]
    B -->|艺术品/博物馆| D[MetMuseum 工具]
    B -->|其他| E[无工具调用]
    C --> F[返回文档内容]
    D --> G[返回艺术品数据]
    E --> H[直接生成回复]
```

## 系统消息配置

### 9.1 智能体角色定义

```python
{"role": "system", "content": "You are a smart, useful agent with tools to access code library documentation and the Met Museum collection."}
```

资料来源：[main.py:72-73](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)

### 9.2 消息类型

| 消息角色 | 来源 | 内容示例 |
|---------|------|---------|
| system | 系统定义 | 智能体角色设定 |
| user | 用户输入 | 用户的自然语言问题 |
| assistant | 智能体生成 | 最终响应内容 |

## 依赖安装

### 10.1 Python 依赖

```bash
pip install langchain-mcp-adapters langgraph langchain-openai
```

### 10.2 Node.js 环境

```bash
npm install -g npx
```

### 10.3 环境变量配置

```bash
export OPENAI_API_KEY="your-api-key-here"
```

## 技术栈总结

| 层级 | 技术选型 | 版本 | 关键作用 |
|------|---------|------|---------|
| 运行时 | Python 3.10+ | 3.10+ | 主要开发语言 |
| 智能体框架 | LangGraph ReAct | 最新 | 推理与工具调用编排 |
| 大语言模型 | GPT-5 Nano | - | 自然语言理解和生成 |
| MCP 客户端 | MultiServerMCPClient | 最新 | 多服务器连接管理 |
| 会话持久化 | InMemorySaver | 最新 | 对话历史记忆 |
| 异步框架 | asyncio | 标准库 | 非阻塞 I/O 操作 |
| 文档服务器 | Context7 | HTTP | 库文档查询 |
| 博物馆服务器 | MetMuseum-MCP | STDIO | 艺术品数据查询 |

资料来源：[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)

---

<a id='page-3'></a>

## 系统架构设计

### 相关页面

相关主题：[项目概览](#page-1), [LangGraph ReAct代理实现](#page-4), [MultiServerMCPClient配置](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)
- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)
</details>

# 系统架构设计

## 概述

mcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器 AI 代理系统，旨在为用户提供统一的接口来访问多个外部服务。该系统利用 LangGraph ReAct 架构实现自主工具选择，并支持 STDIO 和 HTTP 两种传输协议的并发管理。资料来源：[README.md:1]()、[main.py:1-10]()

### 项目定位

该系统被定位为 **"通用接口"**，类似于 USB-C 在硬件连接中的作用，能够同时连接多个 MCP 服务器，支持持久化对话记忆，并基于 GPT-5 Nano 模型实现自主工具调用能力。资料来源：[README.md:3]()

### 技术领域

| 领域 | 说明 |
|------|------|
| 代理类型 | 多服务器 MCP 代理 |
| 编程语言 | Python 3.10+ |
| LLM 模型 | OpenAI GPT-5 Nano |
| 代理框架 | LangGraph ReAct with 持久化内存 |

## 核心架构组件

### 系统层级结构

```
┌──────────────────────────────────────────────────────┐
│           用户层 (CLI 交互界面)                        │
│   "梵高创作了哪些画作？"                               │
│   "展示 LangChain 文档"                              │
└───────────────────────┬──────────────────────────────┘
                        │
┌───────────────────────▼──────────────────────────────┐
│         LangGraph ReAct 代理层                        │
│   • GPT-5 Nano 推理引擎                              │
│   • InMemorySaver 线程级对话记忆                       │
│   • 自主选择调用哪个 MCP 服务器                        │
└──────────┬────────────────────────┬──────────────────┘
           │                        │
    HTTP 传输                  STDIO 传输
           │                        │
┌──────────▼──────────┐   ┌─────────▼──────────────────┐
│   Context7 服务器    │   │   MetMuseum-MCP 服务器     │
│   (远程/云端)        │   │   (本地通过 npx 运行)       │
│                     │   │                             │
│  主流框架/库的 LLM   │   │  大都会艺术博物馆           │
│  优化文档搜索        │   │  400,000+ 艺术品            │
└─────────────────────┘   └─────────────────────────────┘
```

### 技术栈明细

| 组件类别 | 技术选型 | 版本要求 |
|----------|----------|----------|
| 编程语言 | Python | 3.10+ |
| MCP 客户端 | MultiServerMCPClient (langchain-mcp-adapters) | 最新稳定版 |
| 代理框架 | LangGraph ReAct | 最新稳定版 |
| LLM | ChatOpenAI (GPT-5 Nano) | OpenAI API |
| 对话记忆 | InMemorySaver | LangGraph 内置 |
| 异步支持 | asyncio | Python 标准库 |
| MCP 服务器 1 | Context7 | HTTP 流式传输 |
| MCP 服务器 2 | MetMuseum-MCP | STDIO 本地执行 |

资料来源：[README.md:56-66]()

## 通信传输机制

### HTTP 传输 (Context7)

Context7 服务器通过 `streamable_http` 协议实现远程通信。这种方式适合云端部署的文档服务，具有以下特点：

- **传输协议**：`streamable_http`
- **端点地址**：`https://mcp.context7.com/mcp`
- **部署模式**：远程/云端
- **适用场景**：需要访问大型软件框架文档库的场景

```python
"context7": {
    "url": "https://mcp.context7.com/mcp",
    "transport": "streamable_http",
}
```

资料来源：[main.py:21-24]()

### STDIO 传输 (MetMuseum)

MetMuseum MCP 服务器通过标准输入输出（STDIO）协议实现本地通信：

- **传输协议**：`stdio`
- **执行命令**：`npx -y metmuseum-mcp`
- **部署模式**：本地通过 Node.js npx 执行
- **适用场景**：本地艺术品数据查询

```python
"met-museum": {
    "command": "npx",
    "args": ["-y", "metmuseum-mcp"],
    "transport": "stdio",
}
```

资料来源：[main.py:25-29]()

## 代理工作流程

### 完整请求处理流程

```mermaid
graph TD
    A[用户输入查询] --> B{GPT-5 Nano 推理}
    B --> C["判断查询类型"]
    C -->|代码/库文档| D[Context7 HTTP 调用]
    C -->|艺术品/博物馆| E[MetMuseum STDIO 调用]
    D --> F[获取文档数据]
    E --> G[获取艺术品元数据]
    F --> H[结果返回 LLM]
    G --> H
    H --> I[LLM 生成自然语言响应]
    I --> J[InMemorySaver 保存对话]
    J --> K[用户接收响应]
```

### 工具自主选择机制

代理能够根据用户查询内容自主判断应调用哪个 MCP 服务器：

| 用户查询示例 | 调用服务器 | 返回数据类型 |
|--------------|------------|--------------|
| "LangChain 代理工具是什么？" | Context7 | LLM 优化文档 |
| "展示大都会博物馆的印象派画作" | MetMuseum | 艺术品元数据及图片 |

资料来源：[README.md:42-51]()

## 核心模块设计

### MCP 客户端模块

```python
from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "context7": {
        "url": "https://mcp.context7.com/mcp",
        "transport": "streamable_http",
    },
    "met-museum": {
        "command": "npx",
        "args": ["-y", "metmuseum-mcp"],
        "transport": "stdio",
    }
})

tools = await client.get_tools()
```

该模块负责同时连接多个 MCP 服务器，并聚合所有可用的工具供代理使用。资料来源：[main.py:13-29]()

### LLM 模型配置

```python
from langchain_openai import ChatOpenAI

openai_model = ChatOpenAI(
    model="gpt-5-nano",
)
```

使用 OpenAI 的 GPT-5 Nano 模型作为推理引擎，该模型负责理解用户意图并进行工具调用决策。资料来源：[main.py:37-39]()

### ReAct 代理创建

```python
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()
config = {"configurable": {"thread_id": "conversation_id"}}

agent = create_react_agent(
    model=openai_model,
    tools=tools,
    checkpointer=checkpointer,
)
```

ReAct 代理结合了推理（Reasoning）和行动（Acting）能力，通过 checkpointer 实现对话记忆持久化。资料来源：[main.py:42-52]()

### 对话记忆系统

```python
config = {"configurable": {"thread_id": "conversation_id"}}

response = await agent.ainvoke(
    {"messages": query},
    config=config
)
```

InMemorySaver 提供了线程级别的对话历史持久化，确保代理在多轮对话中保持上下文理解能力。资料来源：[main.py:72-77]()

## 交互流程设计

### 启动与初始化

1. 配置 MultiServerMCPClient 连接两个 MCP 服务器
2. 初始化 ChatOpenAI 模型
3. 获取所有可用工具
4. 创建 InMemorySaver 检查点
5. 构建 ReAct 代理实例

```mermaid
sequenceDiagram
    participant User as 用户
    participant Agent as LangGraph Agent
    participant Client as MCP Client
    participant Context7 as Context7 Server
    participant MetMuseum as MetMuseum Server

    User->>Agent: 启动程序
    Client->>Context7: 建立 HTTP 连接
    Client->>MetMuseum: 启动 npx 进程 (STDIO)
    Client->>Agent: 获取工具列表
    Agent->>User: 显示初始介绍

    loop 主交互循环
        User->>Agent: 输入问题
        Agent->>Agent: GPT-5 Nano 推理
        Agent->>Client: 调用工具
        Client->>Context7: 查询文档 (可选)
        Client->>MetMuseum: 查询艺术品 (可选)
        Context7-->>Client: 返回文档数据
        MetMuseum-->>Client: 返回艺术品数据
        Client-->>Agent: 工具执行结果
        Agent->>Agent: 生成自然语言响应
        Agent-->>User: 返回最终回答
    end
```

### 菜单交互模式

系统提供基于菜单的交互方式：

```
Menu:
1. Ask the agent a question
2. Quit
Enter your choice (1 or 2):
```

- 选择 "1"：进入问答模式，代理接收并处理用户查询
- 选择 "2"：退出程序

资料来源：[main.py:57-85]()

## 数据流设计

### 消息传递机制

```mermaid
graph LR
    A[用户消息] --> B[系统消息配置]
    B --> C[消息数组]
    C --> D[agent.ainvoke 调用]
    D --> E[LangGraph 状态机]
    E --> F[工具执行]
    F --> G[结果聚合]
    G --> H[LLM 响应生成]
    H --> I[最终输出]
```

### 配置参数表

| 参数名称 | 类型 | 说明 | 默认值 |
|----------|------|------|--------|
| thread_id | string | 对话线程标识符 | "conversation_id" |
| model | string | LLM 模型名称 | "gpt-5-nano" |
| transport | string | 通信传输协议 | streamable_http / stdio |

资料来源：[main.py:45-47]()

## 系统初始化代码结构

```python
async def main():
    """主函数：设置并运行具有多个 MCP 服务器访问权限的 AI 代理"""

    # 1. 配置 MCP 服务器
    client = MultiServerMCPClient({...})

    # 2. 初始化 OpenAI 语言模型
    openai_model = ChatOpenAI(model="gpt-5-nano")

    # 3. 获取所有可用工具
    tools = await client.get_tools()

    # 4. 设置对话记忆
    checkpointer = InMemorySaver()
    config = {"configurable": {"thread_id": "conversation_id"}}

    # 5. 创建 ReAct 代理
    agent = create_react_agent(
        model=openai_model,
        tools=tools,
        checkpointer=checkpointer,
    )

    # 6. 发送初始介绍消息
    response = await agent.ainvoke({...}, config=config)

    # 7. 主交互循环
    while True:
        choice = input("Menu:...")
        if choice == "1":
            query = input("> ")
            response = await agent.ainvoke({"messages": query}, config=config)
            print(response['messages'][-1].content)
```

资料来源：[main.py:12-85]()

## 关键设计决策

### 多服务器架构优势

| 优势 | 说明 |
|------|------|
| 能力扩展性 | 可通过添加新 MCP 服务器无缝扩展功能 |
| 协议兼容性 | 同时支持 STDIO 和 HTTP 两种传输协议 |
| 自主路由 | LLM 自动选择最合适的服务器处理查询 |
| 持久化记忆 | InMemorySaver 确保多轮对话上下文连贯 |

### 技术选型理由

| 组件 | 选型理由 |
|------|----------|
| LangGraph | 提供成熟的 ReAct 代理实现和状态管理 |
| MultiServerMCPClient | 原生支持多服务器并发连接 |
| InMemorySaver | 轻量级内存存储，适合演示和小规模部署 |
| GPT-5 Nano | 成本效益高的推理模型，适合工具调用场景 |

资料来源：[README.md:4-12]()

## 依赖安装指南

### Python 依赖

```bash
pip install langchain-mcp-adapters langgraph langchain-openai
```

### Node.js 依赖

```bash
npm install -g npx
```

### 环境变量配置

```bash
export OPENAI_API_KEY="your-api-key-here"
```

资料来源：[README.md:30-36]()

## 启动与运行

### 运行命令

```bash
python main.py
```

### 执行流程

1. 初始化 MCP 客户端连接
2. 加载可用的工具
3. 代理自我介绍
4. 进入主菜单循环
5. 处理用户查询并返回结果

资料来源：[main.py:88-91]()

---

<a id='page-4'></a>

## LangGraph ReAct代理实现

### 相关页面

相关主题：[系统架构设计](#page-3), [持久化对话记忆机制](#page-5), [MultiServerMCPClient配置](#page-6)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)
</details>

# LangGraph ReAct代理实现

## 概述

LangGraph ReAct代理是该项目的核心智能组件，负责协调用户查询、MCP服务器工具调用以及对话记忆管理。该代理基于LangGraph框架的ReAct（Reasoning + Acting）设计模式构建，结合OpenAI GPT-5 Nano模型实现自主工具选择和自然语言响应生成功能。

## 核心架构

### 系统组件关系

```mermaid
graph TD
    A[用户 CLI 交互] --> B[LangGraph ReAct Agent]
    B --> C[GPT-5 Nano 模型]
    C --> D{自主工具选择}
    D --> E[Context7 HTTP]
    D --> F[MetMuseum STDIO]
    E --> G[工具执行结果]
    F --> G
    G --> C
    C --> H[自然语言响应]
    H --> I[InMemorySaver 记忆存储]
    I --> B
```

### 技术栈概览

| 组件 | 技术实现 | 版本要求 |
|------|----------|----------|
| 代理框架 | `create_react_agent` | langgraph |
| 语言模型 | `ChatOpenAI` | langchain-openai |
| MCP客户端 | `MultiServerMCPClient` | langchain-mcp-adapters |
| 对话记忆 | `InMemorySaver` | langgraph.checkpoint.memory |
| 传输协议 | STDIO + streamable_http | 混合模式 |

## 代理初始化流程

### 源码实现解析

代理的初始化过程包含四个关键步骤：

```python
# 第一步：配置MCP服务器连接
client = MultiServerMCPClient({
    "context7": {
        "url": "https://mcp.context7.com/mcp",
        "transport": "streamable_http",
    },
    "met-museum": {
        "command": "npx",
        "args": ["-y", "metmuseum-mcp"],
        "transport": "stdio",
    }
})
```

资料来源：[main.py:33-45]()

```python
# 第二步：初始化OpenAI语言模型
openai_model = ChatOpenAI(model="gpt-5-nano")
```

资料来源：[main.py:49-50]()

```python
# 第三步：获取所有MCP服务器工具
tools = await client.get_tools()
```

资料来源：[main.py:52]()

```python
# 第四步：创建ReAct代理
agent = create_react_agent(
    model=openai_model,
    tools=tools,
    checkpointer=InMemorySaver()
)
```

资料来源：[main.py:58-62]()

### 初始化参数说明

| 参数 | 类型 | 说明 | 来源配置 |
|------|------|------|----------|
| model | ChatOpenAI | 提供推理和响应生成能力 | 必须 |
| tools | List[BaseTool] | 从MCP服务器获取的工具集合 | 必须 |
| checkpointer | InMemorySaver | 持久化对话历史记录 | 可选 |

## ReAct执行机制

### 推理与行动循环

LangGraph ReAct代理采用"推理-行动"循环模式处理用户查询：

```mermaid
graph TD
    A[用户查询输入] --> B[Reasoning: 分析查询意图]
    B --> C{判断是否需要调用工具?}
    C -->|是| D[Action: 选择合适工具]
    D --> E[Execute: 执行工具调用]
    E --> F[Observation: 获取工具返回结果]
    F --> B
    C -->|否| G[Final Response: 直接生成响应]
```

### 对话上下文管理

代理通过线程ID机制维护多轮对话上下文：

```python
config = {"configurable": {"thread_id": "conversation_id"}}

response = await agent.ainvoke(
    {"messages": query},
    config=config
)
```

资料来源：[main.py:54-60]()

**上下文管理特点：**

- 每个会话拥有唯一thread_id
- 所有历史消息自动持久化到InMemorySaver
- 后续查询自动携带完整对话上下文

## MCP服务器集成

### 多服务器连接架构

```mermaid
graph LR
    A[ReAct Agent] <-->|统一工具接口| B[MultiServerMCPClient]
    B -->|streamable_http| C[Context7 Server]
    B -->|stdio| D[MetMuseum MCP]
```

### 服务器配置对比

| 服务器 | 传输协议 | 用途 | 连接参数 |
|--------|----------|------|----------|
| Context7 | HTTP | 代码库文档检索 | URL: https://mcp.context7.com/mcp |
| MetMuseum | STDIO | 博物馆藏品查询 | command: npx, args: metmuseum-mcp |

### 工具自动路由

代理根据查询内容自动选择目标服务器：

```
用户: "LangChain代理相关文档" → Context7服务器
用户: "梵高的绘画作品" → MetMuseum服务器
```

## 对话流程实现

### 主交互循环

```python
while True:
    choice = input("""
Menu:
1. Ask the agent a question
2. Quit
Enter your choice (1 or 2): """)

    if choice == "1":
        query = input("> ")
        response = await agent.ainvoke(
            {"messages": query},
            config=config
        )
        print(response['messages'][-1].content)
    else:
        break
```

资料来源：[main.py:71-84]()

### 异步执行模式

整个应用采用异步架构，通过asyncio事件循环驱动：

```python
async def main():
    # 异步初始化和代理执行
    ...

if __name__ == "__main__":
    asyncio.run(main())
```

资料来源：[main.py:24-89]()

## 代理系统提示

代理初始化时注入系统级提示词，定义其角色定位：

```python
{"role": "system", "content": "You are a smart, useful agent with tools to access code library documentation and the Met Museum collection."}
```

资料来源：[main.py:67]()

## 关键特性总结

### 核心能力矩阵

| 特性 | 实现方式 | 技术依赖 |
|------|----------|----------|
| 多服务器并发 | MultiServerMCPClient | langchain-mcp-adapters |
| 持久化记忆 | InMemorySaver | langgraph.checkpoint.memory |
| 自主工具选择 | LLM推理 | GPT-5 Nano |
| 对话连续性 | thread_id配置 | LangGraph checkpointer |
| 异步通信 | asyncio | Python标准库 |

### 执行流程总览

```mermaid
graph LR
    A[CLI Input] --> B[ReAct Agent]
    B --> C[LLM Reasoning]
    C --> D[Tool Selection]
    D --> E[MCP Tool Call]
    E --> F[Result Aggregation]
    F --> G[LLM Response]
    G --> H[Memory Update]
    H --> I[User Output]
```

## 扩展与定制

### 修改系统提示

如需自定义代理行为，修改main.py中的system message内容：

```python
{"role": "system", "content": "自定义代理描述"}
```

### 添加新MCP服务器

在MultiServerMCPClient配置中追加新的服务器条目：

```python
client = MultiServerMCPClient({
    "context7": {...},
    "met-museum": {...},
    "new-server": {
        "command": "npx",
        "args": ["-y", "new-mcp-package"],
        "transport": "stdio",
    }
})
```

### 更换语言模型

调整ChatOpenAI初始化参数以使用其他模型：

```python
openai_model = ChatOpenAI(model="gpt-4")

---

<a id='page-5'></a>

## 持久化对话记忆机制

### 相关页面

相关主题：[LangGraph ReAct代理实现](#page-4), [运行与交互指南](#page-9)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)
</details>

# 持久化对话记忆机制

## 概述

持久化对话记忆机制是 mcp-ai-agent 项目中的核心功能模块，负责在多轮对话场景下维护用户与智能体之间的完整交流上下文。该机制基于 LangGraph 框架的 Checkpointer 实现，通过线程（Thread）隔离不同会话，确保每次对话交互都能回溯历史消息并进行连贯推理。

## 核心组件

### 1. InMemorySaver

`InMemorySaver` 是 LangGraph 框架提供的内存检查点保存器，负责存储对话状态快照。

| 属性 | 说明 |
|------|------|
| 类型 | 内存存储 |
| 来源 | `langgraph.checkpoint.memory` |
| 用途 | 持久化对话历史记录 |
| 生命周期 | 进程运行期间有效 |

```python
from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()
```

资料来源：[main.py:28]()

### 2. 会话配置（Config）

会话配置定义了对话线程的唯一标识符，是实现多会话隔离的关键参数。

| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `thread_id` | string | "conversation_id" | 会话线程唯一标识 |

```python
config = {"configurable": {"thread_id": "conversation_id"}}
```

资料来源：[main.py:67]()

### 3. ReAct Agent 集成

检查点保存器通过 `create_react_agent` 函数注入到智能体中，使智能体具备状态持久化能力。

```python
agent = create_react_agent(
    model=openai_model,
    tools=tools,
    checkpointer=checkpointer
)
```

资料来源：[main.py:70-74]()

## 工作流程

```mermaid
graph TD
    A[用户提问] --> B[构建查询消息]
    B --> C[调用 agent.ainvoke]
    C --> D{检查 thread_id}
    D -->|新会话| E[创建新线程]
    D -->|已有会话| F[加载历史状态]
    E --> G[执行推理与工具调用]
    F --> G
    G --> H[生成响应]
    H --> I[保存状态到 InMemorySaver]
    I --> J[返回响应给用户]
    J --> K[等待下一轮交互]
    K --> A
```

## 状态持久化流程

```mermaid
sequenceDiagram
    participant U as 用户
    participant A as ReAct Agent
    participant C as InMemorySaver
    participant M as LLM

    U->>A: 第一轮: 查询消息
    A->>C: 保存状态快照
    C-->>A: 确认保存
    A-->>U: 返回响应

    U->>A: 第二轮: 新查询
    A->>C: 加载 thread_id 对应状态
    C-->>A: 返回历史消息
    A->>M: 发送完整上下文
    M-->>A: 生成响应
    A->>C: 更新状态快照
    A-->>U: 返回响应
```

## 核心代码解析

### 主函数入口

```python
async def main():
    # 初始化 MCP 服务器客户端
    client = MultiServerMCPClient({...})

    # 初始化 LLM 模型
    openai_model = ChatOpenAI(model="gpt-5-nano")

    # 获取 MCP 服务器提供的工具
    tools = await client.get_tools()

    # 创建内存检查点保存器
    checkpointer = InMemorySaver()

    # 配置会话参数
    config = {"configurable": {"thread_id": "conversation_id"}}

    # 创建带持久化功能的 ReAct Agent
    agent = create_react_agent(
        model=openai_model,
        tools=tools,
        checkpointer=checkpointer
    )
```

资料来源：[main.py:31-75]()

### 智能体调用

```python
    # 发送用户查询，附带会话配置
    response = await agent.ainvoke(
        {"messages": query},
        config=config
    )

    # 输出智能体响应
    print(response['messages'][-1].content)
```

资料来源：[main.py:88-94]()

## 会话状态管理

```mermaid
graph LR
    subgraph 状态结构
        S1[消息列表] --> S2[System 消息]
        S1 --> S3[User 消息]
        S1 --> S4[Assistant 消息]
        S1 --> S5[Tool 调用记录]
    end

    subgraph 持久化存储
        P1[InMemorySaver]
        P1 -.->|存储| S1
        P1 -.->|检索| S2
        P1 -.->|检索| S3
        P1 -.->|检索| S4
        P1 -.->|检索| S5
    end
```

## 消息格式

对话中的消息采用标准角色格式存储：

| 角色 | 说明 | 示例 |
|------|------|------|
| `system` | 系统级指令 | 定义智能体角色定位 |
| `user` | 用户输入 | 用户提出的问题 |
| `assistant` | 智能体响应 | 包含文本和工具调用 |
| `tool` | 工具执行结果 | MCP 服务器返回的数据 |

```python
{"messages": [
    {"role": "system", "content": "You are a smart, useful agent..."},
    {"role": "user", "content": "用户问题内容"},
]}
```

资料来源：[main.py:77-82]()

## 初始化流程

智能体启动时会执行自我介绍，让用户了解其能力范围：

```python
response = await agent.ainvoke(
    {"messages": [
        {"role": "system", "content": "You are a smart, useful agent with tools to access code library documentation and the Met Museum collection."},
        {"role": "user", "content": "Give a brief introduction of what you do and the tools you can access."},
    ]},
    config=config
)
print(response['messages'][-1].content)
```

资料来源：[main.py:77-86]()

## 应用场景

### 单会话连续对话

用户在同一会话中提出多个相关问题，智能体能够理解上下文关联：

```
用户: "LangGraph 的工具调用是什么？"
智能体: [调用 Context7 获取文档]

用户: "能给我一个代码示例吗？"
智能体: [基于上一轮上下文生成示例]
```

### 上下文关联推理

记忆机制使智能体能够：

- 记住用户之前提到的技术栈或偏好
- 基于历史查询提供个性化响应
- 在多轮调试场景中理解问题演进过程

## 限制与注意事项

| 限制项 | 说明 |
|--------|------|
| 内存依赖 | 进程重启后记忆丢失 |
| 并发限制 | 多进程需要外部存储后端 |
| 线程隔离 | 不同 `thread_id` 完全独立 |

如需生产环境持久化，应替换为 `PostgresSaver` 或 `RedisSaver` 等外部存储适配器。

## 依赖关系

```mermaid
graph TD
    A[main.py] --> B[langgraph.checkpoint.memory]
    A --> C[langgraph.prebuilt.create_react_agent]
    A --> D[langchain_openai.ChatOpenAI]
    B --> E[InMemorySaver 类]
    C --> F[ReAct Agent 工厂函数]
```

## 扩展建议

如需增强持久化能力，可考虑以下方案：

1. **数据库持久化**：集成 PostgreSQL 或 SQLite
2. **分布式存储**：使用 Redis 实现跨进程共享
3. **会话管理**：实现会话超时自动清理机制
4. **状态序列化**：支持对话历史导出与恢复

---

<a id='page-6'></a>

## MultiServerMCPClient配置

### 相关页面

相关主题：[系统架构设计](#page-3), [集成MCP服务器详解](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)
</details>

# MultiServerMCPClient配置

## 概述

MultiServerMCPClient 是 langchain-mcp-adapters 库提供的核心客户端类，用于同时连接多个 MCP（Model Context Protocol）服务器。在本项目中，该客户端被配置为同时管理 HTTP 和 STDIO 两种传输协议的 MCP 服务器连接，使 LangGraph ReAct Agent 能够自主选择并调用来自不同域的工具。

**核心作用：**

- 统一管理多个 MCP 服务器的连接生命周期
- 支持异构传输协议（HTTP/STDIO）的并发连接
- 聚合来自不同服务器的可用工具，供 Agent 调用

资料来源：[main.py:12]()

## 架构设计

### 多服务器连接架构

```mermaid
graph TD
    A["LangGraph ReAct Agent"] --> B["MultiServerMCPClient"]
    B --> C["Context7 Server<br/>(HTTP)"]
    B --> D["MetMuseum Server<br/>(STDIO)"]
    C --> E["远程云端<br/>文档搜索服务"]
    D --> F["本地 npx<br/>博物馆数据服务"]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
```

### 传输协议对比

| 传输协议 | 实现方式 | 适用场景 | 延迟特性 |
|---------|---------|---------|---------|
| **streamable_http** | HTTP 长连接 | 远程云服务 | 中等延迟 |
| **stdio** | 标准输入输出 | 本地 Node.js 服务 | 低延迟 |

资料来源：[main.py:38-47]()

## 配置参数详解

### MultiServerMCPClient 构造函数参数

```python
client = MultiServerMCPClient({
    "context7": {
        "url": "https://mcp.context7.com/mcp",
        "transport": "streamable_http",
    },
    "met-museum": {
        "command": "npx",
        "args": ["-y", "metmuseum-mcp"],
        "transport": "stdio",
    }
})
```

### 服务器配置结构

| 参数名 | 类型 | 说明 | 必填 |
|-------|------|------|-----|
| `command` | string | 进程启动命令 | STDIO 传输时必填 |
| `args` | list[string] | 命令行参数列表 | STDIO 传输时必填 |
| `url` | string | 服务器端点 URL | HTTP 传输时必填 |
| `transport` | string | 传输协议类型 | 是 |

### Context7 服务器配置

```python
"context7": {
    "url": "https://mcp.context7.com/mcp",        # 服务器端点
    "transport": "streamable_http",                # HTTP 流式传输
}
```

**配置说明：**

- 该服务器提供 LLM 优化的软件框架文档搜索能力
- 传输协议使用 `streamable_http`，适合与远程云端服务通信
- 无需本地进程管理，服务端自动处理连接

### MetMuseum 服务器配置

```python
"met-museum": {
    "command": "npx",                              # Node.js 包运行器
    "args": ["-y", "metmuseum-mcp"],              # 自动安装并运行
    "transport": "stdio",                         # 标准输入输出传输
}
```

**配置说明：**

- 使用 npx 自动安装并运行 `metmuseum-mcp` 包
- STDIO 传输通过标准输入输出与本地 Node.js 进程通信
- 适合需要本地执行环境的工具服务

## 工具获取与使用

### 获取所有工具

```python
tools = await client.get_tools()
```

该方法异步获取所有已配置 MCP 服务器提供的工具集合，返回的 `tools` 列表包含来自 Context7 和 MetMuseum 两个服务器的所有可用工具。

### 工具聚合机制

```mermaid
graph LR
    A["Context7 Tools"] --> C["统一 Tools 列表"]
    B["MetMuseum Tools"] --> C
    C --> D["ReAct Agent"]
```

## 与 LangGraph Agent 集成

### 完整集成流程

```mermaid
sequenceDiagram
    participant User as 用户
    participant Agent as LangGraph ReAct
    participant Client as MultiServerMCPClient
    participant Servers as MCP Servers

    User->>Agent: 发送查询
    Agent->>Client: await client.get_tools()
    Client->>Servers: 获取工具定义
    Servers-->>Client: 返回工具列表
    Client-->>Agent: 聚合工具集
    Agent->>Servers: 调用选中工具
    Servers-->>Agent: 返回结果
    Agent-->>User: 自然语言响应
```

### Agent 创建代码

```python
# 初始化 OpenAI 模型
openai_model = ChatOpenAI(model="gpt-5-nano")

# 获取工具
tools = await client.get_tools()

# 创建 ReAct Agent
agent = create_react_agent(
    model=openai_model,
    tools=tools,
    checkpointer=InMemorySaver()
)
```

## 异步编程模式

### main 函数异步设计

```python
async def main():
    client = MultiServerMCPClient({...})
    tools = await client.get_tools()
    agent = create_react_agent(model, tools, checkpointer)
    # 异步调用
    response = await agent.ainvoke({"messages": query}, config=config)
```

### 事件循环执行

```python
if __name__ == "__main__":
    asyncio.run(main())
```

**要点说明：**

- 所有涉及 MCP 客户端的操作必须使用 `async/await` 模式
- 顶层入口通过 `asyncio.run()` 启动事件循环
- Agent 调用同样采用异步方式 `await agent.ainvoke()`

## 生命周期管理

### 连接初始化

| 阶段 | 操作 | 说明 |
|-----|------|-----|
| 1 | 创建 MultiServerMCPClient 实例 | 配置服务器参数 |
| 2 | 获取工具集 | `await client.get_tools()` |
| 3 | 创建 Agent | 绑定模型和工具 |
| 4 | 启动交互循环 | 处理用户查询 |

### 资源清理

MultiServerMCPClient 在上下文管理器退出或程序终止时自动关闭所有服务器连接。

## 配置最佳实践

### 开发环境配置建议

| 场景 | 推荐配置 |
|-----|---------|
| 本地开发 | 使用 STDIO 传输，便于调试 |
| 生产部署 | 优先使用 HTTP 传输，稳定性更高 |
| 混合场景 | 按服务特性选择传输协议 |

### 扩展新服务器

添加新 MCP 服务器只需在配置字典中增加条目：

```python
client = MultiServerMCPClient({
    "context7": {...},
    "met-museum": {...},
    "新服务器名称": {
        "command": "npx",
        "args": ["-y", "新服务包名"],
        "transport": "stdio",
    }
})
```

Agent 会自动发现并聚合新增服务器的工具，无需修改 Agent 创建代码。

## 依赖项

| 依赖包 | 版本要求 | 用途 |
|-------|---------|------|
| langchain-mcp-adapters | 最新版 | MultiServerMCPClient |
| langgraph | 最新版 | ReAct Agent 框架 |
| langchain-openai | 最新版 | OpenAI 模型集成 |
| asyncio | Python 3.10+ 内置 | 异步编程支持 |

资料来源：[main.py:1-11]()

---

<a id='page-7'></a>

## 集成MCP服务器详解

### 相关页面

相关主题：[MultiServerMCPClient配置](#page-6), [扩展与定制指南](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)
- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)
</details>

# 集成MCP服务器详解

## 概述

`集成MCP服务器详解`是本项目的核心功能模块，展示了如何构建一个**多服务器MCP（Model Context Protocol）客户端代理**系统。该系统能够同时连接多个不同传输协议的MCP服务器，实现跨域工具调用与智能工具选择能力。

本项目通过`MultiServerMCPClient`同时管理HTTP和STDIO两种传输协议的MCP服务器，结合LangGraph ReAct Agent架构和OpenAI GPT-5 Nano模型，构建了一个具有持久化会话记忆的多功能AI代理。

资料来源：[main.py:1-20](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L1-L20)

---

## 架构设计

### 系统整体架构

本项目采用分层架构设计，从上至下依次为：用户交互层、Agent推理层、MCP客户端层和服务器连接层。

```mermaid
graph TD
    A["用户 CLI 交互层"] --> B["LangGraph ReAct Agent"]
    B --> C["MultiServerMCPClient 客户端"]
    C --> D1["Context7 Server<br/>HTTP 传输"]
    C --> D2["MetMuseum-MCP Server<br/>STDIO 传输"]
    E["OpenAI GPT-5 Nano"] --> B
    F["InMemorySaver 记忆系统"] --> B
```

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

### 核心组件职责

| 组件层 | 组件名称 | 职责描述 |
|--------|----------|----------|
| 用户层 | CLI交互界面 | 提供菜单选择和问题输入功能 |
| 推理层 | LangGraph ReAct Agent | 负责推理决策和工具调用编排 |
| 模型层 | ChatOpenAI (GPT-5 Nano) | 提供LLM推理能力 |
| 记忆层 | InMemorySaver | 维护会话历史和线程状态 |
| 客户端层 | MultiServerMCPClient | 管理多个MCP服务器连接 |
| 服务器层 | Context7 / MetMuseum | 提供具体业务工具 |

资料来源：[main.py:1-20](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L1-L20)

---

## MCP服务器配置详解

### 配置文件结构

`MultiServerMCPClient`接受一个字典参数，键为服务器标识名，值为服务器配置对象。配置对象必须包含`transport`字段来指定传输类型。

```python
client = MultiServerMCPClient({
    "服务器标识名": {
        "transport": "传输类型",
        # 其他配置项...
    }
})
```

资料来源：[main.py:22-40](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L22-L40)

### Context7服务器配置（HTTP传输）

Context7是一个远程云端MCP服务器，提供主流软件框架和库的文档搜索功能。

| 参数 | 值 | 说明 |
|------|-----|------|
| 传输协议 | `streamable_http` | 支持流式HTTP通信 |
| 端点URL | `https://mcp.context7.com/mcp` | 服务器远程地址 |
| 连接类型 | 远程/云端 | 无需本地安装 |

```python
"context7": {
    "url": "https://mcp.context7.com/mcp",
    "transport": "streamable_http",
}
```

资料来源：[main.py:23-26](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L23-L26)

### MetMuseum服务器配置（STDIO传输）

MetMuseum是一个本地MCP服务器，通过npx执行，提供大都会艺术博物馆的藏品数据访问。

| 参数 | 值 | 说明 |
|------|-----|------|
| 传输协议 | `stdio` | 通过标准输入输出通信 |
| 执行命令 | `npx` | Node.js包执行器 |
| 启动参数 | `["-y", "metmuseum-mcp"]` | 自动确认安装并运行 |
| 连接类型 | 本地/STDIO | 需Node.js环境支持 |

```python
"met-museum": {
    "command": "npx",
    "args": ["-y", "metmuseum-mcp"],
    "transport": "stdio",
}
```

资料来源：[main.py:28-32](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L28-L32)

### 传输协议对比

| 特性 | HTTP传输（streamable_http） | STDIO传输 |
|------|----------------------------|----------|
| 通信方式 | 基于HTTP的请求响应/流式 | 标准输入输出管道 |
| 部署模式 | 远程云服务 | 本地进程 |
| 依赖 | 网络连接 | Node.js + npm |
| 延迟 | 依赖网络质量 | 本地进程，延迟低 |
| 适用场景 | 公共服务、文档查询 | 本地工具、数据访问 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

---

## Agent构建流程

### 初始化步骤总览

Agent的构建分为五个主要步骤：导入依赖、配置MCP客户端、初始化LLM、获取工具集、创建ReAct代理。

```mermaid
graph LR
    A["导入依赖"] --> B["配置MultiServerMCPClient"]
    B --> C["初始化ChatOpenAI模型"]
    C --> D["获取所有工具 await client.get_tools()"]
    D --> E["配置InMemorySaver"]
    E --> F["创建create_react_agent"]
```

资料来源：[main.py:44-70](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L44-L70)

### 第一步：导入依赖

```python
import asyncio
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import InMemorySaver
from langchain_openai import ChatOpenAI
```

资料来源：[main.py:1-6](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L1-L6)

| 导入模块 | 来源库 | 用途 |
|----------|--------|------|
| `MultiServerMCPClient` | langchain-mcp-adapters | 多服务器MCP客户端 |
| `create_react_agent` | langgraph.prebuilt | 创建预置ReAct代理 |
| `InMemorySaver` | langgraph.checkpoint.memory | 内存会话持久化 |
| `ChatOpenAI` | langchain-openai | OpenAI聊天模型封装 |

### 第二步：配置OpenAI模型

```python
openai_model = ChatOpenAI(
    model="gpt-5-nano",
)
```

| 参数 | 值 | 说明 |
|------|-----|------|
| model | `gpt-5-nano` | 使用OpenAI的GPT-5 Nano模型 |
| 默认端点 | OpenAI API | 需设置OPENAI_API_KEY环境变量 |

资料来源：[main.py:46-48](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L46-L48)

### 第三步：获取MCP工具

```python
tools = await client.get_tools()
```

`get_tools()`方法会异步获取所有已配置MCP服务器提供的工具集合，这些工具将作为ReAct Agent的可调用资源。

资料来源：[main.py:50](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L50)

### 第四步：配置会话记忆系统

```python
checkpointer = InMemorySaver()
config = {"configurable": {"thread_id": "conversation_id"}}
```

| 参数 | 配置键 | 值 | 说明 |
|------|--------|-----|------|
| checkpointer | - | InMemorySaver实例 | 内存会话检查点 |
| config | configurable.thread_id | "conversation_id" | 会话线程标识 |

资料来源：[main.py:52-55](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L52-L55)

### 第五步：创建ReAct Agent

```python
agent = create_react_agent(
    model=openai_model,
    tools=tools,
    checkpointer=checkpointer
)
```

| 参数 | 类型 | 说明 |
|------|------|------|
| model | ChatOpenAI | LLM推理引擎 |
| tools | List[BaseTool] | MCP服务器工具集 |
| checkpointer | BaseCheckpointSaver | 会话记忆持久化 |

资料来源：[main.py:57-61](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L57-L61)

---

## 自主工具选择机制

### 工具选择工作流

ReAct Agent的核心能力之一是根据用户问题自主选择合适的MCP服务器和工具。

```mermaid
graph TD
    A["用户问题"] --> B{"LLM推理判断"}
    B -->|代码/文档相关| C["调用Context7工具"]
    B -->|艺术/博物馆相关| D["调用MetMuseum工具"]
    C --> E["返回文档数据"]
    D --> F["返回艺术品数据"]
    E --> G["LLM生成自然语言响应"]
    F --> G
    G --> H["用户收到响应"]
```

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

### 工具选择示例

| 用户问题 | 调用服务器 | 返回内容 |
|----------|-----------|----------|
| "LangGraph工具是什么？" | Context7 | 框架文档内容 |
| "展示莫奈的画作" | MetMuseum | 艺术品元数据和图片 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

---

## 会话管理机制

### 线程化会话模型

项目采用基于thread_id的线程化会话管理，每个会话拥有独立的上下文记忆。

```mermaid
graph TD
    A["Session 1<br/>thread_id=conversation_1"] --> B["消息历史 1"]
    A --> C["工具调用历史 1"]
    D["Session 2<br/>thread_id=conversation_2"] --> E["消息历史 2"]
    D --> F["工具调用历史 2"]
```

资料来源：[main.py:52-55](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L52-L55)

### 配置参数详解

```python
config = {"configurable": {"thread_id": "conversation_id"}}
```

| 配置层级 | 键名 | 值类型 | 说明 |
|----------|------|--------|------|
| configurable | thread_id | string | 会话唯一标识符 |

在Agent调用时传入config参数，确保同一thread_id的所有交互共享会话记忆：

```python
response = await agent.ainvoke(
    {"messages": query},
    config=config
)
```

资料来源：[main.py:92-96](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L92-L96)

---

## 主交互流程

### 程序执行流程图

```mermaid
flowchart TD
    A["启动程序"] --> B["初始化MCP客户端"]
    B --> C["获取所有工具"]
    C --> D["创建ReAct Agent"]
    D --> E["发送初始介绍请求"]
    E --> F{"用户选择"}
    F -->|"1. 提问"| G["获取用户问题"]
    G --> H["Agent推理并调用工具"]
    H --> I["返回响应给用户"]
    I --> F
    F -->|"2. 退出"| J["打印 Goodbye!"]
    J --> K["程序结束"]
```

资料来源：[main.py:63-110](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L63-L110)

### 主函数异步设计

```python
async def main():
    # 初始化和Agent创建
    client = MultiServerMCPClient({...})
    openai_model = ChatOpenAI(model="gpt-5-nano")
    tools = await client.get_tools()
    checkpointer = InMemorySaver()
    agent = create_react_agent(model=openai_model, tools=tools, checkpointer=checkpointer)
    
    # 初始介绍
    response = await agent.ainvoke({...}, config=config)
    print(response['messages'][-1].content)
    
    # 交互循环
    while True:
        choice = input("Menu: 1. Ask 2. Quit: ")
        if choice == "1":
            query = input("> ")
            response = await agent.ainvoke({"messages": query}, config=config)
            print(response['messages'][-1].content)
        else:
            break
```

资料来源：[main.py:15-110](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L15-L110)

---

## 系统消息配置

### Agent角色定义

通过系统消息（System Message）定义Agent的角色定位和行为规范：

```python
{"role": "system", "content": "You are a smart, useful agent with tools to access code library documentation and the Met Museum collection."}
```

| 字段 | 值 | 说明 |
|------|-----|------|
| role | "system" | 系统角色消息 |
| content | Agent角色描述 | 声明Agent能力范围 |

资料来源：[main.py:68-71](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py#L68-L71)

---

## 运行环境要求

### 依赖项

| 依赖包 | 版本要求 | 说明 |
|--------|----------|------|
| Python | 3.10+ | 主程序运行环境 |
| langchain-mcp-adapters | 最新版 | MCP客户端适配器 |
| langgraph | 最新版 | Agent框架 |
| langchain-openai | 最新版 | OpenAI模型集成 |

```bash
pip install langchain-mcp-adapters langgraph langchain-openai
```

### 环境变量

| 变量名 | 必填 | 说明 |
|--------|------|------|
| OPENAI_API_KEY | 是 | OpenAI API访问密钥 |

```bash
export OPENAI_API_KEY="your-api-key-here"
```

### 额外要求

| 组件 | 用途 | 安装命令 |
|------|------|----------|
| npm | 运行MetMuseum STDIO服务器 | `npm install -g npx` |
| npx | 包执行器 | 随npm自动安装 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

---

## 执行方式

### 运行程序

```bash
python main.py
```

### 交互示例

```
Agent introduces itself and available tools...

Menu:
1. Ask the agent a question
2. Quit
Enter your choice (1 or 2): 1

Your question
> What LangGraph tools are available for building agents?
→ Agent queries Context7 → Returns documentation

> Show me Impressionist paintings from the Met Museum
→ Agent queries MetMuseum → Returns artwork data
```

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

---

## 技术亮点总结

| 技术特性 | 实现方式 | 优势 |
|----------|----------|------|
| 多传输协议支持 | HTTP + STDIO | 灵活接入远程和本地服务 |
| 自主工具选择 | LLM推理判断 | 无需手动指定工具 |
| 持久化会话记忆 | InMemorySaver + thread_id | 跨轮次上下文保持 |
| 异步架构 | asyncio + await | 高效并发处理 |
| ReAct推理模式 | LangGraph预置Agent | 可靠的工具调用推理 |

资料来源：[README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)

---

<a id='page-8'></a>

## 安装与配置指南

### 相关页面

相关主题：[运行与交互指南](#page-9), [扩展与定制指南](#page-10)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)
- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)
</details>

# 安装与配置指南

## 概述

本项目是一个基于 Model Context Protocol (MCP) 的多服务器 AI Agent 实现，通过 LangGraph ReAct 架构连接多个 MCP 服务器，并利用 OpenAI GPT-5 Nano 模型进行推理与响应生成。安装与配置指南旨在帮助开发者完整搭建运行环境，包括依赖安装、环境变量配置、多服务器连接设置以及运行验证等关键步骤。

本指南覆盖的范围包括：系统环境要求、Python 依赖安装、Node.js 环境准备、API 密钥配置、MCP 服务器连接配置以及运行测试。通过本指南，开发者可以在本地环境成功部署并运行该多服务器 MCP Agent。

## 系统环境要求

### 硬件与操作系统

| 项目 | 最低要求 | 推荐配置 |
|------|----------|----------|
| 操作系统 | macOS / Linux / Windows | macOS / Linux |
| 内存 | 4GB RAM | 8GB RAM |
| 存储空间 | 500MB 可用空间 | 1GB 可用空间 |
| 网络 | 互联网连接 | 稳定的互联网连接 |

### 软件依赖

| 组件 | 版本要求 | 说明 | 资料来源 |
|------|----------|------|----------|
| Python | 3.10+ | 主要运行环境 | README.md |
| Node.js | 14.0+ | npx 包管理器需要 | README.md |
| pip | 最新版本 | Python 包管理器 | - |

## 安装步骤

### 第一步：安装 Python 依赖

本项目依赖三个核心 Python 包，分别负责 MCP 客户端、LangGraph Agent 框架和 OpenAI 模型集成。执行以下命令完成依赖安装：

```bash
pip install langchain-mcp-adapters langgraph langchain-openai
```

安装说明如下：

| 包名 | 用途 | 说明 |
|------|------|------|
| langchain-mcp-adapters | MCP 客户端 | 提供 MultiServerMCPClient，支持多服务器连接 |
| langgraph | Agent 框架 | 提供 create_react_agent 创建 ReAct 风格 Agent |
| langchain-openai | OpenAI 集成 | 提供 ChatOpenAI 模型接口 |

### 第二步：安装 Node.js 和 npm

由于 MetMuseum-MCP 服务器通过 npx 本地运行，需要确保 Node.js 和 npm 已安装。npm 通常随 Node.js 一起安装。

```bash
# 检查 Node.js 和 npm 版本
node --version
npm --version

# 如果未安装，通过包管理器安装
# macOS 使用 Homebrew
brew install node

# Ubuntu/Debian
sudo apt-get install nodejs npm

# Windows 使用 Chocolatey
choco install nodejs
```

对于 MetMuseum 服务器的 STDIO 连接，项目使用 npx 命令直接运行 `metmuseum-mcp` 包，无需全局安装该包，npx 会自动下载并执行。

### 第三步：设置 OpenAI API 密钥

Agent 使用 OpenAI GPT-5 Nano 模型进行推理，需要配置有效的 API 密钥。

```bash
# Linux/macOS
export OPENAI_API_KEY="your-api-key-here"

# Windows (Command Prompt)
set OPENAI_API_KEY=your-api-key-here

# Windows (PowerShell)
$env:OPENAI_API_KEY="your-api-key-here"
```

**注意**：API 密钥应妥善保管，切勿提交到版本控制系统。建议将密钥存储在环境变量文件中，如 `.env` 文件，并确保该文件在 `.gitignore` 中被忽略。

## MCP 服务器配置

### 服务器概述

本项目同时连接两个 MCP 服务器，分别提供不同的服务能力：

| 服务器名称 | 传输协议 | 类型 | 主要功能 |
|------------|----------|------|----------|
| Context7 | HTTP (streamable_http) | 远程云端 | 提供主流软件框架的文档搜索 |
| MetMuseum-MCP | STDIO | 本地 (npx) | 提供大都会艺术博物馆 40 万+ 藏品访问 |

### 配置参数详解

根据 main.py 中的代码实现，MCP 客户端配置如下：

```python
client = MultiServerMCPClient({
    "context7": {
        "url": "https://mcp.context7.com/mcp",
        "transport": "streamable_http",
    },
    "met-museum": {
        "command": "npx",
        "args": ["-y", "metmuseum-mcp"],
        "transport": "stdio",
    }
})
```

配置参数详细说明：

| 服务器 | 参数 | 类型 | 说明 | 必填 |
|--------|------|------|------|------|
| context7 | url | string | Context7 服务器端点 | 是 |
| context7 | transport | string | 传输协议类型，固定为 streamable_http | 是 |
| met-museum | command | string | 执行命令，此处为 npx | 是 |
| met-museum | args | list | 命令参数，`-y` 表示自动确认，`metmuseum-mcp` 为包名 | 是 |
| met-museum | transport | string | 传输协议类型，固定为 stdio | 是 |

## 运行 Agent

### 启动命令

完成所有配置后，执行以下命令启动 Agent：

```bash
python main.py
```

### 交互流程

```mermaid
graph TD
    A[启动 main.py] --> B[初始化 MCP 客户端]
    B --> C[连接 Context7 服务器 HTTP]
    B --> D[连接 MetMuseum-MCP 服务器 STDIO]
    C --> E[获取所有可用工具]
    D --> E
    E --> F[初始化 GPT-5 Nano 模型]
    F --> G[创建 LangGraph ReAct Agent]
    G --> H[初始化 InMemorySaver 内存]
    H --> I[Agent 自我介绍]
    I --> J{用户选择}
    J -->|选择 1| K[用户输入问题]
    K --> L[Agent 推理并调用工具]
    L --> M[返回响应结果]
    M --> J
    J -->|选择 2| N[退出程序]
```

### 会话管理

Agent 使用 InMemorySaver 实现会话记忆功能，所有消息通过 thread_id 进行关联：

```python
checkpointer = InMemorySaver()
config = {"configurable": {"thread_id": "conversation_id"}}
```

这确保了多轮对话中 Agent 能够记住之前的上下文信息。

## 架构组件关系

```mermaid
graph TD
    subgraph 应用层
        A[main.py] --> B[MultiServerMCPClient]
        B --> C[create_react_agent]
        C --> D[ChatOpenAI GPT-5 Nano]
    end
    
    subgraph 连接层
        B --> E[HTTP Transport]
        B --> F[STDIO Transport]
    end
    
    subgraph 服务层
        E --> G[Context7 Server]
        F --> H[MetMuseum-MCP Server]
    end
    
    subgraph 数据层
        G --> I[框架文档数据]
        H --> J[艺术藏品数据]
    end
```

## 常见问题排查

### 依赖安装失败

| 问题 | 解决方案 |
|------|----------|
| pip 版本过旧 | 升级 pip: `pip install --upgrade pip` |
| 权限错误 | 使用虚拟环境或添加 `--user` 参数 |
| SSL 证书错误 | 更新 certifi 包: `pip install --upgrade certifi` |

### MCP 服务器连接问题

| 问题 | 解决方案 |
|------|----------|
| Context7 连接超时 | 检查网络连接，确认 https://mcp.context7.com/mcp 可访问 |
| MetMuseum npx 失败 | 确保 Node.js 和 npm 已正确安装，运行 `npx -y metmuseum-mcp` 测试 |
| 工具获取失败 | 检查 API 密钥是否有效，确认网络连接正常 |

### API 密钥问题

| 问题 | 解决方案 |
|------|----------|
| 密钥未设置 | 执行 `export OPENAI_API_KEY="your-key"` |
| 密钥无效 | 前往 OpenAI 平台检查并生成新密钥 |
| 余额不足 | 检查 OpenAI 账户余额 |

## 项目文件结构

```
mcp-ai-agent/
│
├── main.py          # 主程序入口，包含完整的多服务器 MCP Agent 实现
├── README.md        # 项目说明文档
└── .gitignore       # Git 忽略文件（需创建，包含 .env 等）
```

## 后续步骤

安装配置完成后，建议按以下顺序验证系统：

1. 验证 Python 依赖已正确安装
2. 验证 OpenAI API 密钥有效
3. 运行 `python main.py` 启动 Agent
4. 输入测试问题验证工具调用功能
5. 测试多轮对话确认会话记忆正常

---

<a id='page-9'></a>

## 运行与交互指南

### 相关页面

相关主题：[安装与配置指南](#page-8), [持久化对话记忆机制](#page-5)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)
</details>

# 运行与交互指南

## 概述

本指南详细介绍 `mcp-ai-agent` 项目的运行方法与用户交互流程。该项目是一个基于 Model Context Protocol (MCP) 的多服务器 AI Agent，采用 LangGraph ReAct 架构，能够同时连接多个 MCP 服务器并提供持久化对话记忆功能。资料来源：[main.py:1-95]()

## 系统要求

### 运行环境

| 组件 | 最低要求 |
|------|----------|
| Python 版本 | 3.10+ |
| Node.js | 用于 npx 运行本地 MCP 服务器 |
| OpenAI API Key | 必需 |

### 依赖安装

在运行项目前，需要安装以下 Python 依赖包：

```bash
pip install langchain-mcp-adapters langgraph langchain-openai
```

对于本地 MCP 服务器（如 MetMuseum），需要确保 npm 可用：

```bash
npm install -g npx
```

## 配置步骤

### 环境变量配置

运行项目前，必须设置 OpenAI API 密钥：

```bash
export OPENAI_API_KEY="your-api-key-here"
```

### MCP 服务器配置

`main.py` 中配置了两个 MCP 服务器连接，详情见下表：

| 服务器名称 | 传输协议 | 端点/命令 | 功能描述 |
|-----------|---------|----------|----------|
| context7 | streamable_http | https://mcp.context7.com/mcp | 提供代码库文档搜索能力 |
| met-museum | stdio | npx -y metmuseum-mcp | 提供大都会艺术博物馆藏品访问 |

资料来源：[main.py:37-52]()

## 核心组件架构

### 组件交互流程

```mermaid
graph TD
    A[用户 CLI 交互] --> B[LangGraph ReAct Agent]
    B --> C{GPT-5 Nano 推理}
    C --> D[自动工具选择]
    D --> E[Context7 HTTP]
    D --> F[MetMuseum STDIO]
    E --> G[返回结果]
    F --> G
    G --> B
    H[InMemorySaver] --> B
    I[thread_id 持久化] --> H
```

### 关键组件说明

| 组件 | 类/模块 | 作用 |
|------|---------|------|
| MCP 客户端 | MultiServerMCPClient | 同时管理多个 MCP 服务器连接 |
| Agent 引擎 | create_react_agent | 创建 ReAct 风格代理，整合推理与工具调用 |
| 对话记忆 | InMemorySaver | 维护会话线程内的对话历史 |
| 语言模型 | ChatOpenAI | GPT-5 Nano 提供推理能力 |

资料来源：[main.py:37](), [main.py:68](), [main.py:72](), [main.py:60]()

## 运行流程详解

### 启动序列

```mermaid
sequenceDiagram
    participant User as 用户
    participant Agent as AI Agent
    participant Client as MCP Client
    participant Servers as MCP Servers

    User->>Agent: python main.py
    Agent->>Client: 初始化 MultiServerMCPClient
    Client->>Servers: 建立 HTTP + STDIO 连接
    Servers-->Client: 返回可用工具列表
    Client-->Agent: tools = await client.get_tools()
    Agent->>Agent: 创建 InMemorySaver
    Agent->>Agent: create_react_agent
    Agent->>User: 显示自我介绍与工具列表
```

### 主程序执行逻辑

```python
# 标准库导入
import asyncio

# MCP 和 LangGraph 导入
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.memory import InMemorySaver
from langchain_openai import ChatOpenAI

async def main():
    # 1. 配置并初始化 MCP 客户端
    client = MultiServerMCPClient({...})
    
    # 2. 初始化 OpenAI 模型
    openai_model = ChatOpenAI(model="gpt-5-nano")
    
    # 3. 获取所有可用工具
    tools = await client.get_tools()
    
    # 4. 设置对话记忆系统
    checkpointer = InMemorySaver()
    config = {"configurable": {"thread_id": "conversation_id"}}
    
    # 5. 创建 ReAct Agent
    agent = create_react_agent(
        model=openai_model,
        tools=tools,
        checkpointer=checkpointer
    )
    
    # 6. 发送初始介绍消息
    response = await agent.ainvoke({...}, config=config)
    
    # 7. 进入交互循环
    while True:
        # 处理用户输入...
```

资料来源：[main.py:18-95]()

## 用户交互流程

### 交互菜单系统

项目采用简单的命令行菜单界面，用户通过输入数字选择操作：

```
Menu:
1. Ask the agent a question
2. Quit
Enter your choice (1 or 2): 
```

### 交互状态机

```mermaid
stateDiagram-v2
    [*] --> 启动: python main.py
    启动 --> 初始化: asyncio.run(main)
    初始化 --> 自我介绍: Agent 介绍工具能力
    自我介绍 --> 等待选择: 显示菜单
    等待选择 --> 提问: 用户选择 1
    等待选择 --> 退出: 用户选择 2
    提问 --> 调用Agent: 输入问题
    调用Agent --> 等待选择: 显示响应
    退出 --> [*]: print("Goodbye!")
```

### 消息处理流程

当用户提出问题时，系统按以下步骤处理：

1. **接收用户查询** — 获取用户输入的问题内容
2. **调用 Agent** — 使用 `agent.ainvoke()` 发送查询
3. **传递会话配置** — config 中的 thread_id 维持对话上下文
4. **返回响应** — 显示 agent 的最后一条消息内容

```python
# 发送用户问题并获取响应
query = input("> ")
response = await agent.ainvoke(
    {"messages": query},
    config=config
)
# 显示 agent 的回复
print(response['messages'][-1].content)
```

资料来源：[main.py:86-92]()

## 对话记忆机制

### 持久化原理

系统使用 `InMemorySaver` 和 `thread_id` 实现对话记忆：

| 参数 | 值 | 说明 |
|------|-----|------|
| thread_id | "conversation_id" | 会话唯一标识符 |
| checkpointer | InMemorySaver 实例 | 内存中的对话历史存储 |

所有在同一 thread_id 下的消息都会被持久化保存，Agent 能够记住之前的对话内容。

资料来源：[main.py:72-75]()

### 消息结构

```python
# 系统消息定义 Agent 角色
{"role": "system", "content": "You are a smart, useful agent..."}

# 用户消息
{"role": "user", "content": "用户输入的问题"}

# Agent 响应
{"role": "assistant", "content": "Agent 的回复内容"}
```

## MCP 服务器工具调用

### 自主工具选择

Agent 具备自动选择工具的能力，根据用户问题判断应调用哪个服务器：

```mermaid
graph LR
    A[用户问题] --> B{GPT-5 Nano 推理}
    B -->|代码/库文档| C[Context7 HTTP]
    B -->|艺术/博物馆| D[MetMuseum STDIO]
    C --> E[返回文档数据]
    D --> F[返回艺术品数据]
```

### 示例场景

| 用户问题类型 | 调用服务器 | 返回内容 |
|-------------|-----------|----------|
| "LangChain 代理文档" | Context7 | 代码库文档 |
| "梵高 paintings" | MetMuseum | 艺术品元数据与图片 |

## 快速启动命令汇总

| 步骤 | 命令 | 说明 |
|------|------|------|
| 1 | `pip install langchain-mcp-adapters langgraph langchain-openai` | 安装 Python 依赖 |
| 2 | `export OPENAI_API_KEY="your-api-key-here"` | 设置 API 密钥 |
| 3 | `python main.py` | 启动 Agent |

## 异常处理

程序对用户输入采用宽松处理策略：

- 输入 `1` → 进入提问模式
- 输入其他任何值 → 退出程序

```python
if choice == "1":
    # 处理提问逻辑
else:
    print("Goodbye!")
    break
```

资料来源：[main.py:93-94]()

## 项目结构

```
mcp-ai-agent/
├── main.py          # 完整的 MCP Agent 实现
└── README.md        # 项目说明文档
```

当前项目结构简洁，所有核心逻辑均包含在 `main.py` 中，便于快速理解与部署。

---

<a id='page-10'></a>

## 扩展与定制指南

### 相关页面

相关主题：[MultiServerMCPClient配置](#page-6), [集成MCP服务器详解](#page-7)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [main.py](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/main.py)
- [README.md](https://github.com/LeelaissakAttota/mcp-ai-agent/blob/main/README.md)
</details>

# 扩展与定制指南

本指南详细说明如何扩展和定制 mcp-ai-agent 项目，涵盖 MCP 服务器配置、LLM 模型替换、记忆系统升级、代理架构调整以及传输协议选择等关键定制方向。通过本指南，开发者可以根据实际业务需求灵活调整系统组件，构建符合特定场景的智能代理应用。

## 1. 系统架构概述

mcp-ai-agent 是一个基于 Model Context Protocol (MCP) 的多服务器代理系统，核心架构采用 LangGraph ReAct 模式实现自主工具调用和推理。系统通过 MultiServerMCPClient 同时管理多个 MCP 服务器，连接不同传输协议的外部服务，并利用 GPT-5 Nano 模型进行自然语言理解和工具选择决策。代理运行时维护会话记忆，确保多轮对话的上下文连贯性。

```mermaid
graph TD
    A[用户 CLI 交互界面] --> B[LangGraph ReAct 代理引擎]
    B --> C[GPT-5 Nano 推理引擎]
    C --> D{工具选择决策}
    D --> E[Context7 服务器<br/>HTTP 传输]
    D --> F[MetMuseum 服务器<br/>STDIO 传输]
    E --> G[外部文档库检索]
    F --> H[大都会艺术博物馆数据]
    B <--> I[InMemorySaver<br/>会话记忆存储]
    G --> J[LLM 优化文档结果]
    H --> K[艺术品元数据与图片]
    J --> L[自然语言响应生成]
    K --> L
    L --> A
```

系统核心组件包括：MultiServerMCPClient 负责多服务器连接管理，create_react_agent 构建 ReAct 推理代理，InMemorySaver 提供进程内会话持久化，ChatOpenAI 封装语言模型调用接口。各组件通过异步机制协同工作，支持高并发工具调用场景。资料来源：[main.py:1-30]()

## 2. MCP 服务器扩展

### 2.1 MCP 服务器配置结构

MCP 服务器通过 MultiServerMCPClient 的配置字典进行注册，支持 HTTP 流式传输和 STDIO 本地进程两种主要协议类型。每台服务器配置包含传输协议类型、连接参数和认证信息三个核心维度。HTTP 服务器适合远程云端服务，STDIO 服务器适合本地 Node.js 运行时环境。

| 配置字段 | 类型 | 说明 | 示例值 |
|---------|------|------|--------|
| transport | string | 传输协议类型 | `streamable_http`、`stdio` |
| url | string | HTTP 服务器端点 | `https://mcp.context7.com/mcp` |
| command | string | STDIO 执行命令 | `npx`、`node` |
| args | array | 命令行参数列表 | `["-y", "metmuseum-mcp"]` |
| headers | object | HTTP 请求头 | `{"Authorization": "Bearer xxx"}` |

资料来源：[main.py:28-42]()

### 2.2 添加 HTTP 远程服务器

HTTP 传输协议基于 streamable_http 实现，支持远程 MCP 服务器的云端部署。配置时需指定服务器的 URL 端点，可选配置自定义请求头用于认证。远程服务器的优势在于无需在本地安装依赖，可直接调用云端提供的工具能力。

```python
client = MultiServerMCPClient({
    "custom-remote-server": {
        "url": "https://your-mcp-server.com/mcp",
        "transport": "streamable_http",
        "headers": {
            "Authorization": "Bearer your-api-key",
            "X-Custom-Header": "custom-value"
        }
    }
})
```

HTTP 服务器适用于以下场景：API 密钥管理的云服务、需要大规模计算资源的工具、跨组织数据共享、以及需要频繁更新的服务实例。配置时建议设置合理的超时参数，避免长时间等待响应。资料来源：[main.py:33-36]()

### 2.3 添加 STDIO 本地服务器

STDIO 传输协议通过标准输入输出与本地进程通信，适用于通过 npx 或 node 命令启动的 Node.js MCP 服务器。配置时需指定可执行命令和参数列表，系统会自动管理子进程的启动和生命周期。

```python
client = MultiServerMCPClient({
    "local-mcp-server": {
        "command": "npx",
        "args": ["-y", "your-local-mcp-package"],
        "transport": "stdio"
    }
})
```

本地 STDIO 服务器的优势包括：无网络延迟的工具调用、本地文件系统和数据库的直接访问、以及完全可控的执行环境。开发时可通过本地服务器快速迭代工具定义。资料来源：[main.py:37-41]()

### 2.4 多服务器并发管理

MultiServerMCPClient 支持同时连接多个不同协议的 MCP 服务器，所有服务器的工具会在调用时自动聚合。代理引擎无需感知底层传输差异，统一通过工具名称进行调用。并发连接管理由底层适配器自动处理，开发者只需在配置中声明服务器列表。

```python
client = MultiServerMCPClient({
    "server-a": {
        "url": "https://server-a.com/mcp",
        "transport": "streamable_http"
    },
    "server-b": {
        "command": "npx",
        "args": ["-y", "server-b-package"],
        "transport": "stdio"
    },
    "server-c": {
        "command": "node",
        "args": ["/path/to/server-c.js"],
        "transport": "stdio"
    }
})
tools = await client.get_tools()  # 聚合所有服务器工具
```

资料来源：[main.py:28-47]()

## 3. 大语言模型定制

### 3.1 模型提供商切换

系统默认使用 OpenAI 的 GPT-5 Nano 模型，可通过替换 ChatOpenAI 实例切换到其他兼容提供商。LangChain 生态支持多种 LLM 实现，包括 Anthropic、Google VertexAI、Azure OpenAI 等。模型选择影响代理的推理能力、响应速度和运行成本。

```python
from langchain_openai import ChatOpenAI
from langchain_anthropic import ChatAnthropic
from langchain_google_vertexai import ChatVertexAI

# OpenAI 配置
openai_model = ChatOpenAI(
    model="gpt-5-nano",
    api_key="your-openai-key",
    temperature=0.7
)

# Anthropic Claude 配置
claude_model = ChatAnthropic(
    model="claude-sonnet-4-20250514",
    anthropic_api_key="your-anthropic-key"
)
```

资料来源：[main.py:44-48]()

### 3.2 模型参数调优

ChatOpenAI 初始化支持多个关键参数控制模型行为。temperature 控制输出随机性，数值越高越具创造性；max_tokens 限制单次响应长度；top_p 和 frequency_penalty 提供更细粒度的采样控制。

| 参数名 | 类型 | 默认值 | 说明 |
|-------|------|--------|------|
| model | string | gpt-5-nano | 模型标识符 |
| temperature | float | 0.7 | 采样温度，0-2 之间 |
| max_tokens | int | None | 最大生成 token 数 |
| top_p | float | 1.0 | 核采样概率阈值 |
| frequency_penalty | float | 0.0 | 频率惩罚系数 |
| presence_penalty | float | 0.0 | 存在惩罚系数 |

调优建议：代码生成任务建议使用较低的 temperature（0.2-0.5）；创意写作和头脑风暴适合较高的 temperature（0.7-1.0）；需要确定性输出的场景可设为 0。资料来源：[main.py:44-48]()

### 3.3 自定义系统提示词

系统提示词定义代理的角色定位、行为规范和能力边界。通过修改 create_react_agent 调用时的 messages 参数，可以定制代理的专业领域、响应风格和工具使用策略。

```python
response = await agent.ainvoke(
    {"messages": [
        {"role": "system", "content": """你是一位专业的金融分析助手，专注于：
        1. 股票市场数据分析和趋势预测
        2. 投资组合风险评估
        3. 财务报表解读
        4. 使用可用的金融数据工具获取实时信息
        
        回复时使用简洁专业的语言，提供数据支撑的分析结论。"""},
        {"role": "user", "content": "介绍你自己和可用工具"},
    ]},
    config=config
)
```

资料来源：[main.py:59-68]()

## 4. 代理架构定制

### 4.1 代理类型选择

LangGraph 提供了多种预构建代理类型，除了默认的 ReAct 代理外，还支持 create_structured_chat_agent、create_conversational_agent 等变体。不同代理类型适用于不同交互模式：ReAct 适合需要复杂推理的工具调用场景，Conversational 适合聊天式问答，Structured Chat 适合需要结构化输出的场景。

```python
from langgraph.prebuilt import create_react_agent
from langgraph.prebuilt import create_structured_chat_agent

# ReAct 代理 - 适合工具调用
agent = create_react_agent(
    model=openai_model,
    tools=tools,
    checkpointer=checkpointer,
    state_modifier="你是一个有帮助的助手"
)

# 结构化聊天代理 - 适合需要 JSON 输出
agent = create_structured_chat_agent(
    model=openai_model,
    tools=tools
)
```

### 4.2 ReAct 推理循环定制

ReAct（Reasoning + Acting）代理的核心是思考-行动-观察循环。LangGraph 预构建代理封装了这一逻辑，但可通过 state_modifier 和 prompt 自定义影响推理过程。state_modifier 在每轮推理前修改状态，用于注入额外上下文或约束。

```mermaid
graph TD
    A[用户输入] --> B[构建消息历史]
    B --> C[LLM 推理阶段]
    C --> D{是否调用工具?}
    D -->|是| E[执行工具调用]
    E --> F[收集工具结果]
    F --> B
    D -->|否| G[生成最终响应]
    G --> H[返回给用户]
    C -->|思考过程| I[记录推理步骤]
    I --> D
```

资料来源：[main.py:51-57]()

### 4.3 工具过滤与白名单

出于安全和性能考虑，可通过工具过滤机制限制代理可用的工具范围。get_tools() 返回的完整工具列表可按名称模式或分类标签进行筛选，只将必要的工具暴露给代理。

```python
tools = await client.get_tools()

# 按名称前缀过滤
filtered_tools = [
    tool for tool in tools 
    if tool.name.startswith("context7_")
]

# 按工具类型过滤
document_tools = [
    tool for tool in tools 
    if hasattr(tool, 'tags') and 'document' in tool.tags
]

agent = create_react_agent(
    model=openai_model,
    tools=filtered_tools,  # 使用过滤后的工具列表
    checkpointer=checkpointer
)
```

## 5. 记忆系统升级

### 5.1 内存检查点器对比

默认的 InMemorySaver 将对话历史存储在进程内存中，适用于单实例部署和快速原型开发。生产环境建议使用持久化检查点器，避免进程重启后对话历史丢失。

| 检查点器类型 | 存储介质 | 持久化 | 并发支持 | 适用场景 |
|------------|---------|--------|---------|---------|
| InMemorySaver | 进程内存 | 否 | 单进程 | 开发调试、原型 |
| PostgresSaver | PostgreSQL | 是 | 高并发 | 生产环境 |
| RedisSaver | Redis | 是 | 高并发 | 分布式部署 |
| SQLiteSaver | SQLite | 是 | 低并发 | 轻量级部署 |

资料来源：[main.py:49-50]()

### 5.2 PostgreSQL 检查点器配置

PostgreSQL 检查点器支持多实例并发访问，适合生产环境大规模部署。需提前创建数据库表结构，LangGraph 提供自动迁移功能。

```python
from langgraph.checkpoint.postgres import PostgresSaver
from langchain_postgres import PostgresChatMessageHistory

# PostgreSQL 检查点器配置
checkpointer = PostgresSaver.from_conn_string(
    "postgresql://user:password@localhost:5432/langgraph"
)
checkpointer.setup()  # 创建必要的表结构

config = {"configurable": {"thread_id": "user_session_123"}}
```

### 5.3 多会话隔离管理

通过 thread_id 实现多用户会话隔离，每个会话维护独立的对话历史。config 字典的可配置参数用于指定线程标识符，系统自动为每个线程维护独立的状态快照。

```python
# 用户 A 的会话
config_a = {"configurable": {"thread_id": "user_a_session"}}

# 用户 B 的会话
config_b = {"configurable": {"thread_id": "user_b_session"}}

# 独立调用，互不影响
response_a = await agent.ainvoke({"messages": query}, config=config_a)
response_b = await agent.ainvoke({"messages": query}, config=config_b)
```

资料来源：[main.py:52-53]()

## 6. 传输协议深度定制

### 6.1 HTTP 流式传输配置

streamable_http 传输支持流式响应模式，减少首次响应延迟。配置选项包括连接超时、读取超时和自动重试策略。对于需要实时反馈的工具调用场景，建议启用流式传输。

```python
client = MultiServerMCPClient({
    "streaming-server": {
        "url": "https://streaming-mcp.example.com/mcp",
        "transport": "streamable_http",
        "timeout": 30,           # 超时时间（秒）
        "max_retries": 3,        # 最大重试次数
        "verify_ssl": True       # SSL 证书验证
    }
})
```

### 6.2 STDIO 进程生命周期管理

STDIO 服务器由 MCP 客户端自动管理进程启动和终止。当客户端关闭时，所有 STDIO 子进程会自动清理。必要时可通过客户端上下文管理器手动控制进程生命周期。

```python
async with MultiServerMCPClient({...}) as client:
    tools = await client.get_tools()
    # 使用工具...
# 超出上下文范围时自动清理进程
```

### 6.3 混合传输架构

在复杂企业场景中，可采用混合传输架构：核心业务逻辑使用 HTTP 服务器保证可用性，敏感数据操作使用本地 STDIO 服务器确保数据安全。

```mermaid
graph LR
    A[代理引擎] --> B[HTTP 网关]
    A --> C[本地 STDIO 桥接]
    B --> D[云端 MCP 服务]
    B --> E[第三方 API 服务]
    C --> F[本地数据库服务器]
    C --> G[文件系统]
    D --> H[文档检索]
    E --> I[外部数据源]
    F --> J[业务数据]
    G --> K[附件存储]
```

## 7. 错误处理与容错

### 7.1 工具调用错误捕获

代理运行时可能遇到工具执行失败、网络超时或服务器不可用等情况。建议在外层封装错误处理逻辑，为用户提供友好的错误提示。

```python
try:
    response = await agent.ainvoke(
        {"messages": query},
        config=config
    )
    print(response['messages'][-1].content)
except Exception as e:
    print(f"处理请求时发生错误: {str(e)}")
    # 可选：降级到无工具模式重试
```

### 7.2 重试策略配置

对于临时性故障，可实现自动重试机制。指数退避策略可避免重试风暴，同时给予服务恢复时间。

```python
import asyncio
from tenacity import retry, stop_after_attempt, wait_exponential

@retry(
    stop=stop_after_attempt(3),
    wait=wait_exponential(multiplier=1, min=2, max=10)
)
async def call_agent_with_retry(agent, query, config):
    return await agent.ainvoke({"messages": query}, config=config)
```

### 7.3 降级策略设计

当部分 MCP 服务器不可用时，系统应能优雅降级。可实现工具可用性检查，在初始化阶段过滤不可用工具，并通知代理哪些工具可用。

```python
tools = await client.get_tools()
available_tools = []

for tool in tools:
    try:
        # 健康检查
        await tool.invoke({"type": "ping"})
        available_tools.append(tool)
    except Exception:
        print(f"工具 {tool.name} 不可用，已跳过")

agent = create_react_agent(
    model=openai_model,
    tools=available_tools,
    checkpointer=checkpointer
)
```

## 8. 生产环境部署

### 8.1 环境变量管理

生产部署应使用环境变量管理敏感配置，避免硬编码 API 密钥。建议使用 python-dotenv 或 docker-secrets 管理变量。

```python
import os
from dotenv import load_dotenv

load_dotenv()  # 从 .env 文件加载

openai_model = ChatOpenAI(
    model="gpt-5-nano",
    api_key=os.environ.get("OPENAI_API_KEY")
)

client = MultiServerMCPClient({
    "context7": {
        "url": os.environ.get("CONTEXT7_URL"),
        "transport": "streamable_http"
    }
})
```

资料来源：[main.py:44-48]()

### 8.2 异步入口点设计

main() 函数使用 asyncio.run() 启动异步事件循环。生产环境建议使用 uvicorn 或 gunicorn 配合 ASGI 应用封装，实现真正的并发处理。

```python
from fastapi import FastAPI
import asyncio

app = FastAPI()

@app.post("/chat")
async def chat_endpoint(request: ChatRequest):
    response = await agent.ainvoke(
        {"messages": request.messages},
        config={"configurable": {"thread_id": request.session_id}}
    )
    return {"response": response['messages'][-1].content}

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8000)
```

### 8.3 容器化部署配置

Docker 容器化部署需考虑 MCP 服务器的依赖。STDIO 服务器需要 Node.js 运行时，HTTP 服务器则只需 Python 环境。

```dockerfile
# 多阶段构建 Dockerfile
FROM node:18-slim AS npx-server
WORKDIR /app
RUN npm install -g metmuseum-mcp

FROM python:3.10-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY --from=npx-server /usr/local/bin/npx /usr/local/bin/
COPY main.py .
CMD ["python", "main.py"]
```

## 9. 监控与日志

### 9.1 LangSmith 集成

LangChain 生态提供 LangSmith 用于追踪代理执行过程，包括 LLM 调用、工具执行和状态转换。

```python
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "your-langsmith-key"
os.environ["LANGCHAIN_PROJECT"] = "mcp-agent-production"
```

### 9.2 自定义日志记录

使用 Python logging 模块配置结构化日志，便于生产环境问题排查。

```python
import logging
import json

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("mcp-agent")

async def log_agent_invocation(query, response):
    logger.info(json.dumps({
        "event": "agent_invocation",
        "query": str(query),
        "response_length": len(str(response))
    }))
```

## 10. 快速参考

### 10.1 完整定制配置模板

```python
import asyncio
import os
from langchain_mcp_adapters.client import MultiServerMCPClient
from langgraph.prebuilt import create_react_agent
from langgraph.checkpoint.postgres import PostgresSaver
from langchain_openai import ChatOpenAI
from langchain_anthropic import ChatAnthropic

async def main():
    # 1. MCP 服务器配置
    client = MultiServerMCPClient({
        "context7": {
            "url": os.environ.get("CONTEXT7_URL"),
            "transport": "streamable_http"
        },
        "met-museum": {
            "command": "npx",
            "args": ["-y", "metmuseum-mcp"],
            "transport": "stdio"
        }
    })
    
    # 2. LLM 模型配置
    model = ChatAnthropic(
        model="claude-sonnet-4-20250514",
        anthropic_api_key=os.environ.get("ANTHROPIC_API_KEY")
    )
    
    # 3. 工具与记忆配置
    tools = await client.get_tools()
    checkpointer = PostgresSaver.from_conn_string(
        os.environ.get("DATABASE_URL")
    )
    
    # 4. 创建代理
    agent = create_react_agent(
        model=model,
        tools=tools,
        checkpointer=checkpointer
    )
    
    # 5. 运行代理
    config = {"configurable": {"thread_id": "main"}}
    response = await agent.ainvoke(
        {"messages": [{"role": "user", "content": "你好"}]},
        config=config
    )
    print(response['messages'][-1].content)

if __name__ == "__main__":
    asyncio.run(main())
```

### 10.2 关键文件位置

| 功能模块 | 文件路径 | 行号范围 |
|---------|---------|---------|
| MCP 客户端初始化 | main.py | 28-47 |
| LLM 模型配置 | main.py | 44-48 |
| 工具获取 | main.py | 50 |
| 记忆系统配置 | main.py | 49-50 |
| 代理创建 | main.py | 51-57 |
| 初始对话调用 | main.py | 59-78 |
| 主循环交互 | main.py | 80-95 |

资料来源：[main.py:1-95]()

本指南涵盖 mcp-ai-agent 的主要扩展和定制方向。开发者可根据实际需求组合不同模块，构建满足特定业务场景的智能代理系统。建议从单服务器简单配置开始，逐步添加复杂功能，并在开发过程中使用 InMemorySaver 便于调试，生产环境切换到持久化检查点器确保会话可靠性。

---

---

## Doramagic 踩坑日志

项目：LeelaissakAttota/mcp-ai-agent

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `mcp-ai-agent` 与安装入口 `metmuseum-mcp` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令：`npx metmuseum-mcp`
- 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | repo=mcp-ai-agent; install=metmuseum-mcp

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | last_activity_observed missing

## 4. 安全/权限坑 · 下游验证发现风险项

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1158386431 | https://github.com/LeelaissakAttota/mcp-ai-agent | release_recency=unknown

<!-- canonical_name: LeelaissakAttota/mcp-ai-agent; human_manual_source: deepwiki_human_wiki -->