repo-context-mcp

MCP server that helps AI coding agents understand a repository — without dumping the entire monorepo into the prompt.

Works with Codex, Claude Code, Cursor, Cline, and any client that speaks Model Context Protocol.

Why

AI agents waste tokens re-walking node_modules, missing entrypoints, or pasting random files. repo-context-mcp exposes three focused tools:

Local-only. No cloud. No telemetry. Stdio transport.

Install

# run from source
git clone https://github.com/nduc99911/repo-context-mcp.git
cd repo-context-mcp
npm install
npm run build

# or via npx (after publish)
npx -y repo-context-mcp

Requires Node.js 18+.

CLI (no MCP client)

npm run build

# repository map
node dist/cli.js map .
node dist/cli.js map examples/sample-repo

# search
node dist/cli.js search login examples/sample-repo

# token-aware pack
node dist/cli.js pack . --focus auth,api --max-tokens 8000

# JSON for scripts / CI
node dist/cli.js map . --json
node dist/cli.js pack . --focus src --json

After global install / npx:

npx repo-context-mcp map .
npx repo-context-mcp pack . --focus auth

MCP client config

Claude Desktop / Claude Code

{
  "mcpServers": {
    "repo-context": {
      "command": "npx",
      "args": ["-y", "repo-context-mcp"],
      "env": {
        "REPO_CONTEXT_ROOT": "/absolute/path/to/your/repo"
      }
    }
  }
}

Cursor

Settings → MCP → add server with command npx and args ["-y", "repo-context-mcp"].

Codex / generic stdio

REPO_CONTEXT_ROOT=/path/to/repo node /path/to/repo-context-mcp/dist/server.js

From this repository after build:

npm run build
node dist/cli.js serve
# or: node dist/server.js

See also examples/mcp-config.claude.json and examples/mcp-config.local.json.

Optional env:

Each tool also accepts an explicit root argument.

Tools

repo_map

root?: string
max_depth?: number      # default 6
max_entries?: number    # default 400

Returns a markdown tree, file count, and likely entrypoints (package.json, README.md, src/index.ts, AGENTS.md, …). Skips node_modules, .git, dist, etc.

search_code

query: string
root?: string
max_results?: number    # default 50
case_sensitive?: boolean

Substring search across source-like extensions.

pack_context

root?: string
focus?: string[]        # keywords / path fragments to prioritize
max_tokens?: number     # default 12000 (approx)
max_files?: number      # default 40

Ranks files (entrypoints + focus matches), respects a rough token budget (~4 chars/token), and returns a single markdown document ready to paste into an agent prompt or PR review.

Library API

You can use the core without MCP:

import {
  buildRepoMap,
  formatRepoMap,
  searchCode,
  packContext,
} from "repo-context-mcp";

const map = buildRepoMap({ root: process.cwd() });
console.log(formatRepoMap(map));