Deepeval MCP

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 头球

环境变量引用

\*至少需要一个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

触发器

1. 每日计划：每天UTC凌晨3点运行
2. 手册：通过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