# jhonattang/mcp-qa architecture

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

- Interactive diagram: https://gitdiagram.com/jhonattang/mcp-qa
- Repository: https://github.com/jhonattang/mcp-qa

## Overview

1. **What this repository is**
   - `mcp-qa` is a Python 3.12 automation agent for QA workflows.
   - Its core shape is: a **CLI front end**, a **LangGraph-based orchestrator**, several **MCP tool servers**, and a few **local support services** like Redis and optional Ollama.

2. **Primary control flow**
   - The user starts in `src/console`.
   - The console sends a request into `src/orchestrator`, which runs a stateful pipeline.
   - The orchestrator coordinates LLM calls, cache lookup, MCP tool invocations, and final report delivery.

3. **Orchestration layer**
   - `src/orchestrator/graph.py` defines the main workflow as a state machine.
   - The pipeline is split into four major stages: story extraction, Jira creation, API test execution, and report upload.
   - `src/orchestrator/nodes/` holds the stage-specific actions, while `src/orchestrator/state.py` defines the shared state passed through the graph.

4. **LLM and caching boundary**
   - `src/llm/factory.py` abstracts model selection between local and cloud LLM backends.
   - `src/cache/cag_manager.py` provides the cache layer used to reduce repeated reasoning and token usage.
   - From an architecture perspective, this is the intelligence layer: it sits between the orchestrator and the external tools.

5. **MCP server boundary**
   - All external integrations are isolated under `mcp_servers/`.
   - Each subfolder is a separate MCP server with its own `server.py`, `tools.py`, and usually its own `config.json` and dependencies.
   - This keeps external-service logic out of the orchestrator and makes each connector independently deployable.

6. **Drive, Jira, and Git integration**
   - `mcp_servers/drive` handles Google Drive access and file ingestion, especially planning transcripts.
   - `mcp_servers/jira` creates issues and attaches artifacts in Jira Cloud.
   - `mcp_servers/git` clones and inspects repositories, including README parsing, which is used as the source of truth for API test discovery.

7. **POS API test execution subsystem**
   - `mcp_servers/pos_api` is the execution engine for API validation.
   - It contains the launcher and runner used to bring up the target API, discover endpoints, and execute “happy path” HTTP tests.
   - This is the part of the system that bridges the agent to the application under test, often against a locally running API rather than a hosted service.

8. **Reporting subsystem**
   - `mcp_servers/reporting` generates structured QA output.
   - It renders Markdown through Jinja templates and can produce PDF reports.
   - The reporting stage turns raw test results into an artifact suitable for attachment back into Jira.

9. **Workspace/local filesystem tools**
   - `mcp_servers/workspace` provides local machine utilities such as listing repositories and reports, plus audit-related helpers.
   - This server is the agent’s controlled access point for local file-system inspection and artifact discovery.

10. **Configuration and secrets**
    - `config/settings.py` and `.env.example` centralize environment-driven configuration.
    - `docs/credentials_guide.md` and the per-server configs indicate that credentials are managed per integration rather than globally embedded in code.
    - `docker-compose.yml` and the `Dockerfile` support the agent runtime and auxiliary services.

11. **Data models and validation**
    - `src/schemas/` defines typed structures for user stories, test cases, and test results.
    - These models are the contract between orchestration, LLM output, test execution, and reporting.
    - They reduce ambiguity when moving data across stages and across MCP boundaries.

12. **Utilities and reliability**
    - `src/utils/logging_config.py` standardizes logs.
    - `src/utils/retry.py` provides retry behavior for transient failures, which matters for networked test execution and external APIs.
    - `scripts/health_check.py` suggests a lightweight operational check path for the runtime environment.

13. **Testing and quality gates**
    - `tests/unit` covers core logic such as the cache, router, and schemas.
    - `tests/integration` exists for cross-component behavior, which is important in a system that depends on MCP servers and external services.
    - The repo is built to validate both pure Python behavior and orchestration-driven workflows.

14. **Overall architecture in one sentence**
    - The system is a **modular QA agent** where a **CLI-driven LangGraph orchestrator** uses **LLMs plus Redis-backed cache** to coordinate **specialized MCP servers** for Drive, Jira, Git, API testing, reporting, and local workspace access.

Main entry points: [`src/orchestrator/graph.py`](https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/graph.py) (Workflow), [`tests/unit/test_router.py`](https://github.com/jhonattang/mcp-qa/blob/main/tests/unit/test_router.py) (Tests), [`src/orchestrator/nodes/extract_stories.py`](https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/nodes/extract_stories.py) (Extract stories), [`src/orchestrator/nodes/run_api_tests.py`](https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/nodes/run_api_tests.py) (Run tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_src["Core app"]
  node_node_console["Console<br/>CLI entry<br/>[__main__.py]"]
  node_node_router["Router<br/>CLI routing<br/>[router.py]"]
  node_node_app["App<br/>[app.py]"]
  node_node_orch_graph{{"Workflow<br/>LangGraph state machine<br/>[graph.py]"}}
  node_node_orch_state["State<br/>[state.py]"]
  node_node_extract["Extract stories<br/>orchestrator node<br/>[extract_stories.py]"]
  node_node_jira_create["Create Jira<br/>orchestrator node<br/>[create_jira.py]"]
  node_node_run_tests["Run tests<br/>orchestrator node<br/>[run_api_tests.py]"]
  node_node_upload["Upload report<br/>orchestrator node<br/>[upload_report.py]"]
  node_node_llm[("LLM factory<br/>model adapter<br/>[factory.py]")]
  node_node_cache[("Cache<br/>[cag_manager.py]")]
  node_node_schema["Schemas<br/>data models<br/>[user_story.py]"]
end

subgraph group_group_mcp["MCP servers"]
  node_node_drive["Drive server<br/>MCP server<br/>[server.py]"]
  node_node_git["Git server<br/>MCP server<br/>[server.py]"]
  node_node_jira["Jira server<br/>MCP server<br/>[server.py]"]
  node_node_pos_api["POS API<br/>MCP server<br/>[server.py]"]
  node_node_reporting["Reporting<br/>MCP server<br/>[server.py]"]
  node_node_workspace["Workspace<br/>MCP server<br/>[server.py]"]
end

subgraph group_group_ops["Runtime config"]
  node_node_config["Settings<br/>runtime config<br/>[settings.py]"]
  node_node_compose["Compose<br/>runtime stack<br/>[docker-compose.yml]"]
  node_node_health["Health check<br/>ops script<br/>[health_check.py]"]
end

subgraph group_group_quality["Quality"]
  node_node_tests["Tests<br/>test suite<br/>[test_router.py]"]
end

node_node_console -->|"dispatches to"| node_node_router
node_node_router -->|"builds"| node_node_app
node_node_app -->|"starts"| node_node_orch_graph
node_node_orch_graph -->|"uses state"| node_node_orch_state
node_node_orch_graph -->|"calls"| node_node_llm
node_node_orch_graph -->|"checks cache"| node_node_cache
node_node_orch_graph -->|"stage"| node_node_extract
node_node_orch_graph -->|"stage"| node_node_jira_create
node_node_orch_graph -->|"stage"| node_node_run_tests
node_node_orch_graph -->|"stage"| node_node_upload
node_node_extract -->|"reads input"| node_node_drive
node_node_extract -->|"discovers source"| node_node_git
node_node_jira_create -->|"writes issues"| node_node_jira
node_node_run_tests -->|"executes"| node_node_pos_api
node_node_run_tests -->|"inspects repo"| node_node_git
node_node_upload -->|"renders report"| node_node_reporting
node_node_upload -->|"attaches artifact"| node_node_jira
node_node_orch_graph -->|"uses workspace"| node_node_workspace
node_node_config -->|"configures"| node_node_llm
node_node_config -->|"drives"| node_node_compose
node_node_health -->|"checks"| node_node_workspace
node_node_tests -->|"covers"| node_node_cache
node_node_tests -->|"covers"| node_node_router
node_node_tests -->|"covers"| node_node_schema

click node_node_console "https://github.com/jhonattang/mcp-qa/blob/main/src/console/__main__.py"
click node_node_router "https://github.com/jhonattang/mcp-qa/blob/main/src/console/router.py"
click node_node_app "https://github.com/jhonattang/mcp-qa/blob/main/src/console/app.py"
click node_node_orch_graph "https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/graph.py"
click node_node_orch_state "https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/state.py"
click node_node_extract "https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/nodes/extract_stories.py"
click node_node_jira_create "https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/nodes/create_jira.py"
click node_node_run_tests "https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/nodes/run_api_tests.py"
click node_node_upload "https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/nodes/upload_report.py"
click node_node_llm "https://github.com/jhonattang/mcp-qa/blob/main/src/llm/factory.py"
click node_node_cache "https://github.com/jhonattang/mcp-qa/blob/main/src/cache/cag_manager.py"
click node_node_schema "https://github.com/jhonattang/mcp-qa/blob/main/src/schemas/user_story.py"
click node_node_drive "https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/drive/server.py"
click node_node_git "https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/git/server.py"
click node_node_jira "https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/jira/server.py"
click node_node_pos_api "https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/pos_api/server.py"
click node_node_reporting "https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/reporting/server.py"
click node_node_workspace "https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/workspace/server.py"
click node_node_config "https://github.com/jhonattang/mcp-qa/blob/main/config/settings.py"
click node_node_compose "https://github.com/jhonattang/mcp-qa/blob/main/docker-compose.yml"
click node_node_health "https://github.com/jhonattang/mcp-qa/blob/main/scripts/health_check.py"
click node_node_tests "https://github.com/jhonattang/mcp-qa/blob/main/tests/unit/test_router.py"

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_node_console,node_node_router,node_node_app,node_node_orch_graph,node_node_orch_state,node_node_extract,node_node_jira_create,node_node_run_tests,node_node_upload,node_node_llm,node_node_cache,node_node_schema toneBlue
class node_node_drive,node_node_git,node_node_jira,node_node_pos_api,node_node_reporting,node_node_workspace toneAmber
class node_node_config,node_node_compose,node_node_health toneMint
class node_node_tests toneRose
```

## Components

### Core app

CLI, orchestration, LLM, cache, schemas, and shared utilities.

- [Console](https://github.com/jhonattang/mcp-qa/blob/main/src/console/__main__.py): CLI entry · Command-line front end that starts the QA workflow. · `src/console/__main__.py`
- [Router](https://github.com/jhonattang/mcp-qa/blob/main/src/console/router.py): CLI routing · Dispatches console requests into the application flow. · `src/console/router.py`
- [App](https://github.com/jhonattang/mcp-qa/blob/main/src/console/app.py): CLI app · Console application wiring and prompt handling. · `src/console/app.py`
- [Workflow](https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/graph.py): LangGraph state machine · Main orchestrator graph that drives the QA pipeline. · `src/orchestrator/graph.py`
- [State](https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/state.py): shared state · State model carried across orchestration stages. · `src/orchestrator/state.py`
- [Extract stories](https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/nodes/extract_stories.py): orchestrator node · Stage that turns input material into user stories. · `src/orchestrator/nodes/extract_stories.py`
- [Create Jira](https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/nodes/create_jira.py): orchestrator node · Stage that creates Jira issues and attaches artifacts. · `src/orchestrator/nodes/create_jira.py`
- [Run tests](https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/nodes/run_api_tests.py): orchestrator node · Stage that executes API validation against the target service. · `src/orchestrator/nodes/run_api_tests.py`
- [Upload report](https://github.com/jhonattang/mcp-qa/blob/main/src/orchestrator/nodes/upload_report.py): orchestrator node · Stage that publishes final QA output and attachments. · `src/orchestrator/nodes/upload_report.py`
- [LLM factory](https://github.com/jhonattang/mcp-qa/blob/main/src/llm/factory.py): model adapter · Selects between local and cloud model backends. · `src/llm/factory.py`
- [Cache](https://github.com/jhonattang/mcp-qa/blob/main/src/cache/cag_manager.py): reasoning cache · Cache layer used to reduce repeated reasoning and token usage. · `src/cache/cag_manager.py`
- [Schemas](https://github.com/jhonattang/mcp-qa/blob/main/src/schemas/user_story.py): data models · Typed contracts for stories, test cases, and results. · `src/schemas/user_story.py`

### MCP servers

Isolated tool servers for external systems and local execution.

- [Drive server](https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/drive/server.py): MCP server · Google Drive integration for planning transcripts and ingestion. · `mcp_servers/drive/server.py`
- [Git server](https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/git/server.py): MCP server · Repository clone and README parsing support for test discovery. · `mcp_servers/git/server.py`
- [Jira server](https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/jira/server.py): MCP server · Creates issues and manages Jira Cloud attachments. · `mcp_servers/jira/server.py`
- [POS API](https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/pos_api/server.py): MCP server · Launches and runs API validation against the application under test. · `mcp_servers/pos_api/server.py`
- [Reporting](https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/reporting/server.py): MCP server · Generates structured Markdown and PDF QA reports. · `mcp_servers/reporting/server.py`
- [Workspace](https://github.com/jhonattang/mcp-qa/blob/main/mcp_servers/workspace/server.py): MCP server · Controlled local filesystem access for repos, reports, and audit helpers. · `mcp_servers/workspace/server.py`

### Runtime config

Environment, container, and operational support files.

- [Settings](https://github.com/jhonattang/mcp-qa/blob/main/config/settings.py): runtime config · Environment-driven configuration and secrets wiring. · `config/settings.py`
- [Compose](https://github.com/jhonattang/mcp-qa/blob/main/docker-compose.yml): runtime stack · Container and service definitions for the agent runtime. · `docker-compose.yml`
- [Health check](https://github.com/jhonattang/mcp-qa/blob/main/scripts/health_check.py): ops script · Lightweight operational check for the runtime environment. · `scripts/health_check.py`

### Quality

Tests and validation-focused assets.

- [Tests](https://github.com/jhonattang/mcp-qa/blob/main/tests/unit/test_router.py): test suite · Unit and integration coverage for core orchestration behavior. · `tests/unit/test_router.py`

## Connections

- Console → Router: dispatches to · Console hands requests to routing logic.
- Router → App: builds · Router connects into the console app layer.
- App → Workflow: starts · App invokes the orchestrator workflow.
- Workflow → State: uses state · Workflow shares structured state across stages.
- Workflow → LLM factory: calls · Orchestrator requests model-backed reasoning.
- Workflow → Cache: checks cache · Workflow consults cached reasoning before recomputing.
- Workflow → Extract stories: stage · First major pipeline stage.
- Workflow → Create Jira: stage · Second major pipeline stage.
- Workflow → Run tests: stage · Third major pipeline stage.
- Workflow → Upload report: stage · Final pipeline stage.
- Extract stories → Drive server: reads input · Story extraction can ingest planning material from Drive.
- Extract stories → Git server: discovers source · Extracted stories can be informed by repository README parsing.
- Create Jira → Jira server: writes issues · Issue creation is delegated to the Jira MCP server.
- Run tests → POS API: executes · API validation is delegated to the POS API MCP server.
- Run tests → Git server: inspects repo · Test execution uses repository discovery inputs.
- Upload report → Reporting: renders report · Reporting server produces the final QA artifact.
- Upload report → Jira server: attaches artifact · Final report is sent back to Jira.
- Workflow → Workspace: uses workspace · Workflow may inspect local repositories and reports.
- Settings → LLM factory: configures · Settings influence model backend selection.
- Settings → Compose: drives · Runtime configuration supports containerized deployment.
- Health check → Workspace: checks · Health check validates local runtime and file access.
- Tests → Cache: covers · Tests exercise cache behavior.
- Tests → Router: covers · Tests exercise CLI routing.
- Tests → Schemas: covers · Tests validate data contracts.