turbyho/fw-context-mcp

**Build-aware code intelligence for AI coding agents working on embedded C and C++ firmware.**
fw-context builds a persistent semantic index from compile_commands.json and the libclang AST, then exposes it to coding agents through MCP. Instead of reconstructing your firmware through repeated file reads and text searches, the agent can query the program structure that one build produces.
It helps agents answer questions such as:
- Which implementation is active in this build?
- Who calls this function, directly or indirectly?
- Where is this callback registered?
- Which function-pointer assignments can reach this call site?
- Which code is excluded by preprocessing?
- What will be affected if this API changes?
- How does execution flow from an ISR to application code?
The goal is not to give the model more source code. It is to give it the **smallest useful, build-aware context** needed for the current task.
Results from a real firmware review
In the included firmware review case study, fw-context was used on an nRF52/Mbed OS project containing approximately 67,000 lines of C and C++:
- 115 changed files reviewed by 8 parallel subagents
- 19 findings across memory safety, concurrency, API use and dead code
- 9 findings that depended on semantic relationships not available from ordinary text search alone
- approximately 54,000 context tokens used by fw-context queries
- an estimated 5.8 million tokens for the equivalent broad grep and file-reading workflow
The case study includes the review output, methodology and per-tool token analysis so the claims can be inspected rather than treated as a black-box benchmark.
Quick start
Prerequisites
- Python 3.11 or newer
- libclang
- a project that can produce compile_commands.json
- an MCP-capable coding agent such as Claude Code or OpenCode
Ollama is optional for the core index: symbols, full-text search, call graph and source come from libclang and SQLite only. With the default configuration, Ollama also computes the vector embeddings (semantic_search, the re-rank step of smart_search) and the symbol analysis (explain_symbol, symbol descriptions). Without Ollama, these features fall back to full-text search or return raw prompts. See Ollama.
Install via pip (recommended)
Install the current source version
Register fw-context with the supported coding agents detected in your project:
Build and index the firmware:
Then restart the coding agent and ask it questions about the project. The index is persistent and incremental; after the initial run, changed translation units are reprocessed instead of rebuilding the entire index.
See the Quick Start and Installation Guide for platform-specific setup and supported build systems.
What fw-context changes
Without a semantic project index, an AI coding agent usually starts by opening files, searching for names, following includes and trying to infer relationships that are implicit in the build. In embedded firmware this reconstruction is often the dominant part of the task.
That approach can fail in predictable ways:
- reviewing source files that are not part of the build that you query
- following the wrong preprocessor branch
- missing callback registrations and indirect calls
- selecting an inactive driver or platform implementation
- treating declarations found by text search as reachable code
- consuming large amounts of context on vendor code and unrelated files
fw-context moves much of that reconstruction into a reusable compiler-derived index. The agent can request exact symbol bodies, callers, callees, references, active macros, callback relationships, inheritance edges and other targeted information without reading whole source trees.