repo-context-mcp

MCP-сервер, который помогает AI-агентам по программированию понимать репозиторий — без выгрузки всего монорепозитория в запрос.

Работает с Codex, Claude Code, Cursor, Cline и любым клиентом, который поддерживает Model Context Protocol.

Почему

AI-агенты тратят токены на повторный обход node_modules, пропуск точек входа или вставку случайных файлов. repo-context-mcp предоставляет три специализированных инструмента:

Только локально. Нет облака. Нет телеметрии. Транспорт через stdio.

Установка

# 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

Требуется Node.js 18+.

CLI (без клиента MCP)

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

После глобальной установки / команды npx:

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

Конфигурация клиента MCP

Claude Desktop / Claude Code

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

Cursor

Настройки → MCP → добавить сервер с командой npx и аргументами [\"-y\", \"repo-context-mcp\"].

Codex / универсальный stdio

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

Из этого репозитория после сборки:

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

См. также examples/mcp-config.claude.json и examples/mcp-config.local.json.

Опциональные переменные окружения:

Каждый инструмент также принимает явный аргумент root.

Инструменты

repo_map

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

Возвращает markdown-дерево, количество файлов и вероятные точки входа (package.json, README.md, src/index.ts, AGENTS.md и т.д.). Пропускает node_modules, .git, dist и т.д.

search_code

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

Поиск подстрок по расширениям исходных файлов.

pack_context

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

Ранжирует файлы (точки входа + совпадения фокуса), учитывает приблизительный лимит токенов (~4 символа на токен) и возвращает один markdown-документ, готовый для вставки в промпт агента или в ревью PR.

Библиотечный API

Вы можете использовать ядро без MCP:

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);

Демонстрация (без клиента MCP)

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' })));"

Безопасность

• Читает файлы только в пределах запрашиваемого root.
• Не выполняет код проекта.
• Пропускает типичные вендорные директории и очевидные бинарники.
• Тем не менее: указывайте только на доверенные репозитории.

См. SECURITY.md.

Статус проекта

v0.1.1 — MCP-сервер + CLI + поддержка .gitignore + GitHub Action для PR.

Roadmap:

• [x] Учёт .gitignore
• [x] CLI (map / search / pack) + --json
• [x] GitHub Action: упаковка контекста при каждом PR
• [ ] Опциональный бэкенд ripgrep для больших монорепозиториев
• [ ] Базовый индекс символов (tree-sitter) для find_symbol
• [ ] Настраиваемый файл игнорирования (.repo-contextignore)

Вклад

См. CONTRIBUTING.md.

npm install
npm test
npm run lint
npm run build

Лицензия

MIT © Nguyen Duc

Создан как реальная утилита сопровождения / инструмента для агентов в экосистеме MCP — не заглушечный репозиторий. Приветствуются issues и PR.