MCPFlow评估
一个全面的评估框架，用于测试LLM在再生MCP（模型上下文协议）工具方面的能力，并在现有工作流程中验证其功能。
概述
MCPFlow评估评估大型语言模型在给定工作流上下文时重新生成功能性MCP工具的能力。该框架采用了一种稳健的方法，侧重于多个评估指标： 语法正确性, 工具注册成功, 单个工具执行，以及 工作流集成成功.
主要特点
- LLM驱动刀具再生：使用具有丰富工作流上下文的LLM重新生成MCP工具
- 综合评价指标：从语法到工作流执行的多级验证
- 单个工具测试：每个工具都经过独立测试，以进行准确评估
- FastMCP集成：基于FastMCP框架，用于MCP服务器/客户端实现
- 上下文感知生成：使用workflow.json、server.py、run_workflow.py和pyproject.toml作为上下文
- 多数据集支持：在独立环境中处理多个数据集
- 分层结果：有组织的输出结构，包括数据集级别和总体摘要
- 详细日志记录：完成测试输出捕获，用于调试和分析
快速开始
1.安装
# Clone the repository
git clone
cd MCPFlow-Evaluation
# Install dependencies using uv (recommended)
uv sync
# Or using pip
pip install -e .2.配置
根据提供的示例创建配置文件：
cp config.yaml.example config.yaml编辑 config.yaml 使用您的设置。以下是关键配置部分：
# Framework Configuration
framework_version: "1.0.0"
evaluation_id: "default-evaluation"
output_format: "json"
# Dataset Configuration
dataset_path: "dataset/example" # Path to dataset directory
tasks: ['tools_generation'] # Evaluation tasks to run
# Logging Configuration
log_level: "INFO"
debug_mode: false
save_intermediate_results: false
# LLM Configuration (Required)
llm_config:
provider: "openai"
model_name: "gpt-4o"
api_key: "YOUR_API_KEY_HERE" # Replace with your actual API key
base_url: "http://localhost:4000/v1" # Or OpenAI API URL
temperature: 0.2
max_tokens: 2000
timeout: 60.0
retry_attempts: 2
retry_delay: 1.0
# End-to-end Execution Configuration
e2e_config:
execution_timeout: 30.0
max_tool_generation: 5
max_tool_generation_attempts: 2
generated_module_name: "generated_tools"
allow_parallel_execution: false
error_handling_strategy: "continue"
validation_level: "import"
runner: "uv" # Use uv for workflow execution3.运行评估
测试评估系统：
# Run the MCP tool evaluation test
uv run python test/test_mcp_tool_evaluation.py测试LLM连接：
# Verify LLM connectivity
uv run python test/test_llm_connection.py建筑
核心组件
tasks/mcp_tool_regenerator.py：使用LLM的核心工具再生逻辑tasks/mcp_tool_evaluator.py：数据集级评估协调员tasks/result_storage.py：成果持久性和管理core/config.py：配置管理系统utils/llm_interface.py：LLM通信接口utils/metrics.py：度量计算实用程序models/workflow.py：工作流数据模型
评估程序
- 上下文集合：从多个来源收集工作流上下文：
- workflow.json：工作流结构和步骤说明 - server.py：服务器实现和工具注册模式 - run_workflow.py：工具使用示例和执行上下文 - pyproject.toml：可用依赖关系和项目配置
- 刀具再生：使用LLM重新生成每个MCP工具，包括：
- 丰富的上下文提示 - 显式参数要求（无\*args/\*\*kwargs） - JSON可序列化返回值 - FastMCP兼容性
- 多级验证:
- 语法验证：使用Python检查生成的代码语法 compile() 函数 - 工具注册：使用FastMCP SDK在MCP服务器上注册重新生成的工具 - 单个工具测试：在独立的服务器会话中独立测试每个工具 - 工作流集成：运行原始工作流测试以验证端到端功能
- 结果管理：生成综合报告，包括：
- 单个工具测试结果和输出 - 数据集级摘要 - 总体评价统计 - 详细的错误日志和调试信息
数据集结构
数据集应遵循此结构（请参见 dataset/README.md 详细规格）：
dataset/
├── example/
│ ├── workflow.json # Workflow definition
│ ├── run_workflow.py # Workflow execution script
│ ├── pyproject.toml # Dependencies and project config
│ ├── uv.lock # Dependency lock file
│ └── mcp_server/
│ ├── server.py # FastMCP server implementation
│ └── tools/ # Tool implementations
│ ├── __init__.py
│ ├── add.py
│ ├── multiply.py
│ └── ...所需文件
workflow.json：带有步骤描述和工具映射的工作流结构run_workflow.py：使用FastMCP客户端的可执行工作流mcp_server/server.py：注册工具的FastMCP服务器- **
mcp_server/tools/*.py**：单个工具实施 pyproject.toml：项目依赖关系和配置uv.lock：可复制环境的依赖锁定文件
工具要求
工具必须与FastMCP兼容：
def tool_name(param1: str, param2: int) -> dict:
"""Tool description"""
# Implementation
return {"result": "value"}
# TOOL_METADATA: {"name": "tool_name", "description": "...", "parameters": {...}}重要：工具无法使用 *args 或 **kwargs （FastMCP限制）。
结果结构
该框架按以下结构生成有组织的结果：
results/
├── dataset_name/
│ ├── evaluation_workflow_name.json # Detailed workflow results
│ ├── summary.json # Dataset-level summary
│ ├── tool1.py # Regenerated tool files
│ ├── tool2.py
│ └── ...
└── overall_summary.json # Cross-dataset summary结果文件
- **
evaluation_*.json**：每个工作流程的完整评估结果，包括：
- 单个工具测试结果和输出 - 语法验证结果 - 注册成功状态 - 执行测试日志 - 错误消息和调试信息
summary.json：数据集级统计包括：
- 每个验证级别的成功率 - 执行时间指标 - 逐个工具分解
overall_summary.json:
overall_summary.json：跨数据集汇总统计
评估指标
该框架提供了多个层面的全面评估：
1.语法正确率
- 生成的具有有效Python语法的工具的百分比
- 使用Python的内置验证
compile()函数 - 表示LLM生成语法正确代码的能力
2.刀具注册成功率
- 成功向MCP服务器注册的工具百分比
- 测试FastMCP兼容性和元数据正确性
- 指示正确的工具接口实现
3.单个工具执行成功率
- 单独成功执行的工具百分比
- 每个工具都在自己的服务器会话中独立测试
- 提供对单个工具功能的准确评估
4.工作流集成成功率
- 使用重新生成的工具成功执行的工作流百分比
- 测试端到端功能和工具交互
- 表示生成的工具在实际场景中的实用性
示例结果
{
"dataset_name": "example",
"total_workflows": 1,
"successful_workflows": 1,
"total_tools": 5,
"successful_tools": 5,
"syntax_correct_tools": 5,
"execution_success_rate": 1.0,
"syntax_success_rate": 1.0,
"average_execution_time": 12.60,
"results": [
{
"workflow_id": "simple_math_operations_workflow",
"workflow_name": "Simple Math Operations Workflow",
"tools": [
{
"name": "add",
"registration_success": true,
"execution_success": true,
"syntax_correct": true,
"test_stderr": "... detailed test output ..."
}
],
"execution_success": true,
"execution_time": 12.60
}
]
}控制台输出示例：
=== Evaluation Results ===
Dataset: example
Total workflows: 1
Successful workflows: 1
Total tools: 5
Tools with correct syntax: 5
Tools that passed registration: 5
Tools that passed individual tests: 5
Workflow success rate: 100.00%
Syntax correctness rate: 100.00%
Registration success rate: 100.00%
Individual test success rate: 100.00%
Average execution time: 12.60s
--- Workflow: Simple Math Operations Workflow ---
Overall workflow success: True
Tools regenerated: 5
- add: ✓ Syntax OK | ✓ Registration OK | ✓ Individual Test OK
- subtract: ✓ Syntax OK | ✓ Registration OK | ✓ Individual Test OK
- multiply: ✓ Syntax OK | ✓ Registration OK | ✓ Individual Test OK
- divide: ✓ Syntax OK | ✓ Registration OK | ✓ Individual Test OK
- fetch_data: ✓ Syntax OK | ✓ Registration OK | ✓ Individual Test OK发展
项目结构
MCPFlow-Evaluation/
├── core/ # Core framework components
│ └── config.py # Configuration management
├── tasks/ # Main evaluation tasks
│ ├── mcp_tool_regenerator.py # Tool regeneration logic
│ ├── mcp_tool_evaluator.py # Dataset evaluation coordinator
│ └── result_storage.py # Result persistence
├── utils/ # Utility modules
│ ├── llm_interface.py # LLM communication
│ ├── logger.py # Logging utilities
│ ├── metrics.py # Metrics calculation
│ └── json_encoder.py # JSON serialization utilities
├── models/ # Data models
│ └── workflow.py # Workflow representations
├── test/ # Test suite
│ ├── test_mcp_tool_evaluation.py # Main evaluation test
│ └── test_llm_connection.py # LLM connectivity test
├── dataset/ # Evaluation datasets
│ └── example/ # Example workflow
├── results/ # Evaluation results (generated)
│ └── example/ # Dataset-specific results
└── docs/ # Documentation
└── mcp_tool_evaluation.md # Detailed evaluation docs运行测试
# Run main evaluation test
uv run python test/test_mcp_tool_evaluation.py
# Test LLM connection
uv run python test/test_llm_connection.py
# Run with specific configuration
uv run python test/test_mcp_tool_evaluation.py --config custom_config.yaml添加新数据集
- 在下创建新目录
dataset/ - 遵循中指定的结构
dataset/README.md - 确保所有必需的文件都存在并且格式正确
- 包含
pyproject.toml和uv.lock用于依赖关系管理 - 在添加到评估套件之前进行本地测试
配置选项
该框架支持通过以下方式进行广泛配置 config.yaml:
框架设置
framework_version：版本标识符evaluation_id：评估运行的唯一标识符output_format：结果输出格式（目前仅JSON）
数据集设置
dataset_path：数据集目录或特定数据集的路径tasks：要执行的评估任务列表
LLM设置
provider：法学硕士提供者（openai、azure等）model_name：要使用的具体模型api_key：身份验证密钥base_url：API终结点URLtemperature：生成随机性（0.0-1.0）max_tokens：最大响应长度timeout：请求超时（秒）retry_attempts：重试尝试次数retry_delay：重试之间的延迟
执行设置
execution_timeout：工作流执行超时max_tool_generation：要生成的最大工具数max_tool_generation_attempts：重试工具生成尝试validation_level：验证深度（语法、导入、运行时、集成）runner：执行环境（python或uv）error_handling_strategy：如何处理错误（继续、停止、重试）
贡献
- 复刻仓库
- 创建要素分支
- 按照现有模式进行更改
- 添加新功能的测试
- 更新文档
- 提交拉取请求
故障排除
常见问题
配置错误:
ValueError: Required configuration key 'api_key' is missing- 解决方案：确保所有必填字段都存在于您的
config.yaml
导入错误:
ModuleNotFoundError: No module named 'tasks'- 解决方案：使用
uv run在适当的环境中执行脚本
LLM连接问题:
Error code: 400 - {'error': {'message': 'Invalid API key'}}- 解决方案：验证API密钥和LLM服务器配置
工具生成问题:
SyntaxError: invalid syntax in generated code- 解决方案：检查LLM模型功能并提示工程
紫外线环境问题:
uv: command not found- 解决方案：安装uv包管理器或在配置中使用python runner
调试模式
在配置中启用调试模式以进行详细日志记录：
debug_mode: true
log_level: "DEBUG"
save_intermediate_results: true这将提供：
- 详细的LLM请求/响应日志
- 逐步执行跟踪
- 中间文件保存
- 增强的错误报告
性能优化
- 并行执行：启用
allow_parallel_execution为了更快的处理 - 超时调整：调整
execution_timeout基于工作流复杂性 - 重试策略：配置
retry_attempts和retry_delay可靠性 - 验证级别：使用适当
validation_level满足您的需求
安全考虑
- API密钥：存储在配置文件中，从不存储在代码中
- 配置文件：使用
. gitignore排除敏感文件 - 代码执行：生成的工具在隔离环境中运行
- 输入验证：验证所有用户输入和配置参数
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
致谢
- 用于MCP服务器实现的FastMCP框架
- 用于Python环境管理的UV包管理器
- OpenAI和其他LLM提供商提供工具生成功能
______________________________________________________________________
有关评估方法和实施细节的更多详细信息，请参阅 docs/mcp_tool_evaluation.md.