Llamator MCP Server

🚀 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 文件。