Lucius MCP

Allure TestOps MCP 服务

Lucius 是专为 Allure TestOps 打造的模型上下文协议（MCP）服务，使用 FastMCP 和 Starlette 构建。

🎯 初衷

Allure TestOps 是一款功能强大的工具，拥有庞大的 API。当你使用 AI Agent 管理测试时，很容易陷入细节，或因一个小小的技术失误而失败。

Lucius 通过提供简单易用且不易出错的 AI 工具，让这一切变得更轻松：

• 清晰的工具：每个工具都针对特定任务设计，例如“查找测试用例”或“更新一次运行”。
• 实用的错误提示：如果 AI 出错，Lucius 不会只返回错误代码，还会提供“Agent 提示”，准确说明出了什么问题以及如何修复。
• 可靠的基础：我们采用简洁的“薄工具”结构，使逻辑保持一致，便于人类和 AI 理解。

🛠️ 支持的工具

请参阅工具参考中的完整说明。

工具类别	描述	所有工具
测试用例管理	测试文档的完整生命周期管理。	create_test_case, update_test_case, delete_test_case, delete_archived_test_cases, get_test_case_details, get_test_case_custom_fields
自动化生成	根据现有测试用例生成特定框架的代码。	generate_test_code
搜索与发现	高级搜索和项目元数据发现。	list_test_cases, search_test_cases, get_custom_fields, list_integrations, get_project
共享步骤	创建和管理可重复使用的步骤序列。	create_shared_step, list_shared_steps, update_shared_step, delete_shared_step, delete_archived_shared_steps, link_shared_step, unlink_shared_step
测试层	管理测试分类体系和自动映射架构。	list_test_layers, create_test_layer, update_test_layer, delete_test_layer, list_test_layer_schemas, create_test_layer_schema, update_test_layer_schema, delete_test_layer_schema
测试层级	以树形路径组织套件并分配测试。	create_test_suite, list_test_suites, assign_test_cases_to_suite, delete_test_suite
自定义字段	在项目级别管理自定义字段值。	list_custom_field_values, create_custom_field_value, update_custom_field_value, delete_custom_field_value, delete_unused_custom_fields
发布管理	管理发布、结果上传、手动执行、重新运行和附件。	create_launch, list_launches, get_launch, list_launch_test_results, upload_test_results, attach_file_to_launch, rerun_test_results_manually, start_manual_test_session, submit_manual_test_results, add_test_result_attachment
测试结果管理	检查一条确切的 TestOps 结果，并准备经过验证的证据下载。	get_test_result, prepare_attachment_download
测试计划	管理测试计划及其内容。	create_test_plan, update_test_plan, delete_test_plan, list_test_plans, manage_test_plan_content, run_test_plan
缺陷管理	跟踪缺陷、关联关系和自动化规则。	create_defect, get_defect, update_defect, delete_defect, list_defects, link_defect_to_test_case, unlink_issue_from_test_case, list_defect_test_cases, create_defect_matcher, list_defect_matchers, update_defect_matcher, delete_defect_matcher

🚀 快速开始

1. 安装 uv：curl -LsSf https://astral.sh/uv/install.sh | sh
2. 设置凭据：创建包含以下变量的 .env 文件，或使用 lucius auth 保存 CLI 身份验证信息。
3. 运行服务：uv run start

快速开始所需的基本 .env

变量	描述	示例
ALLURE_ENDPOINT	Allure TestOps 基础 URL	https://example.testops.cloud
ALLURE_PROJECT_ID	默认 Allure 项目 ID（get_project 可选；项目范围工具必需）	123
ALLURE_API_TOKEN	Allure API 令牌	<your_api_token>
MCP_MODE	Lucius 运行时的 MCP 传输模式	stdio

🔌 Claude Desktop 集成

在 Claude Desktop 中使用 Lucius 的最简单方式是使用 .mcpb 捆绑包：

1. 从 Releases 下载最新的 lucius-mcp.mcpb。
2. 使用 Claude Desktop 打开。
3. 在界面中配置 Allure 凭据。

💻 Claude Code 集成

若要将 Lucius 添加到 Claude Code，请在项目目录中运行以下命令：

claude mcp add --transport stdio --scope project \
  --env ALLURE_ENDPOINT=https://example.testops.cloud \
  --env ALLURE_PROJECT_ID=123 \
  --env ALLURE_API_TOKEN=<your_api_token> \
  --env MCP_MODE=stdio \
  testops-mcp -- uvx --from lucius-mcp --refresh start

项目范围的文本配置示例（.mcp.json）：

{
  "mcpServers": {
    "testops-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "lucius-mcp",
        "--refresh",
        "start"
      ],
      "env": {
        "ALLURE_ENDPOINT": "https://example.testops.cloud",
        "ALLURE_PROJECT_ID": "123",
        "ALLURE_API_TOKEN": "<your_api_token>",
        "MCP_MODE": "stdio"
      }
    }
  }
}

🧠 Codex 集成

若要将 Lucius 添加到 Codex（CLI 或 IDE 扩展），请使用：

codex mcp add testops-mcp \
  --env ALLURE_ENDPOINT=https://example.testops.cloud \
  --env ALLURE_PROJECT_ID=123 \
  --env ALLURE_API_TOKEN=<your_api_token> \
  --env MCP_MODE=stdio \
  -- uvx --from lucius-mcp --refresh start

文本配置示例（~/.codex/config.toml 或项目 .codex/config.toml）：

[mcp_servers.testops-mcp]
command = "uvx"
args = ["--from", "lucius-mcp", "--refresh", "start"]

[mcp_servers.testops-mcp.env]
ALLURE_ENDPOINT = "https://example.testops.cloud"
ALLURE_PROJECT_ID = "123"
ALLURE_API_TOKEN = "<your_api_token>"
MCP_MODE = "stdio"

有关详细设置说明（包括 Claude Desktop（MCPB）集成），请参阅设置指南。

🐍 支持的 Python 版本

Lucius 在运行时支持 Python 3.10 至 3.14。生成的 MCPB 清单和代表性的 Nuitka CLI 编译器矩阵也会验证相同的版本范围。Python 3.15 支持处于实验阶段：安装可能需要从源代码构建，平台兼容性仍在验证中。当前限制请参阅开发指南。由于固定版本的 Starlette 依赖要求 Python 3.10 或更高版本，因此仍不支持 Python 3.9。

💻 命令行界面（CLI）

Lucius 还提供通用 CLI 入口，可直接从命令行执行工具：

# List available actions for an entity
uv run lucius test_case

# Execute an action
uv run lucius test_case get --args '{"test_case_id": 1234}'

# Show help for a specific entity/action
uv run lucius test_case get --help

# Save reusable CLI auth
uv run lucius auth --url https://example.testops.cloud --token <your_api_token> --project 123
uv run lucius auth status
uv run lucius auth clear

CLI 功能：

• 🎯 经过验证的类型安全实体／操作调用
• 🔐 可选的持久化 CLI 身份验证，使用原生的按用户配置存储
• 📊 多种输出格式（JSON、表格、csv、纯文本）
• 🔍 提供参数和示例的逐操作帮助
• 🛡️ 清晰的错误消息和指导
• 📦 适用于 Linux、macOS 和 Windows 的独立二进制文件

CLI 身份验证的优先级如下：

1. 显式工具参数，例如 api_token 或 project_id
2. 环境变量
3. 使用 uv run lucius auth 保存的 CLI 身份验证配置
4. 默认值

保存的 CLI 身份验证信息使用原生配置路径：

• Linux/Unix：$XDG_CONFIG_HOME/lucius/auth.json 或 ~/.config/lucius/auth.json
• macOS：~/Library/Application Support/lucius/auth.json，除非显式设置了 XDG 覆盖项
• Windows：%LOCALAPPDATA%\lucius\auth.json

完整的 CLI 文档和安装说明请参阅 CLI 指南。

📡 遥测

Lucius 会收集保护隐私的使用遥测数据，以提升工具质量。遥测默认启用，并会将元数据发送至 https://stats.ostanin.me；该端点由项目所有者运营（没有第三方可以访问此端点）。

如果你的环境允许，保持启用有助于 Lucius 持续改进。如果你希望退出，请在环境中设置 TELEMETRY_ENABLED=false。

不会发送 API 令牌、测试内容或工具参数。

完整的数据字典和遥测行为详情请参阅遥测与隐私。

📂 文档

完整文档位于 docs/ 文件夹中：

• 架构与设计
• 工具参考
• 配置与设置
• 遥测与隐私
• 附件下载能力链接
• 开发指南
• AI Agent 协议

🤝 Contributing

Contributions are welcome! Please see the Contribution Guidelines and the Development Guide for more details.