Back to search
repo-context-mcp
MCP serverGitHub
MCP server: repo map, code search, and token-aware context packs for AI coding agents
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/nduc99911--repo-context-mcp)HTML
<a href="/listings/nduc99911--repo-context-mcp"><img src="/api/listings/nduc99911--repo-context-mcp/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
# 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+**.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 220 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- # repo-context-mcp
- **MCP server that helps AI coding agents understand a repository** — without dumping the entire monorepo into the prompt.
- [](https://github.com/nduc99911/repo-context-mcp/actions/workflows/ci.yml)
- [](LICENSE)
- [](package.json)
- [](https://modelcontextprotocol.io)
- Works with **Codex**, **Claude Code**, **Cursor**, **Cline**, and any client that speaks [Model Context Protocol](https://modelcontextprotocol.io).
- ## Why
- AI agents waste tokens re-walking `node_modules`, missing entrypoints, or pasting random files. **repo-context-mcp** exposes three focused tools:
- | Tool | Purpose |
- | --- | --- |
- | `repo_map` | Lightweight tree + manifests/entrypoints |
- | `search_code` | Fast substring search with path:line hits |
- | `pack_context` | Token-budgeted markdown pack for LLM prompts |
- Local-only. No cloud. No telemetry. Stdio transport.
- ## Install
- ```bash
- # 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)
- ```bash
- 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`:
- ```bash
- npx repo-context-mcp map .
- npx repo-context-mcp pack . --focus auth
- ```
- ## MCP client config
- ### Claude Desktop / Claude Code
- ```json
- {
- "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
- ```bash
- REPO_CONTEXT_ROOT=/path/to/repo node /path/to/repo-context-mcp/dist/server.js
- ```
- From this repository after build:
- ```bash
- 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:
- | Variable | Meaning |
- | --- | --- |
- | `REPO_CONTEXT_ROOT` | Default repository root when tools omit `root` |
- Each tool also accepts an explicit `root` argument.
- ## Tools
- ### `repo_map`
- ```text
- 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`
- ```text
- query: string
- root?: string
- max_results?: number # default 50
- case_sensitive?: boolean
- ```
- Substring search across source-like extensions.
- ### `pack_context`
- ```text
- 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:
- ```ts
- import {
- buildRepoMap,
- formatRepoMap,
- searchCode,
- packContext,
- } from "repo-context-mcp";
- const map = buildRepoMap({ root: process.cwd() });
- console.log(formatRepoMap(map));
- const hits = searchCode({ root: process.cwd(), query: "TODO" });
- const pack = packContext({
- root: process.cwd(),
- focus: ["auth"],
- maxTokens: 8000,
- });
- console.log(pack.markdown);
- ```
- ## Demo (no MCP client)
- ```bash
- npm install
- npm test
- npm run build
- # map the sample tree
- node --input-type=module -e "import { buildRepoMap, formatRepoMap } from './dist/index.js'; console.log(formatRepoMap(buildRepoMap({ root: 'examples/sample-repo' })));"
- ```
- ## Security
- - Reads files only under the requested `root`.
- - Does not execute project code.
- - Skips common vendor dirs and obvious binaries.
- - Still: only point it at repositories you trust.
- See [SECURITY.md](SECURITY.md).
- ## Project status
- **v0.1.1** — MCP server + CLI + gitignore + PR Action.
- Roadmap:
- - [x] `.gitignore` respect
- - [x] CLI (`map` / `search` / `pack`) + `--json`
- - [x] GitHub Action: pack context on each PR
- - [ ] Optional ripgrep backend for large monorepos
- - [ ] Baseline symbol index (tree-sitter) for `find_symbol`
- - [ ] Configurable ignore file (`.repo-contextignore`)
- ## Contributing
- See [CONTRIBUTING.md](CONTRIBUTING.md).
- ```bash
- npm install
- npm test
- npm run lint
- npm run build
- ```
- ## License
- [MIT](LICENSE) © Nguyen Duc
- ---
- Built as a real maintainer / agent-tooling utility for the MCP ecosystem — not a placeholder repo. Issues and PRs welcome.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.