# saakshigupta2002/pr_orchestrator_mcp architecture

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

- Interactive diagram: https://gitdiagram.com/saakshigupta2002/pr_orchestrator_mcp
- Repository: https://github.com/saakshigupta2002/pr_orchestrator_mcp

## Overview

##### Project type and purpose
- This is a backend “tools-only” MCP server written in Python. It exposes a catalog of “tools” over stdio (the MCP protocol) for an LLM orchestrator to call. Its job is to perform safe, deterministic operations on GitHub repositories (cloning, patching, QA, PR creation) inside isolated E2B sandboxes.

##### File structure
- Top‐level folders:
- src/pr_orchestrator/ – the Python package, subdivided into domains:
– server.py – MCP/stdio entrypoint & dispatcher
– config.py, state.py, constants.py – environment & in-memory state
– policy/ – safety policy enforcement (allowlists, redaction, limits)
– sandbox/ – workspace lifecycle abstraction (E2B backend)
– git/ – Git operations & branch strategy
– github/ – GitHub API interactions
– qa/ – detection, install, test, lint, format tools
– artifacts/ – redacted bundle & report generation
– telemetry/ – logging & run-store persistence
– tools/ – public tool adapters (workspace, repo, edit, QA, GitHub, approval, artifact)
- scripts/ – shell helpers
- docs/ – design docs & tool specs
- tests/ – unit & integration suites

##### Key insights from README
- Architecture is a classic micro-kernel / plug-in design: core server + discrete tool plug-ins invoked by name.
- There is a strict safety layer (policy) and all repository work is sandboxed in an E2B container.
- External dependencies: GitHub (via REST API) and the E2B sandbox service.

##### Relationships & data flows
- MCP Server → Policy Enforcer: every tool invocation passes through policy checks (allowlist, limits, redaction).
- MCP Server → Sandbox: calls workspace_create / run_command / workspace_destroy.
- Sandbox → Git Operations module: actual git CLI commands inside container.
- Sandbox → QA Tools: pip install, pytest, flake8, etc., returning structured JSON.
- MCP Server → GitHub API Client: authenticated REST calls (fork creation, PR creation).
- MCP Server → Telemetry: journals tool invocations & run results.
- MCP Server → Artifact Bundler: on request, returns a redacted bundle (base64).
- MCP Server → Approval Gate: request_approval before pushing or opening a PR.

##### Architectural patterns & principles
- Micro-kernel / plug-in for tools.
- Single responsibility per module (one domain per sub-package).
- Policy enforcement as a cross-cutting concern.
- Sandbox isolation to enforce safety/security.
- Stateless core: all long-term state is in environment variables or telemetry store.

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Orchestrator
    LLM["Orchestrator LLM"]:::external

    %% MCP Server Core
    subgraph "MCP Server"
        protocol["Protocol Layer & Dispatcher"]:::core
        config["Configuration & Environment"]:::core
        state["In-Memory State"]:::core
        constants["Constants"]:::core

        subgraph "Policy Enforcer"
            allowlist["Allowlist"]:::core
            limits["Limits"]:::core
            redaction["Redaction"]:::core
        end

        subgraph "Sandbox / Workspace Manager"
            backend["E2B Backend"]:::core
            e2b_code["E2B Code"]:::core
            e2b_desktop["E2B Desktop"]:::core
            workspace_store["Workspace Store"]:::core
        end

        subgraph "Git Operations"
            repo_ops["Repo Operations"]:::core
            branch_strategy["Branch Strategy"]:::core
        end

        subgraph "GitHub Client"
            gh_api["API"]:::core
            gh_auth["Auth"]:::core
            gh_templates["Templates"]:::core
        end

        subgraph "QA Tools"
            detect["Detect"]:::core
            install["Install"]:::core
            lint["Lint"]:::core
            tests["Tests"]:::core
            failure_parser["Failure Parser"]:::core
        end

        subgraph "Artifact Bundler"
            bundler["Bundler"]:::core
            report["Report Generator"]:::core
        end

        subgraph "Telemetry"
            logger["Logger"]:::core
            run_store["Run Store"]:::core
        end

        subgraph "Tool Registry & Dispatch"
            workspace_tools["Workspace Tools"]:::core
            repo_tools["Repo Tools"]:::core
            edit_tools["Edit Tools"]:::core
            qa_tools["QA Tools"]:::core
            github_tools["GitHub Tools"]:::core
            artifact_tools["Artifact Tools"]:::core
            approval_tools["Approval Tools"]:::core
        end
    end

    %% External Services and Data Stores
    E2BService(("E2B Sandbox Service")):::external
    GitHub(("GitHub REST API")):::external
    TelemetryDB[(Telemetry DB)]:::db
    ConfigStore[(Configuration Store)]:::db
    FileSystem[(File System)]:::db
    DeveloperPortal["Developer Portal\n(docs/tool-spec.md)"]:::external

    %% Connections
    LLM <-->|"MCP tool calls / JSON responses"| protocol
    protocol -->|"policy check"| allowlist
    protocol -->|"policy check"| limits
    protocol -->|"policy check"| redaction
    protocol -->|"workspace_create / run_command / destroy"| backend
    backend -->|"invoke CLI"| repo_ops
    backend -->|"invoke tests/lint"| detect
    backend --> E2BService
    E2BService --> repo_ops
    E2BService --> tests
    protocol -->|"REST calls"| gh_api
    protocol -->|"journal results"| logger
    logger --> TelemetryDB
    run_store --> TelemetryDB
    protocol -->|"bundle request"| bundler
    bundler --> FileSystem
    protocol -->|"request_approval"| approval_tools
    protocol --> config
    config --> ConfigStore
    protocol --> state
    protocol --> constants

    developer_tools["Developer Portal\n(docs)"]:::external
    protocol --> developer_tools

    %% Click Events
    click protocol "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/server.py"
    click config "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/config.py"
    click state "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/state.py"
    click constants "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/constants.py"
    click allowlist "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/policy/allowlist.py"
    click limits "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/policy/limits.py"
    click redaction "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/policy/redaction.py"
    click backend "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/sandbox/backend.py"
    click e2b_code "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/sandbox/e2b_code.py"
    click e2b_desktop "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/sandbox/e2b_desktop.py"
    click workspace_store "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/sandbox/workspace_store.py"
    click repo_ops "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/git/repo_ops.py"
    click branch_strategy "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/git/branch_strategy.py"
    click gh_api "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/github/api.py"
    click gh_auth "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/github/auth.py"
    click gh_templates "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/github/templates.py"
    click detect "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/qa/detect.py"
    click install "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/qa/install.py"
    click lint "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/qa/lint.py"
    click tests "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/qa/tests.py"
    click failure_parser "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/qa/failure_parser.py"
    click bundler "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/artifacts/bundler.py"
    click report "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/artifacts/report.py"
    click logger "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/telemetry/logger.py"
    click run_store "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/telemetry/run_store.py"
    click workspace_tools "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/tools/workspace_tools.py"
    click repo_tools "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/tools/repo_tools.py"
    click edit_tools "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/tools/edit_tools.py"
    click qa_tools "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/tools/qa_tools.py"
    click github_tools "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/tools/github_tools.py"
    click artifact_tools "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/tools/artifact_tools.py"
    click approval_tools "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/src/pr_orchestrator/tools/approval_tools.py"
    click developer_tools "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/docs/tool-spec.md"
    click scripts_run "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/scripts/run_server.sh"
    click scripts_smoke "https://github.com/saakshigupta2002/pr_orchestrator_mcp/blob/main/scripts/smoke_test.sh"

    %% Styles
    classDef core fill:#D0E6FF,stroke:#0284C7,stroke-width:1px
    classDef external fill:#FFD8A8,stroke:#C06500,stroke-width:1px
    classDef db fill:#D7FFD9,stroke:#0A6B00,stroke-width:1px
```
