JinDaGe - llamator-mcp-server MCP Details

article

README

🚀 LLAMATOR MCP 服务器

LLAMATOR 的 MCP 服务器，可自动化大语言模型（LLM）红队工作流程。

🚀 快速开始

本仓库为 LLAMATOR 提供了一个面向生产的服务包装器，用于自动化大语言模型（LLM）红队工作。它提供了两个集成接口：

HTTP API（FastAPI）：用于作业提交、作业状态检索和工件访问。
MCP 服务器（可流式 HTTP 传输）：用于代理/工具集成，使 LLAMATOR 运行能够作为工具被调用。

执行是异步的，并通过 ARQ + Redis 进行编排。工件会上传到 MinIO，并通过预签名 URL 进行检索（以 JSON 形式返回，API 不会进行重定向）。

✨ 主要特性

异步测试运行：持久状态存储在 Redis 中。
请求持久化与密钥脱敏：
- API 密钥不以明文形式存储。
- 存储的有效负载仅包含布尔标记（例如 api_key_present）。
工件生命周期管理：
- 工作进程在 LLAMATOR_MCP_ARTIFACTS_ROOT/<job_id>/... 下创建作业本地工件。
- 工件以 artifacts.zip 存档的形式上传到 MinIO。
- HTTP API 可以列出作业前缀下的可用对象并解析预签名下载链接。
可选的 API 密钥保护：通过 X - API - Key 为 HTTP 和 MCP 接口提供保护。
OpenAPI 模式（Swagger UI）：支持 API 密钥授权。
Prometheus 指标：在 /metrics 处公开。

📦 安装指南

要求

Docker
Docker Compose

启动全栈服务

docker compose up --build

默认服务端点

HTTP API：http://localhost:8000
MinIO S3 端点：http://localhost:9000
MinIO 控制台：http://localhost:9001

健康检查

curl -sS http://localhost:8000/v1/health

💻 使用示例

HTTP API 使用示例

创建运行

curl -sS -X POST "http://localhost:8000/v1/tests/runs" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: <可选值>" \
  -d '{
    "tested_model": {
      "kind": "openai",
      "base_url": "http://host.docker.internal:1234/v1",
      "model": "llm",
      "api_key": "lm-studio"
    },
    "run_config": { "enable_reports": false },
    "plan": { "preset_name": "owasp:llm10", "num_threads": 1 }
  }'

响应包含：

job_id（uuid4 十六进制，32 个字符）
status（queued | running | succeeded | failed）
created_at（UTC 时间戳）

检索作业状态

curl -sS "http://localhost:8000/v1/tests/runs/<job_id>" \
  -H "X-API-Key: <可选值>"

响应包括：

status：当前作业状态
result：聚合指标（作业成功时）
error：错误详情（作业失败时）
error_notice：面向用户的简洁错误消息（作业失败时）

工件操作

列出作业可用的对象：

curl -sS "http://localhost:8000/v1/tests/runs/<job_id>/artifacts" \
  -H "X-API-Key: <可选值>"

解析特定对象的预签名下载 URL：

curl -sS "http://localhost:8000/v1/tests/runs/<job_id>/artifacts/<path>" \
  -H "X-API-Key: <可选值>"

下载端点返回包含 download_url 的 JSON 有效负载，不会进行重定向。

MCP 接口使用示例

MCP 服务器挂载到 FastAPI 应用程序中（默认挂载路径：/mcp），并使用可流式 HTTP 传输。

暴露的工具：

create_llamator_run：提交作业，等待完成，返回聚合指标和（如果可用）artifacts.zip 的预签名 URL。
get_llamator_run：返回已完成作业的聚合指标和可选的工件存档 URL。

两个工具都返回一致的响应模式：

{
  "job_id": "string",
  "aggregated": {
    "attack_name": {
      "metric": 0
    }
  },
  "artifacts_download_url": "string or null",
  "error_notice": "string or null"
}

协议说明、头信息和示例记录在 DOCUMENTATION.md 中。

📚 详细文档

配置

所有配置通过以 LLAMATOR_MCP_ 为前缀的环境变量提供。完整参考可在 DOCUMENTATION.md 中找到。

典型本地设置

cp .env.example .env

关键配置类别

Redis：作业队列和状态存储的连接 DSN。
MinIO：用于工件的 S3 兼容存储。
攻击/评判模型：用于 LLAMATOR 执行的 OpenAI 兼容端点。
API 安全：可选的 X - API - Key 保护。
作业执行：超时时间、TTL 和重试行为。

🔧 技术细节

安全模型

如果 LLAMATOR_MCP_API_KEY 为空，则禁用身份验证。
如果配置了该密钥，受保护的 HTTP 路由和 MCP 应用程序需要 X - API - Key: <值>。

本地开发

安装依赖

poetry install

运行 API 服务器

uvicorn llamator_mcp_server.main:app --host 0.0.0.0 --port 8000

运行工作进程

arq llamator_mcp_server.worker_settings.WorkerSettings

教程

在 notebooks/llamator_mcp_server_tutorial.ipynb 中有一个带有逐步示例的 Jupyter 笔记本。它演示了：

使用 curl 进行 HTTP API 使用
MCP JSON - RPC 协议交互
轮询作业完成情况
工件检索

测试

集成测试位于 llamator - mcp - server/tests 中，并依赖于 tests/.env.test。

运行测试：

pytest -q

📄 许可证

本项目根据 知识共享署名 - 相同方式共享 4.0 国际 许可证授权。详情请参阅 LICENSE 文件。

llamator-mcp-server