Deepeval MCP桥
暴露现有 deepeval-wrapper 通过模型上下文协议（MCP）兼容的FastAPI服务进行评估逻辑。
致谢
特性
MCP API（包装响应）
POST /mcp/evaluate–将评估有效载荷转发到包装器，并返回MCP格式的结果。GET /mcp/metrics–列出包装器可用的指标。GET /mcp/metrics/categories–获取按类别组织的指标。GET /mcp/metrics/{metric_type}–获取有关特定指标的详细信息。
直接包装访问
- 所有deepeval包装器端点均可在
/wrapper/* - API交互式文档，网址：
/wrapper/docs - 包括同步端点(
/wrapper/evaluate/,/wrapper/metrics/)异步作业管理(/wrapper/jobs/*)
附加功能
- 过程中ASGI通信（MCP服务器和包装器之间没有网络开销）
- 健康调查
/health和/healthz - 位于的API发现终结点
/有全面的文件 - Docker镜像已准备好进行本地开发或部署
- 带有服务信息的花哨创业横幅
先决条件
- Docker（建议使用24.x或更高版本）
- 至少一个用于运行评估的LLM API密钥（OpenAI、Anthropic或Google）
- 这
deepeval-wrapper包在Docker构建过程中自动嵌入
设置
1.配置环境变量
复制 .env.example 到 .env 并填充所需的秘密：
cp .env.example .env编辑 .env 文件和配置：
必需：LLM API密钥
至少 一 DeepEval运行评估需要以下内容：
OPENAI_API_KEY-OpenAI API密钥（推荐）- 在这里买一个ANTHROPIC_API_KEY-人类克劳德API密钥- 在这里买一个GOOGLE_API_KEY-Google API密钥- 在这里买一个
可选：身份验证
API_KEYS-统一身份验证：
API_KEYS-保护 两者/mcp/*和/wrapper/*端点与X-API-Key标头验证- 支持以逗号分隔的列表形式显示多个键：
key1,key2,key3 - 留空或未设置以禁用身份验证(不建议用于生产！)
安全说明：
- 如果
API_KEYS是 未设置，身份验证是 残疾的 对于两个端点组 - 包装器的不安全默认值
deepeval-default-key被自动覆盖为空字符串 - 这可以防止公开的默认密钥处于活动状态
示例：
# Single key (simple setup)
API_KEYS=my-secret-key-123
# Multiple keys (allows key rotation and multiple clients)
API_KEYS=client-1-key,client-2-key,rotation-key
# Disabled (leave blank or omit - not recommended for production!)
# API_KEYS=多个密钥的好处：
- 为不同的客户端发放不同的密钥以进行访问跟踪
- 无需停机即可旋转密钥（添加新密钥、迁移客户端、删除旧密钥）
- 撤销单个客户端访问权限，而不影响其他客户端
可选：高级设置
这些通常不需要更改：
DEEPEVAL_WRAPPER_IMPORT_PATH-模块导入路径（默认：app.main)DEEPEVAL_WRAPPER_ASGI_TARGET-ASGI应用程序目标（默认：自动检测）DEEPEVAL_HTTP_TIMEOUT-包装器调用超时（秒）（默认值：30)
2.构建和运行
docker build -t deepeval-mcp .
docker run --env-file .env -p 8000:8000 deepeval-mcp该服务将在 http://localhost:8000.
可用端点：
/-API发现和全面的文档/docs-MCP API交互式Swagger用户界面/wrapper/docs-直接包装API交互式Swagger UI
用法
示例请求
MCP服务器将请求转发到deepeval包装器，该包装器需要结构化的测试用例数据：
curl -X POST "http://localhost:8000/mcp/evaluate" \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key-here" \
-d '{
"test_case": {
"input": "What is the capital of France?",
"actual_output": "Paris is the capital of France."
},
"metrics": [
{"metric_type": "answer_relevancy"}
]
}'注： 如果 API_KEYS 未设置，可以省略 X-API-Key 标头（身份验证已禁用）。
备注：The metric_type 字段为必填项。常见值： answer_relevancy, faithfulness, contextual_relevancy, hallucination, bias, toxicity等等。
样品响应
响应被包裹在MCP信封中：
{
"type": "mcp.result",
"timestamp": "2024-01-01T00:00:00.000000+00:00",
"provider": "deepeval",
"request_id": "uuid-here",
"data": {
"test_case": {...},
"results": [
{
"metric": "answer_relevancy",
"score": 0.95,
"reason": "...",
"success": true
}
]
}
}备注：请求格式与 深度评估器API。有关可用的度量和测试用例格式，请参阅他们的文档。
直接访问包装器端点
包装器的完整API可在 /wrapper/*:
# List available metrics
curl -X GET "http://localhost:8000/wrapper/metrics/" \
-H "X-API-Key: your-api-key-here"
# Direct evaluation (without MCP wrapper)
curl -X POST "http://localhost:8000/wrapper/evaluate/" \
-H "Content-Type: application/json" \
-H "X-API-Key: your-api-key-here" \
-d '{
"test_case": {
"input": "What is the capital of France?",
"actual_output": "Paris is the capital of France."
},
"metrics": [
{"metric_type": "answer_relevancy"}
]
}'备注：两者都有 /mcp/* 和 /wrapper/* 端点使用相同的 API_KEYS 身份验证。如果 API_KEYS 未设置，可以省略 X-API-Key 头球
环境变量引用
| 变量 | 必填 | 默认 | 描述 |
|---|---|---|---|
OPENAI_API_KEY | GPT模型的三个\* | - | OpenAI API密钥之一 |
ANTHROPIC_API_KEY | 克劳德模型的三个\* | - | 人类API密钥之一 |
GOOGLE_API_KEY | Gemini模型的三个\* | - | Google API密钥之一 |
API_KEYS | No | Empty（auth disabled） | 用逗号分隔的API密钥同时保护两者 /mcp/* 和 /wrapper/* 端点 |
DEEPEVAL_WRAPPER_IMPORT_PATH | 没有 | app.main | 包装器的Python模块路径 |
DEEPEVAL_WRAPPER_ASGI_TARGET | 否 | 自动检测到 | ASGI应用程序导入路径 |
DEEPEVAL_HTTP_TIMEOUT | 没有 | 30 | 包装器调用超时（秒） |
\*至少需要一个LLM API密钥
安全说明：
- 如果
API_KEYS未设置，身份验证已设置 残疾的 （包装纸deepeval-default-key用空字符串覆盖） - 支持多个密钥：
API_KEYS=key1,key2,key3 - 在生产中使用强随机生成的密钥
开发说明
- 默认的Docker构建安装
git用于获取嵌入的包装器；如果您提供代码，请将其删除。 - 对于长时间运行的部署，考虑设置
UVICORN_WORKERS以及通过环境变量的其他运行时选项。 - 服务器包括
sitecustomize.py它修复了OpenAI SDK和httpx库的UTF-8编码问题。 - 身份验证是可选的，但 强烈推荐 用于生产部署。
- 包装器的不安全默认值
deepeval-default-key如果满足以下条件，则会自动用空字符串覆盖API_KEYS未设置。
持续集成
该存储库包括GitHub Actions工作流(.github/workflows/build.yaml)自动构建Docker镜像并将其发布到GitHub容器注册表（GHCR）。
工作流功能
- 自动版本检测：每天检查PyPI是否有新的DeepEval版本
- 智能构建逻辑：仅在检测到新版本时构建（节省CI分钟）
- 多架构支持：为两者而建
linux/amd64和linux/arm64 - 自动化测试：对已发布的图像进行烟雾测试
- 自动更新：自动更新
requirements.txt并提交更改 - 手动触发：可通过以下方式手动触发
workflow_dispatch
触发器
- 每日计划：每天UTC凌晨3点运行
- 手册：通过GitHub操作“运行工作流”按钮
已发布图片
图片发布到：
ghcr.io/identitry/deepeval-mcp:latest
ghcr.io/identitry/deepeval-mcp:拉最新消息：
docker pull ghcr.io/identitry/deepeval-mcp:latest或特定版本：
docker pull ghcr.io/identitry/deepeval-mcp:3.7.0