OSS Contribution Advisor — MCP Server

An MCP server that helps developers find open-source issues genuinely worth contributing to — not just issues tagged "good first issue," but ones that match their interests, come from a healthy/responsive repo, and have real downstream impact.

Why this exists

Existing "find your first OSS issue" tools filter by label only. This server answers three questions a label can't:

Does this match what I actually want to work on? — semantic search over open issues (local sentence-embeddings), not keyword/label matching.
Is this repo actually a good place to spend my time? — health score based on maintainer responsiveness and first-time-contributor merge rate.
Does this repo matter? — ranks by real downstream reach via libraries.io's dependents graph (how many other packages depend on this one) — not just GitHub stars.

Tools

Tool	Purpose
`match_issues_semantically`	Free-text interest → ranked list of matching open issues, using local sentence-embeddings.
`score_repo_fit`	Given a repo, scores maintainer responsiveness, PR merge rate, doc completeness, and recent activity into a 0-100 fit score.
`find_impact_multiplier_repos`	Ranks a given repo shortlist — or self-searches by language if none given — by real downstream dependents (libraries.io), falling back to a stars/forks proxy if unconfigured.

Caching design

Two genuinely different cache policies, because the underlying data has two different change patterns — using one TTL for everything would either waste API calls (too short) or serve stale data (too long):

Cache	Key	Lifetime	Why
Search results (`match_issues_semantically`)	GitHub search query string	20 min TTL	Open issues genuinely change often, but repeated calls in a short window shouldn't re-hit the API.
Issue embeddings (`match_issues_semantically`)	`(issue_id, updated_at)`	No TTL — invalidated by `updated_at` changing	Unedited issue text is embedded exactly once, ever, and reused across every user/query that pulls it into their candidate pool. If the issue is edited, `updated_at` changes, so the cache key changes and it's naturally recomputed — no manual invalidation logic needed.
Repo impact data (`find_impact_multiplier_repos`)	repo `full_name`	24h TTL	Dependents counts / stars change slowly; no need to hit libraries.io or GitHub on every call.

All caching is a single local SQLite file (~/.cache/oss-contribution-advisor-mcp/cache.sqlite3 by default, override with CACHE_DB_PATH) — no external cache service required, so the server stays a single downloadable package.

libraries.io integration (Tool 3)

GitHub's API only exposes stars/forks — social proof, not real usage. libraries.io aggregates package metadata across ~30 registries (PyPI, npm, crates.io, RubyGems, etc.) and tracks, for each published package, how many other packages declare it as a dependency.

find_impact_multiplier_repos calls GET https://libraries.io/api/github/{owner}/{repo}/projects to find every package linked to a GitHub repo and sums their dependents_count. A repo with modest stars can still be a load-bearing dependency for tens of thousands of other packages — that's a stronger "does my fix matter" signal than stars, and libraries.io is the only free source for it.

If LIBRARIES_IO_API_KEY is unset, or a repo isn't published to any registry (e.g. it's an app, not a library), the tool degrades gracefully to a GitHub stars/forks proxy rather than failing — every result includes a signal_source field so it's clear which one was used.

Get a free key at https://libraries.io/api (60 req/min).

Setup

git clone https://github.com/sonali1103/oss-contribution-advisor-mcp
cd oss-contribution-advisor-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
cp .env.example .env   # add GITHUB_TOKEN and LIBRARIES_IO_API_KEY

Running

As an HTTP-streamable server (default — for remote hosting):

oss-contribution-advisor-mcp
# or: python -m oss_contribution_advisor.server
# serves on http://0.0.0.0:8000 by default (override with MCP_PORT)

Over stdio (for local Claude Desktop use):

MCP_TRANSPORT=stdio oss-contribution-advisor-mcp
# or: fastmcp run -m oss_contribution_advisor.server

Connect to Claude Desktop (stdio)

{
  "mcpServers": {
    "oss-contribution-advisor": {
      "command": "oss-contribution-advisor-mcp",
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

Connect to a remote HTTP deployment

Once deployed (see below), point any MCP-HTTP-capable client at:

https://<your-deployment-url>/mcp

FastMCP Cloud: connect this GitHub repo directly at fastmcp.cloud — it detects pyproject.toml and src/oss_contribution_advisor/server.py and deploys it as an HTTP-streamable server automatically. Set GITHUB_TOKEN and LIBRARIES_IO_API_KEY as environment variables in the deployment dashboard.

Example queries to try

"I'm a Python developer who likes async code and API design — find me an issue to work on." → chains match_issues_semantically → score_repo_fit on the surfaced repos
"Is encode/httpx a good repo for a first-time contributor?" → calls score_repo_fit directly
"Between httpx, django, and fastapi, which has the most real-world reach?" → calls find_impact_multiplier_repos with candidate_repos
"Give me high-impact Python repos to contribute to." → calls find_impact_multiplier_repos with language="python" (self-search mode)

Known simplifications

Built as a scoped demo project, not a production tool at scale:

Merge rate in score_repo_fit is computed over a sample of recently closed PRs, not strictly filtered to first-time contributors (that needs a per-author commit-history lookup per PR — expensive for a 30-PR sample).
SQLite cache is fine for a single-process server; a multi-instance deployment would want Redis/Postgres instead to share cache state.
No auth on the HTTP endpoint — fine for a personal/demo deployment, add an API key or OAuth layer before exposing this publicly at scale.

Stack

fastmcp — MCP server framework (stdio + HTTP-streamable transport)
sentence-transformers (all-MiniLM-L6-v2) — local embeddings, no API key needed
GitHub REST API — live issue/repo data
libraries.io API — downstream dependents data
SQLite — local caching layer