mcp-cpp-project-indexer

Indexador de projetos C++ eficiente, com suporte a SQL, projetado para grandes bases de código com baixo consumo de memória.

GitHub
10
Experimente este MCPPatrocinado

Documentação

mcp-cpp-project-indexer

mcp-cpp-project-indexer é um indexador determinístico de faixas de código-fonte C++ para projetos grandes e com muitos módulos, e para navegação de código por IA baseada em MCP.

Não é um compilador, substituto de LSP, mecanismo de refatoração, analisador semântico ou construtor de grafo de chamadas.

Sua função é simples:

Find code. Read code. Do not guess code.

O indexador mapeia símbolos C++, arquivos e módulos C++20 para faixas de código-fonte exatas, para que uma IA possa ler apenas o código de que precisa.

O trabalho do projeto e a orquestração de IA relacionada estão documentados na página inicial do MEF Programming, incluindo a camada de relay/governança em andamento que estamos construindo em torno do uso de ferramentas MCP.

Visão Geral em 30 Segundos

mcp-cpp-project-indexer constrói um índice de roteamento leve sobre uma árvore de código-fonte C++. Os clientes MCP podem então fazer perguntas determinísticas, como:

  • onde está esta função/classe/membro de dados?
  • qual faixa de código-fonte exata deve ser lida?
  • qual módulo importa ou exporta esta partição?
  • qual trecho alterado intersecta qual símbolo indexado ou faixa de dados?

O indexador retorna metadados e faixas de código-fonte originais. Ele não afirma entender o programa. A IA ainda precisa ler o código-fonte retornado e raciocinar a partir dessas evidências.

Fluxo de trabalho mínimo:

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

Isso mantém grandes projetos C++ fora do prompt até que evidências exatas de código-fonte sejam necessárias.

Início Rápido em 5 Minutos

1. Clone este repositório

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

2. Construa um índice para seu projeto C++

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

O índice gerado é gravado em:

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

3. Inicie o servidor MCP

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

Para vários clientes MCP ou um processo compartilhado de longa duração, use 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. Adicione o servidor ao seu cliente MCP

Configuração mínima no 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. Peça o código-fonte exato, não arquivos inteiros

Bom primeiro pedido:

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

Caminho de ferramenta esperado:

find_symbol -> read_symbol -> source-grounded answer

Para melhores resultados, dê à sua IA as regras de prompt_template.md. A versão resumida é:

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

Conteúdo

Estrutura do Repositório

A raiz pública readme.md é a documentação do projeto voltada para humanos. A implementação real em Python fica em 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

Scripts de nível raiz como build_project_index.py, code_index_mcp_server.py, indexer_tui.py e update_project_index.py são wrappers de compatibilidade. Eles mantêm as linhas de comando existentes e as configurações do cliente MCP funcionando enquanto roteiam a execução para o pacote de implementação.

Os READMEs locais de pastas em src/ usam o formato de orientação do indexador de projetos, para que agentes possam descobrir por onde começar sem transformar o README da raiz pública em documentação apenas para máquinas.

🚀 Escala de Produção e Desempenho

Este projeto é usado em bases de código C++ reais, não apenas em exemplos simples. Duas execuções recentes em escala mostram a faixa pretendida:

ProjetoArquivosLinhas de código-fonteTokens do lexerSímbolosDeclarações de dadosMódulos C++20Build completo
Projeto comercial anônimo C++207.046979.6584.682.88297.92436.5513.75419,5s
Checkout do Chromium137.62230.792.607137.365.3992.327.255818.1880~24m 32s

Esses números dependem da máquina. A execução do Chromium usou --jobs 60 em uma estação de trabalho com muitos núcleos, com um sistema Intel Xeon Silver 4316, 128 GB de RAM e armazenamento NVMe SSD empresarial. É um teste de estresse público útil porque exercita uma base de código C++ clássica muito grande baseada em includes, enquanto o projeto comercial anônimo exercita metadados densos de módulos e partições C++20. A execução do Chromium também validou o indexador de dados/membros em escala: após corrigir o tratamento de profundidade de >> de templates aninhados, o teste de estresse público revelou 46.529 declarações de dados adicionais e 66.866 aliases de nomes de dados adicionais.

O índice de consulta baseado em SQLite mantém a inicialização do servidor prática mesmo na escala do Chromium: o servidor MCP pode iniciar imediatamente e permanecer em cerca de 200 MB de RAM após a inicialização, em vez de carregar milhões de entradas de símbolos/dados/nomes em objetos Python.

Ele é projetado para fluxos de trabalho que combinam o aplicativo de desktop Codex ou outros clientes MCP com navegação no Visual Studio e, quando necessário, evidências binárias/de descompilador de ferramentas como IDA Pro.

Em um fluxo de trabalho medido, o roteamento exato de faixas de código-fonte reduziu a leitura de texto-fonte de aproximadamente 2.000 linhas para 283 linhas, uma redução de 86%.

Centro de Controle TUI

Para uso diário, o indexador inclui um TUI opcional com suporte a mouse. Ele transforma o índice do projeto em um pequeno centro de controle local:

  • inicie o servidor MCP HTTP e o watcher a partir de um único lugar
  • execute builds completos, atualizações incrementais, atualizações rápidas e reconstruções de mapa de módulos
  • acompanhe estatísticas ao vivo do servidor, watcher, lock, processo, token e índice
  • inspecione logs de build/atualização sem trocar de ferramentas
  • alterne seções de arquivos de diagnóstico para obter evidências mais profundas do parser quando necessário

TUI control center

Instale a dependência opcional de interface e inicie o centro de controle com caminhos explícitos de projeto/í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

A interface é opcional; o indexador principal permanece leve em dependências e ainda pode ser totalmente controlado por scripts ou clientes MCP. Para configuração e atalhos de teclado, consulte Centro de Controle.

💡 Por que Esta Ferramenta?

Projetos C++ grandes são caros de alimentar em um modelo de IA quando arquivos inteiros são carregados apenas para encontrar uma função, classe, importação ou declaração. Os módulos C++20 tornam isso mais difícil: muitas ferramentas no estilo IDE/LSP ainda têm dificuldade com grandes grafos de módulos, partições, cabeçalhos de SDK gerados e configuração específica de build.

Este indexador resolve um problema mais restrito, porém muito prático: ele dá à IA um pequeno mapa de roteamento determinístico. A IA pode localizar primeiro o símbolo, módulo, arquivo ou trecho alterado relevante e, em seguida, ler apenas as linhas exatas do código-fonte original necessárias para a tarefa.

Exemplo de um fluxo de trabalho real de busca de bugs:

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

📊 Antes / Depois

Navegação de código por IA padrãoCom mcp-cpp-project-indexer
❌ A IA lê arquivos inteiros para encontrar um símbolo✅ A IA pede metadados compactos e depois lê a faixa exata do código-fonte
❌ O contexto se enche de declarações e implementações não relacionadas✅ O contexto permanece focado nas linhas que importam
❌ Consumidores/importações de módulos C++20 são difíceis de rotear✅ Importações de módulos, re-exportações, partições e consumidores são expostos diretamente
❌ Revisões começam escaneando arquivos alterados manualmente✅ Trechos de alteração são mapeados para faixas de símbolos/dados indexados
❌ Ferramentas podem implicar certeza semântica que não possuem✅ O indexador retorna apenas fatos de roteamento e faixas de código-fonte originais

O resultado é menor uso de tokens, menor latência, menos desvio de contexto e análise mais fundamentada no código-fonte.

Como Funciona

O indexador evita deliberadamente fingir ser um compilador.

  1. Varredura rápida de tokens/estrutura Os arquivos de código-fonte são escaneados com um lexer Python leve e um parser estrutural. A saída é um sumário determinístico: arquivos, símbolos, declarações de dados, diretivas lexicais #include, faixas de código-fonte, diagnósticos e fatos de módulos.
  2. Mapa de módulos C++20 Interfaces de módulos, partições, importações, exportações-importações e consumidores são indexados para que a IA possa navegar por código com muitos módulos sem pedir a um LSP que resolva todo o build.
  3. Atualização incremental e watcher O atualizador rastreia hashes de conteúdo e reescreve apenas os dados de índice alterados quando possível. O watcher opcional pode manter o cache do servidor MCP atualizado enquanto você trabalha no Visual Studio.
  4. Ferramentas MCP com controles de saída compactos As ferramentas expõem primeiro metadados exatos de roteamento. A IA escala apenas quando necessário: consulta compacta de símbolos, visão geral de arquivo/módulo/alteração, read_symbol ou read_range exatos, e depois leituras recursivas mais profundas do código-fonte.

O indexador é apenas o sumário. A IA realiza exploração recursiva e revisão de código a partir das linhas originais do código-fonte que ela lê explicitamente.

Fluxo de Trabalho Principal

Em vez disso:

Read Renderer.cpp completely: ~2000 lines

use isto:

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

Para revisão de código alterado:

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

O que ele faz

O scanner extrai fatos de roteamento de arquivos de código-fonte C++:

  • arquivos e IDs de arquivo estáveis
  • módulos e partições C++20
  • diretivas lexicais #include
  • importações e exportações
  • namespaces
  • classes / structs / enums
  • funções / métodos
  • construtores / destrutores / operadores
  • declarações e definições inline
  • startLine / endLine exatos
  • diagnósticos para arquivos estruturalmente suspeitos

Ele é baseado em stream/tokens, não em regex.

O que ele não faz

Intencionalmente não incluído:

  • nenhum grafo de chamadas de programa inteiro preciso como compilador
  • nenhum find_references
  • nenhuma resolução de tipos
  • nenhuma resolução de instanciação de templates
  • nenhuma resolução de sobrecarga precisa como compilador
  • nenhuma expansão de macros
  • nenhum resumo semântico
  • nenhuma análise de bugs
  • nenhum analyze_symbol(symbolId)

A IA deve ler faixas de código-fonte e raciocinar a partir do código original.

Layout de Saída

Diretório de saída padrão:

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

Arquivos gerados:

.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

Os índices globais de roteamento de símbolos e dados são armazenados em index.sqlite. Os índices JSON por arquivo permanecem como fonte da verdade para faixas exatas de código-fonte e reconstruções incrementais.

Exportação 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

Os campos de índice de arquivo de diagnóstico do scanner são emitidos apenas com --emit-diagnostics ou --emit-diagnostic-file-indexes:

scopeIntervals
structuralEvents
functionBodyRanges

Indexar um arquivo

De qualquer diretório:

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

Com dados de diagnóstico do scanner:

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

Se --project-root for omitido, o diretório pai do arquivo é usado.

Construir um índice de projeto

Uso recomendado a partir da raiz do projeto C++:

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

Isso grava em:

<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

Exemplo de resumo:

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 é a contagem de tokens do lexer do indexador sobre o código-fonte indexado após o apagamento de comentários. É uma métrica de tamanho do projeto, não uma contagem de tokens de cobrança de LLM.

Quando a raiz do projeto está dentro de uma árvore de trabalho Git e git está disponível, a descoberta de arquivos respeita as regras de ignore do Git filtrando candidatos por meio de git check-ignore --stdin. Isso exclui caminhos correspondentes a .gitignore, .git/info/exclude ou ao arquivo de ignore global do usuário. Projetos não-Git, ou sistemas sem Git, usam a lista integrada de diretórios excluídos. Diretórios com ponto, como .git, .vs, .cache, .idea ou .folder, são excluídos por padrão.

Configuração de descoberta de projeto

Para projetos grandes com layouts de código-fonte mistos, coloque indexer_config.json na raiz do projeto ou em qualquer subdiretório. Os arquivos de configuração são aplicados durante a varredura da árvore: a configuração raiz torna-se a base, e as configurações de subdiretórios podem substituí-la ou estendê-la para aquela subárvore.

Exemplo:

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

Campos suportados:

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

extensions e excludeDirs substituem os valores herdados para aquela subárvore. Os campos add* e remove* modificam os valores herdados. A descoberta de cabeçalhos sem extensão é conservadora e opt-in; ela aceita apenas arquivos sem extensão cujas primeiras linhas parecem cabeçalhos C/C++. useGitIgnore:false desativa a passagem final de git check-ignore --stdin para repositórios muito grandes, onde a filtragem de ignore do Git é mais cara do que uma configuração explícita do indexador.

Atualização incremental

Após um build completo do índice, arquivos alterados podem ser detectados e re-indexados incrementalmente.

Execução de teste (dry-run):

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

Atualização rápida para arquivos já indexados:

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

Atualização no estilo watcher para um arquivo alterado conhecido:

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 ignora a descoberta completa de novos arquivos. Isso é ideal para loops de salvar/observar. --changed-file pode ser repetido e permite que um watcher evite fazer hash de arquivos inalterados.

As gravações de índice são protegidas por um arquivo exclusivo .update.lock na raiz do índice. Isso impede que builds completos, atualizações incrementais e reconstruções de mapa de módulos gravem os mesmos arquivos de índice ao mesmo tempo.

Observar o índice do projeto

O watcher autônomo monitora arquivos de origem, faz debounce de alterações, executa o atualizador incremental e, opcionalmente, reconstrói module_map.json.

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

Para modificações puras de arquivo, o watcher chama:

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

Isso calcula o hash apenas do arquivo candidato alterado. Se o hash de conteúdo não mudou, o watcher pula o trabalho de reconstrução do mapa de módulos e recarga do cache MCP.

Apenas um watcher deve possuir uma raiz de índice. O watcher usa .watcher.lock e sai se outro watcher já estiver ativo para o mesmo índice.

Diagnósticos não são fatais. Eles indicam avisos estruturais de melhor esforço para arquivos individuais.

Imprimir resumo 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 o mapa de módulos

Após construir o índice do projeto:

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

Saída:

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

O mapa de módulos contém:

  • nomes de módulos
  • módulos primários e partições
  • arquivos que definem cada módulo
  • imports
  • importedBy
  • uma árvore de módulos
  • importações não resolvidas

É apenas metadados. Não analisa o comportamento da implementação.

Central de Controle

O indexador principal não tem dependências de runtime de terceiros. Para a operação do dia a dia, existem duas superfícies de controle de terminal opcionais:

  • indexer_tui.py: uma UI Textual polida com suporte a mouse
  • indexer_control.py: um fallback de linha de comando sem dependências

Instale a dependência opcional da UI:

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

Inicie a UI 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

A UI Textual fornece uma interface de terminal real com botões, suporte a mouse, cartões de status, polling HTTP ao vivo de /status, logs de atividade e controle de processo para ações de build/update/watch/server.

A entrada do mouse depende do emulador de terminal. No Windows, use o Windows Terminal ou outro terminal moderno que encaminhe eventos de mouse para aplicativos de terminal. Atalhos de teclado funcionam em qualquer lugar onde o Textual possa ser executado.

As configurações da UI são salvas em <indexer-root>/.ui-settings/ ao sair e quando seções de arquivo de diagnóstico são alternadas. Cada arquivo de configurações é identificado pelo nome do projeto mais um hash de caminho, para que as preferências da UI não sejam gravadas na raiz do projeto ou no diretório de índice gerado. As preferências armazenadas incluem a URL HTTP, valor de jobs, alternância de seção de diagnóstico, configurações de inicialização da API de gerenciamento, tema Textual ativo e caminhos de projeto/índice.

O arquivo de configurações também pode ser editado diretamente para configurações externas de Relay UI:

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

A UI Textual tem uma ação separada Start HTTP + management. Ela inicia o servidor HTTP MCP com watcher e --enable-management-api, usando o managementToken salvo quando configurado. Essa ação é intencionalmente local à TUI e não é exposta como comando de gerenciamento na API HTTP.

Central de controle de fallback:

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 comuns:

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

Quando o servidor HTTP está em execução, ambas as centrais de controle fazem polling de /status para estatísticas ao vivo do servidor, watcher, lock e índice. Se o servidor HTTP não estiver acessível, elas recorrem à leitura de manifest.json e module_map.json do disco.

Despejar a árvore de módulos

Árvore de texto:

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

Escrever em arquivo:

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

Árvore de importação para um 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 o servidor MCP

O servidor lê um índice existente. Ele não reconstrói o índice.

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

O servidor é somente leitura e expõe ferramentas de localização/leitura via MCP stdio.

Para permitir que o servidor mantenha seu cache em memória atualizado durante a edição, inicie-o com o 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

O watcher do servidor escreve todo o progresso em stderr para que o stdout permaneça como JSON-RPC MCP válido. Após uma mudança real no índice, ele recarrega o cache do servidor automaticamente. Se um salvamento apenas alterar o mtime e o hash de conteúdo não mudar, ele pula a reconstrução do mapa de módulos e a recarga do cache.

Se outro watcher já possuir a mesma raiz de índice, o servidor MCP continua somente leitura e não inicia seu próprio watcher. Isso evita processos de escrita concorrentes quando vários clientes MCP iniciam instâncias separadas do servidor stdio.

Transporte HTTP compartilhado

Para configurações em que vários clientes MCP iniciariam processos separados de servidor stdio, o servidor também pode expor a mesma superfície MCP JSON-RPC via 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

O endpoint HTTP é:

POST http://127.0.0.1:8765/mcp

Endpoints de status:

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

Isso mantém um processo de servidor de longa duração, um cache de índice em memória e um watcher para a raiz do índice. Clientes que suportam apenas stdio ainda precisam de uma configuração stdio ou de uma pequena ponte no lado do cliente para esse endpoint HTTP.

API de gerenciamento HTTP

UIs de controle externas podem opcionalmente habilitar uma pequena superfície de gerenciamento no mesmo servidor HTTP. Ela fica desabilitada por padrão porque pode iniciar processos 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 retorna o contrato de intenção/categoria/ferramenta legível por máquina usado por camadas externas de relay/governança. O alias legado /management/capabilities também é aceito.

/management/status inclui um objeto dashboard moldado para centrais de controle externas. Ele contém os mesmos campos de alto valor exibidos pela 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

Valores numéricos brutos são incluídos ao lado dos campos formatados *Text onde o servidor puder fornecê-los. dashboard.mode.theme é reservado para UIs externas; o próprio servidor HTTP não possui um tema visual.

Os objetos genéricos server.process e management.runner.process também expõem campos de CPU normalizados quando disponíveis:

cpuUserSeconds
cpuSystemSeconds
cpuTimeSeconds
cpuTimeText
cpuCoresAverage
cpuPercentMachine
cpuText

Quando configurado, o token protege a superfície HTTP MCP/status compartilhada, bem como os endpoints de gerenciamento. Passe-o como:

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

Comandos são 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 retorna a saída do comando de gerenciamento. /management/log/stream é o fluxo SSE correspondente. A saída do subprocesso de build e update é lida de forma assíncrona, para que uma UI possa continuar consultando o status e transmitindo logs enquanto grandes projetos estão sendo indexados.

/management/server-log retorna eventos recentes de log de tráfego HTTP/MCP, incluindo contagens de bytes de requisição/resposta e o detalhe do método MCP quando disponível. /management/server-log/stream é o fluxo SSE correspondente para atividade de requisição ao vivo. Eventos MCP tools/call também incluem um objeto estruturado compacto mcp com toolName, argumentKeys e arguments limitado para detalhes expansíveis de UI. Após a resposta JSON-RPC ser conhecida, o evento inclui mcp.outcome (success ou error) e mcp.errorCount para que UIs de controle possam colorir chamadas de ferramenta com falha sem analisar o payload da resposta. Requisições HTTP keep-alive redefinem metadados de log locais à requisição, para que a consulta de status não possa herdar um rótulo de chamada MCP anterior.

Perfis de segurança HTTP

O desenvolvimento local pode continuar usando HTTP de loopback:

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

Para implantações de cliente ou LAN, não exponha o servidor como HTTP simples. O servidor se recusa a iniciar em um endereço de bind não-loopback, a menos que TLS e autenticação estejam habilitados.

Perfis de segurança:

PerfilUso pretendidoRequisitos
local-devdesenvolvimento na mesma máquinaHTTP de loopback permitido
trusted-lanRelay e indexador em hosts confiáveis diferentesTLS mais token ou mTLS
productionimplantação de clienteTLS mais token ou mTLS

Exemplo de TLS autenticado por 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

Exemplo 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 testes locais criptografados sem um certificado de cliente, um certificado autoassinado pode ser gerado no primeiro início:

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

Os arquivos gerados são armazenados abaixo:

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

O TLS autoassinado criptografa o tráfego, mas não é automaticamente confiável por navegadores ou clientes remotos. Implantações de cliente devem usar uma CA de cliente, certificado público ou material de confiança mTLS explícito.

Configuração MCP do LM Studio

Exemplo 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 um servidor HTTP compartilhado sem autenticação por token:

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

Se o servidor HTTP foi iniciado com --management-token <token>, o LM Studio deve enviar esse token como cabeçalho:

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

O servidor também aceita X-API-Key:

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

Após reconstruir o índice ou o mapa de módulos, reinicie o servidor MCP / LM Studio.

Configuração do Codex

Para o Codex, configure este repositório como um servidor MCP stdio e coloque as regras do agente onde o Codex as carregará como instruções do projeto.

Exemplo 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",
]

As regras de prompt de prompt_template.md devem ser copiadas para um arquivo AGENTS.md na raiz do projeto que o Codex abre, por exemplo:

<project-root>\AGENTS.md

O Codex lê AGENTS.md como instruções de repositório/projeto para a árvore de trabalho atual. Se você costuma iniciar o Codex a partir de um workspace pai em vez da raiz do projeto C++, coloque o arquivo nessa raiz do workspace ou abra o Codex diretamente na raiz do projeto C++ para que as instruções estejam no escopo.

Mantenha a configuração do servidor MCP e as regras de prompt separadas:

  • A configuração MCP inicia o servidor de ferramentas e o aponta para o índice gerado.
  • AGENTS.md diz ao agente como usar as ferramentas com segurança e de forma compacta.

Após alterar a configuração do servidor MCP ou reconstruir o índice, reinicie o servidor MCP / sessão do Codex para que o esquema de ferramentas atualizado fique visível.

Configuração do Claude

O Claude Code e o Claude Desktop usam MCP de maneiras ligeiramente diferentes, então mantenha a configuração dividida por cliente.

Claude Code

Para o Claude Code, coloque a configuração do servidor MCP em um arquivo .mcp.json com escopo de projeto na raiz do projeto, se a configuração deve viajar com o repositório:

{
  "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": {}
    }
  }
}

Configuração 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 as regras de prompt_template.md para o arquivo de memória do projeto do Claude Code:

<project-root>\CLAUDE.md

O Claude Code também suporta .claude/CLAUDE.md; use esse caminho se preferir manter arquivos específicos do Claude sob .claude/. O importante é que o arquivo esteja na raiz do projeto que o Claude Code abre, caso contrário, as regras de uso de ferramentas podem não ser carregadas.

Claude Desktop

O Claude Desktop usa seu arquivo de configuração MCP do aplicativo. No Windows, geralmente é:

%APPDATA%\Claude\claude_desktop_config.json

Adicione o servidor sob 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": {}
    }
  }
}

O Claude Desktop não lê automaticamente arquivos de instrução do repositório como CLAUDE.md para conversas arbitrárias. Cole as regras relevantes de prompt_template.md nas instruções de projeto/conversa que você usa com o Claude Desktop, ou use o Claude Code quando precisar de instruções persistentes com escopo de repositório.

Após alterar .mcp.json, claude_desktop_config.json ou reconstruir o índice, reinicie o cliente Claude para que o esquema de ferramentas atualizado fique visível.

Possíveis configurações de fluxo de trabalho

Encontrando bugs com base no código-fonte

Um fluxo de trabalho prático de revisão é usar mcp-cpp-project-indexer como camada principal de navegação e deixar a IA raciocinar apenas a partir de faixas exatas de código-fonte que ela leu.

Fluxo 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

Isso mantém o contexto do modelo limpo. O indexador cuida do roteamento e da redução de tokens; a IA realiza a análise a partir das linhas originais do código-fonte; o Visual Studio é usado como entrega ao editor voltado ao desenvolvedor.

Prioridade de ferramentas com Visual Studio MCP

Em projetos com muitos módulos C++20, ferramentas no estilo Visual Studio/IntelliSense/clangd podem falhar ao resolver símbolos de módulos de forma confiável o suficiente para a navegação por IA.

Divisão de papéis 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.

Regra 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.

Evidência de código-fonte mais binário para APIs não documentadas

Para código que interage com componentes Windows não documentados, a evidência do código-fonte pode não ser suficiente. Uma configuração útil é manter a DLL relevante carregada no IDAPro e deixar a IA inspecionar código descompilado/desmontado apenas quando a evidência em nível de código-fonte deixar o comportamento pouco claro.

Exemplo de cenário:

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

Isso mantém o trabalho de engenharia reversa direcionado. A IA não navega pelo binário às cegas; ela entra no IDAPro com uma pergunta baseada no código-fonte. Isso reduz contexto irrelevante, diminui o uso de tokens e ajuda o modelo a manter a cadeia de raciocínio fonte/binário intacta.

Por que essa configuração funciona

A parte cara da revisão de código por IA muitas vezes não é o raciocínio; é localizar a pequena quantidade de código-fonte que realmente importa. O indexador reduz o problema de navegação a metadados compactos e intervalos exatos de código-fonte. Outras ferramentas podem então permanecer focadas no que fazem bem: interação com IDE, estado de build ou fatos binários.

Referência de linha de comando

build_file_index.py

Constrói um JSON de índice por arquivo.

--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

Constrói o índice completo do projeto.

--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

Atualiza incrementalmente um índice de projeto 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

Monitora arquivos de código-fonte e executa atualizações incrementais após as alterações se estabilizarem.

--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

Constrói metadados de relacionamento de módulos a partir do índice do projeto.

--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

Despeja visualizações legíveis de árvore de módulos/importações.

--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

Executa o 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

Central de controle de terminal para fluxos de trabalho de build/update/watch/server.

--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

Interface de terminal Textual opcional com suporte a mouse e painéis de status ao vivo. Requer 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

Menu interativo legado e wrapper de comando não interativo. Prefira indexer_control.py para operação 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 suportados 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

Visão geral das ferramentas

Resumo do projeto

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

O servidor expõe um índice stateFingerprint: uma impressão digital barata no lado do servidor sobre os artefatos de índice atuais (manifest.json, index.sqlite, arquivos de módulo/diagnóstico/atualização). Ela muda quando o estado do índice carregado muda, para que camadas de relay/orquestrador possam marcar evidências de ferramentas mais antigas como obsoletas após um rebuild, atualização ou recarga de cache.

Cada resultado de ferramenta MCP carrega a impressão digital no resultado _meta:

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

O mesmo valor também é exposto por get_project_summary.stateFingerprint e pelo endpoint de status HTTP sob index.stateFingerprint.

Para reutilização fina de evidências, prefira as ferramentas de impressão digital. A impressão digital global do índice é apenas um sinal de alerta. Impressões digitais de arquivo, símbolo e dados permitem que um relay valide fatos ativos sem descartar todo o cache de evidências após cada atualização:

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

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

validate_fingerprints é o ponto de entrada em lote para camadas de relay/orquestrador. Ele aceita até 500 itens de arquivo/símbolo/dados e retorna apenas metadados compactos de validade e impressão digital. Essas chamadas não leem nem retornam texto de código-fonte.

Ferramentas de rastreamento de alterações

Essas ferramentas são expostas apenas quando git.exe está disponível e project-root está dentro de uma worktree. Elas são somente leitura e não expõem um executor de comandos genérico.

list_changed_files
list_recent_revisions
get_revision_summary
get_file_change_hunks
resolve_hunk_to_indexed_range

Use-as para alterações atuais, revisões recentes, inspeção de hunks, revisão de arquivos modificados e sugestões de mensagens de commit.

Use resolve_hunk_to_indexed_range(file, line|startLine/endLine) quando os metadados de hunk fornecerem um intervalo de novas linhas alteradas e o relay precisar de um alvo de roteamento válido de symbolId / dataId antes de ler o código-fonte. Ele retorna intervalos indexados de símbolo/dados que contêm, se sobrepõem ou estão mais próximos do intervalo alterado. Isso é somente metadados e não interpreta o diff nem afirma correção.

Quando o usuário diz que corrigiu, alterou, salvou, atualizou, fez commit ou quer que o trabalho atual seja revisado, o agente deve verificar essas ferramentas antes da navegação normal de código-fonte. Em configurações de watcher, o índice pode já estar atualizado, e as ferramentas de alteração fornecem o caminho mais barato para os intervalos de arquivo/símbolo afetados.

get_file_change_hunks pode incluir indexedRanges, que são interseções entre intervalos de linhas de hunks alterados e intervalos indexados de símbolo/dados. Estes são apenas dicas de roteamento. Leia o código-fonte relevante com read_symbol ou read_range antes de fazer afirmações de implementação.

Para roteamento de revisão de baixo consumo de tokens, chame get_file_change_hunks com includeIndexedRangeSummary:true, includeIndexedRanges:false e includeSource:false. O summaryByIndexedRange retornado agrupa hunks alterados por intervalo afetado de símbolo/dados indexado sem repetir cada interseção por hunk.

Após selecionar um intervalo afetado, passe symbolId ou dataId de volta para get_file_change_hunks para retornar apenas hunks que intersectam aquele intervalo de símbolo/dados. Isso ainda é filtragem por intervalo de linhas, não análise semântica.

Ferramentas de símbolo e código-fonte

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 mapeia um arquivo/linha de diagnósticos, hunks, saída de build, Visual Studio ou notas do IDA para intervalos contidos ou mais próximos de símbolo/dados indexados. É somente metadados; leia o intervalo de código-fonte selecionado antes de fazer afirmações de comportamento.

read_symbol aceita startOffset / endOffset opcionais ou startLine / endLine absolutos para ler apenas uma fatia de um corpo de símbolo grande.

read_range aceita startLine / endLine explícitos ou uma forma compacta de linha ao redor com line, beforeLines e afterLines. A forma de linha ao redor é destinada a diagnósticos, hunks, correspondências de busca, transferência do Visual Studio e notas do IDA onde o chamador tem uma linha de código-fonte relevante.

find_symbol pesquisa apenas metadados de símbolo:

  • shortName exato
  • qualifiedName / aliases exatos
  • substring de fallback sobre shortName, qualifiedName e signature

Controles de roteamento opcionais:

  • compact: retorna apenas campos compactos de roteamento
  • responseFormat: JSON pretty ou minified para respostas de metadados
  • omitNulls: omite campos nulos de respostas de metadados
  • omitEmpty: omite arrays/objetos vazios de respostas de metadados
  • symbolTypes: filtra por tipo de símbolo indexado, ex.: method, function, type_alias
  • container: filtra para símbolos contidos por um nome ou sufixo de classe/struct/namespace
  • file: filtra para um fileId ou caminho relativo ao projeto
  • filePattern: filtra por glob de caminho relativo ao projeto
  • exactOnly: retorna apenas correspondências exatas de nome curto ou nome qualificado, incluindo correspondências exatas sem diferenciar maiúsculas/minúsculas
  • hideNamespaces: oculta símbolos de reabertura de namespace dos resultados de navegação

Use container apenas para o contêiner léxico/índice real onde o símbolo é declarado. Não use um contêiner de classe para funções auxiliares livres apenas porque essa classe as chama. Se uma consulta find_symbol com container não retornar resultado, tente novamente o nome exato do símbolo sem container antes de recorrer a search_source.

Cada item retornado inclui matchKind para descrever por que correspondeu. Correspondências fortes como exact_qualified_name e exact_short_name geralmente são as melhores para roteamento. Correspondências de substring, assinatura e metadados são candidatos mais fracos que devem ser desambiguados antes de ler o código-fonte.

Não combine file e filePattern. Esses controles são filtros de localização; eles não leem código-fonte e não resolvem sobrecargas semanticamente.

Opções de empacotamento de resposta são expostas apenas em ferramentas de metadados/roteamento. Ferramentas de código-fonte mantêm sua saída de código-fonte numerada por linha inalterada.

list_file_symbols também pode retornar listas menores de candidatos de símbolo em nível de arquivo quando o arquivo já é conhecido:

  • compact: retorna apenas campos compactos de roteamento
  • symbolTypes: filtra por tipo de símbolo indexado
  • container: filtra para símbolos contidos por um nome ou sufixo de classe/struct/namespace
  • hideNamespaces: oculta símbolos de reabertura de namespace
  • limit: limita o tamanho do resultado

Isso é apenas um filtro de localização. Não resolve herança, sobrecargas ou semântica de tipos.

Quando um arquivo já é conhecido e tanto membros de classe quanto funções auxiliares locais podem importar, prefira list_file_symbols(file, compact:true, hideNamespaces:true) antes de adivinhar um filtro container. Auxiliares de namespace anônimo ainda são funções indexadas normais; elas podem ter o namespace nomeado ao redor como contêiner, não a classe que as chama.

search_source aceita symbolId para pesquisar apenas dentro de um intervalo de símbolo indexado. Esta é a maneira preferida de fazer uma verificação léxica dentro de uma função ou método já localizado. Ainda é busca léxica de código-fonte, não resolução semântica de chamadas/referências.

Argumento canônico:

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

name pode ser aceito como um alias de compatibilidade, mas query é canônico.

Ferramentas de arquivo

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

Glob apenas sobre caminhos relativos ao projeto. Isso não é grep de código-fonte.

list_file_includes retorna as diretivas léxicas #include para um arquivo. É destinado a codebases C++ clássicos baseados em include, como Chromium:

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

Metadados de include são apenas evidência de roteamento. O indexador registra a linha de código-fonte, o texto alvo, o tipo de include (quote, angle ou macro) e a resolução relativa ao projeto de melhor esforço quando o arquivo incluído é diretamente visível. Ele não avalia #if / #ifdef, diretórios de include do compilador, cabeçalhos gerados ou expansão de macros.

get_file_structure retorna um sumário somente de metadados para um arquivo. Para arquivos grandes, prefira includeOutline:false primeiro. Use includeIncludes:true quando metadados de include forem necessários. Use symbolTypes, dataKinds, hideNamespaces, outlineLimit e compactOutline:true para manter as respostas pequenas. Após identificar um item de sumário relevante, leia o código-fonte com read_symbol ou read_range antes de fazer afirmações de implementação.

Quando os índices de arquivo foram construídos com --emit-diagnostic-file-indexes, get_file_structure também pode incluir seções opcionais de diagnóstico de parser/indexador:

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

Use isso apenas para investigar diagnósticos de parser, símbolos ausentes, intervalos de código-fonte suspeitos ou detecção inesperada de escopo/corpo de função. A saída de diagnóstico do indexador é evidência de scanner, não comportamento de implementação.

A formulação do prompt importa aqui. A frase "informações de depuração" é ampla demais para muitos agentes de IA e pode ser confundida com código de build de depuração C++ como DEBUG, _DEBUG, #ifdef DEBUG, depuração do Visual Studio ou ramos de logging. Para dados de scanner do indexador, peça diagnósticos de indexador/parser explicitamente.

Ferramentas de orientação

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

Se um projeto contém arquivos README.md / readme.md em nível de pasta com o bloco de orientação padrão, ou arquivos Markdown com topology no nome do arquivo, o indexador os registra como metadados de orientação opcionais. Isso dá a um agente de IA um mapa de projeto barato antes de ler o código-fonte de implementação. READMEs de pasta usam kind: "folder_orientation"; documentos de topologia usam kind: "topology".

Essas ferramentas são expostas dinamicamente. Se o índice carregado não tem nós de orientação/topologia, tools/list e os metadados de capacidade de gerenciamento omitem as ferramentas de orientação.

A camada de orientação extrai campos estruturados apenas dos cabeçalhos de README de orientação do indexador de projeto vinculado:

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

Cabeçalhos legados como Responsibilities, Non-responsibilities, Use when, Current layout ou Responsibility Boundaries permanecem apenas texto Markdown comum. Eles não preenchem campos estruturados de orientação. Entradas ## Map são analisadas de blocos text cercados com pelo menos dois espaços entre nome da entrada e descrição; entradas resolvidas incluem targetRootRelativePath e pathStatus.

search_orientation usa busca de roteamento BM25 e retorna schema: "cpp.project_orientation.search.v2.1", algorithm: "bm25", diagnósticos de termos de consulta, pontuações, campos de correspondência e termos anti-correspondência. Resultados são apenas dicas de roteamento.

Use-a para perguntas de arquitetura e navegação:

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

Então leia o nó de orientação selecionado:

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

Metadados de orientação não são evidência de implementação. Eles respondem:

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

Eles não respondem o que uma função faz, se o código está correto ou se um comportamento de runtime é garantido. Para essas afirmações, localize e leia o código-fonte com find_symbol, list_file_symbols, read_symbol ou read_range.

Bons prompts:

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.

Evite prompts ambíguos como:

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

O fluxo de trabalho pretendido é:

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

Exemplos:

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

Ferramentas 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)

Use a sintaxe de módulos C++20:

Example.Module:Partition
uiframework.Elements:ElementImpl

Não passe sintaxe de namespaces C++ para ferramentas de módulos:

Example::Namespace
UIFramework::Elements

Para namespaces/classes/funções, use find_symbol ou find_symbols_glob.

A direção é importante:

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)

Não responda perguntas de importação reversa pesquisando primeiro o texto-fonte. O mapa de módulos já armazena metadados importedBy. Use leituras de fonte somente quando o chamador pedir para inspecionar a linha de importação real ou quando os metadados parecerem suspeitos.

As ferramentas de metadados de módulos aceitam compact:true quando útil:

  • find_module / list_module_files: campos compactos de roteamento de módulo/arquivo
  • get_module_info: metadados compactos de arquivos, importações e importados-por
  • list_module_imports: registros compactos de importações de saída
  • list_module_imported_by: registros compactos de módulos importadores

Ferramentas de dados/membros

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

Use find_data para campos, globais, constantes de namespace, valores de enum, templates de variáveis e conceitos. Use list_type_members quando o tipo ou namespace contêiner já for conhecido. Ambas as ferramentas são somente metadados e aceitam compact:true para saída de roteamento menor.

Use resolve_code_entity quando um intervalo de fonte contém um identificador e a IA precisa decidir se é provavelmente uma declaração de campo/dado, símbolo chamável, símbolo de tipo ou candidato ambíguo antes de escolher a próxima ferramenta de leitura. Ela aceita contexto opcional de arquivo, linha e contêiner e retorna candidatos de metadados classificados, além de uma próxima ferramenta recomendada, como read_data ou read_symbol.

resolve_code_entity ainda é apenas orientação. Ela não realiza busca de nomes do compilador, resolução de sobrecarga, expansão de macros, resolução de tipos C++ ou resolução semântica de referências. Afirmações no nível da fonte ainda exigem read_data, read_symbol ou read_range.

typeText é o texto-fonte original para o tipo da declaração. Não é um tipo resolvido pelo compilador. Trate-o como uma dica para busca adicional de símbolo/fonte, não como prova de identidade semântica de tipo.

Ferramentas de grafo de funções

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

Use get_function_body_graph após localizar um símbolo chamável quando a IA precisar de arestas diretas de estrutura de fonte do corpo dessa função: candidatos de chamadas locais ao projeto, chamadas não resolvidas/externas, acessos a dados/membros e marcadores de fluxo de controle. Ela é sob demanda e ciente de cache; não altera o caminho normal de construção do índice.

Modos úteis:

  • compute_if_missing: reutilizar um grafo em cache compatível ou calculá-lo.
  • cache_only: retornar apenas dados de grafo em cache compatíveis.
  • refresh: recalcular o grafo para esse símbolo e substituir as arestas persistidas.

As ferramentas de xref e vizinhança leem apenas arestas de grafo persistidas:

  • get_call_xrefs_from: arestas de chamadas armazenadas de saída de uma função.
  • get_call_xrefs_to: arestas de chamadas armazenadas de entrada para uma função.
  • get_symbol_neighborhood: vizinhança compacta de alvo/chamador/callee.

Calcule ou atualize get_function_body_graph para chamadores relevantes antes de confiar na completude do xref. A saída do grafo de funções é apenas evidência estrutural de navegação: claimStrength=source_structure_allowed e behaviorClaimsAllowed=false. Não é análise de comportamento, semântica de API externa, prova de despacho dinâmico ou resolução de sobrecarga precisa do compilador.

Mais detalhes estão em Ferramentas MCP de Grafo de Funções.

O modelo deve seguir estas regras:

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 exposição de ferramentas

Conjuntos grandes de ferramentas MCP funcionam melhor quando o cliente mantém as ferramentas ativas relevantes para a tarefa atual. Se todas as ferramentas forem expostas para cada solicitação, alguns modelos podem explorar demais, repetir consultas semelhantes ou escolher ferramentas mais amplas do que o necessário. Esse é um comportamento normal para modelos de propósito geral e não indica um problema com os dados do índice.

No uso típico, comece com consultas compactas de metadados e leia intervalos de fonte somente quando evidências de implementação forem necessárias.

Chamadas corretas:

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

Evite:

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

O modelo completo do prompt do sistema está disponível em prompt_template.md.

Fluxos de trabalho de exemplo

Encontrar declaração e definição

Usuário:

Find the declaration and definition of OnNotifyReflect.

Fluxo de trabalho da IA:

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

Analisar uma função sob demanda

Usuário:

Show me Editor::_OnScroll.

Fluxo de trabalho da IA:

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

Então a IA segue apenas chamadas locais relevantes ao projeto:

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

Como um módulo importado é usado

Fluxo de trabalho:

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

Não use find_symbols_glob como substituto para busca de uso na fonte. Ela busca metadados de símbolos, não locais de chamada.

Regras de design

Números de linha exatos são o coração do sistema

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

Manter os dados de runtime pequenos

O índice de runtime armazena fatos de roteamento. Dados de diagnóstico do scanner são opcionais com --emit-diagnostics ou --emit-diagnostic-file-indexes.

Manter busca e navegação separadas

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

Diagnósticos permanecem visíveis

Não oculte problemas reais de parser/fonte apenas para chegar a zero diagnósticos.

Sem expansão de escopo semântico

Sem grafo de chamadas. Sem grafo de referências. Sem expansão de macros. Sem ferramenta de análise. A IA explora a fonte recursivamente sob demanda.

Sequência de reconstrução

cd <project-root>

python <indexer-root>\build_project_index.py

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

Em seguida, reinicie o servidor MCP / LM Studio.

Licença

Este projeto é licenciado sob a Apache License 2.0.

SPDX-License-Identifier: Apache-2.0

Adicione o texto completo da Apache-2.0 no repositório como:

LICENSE

Cabeçalho opcional de arquivo-fonte:

# SPDX-License-Identifier: Apache-2.0

Direitos autorais

Copyright (c) 2026 Mike Walter

Nome do projeto:

mcp-cpp-project-indexer

🤖 Histórico de desenvolvimento

Este projeto foi moldado por um fluxo de trabalho de desenvolvimento assistido por IA multimodelo envolvendo ChatGPT, Gemini e DeepSeek. O objetivo não era deixar um único modelo inventar cegamente uma ferramenta ampla, mas usar vários modelos e feedback real de produção para debater escopo, restrições e atrito no fluxo de trabalho.

  1. Debate de arquitetura e escopo ChatGPT e Gemini foram usados para debater o limite da ferramenta: o que ela deveria fazer, o que deveria evitar e por que deveria permanecer um índice de roteamento leve em vez de se tornar um compilador ou um substituto de clangd.
  2. Implementação incremental A base de código foi implementada incrementalmente com um agente de codificação de IA, com cada mudança funcional testada contra projetos reais pesados em módulos C++20.
  3. Análise e revisão da estrutura do fluxo de trabalho DeepSeek foi usado como parceiro dedicado de análise de fluxo de trabalho durante o uso em produção dentro de uma base de código de 7.000 arquivos. Ele avaliou sequências de chamadas de ferramentas, escolhas de parâmetros, tamanho da saída, qualidade de classificação, atrito de navegação e higiene de contexto, e então devolveu mudanças concretas para reduzir chamadas e melhorar a eficiência de tokens.
  4. Refinamento iterativo O feedback dessas sessões impulsionou melhorias focadas: saídas compactas, filtros de símbolo/arquivo/contêiner, roteamento de hunks de mudança, recarregamentos de watcher, leituras ao redor da linha e regras de prompt mais rígidas.

O resultado é uma ferramenta construída com IA para navegação de código assistida por IA, otimizada em torno de um princípio estrito: manter o indexador honesto e pequeno, e deixar a IA raciocinar apenas a partir de intervalos de fonte que ela lê explicitamente.

Testes de fumaça

Após a integração MCP, teste:

  • get_project_summary
  • Mostrar todos os módulos sob Example.Core.Direct2D.
  • Quais módulos importam Example.Shell.Browser:Impl?
  • Encontre a declaração e a definição de ExampleClass::OnEvent.
  • Leia todas as sobrecargas de GetHandler.
  • Qual arquivo define Example.Elements:ElementImpl?
  • Encontre a definição de ExampleClass::operator=.
  • Liste todos os símbolos em Example/Core/Renderer.cpp.
  • Quais módulos Example.UI:ToggleSwitch importa?
  • Mostre a árvore de módulos para Example.Core (profundidade máxima 3).
  • Encontre todos os arquivos correspondentes a Example Dialog*.
  • Leia as primeiras 20 linhas de Example/Core/Main.ixx.
  • Encontre a declaração de ExampleClass::ExampleClass (construtor).
  • Encontre todos os símbolos correspondentes a Paint em Example/Core/Renderer.cpp.
  • Mostre quais módulos são importados por Example.Shell:Impl.
  • Obtenha o resumo do mapa de módulos.
  • Encontre a definição de ExampleClass::OnKeyDown.
  • Leia o intervalo de ExampleClass::OnPaint (linhas 150-200).
  • Encontre todos os arquivos no módulo Example.UI:Controls.
  • Mostre a árvore de importação para Example.UI:ToggleSwitch.
  • Encontre o símbolo ExampleNamespace::ExampleClass::Method.
  • Liste todos os módulos que importam Example.Core.Service.
  • Encontre a declaração da função de modelo ExampleClass::Create.
  • Leia o símbolo para ExampleClass::OnNotify.
  • Encontre todos os arquivos sob Example/UI/Controls/.
  • Mostre as informações do módulo para Example.Core.Direct2D.Renderer.
  • Encontre a definição de ExampleClass::Initialize.
  • Liste todos os símbolos em Example/Core/Service.cpp que são funções.
  • Encontre quais módulos fazem parte de Example.UI.
  • Leia o código-fonte de ExampleClass::HandleInput (linhas 50-120).
  • Encontre o arquivo que define Example.Core:ModuleImpl.
  • Mostre todas as importações de Example.UI:Controls.Button.
  • Encontre a declaração do enum ExampleClass::State.
  • Leia o símbolo para ExampleClass::GetSize.
  • Encontre todos os arquivos com extensão .ixx sob Example/.
  • Mostre a árvore de módulos para Example.Shell (profundidade máxima 2).
  • Encontre a definição de ExampleClass::_UpdateLayout.
  • Liste todos os símbolos em Example/Core/Utils.cpp.
  • Encontre quais módulos importam Example.UI:Controls.
  • Leia o intervalo de ExampleClass::Paint (linhas 200-250).
  • Encontre a declaração de ExampleClass::~ExampleClass (destrutor).
  • Mostre as informações do módulo para Example.Shell.Browser:Impl.
  • Encontre todos os símbolos correspondentes a Handler em Example/Core/.
  • Leia o símbolo para ExampleClass::OnMouseMove.
  • Encontre o arquivo que define Example.UI:Controls.Button.
  • Liste todos os módulos importados por Example.Core.Direct2D.
  • Encontre a definição de ExampleClass::SetValue.
  • Mostre a árvore de módulos para Example.UI (profundidade máxima 4).
  • Encontre todos os arquivos sob Example/Shell/Browser/.
  • Leia as primeiras 30 linhas de Example/Core/Service.ixx.
  • Encontre a declaração de ExampleClass::GetAccessibleImpl.
  • Liste todos os símbolos em Example/UI/Controls/Button.cpp.
  • Encontre quais módulos são importados por Example.Shell.Browser:Impl.
  • Mostre as informações do módulo para Example.Elements:ElementImpl.
  • Encontre a definição de ExampleClass::OnPropertyChanged.
  • Leia o símbolo para ExampleClass::GetState.
  • Encontre todos os arquivos correspondentes a Service sob Example/Core/.
  • Mostre a árvore de módulos para Example.Elements (profundidade máxima 3).
  • Encontre a declaração de ExampleClass::Register.
  • Liste todos os símbolos em Example/Shell/Browser/Impl.cpp.
  • Encontre quais módulos importam Example.Core.Direct2D.Renderer.
  • Leia o intervalo de ExampleClass::OnInput (linhas 100-150).
  • Encontre a definição de ExampleClass::_SelfLayoutDoLayout.
  • Mostre as informações do módulo para Example.UI:Controls.Dialog.
  • Encontre todos os símbolos correspondentes a Layout em Example/Core/.
  • Leia o símbolo para ExampleClass::GetSliderSize.
  • Encontre o arquivo que define Example.Shell:Impl.
  • Liste todos os módulos que fazem parte de Example.Core.
  • Encontre a declaração de ExampleClass::DefaultAction.
  • Leia as primeiras 40 linhas de Example/UI/Controls/Dialog.ixx.
  • Encontre a definição de ExampleClass::_FireClickEvent.
  • Mostre a árvore de módulos para Example.Core.Direct2D (profundidade máxima 5).
  • Encontre todos os arquivos sob Example/Elements/.
  • Leia o símbolo para ExampleClass::GetCaptured.
  • Encontre quais módulos importam Example.Private.Helper.
  • Mostre as informações do módulo para Example.UI:Controls.Dialog.
  • Encontre a declaração de ExampleClass::SetCaptured.
  • Liste todos os símbolos em Example/Elements/ElementImpl.cpp.
  • Encontre a definição de ExampleClass::OnInput.
  • Leia o intervalo de ExampleClass::_UpdateLabel (linhas 170-180).
  • Encontre todos os arquivos correspondentes a Element sob Example/Elements/.
  • Mostre a árvore de módulos para Example.Private (profundidade máxima 2).
  • Encontre a declaração de ExampleClass::GetPressed.
  • Leia o símbolo para ExampleClass::SetPressed.
  • Encontre quais módulos importam Example.Elements:ElementImpl.
  • Mostre as informações do módulo para Example.Private.Helper.
  • Encontre a definição de ExampleClass::OnPropertyChanged.
  • Liste todos os símbolos em Example/Core/Direct2D/Renderer.cpp.
  • Encontre todos os arquivos com extensão .cpp sob Example/UI/.
  • Leia o símbolo para ExampleClass::GetSliderBorderStrokeWidth.
  • Encontre a declaração de ExampleClass::SliderBackgroundColorProp.
  • Mostre a árvore de módulos para Example (profundidade máxima 1).
  • Encontre todos os módulos que começam com Example.UI.
  • Leia o intervalo de ExampleClass::_SelfLayoutUpdateDesiredSize (linhas 200-220).
  • Encontre a definição de ExampleClass::SliderBorderColorProp.
  • Liste todos os símbolos em Example/Private/Helper.cpp.
  • Encontre quais módulos importam Example.UI:Controls.Dialog.
  • Mostre as informações do módulo para Example.Elements:ElementWithTooltip.
  • Encontre a declaração de ExampleClass::SliderForegroundColorProp.
  • Leia o símbolo para ExampleClass::SliderSizeProp.
  • Encontre todos os arquivos sob Example/Private/.
  • Encontre a definição de ExampleClass::StateProp.
  • Liste todos os símbolos em Example/Core/Service.cpp.
  • Encontre quais módulos são importados por Example.Elements:ElementImpl.
  • Mostre a árvore de módulos para Example.UI.Controls (profundidade máxima 3).
  • Encontre a declaração de ExampleClass::CapturedProp.
  • Leia o símbolo para ExampleClass::PressedProp.
  • Encontre todos os arquivos correspondentes a Helper sob Example/Private/.
  • Encontre a definição de ExampleClass::ClassInfoI::GetClassInfoPtr.
  • Liste todos os símbolos em Example/UI/Controls/Dialog.cpp.
  • Encontre quais módulos importam Example.Private.TreeHelper.
  • Mostre as informações do módulo para Example.UI:Controls.Button.
  • Encontre a declaração de ExampleClass::ElementWithPromptValueI::ElementWithPromptValueProperties.
  • Leia o símbolo para ExampleClass::Initialize (sobrecarga com 3 parâmetros).
  • Encontre todos os arquivos sob Example/Core/Direct2D/.
  • Encontre a definição de ExampleClass::_Initialize.
  • Liste todos os símbolos em Example/Elements/ElementWithTooltip.cpp.
  • Encontre quais módulos importam Example.Private.ValueHelper.
  • Mostre a árvore de módulos para Example.Shell.Browser (profundidade máxima 4).
  • Encontre a declaração de ExampleClass::Register.
  • Leia o símbolo para ExampleClass::ToggleSwitch (construtor).
  • Encontre todos os arquivos correspondentes a Renderer sob Example/Core/Direct2D/.

Comportamento esperado:

  • o modelo usa ferramentas
  • ele não lê arquivos inteiros
  • ele não confunde namespaces com módulos
  • ele chama read_symbol somente após a consulta de metadados de símbolos
  • ele segue chamadas de projeto recursivamente somente quando necessário

Lista de Verificação de Manutenção

Após alterar o comportamento da ferramenta, opções de linha de comando, prompts ou documentação, execute MAINTENANCE_CHECKLIST.md. Ela cobre os pontos de sincronização usuais: descrições de ferramentas, regras de prompt, README, sinalizadores de menu/CLI, compatibilidade de dados de índice, testes de fumaça, premissas de relay e preparação de commit.