# RepoControl MCP (Lite Edition)

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Protocol: MCP](https://img.shields.io/badge/MCP-2024--11--05-green.svg)](https://modelcontextprotocol.io/)
[![Python: >=3.10](https://img.shields.io/badge/Python->=3.10-yellow.svg)](https://python.org/)

**RepoControl MCP** is a secure, least-privilege Model Context Protocol server that enables AI agents (Claude Desktop, Cursor, LangGraph, CrewAI) to manage GitHub issues, inspect discussions, create pull requests, and audit CI check-runs with strict safety guards.

---

## 🎯 The Problem

Developers are increasingly delegating code refactoring and bug-fixing to autonomous agents:
1. **Destructive Force Pushes:** Giving an LLM a blanket `repo` token risks accidental force pushes to `main`, corrupting commit histories or deleting production branches.
2. **Abandoned Failing PRs:** AI agents often push commits, open a PR, and immediately conclude the prompt—leaving failing GitHub Actions builds and broken test suites unaddressed.
3. **Missing Audit Trails:** No cryptographic evidence ledger tracking which commits and diffs were proposed by which agent model.

**RepoControl** acts as an intelligent control plane between your autonomous agents and the GitHub API, enforcing safety guardrails and verifying builds before work is marked complete.

---

## ✨ Features (Lite Edition)

- 🛡️ **Branch Safety Guards:** Built-in protection preventing destructive operations against `main`, `master`, `prod`, `release`.
- 📝 **Issue & PR Lifecycle:** Safely create issues, fetch discussions, and open pull requests.
- 🚦 **CI Status Auditing:** Inspect GitHub Actions check-runs and overall build conclusions directly via MCP tools.
- ⚡ **Zero-Config Protocol:** Standard JSON-RPC 2.0 stdio server compatible with Claude Desktop and Cursor.

---

## 🚀 Quickstart

### 1. Installation

```bash
git clone https://github.com/johannschiffer/repocontrol-mcp.git
cd repocontrol-mcp
pip install -e .
```

### 2. Configure in Claude Desktop or Cursor

Add to your `claude_desktop_config.json` or Cursor MCP settings:

```json
{
  "mcpServers": {
    "repocontrol": {
      "command": "repocontrol",
      "args": ["run"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_github_token_here"
      }
    }
  }
}
```

### 3. CLI Inspection

```bash
# Check CI status of any commit or branch
repocontrol ci-check owner/repo feature-branch
```

---

## 🛠️ MCP Tools Reference

| Tool | Parameters | Description |
|---|---|---|
| `create_issue` | `repo`, `title`, `body`, `labels` | Opens an issue in the target repository |
| `get_issue_comments` | `repo`, `issue_number`, `limit` | Retrieves discussion comments on an issue/PR |
| `create_pull_request` | `repo`, `title`, `head`, `base`, `body` | Opens a PR with branch collision guards |
| `list_pull_requests` | `repo`, `state`, `limit` | Lists open or closed pull requests |
| `check_ci_status` | `repo`, `ref` | Audits GitHub Actions check-runs and conclusion |
| `is_branch_protected` | `branch` | Validates if a branch is covered by safety guards |

---

## 🚀 Upgrade to RepoControl Pro

Need enterprise-grade autonomous CI recovery and security governance?

The **RepoControl Pro Edition** adds:
- 🔍 **CI/CD Log Analyzer & Auto-Fix:** Automatically extracts compiler errors, test failures, and stack traces from failing GitHub Actions runs so the LLM can self-correct without human triage.
- 🔒 **Least-Privilege Token Scoper & Command Filter:** Restricts agent capabilities strictly to authorized operations and blocks destructive API endpoints.
- 📜 **Cryptographic Evidence Audit Ledger:** SQLite WAL ledger recording SHA-256 hashes of every commit, diff, and test report, with automated Markdown attestation for PRs.
- 🐳 **Production Docker & Compose:** Containerized sidecar setup for cloud agent runners.
- 🧪 **100% Passing Pytest Suite** ready for enterprise CI/CD.

👉 **[Get RepoControl Pro on Gumroad ($14.99 USD)](https://johanld.gumroad.com/l/mfiyw)**

---

## 📄 License

MIT © 2026 [Johann Schiffer](https://github.com/johannschiffer)