Model Context Protocol (MCP) Agent Frameworks Demo

Model Context Protocol（MCP）Agent 框架演示与基准测试平台

本仓库演示如何使用多个框架，让大模型 Agent 调用 Model Context Protocol（MCP）服务中的工具：

• Google Agent Development Kit（ADK）
• LangGraph Agents
• OpenAI Agents
• Pydantic-AI Agents

仓库结构

• 使用单个 MCP 服务的 Agent - 学习示例和基本模式
• 使用多个 MCP 服务的 Agent - MCP 服务协调的进阶用法
• 评估套件 - 全面的基准测试工具
  • 评估仪表板：用于模型对比的交互式 Streamlit UI
  • 多模型基准测试：对多个大模型进行并行／顺序评估
  • 丰富的指标：用量分析、成本对比和性能排行榜

本仓库还包含 Python MCP 服务：

• example_server.py 基于 MCP Python SDK Quickstart - 修改后加入了日期时间工具，并作为由 Agent 调用的服务运行
• mermaid_validator.py - 使用 mermaid-cli 验证 Mermaid 图表的服务

跟踪通过 Pydantic Logfire 实现。

快速开始

1. cp .env.example .env

• 添加 GEMINI_API_KEY 和／或 OPENAI_API_KEY
  • 可以调整各个脚本，以使用特定框架支持的任意提供商的模型
• [可选] 添加 LOGFIRE_TOKEN，以在 Logfire Web UI 中查看评估结果

2. 测试一个 Agent 框架脚本，例如：

• uv run agents_mcp_usage/basic_mcp/basic_mcp_use/pydantic_mcp.py

  • 默认需要 GEMINI_API_KEY

• uv run agents_mcp_usage/basic_mcp/basic_mcp_use/oai-agent_mcp.py

  • 默认需要 OPENAI_API_KEY

3. 运行 Docker 化的单模型基准测试（依赖隔离）

• make benchmark MODEL="openai:gpt-5.2 (none)" RUNS=5 PARALLEL=1

查看控制台、Logfire 或 ADK Web UI 中的输出

项目概述

本项目旨在讲解：

1. 如何在多个大模型 Agent 框架中使用 MCP
   • 使用单个 MCP 服务的 Agent（basic_mcp）
   • 使用多个 MCP 服务的 Agent（multi_mcp）
2. 如何使用 Logfire 查看大模型 Agent 的跟踪记录
3. 如何使用 PydanticAI evals 评估大模型

仓库结构

• agents_mcp_usage/basic_mcp/ - 单个 MCP 服务集成示例

  • basic_mcp_use/ - 包含单个 MCP 使用的基础示例：
    • adk_mcp.py - 使用 Google Agent Development Kit（ADK 1.3.0）搭配 MCP 的示例
    • langgraph_mcp.py - 使用 LangGraph 搭配 MCP 的示例
    • oai-agent_mcp.py - 使用 OpenAI Agents 搭配 MCP 的示例
    • pydantic_mcp.py - 使用 Pydantic-AI 搭配 MCP 的示例
    • pydantic_mcp_factory.py - 展示用于支持多个提供商的模型工厂模式的示例

• agents_mcp_usage/multi_mcp/ - 高级多 MCP 服务集成示例

  • multi_mcp_use/ - 包含同时使用多个 MCP 服务的示例：
    • pydantic_mcp.py - 使用 Pydantic-AI Agent 搭配多个 MCP 服务的示例

• agents_mcp_usage/evaluations/ - 用于基准测试的评估模块

  • mermaid_evals/ - 用于修复 mermaid 图表任务的综合评估套件
    • evals_pydantic_mcp.py - 用于单模型测试的核心评估模块
    • run_multi_evals.py - 通过并行执行进行多模型基准测试
    • merbench_ui.py - 用于结果可视化的交互式仪表板

• 演示用 Python MCP 服务

  • mcp_servers/example_server.py - 使用 Python 实现的本地运行简易 MCP 服务
  • mcp_servers/mermaid_validator.py - 使用 Python 实现的 Mermaid 图表验证 MCP 服务

基础 MCP：使用单个服务

basic_mcp 目录展示了如何将单个 MCP 服务集成到不同的 Agent 框架中。每个示例都遵循类似的模式：

1. 环境设置：加载环境变量并配置日志记录
2. 服务连接：与本地 MCP 服务建立连接
3. Agent 配置：使用合适的模型设置 Agent
4. 执行：使用查询运行 Agent 并处理响应

这些示例中的 MCP 服务提供：

• 一个加法工具（add(a, b)）
• 一个时间工具（get_current_time()）
• 一个动态问候资源（greeting://{name}）

基础 MCP 架构

graph LR
    User((User)) --> |"Run script<br>(e.g., pydantic_mcp.py)"| Agent

    subgraph "Agent Frameworks"
        Agent[Agent]
        ADK["Google ADK<br>(adk_mcp.py)"]
        LG["LangGraph<br>(langgraph_mcp.py)"]
        OAI["OpenAI Agents<br>(oai-agent_mcp.py)"]
        PYD["Pydantic-AI<br>(pydantic_mcp.py)"]
        
        Agent --> ADK
        Agent --> LG
        Agent --> OAI
        Agent --> PYD
    end

    subgraph "Python MCP Server"
        MCP["Model Context Protocol Server<br>(mcp_servers/example_server.py)"]
        Tools["Tools<br>- add(a, b)<br>- get_current_time()"]
        Resources["Resources<br>- greeting://{name}"]
        MCP --- Tools
        MCP --- Resources
    end

    subgraph "LLM Providers"
        OAI_LLM["OpenAI Models"]
        GEM["Google Gemini Models"]
        OTHER["Other LLM Providers..."]
    end
    
    Logfire[("Logfire<br>Tracing")]
    
    ADK --> MCP
    LG --> MCP
    OAI --> MCP
    PYD --> MCP
    
    MCP --> OAI_LLM
    MCP --> GEM
    MCP --> OTHER
    
    ADK --> Logfire
    LG --> Logfire
    OAI --> Logfire
    PYD --> Logfire
    
    LLM_Response[("Response")] --> User
    OAI_LLM --> LLM_Response
    GEM --> LLM_Response
    OTHER --> LLM_Response

试用基础 MCP 示例：

# Google ADK example
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/adk_mcp.py

# LangGraph example
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/langgraph_mcp.py

# OpenAI Agents example
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/oai-agent_mcp.py

# Pydantic-AI example
uv run agents_mcp_usage/basic_mcp/basic_mcp_use/pydantic_mcp.py

# Launch ADK web UI for visual interaction
make adk_basic_ui

有关基础 MCP 实现的更多详情，请参阅 basic_mcp README。

多 MCP：高级用法

multi_mcp 目录展示了同时连接和协调多个专用 MCP 服务的高级技术。这种方法有以下优势：

1. 领域划分：每个 MCP 服务都可以专注于特定领域或一组能力
2. 模块化：无需影响整个系统，即可添加、移除或更新功能
3. 可扩展性：在多个服务之间分配负载，以提升性能
4. 专业化：针对特定用例优化各个 MCP 服务

多 MCP 架构

graph LR
    User((User)) --> |"Run script<br>(e.g., pydantic_mcp.py)"| Agent

    subgraph "Agent Framework"
        Agent["Pydantic-AI Agent<br>(pydantic_mcp.py)"]
    end

    subgraph "MCP Servers"
        PythonMCP["Python MCP Server<br>(mcp_servers/example_server.py)"]
        MermaidMCP["Python Mermaid MCP Server<br>(mcp_servers/mermaid_validator.py)"]
        
        Tools["Tools<br>- add(a, b)<br>- get_current_time()"]
        Resources["Resources<br>- greeting://{name}"]
        MermaidValidator["Mermaid Diagram<br>Validation Tools"]
        
        PythonMCP --- Tools
        PythonMCP --- Resources
        MermaidMCP --- MermaidValidator
    end

    subgraph "LLM Providers"
        LLMs["PydanticAI LLM call"]
    end
    
    Logfire[("Logfire<br>Tracing")]
    
    Agent --> PythonMCP
    Agent --> MermaidMCP
    
    PythonMCP --> LLMs
    MermaidMCP --> LLMs
    
    Agent --> Logfire
    
    LLM_Response[("Response")] --> User
    LLMs --> LLM_Response

试用多 MCP 示例：

# Run the Pydantic-AI multi-MCP example
uv run agents_mcp_usage/multi_mcp/multi_mcp_use/pydantic_mcp.py

# Run the multi-MCP evaluation
uv run agents_mcp_usage/evaluations/mermaid_evals/evals_pydantic_mcp.py

# Run multi-model benchmarking
uv run agents_mcp_usage/evaluations/mermaid_evals/run_multi_evals.py --models "gemini-2.5-pro-preview-06-05,gemini-2.0-flash" --runs 5 --parallel

# Dockerized benchmark for a single model (builds the image automatically)
make benchmark MODEL="openai:gpt-5.1 (none)" RUNS=5 PARALLEL=1

# Dockerized dry run (no API calls; useful for smoke tests)
make benchmark-dry-run MODEL="openai:gpt-5.1 (none)"

# Note: the Docker image installs benchmark-only dependencies.
# Run other demos/dashboards from your local environment.

# Launch the evaluation dashboard
uv run streamlit run agents_mcp_usage/evaluations/mermaid_evals/merbench_ui.py

有关多 MCP 实现的更多详情，请参阅 multi_mcp README。

评估套件与基准测试仪表板

此仓库包含一个综合评估系统，用于对多个框架和模型中的大模型 Agent 性能进行基准测试。该评估套件使用多个 MCP 服务测试 Agent 修正 mermaid 图表的能力，并提供丰富的指标和分析功能。

核心评测功能

• 多级难度：提供简单、中等和困难的测试用例，进行全面评估
• 多模型基准测试：跨多个大模型并行或按顺序进行评估
• 交互式仪表板：基于 Streamlit 的 UI，用于可视化结果、成本分析和模型对比
• 丰富的指标收集：Token 用量、成本分析、成功率和失败分类
• 稳健的错误处理：完善的重试逻辑和详细的失败分析
• 导出功能：导出 CSV 结果，用于后续分析和报告

仪表板功能

随附的 Streamlit 仪表板（merbench_ui.py）提供：

• 模型排行榜：按准确率、成本效益和速度对性能进行排名
• 成本分析：详细的成本明细和单次成功成本指标
• 失败分析：对失败原因进行分类，并提供调试见解
• 性能趋势：可视化模型在不同难度等级下的行为
• 资源使用情况：Token 消耗和 API 调用模式
• 对比分析：并排对比不同模型的性能

快速评测命令

# Single model evaluation
uv run agents_mcp_usage/evaluations/mermaid_evals/evals_pydantic_mcp.py

# Dockerized single-model benchmark (isolated dependencies)
make benchmark MODEL="openai:gpt-5.1 (none)" RUNS=5 PARALLEL=1

# Multi-model parallel benchmarking
uv run agents_mcp_usage/evaluations/mermaid_evals/run_multi_evals.py \
  --models "gemini-2.5-pro-preview-06-05,gemini-2.0-flash,gemini-2.5-flash" \
  --runs 5 \
  --parallel \
  --output-dir ./results

# Launch interactive dashboard
uv run streamlit run agents_mcp_usage/evaluations/mermaid_evals/merbench_ui.py

该评测系统支持跨大模型和 Agent 框架进行稳健、可重复的基准测试，既适用于研究，也有助于生产环境中的模型选择决策。

什么是 MCP？

Model Context Protocol 允许应用以标准化方式为大模型提供上下文，将提供上下文与实际的大模型交互分开处理。

了解更多：https://modelcontextprotocol.io/introduction

为什么选择 MCP

通过为资源（数据公开）、提示词（可复用模板）、工具（操作）和采样（补全）等组件定义明确的规范，MCP 简化了开发流程并促进一致性。

MCP 的一项主要优势是灵活性：开发者可以更轻松地在不同的大模型提供商之间切换，而无需彻底改造工具和数据集成。它提供了一种结构化的方法，有望降低为不同模型自定义工具实现时常见的复杂性。Google Agent Development Kit、LangGraph、OpenAI Agents 等框架以及 PydanticAI 等库有助于构建 Agent，而 MCP 则专注于标准化 Agent 的推理（大模型）与其能力（工具和数据）之间的接口，旨在打造更具互操作性的生态系统。

设置说明

1. 克隆此仓库

2. 安装所需软件包：

   make install
   

   要使用 ADK Web UI，请运行：

   make adk_basic_ui
   

3. 在 .env 文件中设置环境变量：

   LOGFIRE_TOKEN=your_logfire_token
   GEMINI_API_KEY=your_gemini_api_key
   OPENAI_API_KEY=your_openai_api_key
   

4. 按照上面的示例运行任意示例脚本

关于 Logfire

Logfire 是由 Pydantic 团队推出的可观测性平台，让 AI 应用监控变得简单。其功能包括：

• 简洁而强大的仪表板
• 以 Python 为中心的洞察，包括丰富的 Python 对象展示
• 基于 SQL 查询应用数据
• 支持 OpenTelemetry，便于利用现有工具
• 集成 Pydantic，可对验证结果进行分析

Logfire 让你能够了解代码的运行情况；对于需要深入理解模型行为的 LLM 应用，这一点尤为重要。