lucius-mcp 0.2.2__tar.gz → 0.4.0__tar.gz

lucius_mcp-0.4.0/.github/workflows/_python_check.yml

@@ -0,0 +1,46 @@
+name: Python Quality Check
+
+on:
+  workflow_call:
+    inputs:
+      python-version:
+        description: 'Python version to use'
+        type: string
+        default: '3.14'
+      run-lint:
+        description: 'Whether to run Ruff linting'
+        type: boolean
+        default: true
+      run-typecheck:
+        description: 'Whether to run Mypy type checking'
+        type: boolean
+        default: true
+      run-tests:
+        description: 'Whether to run unit and integration tests'
+        type: boolean
+        default: true
+
+jobs:
+  python-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python Environment
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: ${{ inputs.python-version }}
+
+      - name: Run ruff linting
+        if: ${{ inputs.run-lint }}
+        run: uv run ruff check .
+
+      - name: Run mypy type checking
+        if: ${{ inputs.run-typecheck }}
+        run: uv run mypy src
+
+      - name: Run unit and integration tests
+        if: ${{ inputs.run-tests }}
+        run: |
+          echo "CI=true" > .env.test
+          uv run --env-file .env.test pytest tests/unit/ tests/integration/ tests/docs/ -v

lucius_mcp-0.4.0/.github/workflows/e2e-tests.yml

@@ -0,0 +1,46 @@
+name: E2E Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  e2e:
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || vars.ALLURE_ENDPOINT != ''
+    
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python Environment
+        uses: ./.github/actions/python-setup
+        with:
+          python-version: '3.14'
+      
+      - name: Install Allure Commandline
+        run: |
+          sudo apt-get update && sudo apt-get install -y default-jre
+          wget https://github.com/allure-framework/allure2/releases/download/2.36.0/allure-2.36.0.tgz
+          tar -zxvf allure-2.36.0.tgz
+          sudo ln -s $(pwd)/allure-2.36.0/bin/allure /usr/bin/allure
+      
+      - name: Run E2E tests
+        env:
+          ALLURE_ENDPOINT: ${{ vars.ALLURE_ENDPOINT }}
+          ALLURE_API_TOKEN: ${{ secrets.ALLURE_API_TOKEN }}
+          ALLURE_PROJECT_ID: ${{ vars.ALLURE_PROJECT_ID }}
+        run: uv run pytest tests/e2e/ -n auto --dist loadfile -v --tb=short --alluredir=allure-results
+      
+      - name: Generate Allure Report
+        if: always()
+        run: |
+          allure generate allure-results -o reports/allure-report --clean
+      
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: e2e-test-results
+          path: reports/allure-report/

lucius_mcp-0.4.0/.github/workflows/release.yml

@@ -0,0 +1,124 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  validate-version:
+    runs-on: ubuntu-latest
+    outputs:
+      version: ${{ steps.get_version.outputs.tag_version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for all branches and tags
+
+      - name: Verify tag is on main branch
+        run: |
+          # Check if the tagged commit is reachable from main
+          if ! git merge-base --is-ancestor ${{ github.sha }} origin/main; then
+            echo "ERROR: Tag must point to a commit on the main branch"
+            exit 1
+          fi
+
+      - name: Extract version from tag
+        id: get_version
+        run: |
+          TAG_VERSION=${GITHUB_REF#refs/tags/v}
+          echo "tag_version=$TAG_VERSION" >> $GITHUB_OUTPUT
+      
+      - name: Validate version matches pyproject.toml
+        run: |
+          PROJECT_VERSION=$(grep '^version = ' pyproject.toml | sed 's/version = "\(.*\)"/\1/')
+          TAG_VERSION=${{ steps.get_version.outputs.tag_version }}
+          
+          if [ "$PROJECT_VERSION" != "$TAG_VERSION" ]; then
+            echo "ERROR: Version mismatch!"
+            echo "Tag version: $TAG_VERSION"
+            echo "pyproject.toml version: $PROJECT_VERSION"
+            exit 1
+          fi
+
+  python-quality:
+    needs: validate-version
+    uses: ./.github/workflows/_python_check.yml
+    with:
+      python-version: '3.14'
+
+  mcpb-build:
+    needs: [validate-version, python-quality]
+    permissions:
+      contents: read
+      packages: write
+    uses: ./.github/workflows/_mcpb_build.yml
+    with:
+      version: ${{ needs.validate-version.outputs.version }}
+      artifact-name: mcpb-bundle-${{ needs.validate-version.outputs.version }}
+
+  docker-build:
+    needs: [python-quality, validate-version]
+    permissions:
+      contents: read
+      packages: write
+    uses: ./.github/workflows/_docker_build_push.yml
+    with:
+      image-name: lucius-mcp
+      tags: |
+        ${{ needs.validate-version.outputs.version }}
+        latest
+      labels: |
+        org.opencontainers.image.source=https://github.com/${{ github.repository }}
+        org.opencontainers.image.description=Release ${{ needs.validate-version.outputs.version }}
+      push: true
+
+  github-release:
+    needs: [validate-version, mcpb-build]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: mcpb-bundle-${{ needs.validate-version.outputs.version }}
+          path: dist/
+
+      - name: Get Changelog Entry
+        id: changelog_reader
+        uses: mindsers/changelog-reader-action@v2
+        with:
+          version: ${{ github.ref_name }}
+          path: ./CHANGELOG.md
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          body: ${{ steps.changelog_reader.outputs.changes }}
+          files: dist/*.mcpb
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+
+  pypi-publish:
+    needs: python-quality
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python Environment
+        uses: ./.github/actions/python-setup
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

lucius_mcp-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-format
+        name: ruff-format
+        entry: uv run ruff format .
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: ruff-check
+        name: ruff-check
+        entry: uv run ruff check --fix .
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: mypy
+        name: mypy
+        entry: uv run mypy src
+        language: system
+        types: [python]
+        pass_filenames: false
+
+      - id: pytest
+        name: pytest
+        entry: uv run pytest tests/unit tests/integration tests/docs tests/packaging
+        language: system
+        types: [python]
+        pass_filenames: false
+        stages: [pre-push]

lucius_mcp-0.4.0/CHANGELOG.md

@@ -0,0 +1,67 @@
+# Changelog
+
+## [Unreleased]
+
+## [v0.4.0] - 2026-02-06
+
+### Added
+- CRUD support for project-level custom field values (#18).
+- Issue linking and unlinking support for test cases (Story 3-12) (#17).
+- Integration filtering by project for issue linking (#22).
+- Support for test case steps with explicit expected results (#13).
+- `get_launch` tool to retrieve detailed execution statistics (#12).
+- Verification instructions for MCP tools (#11).
+
+### Changed
+- Mandatory confirmation and safety warnings for destructive tools (#23).
+- Support for test layers by name in `update_test_case` (#15).
+- Release pipeline restricted to the `main` branch (#10).
+- Standardized specification cleanup (#19).
+
+### Fixed
+- Idempotent deletion messages for better feedback (#16).
+- Logic for unlinking shared steps from test cases (#20).
+- Exposure of the `get_launch` tool on the MCP server (#21).
+
+## [v0.3.0] - 2026-02-03
+
+### Added
+- Launch management tools, including create and list launch operations.
+- New tool entries in manifests for expanded tool coverage.
+- Test layer support across test case CRUD and related tools.
+
+### Changed
+- Search test cases documentation and tests refined.
+- E2E test execution supports parallel mode.
+
+### Fixed
+- Custom fields handling in test case operations.
+- Test layer handling in tools and update_test_case support.
+- Tag casing is preserved in search_test_cases results.
+
+## [v0.2.2] - 2026-01-30
+
+### Fixed
+- Docker image build.
+
+## [v0.2.1] - 2026-01-30
+
+### Fixed
+- Deployment workflows: release description now includes the changelog, and PyPI publishing steps are corrected.
+
+## [v0.2.0]
+
+### Added
+- `get_custom_fields` tool to fetch custom fields and their allowed values (Story 3.6).
+- New example payloads for the `create_test_case` tool to guide usage.
+- Client generation for project and custom field controllers.
+- Initial `CHANGELOG.md` and `LICENSE` documentation.
+
+### Changed
+- Default run mode changed to `stdio` for easier integration with MCP clients.
+- Improved guidance for `create_test_case` tool, providing extended hints when non-existing custom fields are used (Story 3.5).
+- Updated package metadata and versions.
+
+## [v0.1.0]
+
+- Initial release

lucius_mcp-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,24 @@
+# Contributing to Lucius MCP
+
+Thank you for your interest in contributing to Lucius MCP for Allure TestOps!
+
+## 🚀 How to Contribute
+
+1. **Fork the repository** and create your branch from `main`.
+2. **Review the architecture**: Familiarize yourself with the "Thin Tool / Fat Service" pattern
+   in [docs/architecture.md](docs/architecture.md).
+3. **Set up your environment**: Follow the [Setup Guide](docs/setup.md).
+4. **Follow the Development Guide**: Use the instructions in [docs/development.md](docs/development.md) to add tools or
+   services.
+5. **Ensure quality**: Run linting, type checks, and tests before submitting a PR.
+6. **Submit a Pull Request**: Provide a clear description of your changes and reference any relevant issues or stories.
+
+## 📝 Documentation
+
+Remember to update the documentation in the `docs/` folder according to
+the [AI Agent Documentation Protocol](docs/agent-documentation-protocol.md) if you introduce any new features or
+changes.
+
+## ⚖️ License
+
+By contributing, you agree that your contributions will be licensed under the project's [LICENSE](LICENSE).

lucius_mcp-0.4.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.4
+Name: lucius-mcp
+Version: 0.4.0
+Summary: Allure TestOps MCP Server
+Project-URL: Homepage, https://github.com/ivanostanin/lucius-mcp
+Project-URL: Documentation, https://github.com/ivanostanin/lucius-mcp#readme
+Project-URL: Repository, https://github.com/ivanostanin/lucius-mcp.git
+Project-URL: Issues, https://github.com/ivanostanin/lucius-mcp/issues
+Project-URL: Changelog, https://github.com/ivanostanin/lucius-mcp/blob/main/CHANGELOG.md
+Project-URL: Releases, https://github.com/ivanostanin/lucius-mcp/releases
+Author-email: Ivan Ostanin <ivan@ostanin.me>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: allure,allure-testops,fastmcp,mcp,mcp-server,model-context-protocol,testops
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Quality Assurance
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: fastmcp>=2.14.4
+Requires-Dist: httpx>=0.28.1
+Requires-Dist: pydantic-settings>=2.12.0
+Requires-Dist: pydantic>=2.12.5
+Requires-Dist: python-dateutil>=2.9.0.post0
+Requires-Dist: python-json-logger>=2.0.7
+Requires-Dist: rich>=13.7.0
+Requires-Dist: starlette==0.52.1
+Requires-Dist: uvicorn>=0.40.0
+Requires-Dist: wsproto>=1.3.2
+Provides-Extra: dev
+Requires-Dist: allure-pytest>=2.15.3; extra == 'dev'
+Requires-Dist: faker>=40.1.2; extra == 'dev'
+Requires-Dist: mypy>=1.19.1; extra == 'dev'
+Requires-Dist: openapi-generator-cli>=7.19.0; extra == 'dev'
+Requires-Dist: pre-commit>=4.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
+Requires-Dist: pytest-xdist>=3.8.0; extra == 'dev'
+Requires-Dist: pytest>=9.0.2; extra == 'dev'
+Requires-Dist: respx>=0.22.0; extra == 'dev'
+Requires-Dist: ruff>=0.14.14; extra == 'dev'
+Requires-Dist: twine>=6.2.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Lucius MCP Server
+
+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`, `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`, `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` |
+| **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`                                                                                |
+| **Launch Mgmt**        | Execution tracking and launch statistics.        | `create_launch`, `get_launch`, `list_launches`                                                                                                                                                   |
+
+## 🚀 Quick Start
+
+1. **Install uv**: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+2. **Setup Credentials**: Create a `.env` file with `ALLURE_ENDPOINT`, `ALLURE_PROJECT_ID`, and `ALLURE_API_TOKEN`.
+3. **Run Server**: `uv run start`
+
+### 🔌 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 testops-mcp --transport stdio \
+   --env ALLURE_ENDPOINT=https://example.testops.cloud\
+   --env ALLURE_PROJECT_ID=123 \
+   --env ALLURE_API_TOKEN=your_token \
+   --env MCP_MODE=stdio \
+   -- uvx --from lucius-mcp --refresh start
+```
+
+For detailed setup, including Claude Desktop (MCPB) integration, see [Setup Guide](docs/setup.md).
+
+## 📂 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)
+- [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.

lucius_mcp-0.4.0/README.md

@@ -0,0 +1,71 @@
+# Lucius MCP Server
+
+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`, `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`, `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` |
+| **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`                                                                                |
+| **Launch Mgmt**        | Execution tracking and launch statistics.        | `create_launch`, `get_launch`, `list_launches`                                                                                                                                                   |
+
+## 🚀 Quick Start
+
+1. **Install uv**: `curl -LsSf https://astral.sh/uv/install.sh | sh`
+2. **Setup Credentials**: Create a `.env` file with `ALLURE_ENDPOINT`, `ALLURE_PROJECT_ID`, and `ALLURE_API_TOKEN`.
+3. **Run Server**: `uv run start`
+
+### 🔌 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 testops-mcp --transport stdio \
+   --env ALLURE_ENDPOINT=https://example.testops.cloud\
+   --env ALLURE_PROJECT_ID=123 \
+   --env ALLURE_API_TOKEN=your_token \
+   --env MCP_MODE=stdio \
+   -- uvx --from lucius-mcp --refresh start
+```
+
+For detailed setup, including Claude Desktop (MCPB) integration, see [Setup Guide](docs/setup.md).
+
+## 📂 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)
+- [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.