Skip to content
Back to search

repo-context-mcp

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/nduc99911--repo-context-mcp/badge.svg)](/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)

  1. # repo-context-mcp
  2. **MCP server that helps AI coding agents understand a repository** — without dumping the entire monorepo into the prompt.
  3. [![CI](https://github.com/nduc99911/repo-context-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/nduc99911/repo-context-mcp/actions/workflows/ci.yml)
  4. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  5. [![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)
  6. [![MCP](https://img.shields.io/badge/MCP-stdio-purple)](https://modelcontextprotocol.io)
  7. Works with **Codex**, **Claude Code**, **Cursor**, **Cline**, and any client that speaks [Model Context Protocol](https://modelcontextprotocol.io).
  8. ## Why
  9. AI agents waste tokens re-walking `node_modules`, missing entrypoints, or pasting random files. **repo-context-mcp** exposes three focused tools:
  10. | Tool | Purpose |
  11. | --- | --- |
  12. | `repo_map` | Lightweight tree + manifests/entrypoints |
  13. | `search_code` | Fast substring search with path:line hits |
  14. | `pack_context` | Token-budgeted markdown pack for LLM prompts |
  15. Local-only. No cloud. No telemetry. Stdio transport.
  16. ## Install
  17. ```bash
  18. # run from source
  19. git clone https://github.com/nduc99911/repo-context-mcp.git
  20. cd repo-context-mcp
  21. npm install
  22. npm run build
  23. # or via npx (after publish)
  24. npx -y repo-context-mcp
  25. ```
  26. Requires **Node.js 18+**.
  27. ## CLI (no MCP client)
  28. ```bash
  29. npm run build
  30. # repository map
  31. node dist/cli.js map .
  32. node dist/cli.js map examples/sample-repo
  33. # search
  34. node dist/cli.js search login examples/sample-repo
  35. # token-aware pack
  36. node dist/cli.js pack . --focus auth,api --max-tokens 8000
  37. # JSON for scripts / CI
  38. node dist/cli.js map . --json
  39. node dist/cli.js pack . --focus src --json
  40. ```
  41. After global install / `npx`:
  42. ```bash
  43. npx repo-context-mcp map .
  44. npx repo-context-mcp pack . --focus auth
  45. ```
  46. ## MCP client config
  47. ### Claude Desktop / Claude Code
  48. ```json
  49. {
  50. "mcpServers": {
  51. "repo-context": {
  52. "command": "npx",
  53. "args": ["-y", "repo-context-mcp"],
  54. "env": {
  55. "REPO_CONTEXT_ROOT": "/absolute/path/to/your/repo"
  56. }
  57. }
  58. }
  59. }
  60. ```
  61. ### Cursor
  62. Settings → MCP → add server with command `npx` and args `["-y", "repo-context-mcp"]`.
  63. ### Codex / generic stdio
  64. ```bash
  65. REPO_CONTEXT_ROOT=/path/to/repo node /path/to/repo-context-mcp/dist/server.js
  66. ```
  67. From this repository after build:
  68. ```bash
  69. npm run build
  70. node dist/cli.js serve
  71. # or: node dist/server.js
  72. ```
  73. See also `examples/mcp-config.claude.json` and `examples/mcp-config.local.json`.
  74. Optional env:
  75. | Variable | Meaning |
  76. | --- | --- |
  77. | `REPO_CONTEXT_ROOT` | Default repository root when tools omit `root` |
  78. Each tool also accepts an explicit `root` argument.
  79. ## Tools
  80. ### `repo_map`
  81. ```text
  82. root?: string
  83. max_depth?: number # default 6
  84. max_entries?: number # default 400
  85. ```
  86. Returns a markdown tree, file count, and likely entrypoints (`package.json`, `README.md`, `src/index.ts`, `AGENTS.md`, …). Skips `node_modules`, `.git`, `dist`, etc.
  87. ### `search_code`
  88. ```text
  89. query: string
  90. root?: string
  91. max_results?: number # default 50
  92. case_sensitive?: boolean
  93. ```
  94. Substring search across source-like extensions.
  95. ### `pack_context`
  96. ```text
  97. root?: string
  98. focus?: string[] # keywords / path fragments to prioritize
  99. max_tokens?: number # default 12000 (approx)
  100. max_files?: number # default 40
  101. ```
  102. 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.
  103. ## Library API
  104. You can use the core without MCP:
  105. ```ts
  106. import {
  107. buildRepoMap,
  108. formatRepoMap,
  109. searchCode,
  110. packContext,
  111. } from "repo-context-mcp";
  112. const map = buildRepoMap({ root: process.cwd() });
  113. console.log(formatRepoMap(map));
  114. const hits = searchCode({ root: process.cwd(), query: "TODO" });
  115. const pack = packContext({
  116. root: process.cwd(),
  117. focus: ["auth"],
  118. maxTokens: 8000,
  119. });
  120. console.log(pack.markdown);
  121. ```
  122. ## Demo (no MCP client)
  123. ```bash
  124. npm install
  125. npm test
  126. npm run build
  127. # map the sample tree
  128. node --input-type=module -e "import { buildRepoMap, formatRepoMap } from './dist/index.js'; console.log(formatRepoMap(buildRepoMap({ root: 'examples/sample-repo' })));"
  129. ```
  130. ## Security
  131. - Reads files only under the requested `root`.
  132. - Does not execute project code.
  133. - Skips common vendor dirs and obvious binaries.
  134. - Still: only point it at repositories you trust.
  135. See [SECURITY.md](SECURITY.md).
  136. ## Project status
  137. **v0.1.1** — MCP server + CLI + gitignore + PR Action.
  138. Roadmap:
  139. - [x] `.gitignore` respect
  140. - [x] CLI (`map` / `search` / `pack`) + `--json`
  141. - [x] GitHub Action: pack context on each PR
  142. - [ ] Optional ripgrep backend for large monorepos
  143. - [ ] Baseline symbol index (tree-sitter) for `find_symbol`
  144. - [ ] Configurable ignore file (`.repo-contextignore`)
  145. ## Contributing
  146. See [CONTRIBUTING.md](CONTRIBUTING.md).
  147. ```bash
  148. npm install
  149. npm test
  150. npm run lint
  151. npm run build
  152. ```
  153. ## License
  154. [MIT](LICENSE) © Nguyen Duc
  155. ---
  156. 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 in

Free to use. If it’s helped, pass it on.