ModAST-MCP

C++20/23 프로젝트용 모듈 인지 AST MCP 서버입니다. 일반 AST/LSP 작업에는 지속적인 clangd 프로세스를 사용하고, clangd 22가 심볼로 노출하지 않는 엔티티(module, export module, import 엣지)에 대해서는 소스 수준 모듈 인덱스를 유지합니다.

실행

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은 운영 체제 임시 디렉터리 아래에 증강된 컴파일 데이터베이스를 생성하며, 워크스페이스와 빌드 경로의 해시로 격리됩니다. CMake/Ninja가 생성한 .modmap 파일을 재사용합니다. 생성된 맵이 없는 소비자 번역 단위의 경우 기존 PCM 파일에 대한 소스 수준 import를 해석하고 알려진 모든 전이적 PCM 매핑을 포함하는 캐시된 응답 파일을 생성합니다. 이 빠른 경로에서는 experimentalModules를 끄고, 필수 PCM 파일이 없을 때만 켜세요.

workspace_warm은 비차단입니다. 지속적인 clangd 백그라운드 인덱스를 구축하는 동안 workspace_status를 호출하세요. 파일을 연 후에는 동일한 clangd 세션에서 쿼리가 제공됩니다.

개발 업데이트 및 디스크 쓰기

워크스페이스는 compile_commands.json에 있는 파일과 알려진 .pcm 및 .modmap 아티팩트만 감시합니다. 저장소의 모든 파일을 재귀적으로 감시하거나 재스캔하지 않습니다.

• 소스를 편집하면 메모리의 모듈 그래프가 업데이트됩니다. 열린 문서는 textDocument/didChange를 통해 clangd로 전송되며, ModAST 캐시 파일은 작성되지 않습니다.

• 모듈 인터페이스를 편집하면 해당 모듈이 stale로 표시됩니다. 해당 PCM이 재빌드될 때까지 AST, 정의, 참조, 진단 응답에 경고가 포함됩니다.

• PCM, modmap, 컴파일 데이터베이스 변경은 하나의 워크스페이스 새로 고침으로 디바운스됩니다. 이는 일반적인 편집 -> Ninja/CMake 빌드 -> 쿼리 루프를 처리합니다.

• 새 번역 단위는 빌드 시스템이 compile_commands.json을 업데이트한 후 workspace_refresh로 선택됩니다.

• 생성된 컴파일 데이터베이스와 응답 파일은 콘텐츠 비교를 사용합니다. 동일한 콘텐츠는 다시 작성되지 않습니다. workspace_status.compileDatabase는 최신 준비에 대한 diskWrites와 cacheFilesReused를 보고합니다.

• 임시 워크스페이스 캐시는 열 때 14일 TTL, 비활성 워크스페이스 20개 제한, 비활성 캐시 512MB 제한으로 정리됩니다. 활성 워크스페이스는 유지되며 정리 결과는 workspace_status.cacheCleanup으로 노출됩니다.

• 의미 쿼리는 진행 중인 새로 고침을 기다리므로 중지된 클라이언트가 아닌 교체된 clangd 프로세스에 대해 실행됩니다.

workspace_status는 sourceChanges, lastChangeAt, watchedFiles, staleModules, refreshes도 보고하므로 에이전트가 크로스 모듈 데이터가 최신인지 결정할 수 있습니다.

장기 실행 도구와 workspace_open은 클라이언트가 진행 토큰을 보내면 MCP notifications/progress를 내보냅니다. 느린 clangd 요청은 5초마다 하트비트를 내보냅니다. 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는 소스 정규식 대신 clangd AST 노드를 사용합니다. 모듈 인터페이스 단위에서 실질적인 함수 본문을 보고하며, 템플릿과 constexpr/consteval 정의는 무시하고, 명명된 모듈에 .cpp, .cc, .cxx 구현 또는 파티션 구현 단위가 없으면 경고합니다. 두 번째 비내보내기 .cppm은 이 아키텍처 검사를 충족하지 않습니다. 임계값과 동시성은 구성 가능합니다.

설계 노트

• clangd의 textDocument/ast는 clangdAst 아래에 변경 없이 반환됩니다.

• 합성 moduleContext는 export module ...에 대해 clangd 22가 AST 노드를 반환하지 않고 워크스페이스 심볼로 모듈 이름을 인덱싱하지 않기 때문에 모듈 단위와 import를 추가합니다.

• 모듈 파싱은 의도적으로 소스 기반이며 컴파일러 공급업체와 독립적입니다. clangd 프로세스는 C++ 선언에 대한 의미론적 권위자로 남아 있습니다.

• transport가 wsl인 경우 Windows 워크스페이스 경로는 프로세스 경계에서만 /mnt/<drive>/...로 변환되며, MCP 응답은 Windows 경로로 다시 매핑됩니다.

• MCP stdio를 닫거나, stdin을 종료하거나, SIGINT/SIGTERM을 보내면 파일 감시자가 닫히고 clangd가 정상적으로 종료됩니다.

검증

npm test는 단위 및 수명 주기 테스트를 실행합니다. MODAST_INTEGRATION=1을 설정하면 라이브 clangd 테스트가 추가됩니다. Windows에서는 Arch WSL을 사용하고 Linux에서는 네이티브 clangd를 사용합니다. GitHub Actions는 Windows와 Linux에서 Node.js 20 및 24를 테스트하고, 라이브 Linux clangd 테스트를 실행하며, 높은 심각도의 프로덕션 종속성 권고를 거부합니다.