# iampopovich/allure-testops-mcp architecture

> Architecture diagram of the GitHub repository iampopovich/allure-testops-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/iampopovich/allure-testops-mcp
- Repository: https://github.com/iampopovich/allure-testops-mcp

## Overview

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.

Main entry points: [`src/server-bootstrap.ts`](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/server-bootstrap.ts) (Server bootstrap), [`src/client.ts`](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/client.ts) (API client), [`src/tools/utils.ts`](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/utils.ts) (Tool utils), [`tests/unit/tools`](https://github.com/iampopovich/allure-testops-mcp/tree/main/tests/unit/tools) (Unit tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_src_index["Entry<br/>bootstrap<br/>[index.ts]"]
  node_src_bootstrap["Server bootstrap<br/>mcp assembly"]
  node_src_auth["Auth<br/>token exchange<br/>[auth.ts]"]
  node_src_cache["Token cache<br/>in-memory cache<br/>[cache.ts]"]
  node_src_client["API client<br/>HTTP client<br/>[client.ts]"]
end

subgraph group_api["API Adapter"]
  node_api_test_cases["Test cases<br/>domain adapter<br/>[test-cases.ts]"]
  node_api_launches["Launches<br/>domain adapter<br/>[launches.ts]"]
  node_api_test_results["Test results<br/>domain adapter<br/>[test-results.ts]"]
  node_api_test_plans["Test plans<br/>domain adapter<br/>[test-plans.ts]"]
  node_api_defects["Defects<br/>domain adapter<br/>[defects.ts]"]
  node_api_dashboards["Dashboards<br/>domain adapter<br/>[dashboards.ts]"]
  node_api_environments["Environments<br/>domain adapter<br/>[environments.ts]"]
  node_api_shared_steps["Shared steps<br/>domain adapter<br/>[shared-steps.ts]"]
  node_api_analytic["Analytics<br/>domain adapter<br/>[analytic.ts]"]
end

subgraph group_tools["MCP Tools"]
  node_tools_utils["Tool utils<br/>shared helpers<br/>[utils.ts]"]
  node_tools_types["Tool types<br/>shared types<br/>[types.ts]"]
  node_tools_test_cases["Test case tools<br/>MCP tools<br/>[test-cases.ts]"]
  node_tools_launches["Launch tools<br/>MCP tools<br/>[launches.ts]"]
  node_tools_test_results["Result tools<br/>MCP tools<br/>[test-results.ts]"]
  node_tools_test_plans["Plan tools<br/>MCP tools<br/>[test-plans.ts]"]
  node_tools_defects["Defect tools<br/>MCP tools<br/>[defects.ts]"]
  node_tools_dashboards["Dashboard tools<br/>MCP tools<br/>[dashboards.ts]"]
  node_tools_environments["Env tools<br/>MCP tools<br/>[environments.ts]"]
  node_tools_shared_steps["Step tools<br/>MCP tools<br/>[shared-steps.ts]"]
  node_tools_analytic["Analytics tools<br/>MCP tools<br/>[analytic.ts]"]
end

subgraph group_resources["Resources"]
  node_resources_index["Resources<br/>[index.ts]"]
end

subgraph group_ops["Ops & Docs"]
  node_scripts_catalog["Catalog gen<br/>doc generator"]
  node_docs_tools["Tool catalog<br/>generated docs<br/>[tools.json]"]
end

subgraph group_tests["Tests"]
  node_tests_unit_tools["Unit tools<br/>unit tests"]
  node_tests_unit_cache["Cache unit<br/>unit test<br/>[cache.unit.test.ts]"]
  node_tests_integration["Integration"]
end

node_src_index -->|"boots"| node_src_bootstrap
node_src_bootstrap -->|"auth"| node_src_auth
node_src_bootstrap -->|"client"| node_src_client
node_src_auth -->|"caches"| node_src_cache
node_src_client -->|"reads token"| node_src_cache
node_src_bootstrap -->|"registers"| node_tools_test_cases
node_src_bootstrap -->|"registers"| node_tools_launches
node_src_bootstrap -->|"registers"| node_tools_test_results
node_src_bootstrap -->|"registers"| node_tools_test_plans
node_src_bootstrap -->|"registers"| node_tools_defects
node_src_bootstrap -->|"registers"| node_tools_dashboards
node_src_bootstrap -->|"registers"| node_tools_environments
node_src_bootstrap -->|"registers"| node_tools_shared_steps
node_src_bootstrap -->|"registers"| node_tools_analytic
node_src_bootstrap -->|"registers"| node_resources_index
node_tools_test_cases -->|"uses"| node_tools_utils
node_tools_launches -->|"uses"| node_tools_utils
node_tools_test_results -->|"uses"| node_tools_utils
node_tools_test_plans -->|"uses"| node_tools_utils
node_tools_defects -->|"uses"| node_tools_utils
node_tools_dashboards -->|"uses"| node_tools_utils
node_tools_environments -->|"uses"| node_tools_utils
node_tools_shared_steps -->|"uses"| node_tools_utils
node_tools_analytic -->|"uses"| node_tools_utils
node_tools_test_cases -->|"calls"| node_api_test_cases
node_tools_launches -->|"calls"| node_api_launches
node_tools_test_results -->|"calls"| node_api_test_results
node_tools_test_plans -->|"calls"| node_api_test_plans
node_tools_defects -->|"calls"| node_api_defects
node_tools_dashboards -->|"calls"| node_api_dashboards
node_tools_environments -->|"calls"| node_api_environments
node_tools_shared_steps -->|"calls"| node_api_shared_steps
node_tools_analytic -->|"calls"| node_api_analytic
node_api_test_cases -->|"uses"| node_src_client
node_api_launches -->|"uses"| node_src_client
node_api_test_results -->|"uses"| node_src_client
node_api_test_plans -->|"uses"| node_src_client
node_api_defects -->|"uses"| node_src_client
node_api_dashboards -->|"uses"| node_src_client
node_api_environments -->|"uses"| node_src_client
node_api_shared_steps -->|"uses"| node_src_client
node_api_analytic -->|"uses"| node_src_client
node_scripts_catalog -->|"generates"| node_docs_tools
node_tests_unit_tools -.->|"covers"| node_tools_test_cases
node_tests_unit_tools -.->|"covers"| node_tools_launches
node_tests_unit_tools -.->|"covers"| node_tools_test_plans
node_tests_unit_tools -.->|"covers"| node_tools_test_results
node_tests_unit_cache -.->|"covers"| node_src_cache

click node_src_index "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/index.ts"
click node_src_bootstrap "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/server-bootstrap.ts"
click node_src_auth "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/auth.ts"
click node_src_cache "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/cache.ts"
click node_src_client "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/client.ts"
click node_api_test_cases "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/test-cases.ts"
click node_api_launches "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/launches.ts"
click node_api_test_results "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/test-results.ts"
click node_api_test_plans "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/test-plans.ts"
click node_api_defects "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/defects.ts"
click node_api_dashboards "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/dashboards.ts"
click node_api_environments "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/environments.ts"
click node_api_shared_steps "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/shared-steps.ts"
click node_api_analytic "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/analytic.ts"
click node_tools_utils "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/utils.ts"
click node_tools_types "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/types.ts"
click node_tools_test_cases "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/test-cases.ts"
click node_tools_launches "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/launches.ts"
click node_tools_test_results "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/test-results.ts"
click node_tools_test_plans "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/test-plans.ts"
click node_tools_defects "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/defects.ts"
click node_tools_dashboards "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/dashboards.ts"
click node_tools_environments "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/environments.ts"
click node_tools_shared_steps "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/shared-steps.ts"
click node_tools_analytic "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/analytic.ts"
click node_resources_index "https://github.com/iampopovich/allure-testops-mcp/blob/main/src/resources/index.ts"
click node_scripts_catalog "https://github.com/iampopovich/allure-testops-mcp/blob/main/scripts/generate-tool-catalog.ts"
click node_docs_tools "https://github.com/iampopovich/allure-testops-mcp/blob/main/docs/tools.json"
click node_tests_unit_tools "https://github.com/iampopovich/allure-testops-mcp/tree/main/tests/unit/tools"
click node_tests_unit_cache "https://github.com/iampopovich/allure-testops-mcp/blob/main/tests/unit/cache.unit.test.ts"
click node_tests_integration "https://github.com/iampopovich/allure-testops-mcp/tree/main/tests/integration"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_src_index,node_src_bootstrap,node_src_auth,node_src_cache,node_src_client toneBlue
class node_api_test_cases,node_api_launches,node_api_test_results,node_api_test_plans,node_api_defects,node_api_dashboards,node_api_environments,node_api_shared_steps,node_api_analytic toneAmber
class node_tools_utils,node_tools_types,node_tools_test_cases,node_tools_launches,node_tools_test_results,node_tools_test_plans,node_tools_defects,node_tools_dashboards,node_tools_environments,node_tools_shared_steps,node_tools_analytic toneMint
class node_resources_index toneRose
class node_scripts_catalog,node_docs_tools toneIndigo
class node_tests_unit_tools,node_tests_unit_cache,node_tests_integration toneTeal
```

## Components

### Runtime

MCP server startup, config, auth, and transport boundary.

- [Entry](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/index.ts): bootstrap · Process entrypoint that starts the server. · `src/index.ts`
- [Server bootstrap](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/server-bootstrap.ts): mcp assembly · Assembles MCP server, registers tools/resources, and applies env config. · `src/server-bootstrap.ts`
- [Auth](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/auth.ts): token exchange · Exchanges Allure token for bearer JWT and manages auth flow. · `src/auth.ts`
- [Token cache](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/cache.ts): in-memory cache · Caches authentication tokens until near expiry. · `src/cache.ts`
- [API client](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/client.ts): HTTP client · Shared client used to talk to Allure TestOps APIs. · `src/client.ts`

### API Adapter

Domain adapters that translate MCP requests into Allure TestOps REST calls.

- [Test cases](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/test-cases.ts): domain adapter · REST adapter for test case operations. · `src/api/test-cases.ts`
- [Launches](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/launches.ts): domain adapter · REST adapter for launch operations. · `src/api/launches.ts`
- [Test results](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/test-results.ts): domain adapter · REST adapter for test result operations. · `src/api/test-results.ts`
- [Test plans](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/test-plans.ts): domain adapter · REST adapter for test plan operations. · `src/api/test-plans.ts`
- [Defects](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/defects.ts): domain adapter · REST adapter for defect operations. · `src/api/defects.ts`
- [Dashboards](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/dashboards.ts): domain adapter · REST adapter for dashboard operations. · `src/api/dashboards.ts`
- [Environments](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/environments.ts): domain adapter · REST adapter for environment operations. · `src/api/environments.ts`
- [Shared steps](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/shared-steps.ts): domain adapter · REST adapter for shared step operations. · `src/api/shared-steps.ts`
- [Analytics](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/api/analytic.ts): domain adapter · REST adapter for analytic endpoints. · `src/api/analytic.ts`

### MCP Tools

Client-facing tool handlers and shared tool utilities.

- [Tool utils](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/utils.ts): shared helpers · Common validation, formatting, and project resolution helpers. · `src/tools/utils.ts`
- [Tool types](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/types.ts): shared types · Shared type definitions for tool handlers. · `src/tools/types.ts`
- [Test case tools](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/test-cases.ts): MCP tools · Tool handlers for test case workflows. · `src/tools/test-cases.ts`
- [Launch tools](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/launches.ts): MCP tools · Tool handlers for launch workflows. · `src/tools/launches.ts`
- [Result tools](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/test-results.ts): MCP tools · Tool handlers for test result workflows. · `src/tools/test-results.ts`
- [Plan tools](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/test-plans.ts): MCP tools · Tool handlers for test plan workflows. · `src/tools/test-plans.ts`
- [Defect tools](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/defects.ts): MCP tools · Tool handlers for defect workflows. · `src/tools/defects.ts`
- [Dashboard tools](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/dashboards.ts): MCP tools · Tool handlers for dashboard workflows. · `src/tools/dashboards.ts`
- [Env tools](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/environments.ts): MCP tools · Tool handlers for environment workflows. · `src/tools/environments.ts`
- [Step tools](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/shared-steps.ts): MCP tools · Tool handlers for shared step workflows. · `src/tools/shared-steps.ts`
- [Analytics tools](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/tools/analytic.ts): MCP tools · Tool handlers for analytic workflows. · `src/tools/analytic.ts`

### Resources

Read-only MCP resource surface.

- [Resources](https://github.com/iampopovich/allure-testops-mcp/blob/main/src/resources/index.ts): MCP resources · Read-only resource registry for MCP clients. · `src/resources/index.ts`

### Ops & Docs

Packaging, publishing, and generated catalog artifacts.

- [Catalog gen](https://github.com/iampopovich/allure-testops-mcp/blob/main/scripts/generate-tool-catalog.ts): doc generator · Generates the published tool catalog JSON. · `scripts/generate-tool-catalog.ts`
- [Tool catalog](https://github.com/iampopovich/allure-testops-mcp/blob/main/docs/tools.json): generated docs · Static catalog of exposed tools for discovery. · `docs/tools.json`

### Tests

Unit and integration coverage.

- [Unit tools](https://github.com/iampopovich/allure-testops-mcp/tree/main/tests/unit/tools): unit tests · Unit coverage for tool behavior and utilities. · `tests/unit/tools`
- [Cache unit](https://github.com/iampopovich/allure-testops-mcp/blob/main/tests/unit/cache.unit.test.ts): unit test · Unit coverage for token cache behavior. · `tests/unit/cache.unit.test.ts`
- [Integration](https://github.com/iampopovich/allure-testops-mcp/tree/main/tests/integration): integration tests · Live Allure TestOps interaction tests. · `tests/integration`

## Connections

- Entry → Server bootstrap: boots · Entrypoint starts the assembled server.
- Server bootstrap → Auth: auth · Bootstrap wires auth configuration and token flow.
- Server bootstrap → API client: client · Bootstrap constructs the shared API client.
- Auth → Token cache: caches · Auth stores bearer tokens in memory.
- API client → Token cache: reads token · Client uses cached authentication state.
- Server bootstrap → Test case tools: registers · Server exposes test case tools.
- Server bootstrap → Launch tools: registers · Server exposes launch tools.
- Server bootstrap → Result tools: registers · Server exposes test result tools.
- Server bootstrap → Plan tools: registers · Server exposes test plan tools.
- Server bootstrap → Defect tools: registers · Server exposes defect tools.
- Server bootstrap → Dashboard tools: registers · Server exposes dashboard tools.
- Server bootstrap → Env tools: registers · Server exposes environment tools.
- Server bootstrap → Step tools: registers · Server exposes shared step tools.
- Server bootstrap → Analytics tools: registers · Server exposes analytics tools.
- Server bootstrap → Resources: registers · Server exposes MCP resources.
- Test case tools → Tool utils: uses · Tool handlers share validation and project resolution.
- Launch tools → Tool utils: uses · Tool handlers share validation and project resolution.
- Result tools → Tool utils: uses · Tool handlers share validation and project resolution.
- Plan tools → Tool utils: uses · Tool handlers share validation and project resolution.
- Defect tools → Tool utils: uses · Tool handlers share validation and project resolution.
- Dashboard tools → Tool utils: uses · Tool handlers share validation and project resolution.
- Env tools → Tool utils: uses · Tool handlers share validation and project resolution.
- Step tools → Tool utils: uses · Tool handlers share validation and project resolution.
- Analytics tools → Tool utils: uses · Tool handlers share validation and project resolution.
- Test case tools → Test cases: calls · MCP tool requests are translated to API operations.
- Launch tools → Launches: calls · MCP tool requests are translated to API operations.
- Result tools → Test results: calls · MCP tool requests are translated to API operations.
- Plan tools → Test plans: calls · MCP tool requests are translated to API operations.
- Defect tools → Defects: calls · MCP tool requests are translated to API operations.
- Dashboard tools → Dashboards: calls · MCP tool requests are translated to API operations.
- Env tools → Environments: calls · MCP tool requests are translated to API operations.
- Step tools → Shared steps: calls · MCP tool requests are translated to API operations.
- Analytics tools → Analytics: calls · MCP tool requests are translated to API operations.
- Test cases → API client: uses · API adapters use the shared HTTP client.
- Launches → API client: uses · API adapters use the shared HTTP client.
- Test results → API client: uses · API adapters use the shared HTTP client.
- Test plans → API client: uses · API adapters use the shared HTTP client.
- Defects → API client: uses · API adapters use the shared HTTP client.
- Dashboards → API client: uses · API adapters use the shared HTTP client.
- Environments → API client: uses · API adapters use the shared HTTP client.
- Shared steps → API client: uses · API adapters use the shared HTTP client.
- Analytics → API client: uses · API adapters use the shared HTTP client.
- Catalog gen → Tool catalog: generates · Script emits the published tool catalog.
- Unit tools → Test case tools: covers · Unit tests exercise tool handlers.
- Unit tools → Launch tools: covers · Unit tests exercise tool handlers.
- Unit tools → Plan tools: covers · Unit tests exercise tool handlers.
- Unit tools → Result tools: covers · Unit tests exercise tool handlers.
- Cache unit → Token cache: covers · Unit tests exercise token cache behavior.