github-repo-mcp

An MCP (Model Context Protocol) server that lets any AI agent — Claude Desktop, Claude Code, Cursor — reason about a public GitHub repository directly, instead of the human manually reading READMEs, commit logs, and issue trackers.

Why this exists

Evaluating an unfamiliar repo ("is this actively maintained? is this issue actually beginner-friendly? what changed recently?") is repetitive manual work every developer does. This server turns that into four callable tools any MCP-compatible agent can use.

Tools

Setup

npm install
cp .env.example .env
# Add a GitHub personal access token to .env — raises the rate limit from 60/hr to 5000/hr.
# No special scopes needed for public repo data: https://github.com/settings/tokens
#
# ask_repo also needs, both free tier:
#   VOYAGE_API_KEY  — https://dashboard.voyageai.com/ (API Keys -> Create new key)
#   QDRANT_URL, QDRANT_API_KEY — https://cloud.qdrant.io/ (create a free cluster)
npm run build

Running locally with Claude Desktop

Add this to your Claude Desktop MCP config (claude_desktop_config.json):

{
  "mcpServers": {
    "github-repo-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/github-repo-mcp/build/index.js"],
      "env": { "GITHUB_TOKEN": "your_token_here" }
    }
  }
}

Restart Claude Desktop, then try: "Use github-repo-mcp to check the health of facebook/react and find me a good first issue."

Architecture notes

• GitHub API, not scraping — clean, documented, generously rate-limited with a token.
• Deterministic scoring, generative explanation — get_repo_health's score is a fixed formula (recency + issue triage + contributor diversity), not an LLM guess. This keeps the number reproducible; an LLM (in the calling agent) can narrate why on top of it.
• Mislabel detection in find_good_first_issues — real "good first issue" labels are often wrong. The tool checks body length, red-flag keywords (architecture, migration, security), and comment count to catch issues that are mislabeled, not just present them at face value.

Demo

See docs/demo.md for a real (not mocked) protocol exchange against facebook/react, including the embeddings-based ask_repo retrieving the correct answer for a query that shares no words with the source text.

How ask_repo retrieval works

ask_repo started as keyword-window retrieval over the README (see git history) and was upgraded to embeddings-based RAG, implemented in src/rag.ts:

1. On first query for a repo, chunk README + docs/*.md (top-level, cap 15 files) + top 8 most-discussed issue threads (title + body, ~500-word chunks, 50-word overlap)
2. Embed each chunk with Voyage AI (voyage-3.5-lite)
3. Store vectors in Qdrant Cloud, one collection per repo (repo_<owner>_<name>)
4. On every query: embed the question, cosine-similarity search top-5 chunks
5. Subsequent queries for the same repo skip re-indexing (checked via the collection's points_count) — only the query itself gets embedded

Why embeddings over keyword matching: keyword overlap requires literal shared words — "how do I install React?" and a README section titled "Getting Started" share zero words and would never match. Embeddings place semantically similar text near each other in vector space regardless of exact wording, so retrieval survives paraphrasing and synonyms — the actual failure mode keyword search hits in practice.

Known simplifications (marked ponytail: in src/rag.ts), each with a stated upgrade path:

• Issue threads index title+body only, not the full comment discussion (avoids one extra API call per issue) — fetch /issues/{n}/comments if answers need to reflect resolution discussion, not just the original report.
• Chunk sizing uses word count as a token-count approximation, not a real tokenizer.
• No staleness check — a repo indexed once stays indexed even if its docs change. Add a TTL or a pushed_at check against the stored index if content goes stale.

License

MIT