https://github.com/ivanostanin/lucius-mcp
A feature-rich Model Context Protocol (MCP) server and CLI for Allure TestOps TMS.
https://github.com/ivanostanin/lucius-mcp
allure allure-testops fastmcp mcp mcp-server model-context-protocol test-management testops tms
Last synced: 16 days ago
JSON representation
A feature-rich Model Context Protocol (MCP) server and CLI for Allure TestOps TMS.
- Host: GitHub
- URL: https://github.com/ivanostanin/lucius-mcp
- Owner: ivanostanin
- License: apache-2.0
- Created: 2026-01-28T18:25:48.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-05-26T10:18:04.000Z (21 days ago)
- Last Synced: 2026-05-26T11:18:19.964Z (21 days ago)
- Topics: allure, allure-testops, fastmcp, mcp, mcp-server, model-context-protocol, test-management, testops, tms
- Language: Python
- Homepage: https://ivanostanin.github.io/lucius-mcp/
- Size: 2.14 MB
- Stars: 6
- Watchers: 1
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Security: SECURITY.md
Awesome Lists containing this project
README
# Allure TestOps MCP Server
Lucius is a specialized Model Context Protocol (MCP) server for Allure TestOps, built with `FastMCP` and `Starlette`.
## 🎯 Motivation
Allure TestOps is a powerful tool with a huge API. When you're using an AI agent to manage your tests, it can easily get
lost in the details or fail because of a small technical mistake.
Lucius makes this easier by giving your AI tools that are simple to use and hard to break:
- **Clear Tools**: Every tool is designed for a specific task, like "finding a test case" or "updating a launch".
- **Helpful Errors**: If an AI makes a mistake, Lucius doesn't just return a code—it provides an "Agent Hint" that
explains exactly what went wrong and how to fix it.
- **Solid Foundation**: We follow a clean "Thin Tool" structure, meaning the logic is consistent and easy for both
humans and AI to follow.
## 🛠️ Supported Tools
| Tool Category | Description | All Tools |
|:-----------------------|:-------------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **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`, `list_test_cases`, `get_test_case_custom_fields` |
| **Search & Discovery** | Advanced search and project metadata discovery. | `search_test_cases`, `get_custom_fields`, `list_integrations` |
| **Shared Steps** | Create and manage reusable sequence sequences. | `create_shared_step`, `list_shared_steps`, `update_shared_step`, `delete_shared_step`, `delete_archived_shared_steps`, `link_shared_step`, `unlink_shared_step` |
| **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` |
| **Test Hierarchy** | Organize suites and assign tests in tree paths. | `create_test_suite`, `list_test_suites`, `assign_test_cases_to_suite`, `delete_test_suite` |
| **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` |
| **Test Plans** | Manage Test Plans and their content. | `create_test_plan`, `update_test_plan`, `delete_test_plan`, `list_test_plans`, `manage_test_plan_content` |
| **Defect Mgmt** | Track defects, linkage, and automation rules. | `create_defect`, `get_defect`, `update_defect`, `delete_defect`, `list_defects`, `link_defect_to_test_case`, `list_defect_test_cases`, `create_defect_matcher`, `list_defect_matchers`, `update_defect_matcher`, `delete_defect_matcher` |
## 🚀 Quick Start
1. **Install uv**: `curl -LsSf https://astral.sh/uv/install.sh | sh`
2. **Setup Credentials**: Create a `.env` file with the variables below, or save CLI auth with `lucius auth`.
3. **Run Server**: `uv run start`
### Basic `.env` for Quick Start
| Variable | Description | Example |
|:---------|:------------|:--------|
| `ALLURE_ENDPOINT` | Allure TestOps base URL | `https://example.testops.cloud` |
| `ALLURE_PROJECT_ID` | Default Allure project ID | `123` |
| `ALLURE_API_TOKEN` | Allure API token | `` |
| `MCP_MODE` | MCP transport mode for Lucius runtime | `stdio` |
### 🔌 Claude Desktop Integration
The easiest way to use Lucius in Claude Desktop is via the `.mcpb` bundle:
1. Download the latest `lucius-mcp.mcpb` from Releases.
2. Open with Claude Desktop.
3. Configure your Allure credentials in the UI.
### 💻 Claude Code Integration
To add Lucius to Claude Code, use the following command from within your project directory:
```bash
claude mcp add --transport stdio --scope project \
--env ALLURE_ENDPOINT=https://example.testops.cloud \
--env ALLURE_PROJECT_ID=123 \
--env ALLURE_API_TOKEN= \
--env MCP_MODE=stdio \
testops-mcp -- uvx --from lucius-mcp --refresh start
```
Project-scoped text config example (`.mcp.json`):
```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": "",
"MCP_MODE": "stdio"
}
}
}
}
```
### 🧠 Codex Integration
To add Lucius to Codex (CLI or IDE extension), use:
```bash
codex mcp add testops-mcp \
--env ALLURE_ENDPOINT=https://example.testops.cloud \
--env ALLURE_PROJECT_ID=123 \
--env ALLURE_API_TOKEN= \
--env MCP_MODE=stdio \
-- uvx --from lucius-mcp --refresh start
```
Text config example (`~/.codex/config.toml` or project `.codex/config.toml`):
```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 = ""
MCP_MODE = "stdio"
```
For detailed setup, including Claude Desktop (MCPB) integration, see [Setup Guide](docs/setup.md).
### 💻 Command-Line Interface (CLI)
Lucius also provides a universal CLI entry point for direct tool execution from the command line:
```bash
# 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 --project 123
uv run lucius auth status
uv run lucius auth clear
```
**CLI Features:**
- 🎯 Type-safe entity/action invocation with validation
- 🔐 Optional persistent CLI auth with native per-user config storage
- 📊 Multiple output formats (JSON, table, csv, plain)
- 🔍 Per-action help with parameters and examples
- 🛡️ Clean error messages with guidance
- 📦 Standalone binaries for Linux, macOS, and Windows
For local CLI binary builds with Nuitka, use Python 3.13 (the build scripts and CI workflow enforce this).
CLI auth precedence is:
1. Explicit tool args such as `api_token` or `project_id`
2. Environment variables
3. Saved CLI auth config from `uv run lucius auth`
4. Defaults
Saved CLI auth uses native config locations:
- Linux/Unix: `$XDG_CONFIG_HOME/lucius/auth.json` or `~/.config/lucius/auth.json`
- macOS: `~/Library/Application Support/lucius/auth.json` unless XDG overrides are explicitly set
- Windows: `%LOCALAPPDATA%\lucius\auth.json`
For full CLI documentation and installation instructions, see [CLI Guide](docs/CLI.md).
## 📡 Telemetry
Lucius collects privacy-preserving usage telemetry to improve tool quality. Telemetry is enabled by default and sends metadata
to `https://stats.ostanin.me`, an endpoint operated by the project owner (no third party has access to this endpoint).
If this is acceptable in your environment, staying opted in helps improve Lucius over time. If you want to opt out, set
`TELEMETRY_ENABLED=false` in your environment.
No API tokens, test content, or tool arguments are sent.
See [Telemetry & Privacy](docs/telemetry.md) for the full data dictionary and telemetry behavior details.
## 📂 Documentation
Full documentation is available in the [docs/](docs/index.md) folder:
- [Architecture & Design](docs/architecture.md)
- [Tool Reference](docs/tools.md)
- [Configuration & Setup](docs/setup.md)
- [Telemetry & Privacy](docs/telemetry.md)
- [Development Guide](docs/development.md)
- [AI Agent Protocol](docs/agent-documentation-protocol.md)
## 🤝 Contributing
Contributions are welcome! Please see the [Contribution Guidelines](CONTRIBUTING.md) and
the [Development Guide](docs/development.md) for more details.