Agentic CI/CD Orchestrator

Python MCP server for GitHub Actions failure diagnosis, LLM-driven unified-diff auto-repair PR creation, and governed release orchestration.

What this provides

• MCP tooling to inspect failed workflow runs using commit, logs, and test signals.
• LLM diagnosis flow powered by OpenAI gpt-4o-mini.
• Governance layer to auto-fix low-risk issues and require human review for risky changes.
• Generic model-driven repair loop (up to 3 attempts) using unified diff patches.
• GitHub Actions workflows for CI, repair orchestration, and release policy gating.

Project layout

• mcp_server/main.py - MCP tools and orchestration entrypoints
• mcp_server/host_http.py - streamable HTTP MCP server for browser clients
• mcp_server/run_repair.py - workflow-safe command runner
• frontend/ - Vite + React MCP client UI
• mcp_server/config.py - typed environment config
• mcp_server/tools/* - GitHub, diagnosis, risk, and PR automation modules
• .github/workflows/* - CI/CD automation workflows

Setup

1. Create and activate a virtual environment.
2. Install dependencies:
   • pip install -r requirements.txt
3. Copy environment defaults:
   • cp .env.example .env (or create .env manually on Windows)
4. Fill in required values (OPENAI_API_KEY, GITHUB_TOKEN).

Run MCP server locally

• stdio (Cursor / Claude Desktop): python -m mcp_server.main

Web UI (browser MCP client + hosted server)

The frontend app is a real MCP client using streamable HTTP. Secrets stay on the server; the browser only talks MCP.

1. Terminal A — MCP over HTTP (from repo root, with .env configured):

   python -m mcp_server.host_http
   

   Listens on 0.0.0.0 and PORT from the environment (Render sets this). Path: /mcp.

2. Terminal B — SPA dev server:

   cd frontend
   npm install
   cp .env.example .env
   npm run dev
   

   Configure frontend/.env: VITE_MCP_URL is the MCP endpoint (default http://127.0.0.1:8000/mcp). It pre-fills the UI and sets the Vite dev proxy target origin. Clear the field to use same-origin /mcp (proxied to that origin).

3. Open the Vite URL (usually http://localhost:5173).

Production CORS: the browser sends an Origin header; the MCP server must allow it or preflight (OPTIONS) fails (often surfaced as Failed to fetch).

• Set MCP_CORS_ORIGINS to a comma-separated list of exact SPA origins (for example https://your-frontend.onrender.com).
• Or set MCP_CORS_ORIGIN_REGEX (for example https://.*\.onrender\.com) to allow all Render app URLs without listing each one (tighter regex is better for production).

Render (two services): one Web Service should run python -m mcp_server.host_http (the MCP API). A second service or Static Site can serve the built SPA (npm run build output). Set VITE_MCP_URL at frontend build time to the MCP service URL (for example https://your-mcp-api.onrender.com/mcp), not the static site URL, unless you use a reverse proxy that mounts both. If you only run vite preview on Render, that process does not expose the Python MCP server — /mcp will not work there.

GET /mcp → 406 in logs usually means something opened /mcp in a normal browser tab (wrong Accept header); the MCP client uses POST/SSE and is unaffected.

MCP tools exposed: resolve_latest_failed_run, inspect_pipeline_failure, orchestrate_autofix (same behavior as the CLI, with resolve_latest_failed_run matching run_repair when RUN_ID is omitted).

Client timeouts: The MCP TypeScript SDK defaults to 60 seconds per request. orchestrate_autofix often runs longer (LLMs, GitHub). The SPA uses 15 minutes for orchestrate_autofix and 2 minutes for resolve_latest_failed_run unless you set VITE_MCP_ORCHESTRATE_TIMEOUT_MS / VITE_MCP_RESOLVE_TIMEOUT_MS in frontend/.env (milliseconds).

Use in Cursor as MCP

• MCP config is included at .cursor/mcp.json.
• Restart Cursor so it loads the MCP server definition.
• Ensure your .env has OPENAI_API_KEY and GITHUB_TOKEN.
• In Cursor chat, call tools from agentic-cicd-orchestrator with:
  • repository: owner/repo
  • run_id: workflow run id (integer)
• Main tools:
  • inspect_pipeline_failure
  • resolve_latest_failed_run
  • orchestrate_autofix

Run repair orchestration manually

• Set REPOSITORY (for example org/repo).
• Optional:
  • RUN_ID (if omitted, latest failed run is auto-selected)
  • WORKFLOW_NAME (filter latest failed run by workflow name, e.g. ci)
  • BASE_BRANCH (default main)
• Execute: python -m mcp_server.run_repair

LLM auto-repair controls

• MAX_REPAIR_ATTEMPTS - number of patch generation/application retries (default 3).
• PATCH_STRATEGY - patch format expected from model (must be unified_diff).
• LLM_PATCH_MAX_CHARS - upper bound on patch payload size.

Governance model

• risk_score < RISK_AUTO_FIX_THRESHOLD -> autonomous auto-fix PR path.
• RISK_AUTO_FIX_THRESHOLD <= risk_score < RISK_HUMAN_REVIEW_THRESHOLD -> human approval required.
• risk_score >= RISK_HUMAN_REVIEW_THRESHOLD or high-risk file categories -> blocked/review-only path.
• FORCE_AUTOFIX_ALL=true -> bypass thresholds and force auto-fix path (dangerous; use only in controlled testing).

Security notes

• Use least-privilege GitHub credentials.
• Keep production deployment credentials separate from auto-repair identity.
• Review generated PRs and audit artifacts before enabling automerge in production.