# 🚀 Open Source Contribution MCP Server (`open-source-contribution-mcp-server`)

[![TypeScript](https://img.shields.io/badge/TypeScript-5.5-blue.svg)](https://www.typescriptlang.org/)
[![Model Context Protocol](https://img.shields.io/badge/MCP-1.0-purple.svg)](https://modelcontextprotocol.io/)
[![License: ISC](https://img.shields.io/badge/License-ISC-green.svg)](LICENSE)

An end-to-end **Model Context Protocol (MCP) Server** that enables AI clients (Claude Desktop, Cursor, AI agents) to autonomously discover, analyze, fix, test, submit, and track open-source contributions on GitHub.

---

## 🌟 Overview

Making your first (or 50th) open-source contribution can be intimidating: finding active repositories with open PR queues, understanding unwritten codebase conventions, passing strict linters, and avoiding silent CI failures.

This MCP server provides **12 specialized tools** across 6 domain modules to automate the entire contribution lifecycle.

---

## 🛠️ Complete Tool Catalog (12 Tools)

### 👤 1. Skill & Preference Management Module
*Allows AI clients to store and reference your tech stack, language proficiencies, and project preferences.*

| Tool Name | Parameters | Description |
|:---|:---|:---|
| `get_user_skills` | None | Returns your stored tech stack, proficiency levels, and project preferences. |
| `set_user_skills` | `skills`, `preferences` | Overwrites your profile with new skills and preferences (saved to `skills.json`). |
| `add_user_skills` | `skills` | Appends new skills to your profile without clobbering preferences. |
| `remove_user_skill`| `name` | Removes a specific skill from your profile. |
| `clear_user_skills` | None | Resets your skill profile back to default settings. |

### 🔍 2. Repository & Issue Discovery Module
*Filters GitHub for high-confidence, active repositories with zero PR queues.*

| Tool Name | Parameters | Description |
|:---|:---|:---|
| `find_issues` | `query`, `languages`, `limit` | Searches GitHub for open `good first issue` / `help wanted` issues in repos with active maintainers, low open PR queues, and recent commit activity. |

### 📊 3. Deep Repository Context & Analysis Module
*Inspects repository rules, linters, and architectural patterns before writing code.*

| Tool Name | Parameters | Description |
|:---|:---|:---|
| `analyze_repo_context` | `repo`, `issueNumber` | Reads target issue details, `CONTRIBUTING.md`, linter configs (`ruff`, `eslint`, line lengths), target source files, and test files. |

### 🛠️ 4. Code & Test Generation Module
*Synthesizes compliant source code patches and unit tests.*

| Tool Name | Parameters | Description |
|:---|:---|:---|
| `generate_code_fix` | `repo`, `issueNumber`, `instructions` | Generates a compliant source fix obeying repository formatting & line length constraints. |
| `generate_unit_tests` | `repo`, `issueNumber`, `targetFile`, `instructions` | Synthesizes unit tests (with mock coverage) to verify the fix and prevent regressions. |

### 🚀 5. Automated Pull Request Module
*Automates the complete GitHub Git workflow.*

| Tool Name | Parameters | Description |
|:---|:---|:---|
| `submit_pull_request` | `repo`, `branchName`, `title`, `body`, `files` | Forks the repo, creates a branch, commits files, pushes to your fork, and submits a PR to upstream. |
| `track_open_prs` | `repo`, `prNumber` | Checks status, mergeability, CI workflow check runs, and merge state of a PR. |

### 💬 6. Review Feedback & Iteration Module
*Keeps PRs moving toward merge.*

| Tool Name | Parameters | Description |
|:---|:---|:---|
| `get_review_feedback` | `repo`, `prNumber` | Pulls review comments (from maintainers & bots like Copilot) and failed CI step logs to guide single-try fixes. |

---

## 🔐 GitHub Personal Access Token (PAT) Setup

To allow the MCP Server to search repositories, inspect codebases, fork repos, and create pull requests, you need a GitHub Personal Access Token.

### Step-by-Step Instructions:

1. Go to GitHub Settings: **[GitHub Developer Settings > Personal Access Tokens (Classic)](https://github.com/settings/tokens)**
2. Click **Generate new token (classic)**.
3. Set a descriptive note: `MCP Open Source Contribution Server`.
4. Select the following required **scopes**:
   - `repo` (Full control of private/public repositories — required for forking & creating PRs)
   - `workflow` (Update GitHub Action workflows — required if modifying workflow files)
   - `user:email` (Access user email addresses)
5. Click **Generate token** and copy the generated token string (`ghp_...`).
6. Store it in your `.env` file or environment variables:

```env
GITHUB_TOKEN=ghp_your_personal_access_token_here
```

---

## ⚡ Installation & Setup

### Prerequisites
- **Node.js**: `v18.0.0` or higher
- **npm** or **yarn** or **pnpm**
- **Git** installed on system path

### 1. Clone & Install Dependencies

```bash
git clone https://github.com/your-username/open-source-contribution-mcp-server.git
cd open-source-contribution-mcp-server
npm install
```

### 2. Configure Environment

Create a `.env` file in the root directory (or copy `.env.example`):

```bash
cp .env.example .env
```

Edit `.env` and add your GitHub Personal Access Token:

```env
GITHUB_TOKEN=ghp_your_personal_access_token_here
```

### 3. Build the TypeScript Server

```bash
npm run build
```

---

## 🔌 Connecting to MCP Clients

### A. Claude Desktop Integration

Add the server to your Claude Desktop configuration file:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "open-source-contributions": {
      "command": "node",
      "args": [
        "C:/path/to/open-source-contribution-mcp-server/dist/index.js"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token_here"
      }
    }
  }
}
```

### B. Cursor / Antigravity Integration (`mcp_config.json`)

```json
{
  "mcpServers": {
    "open-source-contributions": {
      "command": "node",
      "args": [
        "C:/path/to/open-source-contribution-mcp-server/dist/index.js"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token_here"
      }
    }
  }
}
```

---

## 🧪 Testing & MCP Inspector

You can inspect and test all 12 tools interactively using the official `@modelcontextprotocol/inspector`:

```bash
npm run inspector
```

This launches the interactive MCP web UI at `http://localhost:5173`.

---

## 🏆 Real-World Battle-Tested Proof

This MCP server has been battle-tested on live open-source repositories:

1. 🟣 **[`mldsveda/PyScrappy` PR #139](https://github.com/mldsveda/PyScrappy/pull/139)** — **MERGED TO `main`**
   - Fixed a critical atomic file-saving bug (`tempfile.mkstemp` + `os.replace()`). Passed 100% of Python 3.9–3.13 unit tests and Ruff formatting.
2. 🟢 **[`fu351/Doberman-Core` PR #345](https://github.com/fu351/Doberman-Core/pull/345)** — **OPEN & PASSING CI**
   - Retuned light-mode verdict badge colors to clear WCAG AA 4.5:1 text contrast with unit tests.

---

## 📄 License

Distributed under the **ISC License**. See `LICENSE` for more information.