codegraph-mcp

Локальный MCP-сервер, который предоставляет Claude Code (CLI и расширению VS Code) запрашиваемую модель вашей кодовой базы — где что определено, кто что вызывает, что от чего зависит и что было решено в предыдущих сессиях. Без него агент заново открывает вашу архитектуру в каждой сессии через grep и чтение файлов по одному; с ним структурные вопросы получают структурные ответы:

• Безопасные изменения — перед изменением функции агент видит её радиус поражения (analyze_impact), все места вызова (find_callers), все упоминания (find_references) и все зависимые модули (who_imports), вместо того чтобы редактировать то, что случайно нашлось через grep.

• Быстрая ориентация — один вызов repo_map отображает проект по импортной центральности; find_symbol и semantic_search («где проверяется auth token») сразу попадают в нужный код.

• Непрерывность — save_note / recall_notes переносят решения и подводные камни между сессиями, для каждого репозитория.

• Дешевле исследование — как следствие вышеперечисленного, агент читает сигнатуры вместо целых файлов (file_skeleton, read_symbol), а прозрачный прокси сжимает историю разговора на уровне провода. usage_stats сообщает измеренную экономию.

100% портативно: чистый JavaScript + WASM-грамматики. Никакого node-gyp, никакой нативной компиляции. npm install работает одинаково на Windows, macOS и Linux.

Инструменты, доступные агенту

Понимание и навигация

Безопасность изменений

Целевое чтение

Память и операции

Поддерживаемые языки: JavaScript, TypeScript, TSX, Python, Go, Rust, Java, Ruby, C, C++, C#, PHP, GDScript. Файлы, которые индексатор не может извлечь, подсчитываются и сообщаются через repo_map, поэтому частичное покрытие всегда видно.

Related MCP server: MCP Context Manager

Установка

Требуется Node.js ≥ 20 и Claude Code. Одинаково на Windows / macOS / Linux:

git clone https://github.com/denzharkov/codegraph-mcp
cd codegraph-mcp && npm install
node bin/codegraph-mcp.js install     # registers in Claude Code (user scope)

Всё — команда install выполняет claude mcp add за вас, и сервер работает в CLI и в расширении VS Code (они используют общую конфигурацию MCP). Проверьте с помощью claude mcp list или /mcp внутри Claude Code.

Сервер индексирует каталог, в котором он запущен (Claude Code запускает MCP-серверы в каталоге проекта) или путь, указанный через --root / CODEGRAPH_ROOT. Чтобы ограничить его одним проектом вместо пользовательской области, добавьте .mcp.json в этот проект:

{
  "mcpServers": {
    "codegraph": {
      "command": "node",
      "args": ["/absolute/path/to/codegraph-mcp/bin/codegraph-mcp.js"]
    }
  }
}

Для удаления: node bin/codegraph-mcp.js uninstall.

Нулевая конфигурация

Не нужно редактировать CLAUDE.md или настраивать подсказки: сервер поставляет свои рекомендации по использованию («запустите analyze_impact перед изменением функции, find_symbol вместо grep, file_skeleton перед чтением файла, …») через поле MCP instructions, которое Claude Code автоматически внедряет в контекст агента при подключении. Установите, зарегистрируйте, готово.

Прозрачный прокси (гарантированная экономия)

Инструменты MCP выше экономят токены только тогда, когда агент решает их использовать. Прокси-слой работает иначе — как ContextForge, он находится между Claude Code и API Anthropic и сжимает трафик независимо от поведения агента:

• Дедупликация истории: когда в разговоре есть одинаковые результаты инструментов (один и тот же файл прочитан дважды, повторный вывод команды), каждое вхождение после первого заменяется коротким заглушкой перед отправкой запроса с вашей машины. Первое вхождение остаётся дословно, поэтому модель не теряет ничего, что могло бы реально пригодиться — и префикс кэша подсказок сохраняется (переписывается только новый хвост, поэтому дедупликация никогда не вызывает промахов кэша на старых оборотах).

• Скелетизация устаревших чтений: когда файл был прочитан, отредактирован и прочитан снова, более старая полная копия в истории заменяется его сигнатурным скелетом tree-sitter (импорты + объявления с диапазонами строк); самое новое чтение всегда остаётся дословно. Не-кодовые файлы откатываются к усечению головы+хвоста. Преобразования являются чистыми функциями содержимого, поэтому повторные запросы дают одинаковые байты, и кэш подсказок повторно стабилизируется после одной перезаписи.

• Привязка к подсказке: ваше сообщение преобразуется до того, как оно достигнет модели — безопасным способом. Слова никогда не переписываются; вместо этого прокси добавляет чётко обозначенный блок проверяемых фактов об идентификаторах, упомянутых в сообщении (вид, file:lines, однострочное описание из графа символов). Модель начинает с ориентацией, а не тратит круговые поездки инструментов на обнаружение тех же фактов. Привязываются только точные совпадения с учётом регистра, только самое новое сообщение получает свежий блок, и блоки мемоизируются, чтобы история оставалась байт-стабильной для кэша подсказок.

Заголовки аутентификации проходят без изменений (API-ключ или OAuth). Всё, что прокси не может разобрать, пересылается дословно. Потоковая передача (SSE) пропускается через него.

codegraph-mcp wrap                 # like 'cf wrap claude': proxy + claude in one command
codegraph-mcp proxy --port 3210    # or run the proxy standalone

Для расширения VS Code запустите прокси и укажите расширению на него через настройки проекта или глобальные настройки:

{ "env": { "ANTHROPIC_BASE_URL": "http://127.0.0.1:3210" } }

Совокупная экономия отслеживается в ~/.codegraph/proxy-stats.json и выводится при запуске прокси.

Использование CLI

node bin/codegraph-mcp.js index                # index cwd, print stats
node bin/codegraph-mcp.js index --root ~/proj  # index another directory
node bin/codegraph-mcp.js dashboard            # HTML report, opens in browser
node bin/codegraph-mcp.js map                  # interactive architecture map
node bin/codegraph-mcp.js                      # start stdio MCP server (cwd)

Карта архитектуры (.codegraph/map.html) — это многослойное представление репозитория в стиле C4, полностью полученное из индекса:

• Обзор — карточки подсистем (каталоги верхнего уровня) с взвешенными рёбрами импорта между ними, а также автоматически выведенные отправные точки (хаб, точка входа, самый большой модуль);

• Подсистема — файлы одного каталога с их рёбрами импорта и свёрнутыми соседними подсистемами; щёлкните файл, чтобы проследить зависимые и зависимости, щёлкните ещё раз, чтобы углубиться;

• Файл — его символы с внутрифайловыми стрелками вызовов, импортёры и импорты в виде навигационных колонок.

Каждый уровень описывает назначение, а не только структуру: описания берутся из собственной документации кода — строки документации модулей и комментарии заголовков для файлов и символов, README / __init__.py / index.* для папок и самого репозитория — и отображаются на карточках папок, во всплывающих подсказках и на боковой панели.

Уровни имеют глубокие ссылки (#d=src, #f=src/proxy.js), поиск с помощью /, Esc поднимается на уровень, перетаскивание перемещает, колесо мыши масштабирует. Самодостаточный HTML, офлайн.

Панель мониторинга (--no-open для только записи файла) находится в .codegraph/dashboard.html: экономия токенов, использование по инструментам, индексированные языки и наиболее импортируемые файлы. Статический HTML, без сервера, поддержка светлой/тёмной темы. Агент также может сгенерировать её по запросу через usage_stats с dashboard=true.

Как это работает

• Файлы разбираются с помощью WASM-грамматик tree-sitter (пакет tree-sitter-wasms) через web-tree-sitter — без платформенно-зависимых бинарников.

• Экстрактор проходит по каждому AST один раз, собирая определения, рёбра вызовов и импорты в соответствии со спецификацией языка (src/languages.js).

• Граф сохраняется в .codegraph/index.json внутри целевого репозитория; обновления инкрементальны (mtime+size) и ограничены по частоте, поэтому запросы остаются быстрыми.

• node_modules, результаты сборки, вендорные и минифицированные файлы пропускаются; учитываются простые шаблоны .gitignore в корне.

• semantic_search использует локальную модель встраивания (all-MiniLM-L6-v2 через transformers.js, необязательная зависимость). При первом использовании загружает ~25 МБ в ~/.codegraph/models и кэширует векторы символов для каждого репозитория в .codegraph/vectors.bin. Офлайн или без зависимости он молча переключается на поиск по ключевым словам — всё остальное работает независимо.

Добавьте .codegraph/ в .gitignore вашего проекта (это кэш и ваши личные заметки).

Лицензия

MIT