MCP CCPP Project Indexer

mcp-cpp-project-indexerbuilds a lightweight routing index over a C++ source tree. MCP clients can then ask deterministic questions such as:

- where is this function/class/data member?
- which exact source range should be read?
- which module imports or exports this partition?
- which changed hunk intersects which indexed symbol or data range?

The indexer returns metadata and original source ranges. It does not claim to understand the program. The AI still has to read the returned source and reason from that evidence.

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

This keeps large C++ projects out of the prompt until exact source evidence is needed.

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

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

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

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

For multiple MCP clients or a long-running shared process, use HTTP transport:

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

The public rootreadme.mdis human-facing project documentation. The actual Python implementation lives undersrc/:

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

Root-level scripts such asbuild_project_index.py,code_index_mcp_server.py,indexer_tui.py, andupdate_project_index.pyare compatibility wrappers. They keep existing command lines and MCP client configs working while routing execution to the implementation package.

Folder-local READMEs undersrc/use the project-indexer orientation format so agents can discover where to start without turning the public root README into machine-only documentation.

These numbers are machine-dependent. The Chromium run used--jobs 60on a high-core workstation with an Intel Xeon Silver 4316 system, 128 GB RAM, and enterprise NVMe SSD storage. It is a useful public stress test because it exercises a very large classic include-based C++ codebase, while the anonymized commercial project exercises dense C++20 module and partition metadata. The Chromium run also validated the data/member indexer at scale: after fixing nested-template>>depth handling, the public stress test surfaced46,529additional data declarations and66,866additional data-name aliases.

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

The indexer deliberately avoids pretending to be a compiler.
- Fast token/structure scanSource files are scanned with a lightweight Python lexer and structural parser. The output is a deterministic table of contents: files, symbols, data declarations, lexical#includedirectives, source ranges, diagnostics, and module facts.
- C++20 module mapModule interfaces, partitions, imports, export-imports, and consumers are indexed so the AI can route through module-heavy code without asking an LSP to solve the whole build.
- Incremental update and watcherThe updater tracks content hashes and rewrites only changed index data where possible. The optional watcher can keep the MCP server cache fresh while you work in Visual Studio.
- MCP tools with compact output controlsTools expose exact routing metadata first. The AI escalates only when needed: compact symbol lookup, file/module/change overview, exactread_symbolorread_range, then deeper recursive source reads.

Read Renderer.cpp completely: ~2000 lines

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

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

- files and stable file IDs
- C++20 modules and partitions
- lexical#includedirectives
- imports and exports
- namespaces
- classes / structs / enums
- functions / methods
- constructors / destructors / operators
- declarations and inline definitions
- exactstartLine/endLine
- diagnostics for structurally suspicious files

- no compiler-accurate whole-program call graph
- nofind_references
- no type resolution
- no template-instantiation resolution
- no compiler-accurate overload resolution
- no macro expansion
- no semantic summaries
- no bug analysis
- noanalyze_symbol(symbolId)

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

.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

Global symbol and data routing indexes are stored inindex.sqlite. The per-file JSON indexes remain the source of truth for exact source ranges and incremental rebuilds.

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

Scanner diagnostic file-index fields are emitted only with--emit-diagnosticsor--emit-diagnostic-file-indexes:

scopeIntervals structuralEvents functionBodyRanges

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

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

If--project-rootis omitted, the file's parent directory is used.

Recommended usage from the C++ project root:

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

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

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

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 tokensis the indexer's lexer token count over the indexed source after comment blanking. It is a project-size metric, not an LLM billing-token count.

When the project root is inside a Git worktree andgitis available, file discovery respects Git ignore rules by filtering candidates throughgit check-ignore --stdin. This excludes paths matched by.gitignore,.git/info/exclude, or the user's global Git ignore file. Non-Git projects, or systems without Git, fall back to the built-in excluded directory list. Dot-directories such as.git,.vs,.cache,.idea, or.folderare excluded by default.

For large projects with mixed source layouts, placeindexer_config.jsonin the project root or in any subdirectory. Config files are applied while walking the tree: the root config becomes the base, and subdirectory configs can override or extend it for that subtree.