LLAMATOR

LLAMATOR的MCP服务器：自动化LLM红队工作流程

![License: CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/) ](https://github.com/LLAMATOR-Core/llamator-mcp-server/stargazers) ![Chat](https://t.me/llamator)

此服务器的功能

此服务已结束羊驼分为两个编程接口：

HTTP API：对测试运行、轮询状态、浏览/下载工件进行排队。
MCP服务器（流式HTTP）：将LLAMATOR公开为代理工作流的MCP工具。

它使用 瑞迪斯 存储作业状态和重传工人们执行LLAMATOR跑步。

主要使用流程：

提交运行请求（测试模型+测试计划）。
Worker运行LLAMATOR并汇总结果。
轮询作业状态，并可选择下载工件（日志/报告等）。

建筑

组件：

API容器 （FastAPI+安装的MCP ASGI应用程序）：

- 验证输入(validate_test_specs). - 取消ARQ作业队列(run_llamator_job). - 在以下位置提供HTTP端点 /v1/.... - 使用持久身份验证公开Swagger UI(swagger_ui_parameters={"persistAuthorization": True}). - 将MCP应用程序挂载到 LLAMATOR_MCP_MCP_MOUNT_PATH （默认值： /mcp). - 保护： - 通过FastAPI依赖的HTTP API(X-API-Key 头球 - 通过ASGI包装器安装MCP应用程序(X-API-Key 头球 - 转换 单消息SSE 回应 application/json 用于上游返回时的MCP POST请求 text/event-stream （缓冲高达1 MiB；否则通过）。

工人集装箱 （ARQ）：

- 解决测试计划（预设+明确的测试规范）。 - 运行LLAMATOR(llamator.start_testing)在一个线程。 - 持续 queued → running → succeeded/failed 状态到Redis。 - 处理工件生命周期： - 本地后端：在共享卷上留下工件 - S3后端：将工件归档到 artifacts.zip，上传到S3（预签名PUT），然后清理本地目录

瑞迪斯:

- 存储作业元数据、编辑请求、结果、错误（基于TTL）。

安全：

通过标头的HTTP和MCP路由的可选API密钥 X-API-Key.
如果 LLAMATOR_MCP_API_KEY 为空，身份验证已禁用。

快速入门（Docker Compose）

最小运行次数：

docker compose up --build

组合堆栈通常包括：

redis （端口： 6379:6379)
api （端口： ${LLAMATOR_MCP_HTTP_PORT:-8000}:${LLAMATOR_MCP_HTTP_PORT:-8000})
worker

预期的外部依赖性：

一 OpenAI兼容 攻击/判断/测试模型（如LM Studio、vLLM等）的端点，通过环境配置。

配置（环境）

所有服务设置都是从前缀为的环境变量中读取的 LLAMATOR_MCP_.

瑞迪斯

LLAMATOR_MCP_REDIS_DSN （默认值： redis://redis:6379/0)\

API和工作人员使用的Redis DSN。

文物存储

LLAMATOR_MCP_ARTIFACTS_ROOT （默认值： /data/artifacts)\

存储作业工件的根目录（每个子目录一个子目录 job_id).

工件后端

LLAMATOR_MCP_ARTIFACTS_BACKEND （默认值： auto，允许： local|s3|auto)\

工件后端选择： - local：从文件系统提供工件(LLAMATOR_MCP_ARTIFACTS_ROOT) - s3：将工件存储在S3兼容存储中（需要S3环境变量） - auto：如果已完全配置，请使用S3；否则退回到本地

S3兼容存储（后端为 `s3` 或 `auto`)

必修的：

LLAMATOR_MCP_S3_ENDPOINT_URL （例如。 https://s3.example.com)
LLAMATOR_MCP_S3_BUCKET
LLAMATOR_MCP_S3_ACCESS_KEY_ID
LLAMATOR_MCP_S3_SECRET_ACCESS_KEY

可选：

LLAMATOR_MCP_S3_REGION （默认为 us-east-1 内部为空）
LLAMATOR_MCP_S3_KEY_PREFIX （默认值：空）\

bucket下的关键字前缀（例如。 llamator-mcp).

行为：

工人将工作工件压缩到 artifacts.zip 并通过预签名的PUT URL将其上传到S3。
S3后端返回的HTTP下载 307重定向 到预先签名的GET URL（没有来自API的直接文件流

集装箱）。

MCP工具输出可能包括预签名 artifacts_download_url 为了 artifacts.zip （如果档案存在）。

API安全

LLAMATOR_MCP_API_KEY （默认值：空）\

如果设置，请求必须包含标头 X-API-Key: 对于受保护的路线。

公共路线：

GET /v1/health, GET /health
GET /metrics

受保护的路由（启用时需要API密钥）：

POST /v1/tests/runs
GET /v1/tests/runs/{job_id}
GET /v1/tests/runs/{job_id}/artifacts
GET /v1/tests/runs/{job_id}/artifacts/{path}
MCP可流式HTTP端点 LLAMATOR_MCP_MCP_MOUNT_PATH

攻击模型（兼容OpenAI）

LLAMATOR_MCP_ATTACK_OPENAI_BASE_URL （默认值： http://localhost:1234/v1)
LLAMATOR_MCP_ATTACK_OPENAI_MODEL （默认值： model-identifier)
LLAMATOR_MCP_ATTACK_OPENAI_API_KEY （默认值： lm-studio)
LLAMATOR_MCP_ATTACK_OPENAI_TEMPERATURE （默认值： 0.5)
LLAMATOR_MCP_ATTACK_OPENAI_SYSTEM_PROMPTS （默认：内置提示）

*_SYSTEM_PROMPTS 接受：

JSON数组（首选），例如。 ["Prompt 1", "Prompt 2"]
或换行符分隔的字符串

判断模型（兼容OpenAI）

LLAMATOR_MCP_JUDGE_OPENAI_BASE_URL （默认值： http://localhost:1234/v1)
LLAMATOR_MCP_JUDGE_OPENAI_MODEL （默认值： model-identifier)
LLAMATOR_MCP_JUDGE_OPENAI_API_KEY （默认值： lm-studio)
LLAMATOR_MCP_JUDGE_OPENAI_TEMPERATURE （默认值： 0.1)
LLAMATOR_MCP_JUDGE_OPENAI_SYSTEM_PROMPTS （默认：内置提示）

作业执行

LLAMATOR_MCP_JOB_TTL_SECONDS （默认值： 604800)\

Redis中作业密钥的TTL。

LLAMATOR_MCP_RUN_TIMEOUT_SECONDS （默认值： 3600)\

每个作业超时的ARQ（工作端）和MCP create_llamator_run 等待超时。

LLAMATOR_MCP_REPORT_LANGUAGE （默认值： en，允许： en|ru)\

合并运行配置中使用的默认报告语言。

日志记录

LLAMATOR_MCP_LOG_LEVEL （默认值： INFO)\

应用程序和工作程序的Python日志级别。

LLAMATOR_MCP_UVICORN_LOG_LEVEL （默认值： info)\

HTTP入口点的Uvicorn日志级别。

HTTP服务器

LLAMATOR_MCP_HTTP_HOST （默认值： 0.0.0.0)
LLAMATOR_MCP_HTTP_PORT （默认值： 8000)

MCP安装

LLAMATOR_MCP_MCP_MOUNT_PATH （默认值： /mcp)\

在FastAPI中安装MCP ASGI应用程序的路径。

LLAMATOR_MCP_MCP_STREAMABLE_HTTP_PATH （默认值： /)\

MCP应用程序（内部挂载）公开的可流化HTTP路径。

有效的MCP端点URL:

`http://:

默认情况下： http://localhost:8000/mcp/.

HTTP API

以下所有路线（健康/指标除外）均受保护 X-API-Key 如果 LLAMATOR_MCP_API_KEY 已设置。

健康

GET /v1/health → {"status":"ok"}
GET /health → {"status":"ok"}

创建测试运行

POST /v1/tests/runs → LlamatorTestRunResponse

请求正文： LlamatorTestRunRequest （参见请求模型).

答复(200):

{
  "job_id": "",
  "status": "queued",
  "created_at": "2025-01-01T00:00:00Z"
}

错误：

400 验证失败（例如重复的参数名称）。
401 如果API密钥是必需的并且无效/丢失。

获取跑步状态

GET /v1/tests/runs/{job_id} → LlamatorJobInfo

包含：

status: queued | running | succeeded | failed
时间戳
request: 已编辑 请求快照（无API密钥；仅 api_key_present: true|false)
可选的 result 或 error
可选的 error_notice （紧凑型服务器生成的错误字符串）

错误：

404 如果作业不存在。

列出工件

GET /v1/tests/runs/{job_id}/artifacts → ArtifactsListResponse

答复：

{
  "job_id": "",
  "files": [
    {"path":"logs/run.log","size_bytes":1234,"mtime":1735689600.0}
  ]
}

笔记：

如果作业存在但还没有工件： files: [].
对于S3后端，这将在作业前缀（路径/大小/mtime）下列出对象元数据。

错误：

404 如果作业不存在。
502 如果工件后端不可用。

下载工件

GET /v1/tests/runs/{job_id}/artifacts/{path} → 文件下载

行为取决于工件后端：

本地后端：返回 200 包含文件内容(FileResponse)
S3后端：返回 307 重定向到预签名的URL(RedirectResponse)

服务器强制执行安全的相对路径(.. 逃逸被拒绝）。

错误：

400 无效路径
404 缺少作业或缺少文件
502 工件后端错误

MCP API（流式HTTP）

MCP服务器安装在 LLAMATOR_MCP_MCP_MOUNT_PATH 并使用 可流式传输的HTTP 运输方式：

stateless_http=True
streamable_http_path=LLAMATOR_MCP_MCP_STREAMABLE_HTTP_PATH
json_response=True

暴露的工具：

create_llamator_run

- 输入： LlamatorTestRunRequest - 行为：提交作业和 等待完成 （在 LLAMATOR_MCP_RUN_TIMEOUT_SECONDS) - 输出：聚合结果字典+可选工件URL（S3后端）

get_llamator_run

- 输入： job_id: str - 行为：获取现有作业并返回聚合结果 只有完成了 - 输出：聚合结果字典+可选工件URL（S3后端）

工具输出模式：

{
  "job_id": "",
  "aggregated": {
    "": {
      "": 123
    }
  },
  "artifacts_download_url": "https://presigned-url.example/...",
  "error_notice": "SomeError: some message"
}

artifacts_download_url 是：

一个预签名的URL artifacts.zip 用于S3后端（如果存档存在）
null 对于本地后端，或者如果存档不可用

error_notice 是：

null 如果作业成功无误
失败作业的紧凑错误字符串（由worker存储或由作业错误有效负载构建）

此仓库中客户端常用的标头（集成测试）：

Accept: application/json, text/event-stream
MCP-Protocol-Version:
Origin: ://
可选地 Mcp-Session-Id: 初始化后
可选地 X-API-Key: 如果启用了auth

运输细节：

某些MCP处理程序可能会响应 text/event-stream 对于POST。服务器包括一个ASGI包装器，用于转换

单消息SSE 答复(data: )进入 application/json POST请求（如果可能）以支持期望原始JSON响应的客户端。

请求模型

`tested_model` （必填）

OpenAI兼容客户端配置：

kind: "openai" （必填）
base_url：OpenAI兼容的基本URL（必填），例如。 http://host:port/v1
model：型号标识符（必填）
api_key：可选
temperature：可选， [0.0, 2.0]
system_prompts：可选（JSON中的元组/列表）
model_description：可选

`plan` （必填）

测试计划可以通过预设和/或明确的测试列表来定义：

preset_name：LLAMATOR支持的可选预设名称（例如。 all, rus, owasp:llm01)
num_threads：可选， >= 1
basic_tests：可选列表：

- code_name：str - params：可选列表 {name, value} （每个测试的参数名称必须唯一）

custom_tests：可选列表：

- import_path：完全限定类（导入策略：必须以开头 llamator. 或 llamator_mcp_server.) - params：可选列表 {name, value} （每个测试的名称都是唯一的）

`run_config` （可选）

LLAMATOR运行配置的用户覆盖：

enable_logging: 布尔
enable_reports: 布尔
artifacts_path：作业工件目录内的安全相对路径
debug_level：int in {0,1,2}
report_language: "en" | "ru"

服务器将用户配置与默认值合并，并存储已解析的 artifacts_path 作为以下情况下的绝对路径： //....

最小示例请求（HTTP）

{
  "tested_model": {
    "kind": "openai",
    "base_url": "http://host.docker.internal:1234/v1",
    "model": "model-identifier",
    "api_key": "lm-studio"
  },
  "plan": {
    "preset_name": "owasp:llm07",
    "num_threads": 1
  }
}

文物存储

默认情况下，每个作业将工件写入：

//

如果 run_config.artifacts_path 如果提供，它必须是 安全相对路径 并在作业根内解析。

HTTP API公开：

列出作业根（或S3的作业前缀）下所有文件的元数据
按相对路径下载单个文件（经过验证的服务器端）

S3后端详细信息：

Worker创建存档 artifacts.zip 并通过预签名的PUT上传。
API通过预签名的GET解析下载，并返回307个重定向。
对于本地文件系统下载，API直接流式传输文件。

指标

Prometheus指标公开于：

GET /metrics

存储库测试

存储库发货 集成测试 锻炼正在运行的服务器。

地点：

tests/integration/test_http_api.py
tests/integration/test_mcp_api.py

他们验证了什么：

HTTP API测试

GET /v1/health 回报 {"status":"ok"}
POST /v1/tests/runs 创建工作并返回 job_id +初始状态
GET /v1/tests/runs/{job_id} 回报 LlamatorJobInfo 并编辑秘密(api_key_present)
GET /v1/tests/runs/does-not-exist 回报 404
GET /v1/tests/runs/{job_id}/artifacts 返回与模式兼容的列表
GET /v1/tests/runs/{job_id}/artifacts/../secrets.txt 被拒绝(400)
测试参数中存在重复的参数名 400 验证错误
作业完成后，尝试下载第一个列出的工件：

- 预期 307 + Location S3后端 - 预期 200 +本地后端的非空主体

MCP API测试

主控程序 tools/list 包含 create_llamator_run 和 get_llamator_run
create_llamator_run 返回一个字典：

- job_id （32字符十六进制） - aggregated （如果没有执行测试，则可能为空） - 可选的 artifacts_download_url

MCP工具结果可以通过以下任一方式返回：

- structuredContent - 或者作为JSON content[].text （回退解析）

测试配置：

tests/.env.test 定义集成默认值：

- 超时和轮询间隔 - MCP协议版本头值 - 最小请求负载默认值（预设名称、线程数、测试模型base_url/model/api_key）

可选覆盖：

LLAMATOR_MCP_TEST_BASE_URL 允许对已部署的服务运行测试。

维护者

罗曼·内罗诺夫roman.nieronov@mail.ru
蒂穆尔尼扎莫夫abc@nizamovtimur.ru
伊利亚·坦波夫tambovtsev.io@phystech.edu
毫无疑问，nikitinaalina.work@gmail.com

许可证📜

该项目根据以下条款获得许可 知识共享署名-非商业共享4.0 国际的 许可证。请参阅许可证文件以获取详细信息。

![Creative Commons License](https://creativecommons.org/licenses/by-nc-sa/4.0/)

Team11 Llamator MCP

快速接入

详细介绍

LLAMATOR

目录

此服务器的功能

建筑

快速入门（Docker Compose）

配置（环境）

瑞迪斯

文物存储

工件后端

S3兼容存储（后端为 s3 或 auto)

API安全

攻击模型（兼容OpenAI）

判断模型（兼容OpenAI）

作业执行

日志记录

HTTP服务器

MCP安装

HTTP API

健康

创建测试运行

获取跑步状态

列出工件

下载工件

MCP API（流式HTTP）

请求模型

tested_model （必填）

plan （必填）

run_config （可选）

最小示例请求（HTTP）

文物存储

指标

存储库测试

HTTP API测试

MCP API测试

维护者

许可证📜

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

S3兼容存储（后端为 `s3` 或 `auto`)

`tested_model` （必填）

`plan` （必填）

`run_config` （可选）