Content
# 🤖 MCP Contributor
An **MCP (Model Context Protocol) server** for autonomous GitHub contribution.
It discovers issues, analyzes quality, implements fixes, creates pull requests, monitors their status, and learns from results — all on autopilot.
Built for AI agents like **Claude Code**, **Codex**, **QwenPaw**, or any MCP-compatible agent.
---
## 📦 Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ MCP Contributor │
│ │
│ ┌──────────────────┐ ┌────────────────┐ ┌──────────────┐ │
│ │ MCP Server │ │ Cron Pipeline │ │ PR Monitor │ │
│ │ (server.py) │ │ (daily @ 8AM) │ │ (hourly) │ │
│ │ │ │ │ │ │ │
│ │ • find_repos │ │ • Scan repos │ │ • check PRs │ │
│ │ • get_repo_info │ │ • Analyz.iss. │ │ • detect chg │ │
│ │ • analyze_iss. │ │ • Pick best │ │ • Telegram │ │
│ │ • review_pr │ │ • Fork+PR │ │ • Self-learn │ │
│ └──────┬───────────┘ └───────┬────────┘ └──────┬───────┘ │
│ │ │ │ │
│ └──────────┬───────────┴───────────────────┘ │
│ │ │
│ ┌─────▼──────┐ │
│ │ GitHub CLI │ │
│ │ (gh) │ │
│ └────────────┘ │
└─────────────────────────────────────────────────────────────┘
```
### Components
| Component | File | Trigger | Purpose |
|-----------|------|---------|---------|
| **MCP Server** | `mcp_server/server.py` | On-demand (agent call) | Exposes 4 tools via Stdio transport (JSON-RPC 2.0) |
| **Cron Pipeline** | `mcp_server/cron_pipeline.py` | Daily 08:00 | Scans repos, analyzes issues, creates contributions |
| **PR Monitor** | `mcp_server/pr_monitor.py` | Every hour | Checks PR status, sends Telegram notifications |
| **Self-Learning** | `mcp_server/self_learn.py` | After each monitor | Analyzes merge rate, adjusts quality threshold |
| **Pre-Push Review** | `scripts/pre_push_review.py` | Before git push | Quality gate for code changes |
---
## 🚀 Installation
### Prerequisites
- **Python 3.10+**
- **GitHub CLI (`gh`)** — authenticated with a token that has `repo`, `gist`, `read:org`, `workflow` scopes
- **Telegram Bot** (optional, for notifications)
- **QwenPaw** (or any MCP-compatible agent runner)
### 1. Clone
```bash
git clone https://github.com/nguyenthanhthe/mcp-contributor.git
cd mcp-contributor
```
### 2. Install dependencies
```bash
pip install requests # for Telegram notifications
pip install mcp[cli] # optional — for running MCP server directly
```
### 3. Configure GitHub CLI
```bash
gh auth login
# Must have scopes: repo, gist, read:org, workflow
```
### 4. Configure Telegram (optional)
```bash
python scripts/telegram_notify.py setup <BOT_TOKEN> <CHAT_ID>
```
### 5. Verify setup
```bash
python -c "from mcp_server.gh_utils import search_repos; r = search_repos(1000, 5000, 'Python', 3); print(f'OK: {len(r)} repos found')"
```
---
## 🔧 MCP Tools Reference
The server (`mcp_server/server.py`) exposes 4 tools via MCP Stdio transport:
### 1. `find_repos`
Find high-quality GitHub repositories for contribution opportunities.
**Parameters:**
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `min_stars` | int | 1000 | Minimum star count |
| `max_stars` | int | 10000 | Maximum star count |
| `language` | str | "" | Programming language filter (e.g., "Python", "") |
| `limit` | int | 10 | Number of repos to return |
**Example response:**
```json
[
{"name": "py-pdf/pypdf", "stars": 9981, "description": "A pure-python PDF library...", "language": "Python", "pushed_at": "2026-05-08T..."},
...
]
```
### 2. `get_repo_info`
Get detailed information about a specific repository.
**Parameters:**
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `repo` | str | — | Full repo name (e.g., "py-pdf/pypdf") |
**Example response:**
```json
{
"name": "py-pdf/pypdf",
"stars": 9981,
"language": "Python",
"topics": ["pdf", "python", "pdf-parser"],
"open_issues": 156,
"description": "A pure-python PDF library..."
}
```
### 3. `analyze_issues`
Analyze open issues with quality filtering to find good contribution targets.
**Parameters:**
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `repo` | str | — | Full repo name |
| `min_score` | int | 35 | Minimum quality score (0-100) |
| `max_results` | int | 20 | Max issues to return |
**Quality scoring:**
- **0-20**: Spam/vague (typo fixes, feature requests without context)
- **20-40**: Low quality (minimal description, no labels)
- **40-60**: Medium quality (clear description, some discussion)
- **60-80**: High quality (well-described, active discussion, no assignee)
- **80-100**: Excellent (reproducer provided, maintainer involved)
**Merge probability:**
- `high`: Clearly described bug with reproducer, no assignee
- `medium`: Good feature request with discussion, well-scoped
- `low`: Vague issue, already being discussed by maintainers
**Example response:**
```json
[
{
"number": 3748,
"title": "Fix type hint for pypdf._utils.deprecation",
"score": 60,
"merge_probability": "high",
"reasons": ["Well-described (>200 chars)", "No assignee"],
"url": "https://github.com/py-pdf/pypdf/issues/3748"
}
]
```
### 4. `review_pr`
Review a pull request with quality gate and static analysis.
**Parameters:**
| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `pr_url` | str | — | Full PR URL |
| `repo` | str | — | Repo name |
| `number` | int | — | PR number |
**Quality Gate checks:**
- Min diff length (≥10 lines)
- Max diff size (≤50KB)
- Draft detection
- Static analysis warnings
**Example response:**
```json
{
"quality_gate": "PASSED",
"summary": "Small, focused fix. 1 file changed, 4 insertions, 3 deletions.",
"warnings": [],
"issues": []
}
```
---
## ⚙️ Configuration
File: `config.json`
```json
{
"stars_min": 1000,
"stars_max": 10000,
"quality_score_min": 35,
"cron_frequency": "daily",
"cron": {
"enabled": true,
"schedule": "0 8 * * *"
},
"target_repos": ["ruvnet/ruflo"],
"contributions": [],
"pipeline_history": []
}
```
Key settings:
| Field | Default | Description |
|-------|---------|-------------|
| `stars_min` | 1000 | Minimum stars for repo search |
| `stars_max` | 10000 | Maximum stars for repo search |
| `quality_score_min` | 35 | Minimum score for issue quality filter |
| `cron_frequency` | "daily" | Pipeline frequency (auto-adjusted by self-learning) |
| `target_repos` | [] | Specific repos to always monitor (overrides search) |
---
## 🤖 Usage with Autonomous Agents
This repository is designed for **AI agents with autonomous capabilities**. Below are ready-to-use prompts for different agents.
### Prerequisites for all agents
Before using any prompt, ensure:
1. The repository is cloned on the target machine
2. `gh` CLI is installed and authenticated
3. Python dependencies are installed
4. The MCP server path is correct (`/path/to/mcp-contributor`)
---
### → Claude Code
**Setup:**
```bash
# Configure MCP server in Claude Code
claude mcp add mcp-contributor \
--command python \
--args /path/to/mcp-contributor/mcp_server/server.py
```
**Prompt (copy-paste):**
> ```
> You have access to the MCP server at `mcp-contributor` with 4 tools: find_repos, get_repo_info, analyze_issues, review_pr.
>
> Your goal is to autonomously find and contribute to open-source projects.
>
> Step 1: Use find_repos(min_stars=1000, max_stars=10000, language="Python", limit=10) to find qualified repositories.
>
> Step 2: For each repo returned, use analyze_issues(repo="owner/name", min_score=50) to find high-quality issues.
> - Filter for issues with score >= 60 and merge_probability = "high"
> - Skip issues that are assigned, have vague descriptions, or are simple typo fixes
>
> Step 3: For the best issue found:
> a. Fork the repository using git
> b. Create a new branch: git checkout -b fix/issue-description
> c. Read the issue carefully and understand what needs to change
> d. Implement the fix following these rules:
> - Keep changes minimal and focused
> - Follow the project's coding style
> - Add tests if the project has a test suite
> - Update documentation if needed
> e. Run pre-push review: python /path/to/mcp-contributor/scripts/pre_push_review.py
> f. Fix any issues found by the review
> g. Commit with a clear message referencing the issue: "fix: description (closes #N)"
> h. Push to your fork
> i. Create a PR using gh CLI: gh pr create --repo owner/repo --title "..." --body "..."
> j. Use review_pr tool to verify PR quality
>
> Important rules:
> - NEVER contribute without quality gate passing (score >= 60, merge_probability = "high")
> - NEVER submit typo fixes or formatting-only changes
> - If no good issue is found, report that and stop
> - After creating a PR, monitor it for 24 hours and update if requested
> ```
---
### → Codex / OpenCode
**Setup:**
```bash
# Codex supports MCP natively
# Add the server in Codex settings or config
```
**Prompt (copy-paste):**
> ```
> You have access to an MCP server for GitHub PR automation.
>
> The MCP tools available are:
> - find_repos(min_stars, max_stars, language, limit) — find repositories
> - get_repo_info(repo) — get repository details
> - analyze_issues(repo, min_score, max_results) — find quality issues
> - review_pr(pr_url, repo, number) — review pull request quality
>
> Workflow for autonomous contribution:
>
> 1. DISCOVERY:
> Call find_repos(1000, 10000, "Python", 10) to get candidate repos.
> For each repo, call analyze_issues(repo, 50, 10) to find quality issues.
>
> 2. SELECTION:
> Choose the issue with:
> - score >= 60
> - merge_probability = "high"
> - No assignee
> - Well-described body (>200 characters)
> - Has recent activity (< 30 days)
>
> 3. IMPLEMENTATION:
> a. Fork the repo: gh repo fork owner/repo --clone
> b. Create branch: git checkout -b fix/issue-title
> c. Read the issue body and comments to understand the full context
> d. Study the relevant code section before making changes
> e. Implement the fix following these constraints:
> - One logical change per PR
> - Follow existing code style (run linter if available)
> - Include docstrings/comments where appropriate
> - Do NOT change formatting, whitespace, or unrelated code
> f. Run pre-push review: python /path/to/mcp-contributor/scripts/pre_push_review.py
> g. Fix any quality gate failures
> h. Commit: git commit -m "fix: description (closes #N)"
> i. Push: git push origin fix/issue-title
> j. Create PR: gh pr create --repo owner/repo --fill --label contribution
> k. Verify: call review_pr(pr_url, owner/repo, N)
>
> 4. REPORT:
> Return the PR URL and summary of what was done.
> Do NOT proceed if no high-quality issue is found.
> ```
---
### → QwenPaw Agent
**Setup:**
```bash
# QwenPaw can call Python scripts directly
# Schedule via cron:
qwenpaw cron create --agent-id default --type agent \
--name "mcp-contributor" \
--cron "0 8 * * *" \
--text "Run daily contribution pipeline: python /path/to/mcp-contributor/mcp_server/cron_pipeline.py"
```
**Prompt (copy-paste for agent definition):**
> ```
> You are an autonomous open-source contributor.
>
> Available scripts at /path/to/mcp-contributor/:
> - mcp_server/cron_pipeline.py (daily pipeline: scan → analyze → contribute)
> - mcp_server/pr_monitor.py (hourly monitor: check PRs → notify)
> - mcp_server/self_learn.py (self-learning: analyze → adjust)
> - scripts/pre_push_review.py (quality gate before pushing)
>
> Your operating rhythm:
>
> DAILY (08:00):
> 1. Run cron_pipeline.py with python
> 2. Wait for it to complete and analyze the output
> 3. If quality issues found (score >= 60, high merge probability):
> a. Pick the BEST issue (highest score + unassigned + well-described)
> b. Fork the repo: gh repo fork owner/repo --clone
> c. Create branch, implement fix following project conventions
> d. Run pre_push_review.py
> e. Commit, push, create PR via gh CLI
> f. Log the result in config.json under "contributions"
> 4. If no suitable issue found, report "No quality issues today"
> 5. Notify via Telegram if configured
>
> HOURLY:
> 1. Check all active PRs in config.json "contributions"
> 2. Use gh pr view to check status (merged/closed/changes_requested)
> 3. If status changed:
> - Merged → log success, update learnings
> - Closed → analyze reason, update quality filter
> - Changes requested → read comments, assess if update needed
> 4. Run self_learn.py after each check
> 5. Send Telegram notification on any status change
>
> Rules:
> - Quality OVER quantity. One high-quality PR > ten spam PRs.
> - Never contribute without the quality gate passing.
> - Learn from failures. If a PR is closed, analyze why and adjust.
> - If merge rate drops below 50%, increase quality threshold.
> ```
---
### → General MCP Client
**Server configuration:**
```json
{
"mcpServers": {
"mcp-contributor": {
"command": "python",
"args": ["/path/to/mcp-contributor/mcp_server/server.py"],
"env": {}
}
}
}
```
---
## 🔄 Pipeline Detail
### Daily Discovery (08:00)
```
1. Search repos (1k-10k stars, sorted by stars desc)
2. For each repo, fetch open issues
3. Quality-filter each issue (score 0-100)
4. Rank by score + merge_probability
5. Pick the best candidate
6. Fork → branch → implement → pre-push review → PR
7. Save to config.json contributions list
```
### Hourly Monitor (:00 every hour)
```
1. Read all PRs from config.json contributions
2. For each PR: gh pr view → check status
3. Detect changes: open → merged / closed / changes_requested
4. On change:
- Send Telegram notification
- Record in monitor_history.json
- Run self-learning loop
```
### Self-Learning (after each monitor)
```
1. Calculate merge rate (merged / total completed)
2. Assess health: excellent(>80%) / good(>50%) / fair(>30%) / poor(<30%)
3. Generate lessons learned for closed PRs
4. Auto-adjust quality threshold:
- Excellent → expand search (higher stars_max, lower min_score)
- Fair → tighten (higher quality_score_min)
- Poor → significant tightening + reduce frequency
5. Save suggestions for future runs
```
---
## 🧪 Development Guide
### Project Structure
```
mcp-contributor/
├── mcp_server/
│ ├── server.py # MCP server (Stdio transport, 4 tools)
│ ├── gh_utils.py # GitHub CLI wrapper helper
│ ├── cron_pipeline.py # Daily discovery + contribution pipeline
│ ├── pr_monitor.py # Hourly PR status monitor
│ └── self_learn.py # Self-learning and strategy adjustment
├── scripts/
│ ├── pre_push_review.py # Pre-push quality gate
│ ├── review_helpers.py # Shared helper functions
│ ├── pr_review_automation.py # PR automation utilities
│ └── telegram_notify.py # Telegram notification sender
├── config.json # Main configuration
├── learnings.json # Self-learning data store
├── SKILL.md # QwenPaw skill documentation
└── README.md # This file
```
### Extending the MCP Server
To add a new tool to `server.py`:
```python
@server.tool()
async def my_new_tool(param1: str, param2: int = 10) -> list:
"""Description of what this tool does."""
# Implementation
return [{"result": "data"}]
```
The tool is automatically registered via the MCP `@server.tool()` decorator pattern.
### Testing
```bash
# Test search
python -c "from mcp_server.gh_utils import search_repos; print(search_repos(1000, 5000, 'Python', 3))"
# Test analyze
python -c "from mcp_server.gh_utils import get_repo_issues, assess_issue_quality; issues = get_repo_issues('py-pdf/pypdf', 5); scores = [assess_issue_quality(i) for i in issues]; print(scores)"
# Test pre-push
python scripts/pre_push_review.py
```
---
## 📊 Current State
| Metric | Value |
|--------|-------|
| Contributions made | 2 |
| Open PRs | 1 (py-pdf/pypdf#3762) |
| Merge rate | Pending data |
| Pipeline frequency | Daily |
| Monitor frequency | Hourly |
---
## 📝 License
MIT — feel free to fork, modify, and use.
---
## 🙏 Credits
Built with:
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) — Model Context Protocol
- [GitHub CLI](https://cli.github.com/) — GitHub API access
- [ruvnet/ruflo](https://github.com/ruvnet/ruflo) — Inspiration for MCP tool patterns
- [QwenPaw](https://qwenpaw.ai) — Agent runtime for autonomous execution
