oss-scout

An MCP server that finds genuinely-contributable open source issues — the kind that are actually unclaimed, not the kind sitting under 6 duplicate pull requests.

Why

The good first issue label on popular Python repos is currently swarmed. Searching pandas, FastAPI, Poetry, MLflow, and Apache Airflow for open, labeled issues turned up the same pattern every time: a real, well-scoped bug with zero comments — and 2 to 10 open or merged PRs already racing to fix it, likely from other AI agents running the same search. One Poetry maintainer's comment on a contested issue put it exactly right:

"Something about this issue is astonishingly attractive to everyone and their bots. Humans and AI alike: check for open pull requests already addressing this before opening another one."

oss-scout automates that check. It searches for candidate issues, cross-references each one against existing PRs in the same repo, and scores what's left by how contributable it actually looks — so a fresh contributor (or an agent acting on their behalf) doesn't waste a first PR racing a pile of duplicates.

What it does

Given a label (and optionally a language or a list of repos), oss-scout:

1. Searches for open, unassigned issues matching the label
2. For each one, searches for PRs in the same repo that reference the issue number, to catch ones already being worked on
3. Checks the repo's health — star count, last-push date, archived status — to flag abandoned or suspiciously small/unvetted repos
4. Scores every candidate and returns them ranked, with human-readable reasons for the score

score_issue(issue, contested=False, repo_health=healthy) → score=110
  reasons: ["no comments yet, likely unclaimed"]

score_issue(issue, contested=True, repo_health=healthy) → score=20
  reasons: ["3 existing PR(s) already reference this issue"]

Architecture

gh_client.py   — thin, injectable wrapper around the `gh` CLI (no direct API/token handling; reuses whatever `gh auth login` session is already active)
models.py      — Issue, RepoHealth, ScoutedIssue (pydantic)
scoring.py     — pure scoring function: (issue, contention, repo health) → score + reasons
scout.py       — IssueScout: orchestrates search → contention check → scoring → ranking
server.py      — MCP server exposing scout.py as tools via FastMCP

GhClient takes an injectable command runner, so the whole test suite runs against fakes — no gh install or network access needed in CI, only for actually running the server.

Usage as an MCP server

Requires the GitHub CLI installed and authenticated (gh auth login).

pip install -e .

Add to your MCP client config (e.g. Claude Desktop's claude_desktop_config.json, or Claude Code's MCP settings):

{
  "mcpServers": {
    "oss-scout": {
      "command": "oss-scout"
    }
  }
}

This exposes two tools:

• find_contributable_issues(label, language, repos, limit) — ranked list of scored candidates
• check_repo_health(repo) — star count, last push, archived status for one repo

Running directly

python -m oss_scout.server

Development

pip install -e ".[dev]"
ruff check .
mypy src
pytest --cov=oss_scout

Known limitations

• "Contested" detection works by searching PR titles/bodies for the literal issue number in the same repo. It's a heuristic (matching how this exact check was done manually before this tool existed), not a precise linked-PR lookup — it can occasionally miss or false-positive.
• Scoring heuristics are intentionally simple and tunable; they encode lessons from one round of manual issue-hunting, not a rigorous study.

License

MIT