In embedded projects a repository often holds several plausible implementations of one subsystem while only one is compiled for the target — an agent can reason convincingly about the wrong driver. Indexing through the same compilation database the build uses is what closes that gap. The included firmware-review case study publishes its numbers and its methodology, so the token claims can be inspected rather than taken on faith.
Build-aware code intelligence for agents working on embedded firmware. It builds a persistent semantic index from `compile_commands.json` and the libclang AST, then answers structural questions — callers, callbacks, function-pointer targets, preprocessor exclusions, inheritance — instead of making the agent reconstruct the program from file reads and text searches.
- Search that degrades gracefully — `search_code` runs FTS5 with a kind filter and, when that returns nothing, broadens through six documented fallback steps, tagging each result with which one matched
- Three search surfaces kept distinct: `search_code` finds symbols by name, `search_bodies` searches only what is between a function's braces, `search_content` searches anywhere in files
- Call-graph queries — `find_callers`, `find_references`, `find_call_path`, `find_all_callers_recursive`, `find_callees_recursive`, `find_dead_code`, `find_hotspots`, `find_wrapper_callers`
- The indirect layer that text search cannot reach — `find_indirect_call_sites`, `find_indirect_targets`, `trace_data_flow`
- C++ structure — `get_inheritance_chain`, `get_class_members`, `get_template_instances`, `get_method_overrides`
- Build awareness — `get_active_build`, `list_variants`, `check_dependencies`, `get_environment_status`, so a multi-variant project is queried per variant or across all with `variant: "*"`
- Source retrieval and explanation — `lookup_symbol`, `get_source`, `get_symbol_context`, `get_file_map`, `explain_symbol`, `read_file`, `smart_search`, `semantic_search`, `find_variables`
Python 3.11 or newer, libclang, a project that can produce `compile_commands.json`, and an MCP-capable agent. Install with `pip install fw-context-mcp` (version 0.27.6, stdio), then `fw-context init` in the project and `fw-context index --build` to build and index. Indexing is incremental by default — only changed translation units are re-parsed; `--build` forces a clean build, `--force` bypasses mtime checks. Ollama is optional and only powers local semantic enrichment and symbol explanations; the compiler-derived core index does not need it.
One command — pip install fw-context-mcp