How saakshigupta2002/pr_orchestrator_mcp works
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.