Add Model Context Protocol (MCP) server for Allure Docker Service

[matanbaruch]

Summary

Adds a Model Context Protocol (MCP) server (allure-docker-mcp/) that exposes a running allure-docker-service instance as tools an LLM agent can call — from Claude Desktop, Claude Code, or any MCP host. It lets an assistant manage projects, send results, and generate/export Allure reports through natural language, e.g.:

"Create a project regression-suite, send the results from ./allure-results, generate a report, and give me the URL."

The server is a client of the existing REST API — it does not modify the service.

Closes #291

What's included

• 16 tools, one per REST endpoint: get_version, get_config, list_projects, get_project, search_projects, create_project, delete_project, send_results, send_results_from_directory, generate_report, get_latest_report, clean_results, clean_history, export_report, export_emailable_report, render_emailable_report.
• Security mode support: JWT-cookie login + X-CSRF-TOKEN on mutating requests, with a single 401 re-auth retry.
• stdio, streamable-http, and sse transports; Dockerfile; pyproject.toml; .env.example.
• Unit tests (respx-mocked) and a README with client-config examples.

Design / hardening notes

A few items came out of review + testing against a real instance:

• Export confinement — export_* tools write only inside ALLURE_OUTPUT_DIR and reject path escapes (no arbitrary-file overwrite from an agent-chosen path).
• Symlinks skipped in send_results_from_directory so it can't be pointed at a symlink resolving outside the directory.
• Non-blocking tools — tool bodies run off the event loop (anyio.to_thread) so the HTTP transports stay responsive; client auth is lock-guarded for concurrent callers.
• HTTP bind fix — main() applies FASTMCP_HOST/FASTMCP_PORT to the live settings (FastMCP otherwise ignores them, so streamable-http never bound the requested port). Verified the server now binds the requested host/port.
• Clear endpoint errors — if ALLURE_ENDPOINT points at the web UI instead of the API base, tools return an actionable error instead of opaque HTML.

Testing

• pytest — 24 tests pass (client auth/CSRF/401-retry, endpoint mapping, path confinement, symlink skip, transport config).
• Live integration against frankescobar/allure-docker-service (v2.38.1), driven through the real MCP tool dispatch:
  • non-secure: full lifecycle create → send → generate → latest-report → export → delete.
  • security mode (SECURITY_ENABLED=1): same lifecycle, exercising login + CSRF.
  • export confinement rejecting an out-of-root path; streamable-http real bind test on a non-default port.

Notes for maintainers

• Scoped entirely to a new allure-docker-mcp/ directory; no changes to allure-docker-api or the image.
• Requires Python 3.10+. Apache-2.0, same as the project.
• The HTTP transports are unauthenticated (documented in the package README) — intended to run locally or behind an authenticating proxy; stdio has no network surface.

🤖 Generated with Claude Code