ModAST-MCP

Модульно-ориентированный MCP-сервер для проектов C++20/23. Он использует постоянный процесс clangd для обычных операций AST/LSP и поддерживает индекс модулей на уровне исходного кода для сущностей, которые clangd 22 не раскрывает как символы (module, export module и рёбра импорта).

Запуск

npm install
npm run build
node dist/index.js

Сервер использует MCP-транспорт stdio. В Codex/Claude Desktop укажите команду на node dist/index.js.

Related MCP server: clangd-mcp-server

Windows + Arch WSL

{
  "mcpServers": {
    "modast": {
      "command": "node",
      "args": ["D:/runtime/mcp/ModAST-MCP/dist/index.js"]
    }
  }
}

Сначала откройте рабочую область:

{
  "root": "E:/github/cnetmod",
  "buildDirectory": "E:/github/cnetmod/cmake-build-release-wsl",
  "transport": "wsl",
  "wslDistro": "Arch",
  "experimentalModules": false
}

mode принимает auto, cpp или modules и по умолчанию равен auto. Автоматический режим проверяет расширения модулей и флаги компилятора, такие как -x c++-module, -fmodule-output, /interface и /ifcOutput. Чистый режим cpp пропускает обнаружение PCM/modmap и никогда не включает экспериментальную поддержку модулей clangd.

workspace_open создаёт расширенную базу данных компиляции во временном каталоге операционной системы, изолированную по хешу путей рабочей области и сборки. Он повторно использует любые файлы .modmap, созданные CMake/Ninja. Для потребительских единиц трансляции без сгенерированной карты он разрешает импорт на уровне исходного кода по существующим файлам PCM и создаёт кэшированный файл ответа, содержащий все известные транзитивные PCM-отображения. Держите experimentalModules выключенным для этого быстрого пути; включайте его только тогда, когда требуемые файлы PCM не существуют.

workspace_warm не блокирует выполнение; вызывайте workspace_status, пока он строит постоянный фоновый индекс clangd. Запросы обслуживаются из той же сессии clangd после открытия файлов.

Обновления разработки и записи на диск

Рабочая область отслеживает только файлы, присутствующие в compile_commands.json, плюс известные артефакты .pcm и .modmap. Она не отслеживает рекурсивно и не пересканирует каждый файл в репозитории.

• Редактирование отслеживаемого исходного файла обновляет граф модулей в памяти. Открытые документы отправляются в clangd через textDocument/didChange; файл кэша ModAST не записывается.

• Редактирование интерфейса модуля помечает его модуль как устаревший. Ответы AST, определения, ссылок и диагностики включают предупреждение, пока соответствующий PCM не будет пересобран.

• Изменения PCM, modmap и базы данных компиляции объединяются в одно обновление рабочей области. Это обрабатывает обычный цикл редактирование -> сборка Ninja/CMake -> запрос.

• Новые единицы трансляции подхватываются workspace_refresh после того, как система сборки обновит compile_commands.json.

• Сгенерированные базы данных компиляции и файлы ответов используют сравнение содержимого. Идентичное содержимое никогда не перезаписывается. workspace_status.compileDatabase сообщает diskWrites и cacheFilesReused для последней подготовки.

• Временные кэши рабочей области очищаются при открытии с использованием TTL 14 дней, лимита 20 неактивных рабочих областей и лимита 512 МБ неактивного кэша. Активная рабочая область сохраняется, а результаты очистки раскрываются как workspace_status.cacheCleanup.

• Семантические запросы ожидают выполняющегося обновления, поэтому они выполняются против заменяющего процесса clangd, а не остановленного клиента.

workspace_status также сообщает sourceChanges, lastChangeAt, watchedFiles, staleModules и refreshes, чтобы агент мог решить, актуальны ли данные между модулями.

Как долго выполняющиеся инструменты, так и workspace_open отправляют MCP notifications/progress, когда клиент передаёт токен прогресса. Медленные запросы clangd отправляют контрольный сигнал каждые пять секунд. workspace_status также безопасен для опроса: он включает phase, progressCompleted, progressTotal, elapsedMs и последние 20 читаемых человеком events.

Инструменты

• workspace_open, workspace_status, workspace_refresh, workspace_warm

• module_search, module_graph

• module_quality, format

• ast, document_symbols, workspace_symbols

• definition, references, diagnostics

Аргументы строк и символов отсчитываются от 1. Для использования агентом definition и references принимают needle плюс occurrence, избегая ручных вычислений позиций.

format делегирует clangd/clang-format и учитывает .clang-format проекта. По умолчанию он только предварительный просмотр и возвращает отформатированный текст плюс правки LSP. Для записи исходного файла требуется apply=true. Перед применением сервер проверяет, что файл всё ещё соответствует снимку clangd; одновременные изменения редактора вызывают ошибку конфликта вместо перезаписи. Успешные записи используют временный файл в том же каталоге и атомарное переименование, затем синхронизируют постоянный документ clangd.

module_quality использует узлы AST clangd, а не регулярные выражения по исходному коду. Он сообщает о существенных телах функций в единицах интерфейса модуля, игнорирует шаблоны и определения constexpr/consteval и предупреждает, когда именованный модуль не имеет реализации .cpp, .cc или .cxx или единицы реализации раздела. Второй неэкспортируемый .cppm не удовлетворяет этой проверке архитектуры. Пороги и параллелизм сканирования настраиваются.

Заметки по дизайну

• textDocument/ast clangd возвращается без изменений под clangdAst.

• Синтетический moduleContext добавляет единицы модулей и импорты, потому что clangd 22 не возвращает узел AST для export module ... и не индексирует имена модулей как символы рабочей области.

• Разбор модулей намеренно основан на исходном коде и не зависит от поставщика компилятора. Процесс clangd остаётся семантическим авторитетом для объявлений C++.

• Когда transport равен wsl, пути рабочей области Windows преобразуются в /mnt/<drive>/... только на границе процесса; ответы MCP отображаются обратно в пути Windows.

• Закрытие MCP stdio, завершение stdin или отправка SIGINT/SIGTERM закрывает наблюдатели файлов и корректно завершает clangd.

Проверка

npm test запускает модульные и жизненные тесты. Установите MODAST_INTEGRATION=1, чтобы добавить живой тест clangd; он использует Arch WSL на Windows и нативный clangd на Linux. GitHub Actions тестирует Node.js 20 и 24 на Windows и Linux, запускает живой тест clangd на Linux и отклоняет предупреждения о высокосерьёзных зависимостях производственной среды.