{"id":42831204,"url":"https://github.com/ivanostanin/lucius-mcp","last_synced_at":"2026-08-28T02:08:02.171Z","repository":{"id":335163154,"uuid":"1144489782","full_name":"ivanostanin/lucius-mcp","owner":"ivanostanin","description":"A feature-rich Model Context Protocol (MCP) server and CLI for Allure TestOps TMS.","archived":false,"fork":false,"pushed_at":"2026-08-03T21:32:00.000Z","size":3630,"stargazers_count":7,"open_issues_count":1,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-08-07T02:04:13.299Z","etag":null,"topics":["allure","allure-testops","cli","fastmcp","mcp","mcp-server","model-context-protocol","test-management","testops","tms"],"latest_commit_sha":null,"homepage":"https://ivanostanin.github.io/lucius-mcp/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ivanostanin.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-28T18:25:48.000Z","updated_at":"2026-08-04T17:49:33.000Z","dependencies_parsed_at":null,"dependency_job_id":"6031d3d1-ddae-4e0e-8d15-4c552ebfc9a9","html_url":"https://github.com/ivanostanin/lucius-mcp","commit_stats":null,"previous_names":["ivanostanin/lucius-mcp"],"tags_count":35,"template":false,"template_full_name":null,"purl":"pkg:github/ivanostanin/lucius-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanostanin%2Flucius-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanostanin%2Flucius-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanostanin%2Flucius-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanostanin%2Flucius-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ivanostanin","download_url":"https://codeload.github.com/ivanostanin/lucius-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivanostanin%2Flucius-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36948032,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-08-22T15:14:58.755Z","status":"online","status_checked_at":"2026-08-28T02:00:06.244Z","response_time":114,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["allure","allure-testops","cli","fastmcp","mcp","mcp-server","model-context-protocol","test-management","testops","tms"],"created_at":"2026-01-30T11:28:50.768Z","updated_at":"2026-08-28T02:08:02.159Z","avatar_url":"https://github.com/ivanostanin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- mcp-name: io.github.ivanostanin/lucius-mcp --\u003e\n[![PyPI Version](https://img.shields.io/pypi/v/lucius-mcp)](https://pypi.org/project/lucius-mcp/)\n[![PyPI Python Version](https://img.shields.io/pypi/pyversions/lucius-mcp)](https://pypi.org/project/lucius-mcp/)\n![PyPI Downloads](https://img.shields.io/pypi/dw/lucius-mcp)\n[![GitHub License](https://img.shields.io/github/license/ivanostanin/lucius-mcp)](https://github.com/ivanostanin/lucius-mcp/blob/main/LICENSE)\n\n# Allure TestOps MCP Server\n\nLucius is a specialized Model Context Protocol (MCP) server for Allure TestOps, built with `FastMCP` and `Starlette`.\n\n## 🎯 Motivation\n\nAllure TestOps is a powerful tool with a huge API. When you're using an AI agent to manage your tests, it can easily get\nlost in the details or fail because of a small technical mistake.\n\nLucius makes this easier by giving your AI tools that are simple to use and hard to break:\n\n- **Clear Tools**: Every tool is designed for a specific task, like \"finding a test case\" or \"updating a launch\".\n- **Helpful Errors**: If an AI makes a mistake, Lucius doesn't just return a code—it provides an \"Agent Hint\" that\n  explains exactly what went wrong and how to fix it.\n- **Solid Foundation**: We follow a clean \"Thin Tool\" structure, meaning the logic is consistent and easy for both\n  humans and AI to follow.\n\n## 🛠️ Supported Tools\n\nSee the full reference in [Tool Reference](docs/tools.md).\n\n| Tool Category                  | Description                                                     | All Tools                                                                                                                                                                                                                                |\n|:-------------------------------|:----------------------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| **Test Case Mgmt**             | Full lifecycle for test documentation.                          | `create_test_case`, `update_test_case`, `delete_test_case`, `delete_archived_test_cases`, `get_test_case_details`, `get_test_case_custom_fields`                                                                                       |\n| **Automation Generation**      | Generate framework-specific code from existing test cases.      | `generate_test_code`                                                                                                                                                                                                                     |\n| **Search \u0026 Discovery**         | Advanced search and project metadata discovery.                 | `list_test_cases`, `search_test_cases`, `get_custom_fields`, `list_integrations`, `get_project`                                                                                                                                         |\n| **Shared Steps**               | Create and manage reusable step sequences.                      | `create_shared_step`, `list_shared_steps`, `update_shared_step`, `delete_shared_step`, `delete_archived_shared_steps`, `link_shared_step`, `unlink_shared_step`                                                                          |\n| **Test Layers**        | Manage test taxonomy and auto-mapping schemas.   | `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`                                         |\n| **Test Hierarchy**             | Organize suites and assign tests in tree paths.                 | `create_test_suite`, `list_test_suites`, `assign_test_cases_to_suite`, `delete_test_suite`                                                                                                                                               |\n| **Custom Fields**      | Project-level management of custom field values. | `list_custom_field_values`, `create_custom_field_value`, `update_custom_field_value`, `delete_custom_field_value`, `delete_unused_custom_fields`                                                                                         |\n| **Launch Management**          | Manage launches, result uploads, manual execution, reruns, and attachments. | `create_launch`, `list_launches`, `get_launch`, `list_launch_test_results`, `upload_test_results`, `rerun_test_results_manually`, `start_manual_test_session`, `submit_manual_test_results`, `add_test_result_attachment`, `add_test_step_attachment`         |\n| **Test Result Management**     | Inspect one exact TestOps result and its execution evidence. | `get_test_result` |\n| **Test Plans**                 | Manage test plans and their content.                            | `create_test_plan`, `update_test_plan`, `delete_test_plan`, `list_test_plans`, `manage_test_plan_content`                                                                                                                                |\n| **Defect Mgmt**                | Track defects, linkage, and automation rules.                   | `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` |\n\n## 🚀 Quick Start\n\n1. **Install uv**: `curl -LsSf https://astral.sh/uv/install.sh | sh`\n2. **Setup Credentials**: Create a `.env` file with the variables below, or save CLI auth with `lucius auth`.\n3. **Run Server**: `uv run start`\n\n### Basic `.env` for Quick Start\n\n| Variable | Description | Example |\n|:---------|:------------|:--------|\n| `ALLURE_ENDPOINT` | Allure TestOps base URL | `https://example.testops.cloud` |\n| `ALLURE_PROJECT_ID` | Default Allure project ID (optional for `get_project`; required by project-scoped tools) | `123` |\n| `ALLURE_API_TOKEN` | Allure API token | `\u003cyour_api_token\u003e` |\n| `MCP_MODE` | MCP transport mode for Lucius runtime | `stdio` |\n\n### 🔌 Claude Desktop Integration\n\nThe easiest way to use Lucius in Claude Desktop is via the `.mcpb` bundle:\n\n1. Download the latest `lucius-mcp.mcpb` from Releases.\n2. Open with Claude Desktop.\n3. Configure your Allure credentials in the UI.\n\n### 💻 Claude Code Integration\n\nTo add Lucius to Claude Code, use the following command from within your project directory:\n\n```bash\nclaude mcp add --transport stdio --scope project \\\n  --env ALLURE_ENDPOINT=https://example.testops.cloud \\\n  --env ALLURE_PROJECT_ID=123 \\\n  --env ALLURE_API_TOKEN=\u003cyour_api_token\u003e \\\n  --env MCP_MODE=stdio \\\n  testops-mcp -- uvx --from lucius-mcp --refresh start\n```\n\nProject-scoped text config example (`.mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"testops-mcp\": {\n      \"type\": \"stdio\",\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"lucius-mcp\",\n        \"--refresh\",\n        \"start\"\n      ],\n      \"env\": {\n        \"ALLURE_ENDPOINT\": \"https://example.testops.cloud\",\n        \"ALLURE_PROJECT_ID\": \"123\",\n        \"ALLURE_API_TOKEN\": \"\u003cyour_api_token\u003e\",\n        \"MCP_MODE\": \"stdio\"\n      }\n    }\n  }\n}\n```\n\n### 🧠 Codex Integration\n\nTo add Lucius to Codex (CLI or IDE extension), use:\n\n```bash\ncodex mcp add testops-mcp \\\n  --env ALLURE_ENDPOINT=https://example.testops.cloud \\\n  --env ALLURE_PROJECT_ID=123 \\\n  --env ALLURE_API_TOKEN=\u003cyour_api_token\u003e \\\n  --env MCP_MODE=stdio \\\n  -- uvx --from lucius-mcp --refresh start\n```\n\nText config example (`~/.codex/config.toml` or project `.codex/config.toml`):\n\n```toml\n[mcp_servers.testops-mcp]\ncommand = \"uvx\"\nargs = [\"--from\", \"lucius-mcp\", \"--refresh\", \"start\"]\n\n[mcp_servers.testops-mcp.env]\nALLURE_ENDPOINT = \"https://example.testops.cloud\"\nALLURE_PROJECT_ID = \"123\"\nALLURE_API_TOKEN = \"\u003cyour_api_token\u003e\"\nMCP_MODE = \"stdio\"\n```\n\nFor detailed setup, including Claude Desktop (MCPB) integration, see [Setup Guide](docs/setup.md).\n\n### 🐍 Supported Python versions\n\nLucius supports Python 3.10 through 3.14 for runtime use. The generated MCPB manifests and the representative Nuitka\nCLI compiler matrix validate the same range. Python 3.9 remains unsupported because the pinned `starlette==1.3.1`\nrequires Python 3.10 or newer; Python 3.15 is deferred because the current native dependency set does not build for it.\n\n### 💻 Command-Line Interface (CLI)\n\nLucius also provides a universal CLI entry point for direct tool execution from the command line:\n\n```bash\n# List available actions for an entity\nuv run lucius test_case\n\n# Execute an action\nuv run lucius test_case get --args '{\"test_case_id\": 1234}'\n\n# Show help for a specific entity/action\nuv run lucius test_case get --help\n\n# Save reusable CLI auth\nuv run lucius auth --url https://example.testops.cloud --token \u003cyour_api_token\u003e --project 123\nuv run lucius auth status\nuv run lucius auth clear\n```\n\n**CLI Features:**\n- 🎯 Type-safe entity/action invocation with validation\n- 🔐 Optional persistent CLI auth with native per-user config storage\n- 📊 Multiple output formats (JSON, table, csv, plain)\n- 🔍 Per-action help with parameters and examples\n- 🛡️ Clean error messages with guidance\n- 📦 Standalone binaries for Linux, macOS, and Windows\n\nCLI auth precedence is:\n\n1. Explicit tool args such as `api_token` or `project_id`\n2. Environment variables\n3. Saved CLI auth config from `uv run lucius auth`\n4. Defaults\n\nSaved CLI auth uses native config locations:\n\n- Linux/Unix: `$XDG_CONFIG_HOME/lucius/auth.json` or `~/.config/lucius/auth.json`\n- macOS: `~/Library/Application Support/lucius/auth.json` unless XDG overrides are explicitly set\n- Windows: `%LOCALAPPDATA%\\lucius\\auth.json`\n\nFor full CLI documentation and installation instructions, see [CLI Guide](docs/CLI.md).\n\n## 📡 Telemetry\n\nLucius collects privacy-preserving usage telemetry to improve tool quality. Telemetry is enabled by default and sends metadata\nto `https://stats.ostanin.me`, an endpoint operated by the project owner (no third party has access to this endpoint).\n\nIf this is acceptable in your environment, staying opted in helps improve Lucius over time. If you want to opt out, set\n`TELEMETRY_ENABLED=false` in your environment.\n\nNo API tokens, test content, or tool arguments are sent.\n\nSee [Telemetry \u0026 Privacy](docs/telemetry.md) for the full data dictionary and telemetry behavior details.\n\n## 📂 Documentation\n\nFull documentation is available in the [docs/](docs/index.md) folder:\n\n- [Architecture \u0026 Design](docs/architecture.md)\n- [Tool Reference](docs/tools.md)\n- [Configuration \u0026 Setup](docs/setup.md)\n- [Telemetry \u0026 Privacy](docs/telemetry.md)\n- [Development Guide](docs/development.md)\n- [AI Agent Protocol](docs/agent-documentation-protocol.md)\n\n## 🤝 Contributing\n\nContributions are welcome! Please see the [Contribution Guidelines](CONTRIBUTING.md) and\nthe [Development Guide](docs/development.md) for more details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivanostanin%2Flucius-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivanostanin%2Flucius-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivanostanin%2Flucius-mcp/lists"}