# GitPilot MCP

An autonomous MCP-powered agent that automates GitHub contributions end-to-end, from issue analysis and code changes to pull requests, conflict resolution, and review updates.

---

## 🚀 Overview

GitPilot MCP is an **Autonomous GitHub Contribution Agent** built using the **Model Context Protocol (MCP)**.
It helps developers and contributors automate the full open-source workflow:

* Forking repositories
* Analyzing issues
* Making code changes
* Running tests
* Creating pull requests
* Syncing with upstream changes
* Handling merge conflicts
* Updating PRs based on maintainer feedback

The agent is designed to be **minimal, safe, and extensible**, without overengineering.

---

## ✨ Key Features

* 🔁 Fork & clone GitHub repositories
* 🌿 Create and manage feature branches
* 🔄 Sync fork with upstream when new PRs are merged
* 🧠 Semantic code understanding using RAG
* ✍️ Generate minimal, clean git diffs
* 🧪 Run tests and retry fixes automatically
* 📦 Commit & push changes
* 🔀 Create pull requests programmatically
* 🛠️ Update existing PRs after review feedback
* ⚠️ Detect merge conflicts before PR updates

---

## 🧠 Architecture (High Level)

```
Issue → Code Context (RAG) → Patch → Tests → Commit → PR
              ↑
      Sync / Review Feedback
```

The system follows **real-world open-source contribution practices**.

---

## 📂 Project Structure

```
mcp-github/
│
├── main.py        # MCP server & tools
├── rag.py         # RAG indexing and search
├── config.py      # GitHub token & workspace
├── .rag/          # Vector store (local)
└── README.md
```

## 🧩 Installation & Setup

Make sure you have the following installed:

- Python 3.10+
- Git
- Claude Desktop (latest version)
- Ollama (for embeddings)

### Step 1: Install uv

uv is used for dependency management and isolated execution.
```bash
pip install uv
```

### Step 2: Clone the Repository
```bash
git clone https://github.com/<your-username>/GitPilot-MCP.git
cd GitPilot-MCP
```

### Step 3: Initialize the Project (uv)

Initialize the project environment:
```bash
uv init
```

### Step 4: Install Dependencies

Add all required dependencies:
```bash
uv add fastmcp gitpython pygithub python-dotenv numpy faiss-cpu ollama
```

### Step 5: For MCP tools testing
```bash
uv run fastmcp dev main.py
```

---


## ⚙️ MCP Server Configuration

Use the following configuration to run the MCP server locally via **uv + fastmcp** in **Claude-desktop**:

paste this configuration in claudee-desktop-config file.

```json
{
  "mcpServers": {
    "GitPilot-MCP": {
      "command": "<PATH_TO_PYTHON>/Scripts/uv.exe",
      "args": [
        "run",
        "--project",
        "<PATH_TO_PROJECT_ROOT>",
        "--directory",
        "<PATH_TO_PROJECT_ROOT>",
        "fastmcp",
        "run",
        "main.py"
      ],
      "transport": "stdio"
    }
  }
}
```

---

## 🔐 Configuration

Create a `config.py` file:

```python
GITHUB_TOKEN = "your_github_personal_access_token"
WORKSPACE = "./workspace"
```

⚠️ The token must have permissions to fork repositories and create pull requests.

---

## 🛠️ Available MCP Tools

Some important tools exposed by the agent:

* `fork_repo`
* `clone_repo`
* `create_branch`
* `sync_with_upstream`
* `index_repo`
* `get_repo_context`
* `apply_patch`
* `run_tests`
* `retry_fix_with_tests`
* `commit_and_push`
* `create_pull_request`
* `check_for_conflicts`
* `update_pr_after_feedback`

Each tool is **single-responsibility and composable**.

---

## 🧪 Testing Workflow

1. Apply generated patch
2. Run tests (`pytest -q` by default)
3. Retry fixes automatically if tests fail
4. Stop immediately once tests pass

---

## 🔄 Handling Maintainer Feedback

When a maintainer requests changes:

* Generate a new patch
* Apply it to the same branch
* Commit & push

The existing PR updates automatically.
No new PRs are created.

---

## 🧩 Design Principles

* ✅ Minimal diffs
* ✅ Short, inline comments only when necessary
* ✅ No hard refresh or destructive git actions
* ✅ No silent failures
* ✅ Extensible for future improvements

---

## 🚧 Limitations

* Repository indexing may be limited on very large repos
* Conflict resolution is assisted, not fully automatic
* Designed for local / controlled environments (remote hardening can be added later)

---

## 🔮 Future Improvements

* Scoped repository indexing
* PR comment parsing
* CI status polling
* Refresh-token support
* Remote multi-user MCP deployment

---

## 📜 License

MIT License (or as per your choice)

---

## 🙌 Acknowledgements

Built using:

* FastMCP
* GitPython
* PyGitHub
* Ollama (for embeddings)
* Qdrant / FAISS (vector search)

## 👨‍💻 Author
Divyanshu Giri