AI导哈

多智能体文档检索系统

一个集成了LangGraph、模型上下文协议(MCP)和Claude 3.5 Sonnet的多智能体系统，提供智能文档检索、计算和代码执行功能。

  • by JoonHyoungLee-Seoul
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 JoonHyoungLee-Seoul/MCP_tutorial

使用说明

LangGraph MCP 多智能体系统

一个综合性的多智能体系统，集成了 LangGraph， 模型上下文协议（MCP），以及 Claude 3.5 Sonnet（中文可译为“克劳德3.5版莎士比亚体”或根据具体语境简化为“克劳德3.5”） 用于智能文档检索、计算和代码执行。

✅ 项目概述

• 开发了一个多智能体系统 和，与 3台MCP服务器 提供 12种专业工具 用于文档检索、数学计算、数据可视化和网页搜索。

• 集成了LangChain、LangGraph、FastMCP和Claude 3.5 Sonnet 用于智能代理编排和多模态任务执行。

• 设计了3个用户界面 （Streamlit 网页界面、Python 命令行界面、Jupyter Notebook）以支持从交互式开发到生产部署的各种应用场景。

• 实现了RAG（检索增强生成） 使用FAISS向量存储和OpenAI嵌入进行上下文感知的文档检索。

🔧 使用的技术

• python核心编程语言

• **LangChain / LangGraph（注：此翻译保持原名不变，因为“LangChain”和“LangGraph”是专有名词，通常不直接翻译，除非有官方或广泛接受的中文译名。在此情况下，我们假设没有官方中文译名，因此直接保留原名。）**代理工作流编排与ReAct模式实现

• **Claude 3.5 Sonnet（Anthropic出品）**用于推理和自然语言理解的高级大型语言模型

• FastMCP快速模型上下文协议服务器开发框架

• **FAISS（高效相似性搜索库）**用于RAG的高性能向量相似度搜索

• **OpenAI 嵌入（或：OpenAI 词嵌入）**用于语义文档检索的文本嵌入

• **Streamlit（斯特林·莱特，或直接音译为“斯特莱特”，但通常保持原英文名以体现其专有性）**用于演示的交互式网页界面

• **Pandas，NumPy（这两个是Python中用于数据处理和科学计算的库名，直接翻译即为“熊猫”和“NumPy”，但通常在中文语境下，我们直接使用其英文名）**数据处理和数值计算

• **Matplotlib（注：这是一个用于数据可视化的Python库名称，直接翻译即为“Matplotlib”，在中文语境下通常保持原名不变）**数据可视化和图表生成

• Tavily搜索API实时网页搜索集成

项目概述

这个项目展示了如何通过整合以下要素来构建一个强大的人工智能代理：

  • LangGraph构建复杂的代理工作流
  • **MCP（模型上下文协议）**工具与外部系统集成
  • **RAG（检索增强生成）**基于文档的信息检索
  • TavilySearch实时网页搜索
  • **Claude 3.5 Sonnet（中文可译为“克劳德3.5·十四行诗”或根据具体语境调整，但通常保留原名以体现其独特性）**Anthropic的最新大型语言模型（LLM）

架构概述

系统架构

graph TB
    subgraph "User Interfaces"
        A1[🌐 Streamlit Web UI<br/>web_demo.py]
        A2[💻 Python CLI<br/>agent.py]
        A3[📓 Jupyter Notebook<br/>examples/MCP.ipynb]
    end

    subgraph "Agent Core"
        B[🤖 LangGraph ReAct Agent<br/>Reasoning + Acting Loop]
    end

    subgraph "MCP Servers"
        C1[📚 RAG Server<br/>mcp_server_rag.py<br/>1 tool]
        C2[🧮 Calculator Server<br/>mcp_server_calculator.py<br/>5 tools]
        C3[💻 Code Executor Server<br/>mcp_server_code_executor.py<br/>5 tools]
    end

    subgraph "External Services"
        D1[🔍 Tavily Search<br/>Web Search API<br/>1 tool]
        D2[🧠 Claude 3.5 Sonnet<br/>Anthropic API]
    end

    subgraph "Data Sources"
        E1[(📄 PDF Documents<br/>data/)]
        E2[(🗂️ FAISS Index<br/>Vector Store)]
    end

    subgraph "Outputs"
        F1[📊 Visualizations<br/>output/*.png]
        F2[📋 Data Files<br/>output/*.csv]
        F3[💬 Chat Responses]
    end

    A1 --> B
    A2 --> B
    A3 --> B

    B --> C1
    B --> C2
    B --> C3
    B --> D1
    B --> D2

    C1 --> E1
    C1 --> E2
    E1 --> E2

    C2 --> F3
    C3 --> F1
    C3 --> F2
    C1 --> F3
    D1 --> F3

    style B fill:#e1f5ff
    style C1 fill:#fff4e6
    style C2 fill:#fff4e6
    style C3 fill:#fff4e6
    style D1 fill:#f3e5f5
    style D2 fill:#f3e5f5

数据流

sequenceDiagram
    participant User
    participant Agent
    participant RAG as 📚 RAG Server
    participant Calc as 🧮 Calculator
    participant Code as 💻 Code Executor
    participant Web as 🔍 Web Search
    participant Claude as 🧠 Claude 3.5

    User->>Agent: Query: "Retrieve iPhone 17 price and create chart"
    Agent->>Claude: Analyze query + available tools
    Claude->>Agent: Plan: 1) RAG retrieve 2) Code visualize

    Agent->>RAG: retrieve("iPhone 17 price")
    RAG->>RAG: Search FAISS vector store
    RAG-->>Agent: "iPhone 17: $799"

    Agent->>Claude: Process retrieved data
    Claude->>Agent: Next: Create visualization

    Agent->>Code: create_visualization(data, type="bar")
    Code->>Code: Generate matplotlib chart
    Code-->>Agent: "Saved to output/chart.png"

    Agent->>User: ✅ Response + 📊 Chart

工具分发

pie title "12 Tools Across 4 Categories"
    "📚 RAG Retriever" : 1
    "🧮 Calculator" : 5
    "💻 Code Executor" : 5
    "🔍 Web Search" : 1

项目结构图

graph LR
    subgraph "Core Files"
        A[agent.py<br/>CLI Interface]
        B[web_demo.py<br/>Web Interface]
        C[utils.py<br/>Utilities]
        D[utils_streamlit.py<br/>UI Helpers]
    end

    subgraph "MCP Servers"
        E[mcp_server_rag.py]
        F[mcp_server_calculator.py]
        G[mcp_server_code_executor.py]
    end

    subgraph "Resources"
        H[data/<br/>PDFs]
        I[output/<br/>Generated]
        J[examples/<br/>Notebooks]
        K[tests/<br/>Test Scripts]
        L[docs/<br/>Documentation]
    end

    A --> E
    A --> F
    A --> G
    B --> A
    B --> D
    D --> C

    E --> H
    G --> I

    style A fill:#e3f2fd
    style B fill:#e3f2fd
    style E fill:#fff3e0
    style F fill:#fff3e0
    style G fill:#fff3e0

主要特点

1. 多功能工具集成（共12种工具！）

  • RAG检索器 (1 工具)：从PDF文档中搜索信息
  • 计算器 （5种工具）：数学计算、统计、货币换算、价值比较
  • 代码执行器 (5种工具)：Python代码执行、数据分析、可视化
  • TavilySearch (1 工具)：搜索最新新闻和网络信息
  • 自动工具选择代理根据查询自动选择适当的工具

2. MCP服务器实现

📚 RAG检索器MCP（mcp_server_rag.py）

  • 基于FAISS向量存储的文档检索
  • 通过OpenAI嵌入进行文本嵌入
  • 通过全局缓存进行性能优化
  • 批量加载PDF文档

🧮 计算器 MCP（mcp_server_calculator.py)

  • 数学表达式求值（三角函数、对数、平方根等）
  • 百分比变化计算
  • 统计汇总（平均值、中位数、标准差）
  • 货币兑换
  • 价值比较分析

💻 代码执行器 MCP（mcp_server_code_executor.py)

  • 安全执行Python代码（pandas、numpy、matplotlib）
  • 数据可视化（5种图表类型：折线图、柱状图、散点图、饼图、直方图）
  • 数据分析（统计、分组、排序、相关性分析）
  • CSV文件的读取/写入

3. 实时流媒体

  • 代理执行的实时监控
  • 工具使用追踪（选择与执行）
  • 彩色编码输出，提升可读性

安装

1. 先决条件

  • Python 3.12+
  • 虚拟环境（venv）
  • Jupyter Notebook（可选，用于交互式开发）

2. 克隆仓库

git clone <your-repo-url>
cd lee_mcp_tutorial

3. 创建虚拟环境

python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

4. 安装依赖项

pip install -r requirements.txt

5. 注册 Jupyter 内核（可选）

如果您想使用Jupyter Notebook界面：

python -m ipykernel install --user --name=langgraph-mcp --display-name="Python (langgraph-mcp)"

6. 环境设置

创建一个 .env 文件内容如下：

ANTHROPIC_API_KEY=your_anthropic_api_key_here
OPENAI_API_KEY=your_openai_api_key_here
LANGSMITH_API_KEY=your_langsmith_api_key_here
LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_PROJECT=LangGraph-MCP-Agents
TAVILY_API_KEY=your_tavily_api_key_here

重要的移除 OPENAI_BASE_URL 如果已设置，则从系统环境变量中获取。此项目直接使用OpenAI API。

使用方法

快速入门

这个项目提供 3种不同的接口 与代理进行交互：

1️⃣ Jupyter Notebook（交互式开发）

jupyter notebook examples/MCP.ipynb

最适合于逐步探索、学习并立即看到成果

2️⃣ Python CLI（命令行界面）

python agent.py

最适合于快速测试、自动化、脚本集成

示例：

👤 You: Create a bar chart showing iPhone sales
🤖 Agent: [Response with chart generation]
👤 You: quit

3️⃣ Streamlit网页演示（网页界面）

streamlit run web_demo.py

最适合用于演示、展示、非技术用户

特点：

  • 📌 示例查询按钮
  • 🖼️ 自动显示生成的图像
  • 📊 实时统计
  • 🎨 精美的图形用户界面

看 QUICK_START.md 翻译为中文是：快速入门指南.md（或“快速开始指南.md”，具体取决于上下文对“QUICK_START”的理解，但通常“QUICK_START”可译为“快速入门”或“快速开始”） 以获取详细说明。

准备PDF文档

将PDF文档放置在 data/ 目录：

data/
├── document1.pdf
├── document2.pdf
└── ...

3. 单元格执行顺序

单元0：环境设置

# Set working directory and load environment variables

单元3：工具初始化

# Configure MCP client and TavilySearch
# Use MultiServerMCPClient for automatic session management

单元5：代理创建

# Create and configure ReAct agent

单元格7：Tavily搜索测试

# Example: Latest news search
await astream_graph(
    agent,
    {"messages": "Tell me about iPhone 17 sales..."},
    config=config
)

9号单元：RAG检索器测试

# Example: Search information from documents
await astream_graph(
    agent,
    {"messages": "What are the specifications of iPhone 17 Pro Camera?"},
    config=config
)

单元格11：综合使用

# Example: Using both tools
await astream_graph(
    agent,
    {"messages": "First retrieve color options, then search for news..."},
    config=config
)

项目结构

lee_mcp_tutorial/
├── 📓 User Interfaces
│   ├── agent.py                   # Python CLI (command line)
│   ├── web_demo.py                # Streamlit Web Demo (web UI)
│   └── utils_streamlit.py         # Streamlit utilities
│
├── 🤖 MCP Servers
│   ├── mcp_server_rag.py          # 📚 RAG Retriever (document search)
│   ├── mcp_server_calculator.py   # 🧮 Calculator (math & stats)
│   └── mcp_server_code_executor.py# 💻 Code Executor (Python & viz)
│
├── 🔧 Utilities
│   ├── utils.py                   # Streaming & tool tracking
│   └── .env                       # Environment variables (create this)
│
├── 📁 Data & Output
│   ├── data/                      # PDF documents
│   │   ├── *.pdf                  # Place your PDF files here
│   │   └── ...
│   └── output/                    # Generated files (auto-created)
│       ├── *.png                  # Charts & visualizations
│       └── *.csv                  # Data files
│
├── 📚 Examples
│   └── MCP.ipynb                  # Jupyter Notebook tutorial
│
├── 🧪 Tests
│   ├── test_agent_init.py         # Agent initialization test
│   ├── test_calculator.py         # Calculator tools test
│   └── test_visualization.py      # Visualization test
│
├── 📖 Documentation
│   ├── QUICK_START.md             # Quick start guide
│   ├── USAGE_GUIDE.md             # Detailed usage
│   ├── CALCULATOR_USAGE.md        # Calculator tool guide
│   ├── CODE_EXECUTOR_USAGE.md     # Code executor guide
│   ├── NOTEBOOK_EXAMPLES.md       # Example collection
│   ├── FIX_NOTES.md               # Troubleshooting fixes
│   ├── VISUALIZATION_FIX.md       # Visualization fixes
│   ├── WEB_DEMO_IMPROVEMENTS.md   # Web demo features
│   ├── EMPTY_CHART_FIX.md         # Chart debugging guide
│   └── STREAMLIT_UI_PREVIEW.md    # UI preview
│
├── 📋 Configuration
│   ├── requirements.txt           # Python dependencies
│   ├── .gitignore                 # Git ignore rules
│   ├── README.md                  # English README (this file)
│   ├── README_KOR.md              # Korean README
│   └── RUN_WEB_DEMO.sh            # Web demo launcher script
│
└── 🗑️ Ignored Files (see .gitignore)
    ├── __pycache__/               # Python cache
    ├── .DS_Store                  # macOS metadata
    ├── .env                       # API keys (DO NOT COMMIT)
    └── output/*.png               # Generated images

文件描述

用户界面

agent.py ⭐新

针对MCP多智能体系统的独立Python命令行界面（CLI）：

  • 可以在没有Jupyter的情况下独立运行
  • 用于快速测试的命令行界面
  • 提供 create_mcp_agent() 用于程序化使用的函数
  • 带有退出/终止命令的交互循环

用法：

python agent.py

或者在你自己的代码中导入：

from agent import create_mcp_agent, chat_with_agent
agent, config, tools = create_mcp_agent()
web_demo.py ⭐新

基于Streamlit的网页界面：

  • 带有示例查询按钮的美观图形用户界面
  • 实时工具使用追踪
  • 自动生成图表和图像的自动显示
  • 侧边栏，包含工具类别和统计数据
  • 生成输出的文件浏览器

发射：

streamlit run web_demo.py
MCP.ipynb （在examples/目录中）

用于交互式开发和学习的原始Jupyter Notebook界面。

utils_streamlit.py

Streamlit专用的实用函数：

  • display_agent_response_streamlit()代理响应的美观用户界面渲染
  • astream_graph_streamlit()与Streamlit兼容的图表流式传输
  • get_tool_icon()工具表情符号映射
  • format_tool_result()结果格式化以供显示

MCP 服务器

mcp_server_rag.py

  • 基于FastMCP的MCP服务器
  • PDF文档加载（目录加载器）
  • 创建FAISS向量存储
  • OpenAI Embeddings 的使用
  • 全局缓存以实现检索器重用
  • 提供 retrieve(query: str) 工具

核心功能：

@mcp.tool()
async def retrieve(query: str) -> str:
    """Retrieve information from document database"""
    global _retriever
    if _retriever is None:
        _retriever = create_retriever()
    retrieved_docs = _retriever.invoke(query)
    return "\n".join([doc.page_content for doc in retrieved_docs])

utils.py

核心实用函数：

  • astream_graph()LangGraph执行流式处理功能
  • print_tool_info()工具使用追踪与输出
  • 彩色编码输出（🔧 已选工具，✅ 工具已执行）

文档文件（位于 docs/ 目录下）

请参阅 docs/ 包含详细指南的文件夹：

  • **QUICK_START.md 翻译为中文是：“快速入门指南.md”（其中，“.md”表示这是Markdown格式的文件）**快速设置与使用指南
  • 使用指南.md全面的使用说明
  • **CALCULATOR_USAGE.md 翻译为中文是：“CALCULATOR_USAGE（计算器使用）.md”（文件名）。这里，“.md”通常表示这是一个Markdown格式的文件。所以，整个文件名可以理解为“计算器使用指南（Markdown格式）”**计算器MCP服务器文档
  • **CODE_EXECUTOR_USAGE.md 翻译为中文是：“代码执行器使用指南.md” 或 “代码执行器使用说明.md”**代码执行器MCP服务器文档
  • **`NOTEBOOK_EXAMPLES.md` 翻译为中文是：`笔记本示例.md`**Jupyter Notebook 示例查询
  • FIX_NOTES.md 翻译为中文是：“修复说明.md” 或 “修复备注.md”，具体取决于上下文，但通常“FIX_NOTES”可以理解为包含修复说明或备注的文件。在这里，“.md”表示这是一个Markdown格式的文件， **`VISUALIZATION_FIX.md` 翻译为中文是：“可视化修复说明文件” 或 “可视化修正指南文件”。（注：这里的“FIX”根据上下文可能指的是“修复”、“修正”或类似的含义，而“md”是Markdown文件格式的缩写。）**故障排除指南

技术栈

大型语言模型（LLM）与人工智能（AI）框架

  • Claude 3.5 Sonnet（可译为“克劳德3.5·十四行诗”，但具体翻译可能需根据上下文或品牌命名习惯调整） (claude-3-7-sonnet-latest): 人类（Anthropic）公司最新的大型语言模型
  • **LangChain（语言链）**大型语言模型（LLM）应用框架
  • LangGraph复杂代理工作流构建

MCP（模型上下文协议）

  • FastMCP快速MCP服务器构建框架
  • LangChain-MCP适配器LangChain与MCP的集成
  • 多服务器MCP客户端多个MCP服务器管理

文档处理与搜索

  • **PyMuPDFLoader（注：这个名称在中文中通常保持原样，不直接翻译，因为它是一个特定库或工具的名称，但为了说明其含义，可以理解为“用于加载PDF文件的PyMuPDF工具”或简化为“PyMuPDF加载器”，不过实际使用时仍以原名称为准）**PDF文件加载中
  • 目录加载器基于目录的批量文档加载
  • 递归字符文本分割器文本分块
  • **FAISS（快速应用索引库）**高速向量相似度搜索
  • **OpenAI 嵌入（或：OpenAI 向量表示）**文本嵌入（text-embedding-3-small)

网页搜索

  • TavilySearch实时新闻和网页搜索

开发工具

  • Jupyter Notebook交互式开发环境
  • python-dotenv环境变量管理
  • LangSmith大型语言模型（LLM）应用监控与调试

故障排除

1. ClosedResourceError 发生的；出现的

症状： Error: ClosedResourceError() 在执行时 retrieve 工具

原因当使用时 stdio_client + ClientSession会话在（满足条件时）自动关闭 async with 区块结束

解决方案使用 MultiServerMCPClient

# ❌ Incorrect approach
async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        tools = await load_mcp_tools(session)
# Session closes when block ends

# ✅ Correct approach
client = MultiServerMCPClient({
    "document-retriever": {
        "command": "../.venv/bin/python",
        "args": ["./mcp_server_rag.py"],
        "transport": "stdio",
    }
})
tools = await client.get_tools()  # Session remains active

2. OPENAI_BASE_URL 相关的403错误

症状： PermissionDeniedError: 403 unauthorized 当使用OpenAI嵌入向量时

原因系统环境变量已 OPENAI_BASE_URL=https://api.fireworks.ai/...

解决方案：

# Already applied in mcp_server_rag.py
if 'OPENAI_BASE_URL' in os.environ:
    del os.environ['OPENAI_BASE_URL']

3. load_dotenv() 失败

症状： .env 文件加载失败

原因工作目录与（另一个）不同 .env 文件位置

解决方案:

import os
os.chdir('/Users/ijunhyeong/Desktop/mcp/langgraph-mcp-agents/lee_mcp_tutorial')
load_dotenv(override=True)

4. 无法选择Jupyter内核

症状“langgraph-mcp”内核不在列表中

解决方案：

source ../.venv/bin/activate
python -m ipykernel install --user --name=langgraph-mcp --display-name="Python (langgraph-mcp)"

5. 模块导入错误

症状: ModuleNotFoundError: No module named 'utils'

原因项目目录不在 Python 路径中

解决方案:

import sys
sys.path.insert(0, '/Users/ijunhyeong/Desktop/mcp/langgraph-mcp-agents/lee_mcp_tutorial')

学习要点

1. MCP 会话管理

  • stdio_client + ClientSession仅在块作用域内有效
  • MultiServerMCPClient在全球范围内维持会话
  • MultiServerMCPClient 推荐用于Jupyter Notebook

2. RAG优化

  • 全局变量中的缓存检索器
  • 仅在首次调用时进行初始化
  • 设置 show_progress=False 在标准输入输出模式下

3. 代理提示（或代理引导）

prompt = (
    "You are a smart agent with multiple tools. "
    "Use `retrieve` tool to search information from iPhone documents. "
    "Use `tavily_search_results_json` tool to search recent news. "
    "Answer in English."
)
  • 提供清晰的工具使用说明
  • 明确指定每种工具的用途

4. 流式输出

  • 实时输出，带有 astream_graph() 函数
  • 工具追踪与 print_tool_info() 函数
  • 通过颜色编码提高可读性

参考文献

许可证

此项目免费提供，供学习和研究之用。

做出贡献

欢迎提交错误报告、功能建议和拉取请求！

相关 MCP