---
module_type: MCP Server
status: Active
protocol: MCP / JSON-RPC / stdio
primary_capability: Automated security reviews for GitHub PR diffs with deep fallback redundancy
requires: python 3.12+, Cloudflare Workers AI token, Poolside token
works_with: Google Antigravity, Telegram Agent, Cloudflare, Poolside, OpenRouter
last_verified: 2026-08-21
---

# MCP GitHub PR Reviewer

**A Universal Fallback MCP Server that provides highly resilient automated GitHub Pull Request security reviews.**

## Status and Last Verified Date
**Status:** Active  
**Last Verified Date:** 2026-08-21  

## What it does / does not do
**What it does:**
- Implements an MCP Server exposing the `audit_pr` tool to AI agents.
- Processes code diffs and returns structured security vulnerabilities and architecture feedback in JSON format.
- Automatically routes and cascades LLM requests across a 14-layer failover pipeline to ensure 100% uptime.
- Balances load and failovers between Cloudflare Workers AI, Poolside Native, and OpenRouter API endpoints.

**What it does not do:**
- It does not automatically merge PRs or act on the code itself (it acts purely as an analytical auditor).
- It does not manage GitHub API tokens directly for fetching; diffs are expected to be provided by the calling agent.

## Why an agent would use it
Agents use this MCP server to offload computationally heavy code review tasks to specialized external LLMs without having to manage tokens, fallback logic, or retry loops themselves. The agent simply provides the diff, and the MCP server guarantees a high-quality review.

## Architecture and dependencies
**Architecture:**
- **Universal Fallback Engine:** A state-machine (`engine.py`) that iterates through any configured OpenAI-compatible LLM endpoints and key pools.
- **Provider Pipeline (Configurable):**
  You can configure your own cascading provider pipeline using the `FALLBACK_PROVIDERS` environment variable (JSON array).
  - *Example Config:* Try local Ollama first, then DeepSeek, then OpenRouter.
- **Legacy Lab Support:** If `FALLBACK_PROVIDERS` is empty, it automatically degrades to TheNovaNodes lab defaults (Cloudflare -> Poolside -> OpenRouter) using legacy regex parsing.
- **MCP Protocol Layer:** Uses standard `stdio` JSON-RPC for MCP server execution (`server.py`).

**Dependencies:**
- `mcp` (official Python SDK)
- Standard Python `urllib` (no third-party HTTP clients required)
- `pytest` (for tests)

## Compatibility
- Python 3.12+
- Linux/Unix environments

## Quick start and health check
**Quick Start:**
```bash
git clone https://github.com/TheNovaNodes/mcp-gh-pr-reviewer.git
cd mcp-gh-pr-reviewer
python3 -m venv .venv
source .venv/bin/activate
pip install mcp
# Ensure vault tokens are populated in /dev/shm/agent_vault/
./run_mcp.sh
```

**Health Check:**
To verify the engine initialization and API connections, run:
```bash
python3 test_fallback.py
```
This triggers a simulated PR diff audit to test the cascade without exposing the server to an MCP client.

## Configuration and environment variables
| Variable | Description |
| -------- | ----------- |
| `FALLBACK_PROVIDERS` | JSON array of providers. Example: `[{"name": "Local", "url": "http://127.0.0.1:11434/v1/chat/completions", "model": "qwen2.5-coder", "keys_env": "LOCAL_TOKENS"}]` |
| `CF_TOKENS` | (Legacy Mode) Cloudflare tokens and Account IDs. |
| `PS_TOKENS` | (Legacy Mode) Poolside API keys. |
| `OR_TOKENS` | (Legacy Mode) OpenRouter API keys. |

## Complete MCP tool/API table with side effects
| Server Key | Name | Type | Plane | Side Effects / Actions |
| ---------- | ---- | ---- | ----- | ---------------------- |
| `universal-pr-auditor` | PR Auditor (Universal) | audit | data | Reads diffs, queries external LLMs via HTTP, returns JSON. |

## Security model and trust boundaries
- **Secrets Management:** The server reads secrets dynamically from the RAM disk (`/dev/shm/agent_vault/`) via the `run_mcp.sh` wrapper. No secrets are ever hardcoded in the Python source code or git history.
- **Execution:** Runs as a standard local process communicating over `stdio`. Does not expose any open network ports locally.

## Tests and exact commands
To run tests using `pytest`:
```bash
python3 -m pytest test_engine.py
```
This suite tests the key extraction, parsing, and engine routing logic without burning actual LLM tokens.

## Operations, logs, backup/restore, rollback
- **Operations:** The server is executed contextually by the `antigravity-telegram-agent` using `run_mcp.sh`.
- **Logs:** Engine logs (fallbacks, HTTP errors) are printed to `stderr` and intercepted by the agent's MCP manager.
- **Backup/Restore:** No persistent state is stored by this server. 
- **Rollback:** `git checkout main && git reset --hard <hash>`

## Generic MCP-client example
Example JSON-RPC payload to trigger an audit:
```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "callTool",
  "params": {
    "name": "audit_pr",
    "arguments": {
      "diff_content": "+ def bypass_auth():\n+    return True"
    }
  }
}
```

## Limitations and roadmap
**Limitations:**
- OpenRouter free models have strict rate limits and may fail frequently (handled gracefully by the engine).
- Diffs larger than 128K tokens may be truncated by the LLM providers.

**Roadmap:**
- Add native GitHub PR fetching capabilities (currently relying on the caller agent to provide the diff).

## Related TheNovaNodes modules
- Antigravity Telegram Agent
- Google Jules MCP modules

## License
MIT License