repo-insight-mcp

An MCP server that gives an AI agent read-only, structured access to a GitHub repository.

Built for the case where an agent has to reason about a codebase nobody on the team wrote: a legacy service being migrated, a dependency audit, a repo you have been handed on day one. The agent gets six tools instead of a shell and a prayer.

Written against the Model Context Protocol Python SDK v2 (MCPServer).

Why these six tools

An agent exploring an unfamiliar repository asks the same questions in the same order, so the tools are shaped around that sequence rather than around GitHub's API surface.

list_dependencies is the one that earns its place. It walks the tree, finds every requirements.txt, pyproject.toml, package.json, pom.xml, go.mod and Gemfile, parses each one and returns a single normalised list:

{
  "ecosystems": ["maven", "npm", "pypi"],
  "count": 47,
  "dependencies": [
    {"name": "httpx", "version": ">=0.27", "ecosystem": "pypi",
     "source_file": "requirements.txt", "scope": "runtime"},
    {"name": "org.springframework:spring-core", "version": "5.3.39",
     "ecosystem": "maven", "source_file": "service/pom.xml", "scope": "runtime"}
  ],
  "problems": []
}

The agent does not need to know that Maven nests coordinates in XML and npm uses a flat object. A manifest that fails to parse lands in problems and the rest of the results still come back, because one broken file in a monorepo should not fail the whole call.

Related MCP server: atelier-busco-github-mcp

Install

git clone https://github.com/viradm/repo-insight-mcp
cd repo-insight-mcp
pip install -e ".[dev]"

Python 3.11 or newer.

Configure

Add it to any MCP client. For Claude Desktop, in claude_desktop_config.json:

{
  "mcpServers": {
    "repo-insight": {
      "command": "repo-insight-mcp",
      "env": { "GITHUB_TOKEN": "ghp_your_token_here" }
    }
  }
}

For Claude Code:

claude mcp add repo-insight --env GITHUB_TOKEN=ghp_... -- repo-insight-mcp

Or run it directly over stdio:

GITHUB_TOKEN=ghp_... python -m repo_insight_mcp

The token

Everything except search_code works unauthenticated, but GitHub allows only 60 requests an hour that way and a single agent run will spend them. A classic token with the public_repo scope raises the limit to 5000 and enables code search. Set GITHUB_TOKEN or GH_TOKEN.

Design notes

Caching. An agent chaining tool calls asks for the same tree three times in a row. Responses are cached in memory with a 300 second TTL, which is long enough for a conversation and short enough that a push mid-session is picked up. Override with REPO_INSIGHT_TTL.

Rate limits. A secondary limit that resets within five seconds is waited out and retried once. A primary limit resets in minutes, so it is raised immediately as a RateLimited error naming the token variable, rather than hanging the agent on a call that cannot succeed.

Truncation is explicit. read_file caps at 40 KB by default and returns truncated: true with the real byte count. list_tree returns matched next to returned, so an agent can tell "there are 12 Python files" from "there are 400 and you are looking at 300 of them". Silently returning a partial answer that looks complete is how agents reach confident wrong conclusions.

Vendored code is skipped. node_modules and vendor directories are excluded from the dependency walk. Other people's dependencies are not this repository's dependencies.

Errors are typed. RepoNotFound, RateLimited and GitHubError are distinct, and tool-facing failures are raised as ToolError so the client gets a usable message instead of a traceback.

Tests

pytest

51 tests, no network. HTTP is mocked with respx, so the suite covers the paths that are awkward to reach against the live API: a 404, an exhausted primary rate limit, a secondary limit that retries and then succeeds, a cache hit, a cache expiry, invalid UTF-8 in a file, a directory passed where a file was expected, and a malformed manifest sitting next to a valid one.

The server tests call tools through mcp.call_tool, the same path an MCP client takes, so the registered schemas are exercised rather than just the Python functions underneath them.

Licence

MIT