🤖 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

git clone https://github.com/nguyenthanhthe/mcp-contributor.git
cd mcp-contributor

2. Install dependencies

pip install requests            # for Telegram notifications
pip install mcp[cli]            # optional — for running MCP server directly

3. Configure GitHub CLI

gh auth login
# Must have scopes: repo, gist, read:org, workflow

4. Configure Telegram (optional)

python scripts/telegram_notify.py setup <BOT_TOKEN> <CHAT_ID>

5. Verify setup

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:

[
  {"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:

{
  "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:

[
  {
    "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:

{
  "quality_gate": "PASSED",
  "summary": "Small, focused fix. 1 file changed, 4 insertions, 3 deletions.",
  "warnings": [],
  "issues": []
}

⚙️ Configuration

File: config.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:

The repository is cloned on the target machine
gh CLI is installed and authenticated
Python dependencies are installed
The MCP server path is correct (/path/to/mcp-contributor)

→ Claude Code

Setup:

# 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:

# 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:

# 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:

{
  "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:

@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

# 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 — Model Context Protocol
GitHub CLI — GitHub API access
ruvnet/ruflo — Inspiration for MCP tool patterns
QwenPaw — Agent runtime for autonomous execution

MCP Servers

🤖 MCP Contributor

📦 Architecture

Components

🚀 Installation

Prerequisites

1. Clone

2. Install dependencies

3. Configure GitHub CLI

4. Configure Telegram (optional)

5. Verify setup

🔧 MCP Tools Reference

1. `find_repos`

2. `get_repo_info`

3. `analyze_issues`

4. `review_pr`

⚙️ Configuration

🤖 Usage with Autonomous Agents

Prerequisites for all agents

→ Claude Code

→ Codex / OpenCode

→ QwenPaw Agent

→ General MCP Client

🔄 Pipeline Detail

Daily Discovery (08:00)

Hourly Monitor (:00 every hour)

Self-Learning (after each monitor)

🧪 Development Guide

Project Structure

Extending the MCP Server

Testing

📊 Current State

📝 License

🙏 Credits

安装包（如果需要）

Cursor 配置 (mcp.json)

🤖 MCP Contributor

📦 Architecture

Components

🚀 Installation

Prerequisites

1. Clone

2. Install dependencies

3. Configure GitHub CLI

4. Configure Telegram (optional)

5. Verify setup

🔧 MCP Tools Reference

1. find_repos

2. get_repo_info

3. analyze_issues

4. review_pr

⚙️ Configuration

🤖 Usage with Autonomous Agents

Prerequisites for all agents

→ Claude Code

→ Codex / OpenCode

→ QwenPaw Agent

→ General MCP Client

🔄 Pipeline Detail

Daily Discovery (08:00)

Hourly Monitor (:00 every hour)

Self-Learning (after each monitor)

🧪 Development Guide

Project Structure

Extending the MCP Server

Testing

📊 Current State

📝 License

🙏 Credits

安装包 （如果需要）

Cursor 配置 (mcp.json)

1. `find_repos`

2. `get_repo_info`

3. `analyze_issues`

4. `review_pr`

安装包（如果需要）