fw-context

mcp-name: io.github.turbyho/fw-context-mcp

Working on an embedded C/C++ project — Zephyr, PlatformIO, Mbed OS, Arduino, FreeRTOS, and beyond — and want more from your AI assistant than just reading files?

Your AI agent can open main.cpp, but it doesn't know who calls uart_init, which functions are dead, or how data flows from a sensor to the modem. Every question burns tokens repeatedly re-reading headers and source, and you still end up in the wrong #ifdef branch.

fw-context gives your AI agent a compiler-accurate map of your codebase. It parses your actual build flags from compile_commands.json with libclang and builds a persistent index that sees active #ifdef branches exactly like your compiler does. 27 tools for symbol lookup, call-graph traversal, full-text and semantic search, dead code detection, and hotspot analysis. Ask in natural language, get precise answers. No grepping. No hallucination.

If your AI agent works with embedded C/C++, you want this.

What it does

Your AI assistant goes from guessing to knowing:

"What does `uart_init` do and who calls it?" → get_symbol_context("uart_init") — body, callers, callees in one call.

>

"Find all BLE advertising functions and how they're connected." → search_code("ble advertising", kind="function") → find_call_path("gap_init", "start_advertising")

>

"Show me the implementation of `adc_read` — not the declaration." → get_source("adc_read") — exact body via libclang, no file reading.

>

"What would break if I change `spi_transfer`?" → find_all_callers_recursive("spi_transfer") — every caller, direct and indirect.

>

"Give me a map of `modem_msg.cpp` before I read it." → get_file_map("src/modem_msg.cpp") — 426 symbols grouped by kind.

27 MCP tools — symbol search, source reading, call-graph traversal, hotspot analysis, dead code detection, vector search. All backed by real compiler flags from compile_commands.json — #ifdef-aware, not grep.

Quick start

1. Install

#### Prerequisites

# Linux
sudo apt install python3 bear libclang-dev

# macOS
brew install python bear llvm

# Both — uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Both — Ollama (optional)
curl -fsSL https://ollama.com/install.sh | sh   # Linux
brew install ollama                               # macOS

git clone [email protected]:turbyho/fw-context-mcp.git ~/.fw-context/src
cd ~/.fw-context/src && make install

2. Ollama (optional)

Powers smart_search (natural-language search) and explain_symbol. Works without it — the AI assistant processes results on its own. See the installation guide for detailed setup.

3. Register with your AI assistant

fw-context init

4. Update

cd ~/.fw-context/src && make update

5. Index your firmware project

cd your-firmware-project

# One command — auto-detects build system, runs clean build, indexes:
fw-context index

# Skip the build step (use existing compile_commands.json):
fw-context index --no-build

Auto-detection: mbed-os (.mbed, mbed-os/), Zephyr (west.yml), PlatformIO (platformio.ini), or any build with bear.

What happens: On fw-context index without arguments, the tool:

1. Detects your build system
2. Runs a clean build via bear / west / pio to produce a complete

compile_commands.json

1. Parses every translation unit with libclang
2. Builds the SQLite index with symbols, references, and embeddings

Subsequent runs are incremental — seconds for a few changed files. Use --no-build if you already have an up-to-date compile_commands.json.

6. Restart your assistant and start asking about your code

For detailed prerequisites, Ollama setup, and AI assistant integration: [Installation guide →](docs/installation.md)

Why not just use LSP?

LSP servers (clangd, ccls) are excellent for interactive editing. But they have limitations for AI-assisted exploration:

Use clangd for editing, fw-context for AI-assisted exploration.

Architecture

Data flow

graph TB
    subgraph BUILD["Build"]
        build[Bear / West / PIO<br/>cmake / make]
        cc[(compile_commands.json)]
        build --> cc
    end
    subgraph INDEX["Index"]
        libclang[libclang parses each TU<br/>extracts symbols + refs<br/>generates embeddings]
        db[(SQLite on disk<br/>~/.fw-context/index/)]
        cc --> libclang
        libclang --> db
    end
    subgraph QUERY["Query"]
        mcp[MCP tools<br/>JSON-RPC stdio]
        ai[AI assistant answers<br/>your question about the code]
        mcp --> ai
    end
    db --> mcp

Components

graph LR
    cli[CLI: fw-context<br/>index, export, watch, status]
    server[MCP Server: fw-context-mcp<br/>27 tools across search, source,<br/>graph, and maintenance categories]
    ollama[Ollama<br/>optional]
    db[(SQLite + FTS5<br/>+ vec0 + refs)]

    cli -->|writes| db
    server -->|reads| db
    ollama -->|HTTP| server

Features

• Fast lookups — FTS5 full-text search, prefix/exact symbol lookup, call-graph traversal
• Natural-language search — "how does the modem connect?" → finds network_registration, modem_attach, … (Ollama, optional)
• Vector search — semantic similarity via sqlite-vec + Ollama embeddings, hybrid FTS5+vector re-ranking
• Graph analytics — call paths, transitive callers/callees, dead code detection, hotspot analysis
• Indirect call detection — resolves function-pointer arguments at direct call sites, uncovering call-graph edges that grep/cscope miss
• Incremental indexing — only changed files re-parsed; auto-reindex on query detects and fixes staleness
• Offline-first — index is a file on disk at ~/.fw-context/index/. No daemon, no cloud, no network.
• `#ifdef`-aware — uses real compiler flags; sees exactly what your compiler sees

Supported ecosystems

Works with any build system that produces compile_commands.json:

fw-context index handles the build automatically. Use --no-build to skip and use an existing compile_commands.json.

Subsequent runs are incremental — seconds for a few changed files.

Documentation

Directory layout

~/.fw-context/
├── config.toml              # global defaults
├── .venv/                   # Python virtual environment
│   └── bin/
│       ├── fw-context       # CLI
│       └── fw-context-mcp   # MCP server
└── index/
    └── <project-id>/
        └── index.db         # SQLite + FTS5 + vec0 + refs

your-firmware/
├── .fw-context/
│   ├── config.toml          # shared project config (commit to git)
│   └── local.toml           # local developer overrides (gitignored)
└── compile_commands.json