ModAST-MCP

Servidor MCP de AST con soporte de módulos para proyectos C++20/23. Utiliza un proceso clangd persistente para operaciones normales de AST/LSP y mantiene un índice de módulos a nivel de fuente para entidades que clangd 22 no expone como símbolos (module, export module y aristas de importación).

Ejecución

npm install
npm run build
node dist/index.js

El servidor utiliza transporte stdio de MCP. En Codex/Claude Desktop, apunta el comando a 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"]
    }
  }
}

Abre un espacio de trabajo primero:

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

mode acepta auto, cpp o modules y su valor predeterminado es auto. El modo automático comprueba las extensiones de módulo y las opciones del compilador como -x c++-module, -fmodule-output, /interface y /ifcOutput. El modo cpp puro omite la detección de PCM/modmap y nunca activa el soporte experimental de módulos de clangd.

workspace_open crea una base de datos de compilación aumentada en el directorio temporal del sistema operativo, aislada mediante un hash de las rutas del espacio de trabajo y de compilación. Reutiliza cualquier archivo .modmap generado por CMake/Ninja. Para unidades de traducción consumidoras sin un mapa generado, resuelve las importaciones a nivel de fuente contra los archivos PCM existentes y crea un archivo de respuesta en caché con todas las correspondencias PCM transitivas conocidas. Mantén experimentalModules desactivado para esta ruta rápida; actívalo solo cuando los archivos PCM necesarios no existan.

workspace_warm no es bloqueante; llama a workspace_status mientras construye el índice de fondo persistente de clangd. Las consultas se sirven desde la misma sesión de clangd después de abrir los archivos.

Actualizaciones de desarrollo y escrituras en disco

El espacio de trabajo solo observa los archivos presentes en compile_commands.json más los artefactos conocidos .pcm y .modmap. No observa ni vuelve a escanear recursivamente todos los archivos del repositorio.

• Editar una fuente observada actualiza el grafo de módulos en memoria. Los documentos abiertos se envían a clangd mediante textDocument/didChange; no se escribe ningún archivo de caché de ModAST.

• Editar una interfaz de módulo marca su módulo como obsoleto. Las respuestas de AST, definición, referencias y diagnósticos incluyen una advertencia hasta que se reconstruya el PCM correspondiente.

• Los cambios en PCM, modmap y la base de datos de compilación se combinan con debounce en un único refresco del espacio de trabajo. Esto cubre el ciclo normal edición -> compilación Ninja/CMake -> consulta.

• workspace_refresh detecta las nuevas unidades de traducción después de que el sistema de compilación actualice compile_commands.json.

• Las bases de datos de compilación y los archivos de respuesta generados usan comparación de contenido. El contenido idéntico nunca se vuelve a escribir. workspace_status.compileDatabase informa de diskWrites y cacheFilesReused de la última preparación.

• Las cachés temporales de espacios de trabajo se podan al abrir con un TTL de 14 días, un límite de 20 espacios de trabajo inactivos y un límite de 512 MB de caché inactiva. El espacio de trabajo activo se conserva y los resultados de la limpieza se exponen como workspace_status.cacheCleanup.

• Las consultas semánticas esperan un refresco en curso, por lo que se ejecutan contra el proceso clangd de reemplazo en lugar de contra un cliente detenido.

workspace_status también informa de sourceChanges, lastChangeAt, watchedFiles, staleModules y refreshes para que un agente pueda decidir si los datos entre módulos están actualizados.

Tanto las herramientas de larga duración como workspace_open emiten notifications/progress de MCP cuando el cliente envía un token de progreso. Las solicitudes lentas a clangd emiten un latido cada cinco segundos. workspace_status también puede sondearse con seguridad: incluye phase, progressCompleted, progressTotal, elapsedMs y los últimos 20 events legibles para humanos.

Herramientas

• workspace_open, workspace_status, workspace_refresh, workspace_warm

• module_search, module_graph

• module_quality, format

• ast, document_symbols, workspace_symbols

• definition, references, diagnostics

Los argumentos de línea y carácter se indexan desde 1. Para uso de agentes, definition y references aceptan un needle más una occurrence, evitando cálculos manuales de posición.

format delega en clangd/clang-format y respeta el .clang-format del proyecto. Por defecto es solo de vista previa y devuelve el texto formateado más las ediciones LSP. Se requiere apply=true para escribir el código fuente. Antes de aplicar, el servidor verifica que el archivo sigue coincidiendo con la instantánea de clangd; los cambios concurrentes del editor provocan un error de conflicto en lugar de sobrescribirse. Las escrituras correctas usan un archivo temporal en el mismo directorio y un renombrado atómico, y después sincronizan el documento persistente de clangd.

module_quality usa nodos AST de clangd en lugar de expresiones regulares sobre el código fuente. Informa de cuerpos de función sustanciales en unidades de interfaz de módulo, ignora plantillas y definiciones constexpr/consteval, y advierte cuando un módulo con nombre no tiene una implementación .cpp, .cc o .cxx ni una unidad de implementación de partición. Un segundo .cppm no exportado no satisface esta comprobación de arquitectura. Los umbrales y la concurrencia de escaneo son configurables.

Notas de diseño

• El textDocument/ast de clangd se devuelve sin cambios bajo clangdAst.

• Un moduleContext sintético añade unidades de módulo e importaciones porque clangd 22 no devuelve ningún nodo AST para export module ... ni indexa los nombres de módulo como símbolos del espacio de trabajo.

• El análisis de módulos es deliberadamente basado en el código fuente e independiente del proveedor del compilador. El proceso de clangd sigue siendo la autoridad semántica para las declaraciones de C++.

• Cuando transport es wsl, las rutas de espacio de trabajo de Windows se convierten a /mnt/<drive>/... solo en el límite del proceso; las respuestas MCP se vuelven a mapear a rutas de Windows.

• Cerrar MCP stdio, finalizar stdin o enviar SIGINT/SIGTERM cierra los observadores de archivos y apaga clangd de forma ordenada.

Verificación

npm test ejecuta las pruebas unitarias y de ciclo de vida. Establece MODAST_INTEGRATION=1 para añadir una prueba de clangd en vivo; usa Arch WSL en Windows y clangd nativo en Linux. GitHub Actions prueba Node.js 20 y 24 en Windows y Linux, ejecuta la prueba de clangd en vivo de Linux y rechaza avisos de dependencias de producción de alta severidad.