AI导哈

AI代理开发与评估框架

MCP-Universe 是一个用于开发、测试和评估AI代理的综合框架，支持与外部MCP服务器的无缝集成和复杂的代理编排工作流，适用于真实世界场景中的多步骤任务评估。

  • by eliumusk
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 eliumusk/mcp-universe

使用说明

MCP宇宙

什么是MCP宇宙？

MCP Universe是一个全面的框架，旨在开发、测试和基准测试AI代理。它为在各种任务环境中构建和评估AI代理和LLM提供了一个强大的平台。该框架还支持与外部MCP服务器的无缝集成，并促进复杂的代理编排工作流程。

与依赖于过于简单任务的现有基准不同，MCP Universe通过评估LLM来解决关键差距 现实世界场景 通过与实际MCP服务器的交互，捕捉实际应用程序的挑战，例如：

  • 🎯 长期推理 跨多步骤任务
  • 🔧 大型、陌生的工具空间 配备多种MCP服务器
  • 🌍 真实世界的数据源 以及生活环境
  • ⚡ 动态评价 具有时间敏感性的地面真相

业绩亮点

即使是最先进的模型在现实世界的MCP交互中也显示出明显的局限性：

  • 🥇 GPT-5：成功率43.72%
  • 🥈 Grok-4：33.33%的成功率
  • 🥉 第4.0-条-附件：成功率29.44%

这突显了现实世界MCP服务器交互的挑战性，以及当前LLM代理的巨大改进空间。

目录

架构概述

MCPUniverse架构由以下关键组件组成：

  • 代理 (mcpuniverse/agent/)：不同代理类型的基本实现
  • 工作流 (mcpuniverse/workflows/)：编排和协调层
  • MCP服务器 (mcpuniverse/mcp/)：协议管理和外部服务集成
  • LLM集成 (mcpuniverse/llm/)：多提供商语言模型支持
  • 基准测试 (mcpuniverse/benchmark/)：评价和测试框架
  • 仪表盘 (mcpuniverse/dashboard/)：可视化和监控界面

下图说明了高级视图：

┌─────────────────────────────────────────────────────────────────┐
│                      Application Layer                          │
├─────────────────────────────────────────────────────────────────┤
│  Dashboard  │    Web API      │   Python Lib   │   Benchmarks   │
│   (Gradio)  │   (FastAPI)     │                │                │
└─────────────┬─────────────────┬────────────────┬────────────────┘
              │                 │                │
┌─────────────▼─────────────────▼────────────────▼────────────────┐
│                      Orchestration Layer                        │
├─────────────────────────────────────────────────────────────────┤
│           Workflows           │        Benchmark Runner         │
│    (Chain, Router, etc.)      │      (Evaluation Engine)        │
└─────────────┬─────────────────┬────────────────┬────────────────┘
              │                 │                │
┌─────────────▼─────────────────▼────────────────▼────────────────┐
│                        Agent Layer                              │
├─────────────────────────────────────────────────────────────────┤
│  BasicAgent │   ReActAgent    │  FunctionCall  │     Other      │
│             │                 │     Agent      │     Agents     │
└─────────────┬─────────────────┬────────────────┬────────────────┘
              │                 │                │
┌─────────────▼─────────────────▼────────────────▼────────────────┐
│                      Foundation Layer                           │
├─────────────────────────────────────────────────────────────────┤
│   MCP Manager   │   LLM Manager   │  Memory Systems │  Tracers  │
│   (Servers &    │   (Multi-Model  │   (RAM, Redis)  │ (Logging) │
│    Clients)     │    Support)     │                 │           │
└─────────────────┴─────────────────┴─────────────────┴───────────┘

可以找到更多信息 这里.

入门指南

我们跟随 这 特征分支工作流 为了简单起见，在这个回购中。为了确保代码质量， 皮林特 已集成到我们的CI中，以执行Python编码标准。

先决条件

  • python：需要3.10或更高版本。
  • 码头工人：用于运行Docker化的MCP服务器。
  • PostgreSQL （可选）：用于数据库存储和持久化。
  • 瑞迪斯 （可选）：用于缓存和内存管理。

安装

  1. 克隆存储库

    git clone https://github.com/SalesforceAIResearch/MCP-Universe.git
cd MCP-Universe

  2. 创建并激活虚拟环境

    python3 -m venv venv
source venv/bin/activate

  3. 安装依赖项

    pip install -r requirements.txt
pip install -r dev-requirements.txt

  4. 平台特定要求

    Linux：

    sudo apt-get install libpq-dev

    macOS：

    brew install postgresql

  5. 配置预提交挂钩

    pre-commit install

  6. 环境配置

    cp .env.example .env
# Edit .env with your API keys and configuration

快速测试

要运行基准测试，您首先需要设置环境变量：

  1. 复制 .env.example 将文件转换为名为的新文件 .env.
  2. 在 .env 文件，为代理使用的各种服务设置所需的API密钥， 例如 OPENAI_API_KEY 和 GOOGLE_MAPS_API_KEY.

要以编程方式执行基准测试，请执行以下操作：

from mcpuniverse.tracer.collectors import MemoryCollector  # You can also use SQLiteCollector
from mcpuniverse.benchmark.runner import BenchmarkRunner

async def test():
    trace_collector = MemoryCollector()
    # Choose a benchmark config file under the folder "mcpuniverse/benchmark/configs"
    benchmark = BenchmarkRunner("dummy/benchmark_1.yaml")
    # Run the specified benchmark
    results = await benchmark.run(trace_collector=trace_collector)
    # Get traces
    trace_id = results[0].task_trace_ids["dummy/tasks/weather_1.json"]
    trace_records = trace_collector.get(trace_id)

评估LLM和代理

本节提供了使用MCP Universe基准套件评估LLM和AI代理的全面说明。该框架支持跨多个领域的评估，包括网络搜索、位置导航、浏览器自动化、财务分析、存储库管理和3D设计。

先决条件

在运行基准评估之前，请确保您已完成 入门指南 部分，并具有以下内容：

  • Python：3.10或更高版本
  • Docker：已在您的环境中安装并可用
  • 通过安装所有必需的依赖项 pip install -r requirements.txt
  • 活动虚拟环境
  • 为您打算评估的服务提供适当的API访问权限

环境配置

1.初始设置

复制环境模板并配置API凭据：

cp .env.example .env

2.API密钥和配置

在您的 .env 文件。所需的密钥取决于您计划评估的基准域：

核心LLM提供商
环境变量 提供者 描述 必需
OPENAI_API_KEY OpenAI GPT模型的API密钥（GPT-5等） 所有域
ANTHROPIC_API_KEY Anthropic Claude模型的API密钥 所有域
GEMINI_API_KEY Google Gemini模型的API密钥 所有域

备注：您只需要为要在评估中使用的LLM提供程序配置API密钥。

特定域服务
环境变量 服务 描述 设置说明
SERP_API_KEY SerpAPI 用于搜索基准评估的Web搜索API 获取API密钥
GOOGLE_MAPS_API_KEY 谷歌地图 地理定位和地图服务 安装指南
GITHUB_PERSONAL_ACCESS_TOKEN GitHub 用于存储库操作的个人访问令牌 令牌设置
GITHUB_PERSONAL_ACCOUNT_NAME GitHub 您的GitHub用户名 不适用
NOTION_API_KEY Notion Notion工作区访问的集成令牌 集成设置
NOTION_ROOT_PAGE Notion Notion工作区的根页面ID 请参阅下面的配置示例
系统路径
环境变量 描述 示例
BLENDER_APP_PATH Blender可执行文件的完整路径（我们使用v4.4.0） /Applications/Blender.app/Contents/MacOS/Blender
MCPUniverse_DIR 通往MCP Universe存储库的绝对路径 /Users/username/MCP-Universe
配置示例

Notion根页面ID: 如果您的Notion页面URL为：

https://www.notion.so/your_workspace/MCP-Evaluation-1dd6d96e12345678901234567eaf9eff

集 NOTION_ROOT_PAGE=MCP-Evaluation-1dd6d96e12345678901234567eaf9eff

搅拌机安装：

  1. 从以下网址下载Blender v4.4.0 blender.org
  2. 按照以下步骤安装我们经过修改的Blender MCP服务器 安装指南
  3. 设置Blender可执行文件的路径
⚠️ 安全建议

🔒 重要安全通知

在运行基准测试之前，请仔细阅读并遵循这些安全指南：

  • 🚨 GitHub集成: 关键的 -我们强烈建议使用专用的测试GitHub帐户进行基准测试评估。AI代理将在GitHub存储库上执行实际操作，这可能会修改或损坏您的个人存储库。

  • 🔐 API密钥管理:

    • 安全存储API密钥，永远不要将其提交到版本控制
    • 使用环境变量或安全密钥管理系统
    • 定期轮换API密钥以增强安全性

  • 🛡️ 访问权限:

    • 为每个服务集成授予最低限度的必要权限
    • 审查API关键作用域并将其限制为仅需要的操作
    • 监控API的使用情况并设置适当的费率限制

  • ⚡ 搅拌机操作：3D设计基准测试将执行Blender命令，这些命令可能会在您的系统上修改或创建文件。确保您有足够的备份，并在必要时在隔离环境中运行。

基准配置

域特定配置文件

每个基准域都有一个专用的YAML配置文件，位于 mcpuniverse/benchmark/configs/test/。要评估LLM/代理，请修改相应的配置文件：

域 配置文件 描述
网络搜索 web_search.yaml 搜索引擎和信息检索任务
位置导航 location_navigation.yaml 地理和地图相关查询
浏览器自动化 browser_automation.yaml Web交互和自动化场景
财务分析 financial_analysis.yaml 市场数据分析和财务计算
存储库管理 repository_management.yaml Git操作和代码库任务
3D设计 3d_design.yaml 基于Blender的3D建模和设计任务

LLM模型配置

在每个配置文件中，更新LLM规范以匹配您的目标模型：

kind: llm
spec:
  name: llm-1
  type: openai  # or anthropic, google, etc.
  config:
    model_name: gpt-4o  # Replace with your target model

执行

运行个人基准

使用以下命令执行特定的域基准测试：

# Set Python path and run individual benchmarks
export PYTHONPATH=.

# Location Navigation
python tests/benchmark/test_benchmark_location_navigation.py

# Browser Automation  
python tests/benchmark/test_benchmark_browser_automation.py

# Financial Analysis
python tests/benchmark/test_benchmark_financial_analysis.py

# Repository Management
python tests/benchmark/test_benchmark_repository_management.py

# Web Search
python tests/benchmark/test_benchmark_web_search.py

# 3D Design
python tests/benchmark/test_benchmark_3d_design.py

批处理执行

对于所有领域的综合评估：

#!/bin/bash
export PYTHONPATH=.

domains=("location_navigation" "browser_automation" "financial_analysis" 
         "repository_management" "web_search" "3d_design")

for domain in "${domains[@]}"; do
    echo "Running benchmark: $domain"
    python "tests/benchmark/test_benchmark_${domain}.py"
    echo "Completed: $domain"
done

保存运行日志

如果你想保存运行日志，你可以通过 trace_collector 对于基准运行函数：

from mcpuniverse.tracer.collectors import FileCollector

trace_collector = FileCollector(log_file="log/location_navigation.log")
benchmark_results = await benchmark.run(trace_collector=trace_collector)

将基准测试结果保存到报告中

如果要保存基准测试结果的报告，可以使用 BenchmarkReport 要转储报告，请执行以下操作：

from mcpuniverse.benchmark.report import BenchmarkReport

report = BenchmarkReport(benchmark, trace_collector=trace_collector)
report.dump()

可视化代理运行信息

要运行具有中间结果的基准测试并查看实时进度，请通过 callbacks=get_vprint_callbacks() 转到run函数：

from mcpuniverse.callbacks.handlers.vprint import get_vprint_callbacks

benchmark_results = await benchmark.run(
    trace_collector=trace_collector, 
    callbacks=get_vprint_callbacks()
)

这将在基准运行时打印出中间结果。

有关更多详细信息，请参阅代码中的文档或存储库中的现有配置示例。

创建自定义基准

基准由三个主要配置元素定义：任务定义， 代理/工作流定义和基准配置本身。下面是一个例子 使用一个简单的“天气预报”任务。

任务定义

任务定义以JSON格式提供，例如：

{
  "category": "general",
  "question": "What's the weather in San Francisco now?",
  "mcp_servers": [
    {
      "name": "weather"
    }
  ],
  "output_format": {
    "city": "<City>",
    "weather": "<Weather forecast results>"
  },
  "evaluators": [
    {
      "func": "json -> get(city)",
      "op": "=",
      "value": "San Francisco"
    }
  ]
}

字段描述：

  1. 类别：任务类别，例如“一般”、“谷歌地图”等。您可以为此属性设置任何值。
  2. 问题：此任务中您要问的主要问题。这被视为用户消息。
  3. mcp服务器：此框架中支持的MCP服务器列表。
  4. 输出格式：代理响应的理想输出格式。
  5. 评估师：要评估的测试列表。对于每个测试/评估器，它有三个属性：“func”表示 如何从代理响应中提取值，“op”是比较运算符，“value”是基本事实 价值。 它将评估 op（函数（…）、值、op_args…）“op”可以是“=”、“<”、“>”或其他自定义运算符。

在“evaluators”中，您需要编写一个规则（“func”属性），显示如何提取测试值。在示例中 上面，“json->get（city）”将首先进行json解码，然后提取密钥“city”的值。有几个 此仓库中的预定义函数：

  1. JSON：执行JSON解码。
  2. 得到：获取键的值。
  3. 长度：获取列表的长度。
  4. 遍历：执行FOR-EACH循环。

例如，让我们定义

data = {"x": [{"y": [1]}, {"y": [1, 1]}, {"y": [1, 2, 3, 4]}]}

然后 get(x) -> foreach -> get(y) -> len 将执行以下操作：

  1. 获取“x”的值： [{"y": [1]}, {"y": [1, 1]}, {"y": [1, 2, 3, 4]}].
  2. 执行foreach循环并获取“y”的值： [[1], [1, 1], [1, 2, 3, 4]].
  3. 获取每个列表的长度： [1, 2, 4].

如果这些预定义函数还不够，您可以实现自定义函数。 有关更多详细信息，请查看 这 文档.

基准定义

在YAML文件中定义代理和基准。以下是一个简单的天气预报基准：

kind: llm
spec:
  name: llm-1
  type: openai
  config:
    model_name: gpt-4o

---
kind: agent
spec:
  name: ReAct-agent
  type: react
  config:
    llm: llm-1
    instruction: You are an agent for weather forecasting.
    servers:
      - name: weather

---
kind: benchmark
spec:
  description: Test the agent for weather forecasting
  agent: ReAct-agent
  tasks:
    - dummy/tasks/weather.json

基准定义主要包括两部分：代理定义和基准配置。基准配置很简单——您只需要指定要使用的代理（通过定义的代理名称）和要评估的任务列表。每个任务条目都是任务配置文件 路径。它可以是完整文件路径或部分文件路径。如果它是一个部分文件路径（如“dummy/tasks/weather.json”）， 它应该放在 文件夹 mcpuniverse/基准测试/配置 在这个回购中。

该框架提供了一种灵活的方法来定义简单代理（如ReAct）和更复杂的多步骤代理 工作流程。

  1. 指定LLM： 首先声明希望代理使用的大型语言模型（LLM）。每个LLM组件 必须分配一个唯一的名称（例如。， "llm-1").这些名称用作框架用于连接的标识符 将不同的组件放在一起。
  2. 定义代理： 接下来，通过提供代理名称并选择代理类来定义代理。代理类包括 可用 这 麦克普纳律师事务所 包裹。 常用的课程包括 "basic", "function-call"，以及 "react"在代理规范范围内( spec.config)，您还必须通过设置 "llm" 现场。
  3. 创建复杂的工作流： 除了简单的代理之外，该框架还支持复杂、， 多个代理交互或协作以解决更复杂任务的编排工作流。

例如：

kind: llm
spec:
  name: llm-1
  type: openai
  config:
    model_name: gpt-4o

---
kind: agent
spec:
  name: basic-agent
  type: basic
  config:
    llm: llm-1
    instruction: Return the latitude and the longitude of a place.

---
kind: agent
spec:
  name: function-call-agent
  type: function-call
  config:
    llm: llm-1
    instruction: You are an agent for weather forecast. Please return the weather today at the given latitude and longitude.
    servers:
      - name: weather

---
kind: workflow
spec:
  name: orchestrator-workflow
  type: orchestrator
  config:
    llm: llm-1
    agents:
      - basic-agent
      - function-call-agent

---
kind: benchmark
spec:
  description: Test the agent for weather forecasting
  agent: orchestrator-workflow
  tasks:
    - dummy/tasks/weather.json

引用

如果您在研究中使用MCP Universe，请引用我们的论文：

@misc{mcpuniverse,
  title={MCP-Universe: Benchmarking Large Language Models with Real-World Model Context Protocol Servers},
  author={Ziyang Luo and Zhiqi Shen and Wenzhuo Yang and Zirui Zhao and Prathyusha Jwalapuram and Amrita Saha and Doyen Sahoo and Silvio Savarese and Caiming Xiong and Junnan Li},
  year={2025},
  eprint={2508.14704},
  archivePrefix={arXiv},
  primaryClass={cs.AI},
  url={https://arxiv.org/abs/2508.14704}, 
}

相关 MCP