项目简介

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

核心架构

系统架构图

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

技术组件表

资料来源：README.md

工作流程

代理决策流程

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[返回用户响应]

典型交互流程

资料来源：README.md

集成 MCP 服务器

服务器配置表

资料来源：README.md

多服务器连接实现

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

核心功能特性

1. LangGraph ReAct 代理

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

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

2. 持久化对话记忆

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

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

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

3. 自主工具选择

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

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

快速开始

环境准备

运行步骤

``bash pip install langchain-mcp-adapters langgraph langchain-openai npm install -g npx ``

1. 安装依赖

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

1. 配置环境变量

``bash python main.py ``

1. 启动代理

``` Menu:

Enter your choice (1 or 2): 1

1. 交互操作
2. Ask the agent a question
3. Quit

Your question

What LangGraph tools are available?

→ 代理调用 Context7 → 返回文档 ```

资料来源：README.md

关键技术亮点

资料来源：README.md

适用场景

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

概述

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

资料来源：README.md

核心技术组件

2.1 编程语言与运行环境

资料来源：README.md

2.2 核心依赖库

资料来源：main.py:1-7

2.3 语言模型

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

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

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

资料来源：main.py:49-51

架构设计

3.1 系统架构图

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 分层职责

资料来源：README.md

MCP 多服务器架构

4.1 MultiServerMCPClient 配置

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

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

4.2 集成 MCP 服务器对比

资料来源：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 智能体创建

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

资料来源：main.py:60-64

5.2 ReAct 工作流程

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

5.3 ReAct 模式特点

会话记忆系统

6.1 InMemorySaver 检查点器

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

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

资料来源：main.py:53-67

6.2 线程管理机制

6.3 记忆持久化流程

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 异步入口点

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

资料来源：main.py:92-94

7.2 异步调用模式

7.3 事件循环管理

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

工具集成与自主选择

8.1 工具获取

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

资料来源：main.py:53

8.2 自主工具选择逻辑

8.3 工具选择流程图

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

系统消息配置

9.1 智能体角色定义

{"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

9.2 消息类型

依赖安装

10.1 Python 依赖

pip install langchain-mcp-adapters langgraph langchain-openai

10.2 Node.js 环境

npm install -g npx

10.3 环境变量配置

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

技术栈总结

资料来源：README.md, main.py:1-7

概述

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

技术领域

核心架构组件

系统层级结构

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

技术栈明细

资料来源：README.md:56-66

通信传输机制

HTTP 传输 (Context7)

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

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

"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 执行
• 适用场景：本地艺术品数据查询

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

资料来源：main.py:25-29

代理工作流程

完整请求处理流程

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 服务器：

资料来源：README.md:42-51

核心模块设计

MCP 客户端模块

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 模型配置

from langchain_openai import ChatOpenAI

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

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

ReAct 代理创建

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

对话记忆系统

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 代理实例

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

数据流设计

消息传递机制

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

配置参数表

资料来源：main.py:45-47

系统初始化代码结构

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

关键设计决策

多服务器架构优势

技术选型理由

资料来源：README.md:4-12

依赖安装指南

Python 依赖

pip install langchain-mcp-adapters langgraph langchain-openai

Node.js 依赖

npm install -g npx

环境变量配置

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

资料来源：README.md:30-36

启动与运行

运行命令

python main.py

执行流程

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

资料来源：main.py:88-91

概述

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

核心架构

系统组件关系

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

技术栈概览

代理初始化流程

源码实现解析

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

# 第一步：配置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

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

资料来源：main.py:49-50

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

资料来源：main.py:52

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

资料来源：main.py:58-62

初始化参数说明

ReAct执行机制

推理与行动循环

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

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

对话上下文管理

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

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

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

资料来源：main.py:54-60

上下文管理特点：

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

MCP服务器集成

多服务器连接架构

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

服务器配置对比

工具自动路由

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

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

对话流程实现

主交互循环

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事件循环驱动：

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

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

资料来源：main.py:24-89

代理系统提示

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

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

资料来源：main.py:67

关键特性总结

核心能力矩阵

执行流程总览

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内容：

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

添加新MCP服务器

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

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

更换语言模型

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

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

概述

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

核心组件

1. InMemorySaver

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

from langgraph.checkpoint.memory import InMemorySaver

checkpointer = InMemorySaver()

资料来源：main.py:28

2. 会话配置（Config）

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

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

资料来源：main.py:67

3. ReAct Agent 集成

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

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

资料来源：main.py:70-74

工作流程

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

状态持久化流程

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: 返回响应

核心代码解析

主函数入口

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

智能体调用

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

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

资料来源：main.py:88-94

会话状态管理

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

消息格式

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

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

资料来源：main.py:77-82

初始化流程

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

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 获取文档]

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

上下文关联推理

记忆机制使智能体能够：

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

限制与注意事项

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

依赖关系

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. 状态序列化：支持对话历史导出与恢复

概述

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

核心作用：

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

资料来源：main.py:12

架构设计

多服务器连接架构

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

传输协议对比

资料来源：main.py:38-47

配置参数详解

MultiServerMCPClient 构造函数参数

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

服务器配置结构

Context7 服务器配置

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

配置说明：

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

MetMuseum 服务器配置

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

配置说明：

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

工具获取与使用

获取所有工具

tools = await client.get_tools()

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

工具聚合机制

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

与 LangGraph Agent 集成

完整集成流程

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 创建代码

# 初始化 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 函数异步设计

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)

事件循环执行

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

要点说明：

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

生命周期管理

连接初始化

资源清理

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

配置最佳实践

开发环境配置建议

扩展新服务器

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

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

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

依赖项

资料来源：main.py:1-11

概述

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

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

资料来源：main.py:1-20

概述

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

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

系统环境要求

硬件与操作系统

软件依赖

安装步骤

第一步：安装 Python 依赖

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

pip install langchain-mcp-adapters langgraph langchain-openai

安装说明如下：

第二步：安装 Node.js 和 npm

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

# 检查 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 密钥。

# 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 服务器，分别提供不同的服务能力：

配置参数详解

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

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

配置参数详细说明：

运行 Agent

启动命令

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

python main.py

交互流程

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 进行关联：

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

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

架构组件关系

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

常见问题排查

依赖安装失败

MCP 服务器连接问题

API 密钥问题

项目文件结构

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

后续步骤

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

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

概述

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

系统要求

运行环境

依赖安装

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

pip install langchain-mcp-adapters langgraph langchain-openai

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

npm install -g npx

配置步骤

环境变量配置

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

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

MCP 服务器配置

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

资料来源：main.py:37-52

核心组件架构

组件交互流程

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

关键组件说明

资料来源：main.py:37, main.py:68, main.py:72, main.py:60

运行流程详解

启动序列

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: 显示自我介绍与工具列表

主程序执行逻辑

# 标准库导入
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): 

交互状态机

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 的最后一条消息内容

# 发送用户问题并获取响应
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 下的消息都会被持久化保存，Agent 能够记住之前的对话内容。

资料来源：main.py:72-75

消息结构

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

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

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

MCP 服务器工具调用

自主工具选择

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

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

示例场景

快速启动命令汇总

异常处理

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

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

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

资料来源：main.py:93-94

项目结构

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

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

1. 系统架构概述

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

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 运行时环境。

资料来源：main.py:28-42

2.2 添加 HTTP 远程服务器

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

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 服务器。配置时需指定可执行命令和参数列表，系统会自动管理子进程的启动和生命周期。

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

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

2.4 多服务器并发管理

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

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 等。模型选择影响代理的推理能力、响应速度和运行成本。

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 提供更细粒度的采样控制。

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

3.3 自定义系统提示词

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

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 适合需要结构化输出的场景。

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 在每轮推理前修改状态，用于注入额外上下文或约束。

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() 返回的完整工具列表可按名称模式或分类标签进行筛选，只将必要的工具暴露给代理。

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

资料来源：main.py:49-50

5.2 PostgreSQL 检查点器配置

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

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 字典的可配置参数用于指定线程标识符，系统自动为每个线程维护独立的状态快照。

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

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 子进程会自动清理。必要时可通过客户端上下文管理器手动控制进程生命周期。

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

6.3 混合传输架构

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

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 工具调用错误捕获

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

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

7.2 重试策略配置

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

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 服务器不可用时，系统应能优雅降级。可实现工具可用性检查，在初始化阶段过滤不可用工具，并通知代理哪些工具可用。

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 管理变量。

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 应用封装，实现真正的并发处理。

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
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 调用、工具执行和状态转换。

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 模块配置结构化日志，便于生产环境问题排查。

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 完整定制配置模板

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 关键文件位置

资料来源：main.py:1-95

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

Pitfall Log / 踩坑日志

项目：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