allure-testops-mcp

allure-testops-mcp

一个适用于 Allure TestOps 的 MCP 服务。它让 大模型 Agent（Claude Code、Cursor、OpenCode 等）通过 Allure REST API 浏览和管理项目、测试运行、测试用例、测试 结果和参考数据。

• 技术栈： Python 3.10+、FastMCP、stdio 传输。
• 兼容性： 适用于任何 Allure TestOps 实例——SaaS qameta.io 或可自托管／本地部署的实例（API 位于 /api/rs）。
• 实例范围——一次覆盖所有项目： 一个连接即可服务实例中的每个项目。服务不会固定到单个项目——使用 allure_list_projects 发现项目，然后传入任意 project_id。切换或比较项目无需重新配置。
• 适合企业使用： API 令牌身份验证、可选的 SSL 验证开关、主动绕过代理。
• 默认安全： 13 个只读工具；7 个写入工具默认关闭，需主动启用。

快速开始

claude mcp add allure -s user \
  --env ALLURE_URL=https://allure.example.com \
  --env ALLURE_TOKEN=your-api-token \
  -- uvx --from allure-testops-mcp allure-testops-mcp

然后向 Agent 提问：“列出所有 Allure 项目” 或 “显示项目 175 最近一次测试运行中的失败测试”。 在 Allure TestOps 的 Profile → API tokens 中获取 API 令牌。其他客户端的配置请参阅配置， 所有选项请参阅环境变量。

工具一览

共 20 个工具——13 个只读工具（始终启用）和 7 个写入工具（通过 ALLURE_ENABLE_WRITE=true 选择性启用）。每个工具 都带有 MCP 注解，并同时返回类型化的 structuredContent 负载和 Markdown 摘要。

工具	类型	用途
allure_list_projects	read	所有项目（id、名称、缩写）
allure_get_project_statistics	read	测试用例数量、自动化率、最近一次测试运行摘要
allure_list_launches	read	最近的测试运行及通过／失败统计
allure_get_test_results	read	某次测试运行中的测试结果（按状态筛选）
allure_search_failed_tests	read	最近一次或指定测试运行中的 FAILED/BROKEN 测试
allure_list_test_cases	read	测试用例（自动化／手动及负责人筛选）
allure_get_test_case	read	单个测试用例的完整详情和场景步骤
allure_get_test_case_custom_fields	read	测试用例的自定义字段值
allure_list_statuses	read	项目状态（id、名称、颜色）
allure_list_layers	read	项目测试层级（id、名称）
allure_list_custom_fields	read	项目自定义字段架构
allure_list_categories	read	缺陷类别（带名称／颜色的分组）
allure_list_category_matchers	read	正则自动化规则（消息／跟踪信息 → 类别）
allure_create_test_case	write ⚑	创建测试用例
allure_update_test_case	write ⚑	部分更新测试用例
allure_delete_test_case	write ⚑	永久删除（具有破坏性——需要 confirm=true）
allure_create_category	write ⚑	创建缺陷类别
allure_delete_category	write ⚑	永久删除（具有破坏性——需要 confirm=true）
allure_create_category_matcher	write ⚑	创建并附加正则自动化规则
allure_delete_category_matcher	write ⚑	永久删除（具有破坏性——需要 confirm=true）

⚑ 仅在 ALLURE_ENABLE_WRITE=true 时注册。未设置该标志时，这些工具不会被导入，因此 Agent 也看不到它们——请参阅安全注意事项。

写入工具 — 按名称或 ID 设置状态和层级

allure_create_test_case / allure_update_test_case 接受名称（status / layer）或数字 ID（status_id / layer_id）作为状态和层级。名称会根据项目的状态列表和层级列表自动解析为 ID（GET /api/rs/status / GET /api/rs/testlayer）——如果名称未知，会返回可操作的错误，并列出有效选项。更新是部分更新（仅更改你传入的字段），而 allure_delete_test_case 不可撤销：它带有 destructiveHint: True（合规的客户端会提示），并且还要求显式传入 confirm=true 参数。

设计亮点

• 完整的工具注解 — 读取工具设为 readOnlyHint: True / openWorldHint: True，因此客户端不会提示；allure_delete_test_case 设为 destructiveHint: True。
• 每个工具都提供结构化输出 — 每个工具都声明了 TypedDict 返回类型，因此 FastMCP 会自动生成 outputSchema，且每个结果都同时包含 structuredContent 和 Markdown 区块。
• 可操作的错误信息 — 身份验证 / 400 / 403 / 404 / 409 / 429 / 5xx / 缺少环境变量等错误会转换为具体的后续操作提示（例如 “身份验证失败——请确认 ALLURE_TOKEN 具有 API 权限”）。
• Pydantic 输入验证 — 每个参数都有类型化约束（范围、长度、字面值），并以 JSON Schema 形式公开；用户名限制为仅包含字母，以防止 RQL 注入。
• 分页 — 列表工具会返回包含 page、total、has_more、next_page 的 pagination 区块。
• 进度报告 — 多次调用的工具会发出 ctx.report_progress + ctx.info 事件。
• 不受版本影响的更新动词 — allure_update_test_case 会发送 PATCH，并在 HTTP 405 时回退到 PUT，因此可适用于仅支持其中一种动词的 Allure 部署。
• 版本的唯一真实来源 — __version__ 源自已安装的软件包元数据，且测试会断言 pyproject.toml 与 server.json 中的两个版本字段一致，因此已发布的版本不会出现偏差。

安装

需要 Python 3.10+。如果使用 uvx（推荐），则无需手动安装——MCP 客户端会运行它。

# run on demand via uvx (recommended)
uvx --from allure-testops-mcp allure-testops-mcp

# or install with pipx
pipx install allure-testops-mcp

配置

Claude Code — 一条命令：

claude mcp add allure -s user \
  --env ALLURE_URL=https://allure.example.com \
  --env ALLURE_TOKEN=your-api-token \
  --env ALLURE_SSL_VERIFY=true \
  -- uvx --from allure-testops-mcp allure-testops-mcp

任何 MCP 客户端 — 添加到 ~/.claude.json、项目的 .mcp.json、Cursor 的 mcp.json 等文件中：

{
  "mcpServers": {
    "allure": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "allure-testops-mcp", "allure-testops-mcp"],
      "env": {
        "ALLURE_URL": "https://allure.example.com",
        "ALLURE_TOKEN": "${ALLURE_TOKEN}",
        "ALLURE_SSL_VERIFY": "true"
      }
    }
  }
}

参见 .env.example 获取模板。验证连接：

claude mcp list
# allure: uvx --from allure-testops-mcp allure-testops-mcp - ✓ Connected

环境变量

变量	必需	默认值	描述
ALLURE_URL	是	—	Allure TestOps URL（例如 https://allure.example.com）
ALLURE_TOKEN	是	—	API 令牌（Allure → Profile → API tokens）
ALLURE_SSL_VERIFY	否	true	true/false。自签名企业证书请设为 false
ALLURE_ENABLE_WRITE	否	false	设为 true 可注册 7 个写入工具；默认使用只读服务

ALLURE_TEST_PROJECT_ID（以及可选的 ALLURE_TEST_STATUS / ALLURE_TEST_LAYER）仅用于选择性启用的实时集成测试——参见开发。

更新

该服务是一个 stdio 进程，客户端会在每个会话启动时重新运行，因此运行的版本由 uvx 调用决定。uvx 会将解析后的环境缓存到 ~/.cache/uv，因此旧版本会一直保留，直到你刷新缓存：

uvx --refresh --from allure-testops-mcp allure-testops-mcp   # force latest on next run
uv cache clean allure-testops-mcp                            # or drop the cached env

然后重新连接服务（/mcp → 重新连接，或重启会话）。若要通过配置控制版本，请编辑 args——固定版本以保持稳定，或始终使用最新版本：

// Pin a version (deterministic; bump consciously)
"args": ["--from", "allure-testops-mcp==0.8.0", "allure-testops-mcp"]

// Always latest on every start (adds a PyPI lookup per launch)
"args": ["--refresh", "--from", "allure-testops-mcp", "allure-testops-mcp"]

示例提示词

只读：

• “列出所有 Allure 项目”
• “显示项目 63 最近的 10 次发布”
• “项目 175 最近一次发布中的失败测试”
• “项目 842 的自动化率是多少？”
• “比较项目 63 和项目 842 的自动化率”——支持在一次会话中跨项目操作
• “显示测试用例 641012 的步骤”
• “项目 1664 有哪些自定义字段？”

启用 ALLURE_ENABLE_WRITE=true 后，可以用自然语言管理测试用例的增删改查：

• “在项目 63 中创建一个名为‘Login flow’的 Draft 手动 TC”
• “在项目 63 中添加一个带有标签 smoke、层级为 E2E 的自动化 smoke TC”
• “将测试用例 555 重命名为‘Login (rewritten)’，并将其状态设为 Active”
• “删除测试用例 555”——Agent 会传入 confirm=true，符合规范的客户端会先向你确认

安全注意事项

• API 令牌仅从 ALLURE_TOKEN 读取——绝不会通过命令行传递，也不会写入日志。
• 绝不会在工具响应中回显机密（不会输出请求头，也不会反射认证信息）。
• 自签名 SSL 需显式启用，通过 ALLURE_SSL_VERIFY=false 设置（默认值为 true）。在公共网络上禁用验证存在风险；仅在受信任的企业实例中使用。
• 禁用代理发现（session.trust_env = False）——服务会忽略 HTTP_PROXY / HTTPS_PROXY，避免请求在不知情的情况下经由非预期代理路由。
• 写入功能需显式启用，并遵循最小权限原则——未设置 ALLURE_ENABLE_WRITE=true 时，服务只会注册 13 个只读工具，即使使用具有写入权限的令牌，也无法创建、修改或删除任何内容。启用后，破坏性工具（allure_delete_test_case / allure_delete_category / allure_delete_category_matcher）会带有 destructiveHint: True，并要求设置 confirm=true。
• 使用 Pydantic 验证输入——每个参数都有类型和范围限制；用户名仅允许使用字母，以防止通过搜索端点进行 RQL 注入。
• 令牌的权限不会高于其所属账户——Allure 的 Api-Token 认证会继承签发用户的角色，因此只读（访客）账户无论 ALLURE_ENABLE_WRITE 标志如何设置，使用它的服务都只能进行只读操作。

速率限制

Allure TestOps 会对每个实例施加速率限制（通常每个令牌约为 60 次请求/分钟）。遇到 HTTP 429 时，服务会返回可执行的错误提示，建议等待 30–60s、减小 size，或使用较小页面进行分页。 有两个工具会在内部进行多次 API 调用——allure_get_project_statistics（3 次）和 allure_search_failed_tests（2–3 次）——并通过 MCP Context 报告各步骤的进度。

开发

git clone https://github.com/mshegolev/allure-testops-mcp.git
cd allure-testops-mcp
pip install -e '.[dev]'
pytest          # unit suite (all HTTP mocked)
ruff check src tests && ruff format --check src tests

直接运行服务（stdio 传输——会等待从 stdin 接收 MCP 消息）：

ALLURE_URL=... ALLURE_TOKEN=... allure-testops-mcp

实时实例集成测试

一个可选测试套件会针对实时 Allure 项目运行真实的创建 → 更新 → 删除生命周期。默认情况下不会选择该套件；除非提供了凭据，否则测试会自动跳过，因此普通的 pytest 运行仍会通过：

export ALLURE_URL=https://allure.example.com
export ALLURE_TOKEN=...                 # token from an account with write access
export ALLURE_ENABLE_WRITE=true
export ALLURE_TEST_PROJECT_ID=63        # a throwaway project you can write to
pytest -m integration tests/integration -v

贡献

欢迎提交问题和 PR。请确保单元测试套件通过（pytest），且代码检查无误（ruff check、 ruff format）；CI 会在 Python 3.10 / 3.11 / 3.12 上运行这两项检查。发布历史请参阅 CHANGELOG.md。

许可证

MIT © Mikhail Shchegolev