project-graph-mcp: как дать ИИ-агенту карту вашего репозитория — VogueTech

Что появилось / что изменилось

project-graph-mcp — это MCP‑сервер для навигации по коду, который автор довёл до рабочего инструмента для мультиагентных ИИ‑систем.

Ключевые изменения и факты:

"Скелетон" проекта: сервер парсит код и отдаёт сжатый JSON‑граф архитектуры. Сжатие достигает 10–50 раз относительно «сырых» данных.
Поддержка нескольких языков: к JavaScript добавились TypeScript, Python и Go (версия 1.1).
Единый формат ParseResult для всех языков: классы, функции, импорты и вызовы описаны одной структурой.
Размер пакета: 132 кБ, 47 файлов, без внешних зависимостей.
Требования к окружению: только Node.js 18+.
Встроенные анализаторы:
- get_dead_code — поиск неиспользуемого кода,
- get_complexity — цикломатическая сложность,
- get_large_files — поиск перегруженных файлов,
- get_call_chain — цепочки вызовов вроде authMiddleware → validateToken → loadUser → renderDashboard.
Единый Health Score от 0 до 100, который агрегирует результаты проверок.
JSDoc‑чеклисты тестов через аннотации @test и @expect, с API get_pending_tests и mark_test_passed.
11 встроенных наборов правил (всего 86 правил) для React 18/19, Vue 3, Express 5, TypeScript 5 и Symbiote.js.
Автоопределение фреймворка и выдача контекстной справки через get_framework_reference.
Кастомные правила через директорию rules/ и метод set_custom_rule.
Конфиги для Antigravity, Gemini CLI, Cursor, Claude Desktop, VS Code, Zed и других клиентов описаны в CONFIGURATION.md.
Path Traversal Protection: все пути проверяются через resolve + startsWith, обращения вне рабочей директории блокируются.
Актуальная версия на npm — 1.2.0.

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

project-graph-mcp разворачивается как MCP‑сервер, к которому IDE‑агент обращается за «картой» проекта.

Скелетон и граф

Сервер читает исходники и строит компактный JSON‑граф. В нём есть:

легенда символов (L),
агрегированная статистика (s: количество файлов, классов, функций),
описание узлов (n: классы с количеством методов m и свойств $),
число рёбер и других структур.

Модель получает этот JSON и видит архитектуру без дорогостоящего чтения длинных файлов. Когда нужно больше деталей, агент вызывает методы expand и deps, которые раскрывают нужные участки графа.

Поддержка языков

Для JavaScript сервер использует AST‑парсинг (Acorn). Для TypeScript, Python и Go автор перешёл на regex‑подход:

хорошие AST‑парсеры на чистом JS для этих языков тяжёлые,
для задач уровня «классы, методы, импорты» достаточно регулярных выражений,
регулярки можно настраивать под стиль конкретного проекта.

Общая функция stripStringsAndComments в lang-utils.js удаляет строки и комментарии с настройками под язык:

Python — тройные кавычки и #‑комментарии,
Go — строковые литералы в бэктиках без интерполяции,
TypeScript — стандартный набор, включая ${} в шаблонных литералах.

Все парсеры возвращают единый ParseResult, так что остальные части системы не завязаны на язык.

Аналитика и Health Score

Поверх графа сервер считает метрики:

get_dead_code — понимает, какие функции и файлы никто не вызывает,
get_complexity — оценивает цикломатическую сложность,
get_large_files — ищет кандидатов на рефакторинг.

get_call_chain строит цепочки вызовов между точками интереса. На этой базе сервер собирает Health Score (0–100) и добавляет к ответам «подсказки»: например, предложит проверить сложность функции, если она выглядит слишком объёмной.

Тестовые чеклисты

Через JSDoc‑комментарии с @test и @expect разработчик (или ИИ‑агент) описывает сценарии: API, CLI, интеграционные и браузерные.

Дальше:

get_pending_tests возвращает сценарии, которые ещё не помечены как выполненные,
mark_test_passed фиксирует, что агент реализовал и проверил сценарий.

Связка с пулом агентов

project-graph-mcp задуман как часть мультиагентной системы. IDE‑агент берет скелетон, делит задачу на подпроблемы и раскидывает их воркерам через agent-pool-mcp. Каждый воркер поднимает у себя такой же project-graph-mcp и уже локально работает с графом через expand, deps и остальные методы.

Развёртывание

Минимальный конфиг для IDE с поддержкой MCP выглядит так:

{
  "mcpServers": {
    "project-graph": {
      "command": "npx",
      "args": ["-y", "project-graph-mcp"]
    }
  }
}

При старте IDE npx подтянет сервер из npm. Дополнительная установка не нужна.

Что это значит для вас

project-graph-mcp полезен, если вы уже экспериментируете с ИИ‑ассистентами в разработке и хотите, чтобы они работали не вслепую, а с пониманием архитектуры.

Где инструмент особенно уместен:

Крупные репозитории. Модели вроде GPT‑4o, Claude 3.5 или Gemini 1.5 не любят, когда им скармливают весь монорепозиторий в лоб. Скелетон даёт сжатую карту, а не гигабайты кода.
Фрактальные и мультиагентные системы. Если вы строите свою оркестрацию агентов, project-graph-mcp даёт стандартизированный способ навигации и делегирования задач.
Аудит и рефакторинг. Health Score, поиск dead code и сложных участков помогают навести порядок в старом коде и задать агента‑«санитара» репозитория.
Командная разработка с ИИ‑ассистентом. JSDoc‑чеклисты позволяют описать ожидаемое поведение, а затем поручить агенту реализовать и закрыть сценарии.

Где ожидания лучше умерить:

Это не статический анализатор уровня промышленного линтера. Regex‑парсеры для TS, Python и Go заточены под архитектурный обзор, а не под полноценный разбор всех языковых конструкций.
project-graph-mcp не решает сам по себе задачу «сделайте мне приложение». Он нужен как инфраструктурный слой под уже существующий агент или IDE‑клиент.
Для маленьких pet‑проектов выигрыш будет меньше: модель и так может держать весь код в контексте.

Инструмент распространяется через npm и работает поверх Node.js 18+, VPN не нужен. Если вы уже используете Antigravity, Gemini CLI, Cursor, Claude Desktop, VS Code или Zed с MCP‑поддержкой, интеграция сведётся к одной записи в конфиге.

Место на рынке

project-graph-mcp занимает нишу между классическими анализаторами кода и встроенными ассистентами IDE.

С одной стороны, это не конкурент ESLint, Pylint или SonarQube:

он не делает глубокий статический анализ,
не строит сложные отчёты для менеджмента,
не внедряется в CI как основной gate.

С другой стороны, встроенные ассистенты вроде GitHub Copilot, Cursor, Cody или встроенного ИИ в VS Code обычно работают с контекстом «текущий файл + немного соседних». project-graph-mcp даёт им внешний источник знания об архитектуре в виде компактного графа и дополнительных метрик.

Размер пакета — 132 кБ без зависимостей — делает его удобным для встраивания в агентские стеки, где важны скорость старта и предсказуемость окружения. Поддержка нескольких языков и фреймворков через правила позволяет использовать один и тот же сервер и для фронтенда на React или Vue, и для бэкенда на Express или Go.

Для команд, которые уже строят свои стеки вокруг Gemini, Claude или других LLM и экспериментируют с MCP, project-graph-mcp добавляет недостающий слой: структуру проекта, health‑метрики и безопасную файловую навигацию с защитой от выхода за пределы рабочей директории.