SalesforceAIResearch__MCP-宇宙.c4dd787a

作者：swesmith-repos0 星标更新：2025-11-17

安装使用来源：spider==github.com

项目介绍

<img src="assets/icon.png" alt="MCP-Universe" width="23" height="23"> MCP-Universe

</div>

什么是MCP-Universe？

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

MCP-Universe简介

</div>

与依赖过于简单任务的现有基准不同，MCP-Universe通过与实际MCP服务器交互来评估LLM在真实世界场景中的表现，捕捉到实际应用挑战，如：

🎯 长周期推理跨越多步骤任务
🔧 大型陌生工具空间具有多样化的MCP服务器
🌍 真实世界数据源和实时环境
⚡ 动态评估带有时间敏感的基准事实

性能亮点

即使是最先进的模型，在真实的MCP交互中也显示出显著的局限性：

🥇 GPT-5：成功率为43.72%
🥈 Grok-4：成功率为33.33%
🥉 Claude-4.0-Sonnet：成功率为29.44%

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

架构概述

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

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

下图展示了高层次视图：

┌─────────────────────────────────────────────────────────────────┐
│                      应用层                          │
├─────────────────────────────────────────────────────────────────┤
│  仪表板  │    Web API      │   Python库   │   基准测试   │
│   (Gradio)  │   (FastAPI)     │                │                │
└─────────────┬─────────────────┬────────────────┬────────────────┘
              │                 │                │
┌─────────────▼─────────────────▼────────────────▼────────────────┐
│                      编排层                        │
├─────────────────────────────────────────────────────────────────┤
│           工作流           │        基准测试运行器         │
│    (链、路由器等)      │      (评估引擎)        │
└─────────────┬─────────────────┬────────────────┬────────────────┘
              │                 │                │
┌─────────────▼─────────────────▼────────────────▼────────────────┐
│                        代理层                              │
├─────────────────────────────────────────────────────────────────┤
│  基本代理 │   ReAct代理    │  函数调用  │     其他      │
│             │                 │     代理      │     代理     │
└─────────────┬─────────────────┬────────────────┬────────────────┘
              │                 │                │
┌─────────────▼─────────────────▼────────────────▼────────────────┐
│                      基础层                           │
├─────────────────────────────────────────────────────────────────┤
│   MCP管理器   │   LLM管理器   │  内存系统 │  追踪器  │
│   (服务器及    │   (多模型  │   (RAM, Redis)  │ (日志) │
│    客户端)     │    支持)     │                 │           │
└─────────────────┴─────────────────┴─────────────────┴───────────┘

更多信息可以在这里找到：这里。

快速开始

我们遵循此仓库中的特性分支工作流，以确保代码质量，我们的CI集成了PyLint以强制执行Python编码标准。

前提条件

Python：需要版本3.10或更高。
Docker：用于运行Docker化的MCP服务器。
PostgreSQL（可选）：用于数据库存储和持久化。
Redis（可选）：用于缓存和内存管理。

安装

克隆仓库

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

创建并激活虚拟环境

python3 -m venv venv
source venv/bin/activate

安装依赖项

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

特定平台需求

Linux:

sudo apt-get install libpq-dev

macOS:

brew install postgresql

配置预提交钩子
```
pre-commit install
```

环境配置

cp .env.example .env
# 使用您的API密钥和配置编辑.env

快速测试

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

将.env.example文件复制到一个名为.env的新文件中。
在.env文件中，设置代理使用的各种服务所需的API密钥，例如OPENAI_API_KEY和GOOGLE_MAPS_API_KEY。

要编程执行基准测试：

from mcpuniverse.tracer.collectors import MemoryCollector  # 您也可以使用SQLiteCollector
from mcpuniverse.benchmark.runner import BenchmarkRunner

async def test():
    trace_collector = MemoryCollector()
    # 选择位于“mcpuniverse/benchmark/configs”文件夹下的基准配置文件
    benchmark = BenchmarkRunner("dummy/benchmark_1.yaml")
    # 运行指定的基准测试
    results = await benchmark.run(trace_collector=trace_collector)
    # 获取跟踪记录
    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模型（gpt-5等）的API密钥	所有领域
`ANTHROPIC_API_KEY`	Anthropic	Claude模型的API密钥	所有领域
`GEMINI_API_KEY`	Google	Gemini模型的API密钥	所有领域

注意：您只需配置您打算在评估中使用的LLM提供商的API密钥。

领域特定服务

环境变量	服务	描述	设置指南
`SERP_API_KEY`	SerpAPI	用于搜索基准评估的网络搜索API	获取API密钥
`GOOGLE_MAPS_API_KEY`	Google Maps	地理定位和地图服务	设置指南
`GITHUB_PERSONAL_ACCESS_TOKEN`	GitHub	用于仓库操作的个人访问令牌	令牌设置
`GITHUB_PERSONAL_ACCOUNT_NAME`	GitHub	您的GitHub用户名	N/A
`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

Blender安装：

从blender.org下载Blender v4.4.0
按照安装指南安装我们修改过的Blender MCP服务器
设置Blender可执行文件的路径

⚠️ 安全建议

🔒 重要安全通知

在运行基准测试之前，请仔细阅读并遵守以下安全指南：

🚨 GitHub集成：关键 - 我们强烈建议使用专用的测试GitHub帐户进行基准评估。AI代理将在GitHub存储库上执行实际操作，可能会修改或损坏您的个人存储库。
🔐 API密钥管理：
- 安全存储API密钥，切勿将其提交到版本控制
- 使用环境变量或安全密钥管理系统
- 定期轮换API密钥以增强安全性
🛡️ 访问权限：
- 为每个服务集成授予最低必要的权限
- 审查并限制API密钥的作用范围仅限于所需的操作
- 监控API使用情况并设置适当的速率限制
⚡ Blender操作：3D设计基准测试将执行可能修改或创建系统文件的Blender命令。确保您有足够的备份，并在必要时在隔离环境中运行。

基准配置

领域特定配置文件

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

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

LLM模型配置

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

kind: llm
spec:
  name: llm-1
  type: openai  # 或anthropic, google等
  config:
    model_name: gpt-4o  # 替换为目标模型

执行

运行单个基准测试

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

# 设置Python路径并运行单个基准测试
export PYTHONPATH=.

# 位置导航
python tests/benchmark/test_benchmark_location_navigation.py

# 浏览器自动化  
python tests/benchmark/test_benchmark_browser_automation.py

# 财务分析
python tests/benchmark/test_benchmark_financial_analysis.py

# 仓库管理
python tests/benchmark/test_benchmark_repository_management.py

# 网络搜索
python tests/benchmark/test_benchmark_web_search.py

# 3D设计
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 "运行基准测试: $domain"
    python "tests/benchmark/test_benchmark_${domain}.py"
    echo "完成: $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()传递给运行函数：

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": "现在旧金山的天气如何？",
  "mcp_servers": [
    {
      "name": "weather"
    }
  ],
  "output_format": {
    "city": "<City>",
    "weather": "<天气预报结果>"
  },
  "evaluators": [
    {
      "func": "json -> get(city)",
      "op": "=",
      "value": "旧金山"
    }
  ]
}

字段描述：

category：任务类别，例如“general”，“google-maps”等。您可以为此属性设置任何值。
question：您希望在此任务中询问的主要问题。这被视为用户消息。
mcp_servers：在此框架中支持的MCP服务器列表。
output_format：期望的代理响应输出格式。
evaluators：一组测试来

SalesforceAIResearch__MCP-宇宙.c4dd787a

项目介绍

<img src="assets/icon.png" alt="MCP-Universe" width="23" height="23"> MCP-Universe

什么是MCP-Universe？

性能亮点

目录

架构概述

快速开始

前提条件

安装

快速测试

评估LLM和代理

前提条件

环境配置

1. 初始设置

2. API密钥和配置

核心LLM提供商

领域特定服务

系统路径

配置示例

⚠️ 安全建议

基准配置

领域特定配置文件

LLM模型配置

执行

运行单个基准测试

批量执行

保存运行日志

将基准结果保存到报告

可视化代理运行信息

创建自定义基准

任务定义