mcp-cpp-project-indexer

Indexador de proyectos C++ eficiente respaldado por SQL, diseñado para bases de código grandes con bajo consumo de memoria.

GitHub

Prueba este MCPPatrocinado

Documentación

mcp-cpp-project-indexer

mcp-cpp-project-indexer es un indexador determinista de rangos de código fuente C++ para proyectos grandes y con muchos módulos, así como para navegación de código con IA basada en MCP.

No es un compilador, un reemplazo de LSP, un motor de refactorización, un analizador semántico ni un constructor de grafos de llamadas.

Su trabajo es simple:

Find code. Read code. Do not guess code.

El indexador mapea símbolos, archivos y módulos C++20 a rangos de código fuente exactos para que una IA pueda leer solo el código que necesita.

El trabajo del proyecto y la orquestación de IA relacionada se documenta en la página principal de MEF Programming, incluida la capa de relevo/gobernanza que estamos construyendo en torno al uso de herramientas MCP.

Resumen en 30 segundos

mcp-cpp-project-indexer construye un índice de enrutamiento ligero sobre un árbol de código fuente C++. Los clientes MCP pueden entonces hacer preguntas deterministas como:

¿dónde está esta función/clase/miembro de datos?
¿qué rango de código fuente exacto debería leerse?
¿qué módulo importa o exporta esta partición?
¿qué fragmento modificado se cruza con qué símbolo o rango de datos indexado?

El indexador devuelve metadatos y rangos de código fuente originales. No pretende entender el programa. La IA aún tiene que leer el código fuente devuelto y razonar a partir de esa evidencia.

Flujo de trabajo mínimo:

User asks about Widget::OnScroll
-> find_symbol("Widget::OnScroll")
-> read_symbol(symbolId)
-> AI explains only what was visible in that source range

Esto mantiene los proyectos grandes de C++ fuera del prompt hasta que se necesite evidencia de código fuente exacta.

Inicio rápido en 5 minutos

1. Clona este repositorio

git clone https://github.com/walti1972/mcp-cpp-project-indexer.git
cd mcp-cpp-project-indexer

2. Construye un índice para tu proyecto C++

python <indexer-root>\build_project_index.py \`
  --root <project-root> \`
  --output-root <project-root>\.mcp-cpp-project-indexer

El índice generado se escribe en:

<project-root>\.mcp-cpp-project-indexer

3. Inicia el servidor MCP

python <indexer-root>\code_index_mcp_server.py \`
  --project-root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer

Para múltiples clientes MCP o un proceso compartido de larga duración, usa transporte HTTP:

python <indexer-root>\code_index_mcp_server.py \`
  --project-root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --transport http \`
  --http-host 127.0.0.1 \`
  --http-port 8765

4. Añade el servidor a tu cliente MCP

Configuración mínima estilo LM Studio:

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "command": "python",
      "args": [
        "<indexer-root>\\code_index_mcp_server.py",
        "--project-root",
        "<project-root>",
        "--index-root",
        "<project-root>\\.mcp-cpp-project-indexer"
      ]
    }
  }
}

5. Pide código fuente exacto, no archivos completos

Buena primera solicitud:

Find the symbol Widget::OnScroll, read its implementation, and explain only
what is visible in the source range.

Ruta de herramienta esperada:

find_symbol -> read_symbol -> source-grounded answer

Para mejores resultados, dale a tu IA las reglas de prompt_template.md. La versión corta es:

Use metadata to locate code. Read exact source ranges before explaining behavior.
Do not infer implementation behavior from metadata alone.

Contenido

Estructura del repositorio

La raíz pública readme.md es documentación del proyecto orientada a humanos. La implementación real en Python está bajo src/:

src/
  README.md
  indexer/
    build_project_index.py
    update_project_index.py
    cpp_project_index.py
  server/
    code_index_mcp_server.py
    server_ui/
  ui/
    indexer_tui.py
    indexer_control.py

Los scripts de nivel raíz como build_project_index.py, code_index_mcp_server.py, indexer_tui.py y update_project_index.py son envoltorios de compatibilidad. Mantienen las líneas de comando existentes y las configuraciones de clientes MCP funcionando mientras redirigen la ejecución al paquete de implementación.

Los README locales de carpetas bajo src/ usan el formato de orientación del indexador de proyectos para que los agentes puedan descubrir por dónde empezar sin convertir el README raíz público en documentación solo para máquinas.

🚀 Escala de producción y rendimiento

Este proyecto se usa en bases de código C++ reales, no solo en ejemplos de juguete. Dos ejecuciones recientes a escala muestran el rango previsto:

Proyecto	Archivos	Líneas de código fuente	Tokens del lexer	Símbolos	Declaraciones de datos	Módulos C++20	Compilación completa
Proyecto comercial C++20 anonimizado	7,046	979,658	4,682,882	97,924	36,551	3,754	19.5s
Checkout de Chromium	137,622	30,792,607	137,365,399	2,327,255	818,188	0	~24m 32s

Estos números dependen de la máquina. La ejecución de Chromium usó --jobs 60 en una estación de trabajo de muchos núcleos con un sistema Intel Xeon Silver 4316, 128 GB de RAM y almacenamiento NVMe SSD empresarial. Es una prueba de estrés pública útil porque ejercita una base de código C++ clásica muy grande basada en includes, mientras que el proyecto comercial anonimizado ejercita metadatos densos de módulos y particiones C++20. La ejecución de Chromium también validó el indexador de datos/miembros a escala: después de corregir el manejo de profundidad de >> de plantillas anidadas, la prueba de estrés pública reveló 46,529 declaraciones de datos adicionales y 66,866 alias de nombres de datos adicionales.

El índice de búsqueda respaldado por SQLite mantiene el inicio del servidor práctico incluso a escala de Chromium: el servidor MCP puede iniciarse inmediatamente y mantenerse alrededor de 200 MB de RAM después del inicio, en lugar de cargar millones de entradas de símbolos/datos/nombres en objetos de Python.

Está diseñado para flujos de trabajo que combinan la aplicación de escritorio Codex u otros clientes MCP con navegación de Visual Studio y, cuando sea necesario, evidencia binaria/descompilada de herramientas como IDA Pro.

En un flujo de trabajo medido, el enrutamiento exacto de rangos de código fuente redujo la lectura de texto fuente de aproximadamente 2,000 líneas a 283 líneas, una reducción del 86%.

Centro de control TUI

Para uso diario, el indexador incluye una TUI opcional compatible con mouse. Convierte el índice del proyecto en un pequeño centro de control local:

inicia el servidor MCP HTTP y el vigilante desde un solo lugar
ejecuta compilaciones completas, actualizaciones incrementales, actualizaciones rápidas y reconstrucciones del mapa de módulos
observa estadísticas en vivo del servidor, vigilante, bloqueo, proceso, token e índice
inspecciona registros de compilación/actualización sin cambiar de herramienta
alterna secciones de archivos de diagnóstico para obtener evidencia más profunda del analizador cuando sea necesario

Instala la dependencia de UI opcional e inicia el centro de control con rutas explícitas de proyecto/índice:

pip install -r <indexer-root>\requirements-ui.txt

python <indexer-root>\indexer_tui.py \`
  --root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --jobs 20 \`
  --http-url http://127.0.0.1:8765

La UI es opcional; el indexador principal sigue siendo ligero en dependencias y aún puede manejarse completamente desde scripts o clientes MCP. Para configuración y atajos de teclado, consulta Centro de control.

💡 ¿Por qué esta herramienta?

Los proyectos grandes de C++ son costosos de alimentar a un modelo de IA cuando se cargan archivos completos solo para encontrar una función, clase, importación o declaración. Los módulos C++20 lo hacen más difícil: muchas herramientas estilo IDE/LSP aún tienen problemas con grafos de módulos grandes, particiones, encabezados SDK generados y configuración específica de compilación.

Este indexador resuelve un problema más acotado pero muy práctico: le da a la IA un pequeño mapa de enrutamiento determinista. La IA puede localizar el símbolo, módulo, archivo o fragmento modificado relevante primero, y luego leer solo las líneas de código fuente originales exactas necesarias para la tarea.

Ejemplo de un flujo de trabajo real de búsqueda de errores:

Whole file context:     ~2000 source lines
On-demand source reads:  ~283 source lines
--------------------------------------------
Reduction:               ~86% less source text

📊 Antes / Después

Navegación de código IA estándar	Con mcp-cpp-project-indexer
❌ La IA lee archivos completos para encontrar un símbolo	✅ La IA pide metadatos compactos y luego lee el rango de código fuente exacto
❌ El contexto se llena con declaraciones e implementaciones no relacionadas	✅ El contexto se mantiene enfocado en las líneas que importan
❌ Los consumidores/importaciones de módulos C++20 son difíciles de enrutar	✅ Importaciones de módulos, reexportaciones, particiones y consumidores se exponen directamente
❌ Las revisiones comienzan escaneando archivos modificados manualmente	✅ Los fragmentos de cambios se mapean a rangos de símbolos/datos indexados
❌ Las herramientas pueden implicar certeza semántica que no tienen	✅ El indexador solo devuelve hechos de enrutamiento y rangos de código fuente originales

El resultado es menor uso de tokens, menor latencia, menos deriva de contexto y un análisis más fundamentado en el código fuente.

Cómo funciona

El indexador evita deliberadamente pretender ser un compilador.

Escaneo rápido de tokens/estructura Los archivos fuente se escanean con un lexer de Python ligero y un analizador estructural. La salida es una tabla de contenidos determinista: archivos, símbolos, declaraciones de datos, directivas léxicas #include, rangos de código fuente, diagnósticos y hechos de módulos.
Mapa de módulos C++20 Las interfaces de módulos, particiones, importaciones, exportaciones-importaciones y consumidores se indexan para que la IA pueda enrutar a través de código con muchos módulos sin pedirle a un LSP que resuelva toda la compilación.
Actualización incremental y vigilante El actualizador rastrea hashes de contenido y reescribe solo los datos de índice modificados cuando es posible. El vigilante opcional puede mantener fresco el caché del servidor MCP mientras trabajas en Visual Studio.
Herramientas MCP con controles de salida compactos Las herramientas exponen primero metadatos de enrutamiento exactos. La IA escala solo cuando es necesario: búsqueda compacta de símbolos, descripción general de archivo/módulo/cambio, read_symbol o read_range exactos, y luego lecturas recursivas más profundas del código fuente.

El indexador es solo la tabla de contenidos. La IA realiza la exploración recursiva y la revisión de código a partir de las líneas de código fuente originales que lee explícitamente.

Flujo de trabajo principal

En lugar de esto:

Read Renderer.cpp completely: ~2000 lines

usa esto:

find_symbol("Renderer::Paint")
read_symbol(symbolId)
inspect visible calls
read only relevant project callees

Para revisión de código modificado:

list_changed_files
get_file_change_hunks(includeIndexedRangeSummary:true, includeSource:false)
get_file_change_hunks(symbolId/dataId, includeSource:true)
read_symbol/read_range only when current source behavior is needed

Qué hace

El escáner extrae hechos de enrutamiento de archivos fuente C++:

archivos e IDs de archivo estables
módulos y particiones C++20
directivas léxicas #include
importaciones y exportaciones
espacios de nombres
clases / estructuras / enumeraciones
funciones / métodos
constructores / destructores / operadores
declaraciones y definiciones en línea
startLine / endLine exactos
diagnósticos para archivos estructuralmente sospechosos

Está basado en flujo/tokens, no en expresiones regulares.

Qué no hace

Intencionalmente no incluido:

sin grafo de llamadas de programa completo preciso como compilador
sin find_references
sin resolución de tipos
sin resolución de instanciación de plantillas
sin resolución de sobrecarga precisa como compilador
sin expansión de macros
sin resúmenes semánticos
sin análisis de errores
sin analyze_symbol(symbolId)

La IA debería leer rangos de código fuente y razonar a partir del código original.

Diseño de salida

Directorio de salida predeterminado:

<project-root>/.mcp-cpp-project-indexer/

Archivos generados:

.mcp-cpp-project-indexer/
  manifest.json
  files/
    f_<pathHash>.json
  index.sqlite
  modules.json
  diagnostics.json
  update_state.json      # written by build/update; used for fast incremental updates
  module_map.json        # generated by build_module_map.py
  .watch_update_summary.json  # temporary watcher/update summary
  .update.lock           # process lock for index writers
  .watcher.lock          # process lock for one active watcher

Los índices globales de enrutamiento de símbolos y datos se almacenan en index.sqlite. Los índices JSON por archivo siguen siendo la fuente de verdad para rangos de código fuente exactos y reconstrucciones incrementales.

Exportación JSONL opcional:

python <indexer-root>\export_index_jsonl.py --index-root <project-root>\.mcp-cpp-project-indexer --kind symbols --output symbols.jsonl
python <indexer-root>\export_index_jsonl.py --index-root <project-root>\.mcp-cpp-project-indexer --kind data --output data.jsonl

Los campos de índice de archivos de diagnóstico del escáner se emiten solo con --emit-diagnostics o --emit-diagnostic-file-indexes:

scopeIntervals
structuralEvents
functionBodyRanges

Indexar un archivo

Desde cualquier directorio:

python <indexer-root>\build_file_index.py \`
  --file <project-root>\path\to\file.ixx \`
  --project-root <project-root> \`
  --output <project-root>\.mcp-cpp-project-indexer\diagnostic_file.json

Con datos de diagnóstico del escáner:

python <indexer-root>\build_file_index.py \`
  --file <project-root>\path\to\file.ixx \`
  --project-root <project-root> \`
  --output <project-root>\.mcp-cpp-project-indexer\diagnostic_file.json \`
  --emit-diagnostics

Si se omite --project-root, se usa el directorio padre del archivo.

Construir un índice de proyecto

Uso recomendado desde la raíz del proyecto C++:

cd <project-root>
python <indexer-root>\build_project_index.py

Esto escribe en:

<project-root>/.mcp-cpp-project-indexer/

Forma explícita:

python <indexer-root>\build_project_index.py \`
  --root <project-root> \`
  --output-root <project-root>\.mcp-cpp-project-indexer

Ejemplo de resumen:

Built cpp.project_index.v1
Root: <project-root>
Output: <project-root>/.mcp-cpp-project-indexer
Files: 7076
Symbols: 97583
Names: 95674
Modules: 3774
Diagnostics: 7
Total code lines: 1750000
Total tokens: 14200000
SQLite index: <project-root>/.mcp-cpp-project-indexer/index.sqlite

Total tokens es el recuento de tokens del lexer del indexador sobre el código fuente indexado después del enmascarado de comentarios. Es una métrica de tamaño de proyecto, no un recuento de tokens de facturación de LLM.

Cuando la raíz del proyecto está dentro de un árbol de trabajo Git y git está disponible, el descubrimiento de archivos respeta las reglas de ignorar de Git filtrando candidatos a través de git check-ignore --stdin. Esto excluye rutas que coinciden con .gitignore, .git/info/exclude o el archivo de ignorar global del usuario. Los proyectos que no son Git, o sistemas sin Git, recurren a la lista integrada de directorios excluidos. Los directorios con punto como .git, .vs, .cache, .idea o .folder se excluyen por defecto.

Configuración de descubrimiento de proyectos

Para proyectos grandes con diseños de código fuente mixtos, coloca indexer_config.json en la raíz del proyecto o en cualquier subdirectorio. Los archivos de configuración se aplican mientras se recorre el árbol: la configuración raíz se convierte en la base, y las configuraciones de subdirectorios pueden anularla o extenderla para ese subárbol.

Ejemplo:

{
  "addExtensions": [".mm"],
  "addExcludeDirs": ["generated", "third_party"],
  "includeExtensionlessHeaders": true,
  "useGitIgnore": false
}

Campos admitidos:

{
  "extensions": [".cpp", ".cc", ".h"],
  "addExtensions": [".mm"],
  "removeExtensions": [".c"],
  "excludeDirs": ["out", "build"],
  "addExcludeDirs": ["generated"],
  "removeExcludeDirs": ["third_party"],
  "includeExtensionlessHeaders": true,
  "useGitIgnore": false
}

extensions y excludeDirs reemplazan los valores heredados para ese subárbol. Los campos add* y remove* modifican los valores heredados. El descubrimiento de encabezados sin extensión es conservador y opt-in; solo acepta archivos sin extensión cuyas primeras líneas parecen encabezados C/C++. useGitIgnore:false desactiva el paso final de git check-ignore --stdin para repositorios muy grandes donde el filtrado de ignorar de Git es más costoso que una configuración explícita del indexador.

Actualización incremental

Después de una compilación completa del índice, los archivos modificados se pueden detectar y reindexar incrementalmente.

Ejecución de prueba:

python <indexer-root>\update_project_index.py \`
  --root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --dry-run

Actualización rápida para archivos ya indexados:

python <indexer-root>\update_project_index.py \`
  --root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --known-files-only

Actualización estilo vigilante para un archivo modificado conocido:

python <indexer-root>\update_project_index.py \`
  --root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --known-files-only \`
  --changed-file path\to\changed.cpp

--known-files-only omite el descubrimiento completo de archivos nuevos. Esto es ideal para bucles de guardado/vigilancia. --changed-file se puede repetir y permite que un vigilante evite calcular hashes de archivos sin cambios.

Las escrituras de índice están protegidas por un archivo exclusivo .update.lock en la raíz del índice. Esto evita que compilaciones completas, actualizaciones incrementales y reconstrucciones del mapa de módulos escriban los mismos archivos de índice al mismo tiempo.

Vigilar el índice del proyecto

El watcher independiente sondea los archivos fuente, aplica debounce a los cambios, ejecuta el actualizador incremental y, opcionalmente, reconstruye module_map.json.

python <indexer-root>\watch_project_index.py \`
  --root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --jobs 20

Para modificaciones puras de archivos, el watcher llama a:

update_project_index.py --known-files-only --changed-file <path>

Esto calcula el hash solo del archivo candidato modificado. Si el hash de contenido no cambió, el watcher omite la reconstrucción del mapa de módulos y el trabajo de recarga de caché de MCP.

Solo un watcher debe ser propietario de una raíz de índice. El watcher usa .watcher.lock y sale si otro watcher ya está activo para el mismo índice.

Los diagnósticos no son fatales. Indican advertencias estructurales de mejor esfuerzo para archivos individuales.

Imprimir resumen de diagnósticos:

python -c "import json; from collections import Counter; d=json.load(open(r'<project-root>\.mcp-cpp-project-indexer\diagnostics.json',encoding='utf-8')); print(len(d)); print(Counter(x.get('code') for x in d)); [print(x['relativePath'], x['code'], x['message'], x.get('range')) for x in d]"

Construir el mapa de módulos

Después de construir el índice del proyecto:

python <indexer-root>\build_module_map.py \`
  --index-root <project-root>\.mcp-cpp-project-indexer

Salida:

<project-root>/.mcp-cpp-project-indexer/module_map.json

El mapa de módulos contiene:

nombres de módulos
módulos primarios y particiones
archivos que definen cada módulo
importaciones
importedBy
un árbol de módulos
importaciones no resueltas

Es solo metadatos. No analiza el comportamiento de la implementación.

Centro de control

El indexador principal no tiene dependencias de terceros en tiempo de ejecución. Para la operación diaria hay dos superficies de control de terminal opcionales:

indexer_tui.py: una interfaz Textual pulida con soporte de mouse
indexer_control.py: una alternativa de línea de comandos sin dependencias

Instalar la dependencia opcional de la interfaz:

pip install -r <indexer-root>\requirements-ui.txt

Iniciar la interfaz Textual:

python <indexer-root>\indexer_tui.py \`
  --root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --jobs 20 \`
  --http-url http://127.0.0.1:8765

La interfaz Textual proporciona una interfaz de terminal real con botones, soporte de mouse, tarjetas de estado, sondeo HTTP en vivo de /status, registros de actividad y control de procesos para acciones de build/update/watch/server.

La entrada de mouse depende del emulador de terminal. En Windows, use Windows Terminal u otro terminal moderno que reenvíe eventos de mouse a aplicaciones de terminal. Los atajos de teclado funcionan en cualquier lugar donde Textual pueda ejecutarse.

La configuración de la interfaz se guarda en <indexer-root>/.ui-settings/ al salir y cuando se alternan secciones de archivos de diagnóstico. Cada archivo de configuración está identificado por el nombre del proyecto más un hash de ruta, por lo que las preferencias de la interfaz no se escriben en la raíz del proyecto ni en el directorio de índice generado. Las preferencias almacenadas incluyen la URL HTTP, el valor de trabajos, la alternancia de sección de diagnóstico, la configuración de lanzamiento de la API de gestión, el tema Textual activo y las rutas de proyecto/índice.

El archivo de configuración también se puede editar directamente para configuraciones externas de Relay UI:

{
  "httpUrl": "http://127.0.0.1:8765",
  "jobs": 20,
  "managementApiEnabled": true,
  "managementToken": "local-secret-token",
  "emitDiagnosticFileIndexes": true,
  "theme": "textual-dark"
}

La interfaz Textual tiene una acción separada de Start HTTP + management. Inicia el servidor HTTP MCP con watcher y --enable-management-api, usando el managementToken guardado cuando está configurado. Esta acción es intencionalmente local a la TUI y no se expone como un comando de gestión en la API HTTP.

Centro de control alternativo:

python <indexer-root>\indexer_control.py \`
  --root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --jobs 20 \`
  --http-url http://127.0.0.1:8765

Teclas comunes:

B  full build
U  incremental update
F  fast known-files update
M  rebuild module map
H  start HTTP server with watcher
G  start HTTP server with watcher and management API
W  start standalone watcher
S  toggle diagnostic file sections for launched commands
X  stop the currently running command
R  refresh
Q  quit

Cuando el servidor HTTP está en ejecución, ambos centros de control sondean /status para estadísticas en vivo del servidor, watcher, bloqueo e índice. Si el servidor HTTP no es accesible, recurren a leer manifest.json y module_map.json desde el disco.

Volcar el árbol de módulos

Árbol de texto:

python <indexer-root>\dump_module_tree.py \`
  --index-root <project-root>\.mcp-cpp-project-indexer

Escribir a archivo:

python <indexer-root>\dump_module_tree.py \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --output <project-root>\.mcp-cpp-project-indexer\module-tree.txt

Árbol de importación para un módulo:

python <indexer-root>\dump_module_tree.py \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --imports Example.Module:Partition \`
  --max-depth 5

Iniciar el servidor MCP

El servidor lee un índice existente. No reconstruye el índice.

python <indexer-root>\code_index_mcp_server.py \`
  --project-root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer

El servidor es de solo lectura y expone herramientas de localización/lectura a través de MCP stdio.

Para que el servidor mantenga su caché en memoria actualizada durante la edición, inícielo con el watcher integrado:

python <indexer-root>\code_index_mcp_server.py \`
  --project-root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --watch-index \`
  --watch-jobs 20

El watcher del servidor escribe todo el progreso en stderr para que stdout siga siendo JSON-RPC MCP válido. Después de un cambio real en el índice, recarga automáticamente la caché del servidor. Si un guardado solo cambia el mtime y el hash de contenido no cambia, omite la reconstrucción del mapa de módulos y la recarga de caché.

Si otro watcher ya es propietario de la misma raíz de índice, el servidor MCP continúa en modo de solo lectura y no inicia su propio watcher. Esto evita procesos de escritura concurrentes cuando múltiples clientes MCP inician instancias separadas de servidor stdio.

Transporte HTTP compartido

Para configuraciones donde múltiples clientes MCP iniciarían procesos de servidor stdio separados, el servidor también puede exponer la misma superficie MCP JSON-RPC a través de HTTP:

python <indexer-root>\code_index_mcp_server.py \`
  --project-root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --transport http \`
  --http-host 127.0.0.1 \`
  --http-port 8765 \`
  --watch-index \`
  --watch-jobs 20

El endpoint HTTP es:

POST http://127.0.0.1:8765/mcp

Endpoints de estado:

GET http://127.0.0.1:8765/health
GET http://127.0.0.1:8765/status

Esto mantiene un proceso de servidor de larga duración, una caché de índice en memoria y un watcher para la raíz del índice. Los clientes que solo admiten stdio aún necesitan una configuración stdio o un puente pequeño del lado del cliente hacia este endpoint HTTP.

API de gestión HTTP

Las UIs de control externas pueden habilitar opcionalmente una pequeña superficie de gestión en el mismo servidor HTTP. Está deshabilitada por defecto porque puede iniciar procesos de build/update.

python <indexer-root>\code_index_mcp_server.py \`
  --project-root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --transport http \`
  --http-host 127.0.0.1 \`
  --http-port 8765 \`
  --enable-management-api \`
  --management-token <token>

Endpoints:

GET  /management/status
GET  /server/management/capabilities
POST /management/command
GET  /management/log?since=<eventId>&limit=<n>
GET  /management/log/stream
GET  /management/server-log?since=<eventId>&limit=<n>
GET  /management/server-log/stream

/server/management/capabilities devuelve el contrato de intención/categoría/herramienta legible por máquina utilizado por capas externas de relay/gobernanza. El alias heredado /management/capabilities también se acepta.

/management/status incluye un objeto dashboard diseñado para centros de control externos. Contiene los mismos campos de alto valor que muestra la TUI:

dashboard.project.text
dashboard.index.text
dashboard.server.url / pid / ramText / cpuTimeText / cpuText / uptimeText
dashboard.watcher.runningText / lockText / last
dashboard.counts.filesText / symbolsText / dataText / modulesText / diagnosticsText
dashboard.stats.codeLinesText / tokensText / cpuTimeText / threadsText
dashboard.locks.updateFile / watcherFile
dashboard.mode.diagnosticFileSectionsText / jobsText / theme

Los valores numéricos sin procesar se incluyen junto a los campos formateados de *Text donde el servidor puede proporcionarlos. dashboard.mode.theme está reservado para UIs externas; el servidor HTTP en sí no posee un tema visual.

Los objetos genéricos server.process y management.runner.process también exponen campos de CPU normalizados cuando están disponibles:

cpuUserSeconds
cpuSystemSeconds
cpuTimeSeconds
cpuTimeText
cpuCoresAverage
cpuPercentMachine
cpuText

Cuando está configurado, el token protege la superficie HTTP MCP/estado compartida, así como los endpoints de gestión. Páselo como cualquiera de:

Authorization: Bearer <token>
x-api-key: <token>

Los comandos son objetos JSON únicos:

{ "command": "build", "jobs": 20 }
{ "command": "update", "jobs": 20 }
{ "command": "fast_update", "jobs": 20 }
{ "command": "module_map" }
{ "command": "reload_index" }
{ "command": "start_watcher", "jobs": 20 }
{ "command": "stop_watcher" }
{ "command": "stop_command", "wait": true }

/management/log devuelve la salida de comandos de gestión. /management/log/stream es el flujo SSE correspondiente. La salida de subprocesos de build y update se lee de forma asíncrona, por lo que una UI puede seguir sondeando el estado y transmitiendo registros mientras se indexan proyectos grandes.

/management/server-log devuelve eventos recientes de registro de tráfico HTTP/MCP, incluidos los recuentos de bytes de solicitud/respuesta y el detalle del método MCP cuando está disponible. /management/server-log/stream es el flujo SSE correspondiente para actividad de solicitudes en vivo. Los eventos MCP tools/call también incluyen un objeto estructurado compacto mcp con toolName, argumentKeys y arguments acotado para detalles expandibles de la UI. Después de que se conoce la respuesta JSON-RPC, el evento incluye mcp.outcome (success o error) y mcp.errorCount para que las UIs de control puedan colorear llamadas de herramientas fallidas sin analizar el payload de respuesta. Las solicitudes HTTP keep-alive restablecen los metadatos de registro locales de la solicitud, por lo que el sondeo de estado no puede heredar una etiqueta de llamada MCP anterior.

Perfiles de seguridad HTTP

El desarrollo local puede seguir usando HTTP de loopback:

--transport http --http-host 127.0.0.1 --http-port 8765

Para implementaciones de clientes o LAN, no exponga el servidor como HTTP sin cifrar. El servidor se niega a iniciarse en una dirección de enlace no loopback a menos que TLS y autenticación estén habilitados.

Perfiles de seguridad:

Perfil	Uso previsto	Requisitos
`local-dev`	desarrollo en la misma máquina	HTTP de loopback permitido
`trusted-lan`	Relay e indexador en hosts confiables diferentes	TLS más token o mTLS
`production`	implementación de cliente	TLS más token o mTLS

Ejemplo de TLS con autenticación de token:

python <indexer-root>\code_index_mcp_server.py \`
  --project-root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --transport http \`
  --http-host 10.0.0.20 \`
  --http-port 8765 \`
  --management-security-profile trusted-lan \`
  --management-tls cert \`
  --management-cert security\indexer-server.crt \`
  --management-key security\indexer-server.key \`
  --management-token <token> \`
  --management-cors-origin https://relay.customer.internal \`
  --management-allow-ip 10.0.0.12

Ejemplo de mTLS:

python <indexer-root>\code_index_mcp_server.py \`
  --project-root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --transport http \`
  --http-host 10.0.0.20 \`
  --http-port 8765 \`
  --management-security-profile production \`
  --management-tls cert \`
  --management-cert security\indexer-server.crt \`
  --management-key security\indexer-server.key \`
  --management-client-ca security\relay-clients-ca.crt \`
  --management-require-client-cert \`
  --management-cors-origin https://relay.customer.internal \`
  --management-allow-ip 10.0.0.12

Para pruebas locales cifradas sin un certificado de cliente, se puede generar un certificado autofirmado en el primer inicio:

python <indexer-root>\code_index_mcp_server.py \`
  --project-root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer \`
  --transport http \`
  --http-host 127.0.0.1 \`
  --http-port 8765 \`
  --management-tls self-signed \`
  --management-auto-cert

Los archivos generados se almacenan en:

<index-root>\certs\management-cert.pem
<index-root>\certs\management-key.pem

El TLS autofirmado cifra el tráfico pero no es confiable automáticamente para navegadores o clientes remotos. Las implementaciones de clientes deben usar una CA de cliente, un certificado público o material de confianza mTLS explícito.

Configuración de MCP en LM Studio

Ejemplo de mcp.json:

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "command": "python",
      "args": [
        "<indexer-root>\\code_index_mcp_server.py",
        "--project-root",
        "<project-root>",
        "--index-root",
        "<project-root>\\.mcp-cpp-project-indexer"
      ]
    }
  }
}

Para un servidor HTTP compartido sin autenticación de token:

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Si el servidor HTTP se inició con --management-token <token>, LM Studio debe enviar ese token como encabezado:

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

El servidor también acepta X-API-Key:

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "X-API-Key": "<token>"
      }
    }
  }
}

Después de reconstruir el índice o el mapa de módulos, reinicie el servidor MCP / LM Studio.

Configuración de Codex

Para Codex, configure este repositorio como un servidor MCP stdio y coloque las reglas del agente donde Codex las cargue como instrucciones del proyecto.

Ejemplo de entrada de servidor MCP:

[mcp_servers.mcp-cpp-project-indexer]
command = "python"

args = [
  "<indexer-root>\\code_index_mcp_server.py",
  "--project-root",
  "<project-root>",
  "--index-root",
  "<project-root>\\.mcp-cpp-project-indexer",
]

Las reglas de prompt de prompt_template.md deben copiarse en un archivo AGENTS.md en la raíz del proyecto que Codex abra, por ejemplo:

<project-root>\AGENTS.md

Codex lee AGENTS.md como instrucciones de repositorio/proyecto para el árbol de trabajo actual. Si normalmente inicia Codex desde un espacio de trabajo principal en lugar de la raíz del proyecto C++, coloque el archivo en esa raíz del espacio de trabajo o abra Codex directamente en la raíz del proyecto C++ para que las instrucciones estén en alcance.

Mantenga la configuración del servidor MCP y las reglas de prompt separadas:

La configuración de MCP inicia el servidor de herramientas y lo apunta al índice generado.
AGENTS.md le dice al agente cómo usar las herramientas de manera segura y compacta.

Después de cambiar la configuración del servidor MCP o reconstruir el índice, reinicie el servidor MCP / sesión de Codex para que el esquema de herramientas actualizado sea visible.

Configuración de Claude

Claude Code y Claude Desktop usan MCP de manera ligeramente diferente, así que mantenga la configuración dividida por cliente.

Claude Code

Para Claude Code, coloque la configuración del servidor MCP en un archivo .mcp.json con alcance de proyecto en la raíz del proyecto si la configuración debe viajar con el repositorio:

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "type": "stdio",
      "command": "python",
      "args": [
        "<indexer-root>\\code_index_mcp_server.py",
        "--project-root",
        "<project-root>",
        "--index-root",
        "<project-root>\\.mcp-cpp-project-indexer"
      ],
      "env": {}
    }
  }
}

Configuración CLI equivalente:

claude mcp add mcp-cpp-project-indexer --scope project -- \`
  python <indexer-root>\code_index_mcp_server.py \`
  --project-root <project-root> \`
  --index-root <project-root>\.mcp-cpp-project-indexer

Copie las reglas de prompt_template.md en el archivo de memoria del proyecto de Claude Code:

<project-root>\CLAUDE.md

Claude Code también admite .claude/CLAUDE.md; use esa ruta si prefiere mantener archivos específicos de Claude bajo .claude/. Lo importante es que el archivo esté en la raíz del proyecto que Claude Code abre; de lo contrario, las reglas de uso de herramientas pueden no cargarse.

Claude Desktop

Claude Desktop usa su archivo de configuración MCP de la aplicación. En Windows, esto suele estar en:

%APPDATA%\Claude\claude_desktop_config.json

Agregue el servidor bajo mcpServers:

{
  "mcpServers": {
    "mcp-cpp-project-indexer": {
      "type": "stdio",
      "command": "python",
      "args": [
        "<indexer-root>\\code_index_mcp_server.py",
        "--project-root",
        "<project-root>",
        "--index-root",
        "<project-root>\\.mcp-cpp-project-indexer"
      ],
      "env": {}
    }
  }
}

Claude Desktop no lee automáticamente archivos de instrucciones del repositorio como CLAUDE.md para chats arbitrarios. Pegue las reglas relevantes de prompt_template.md en las instrucciones de proyecto/chat que use con Claude Desktop, o use Claude Code cuando necesite instrucciones persistentes con alcance de repositorio.

Después de cambiar .mcp.json, claude_desktop_config.json o reconstruir el índice, reinicie el cliente de Claude para que el esquema de herramientas actualizado sea visible.

Posibles configuraciones de flujo de trabajo

Búsqueda de errores basada en código fuente

Un flujo de trabajo práctico de revisión es usar mcp-cpp-project-indexer como capa de navegación principal y dejar que la IA razone solo a partir de rangos de código fuente exactos que haya leído.

Flujo típico:

1. User asks:
     Review module X, file X, or function X for bugs.

2. AI uses mcp-cpp-project-indexer:
     find module/file/symbol
     read exact source ranges
     follow only relevant project-local calls
     avoid whole-file reads unless needed

3. AI reports findings:
     file path
     line range
     source-grounded explanation
     uncertainty where more context is needed

4. AI uses Visual Studio MCP only after analysis:
     open the file
     navigate to the exact finding location

Esto mantiene el contexto del modelo limpio. El indexador maneja el enrutamiento y la reducción de tokens; la IA realiza el análisis a partir de líneas de código fuente originales; Visual Studio se usa como traspaso de editor orientado al desarrollador.

Prioridad de herramientas con Visual Studio MCP

En proyectos con muchos módulos C++20, las herramientas de estilo Visual Studio/IntelliSense/clangd pueden fallar al resolver símbolos de módulos de manera confiable para la navegación de IA.

División de roles recomendada:

mcp-cpp-project-indexer
  Primary navigation layer.
  Use for symbols, files, modules, source ranges, imports, imported-by metadata.

Visual Studio MCP
  Editor and project-state layer.
  Use for opening files, jumping to locations, looking at build/output/editor state.
  Do not use as the primary C++20 module symbol resolver.

IDAPro MCP
  Binary/decompiler layer.
  Use only when source evidence is insufficient, or for ABI, crash, reverse
  engineering, decompiled code, imports/exports, or binary-behavior questions.

Regla de prompt:

Use mcp-cpp-project-indexer first for C++ source navigation.
Use Visual Studio MCP only when IDE/editor/build state is needed.
Use IDAPro MCP only when the question requires binary or decompiler evidence.

Evidencia de código fuente más binaria para APIs no documentadas

Para código que interactúa con componentes de Windows no documentados, la evidencia del código fuente puede no ser suficiente. Una configuración útil es mantener la DLL relevante cargada en IDAPro y dejar que la IA inspeccione código descompilado/desensamblado solo cuando la evidencia a nivel de código fuente deje el comportamiento poco claro.

Escenario de ejemplo:

Project code uses wrappers around undocumented DirectUI behavior.
IDAPro has dui70.dll loaded.

1. AI uses mcp-cpp-project-indexer first:
     find the project wrapper/function
     read the exact source range
     follow only relevant local calls

2. If behavior is still unclear:
     use IDAPro MCP to inspect the corresponding function, import, export,
     vtable target, or decompiled implementation in dui70.dll

3. AI combines evidence:
     source callsite and wrapper behavior
     binary/decompiler evidence from the undocumented implementation
     final finding with source line ranges and binary evidence notes

4. AI uses Visual Studio MCP only for handoff:
     open the project source file
     navigate to the line that should be reviewed or changed

Esto mantiene el trabajo de ingeniería inversa dirigido. La IA no navega el binario a ciegas; entra en IDAPro con una pregunta basada en el código fuente. Eso reduce el contexto irrelevante, reduce el uso de tokens y ayuda al modelo a mantener la cadena de razonamiento fuente/binario intacta.

Por qué esta configuración funciona

La parte costosa de la revisión de código con IA a menudo no es el razonamiento; es localizar la pequeña cantidad de código fuente que realmente importa. El indexador reduce el problema de navegación a metadatos compactos y rangos de código fuente exactos. Otras herramientas pueden entonces mantenerse enfocadas en lo que hacen bien: interacción con IDE, estado de compilación o hechos binarios.

Referencia de línea de comandos

build_file_index.py

Construye un índice JSON por archivo.

--file PATH                    C++ source/module file to index. Required.
--project-root PATH            Root used for normalized relative paths.
--output PATH                  Output JSON path.
--output-root PATH             Directory used when --output is omitted.
--case-insensitive-paths / --no-case-insensitive-paths
                               Case-fold relative paths before hashing. Default: true.
--blank-comments / --no-blank-comments
                               Blank comments before scanning while preserving lines.
--emit-diagnostics / --no-emit-diagnostics
                               Include scanner diagnostic data.
--print-summary-json           Print summary JSON.

build_project_index.py

Construye el índice completo del proyecto.

--root PATH                    Project/source root. Default: current directory.
--output-root PATH             Index output root. Default: <root>/.mcp-cpp-project-indexer.
--extensions EXT [EXT ...]     Source extensions, e.g. .cpp .cc .mm .h .ixx or cpp,h,ixx.
--include-extensionless-headers / --no-include-extensionless-headers
                               Also discover extensionless files that look like
                               C/C++ headers. Uses a conservative first-lines
                               heuristic. Default: false.
--git-ignore / --no-git-ignore Filter discovered files through git check-ignore
                               when available. Default: true.
--exclude-dir NAME             Extra excluded directory name. Repeatable or comma-separated.
--case-insensitive-paths / --no-case-insensitive-paths
                               Case-fold relative paths before hashing. Default: true.
--blank-comments / --no-blank-comments
                               Blank comments before scanning. Default: true.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Include scanner diagnostic fields in files/<fileId>.json.
                               Compatibility alias: --emit-debug-file-indexes.
                               Default: false.
--print-summary-json           Print summary JSON.
--list-defaults                Print default extensions and excluded directories.
--jobs N                       Worker processes. 1 = sequential, 0 = conservative auto.
--progress / --no-progress     Show progress on stderr. Default: true.

update_project_index.py

Actualiza incrementalmente un índice de proyecto existente.

--root PATH                    Project/source root. Default: current directory.
--index-root PATH              Index root. Default: <root>/.mcp-cpp-project-indexer.
--extensions EXT [EXT ...]     Source extensions for discovery.
--include-extensionless-headers / --no-include-extensionless-headers
                               Also discover extensionless files that look like
                               C/C++ headers. Uses a conservative first-lines
                               heuristic. Default: false.
--git-ignore / --no-git-ignore Filter discovered files through git check-ignore
                               when available. Default: true.
--exclude-dir NAME             Extra excluded directory name. Repeatable or comma-separated.
--case-insensitive-paths / --no-case-insensitive-paths
                               Case-fold relative path keys. Default: true.
--blank-comments / --no-blank-comments
                               Blank comments before scanning changed files. Default: true.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Include scanner diagnostic fields in updated file indexes.
                               Compatibility alias: --emit-debug-file-indexes.
                               Default: false.
--dry-run                      Show added/modified/deleted files without writing.
--jobs N                       Worker processes for added/modified files.
--force                        Reindex all current files.
--known-files-only             Only consider files already present in manifest.json.
--changed-file PATH            Known changed file. Repeatable. Used by watchers to avoid
                               hashing unchanged files.
--progress / --no-progress     Show progress on stderr. Default: true.
--print-summary-json           Print summary JSON.
--summary-json-file PATH       Write summary JSON while keeping normal console output.

watch_project_index.py

Monitorea archivos fuente y ejecuta actualizaciones incrementales después de que los cambios se estabilicen.

--root PATH                    Project/source root. Default: current directory.
--index-root PATH              Index root. Default: <root>/.mcp-cpp-project-indexer.
--indexer-root PATH            Directory containing the indexer scripts.
--extensions EXT [EXT ...]     Source extensions for snapshot scanning.
--include-extensionless-headers / --no-include-extensionless-headers
                               Also discover extensionless files that look like
                               C/C++ headers. Uses a conservative first-lines
                               heuristic. Default: false.
--git-ignore / --no-git-ignore Filter discovered files through git check-ignore
                               when available. Default: true.
--exclude-dir NAME             Extra excluded directory name. Repeatable or comma-separated.
--case-insensitive-paths / --no-case-insensitive-paths
                               Case-fold relative path keys. Default: true.
--jobs N                       Worker process count for update actions.
--poll-interval SECONDS        Poll interval. Default: 1.0.
--debounce SECONDS             Wait for changes to settle. Default: 1.5.
--module-map / --no-module-map Rebuild module_map.json after real index changes. Default: true.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Pass diagnostic emission to watcher-triggered updates.
                               Compatibility alias: --emit-debug-file-indexes.
                               Default: false.

build_module_map.py

Construye metadatos de relaciones de módulos a partir del índice del proyecto.

--index-root PATH              Project index root. Default: ./.mcp-cpp-project-indexer.
--output PATH                  Output JSON path. Default: <index-root>/module_map.json.
--print-summary-json           Print compact summary JSON.

dump_module_tree.py

Vuelca vistas legibles del árbol de módulos/importaciones.

--index-root PATH              Project index root. Default: ./.mcp-cpp-project-indexer.
--imports MODULE               Dump import tree for one C++20 module name.
--max-depth N                  Maximum tree depth. For --imports, default is 4.
--max-files N                  Maximum file paths per module leaf. Default: 1.
--output PATH                  Optional output text file.

code_index_mcp_server.py

Ejecuta el servidor MCP stdio.

--project-root PATH            Project root used for read_range/read_symbol.
--index-root PATH              Directory containing the generated index.
--watch-index / --no-watch-index
                               Start server-managed background watcher. Default: false.
--watch-poll-interval SECONDS  Watcher poll interval. Default: 1.0.
--watch-debounce SECONDS       Watcher debounce delay. Default: 1.5.
--watch-jobs N                 Worker process count for watcher update actions.
--watch-module-map / --no-watch-module-map
                               Rebuild module_map.json after watcher updates. Default: true.
--watch-emit-diagnostic-file-indexes / --no-watch-emit-diagnostic-file-indexes
                               Pass diagnostic emission to server watcher updates.
                               Compatibility alias: --watch-emit-debug-file-indexes.
                               Default: false.
--watch-include-extensionless-headers / --no-watch-include-extensionless-headers
                               Let the server watcher discover extensionless files
                               that look like C/C++ headers. Default: false.
--watch-git-ignore / --no-watch-git-ignore
                               Filter watcher discovery through git check-ignore
                               when available. Default: true.
--transport stdio|http         Transport mode. Default: stdio.
--http-host HOST               HTTP bind host for --transport http. Default: 127.0.0.1.
--http-port PORT               HTTP bind port for --transport http. Default: 8765.

indexer_control.py

Centro de control de terminal para flujos de trabajo de compilación/actualización/monitoreo/servidor.

--root PATH                    C++ project root. Default: current directory.
--index-root PATH              Index root. Default: <root>/.mcp-cpp-project-indexer.
--indexer-root PATH            Directory containing indexer scripts.
--jobs N                       Worker process count for launched commands.
--http-url URL                 HTTP server base URL for live status.
                               Default: http://127.0.0.1:8765.
--enable-management-api / --no-enable-management-api
                               Enable the TUI's HTTP + management launch mode.
--management-token TOKEN       Management API token used when launching
                               HTTP + management.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Initial diagnostic file section setting.

indexer_tui.py

Interfaz de terminal Textual opcional con soporte de mouse y paneles de estado en vivo. Requiere pip install -r requirements-ui.txt.

--root PATH                    C++ project root. Default: current directory.
--index-root PATH              Index root. Default: <root>/.mcp-cpp-project-indexer.
--indexer-root PATH            Directory containing indexer scripts.
--jobs N                       Worker process count for launched commands.
--http-url URL                 HTTP server base URL for live status.
                               Default: http://127.0.0.1:8765.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Initial diagnostic file section setting.

indexer_menu.py

Menú interactivo heredado y envoltorio de comandos no interactivo. Prefiere indexer_control.py para operación normal.

--root PATH                    C++ project root. Default: current directory.
--index-root PATH              Index root. Default: <root>/.mcp-cpp-project-indexer.
--indexer-root PATH            Directory containing the indexer scripts.
--jobs N                       Worker process count for build/update actions.
--emit-diagnostic-file-indexes / --no-emit-diagnostic-file-indexes
                               Initial menu switch state for scanner diagnostic file sections.
                               Compatibility alias: --emit-debug-file-indexes.
                               Default: false.
--action NAME                  Run one action without the menu.

Valores admitidos de --action:

build-index
build-module-map
build-all
update-dry-run
update-known-dry-run
update-index
update-known
update-all
update-known-all
watch
summary
diagnostics
dump-module-tree
lmstudio-config
server
server-watch
server-http-watch

Resumen de herramientas

Resumen del proyecto

get_project_summary
get_index_fingerprint
get_file_fingerprint(file)
get_symbol_fingerprint(symbolId)
get_data_fingerprint(dataId)
validate_fingerprints(items)

El servidor expone un índice stateFingerprint: una huella digital económica del lado del servidor sobre los artefactos de índice actuales (manifest.json, index.sqlite, archivos de módulo/diagnóstico/actualización). Cambia cuando el estado del índice cargado cambia, por lo que las capas de retransmisión/orquestación pueden marcar evidencia de herramientas más antigua como obsoleta después de una reconstrucción, actualización o recarga de caché.

Cada resultado de herramienta MCP lleva la huella digital en el resultado _meta:

{
  "_meta": {
    "stateFingerprint": "..."
  }
}

El mismo valor también se expone mediante get_project_summary.stateFingerprint y el punto final de estado HTTP bajo index.stateFingerprint.

Para reutilización de evidencia de grano fino, prefiere las herramientas de huella digital. La huella digital global del índice es solo una señal de advertencia. Las huellas digitales de archivo, símbolo y datos permiten que una retransmisión valide hechos activos sin descartar toda la caché de evidencia después de cada actualización:

fileFingerprint =
  hash(fileId + relativePath + contentHash + line/token counts)

symbol/data fingerprint =
  hash(id + fileFingerprint + startLine + endLine + signature)

validate_fingerprints es el punto de entrada por lotes para capas de retransmisión/orquestación. Acepta hasta 500 elementos de archivo/símbolo/datos y devuelve solo metadatos compactos de validez y huella digital. Estas llamadas no leen ni devuelven texto fuente.

Herramientas de seguimiento de cambios

Estas herramientas se exponen solo cuando git.exe está disponible y project-root está dentro de un árbol de trabajo. Son de solo lectura y no exponen un ejecutor de comandos genérico.

list_changed_files
list_recent_revisions
get_revision_summary
get_file_change_hunks
resolve_hunk_to_indexed_range

Úsalas para cambios actuales, revisiones recientes, inspección de fragmentos, revisión de archivos modificados y sugerencias de mensajes de confirmación.

Usa resolve_hunk_to_indexed_range(file, line|startLine/endLine) cuando los metadatos de fragmentos den un rango de nuevas líneas cambiado y la retransmisión necesite un objetivo de enrutamiento symbolId / dataId válido antes de leer el código fuente. Devuelve rangos de símbolo/datos indexados que contienen, se superponen o están más cerca del rango cambiado. Esto es solo metadatos y no interpreta el diff ni afirma corrección.

Cuando el usuario dice que arregló, cambió, guardó, actualizó, confirmó o quiere que se revise el trabajo actual, el agente debe verificar estas herramientas antes de la navegación normal de código fuente. En configuraciones de monitoreo, el índice puede ya estar actualizado, y las herramientas de cambio proporcionan la ruta más económica a los rangos de archivo/símbolo afectados.

get_file_change_hunks puede incluir indexedRanges, que son intersecciones entre rangos de líneas de fragmentos cambiados y rangos de símbolo/datos indexados. Estos son solo indicaciones de enrutamiento. Lee el código fuente relevante con read_symbol o read_range antes de hacer afirmaciones de implementación.

Para enrutamiento de revisión de bajo token, llama a get_file_change_hunks con includeIndexedRangeSummary:true, includeIndexedRanges:false y includeSource:false. El summaryByIndexedRange devuelto agrupa fragmentos cambiados por rango de símbolo/dato indexado afectado sin repetir cada intersección por fragmento.

Después de seleccionar un rango afectado, pasa symbolId o dataId de vuelta a get_file_change_hunks para devolver solo fragmentos que se cruzan con ese rango de símbolo/datos. Esto sigue siendo filtrado de rango de líneas, no análisis semántico.

Herramientas de símbolo y código fuente

find_symbol(query)
find_declaration(query)
find_symbols_glob(pattern)
read_symbol(symbolId)
read_range(file, startLine, endLine)
read_range(file, line, beforeLines, afterLines)
get_nearest_symbol_for_line(file, line)
list_file_symbols(file)

get_nearest_symbol_for_line mapea un archivo/línea de diagnósticos, fragmentos, salida de compilación, Visual Studio o notas de IDA a rangos de símbolo/datos indexados que contienen o están más cerca. Es solo metadatos; lee el rango de código fuente seleccionado antes de hacer afirmaciones de comportamiento.

read_symbol acepta startOffset / endOffset opcionales o startLine / endLine absolutos para leer solo una porción de un cuerpo de símbolo grande.

read_range acepta startLine / endLine explícitos o una forma compacta de línea alrededor con line, beforeLines y afterLines. La forma de línea alrededor está destinada a diagnósticos, fragmentos, coincidencias de búsqueda, transferencia de Visual Studio y notas de IDA donde el llamador tiene una línea de código fuente relevante.

find_symbol busca solo metadatos de símbolos:

shortName exacto
qualifiedName / alias exactos
subcadena de respaldo sobre shortName, qualifiedName y signature

Controles de enrutamiento opcionales:

compact: devuelve solo campos de enrutamiento compactos
responseFormat: JSON pretty o minified para respuestas de metadatos
omitNulls: omite campos nulos de respuestas de metadatos
omitEmpty: omite arreglos/objetos vacíos de respuestas de metadatos
symbolTypes: filtra por tipo de símbolo indexado, p. ej., method, function, type_alias
container: filtra a símbolos contenidos por un nombre o sufijo de clase/estructura/espacio de nombres
file: filtra a un fileId o ruta relativa al proyecto
filePattern: filtra por glob de ruta relativa al proyecto
exactOnly: devuelve solo coincidencias exactas de nombre corto o nombre calificado, incluidas coincidencias exactas sin distinción de mayúsculas
hideNamespaces: oculta símbolos de reapertura de espacio de nombres de resultados de navegación

Usa container solo para el contenedor léxico/índice real donde se declara el símbolo. No uses un contenedor de clase para funciones auxiliares libres solo porque esa clase las llama. Si una consulta find_symbol con container no devuelve resultado, reintenta el nombre de símbolo exacto sin container antes de recurrir a search_source.

Cada elemento devuelto incluye matchKind para describir por qué coincidió. Coincidencias fuertes como exact_qualified_name y exact_short_name suelen ser las mejores para enrutamiento. Coincidencias de subcadena, firma y metadatos son candidatos más débiles que deben desambiguarse antes de leer el código fuente.

No combines file y filePattern. Estos controles son filtros de localización; no leen código fuente y no resuelven sobrecargas semánticamente.

Las opciones de empaquetado de respuestas se exponen solo en herramientas de metadatos/enrutamiento. Las herramientas de código fuente mantienen su salida de código fuente numerada por líneas sin cambios.

list_file_symbols también puede devolver listas más pequeñas de candidatos de símbolos a nivel de archivo cuando el archivo ya se conoce:

compact: devuelve solo campos de enrutamiento compactos
symbolTypes: filtra por tipo de símbolo indexado
container: filtra a símbolos contenidos por un nombre o sufijo de clase/estructura/espacio de nombres
hideNamespaces: oculta símbolos de reapertura de espacio de nombres
limit: limita el tamaño del resultado

Esto es solo un filtro de localización. No resuelve herencia, sobrecargas ni semántica de tipos.

Cuando un archivo ya se conoce y tanto los miembros de clase como las funciones auxiliares locales pueden importar, prefiere list_file_symbols(file, compact:true, hideNamespaces:true) antes de adivinar un filtro container. Los auxiliares de espacio de nombres anónimo siguen siendo funciones indexadas normales; pueden tener el espacio de nombres nombrado circundante como su contenedor, no la clase que los llama.

search_source acepta symbolId para buscar solo dentro de un rango de símbolo indexado. Esta es la forma preferida de hacer una verificación léxica dentro de una función o método ya localizado. Sigue siendo búsqueda léxica de código fuente, no resolución semántica de llamadas/referencias.

Argumento canónico:

{ "query": "Editor::_OnScroll" }

name puede aceptarse como alias de compatibilidad, pero query es canónico.

Herramientas de archivo

find_files(pattern)
list_file_includes(file)
get_file_structure(file)

Glob sobre rutas relativas al proyecto solamente. Esto no es búsqueda grep de código fuente.

list_file_includes devuelve las directivas léxicas #include para un archivo. Está destinado a bases de código C++ clásicas basadas en includes, como Chromium:

{
  "file": "chrome/app/chrome_main.cc",
  "compact": true,
  "includeResolved": true
}

Los metadatos de includes son solo evidencia de enrutamiento. El indexador registra la línea de código fuente, el texto objetivo, el tipo de include (quote, angle o macro) y la resolución relativa al proyecto de mejor esfuerzo cuando el archivo incluido es directamente visible. No evalúa #if / #ifdef, directorios de includes del compilador, encabezados generados ni expansión de macros.

get_file_structure devuelve una tabla de contenidos solo de metadatos para un archivo. Para archivos grandes, prefiere includeOutline:false primero. Usa includeIncludes:true cuando se necesiten metadatos de includes. Usa symbolTypes, dataKinds, hideNamespaces, outlineLimit y compactOutline:true para mantener las respuestas pequeñas. Después de identificar un elemento de esquema relevante, lee el código fuente con read_symbol o read_range antes de hacer afirmaciones de implementación.

Cuando los índices de archivo se construyeron con --emit-diagnostic-file-indexes, get_file_structure también puede incluir secciones de diagnóstico opcionales de analizador/indexador:

{
  "file": "...",
  "includeOutline": false,
  "includeIndexerDiagnostics": true,
  "diagnosticKinds": ["structuralEvents", "scopeIntervals", "functionBodyRanges"],
  "diagnosticStartLine": 120,
  "diagnosticEndLine": 180,
  "compactDiagnostics": true,
  "diagnosticLimit": 100
}

Usa esto solo para investigar diagnósticos de analizador, símbolos faltantes, rangos de código fuente sospechosos o detección inesperada de alcance/cuerpo de función. La salida de diagnóstico del indexador es evidencia de escáner, no comportamiento de implementación.

La redacción de la solicitud importa aquí. La frase "información de depuración" es demasiado amplia para muchos agentes de IA y puede confundirse con código de compilación de depuración de C++ como DEBUG, _DEBUG, #ifdef DEBUG, depuración de Visual Studio o ramas de registro. Para datos de escáner del indexador, solicita diagnósticos de indexador/analizador explícitamente.

Herramientas de orientación

get_project_orientation()
list_orientation_nodes()
get_orientation_node(path)
search_orientation(query)

Si un proyecto contiene archivos README.md / readme.md a nivel de carpeta con el bloque de orientación estándar, o archivos Markdown con topology en el nombre de archivo, el indexador los registra como metadatos de orientación opcionales. Esto le da a un agente de IA un mapa de proyecto económico antes de leer el código fuente de implementación. Los README de carpetas usan kind: "folder_orientation"; los documentos de topología usan kind: "topology".

Estas herramientas se exponen dinámicamente. Si el índice cargado no tiene nodos de orientación/topología, tools/list y los metadatos de capacidad de gestión omiten las herramientas de orientación.

La capa de orientación extrae campos estructurados solo de los encabezados de README de orientación vinculantes del indexador de proyectos:

Purpose:
Use this folder when the question is about:
Do not use this folder first when the question is about:
## Map
## Start Here
## Boundaries

Encabezados heredados como Responsibilities, Non-responsibilities, Use when, Current layout o Responsibility Boundaries siguen siendo solo texto Markdown ordinario. No pueblan campos de orientación estructurados. Las entradas ## Map se analizan de bloques text delimitados con al menos dos espacios entre el nombre de la entrada y la descripción; las entradas resueltas incluyen targetRootRelativePath y pathStatus.

search_orientation usa búsqueda de enrutamiento BM25 y devuelve schema: "cpp.project_orientation.search.v2.1", algorithm: "bm25", diagnósticos de términos de consulta, puntuaciones, campos de coincidencia y términos anti-coincidencia. Los resultados son solo indicaciones de enrutamiento.

Úsalo para preguntas de arquitectura y navegación:

{
  "query": "MCP dispatch",
  "limit": 10
}

Luego lee el nodo de orientación seleccionado:

{
  "path": "src/server/core/mcp"
}

Los metadatos de orientación no son evidencia de implementación. Responden:

Where should I start?
Which subsystem owns this responsibility?
Which folder should I not inspect first?

No responden qué hace una función, si el código es correcto o si un comportamiento en tiempo de ejecución está garantizado. Para esas afirmaciones, localiza y lee el código fuente con find_symbol, list_file_symbols, read_symbol o read_range.

Buenas solicitudes:

Show me which indexer diagnostics are present.
Show me the parser/indexer diagnostics from the index.
Show me indexerDiagnostics.diagnostics from get_file_structure(includeIndexerDiagnostics:true) for file X.
Which indexerDiagnostics.diagnostics are available in the index for file X?
Show me the source location for this indexer diagnostic.

Evita solicitudes ambiguas como:

Show me debug information.
Find the debug code.
Where is DEBUG used?

El flujo de trabajo previsto es:

get_file_structure(includeIndexerDiagnostics:true, compactDiagnostics:true)
-> inspect indexerDiagnostics.diagnostics first
-> read_range around the reported line
-> optionally get_nearest_symbol_for_line for the containing symbol

Ejemplos:

*Editor*
*/TextEditor/*.ixx
*/Shell/Browser/*

Herramientas de módulos

find_module(moduleName)
list_module_files(moduleName)
search_modules(pattern)
get_module_map_summary
get_module_info(moduleName)
list_module_imports(moduleName)
list_module_imported_by(moduleName)
get_module_tree(maxDepth)

Usa la sintaxis de módulos C++20:

Example.Module:Partition
uiframework.Elements:ElementImpl

No pases sintaxis de espacios de nombres de C++ a las herramientas de módulos:

Example::Namespace
UIFramework::Elements

Para espacios de nombres/clases/funciones, usa find_symbol o find_symbols_glob.

La dirección importa:

What does module X import?       -> list_module_imports(X) or get_module_info(X)
Who imports/consumes module X?   -> list_module_imported_by(X) or get_module_info(X)

No respondas preguntas de importación inversa buscando primero en el texto fuente. El mapa de módulos ya almacena metadatos de importedBy. Usa lecturas de fuente solo cuando quien pregunta solicite inspeccionar la línea de importación real o cuando los metadatos parezcan sospechosos.

Las herramientas de metadatos de módulos aceptan compact:true cuando sea útil:

find_module / list_module_files: campos compactos de enrutamiento de módulos/archivos
get_module_info: metadatos compactos de archivos, importaciones e importados por
list_module_imports: registros compactos de importaciones salientes
list_module_imported_by: registros compactos de módulos importadores

Herramientas de datos/miembros

find_data(query)
list_type_members(container)
read_data(dataId)
resolve_code_entity(query, file?, line?, container?)

Usa find_data para campos, globales, constantes de espacios de nombres, valores de enumeración, plantillas de variables y conceptos. Usa list_type_members cuando el tipo contenedor o el espacio de nombres ya sea conocido. Ambas herramientas son solo de metadatos y aceptan compact:true para una salida de enrutamiento más pequeña.

Usa resolve_code_entity cuando un rango de fuente contenga un identificador y la IA necesite decidir si probablemente sea una declaración de campo/dato, un símbolo invocable, un símbolo de tipo o un candidato ambiguo antes de elegir la siguiente herramienta de lectura. Acepta contexto opcional de archivo, línea y contenedor, y devuelve candidatos de metadatos clasificados más una herramienta siguiente recomendada como read_data o read_symbol.

resolve_code_entity sigue siendo solo orientación. No realiza búsqueda de nombres del compilador, resolución de sobrecarga, expansión de macros, resolución de tipos de C++ ni resolución semántica de referencias. Las afirmaciones a nivel de fuente aún requieren read_data, read_symbol o read_range.

typeText es el texto fuente original para el tipo de declaración. No es un tipo resuelto por el compilador. Trátalo como una pista para búsquedas adicionales de símbolos/fuente, no como prueba de identidad de tipo semántico.

Herramientas de grafo de funciones

get_function_body_graph(symbolId, mode?)
get_call_xrefs_from(symbolId)
get_call_xrefs_to(symbolId)
get_symbol_neighborhood(symbolId)

Usa get_function_body_graph después de localizar un símbolo invocable cuando la IA necesite aristas directas de estructura de fuente desde el cuerpo de esa función: candidatos de llamadas locales al proyecto, llamadas no resueltas/externas, accesos a datos/miembros y marcadores de flujo de control. Es bajo demanda y consciente de caché; no cambia la ruta normal de construcción del índice.

Modos útiles:

compute_if_missing: reutiliza un grafo en caché compatible o calcúlalo.
cache_only: devuelve solo datos de grafo en caché compatibles.
refresh: recalcula el grafo para ese símbolo y reemplaza las aristas persistidas.

Las herramientas de referencias cruzadas y vecindario leen solo aristas de grafo persistidas:

get_call_xrefs_from: aristas de llamadas almacenadas salientes de una función.
get_call_xrefs_to: aristas de llamadas almacenadas entrantes a una función.
get_symbol_neighborhood: vecindario compacto de destino/llamante/llamado.

Calcula o actualiza get_function_body_graph para los llamantes relevantes antes de confiar en la completitud de referencias cruzadas. La salida del grafo de funciones es solo evidencia estructural de navegación: claimStrength=source_structure_allowed y behaviorClaimsAllowed=false. No es análisis de comportamiento, semántica de API externa, prueba de despacho dinámico ni resolución de sobrecarga precisa del compilador.

Más detalles en Herramientas MCP de Grafo de Funciones.

El modelo debe seguir estas reglas:

Use mcp-cpp-project-indexer as a deterministic source-range locator.
Read source before making implementation claims.
Use query as the canonical argument for symbol lookup tools.
Do not ask for analyze_symbol.
Use function graph tools only as structural navigation evidence.
Do not treat module metadata as implementation behavior.

Nota sobre exposición de herramientas

Los conjuntos grandes de herramientas MCP funcionan mejor cuando el cliente mantiene las herramientas activas relevantes a la tarea actual. Si cada herramienta se expone para cada solicitud, algunos modelos pueden sobreexplorar, repetir consultas similares o elegir herramientas más amplias de lo necesario. Este es un comportamiento normal para modelos de propósito general y no indica un problema con los datos del índice.

En uso típico, comienza con consultas de metadatos compactas y lee rangos de fuente solo cuando se necesite evidencia de implementación.

Llamadas correctas:

find_symbol({"query": "Editor::_OnScroll"})
find_declaration({"query": "OnNotifyReflect"})

Evita:

find_symbol({"name": "Editor::_OnScroll"})

La plantilla completa del mensaje del sistema está disponible en prompt_template.md.

Flujos de trabajo de ejemplo

Encontrar declaración y definición

Usuario:

Find the declaration and definition of OnNotifyReflect.

Flujo de trabajo de IA:

find_symbol({"query": "OnNotifyReflect"})
read_symbol(symbolId for declaration)
read_symbol(symbolId for definition)

Analizar una función bajo demanda

Usuario:

Show me Editor::_OnScroll.

Flujo de trabajo de IA:

find_symbol({"query": "Editor::_OnScroll"})
read_symbol(symbolId)

Luego la IA sigue solo las llamadas locales relevantes al proyecto:

GetHWND -> find_symbol/read_symbol
SendMessageW -> external Win32 API, do not query project index
MAKEWPARAM -> external Win32 macro, do not query project index

Cómo se usa un módulo importado

Flujo de trabajo:

1. get_module_info or list_module_imports/list_module_imported_by
2. use relativePath and sourceLine from import metadata
3. list_file_symbols(relativePath)
4. choose the likely entry point from symbol names/signatures
5. read_symbol(candidate)
6. inspect visible source usage
7. follow more project symbols only if needed

No uses find_symbols_glob como sustituto de la búsqueda de uso en fuente. Busca metadatos de símbolos, no sitios de llamada.

Reglas de diseño

Los números de línea exactos son el corazón del sistema

symbolId -> fileId -> startLine/endLine -> original source

Mantén pequeños los datos en tiempo de ejecución

El índice en tiempo de ejecución almacena hechos de enrutamiento. Los datos de diagnóstico del escáner son opcionales con --emit-diagnostics o --emit-diagnostic-file-indexes.

Mantén separados búsqueda y navegación

index.sqlite               -> symbol/data search
module_map.json            -> module browsing
manifest.json              -> file browsing

Los diagnósticos permanecen visibles

No ocultes problemas reales del analizador/fuente solo para alcanzar cero diagnósticos.

Sin expansión de alcance semántico

Sin grafo de llamadas. Sin grafo de referencias. Sin expansión de macros. Sin herramienta de análisis. La IA explora recursivamente la fuente bajo demanda.

Secuencia de reconstrucción

cd <project-root>

python <indexer-root>\build_project_index.py

python <indexer-root>\build_module_map.py \`
  --index-root .\.mcp-cpp-project-indexer

Luego reinicia el servidor MCP / LM Studio.

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0.

SPDX-License-Identifier: Apache-2.0

Agrega el texto completo de la licencia Apache-2.0 en el repositorio como:

LICENSE

Encabezado opcional de archivo fuente:

# SPDX-License-Identifier: Apache-2.0

Derechos de autor

Copyright (c) 2026 Mike Walter

Nombre del proyecto:

mcp-cpp-project-indexer

🤖 Historia de desarrollo

Este proyecto se formó a través de un flujo de trabajo de desarrollo asistido por IA multimodelo que involucró a ChatGPT, Gemini y DeepSeek. El objetivo no era dejar que un solo modelo inventara ciegamente una herramienta amplia, sino usar múltiples modelos y retroalimentación real de producción para debatir el alcance, las restricciones y la fricción del flujo de trabajo.

Debate de arquitectura y alcance Se usaron ChatGPT y Gemini para debatir el límite de la herramienta: qué debería hacer, qué debería evitar y por qué debería seguir siendo un índice de enrutamiento ligero en lugar de convertirse en un compilador o un reemplazo de clangd.
Implementación incremental El código se implementó incrementalmente con un agente de codificación de IA, probando cada cambio funcional contra proyectos reales con uso intensivo de módulos C++20.
Análisis y revisión de la estructura del flujo de trabajo Se usó DeepSeek como socio dedicado de análisis de flujo de trabajo durante el uso en producción dentro de un código base de 7,000 archivos. Evaluó secuencias de llamadas a herramientas, elecciones de parámetros, tamaño de salida, calidad de clasificación, fricción de navegación e higiene de contexto, y luego retroalimentó cambios concretos para reducir llamadas y mejorar la eficiencia de tokens.
Refinamiento iterativo La retroalimentación de esas sesiones impulsó mejoras enfocadas: salidas compactas, filtros de símbolos/archivos/contenedores, enrutamiento de fragmentos de cambios, recargas de watcher, lecturas alrededor de líneas y reglas de mensaje más estrictas.

El resultado es una herramienta construida con IA para navegación de código asistida por IA, optimizada en torno a un principio estricto: mantener el indexador honesto y pequeño, y dejar que la IA razone solo a partir de rangos de fuente que lea explícitamente.

Pruebas de humo

Después de la integración MCP, prueba:

get_project_summary
Mostrar todos los módulos bajo Example.Core.Direct2D.
¿Qué módulos importan Example.Shell.Browser:Impl?
Encuentra la declaración y definición de ExampleClass::OnEvent.
Lee todas las sobrecargas de GetHandler.
¿Qué archivo define Example.Elements:ElementImpl?
Encuentra la definición de ExampleClass::operator=.
Lista todos los símbolos en Example/Core/Renderer.cpp.
¿Qué módulos importa Example.UI:ToggleSwitch?
Muestra el árbol de módulos para Example.Core (profundidad máxima 3).
Encuentra todos los archivos que coincidan con Example Dialog*.
Lee las primeras 20 líneas de Example/Core/Main.ixx.
Encuentra la declaración de ExampleClass::ExampleClass (constructor).
Encuentra todos los símbolos que coincidan con Paint en Example/Core/Renderer.cpp.
Muestra qué módulos son importados por Example.Shell:Impl.
Obtén el resumen del mapa de módulos.
Encuentra la definición de ExampleClass::OnKeyDown.
Lee el rango de ExampleClass::OnPaint (líneas 150-200).
Encuentra todos los archivos en el módulo Example.UI:Controls.
Muestra el árbol de importaciones para Example.UI:ToggleSwitch.
Encuentra el símbolo ExampleNamespace::ExampleClass::Method.
Lista todos los módulos que importan Example.Core.Service.
Encuentra la declaración de la función plantilla ExampleClass::Create.
Lee el símbolo para ExampleClass::OnNotify.
Encuentra todos los archivos bajo Example/UI/Controls/.
Muestra la información del módulo para Example.Core.Direct2D.Renderer.
Encuentra la definición de ExampleClass::Initialize.
Lista todos los símbolos en Example/Core/Service.cpp que sean funciones.
Encuentra qué módulos son parte de Example.UI.
Lee el código fuente de ExampleClass::HandleInput (líneas 50-120).
Encuentra el archivo que define Example.Core:ModuleImpl.
Muestra todas las importaciones de Example.UI:Controls.Button.
Encuentra la declaración del enum ExampleClass::State.
Lee el símbolo para ExampleClass::GetSize.
Encuentra todos los archivos con extensión .ixx bajo Example/.
Muestra el árbol de módulos para Example.Shell (profundidad máxima 2).
Encuentra la definición de ExampleClass::_UpdateLayout.
Lista todos los símbolos en Example/Core/Utils.cpp.
Encuentra qué módulos importan Example.UI:Controls.
Lee el rango de ExampleClass::Paint (líneas 200-250).
Encuentra la declaración de ExampleClass::~ExampleClass (destructor).
Muestra la información del módulo para Example.Shell.Browser:Impl.
Encuentra todos los símbolos que coincidan con Handler en Example/Core/.
Lee el símbolo para ExampleClass::OnMouseMove.
Encuentra el archivo que define Example.UI:Controls.Button.
Lista todos los módulos importados por Example.Core.Direct2D.
Encuentra la definición de ExampleClass::SetValue.
Muestra el árbol de módulos para Example.UI (profundidad máxima 4).
Encuentra todos los archivos bajo Example/Shell/Browser/.
Lee las primeras 30 líneas de Example/Core/Service.ixx.
Encuentra la declaración de ExampleClass::GetAccessibleImpl.
Lista todos los símbolos en Example/UI/Controls/Button.cpp.
Encuentra qué módulos son importados por Example.Shell.Browser:Impl.
Muestra la información del módulo para Example.Elements:ElementImpl.
Encuentra la definición de ExampleClass::OnPropertyChanged.
Lee el símbolo para ExampleClass::GetState.
Encuentra todos los archivos que coincidan con Service bajo Example/Core/.
Muestra el árbol de módulos para Example.Elements (profundidad máxima 3).
Encuentra la declaración de ExampleClass::Register.
Lista todos los símbolos en Example/Shell/Browser/Impl.cpp.
Encuentra qué módulos importan Example.Core.Direct2D.Renderer.
Lee el rango de ExampleClass::OnInput (líneas 100-150).
Encuentra la definición de ExampleClass::_SelfLayoutDoLayout.
Muestra la información del módulo para Example.UI:Controls.Dialog.
Encuentra todos los símbolos que coincidan con Layout en Example/Core/.
Lee el símbolo para ExampleClass::GetSliderSize.
Encuentra el archivo que define Example.Shell:Impl.
Lista todos los módulos que son parte de Example.Core.
Encuentra la declaración de ExampleClass::DefaultAction.
Lee las primeras 40 líneas de Example/UI/Controls/Dialog.ixx.
Encuentra la definición de ExampleClass::_FireClickEvent.
Muestra el árbol de módulos para Example.Core.Direct2D (profundidad máxima 5).
Encuentra todos los archivos bajo Example/Elements/.
Lee el símbolo para ExampleClass::GetCaptured.
Encuentra qué módulos importan Example.Private.Helper.
Muestra la información del módulo para Example.UI:Controls.Dialog.
Encuentra la declaración de ExampleClass::SetCaptured.
Lista todos los símbolos en Example/Elements/ElementImpl.cpp.
Encuentra la definición de ExampleClass::OnInput.
Lee el rango de ExampleClass::_UpdateLabel (líneas 170-180).
Encuentra todos los archivos que coincidan con Element bajo Example/Elements/.
Muestra el árbol de módulos para Example.Private (profundidad máxima 2).
Encuentra la declaración de ExampleClass::GetPressed.
Lee el símbolo para ExampleClass::SetPressed.
Encuentra qué módulos importan Example.Elements:ElementImpl.
Muestra la información del módulo para Example.Private.Helper.
Encuentra la definición de ExampleClass::OnPropertyChanged.
Lista todos los símbolos en Example/Core/Direct2D/Renderer.cpp.
Encuentra todos los archivos con extensión .cpp bajo Example/UI/.
Lee el símbolo para ExampleClass::GetSliderBorderStrokeWidth.
Encuentra la declaración de ExampleClass::SliderBackgroundColorProp.
Muestra el árbol de módulos para Example (profundidad máxima 1).
Encuentra todos los módulos que comiencen con Example.UI.
Lee el rango de ExampleClass::_SelfLayoutUpdateDesiredSize (líneas 200-220).
Encuentra la definición de ExampleClass::SliderBorderColorProp.
Lista todos los símbolos en Example/Private/Helper.cpp.
Encuentra qué módulos importan Example.UI:Controls.Dialog.
Muestra la información del módulo para Example.Elements:ElementWithTooltip.
Encuentra la declaración de ExampleClass::SliderForegroundColorProp.
Lee el símbolo para ExampleClass::SliderSizeProp.
Encuentra todos los archivos bajo Example/Private/.
Encuentra la definición de ExampleClass::StateProp.
Lista todos los símbolos en Example/Core/Service.cpp.
Encuentra qué módulos son importados por Example.Elements:ElementImpl.
Muestra el árbol de módulos para Example.UI.Controls (profundidad máxima 3).
Encuentra la declaración de ExampleClass::CapturedProp.
Lee el símbolo para ExampleClass::PressedProp.
Encuentra todos los archivos que coincidan con Helper bajo Example/Private/.
Encuentra la definición de ExampleClass::ClassInfoI::GetClassInfoPtr.
Lista todos los símbolos en Example/UI/Controls/Dialog.cpp.
Encuentra qué módulos importan Example.Private.TreeHelper.
Muestra la información del módulo para Example.UI:Controls.Button.
Encuentra la declaración de ExampleClass::ElementWithPromptValueI::ElementWithPromptValueProperties.
Lee el símbolo para ExampleClass::Initialize (sobrecarga con 3 parámetros).
Encuentra todos los archivos bajo Example/Core/Direct2D/.
Encuentra la definición de ExampleClass::_Initialize.
Lista todos los símbolos en Example/Elements/ElementWithTooltip.cpp.
Encuentra qué módulos importan Example.Private.ValueHelper.
Muestra el árbol de módulos para Example.Shell.Browser (profundidad máxima 4).
Encuentra la declaración de ExampleClass::Register.
Lee el símbolo para ExampleClass::ToggleSwitch (constructor).
Encuentra todos los archivos que coincidan con Renderer bajo Example/Core/Direct2D/.

Comportamiento esperado:

el modelo usa herramientas
no lee archivos completos
no confunde espacios de nombres con módulos
llama a read_symbol solo después de la búsqueda de metadatos de símbolos
sigue llamadas de proyecto recursivamente solo cuando sea necesario

Lista de Verificación de Mantenimiento

Después de cambiar el comportamiento de las herramientas, los interruptores de línea de comandos, los mensajes o la documentación, revisa MAINTENANCE_CHECKLIST.md. Cubre los puntos de sincronización habituales: descripciones de herramientas, reglas de mensajes, README, banderas de menú/CLI, compatibilidad de datos de índice, pruebas de humo, suposiciones de relay y preparación de confirmaciones.