Fw Context MCP

What turbyho/fw-context-mcp does

turbyho/fw-context-mcp gives coding agents structured access to the C and C++ program represented by a firmware build. It reads compile_commands.json and parses translation units with libclang, then stores symbols, source extents, active preprocessor content, macros, references, call-graph edges, inheritance data, and project/vendor classification in a persistent SQLite index with FTS5 search.

The build context matters for embedded projects: multiple implementations, compiler definitions, generated headers, board selections, and RTOS configuration can coexist in one source tree. Queries are tied to an indexed build and can distinguish project code from SDK or vendor paths. Multi-variant projects can expose variant, image, board, linker entry-point, and memory-region information.

How it works

Initialize a project and create its compilation database, then run the fw-context index command. The server checks index health with get_active_build and can reparse changed files incrementally. Full indexing uses the compiler flags from compile_commands.json, while file-level reindexing updates one source file or parses a header through an including translation unit.

Core analysis comes from libclang and SQLite. Search tools operate on active, ifdef-filtered code for the selected build. Reference and call-graph tools model ordinary calls as well as function-pointer assignments, callback registrations, interrupt-vector relationships, implicit constructors, and selected dispatch bridges. Optional LLM features use precomputed analysis or query a configured backend; semantic search requires embeddings, and smart_search uses an LLM-driven search pipeline with fallbacks.

Setup and configuration

Install with Python 3.11 or newer, libclang, and the fw-context-mcp package:

pip install fw-context-mcp

From a firmware project, initialize the integration and build the index:

fw-context init
fw-context index --build

Restart the coding agent after initialization. The project must be able to produce compile_commands.json. Supported project families include Zephyr, PlatformIO, Mbed OS, Arduino, ESP-IDF, generic CMake, Makefile-based projects, and custom builds that provide a compilation database. Additional setup paths cover Keil, IAR, STM32CubeIDE, and TI Code Composer Studio.

Ollama is optional. Without an LLM backend, symbol indexing, source search, call-graph queries, and core SQLite-backed analysis remain available. Embedding-based search falls back to lexical search when embeddings are unavailable, and explanation or enrichment requests can return source and a prompt instead of generated analysis. A configured external chat endpoint may receive source snippets, so its use should be reviewed against applicable data-security requirements.

Tools and capabilities

• Check dependencies, build metadata, compile-database state, index freshness, project registration, and available build variants.
• Search exact or prefixed symbols, names and documentation with lookup_symbol and search_code.
• Search active function and type bodies with search_bodies, or whole ifdef-filtered files with search_content.
• Use semantic_search and smart_search for concept-oriented retrieval when the required LLM or embedding services are configured.
• Inspect callers, callees, call paths, all references, indirect targets and indirect call sites.
• Analyze dead-code candidates, highly referenced functions, wrapper classes, recursive dependencies, and type-based data flow.
• Inspect interrupt vector tables, including C, assembly, linker, runtime, dispatcher, data, and unhandled entries where the build exposes them.
• Retrieve symbol explanations, source context, macros, class relationships, and build-specific metadata.
• Reindex individual files, reset an index, configure per-project LLM settings, and audit the environment.

Limitations and notes

Queries depend on the quality and coverage of compile_commands.json. A source file absent from that database cannot be incorporated by a normal file reparse. Header reindexing through one including translation unit may not represent every compilation context; a full index is needed for complete coverage.

Call-graph results can omit ambiguous fallback edges rather than risk assigning a call to the wrong method. Dead-code detection identifies symbols with no indexed references, not full reachability from application entry points, and possibly-dead function-pointer assignments require review. Data-flow tracing is intended for synchronous paths and cannot follow asynchronous queues, interrupts, or callback flows completely.

Index status should be checked before querying. Structural mismatches may require reindexing, while an index written with a newer row format requires restarting the client rather than rewriting the database. Semantic search answers for the active build and does not select a variant or image; build-specific lexical and body searches should be used when that distinction matters. Interrupt analysis cannot represent architectures whose vector tables are built from branch instructions, and some link-resolved handler addresses have no source-level name.