Back to portfolio

Developer tooling · 4 min read

github-repo-mcp: letting an AI explore any GitHub repo without cloning it by hand

A small MCP server that clones, maps, searches and reads any repository on demand, with a local cache and a symbol map built with tree-sitter.

  • MCP
  • TypeScript
  • Bun
  • tree-sitter
  • ripgrep

When an assistant needs to understand a codebase it does not have locally, the usual options are pasting files or cloning by hand. I wanted something better: point the assistant at owner/repo and let it explore, the way a developer would. So I wrote github-repo-mcp, a local Model Context Protocol server.

ArchitectureThe server runs over stdio. Repos are cloned once and reused from a local cache.

Request path

  1. Claude
    MCP client
  2. github-repo-mcp
    stdio server, written in TypeScript on Bun
  3. Local clone cache
    ~/.cache/github-repo-mcp/owner/repo
  4. GitHub
    Cloned once, pulled on refresh

Five tools

  1. load_repo
    Clone or reuse, return a summary
  2. get_repo_map
    Files and exported symbols
  3. grep
    Regex search with context
  4. read_file
    A file or a line range
  5. refresh_repo
    Pull latest, invalidate the map

How it works

  • load_repo clones a repo (or reuses the cached copy) and returns languages, file count, a top-level tree and a README excerpt, enough to decide where to look next.
  • get_repo_map builds a structural map of paths and exported symbols. TypeScript gets a fast extraction path, and other languages such as Python are parsed with tree-sitter.
  • grep uses ripgrep for speed and falls back to a pure-JS search when ripgrep is not installed.
  • A GitHub token is optional and only needed for private repos. Path guards keep reads inside the cloned repo.

The workflow it enables

Load the repo, read the map to find the right module, grep for the call sites, then read only the lines that matter. The assistant spends its context on understanding the code and not on scrolling through it.

It is a small server with a deliberately small surface: five tools, one cache directory, and tests around the guards and the parser.