Fw Context MCP server

<!-- mcp-name: io.github.turbyho/fw-context-mcp -->

fw-context

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 produced by the active build configuration.

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. It is used only for local semantic enrichment and symbol explanations; the core compiler-derived index does not require it.

Install via pip (recommended)

pip install fw-context-mcp

Install the current source version

git clone https://github.com/turbyho/fw-context-mcp.git ~/.fw-context/src
cd ~/.fw-context/src
make install

Register fw-context with the supported coding agents detected in your project:

cd /path/to/your/firmware
fw-context init

Build and index the firmware:

cd /path/to/your/firmware
fw-context index --build

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 active build
• 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.

Why embedded firmware is different

Shortened. The full README is on GitHub.