Привет, Хабр! В предыдущих статьях я рассказывал про наш мультиагентный сервер и фрактальную оркестрацию, где пул ИИ-агентов совместно решает сложные задачи разработки. Чтобы эта группа могла работать с кодовой базой и понимать зависимости, ей нужен инструмент навигации.
Скелетон проекта
Мы создали project-graph-mcp — MCP-сервер для структурного анализа кода. Агент работает, зная полную архитектуру проекта, и не тратит лишние токены. Сервер строит граф зависимостей и возвращает минифицированный JSON.
Ключевая функция — «скелетон» проекта. Сервер парсит исходники и выдаёт сжатый JSON. Степень сжатия — в 10–50 раз.
В JSON-структуре: L — легенда с именами, s — общая статистика. Узел n описывает классы с количеством методов (m) и свойств ($). Модель читает этот JSON и понимает общую структуру. При необходимости углубиться — вызывает expand или deps.
Мультиязыковая поддержка: не только JavaScript
Изначально парсер работал только с JavaScript через AST-дерево (Acorn). Но реальные проекты редко ограничиваются одним языком: Go-серверы соседствуют с TypeScript-фронтом и Python-скриптами.
В версии 1.1 мы добавили парсеры для TypeScript, Python и Go. У каждого языка свои особенности — от декораторов в TS до строковых литералов в Go. Все новые парсеры построены на основе регулярных выражений, а не AST. На чистом JavaScript нет хороших AST-парсеров для этих языков, а подключать тяжёлые внешние библиотеки ради базовой абстракции (классы, методы, импорты) нецелесообразно.
Языки поддерживают настройку — регулярные выражения можно адаптировать под стиль проекта. Общая утилита stripStringsAndComments вынесена в lang-utils.js и принимает опции под каждый язык.
Все парсеры возвращают единый ParseResult — с классами, функциями, импортами и вызовами. Это обеспечивает одну структуру для всех языков.
Метрики кода и Health Score
Помимо графа, MCP включает инструменты анализа: get_dead_code находит неиспользуемый код, get_complexity оценивает цикломатическую сложность, get_large_files выявляет файлы, нуждающиеся в рефакторинге.
Особый интерес представляют цепочки вызовов. Например, как authMiddleware связан с renderDashboard. Метод get_call_chain возвращает путь: authMiddleware → validateToken → loadUser → renderDashboard. Сервер объединяет результаты всех проверок в Health Score — от 0 до 100.
После каждого ответа инструменты возвращают подсказки (Response Hints). Например, если модель обнаружила громоздкую функцию, сервер предложит проверить её сложность.
Тестовые чеклисты
В project-graph-mcp используется паттерн JSDoc-аннотаций @test и @expect для тестовых чеклистов.
Вызов get_pending_tests возвращает список незавершённых тестов. После написания кода агент вызывает mark_test_passed. Поддерживаются API, CLI, интеграционные и браузерные сценарии.
Кастомные правила и фреймворки
Сервер поставляется с 11 базовыми наборами правил (всего 86 правил) для React 18/19, Vue 3, Express 5, TypeScript 5 и Symbiote. Проект распознаётся автоматически, а модель получает адаптированную документацию через get_framework_reference.
Этого достаточно для типовых случаев. Если в проекте свои конвенции — можно вручную добавить правила в папку rules/ или поручить это агенту через set_custom_rule.
Связка с пулом агентов
Оба инструмента работают вместе. Основной IDE-агент, прочитав граф проекта, сразу делегирует подзадачи фоновым воркерам через agent-pool-mcp. Для этого он запрашивает скелетон и передаёт работу Gemini-воркеру, который запускает у себя аналогичный project-graph MCP и навигирует по графу с помощью expand, deps и других методов.
Быстрый старт
Для запуска достаточно Node.js 18+. Добавьте вызов npx в конфиг IDE — при следующем запуске сервер установится автоматически.
Пакет весит 132 КБ (47 файлов), внешних зависимостей нет. Конфигурации для Antigravity, Gemini CLI, Cursor, Claude Desktop, VS Code, Zed и других редакторов описаны в CONFIGURATION.md.
Безопасность
Сервер включает защиту от Path Traversal: все входящие пути проверяются через resolve и startsWith. Агент не может выйти за пределы рабочей директории. MCP-инструменты, работающие с файлами (expand, deps, get_skeleton), наследуют эту проверку. Попытка доступа к ../../etc/passwd вернёт ошибку, а не содержимое файла.
Исходники на GitHub, пакет в npm (версия 1.2.0).