iampopovich/allure-testops-mcp

1. This repo is a TypeScript/Node.js MCP server that sits between an MCP client and an Allure TestOps instance. The architectural boundary is clear: the server exposes MCP tools/resources over stdio, and all business operations are translated into Allure TestOps REST API calls.

2. The main runtime entrypoint is src/index.ts, which boots the server via src/server-bootstrap.ts. That bootstrap layer is where the MCP server is assembled: tools are registered, resources are exposed, and environment-driven configuration is applied.

3. Configuration and authentication are handled centrally in src/auth.ts, src/cache.ts, and src/client.ts. The server reads ALLURE_TESTOPS_URL, ALLURE_TOKEN, and optional ALLURE_PROJECT_ID, then exchanges the user token for a bearer JWT at the Allure auth endpoint and caches it in memory until near expiry.

4. The external system dependency is Allure TestOps itself. The repo does not persist its own business data; instead, it proxies operations to Allure TestOps APIs such as launches, test cases, test results, test plans, dashboards, defects, mutes, members, shared steps, and environments. That means state lives primarily in the upstream TestOps backend.

5. The src/api/ directory is the HTTP/domain adapter layer. Each file groups REST calls by domain (test-cases, launches, test-results, test-plans, defects, dashboards, environments, shared-steps, analytic). This is the boundary where request shaping, response normalization, and project-scoped URL logic live.

6. The src/tools/ directory is the MCP-facing application layer. Each domain file mirrors the API layer but exposes user actions as MCP tools. These handlers are the main orchestration point: they validate input, resolve project scope, call the API layer, and format results for the MCP client.

7. Project scoping is a recurring architectural concern. Some operations can use a default project from ALLURE_PROJECT_ID, while others require an explicit projectId or a projectName lookup. That project-resolution behavior is part of the server’s request flow, not a separate service.

8. src/resources/ defines MCP resources separate from tools. This is the read-only/catalog side of the server, complementing the action-oriented tool layer. The presence of a resource index suggests some shared metadata or discoverability surface for clients.

9. The repo also includes a generation path for a public tool catalog. scripts/generate-tool-catalog.ts produces docs/tools.json, and the GitHub Pages workflow publishes the static catalog under docs/. This is documentation infrastructure, but it is directly tied to the source-defined tool surface.

10. Operationally, the server is designed for multiple deployment modes: local npx, compiled node execution, Docker, and CI/CD publishing. The README and docker-compose.yml indicate that stdio transport is the intended client integration model rather than an HTTP API server.

11. Testing is split between unit and integration layers. Unit tests focus on tool behavior and shared helpers under tests/unit/, while tests/integration/ exercises live Allure TestOps interactions. That split reflects the core risk in this repo: correctness of API translation and auth/token reuse.

12. Overall dependency direction is one-way: MCP client → server bootstrap → tool handlers → API adapters → Allure TestOps. Cross-cutting concerns like auth caching, project resolution, and shared tool utilities are centralized so the domain tool files stay thin and consistent.