repohunt

Grounded GitHub repo discovery as an MCP server. Your AI agent expands one intent into several keyword queries; repohunt fires them at GitHub's live Search API, dedupes and ranks the hits, and returns clean structured evidence (a trimmed README excerpt plus metadata) for the agent to judge.

No embeddings. No corpus. No backend. No LLM inside the server. All the intelligence lives in the agent you're already paying for, so repohunt costs nothing to run and nothing to use beyond your own GitHub rate limit.

Why

When you start a feature, the right first move is often "find a repo to fork, study, or avoid" rather than building from scratch. GitHub's native search is a flat keyword list with no judgment. Thankfully, GitHub already maintains the keyword index; the calling agent supplies the query variety on the way in and the ranking judgment on the way out.

While keyword search has a somewhat weak intent-recall than say semantic search, this tool narrows the gap by (a) searching README bodies, not just names and descriptions, and (b) firing 4-8 agent-expanded query variations per call.

Quick start

1. Get a GitHub token (read-only)

A token raises your search rate limit from ~10/min (unauthenticated, degraded) to 30/min. Public-repo read needs no scopes at all.

Classic token (simplest):

1. Open https://github.com/settings/tokens/new
2. Note: repohunt. Expiration: your choice.
3. Select NO scopes. Public read needs none.
4. Generate and copy the ghp_... token.

Fine-grained token (most locked-down): open https://github.com/settings/personal-access-tokens/new, set Repository access to Public repositories (read-only) with no account permissions.

The token only ever lives in your MCP host config on your machine. repohunt never sends it anywhere except api.github.com.

2. Add repohunt to your MCP host

Claude Desktop: open Settings > Developer > Edit Config, then add:

{
  "mcpServers": {
    "repohunt": {
      "command": "npx",
      "args": ["-y", "repohunt"],
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    }
  }
}

Restart the host. You should see find_repos in the tool list. The same command/args/env shape works for Cursor, Claude Code, or any MCP host.

If GITHUB_TOKEN is missing, repohunt exits immediately with a message telling you exactly how to fix it. It never runs silently unauthenticated.

The find_repos tool

One tool. Your agent calls it; you don't.

Input

| Field | Type | Required | Notes | |---|---|---|---| | queries | string[] | yes | Keyword search strings. The agent expands ONE intent into 4-8 varied queries (synonyms, library names, restatements). More variety = better recall. | | language | string | no | GitHub language filter, e.g. "typescript". | | min_stars | integer | no | Drop repos below this star count. Default 0. | | max_results | integer | no | Enriched candidates to return. Default 8, hard cap 15. |

Output: structured JSON. A list of candidates, each with full_name, url, description, readme_excerpt, stars, forks, open_issues, last_pushed, license, primary_language, and matched_queries (which of your queries surfaced it). Plus optional notes (hints) and degraded (set when rate limits made the results partial). It returns evidence, not a verdict. Ranking is the agent's job.

Example. You ask your agent: "find me a rate-limiting middleware for Express." The agent expands the intent and calls:

{
  "queries": [
    "express rate limit middleware",
    "express-rate-limit",
    "api throttling node",
    "request throttling express",
    "leaky bucket rate limiter node"
  ],
  "max_results": 5
}

repohunt returns (trimmed):

{
  "candidates": [
    {
      "full_name": "express-rate-limit/express-rate-limit",
      "url": "https://github.com/express-rate-limit/express-rate-limit",
      "description": "Basic rate-limiting middleware for the Express web server",
      "readme_excerpt": "# express-rate-limit\n\nBasic rate-limiting middleware for Express. Use to limit repeated requests to public APIs and endpoints such as password reset...",
      "stars": 3000,
      "forks": 320,
      "open_issues": 4,
      "last_pushed": "2026-05-20T12:00:00Z",
      "license": "MIT",
      "primary_language": "TypeScript",
      "matched_queries": ["express rate limit middleware", "express-rate-limit", "request throttling express"]
    }
  ]
}

The agent reads the excerpts and tells you which repo to fork, study, or avoid.

How it works

queries[]  ->  fan-out search (in:name,description,readme, bounded concurrency)
           ->  pool & dedupe (record matched_queries)  ->  cheap pre-rank  ->  TRIM
           ->  fetch READMEs for the survivors ONLY  ->  denoise + excerpt
           ->  return structured evidence              (no model call, ever)

Bounded concurrency keeps GitHub's secondary rate limits happy; READMEs are fetched only for the trimmed candidate set (never the whole pool); a rate-limited query or README degrades to partial results with a degraded note instead of failing.

Development

npm install
npm run build       # tsc -> dist/
npm test            # vitest, mocked + deterministic
npm run typecheck

# optional: live smoke test against the real GitHub API
RUN_LIVE=1 GITHUB_TOKEN=ghp_... npm test

License

MIT. See LICENSE.