io.github.turbyho/fw-context-mcp
PYPI · FW-CONTEXT-MCP
Build-aware code intelligence for embedded C/C++ firmware — libclang, FTS5, call graphs, 37 tools
Available components
Last scanned (16 hours ago)
Scores higher than 53% of PyPI servers
Category Code Search and Documentation
How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. How we score → Why this is hard to score →
Supply Chain Security50
- Malware scan not yet available for this package.Unverified
- No known CVEs affecting this package version or its production dependencies.Pass
- Runs hatchling.build at install time, a recognised build step with no custom scripting around it. View diagnostics → Pass
- 4 of 51 dependencies flagged as unhealthy. View diagnostics → Partial
Provenance & Transparency45
- Source repository is publicly reachable at the declared URL. View diagnostics → Pass
- Provenance check failed: no build-provenance attestation is published. See how to fix → View diagnostics → Fail
- Clear OSI-approved license (MIT AND Apache-2.0 WITH LLVM-exception).Pass
- Actively maintained (last published 0 days ago).Pass
- Disclosure check failed: no security disclosure policy was found in the source repository. See how to fix → Fail
Schema Quality & AI Usability72
- 100% of prompts and resources have a non-trivial description (not blank, and not just the item's name).Pass
- AI-judged instruction clarity (excellent).Pass
- Context-footprint check failed: tool/resource definitions use about 55163 tokens (~1379/item across 40 items; 37 tools + 3 resources), over budget; trim descriptions and params. See how to fix → Fail
- Usage-examples check failed: none of the tools include examples. See how to fix → Fail
Stability & Change Management43
- Stability observed for 13 of 30 days with no destabilising changes; credit accrues until the full window elapses.Partial
Tool Coverage100
- 100% of tools have a non-trivial description (not blank, and not just the tool's name).Pass
- 100% of tool parameters carry a description.Pass
- Structured output schemas are declared (59% of tools); any adoption earns full credit.Pass
Tool Safety75
- No prompt-injection markers were found in the server instructions, tool names or descriptions we captured.Pass
- 0 of 1 tool(s) whose name or description implies an irreversible operation declare an MCP destructiveHint annotation; "reset_index" implies "delete" and declares no destructiveHint at all, which the MCP spec reads as destructive by default. See how to fix → Fail
- An AI judge read all 39 captured unit(s) of tool text and found none that tries to manipulate the model reading it.Pass
Capabilities100
- Implements a supported MCP spec version (2025-11-25); the latest is 2026-07-28.Pass
Checks we ran (15)
- Known CVEs
- Install scripts
- Dependency health
- Source repository
- Provenance
- License
- Maintenance
- Security disclosure
- Schema quality
- Stability
- Tool coverage
- Injection markers
- Destructive annotations
- Judged manipulation
- MCP protocol
Checks we could not complete (1)
These are gaps on our side, not findings about this package. We only credit what we can confirm, so a category made up entirely of them scores 0.
- Malware scan in Supply Chain SecurityMalware scan not yet available for this package.
Does not apply to this package (2)
- Endpoint SecurityScored on hosted endpoints only. A package has no live endpoint of its own for us to probe.
- Transport & ReachabilityScored on hosted endpoints only. A package has no live endpoint of its own for us to probe.
The score does not measure everything. What the score does not measure →
Every change we have recorded for this component, newest first. Security-relevant changes are always shown. ▲ marks a change for the better, ▼ a change for the worse; unmarked changes are neutral.
- 21 Nov 26 −15
- Malware scan: pass → unverified ▼ security
- 20 Nov 26 +26
- Malware scan: unverified → pass ▲ security
- Known CVEs: unverified → pass ▲ security
- Dependency health: unverified → 0.97 ▲ functional
- Package version: 0.37.0 → 0.37.1 functional
- 19 Nov 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 33 to 37. That category is still filling its 30-day observation window: 10 days of observed history at the previous scan, 11 at this one. The score rises as the window fills, whether or not the server changes.
- 18 Nov 26 −11
- Known CVEs: pass → unverified ▼ security
- Dependency health: 0.97 → unverified ▼ functional
- 17 Nov 26 +1
- Security disclosure: unverified → fail ▼ functional
- 16 Nov 26 0
- Security disclosure: fail → unverified ▼ functional
- 15 Nov 26 +1
No change was recorded against any check on this day. Stability & Change Management went from 20 to 23. That category is still filling its 30-day observation window: 6 days of observed history at the previous scan, 7 at this one. The score rises as the window fills, whether or not the server changes.
- 14 Nov 26 +3
- Malware scan: unverified → pass ▲ security
- Stability: unverified → 0.20 ▲ functional
- Package version: 0.36.0 → 0.37.0 functional
Diagnostic detail from the automated scan of this channel: what the scanner observed at each step, so you can see exactly where a check passed or failed. It is informational only and never changes the trust score.
Captured 21 Nov 2026 · Analysed pypi/fw-context-mcp@0.37.1
Provenance No attestation
The registry publishes no build provenance for this version, so there is nothing to verify.
| Result | No attestation |
|---|---|
| Ecosystem | pypi |
| Reason | No attestation published |
Background: How many MCP packages publish verified provenance →
Install scripts 1 script
| Hook | Tier | Command |
|---|---|---|
| build_backend | Known build tool | hatchling.build |
Background: Why install scripts are a supply-chain risk →
Dependencies 51 packages
| Packages resolved | 51 |
|---|---|
| Stale | 3 |
| No linked repository | 1 |
| Tree resolution | Complete |
Background: SBOMs and build attestations, explained →
The tools this component advertises to a client, with an estimated token cost for each. Expand a tool to see its parameters and schema. The per-tool counts are indicative and are not scored directly; the schema's total context footprint is one signal in Schema Quality & AI Usability. A tool's description is untrusted text the model reads on every call, which is what makes this list a security surface and not just an inventory: how tool poisoning works →
check_dependencies ~472
Run the dependency audit of the installation. Read-only, and it creates no file. Call it when get_project_status or another tool reports a problem of the installation, or before the first ``fw-context init``. It is not a call for each session: it runs every check of the installation. Each entry gives what to do in ``action``: a ``message`` for a human, and the shell ``command`` that repairs it. ``status="skipped"`` means a prerequisite is missing (e.g. ``libclang-so`` skipped because ``libclang-python`` is absent) — not a failure. In a project that is not initialized, only the checks of the installation run: the Python packages, SQLite, libclang and its headers. The LLM, model, database and disk checks need the config. The check ``config`` names a config file that cannot be used. The checks that read the config are then ``skipped``. When a config file cannot be used, the tool cannot know if the project is initialized, thus it runs every check. Args: project_root: Project root directory. Auto-detected from CWD if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. Returns: list[dict]: one dict per check, each with ``name``, ``status``, ``critical`` (bool), ``message``, and an optional ``action`` ({message, command}).
| Name | Type | Req | Description |
|---|---|---|---|
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. Pass explicitly when the project is not the server cwd. This field also accepts a project name or a project_id, but project is the clear field for those. |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
check_ollama ~1,329
Check whether the LLM backend is running and the configured embedding/chat model is installed. Read-only: yes. No side effects. Call before smart_search, semantic_search, or explain_symbol (when on-demand fallback is expected — pre-computed analysis returns instantly without the LLM backend). Args: project_root: Project root. Auto-detected if omitted. Used to locate the project's LLM configuration. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. Returns: dict: {ollama_enabled (bool), status (str — "ok"|"disabled"| "not_configured"|"model_missing"|"embedding_unavailable"|"error"), ollama_running (bool), ollama_url (str), configured_model (str), num_ctx (int), installed_models (list[str]), chat_api (dict — ``{configured (bool), model (str)}``: whether an external chat API replaces Ollama, and the model it names; a configured one adds endpoint, format, and compliance_warning for an external host), configured_embed_model (str), embedding_installed (bool), embedding_backend (str — "ollama", "local" for a sentence-transformers or ``ft://`` model, which needs no Ollama: it counts as installed, and with chat on an external API a stopped Ollama still gives "ok"; or the provider of an API profile of the embeddings, "openrouter" or "openai_compatible"), embedding_compliance_warning (str, when the embeddings go to an external API: the code and each search query leave the machine), version_problem (str, when the Ollama server of ``ollama_url`` is older than the oldest version of one of its uses: 0.40.15 for the embeddings, 0.30.1 for the chat), message (str, when status is not "ok"), model_details (list[dict]), suggest_cloud (bool), vec_available (bool), ve…
| Name | Type | Req | Description |
|---|---|---|---|
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. Used to locate LLM config. Falls back to auto-detection when omitted. This field also accepts a project name or a project_id, but project is the clear field fo… |
No output schema declared.
No examples provided.
configure_llm ~715
Select the LLM profile (and the embedding model) of the current project. Writes to ``<project>/.fw-context/local.toml`` ONLY (gitignored, per-developer). Does NOT modify the global config or the shared project ``config.toml``. The profiles themselves are in the global config, and only the operator writes them (``fw-context llm setup`` or ``fw-context init``): this tool takes no URL and no API key. After writing, tests the configuration by making a simple API call (skipped when LLM is disabled). When the test fails, the previous ``local.toml`` is restored and ``status`` is ``"error"``. A call with no change returns ``"error"`` and writes nothing. WHY no URL and no key here (since the profiles, 2026-10-20): a key that an MCP call writes passes through the conversation of the LLM client, and a URL that a tool call sets can send the source code to any host. Args: project_root: Project root directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. profile: The name of a profile of the global config. embed_model: Embedding model: an Ollama tag, a sentence-transformers name (``BAAI/...``, needs the ``st`` extra), or ``ft://``. Returns: dict: {status ("ok"|"error"), profile (str), provider (str), chat_api (dict — configured, endpoint, format, model), model (str), auto_pull (bool), stream (bool), context (int, for a profile of an API or of the ChatGPT plan: the context of the model in tokens), test_latency_s (float, on success), test_response (str, on success), compliance_warning (str, when the chat goes to another host), message (str)}
| Name | Type | Req | Description |
|---|---|---|---|
| embed_model | – | – | Embedding model: an Ollama tag, a sentence-transformers name (e.g. 'BAAI/bge-small-en-v1.5'), or 'ft://latest'. None = keep current. |
| profile | – | – | The LLM profile of this project: the name of a [llm.profiles.<name>] table of the global config (~/.fw-context/config.toml). None = keep the current profile. A project selects an external profile (an… |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
No output schema declared.
No examples provided.
explain_symbol ~1,121
Explain what a C/C++ symbol does in plain English — libclang-aware analysis. Uses pre-computed LLM analysis when available (instant), falls back to on-demand LLM. Falls back to macro explanation when the name matches a ``#define``. Read-only. No side effects — uses pre-computed LLM analysis when available (instant, generated during ``fw-context index --analyze``), falls back to calling an LLM on-demand. Returns the symbol's purpose, inputs, outputs, and side effects. For raw source code use ``get_source``. For symbol metadata without explanation use ``lookup_symbol``. For body + callers + callees use ``get_symbol_context``. Args: name: Symbol name to explain. E.g. ``uart_init``, ``Modem::send``. project_root: Project root directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. context_lines: Lines of source context around the symbol definition (default 40, max 200). Only used when no pre-computed analysis exists. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name. Returns: dict: {name, kind, file, line, signature, explanation, llm_analysis (if pre-computed)}. With no pre-computed analysis and no LLM (disabled), the dict holds ``explain_prompt`` and no ``explanation``. Macro fallback returns ``kind="macro"``, ``signature`` (as ``#define NAME`` or ``#define NAME(a, b)``), ``…
| Name | Type | Req | Description |
|---|---|---|---|
| context_lines | integer | – | Lines of source context around the symbol definition (1-200). |
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| name | string | yes | Symbol name to explain. E.g. 'uart_init', 'Modem::send'. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
No output schema declared.
No examples provided.
find_all_callers_recursive ~1,215
Find all transitive C/C++ callers — who calls *name*, directly or indirectly, through the libclang call graph including function-pointer edges, implicit constructors, and the edges of the SDK model. libclang-powered: follows function-pointer assignments and ISR vector registrations across the full call tree. Use for impact analysis: "if I change this function, how far does the ripple go?" Returns callers at depth 1 (direct), depth 2 (callers of callers), up to ``max_depth`` (default 5). Results are deduplicated — each caller appears once at its shortest distance to the target. **Edge types traversed:** Includes ``call``, ``indirect`` (function pointers / ISRs), ``implicit_construct`` (the constructors of the objects at namespace or class scope). A ``call`` edge with the origin ``sdk`` comes from the SDK model: the registration function (``xTaskCreate``) calls the task. **Limitation — calls without a target:** a call that libclang cannot resolve (a dependent call in a template that is never instantiated) has no edge, because fw-context does not take a target from a name. A construction that the source does not write has no edge either: the default construction of a member, and the member constructions of an implicit constructor. If you suspect a missing caller, verify with ``search_bodies("target_name")`` and ``find_indirect_targets``. For a flat, single-level caller list use ``find_callers`` (faster). For the reverse direction use ``find_callees_recursive``. Read-only. No side effects. Requires the reference index (``fw-context index`` — refs on by default). BFS from the target outward; performance scales with call-graph fan-out. Args: name: Symbol name to find transitive callers of. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results (default 50). |
| max_depth | integer | – | Maximum BFS depth for transitive search (default 5). |
| name | string | yes | Symbol name to find transitive callers of. |
| offset | integer | – | Skip this many results. Reads the next page of a deep call tree. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
find_call_path ~1,601
Find call paths between two C/C++ functions via BFS in the libclang call graph, including function-pointer edges, ISR vector registrations, implicit constructors, and the edges of the SDK model (a task that the scheduler starts). libclang-powered: follows function-pointer edges and ISR vector registrations that text-based search cannot resolve. Use to answer "how does A reach B?" — e.g. tracing how a high-level event handler eventually calls a low-level driver. Returns up to 5 distinct paths in BFS order (short paths first), each with ``depth`` (edge count) and ``chain`` (e.g. ``"main → app_run → modem_init"``). **Edge types traversed:** The BFS includes ``call``, ``indirect`` (function pointers / ISRs), and ``implicit_construct`` (the constructors of the objects at namespace or class scope). A ``call`` edge with the origin ``sdk`` comes from the SDK model: the registration function (``xTaskCreate``) calls the task. **Limitations:** - **SDK entry points:** an SDK can start a task, a thread or a callback from data that the call graph cannot follow (a stack frame, a library without source, an event in memory through ``void *``). Such a function gets its caller from the SDK model. The built-in rules cover FreeRTOS, ESP-IDF, lwIP, POSIX ``pthread_once``, the NVM of Nanostack, the stdio of picolibc and avr-libc, Zephyr threads, CMSIS and the mbed ``EventQueue`` (``call``, ``call_in``, ``call_every``). A handler of ``queue.event(handler)`` gets no caller from the model. Add the rules of another SDK in ``[[call_graph.sdk]]`` (``.fw-context/config.toml``). - **Calls without a target:** a call that libclang cannot resolve (a dependent call in a template that is never instantiated) has NO call edge. fw-context does not take a target from the name of the call: that once gave false paths through a method of the same name. - **Global constructors:** the ``implicit_construct`` edges of the objects at namespace or class scope hang off a sy…
| Name | Type | Req | Description |
|---|---|---|---|
| from_name | string | yes | Starting symbol for path search. |
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| max_depth | integer | – | Maximum BFS depth from each end of the search (default 10). A path can hold up to 2 x max_depth edges. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| to_name | string | yes | Target symbol to find path to. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
find_callees_recursive ~1,151
Find all transitive C/C++ callees — what *name* calls, directly or indirectly, through the libclang call graph including function-pointer edges, implicit constructors, and the edges of the SDK model. libclang-powered: follows function-pointer calls and indirect invocations across the full dependency tree. Use for dependency analysis: "what does this function depend on to do its job?" Returns callees at depth 1 (direct), depth 2 (callees of callees), up to ``max_depth`` (default 5). Results are deduplicated by shortest distance. **Edge types traversed:** Includes ``call``, ``indirect`` (function pointers / ISRs), ``implicit_construct`` (the constructors of the objects at namespace or class scope). A ``call`` edge with the origin ``sdk`` comes from the SDK model: the registration function (``xTaskCreate``) calls the task. **Limitation — calls without a target:** a call that libclang cannot resolve (a dependent call in a template that is never instantiated) has no edge, because fw-context does not take a target from a name. If you suspect a missing callee, verify with ``search_bodies("target_name")``. For direct callees only, ``get_symbol_context`` gives a faster flat list along with the function body and callers. For the reverse direction use ``find_all_callers_recursive``. Read-only. No side effects. Requires the reference index (``fw-context index`` — refs on by default). Args: name: Symbol name to find transitive callees of. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. max_depth: Maximum BFS depth for transitive search (default 5). limit: Maximum results (default 50). offset: Skip this many results. Reads the next page of a deep call tree; the page not…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results (default 50). |
| max_depth | integer | – | Maximum BFS depth for transitive search (default 5). |
| name | string | yes | Symbol name to find transitive callees of. |
| offset | integer | – | Skip this many results. Reads the next page of a deep call tree. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
find_callers ~1,725
Find who calls a C/C++ function — direct calls AND indirect via function pointers, callbacks, and struct/array init lists (such as a vector table that the build generates in C). libclang-powered: detects function-pointer assignments that text-based search cannot see. A slot of an assembly vector table (``ref_kind`` ``"vector"``) and an ``NVIC_SetVector`` install (``"runtime_vector"``) are not callers: use ``find_references`` or ``get_vector_table`` for those. The SDK model gives the handler of an ``NVIC_SetVector`` install a ``"call"`` row from ``NVIC_SetVector`` too (origin ``"sdk"``, entry ``"an interrupt"``). Falls back to macro lookup when the symbol is not found as a function/method: returns the macro definition (kind="macro") and files that use it (ref_kind="macro_use"). Use when you need a quick, flat list of immediate callers. For the full transitive call tree (who calls this indirectly through other functions), use ``find_all_callers_recursive``. For all references including reads and member accesses, use ``find_references``. For a path between two specific symbols, use ``find_call_path``. Read-only. No side effects. Requires the reference index (``fw-context index`` — refs are on by default). Only direct call sites are returned; callers more than one hop away are not included. Indirect edges (``ref_kind: "indirect"``) are detected when a function pointer references a function through: - **Call arguments**: ``callback(&Class::method, this)``, ``EventQueue::call_every(ms, obj, &handler)`` - **Assignments**: ``driver.onData = &handleData``, ``global_cb = &handler`` - **Variable initializers**: ``static void (*fp)(int) = &handler`` - **Struct/array init lists**: ``{.on_data = &handler}``, ``{&fn_a, &fn_b}`` Args: name: Symbol name to find callers of. Uses the same three-tier resolution as ``find_references`` (exact name, exact qualified, suffix LIKE). project_root: Project root directory. Auto-detected if omitted. p…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results of one page (default 50, max 200). |
| name | string | yes | Symbol name to find callers of. Returns direct call sites and indirect calls via function pointers. |
| offset | integer | – | Skip this many results. Reads the next page of a symbol with many call sites. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
find_dead_code ~1,474
Find C/C++ functions that are defined but never called — libclang-powered dead code detection across the entire indexed codebase. Distinguishes called from uncalled symbols globally, not just within a single file — text-based search cannot determine whether a function is actually reachable. **What "dead" means:** zero references of any ``ref_kind`` in the index — no call, no read, no function-pointer use, no vector slot. Only functions, methods, constructors, and destructors with a definition are checked. This is a single-layer reference check, NOT a reachability analysis from the entry points (main, ISR, exported symbols): a function that only a second dead function calls still has a reference, thus this tool does not mark it. For transitive reachability, trace from your entry points with ``find_callees_recursive``. The ``status`` field splits the results: * ``"dead"`` — no reference at all. Likely unused. * ``"possibly_dead"`` — assigned to a function pointer (``ref_kind="indirect"``) and never called directly, but no call site through that pointer resolved. Unindexed code or a type-erased API can still call it. Treat it as uncertain, and check each hit with ``find_indirect_targets`` before you delete anything. A call that reaches a function by its type only (origin ``"type_only"`` in ``find_callers``) is a call too: the function is not reported, also when no code really calls it through that pointer. fw-context records the constructor call of an object at namespace or class scope as an ``implicit_construct`` reference, and the constructor call of a local object, a new-expression or a member initializer as a ``call``. A construction that the source does not write has no reference: the default construction of a member that a constructor does not name, and the member constructions of an implicit constructor. A constructor that only such constructions call can show as dead; check its class with ``find_references`` before you delete it. ISRs: a h…
| Name | Type | Req | Description |
|---|---|---|---|
| exclude_paths | – | – | LIKE patterns on the project-relative file path to exclude, on top of project_only. E.g. ['lib/%']. |
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results of one page (default 100, max 200). |
| offset | integer | – | Skip this many results. Reads the next page of a long report. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_only | boolean | – | When True (default), keeps only project code (is_project, from the vendor_paths/project_paths config and SDK detection). Set False to see all results. |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
find_hotspots ~863
Find the most-called C/C++ functions ranked by caller count — libclang call-graph hotspot detection. Identifies functions with the most architectural weight — good targets for refactoring, optimization, or extra testing. Text-based search cannot aggregate caller statistics across the full call graph. Use for high-level impact assessment: changing a hotspot affects many call sites. The result tells you which functions carry the most "architectural weight" across the entire codebase. By default, SDK/vendor paths are auto-excluded so hotspots reflect project code. Use ``project_only=False`` to see all results including vendor code. For the callers of a specific hotspot, follow up with ``find_callers`` or ``find_all_callers_recursive``. Read-only. No side effects. Requires the reference index (``fw-context index`` — refs on by default). Args: project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Number of top-called functions per page (default 20, max 50). offset: Skip this many results. Reads further down the ranking; the page notice names the offset to use. project_only: When True (default), filters to ``is_project = 1`` symbols so hotspots reflect project code. exclude_paths: Additional LIKE patterns to exclude (user-supplied tool parameter). E.g. ``['lib/%']``. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application…
| Name | Type | Req | Description |
|---|---|---|---|
| exclude_paths | – | – | LIKE patterns on the project-relative file path to exclude, on top of project_only. E.g. ['lib/%']. |
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Number of top-called functions per page (default 20, max 50). |
| offset | integer | – | Skip this many results. Reads further down the ranking. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_only | boolean | – | When True (default), auto-excludes SDK/vendor paths so hotspots reflect project code. |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
find_indirect_call_sites ~1,236
Find the indirect calls through a C/C++ function pointer field or variable, or the indirect calls that a function makes, with the functions that each call reaches. An indirect call goes through a slot: a field, a variable, a parameter or the return value of a function that holds a function (``driver.onData(buf, len)``, ``g_cb(42)``, ``handlers[i](x)``), or the ``operator()`` of a ``std::function`` or another callable object. For a field or a variable, the answer holds each call through it, also through a copy of its value (``cb_t f = dev->on_rx; f(1);``). Read-only. No side effects. Use this to answer "where is this function pointer invoked, and what does it call?" as opposed to ``find_callers`` which answers "who calls this function?" (an indirect call that reaches it is a ``"call"`` row there, origin ``"slot"`` or ``"type_only"``). For the functions that a pointer can hold, and where the code stores them, use ``find_indirect_targets``. Requires the reference index (``fw-context index`` — refs on by default). Args: name: A function pointer field or variable, or a function, method or lambda. Resolved as every symbol tool resolves a name (qualified name, bare name, suffix); a name of several symbols answers for each of them. A parameter is no symbol: ask with its function. project_root: Project root directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Maximum results (default 50, max 200). offset: Skip this many results. Reads the next page; the page notice names the offset to use. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the r…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results (default 50, max 200). |
| name | string | yes | A function pointer field or variable (the calls through it), or a function (the indirect calls it makes). E.g. 'onData'. |
| offset | integer | – | Skip this many results. Reads the next page of a long answer. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root directory. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
find_indirect_targets ~1,251
Find the functions that a C/C++ function pointer field or variable can hold, and where the code stores each of them; or, for a function, where the code stores its address and which indirect calls reach it. The answer comes from the data flow of the build, not from names: a function reaches a field when the code stores it there, or stores it in a slot whose value flows there (an argument of ``set_cb(h)`` into the parameter, the parameter into the field), in any file of the build. For the calls through the pointer, use ``find_indirect_call_sites``. Read-only. No side effects. Requires the reference index (``fw-context index`` — refs on by default). Args: name: A function pointer field or variable, or a function, method or lambda. Resolved as every symbol tool resolves a name; a name of several symbols answers for each of them. project_root: Project root directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Maximum results (default 50, max 200). offset: Skip this many results. Reads the next page; the page notice names the offset to use. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name. Returns: For a field or a variable, one dict per function: function, kind, file and line (the definition), origin (``"slot"``), stored_file and stored_line (the first pl…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results (default 50, max 200). |
| name | string | yes | A function pointer field or variable (the functions it can hold), or a function (where the code stores its address, and the indirect calls that reach it). E.g. 'onData'. |
| offset | integer | – | Skip this many results. Reads the next page of a long answer. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
find_references ~1,293
Find ALL references to a C/C++ symbol — calls, reads, member accesses, function pointer registrations, vector table slots, and macro usages. libclang-powered: detects function-pointer registrations (vector table entries, callback attachments, ``NVIC_SetVector`` installs) that text-based search cannot see. Falls back to macro lookup when the symbol is not found as a function/method: returns the macro definition (kind="macro") and files that reference it (ref_kind="macro_use"). Read-only. No side effects. Returns every reference in the indexed codebase, including call sites, variable reads, struct member accesses, indirect function-pointer references, and macro usages. Requires the reference index (``fw-context index`` — refs on by default). For direct callers only use ``find_callers``. For transitive callers use ``find_all_callers_recursive``. For call paths between two symbols use ``find_call_path``. Args: name: Symbol name to find all references of. project_root: Project root directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Maximum results of one page (default 50, max 200). offset: Skip this many results. Reads the next page of a symbol with many references; the page notice names the offset to use. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name. Returns: The page not…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results of one page (default 50, max 200). |
| name | string | yes | Symbol name to find all references of — calls, reads, member accesses. |
| offset | integer | – | Skip this many results. Reads the next page of a symbol with many references. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
find_variables ~1,357
Find C/C++ variables by name or part of it and trace who reads or writes them through the call graph. libclang-powered: splits variables into global (``varglobal`` — file/namespace/class-scope) and local (``varlocal`` — inside a function body). Each result includes a type signature (``bool timeSet``, ``const IPAddress modbus_ip``), the enclosing function for locals (``"<file scope>"`` for globals), and a ``references`` list of the functions that read or write the variable — the same ``ref_kind`` values as ``find_references`` (``"call"``, ``"ref"``, ``"member"``). The list is capped at 30 per variable, and holds only references of the selected build; ``references_total`` gives the whole count. Only definitions are returned, globals first, then by name. Use when you need to understand shared state, find who modifies a global variable, trace side effects, or distinguish important globals from loop counters. For general symbol search use ``search_code`` or ``lookup_symbol``. For all references to a specific variable (including reads in expressions), use ``find_references``. This tool is the way to a LOCAL variable: ``search_code`` drops the ``varlocal`` kind, because a local matches every topic query aimed at the function around it. ``search_code(..., kind="varlocal")`` reaches them as well. Legacy indexes with ``kind="variable"`` (pre-split) are detected and included in results — reindex to fully benefit from the split. Read-only. No side effects. Args: name: Variable name or part of it. Substring match on name and qualified name (e.g. ``g_`` finds ``g_debug_level``, ``g_state``). project_root: Project root directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. kind: Optional kind filter…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| kind | – | – | Filter by kind: 'varglobal', 'varlocal', 'field', legacy 'variable', or None for all. |
| limit | integer | – | Maximum results (default 20, max 100). |
| name | string | yes | Variable name or part of it. Substring match on name and qualified name (e.g. 'g_' finds g_debug_level, g_state). |
| offset | integer | – | Skip this many variables. Reads the next page of a name that many variables share. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
find_wrapper_callers ~1,021
Find C/C++ wrapper classes that call methods of a driver class — libclang-powered adapter pattern detection. Traces method ownership across class boundaries to reveal the wrapper/adapter architecture (e.g. ``UART`` wraps ``UART_DRIVER``). Text-based search cannot distinguish which class owns each method call. Returns wrapper methods grouped by wrapper class, showing which driver methods each wrapper calls. Useful for understanding the adapter/wrapper architecture (e.g. ``UART`` wraps ``UART_DRIVER``). For the reverse perspective — finding who calls a specific driver method — use ``find_callers``. For class member listing use ``get_class_members``. Read-only. No side effects. Requires the reference index (``fw-context index`` — refs on by default). Args: class_name: Driver class name to find wrappers for. E.g. ``'UART_DRIVER'`` or ``'hal::UART_DRIVER'``. The name is case-sensitive. A bare name that names no top-level class matches the class of that name in each namespace, but not a class whose name only ends with it. The methods of a class nested in the driver class count as driver methods. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Maximum wrapper classes on one page (default 20, max 100). Each class comes with all of its methods and calls into the driver (``call`` and ``indirect`` references), thus a class is never split over two pages. offset: Skip this many wrapper classes. Reads the next page; the page notice names the offset to use. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of o…
| Name | Type | Req | Description |
|---|---|---|---|
| class_name | string | yes | Driver class name to find wrappers for. E.g. 'UART_DRIVER' or 'hal::UART_DRIVER'. Case-sensitive. |
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum wrapper classes on one page (default 20, max 100). |
| offset | integer | – | Skip this many wrapper classes. Reads the next page. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
get_build_info ~1,638
Return the detail of ONE build: its identity, its health, its memory map and its defines. Read-only with the two exceptions that ``get_project_status`` also has: it removes the marker of a missing build when it finds that build again, and a ``reindex.pid`` or a ``reindex.pending`` of a process that no longer runs. It spawns no subprocess. On a project of more than one build, give the arguments of one build as the refusal lists them: the ``variant``, the ``image``, or the two. ``get_project_status`` lists the builds in ``builds``. Without the arguments the answer is an error that lists the builds. A project of one build needs no selector. The health fields (``status``, ``reindex_state``, ``reindex_needed``, ``reindex_reasons``, ``index_message``, ``modified_files_count`` and the others) have the meaning that ``get_project_status`` gives them, for this build only. The version fields (``update_notice``, a restart after an upgrade) are in ``get_project_status``. About ``memory``: ``origin`` and ``length`` hold the expression the script writes, thus they differ by platform — an mbed script writes `0xefe00` and a Zephyr script writes `((673792) - 0xe6)`. ``origin_value`` and ``length_value`` hold the number, and both are None for an expression that names a symbol, such as `ORIGIN(RAM) + LENGTH(RAM)`. A name that the link command defines with ``--defsym`` counts as a number: the STM32 Arduino core writes `LENGTH = LD_MAX_DATA_SIZE` and gets ``length_value`` 98304. The end of a region is ``origin_value + length_value``. ``memory`` is empty for a build system that records no linker script, such as Keil or IAR. A PlatformIO project records its link only in ``fw-context index --build``: SCons writes no file with the link command, thus the build asks ``pio run -t envdump``. An empty list for PlatformIO means that no build recorded the link yet, and ``fw-context index --build`` is the step. An empty list means "not recorded", never "no memory". ``defines`` holds…
| Name | Type | Req | Description |
|---|---|---|---|
| fast | boolean | – | When True (default), reuse the cached manifest hashes for the header check. Pass False to recompute them, which is far slower. |
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root directory. Auto-detected from CWD if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
No output schema declared.
No examples provided.
get_class_members ~847
Return all methods, fields, and nested types of a C/C++ class/struct — libclang-powered member table. Groups members by kind (method, constructor, field, enum, etc.), distinguishing class members from free functions across the entire codebase. Members are grouped by kind (method, constructor, destructor, field, enum, typedef, class, struct). Each member includes its signature, virtual flags, and source line. Works for C structs too — they just won't have methods. For inheritance hierarchy use ``get_inheritance_chain``. For individual method details use ``get_symbol_context``. Read-only. No side effects. Args: class_name: Class or struct name. E.g. ``'ModemManager'`` or ``'comm::MODEM'``. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Maximum members on one page (default 200, max 500). offset: Skip this many members. Reads the next page; ``page`` names the offset to use. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name. Returns: dict: {name, qualified_name, kind, file, line, members: {kind: [{name, qualified_name, signature, is_virtual, is_pure_virtual, line}]}, member_count (int — every member), page} ``page`` is the page notice ``{total, offset, shown, more, hint}``. A page holds the members in the order kind, name and…
| Name | Type | Req | Description |
|---|---|---|---|
| class_name | string | yes | Class or struct name. E.g. 'ModemManager' or 'comm::MODEM'. |
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum members on one page (default 200, max 500). |
| offset | integer | – | Skip this many members. Reads the next page of a large class. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
No output schema declared.
No examples provided.
get_file_map ~1,227
Fast structural map of all C/C++ symbols in a file grouped by kind — libclang-powered table of contents. Like a table of contents before reading a chapter: see what functions, classes, and enums a file defines at a glance. The index decides which file a path may reach: a path that no file of this build answers for is refused, and a header of the SDK that the build compiles is reachable like any file of the application. Pass a path relative to the project root (``src/main.cpp``) or just the filename (``main.cpp``). The exact path wins; else the path matches whole trailing path segments (``config.h`` matches ``src/config.h``, not ``hw_config.h``), a project file before a vendor file, then the shortest path. Returns symbols keyed by kind (function, method, class, struct, enum, ...). Each kind has count (total) and items (first N, default 30). Set max_per_kind=0 for unlimited, signatures=true for full sigs. Enum constants (``enum_constant``) are grouped into ``subgroups`` by parent enum. Each subgroup has ``name``, ``count``, and ``constants`` (list of ``{name, qualified_name, line, enum_value}``). The subgroup count reflects the real total even when ``max_per_kind`` limits the constants list. For detailed symbol information use ``get_symbol_context`` or ``lookup_symbol``. Read-only. No side effects. Use before reading a large file to orient yourself — see what functions, classes, and enums it defines. Args: file_path: Path relative to project root, or just the filename. project_root: Project directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. signatures: Include full function signatures. Default: False. max_per_kind: Max items per kind group (default 30, 0 = unlimited). With ``kind``, t…
| Name | Type | Req | Description |
|---|---|---|---|
| file_path | string | yes | Path to source file — relative to project root or just filename. |
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| kind | – | – | One symbol kind, e.g. 'function' or 'enum_constant'. Gives one page of the items of that kind. |
| max_per_kind | integer | – | Max items per symbol kind group (default 30, 0 = unlimited). With kind, the size of the page. |
| offset | integer | – | With kind: skip this many items of that kind. Reads the next page. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| signatures | boolean | – | Include full function signatures in output. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
No output schema declared.
No examples provided.
get_inheritance_chain ~1,109
Return the C++ inheritance chain for a class or struct — libclang-aware hierarchy. Resolves base/derived class relationships across all translation units, which single-file reading cannot do. Shows direct base classes (what this inherits from) and direct derived classes (what inherits from this), along with access level and virtual flag for each edge. When ``transitive=True``, walks the full hierarchy up to all ancestors and down to all descendants (bounded by ``max_depth``). Uses BFS with cycle detection to handle diamond inheritance. For class members use ``get_class_members``. For virtual method override chains use ``get_method_overrides``. Read-only. No side effects. Args: class_name: Class or struct name to get inheritance information for. E.g. ``'UART_DRIVER'`` or ``'comm::MODEM'``. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. transitive: When True, walk the full inheritance tree both up (ancestors) and down (descendants). Default: False (direct bases and derived only). max_depth: Maximum BFS depth for transitive walk (default 10). The schema holds it between 1 and 50, thus a number outside that range is REFUSED and not cut down to fit. limit: Maximum classes in ``all_bases`` and in ``all_derived`` on one page (default 100, max 500). Only with ``transitive=True``. offset: Skip this many classes in ``all_bases`` and in ``all_derived``. One offset pages the two lists together. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the tw…
| Name | Type | Req | Description |
|---|---|---|---|
| class_name | string | yes | Class or struct name to get inheritance information for. E.g. 'UART_DRIVER' or 'comm::MODEM'. |
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum classes in all_bases and in all_derived on one page (default 100, max 500). Only with transitive=True. |
| max_depth | integer | – | Maximum BFS depth for transitive walk (default 10). |
| offset | integer | – | Skip this many classes in all_bases and in all_derived. Reads the next page of a large hierarchy. Only with transitive=True. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| transitive | boolean | – | When True, walk the full inheritance tree both up (ancestors) and down (descendants). Default: False (direct bases and derived only). |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
No output schema declared.
No examples provided.
get_method_overrides ~729
Return C++ virtual method override information — libclang-powered vtable analysis. Resolves virtual dispatch across class hierarchies: shows which base-class method this overrides, and which derived-class methods override this one. Text-based search cannot resolve virtual dispatch across translation units. Shows what base-class method this method overrides, and what derived-class methods override this one. Built from the ``overrides`` table: the compiler records each override when ``fw-context index`` parses a translation unit, thus an alias of a parameter type and a base that is an instance of a class template do not hide one. For class-level inheritance, use ``get_inheritance_chain``. For symbol details, use ``get_symbol_context``. Read-only. No side effects. Args: method_name: Method name to get override information for. Use qualified name for disambiguation, e.g. ``'UART_DRIVER::write'``. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build. image: Image of the build: a separate program, such as the application or the bootloader. Give it when the build has an image name. Returns: dict: { name, qualified_name, kind, file, line, signature, overrides: [{usr, name, qualified_name, kind, file, line}], overridden_by: [{usr, name, qualified_name, kind, file, line}] } When a file of the answer changed after the las…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| method_name | string | yes | Method name to get override information for. Use qualified name for disambiguation, e.g. 'UART_DRIVER::write'. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
No output schema declared.
No examples provided.
get_project_info ~165
Return project metadata (name, type, root_path) for a project ID. Looks up the global project registry at ``~/.fw-context/projects.db``. Use this to identify a project from its UUID4 — find out what build system it uses, its name, and where it was last indexed. Read-only. No side effects. Args: project_id: Project ID (UUID4 hex) to look up. Returns: dict: {project_id, name, project_type, root_path, created_at, updated_at} or {"error": "..."} when the project_id is not registered. On failure the dict holds only ``error`` with the reason.
| Name | Type | Req | Description |
|---|---|---|---|
| project_id | string | – | Project ID (UUID4 hex) to look up. |
No output schema declared.
No examples provided.
get_project_status ~3,885
MANDATORY FIRST CALL for C/C++ projects. Return the health of the index of the project, and the list of its builds — check it before you use any other fw-context tool, and call it again while you wait for a reindex. Read-only with two exceptions, and it spawns no subprocess — the startup daemon thread and the file watcher own the background reindex. The exceptions: the last index run can leave a marker that says that the build is not there, and when the tool finds that build again, it removes the marker. It also removes a ``reindex.pid`` or a ``reindex.pending`` of a process that no longer runs. It creates no ``.fw-context`` file in a project that is not initialized. It takes no ``variant`` and no ``image``: it reports every build. For the detail of one build (its ``config_hash``, memory map, defines), call ``get_build_info``. ``builds`` lists every build of the index. A project of more than one build has no active build: every query tool must get the parts of one entry that are not empty, its ``variant``, its ``image``, or the two. Select the build from the task, and ask the user when the task does not identify one. Act on ``reindex_state`` of the build that the task needs, in ``builds`` (a project of one build has it at the top level too): * ``null`` — the index of the build is current. Continue. * ``"reindexing"`` or ``"pending"`` — the index of the build is not current, and an index run is active or scheduled. Wait, and call this tool again after about 30 s. Continue with the old index only when the user tells you to. * ``"not_scheduled"`` — the index of the build is not current, and no run updates it. Tell the user the command that the reasons name. * ``"failed"`` — the last index run failed. Give its text to the user: it names the command that repairs it. Each query answer carries the state of its build as ``index_state``, from quick checks only. A query thus can miss a changed header, a changed file that its answer does not name, or a new…
| Name | Type | Req | Description |
|---|---|---|---|
| fast | boolean | – | When True (default), reuse the cached manifest hashes for the header check. Both modes count modified files. Pass False to recompute the header hashes, which is far slower. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root directory. Auto-detected from CWD if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
No output schema declared.
No examples provided.
get_source ~1,499
Read a C/C++ function/method/enum/macro body using libclang exact extents — no guessing line numbers. Uses AST-precise {start, end} extents so you get exactly the function body. Generic file readers don't know where a function actually ends — libclang tracks exact {start, end} from the AST. The body is **ifdef-filtered**: a line of an inactive ``#if`` branch comes back blank, thus the text holds only the code that compiles for this build. The line numbers do not move. ``source_origin`` says where the text came from — ``"index"`` is the filtered copy, ``"disk"`` is the file itself and holds EVERY branch. A body reaches you from the disk when the file changed after the last index run (``stale_warning`` says so), or when the index holds no body for the symbol, such as a declaration. For enums, includes a ``constants`` array of the member constants with their values (at most 200; ``constants_total`` counts them all, and ``constants_hint`` names the call that pages them). For macros, returns kind="macro" with ``signature`` (``#define NAME`` or ``#define NAME(a, b)``), ``is_function_like``, ``value`` (the replacement text ALONE — the parameter list is not part of it) and ``expanded_value`` or ``expanded_values`` (the value in the build, see ``lookup_symbol``). For rich context (who calls this, what does it call) use ``get_symbol_context`` instead — it returns body, callers, and callees in a single call. For the full file, use ``read_file``. Read-only. No side effects. Args: name: Symbol name, or qualified name (``Class::method``) to select one symbol. Returns exact function body via libclang extent. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. variant: Variant of the…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| name | string | yes | Symbol name, or qualified name (Class::method) to select one symbol. Returns exact function body via libclang extent. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
No output schema declared.
No examples provided.
get_symbol_context ~1,611
Rich one-shot context for a C/C++ symbol: body, signature, the direct callers and callees. Answers "what does this do and how does it fit in the system?" in a single response — libclang powers the call graph, not regex. Falls back to macro display when the symbol is not found. Prefer this over ``get_source`` when you also need callers, callees, indirect call sites, or LLM analysis — all returned in a single call. If you only need the raw function body (no metadata), ``get_source`` is slightly faster. For transitive call-graph exploration use ``find_all_callers_recursive`` or ``find_callees_recursive``. The callers and callees include vendor/SDK code — the call graph naturally spans project and vendor boundaries in both directions (project → vendor API, vendor callback → project handler). Each list is cut (callers at 50, callees at 100), and its ``*_total`` says how many there are; ``*_hint`` names the tool that pages a cut list. The body is **ifdef-filtered**, the same as in ``get_source``: a line of an inactive ``#if`` branch comes back blank and the line numbers do not move. ``source_origin`` says whether the text is the filtered copy (``"index"``) or the file itself (``"disk"``, every branch present). Read-only. No side effects. Args: name: Symbol name. Returns body, signature, the direct callers and callees (each list with its total). project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answe…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| name | string | yes | Symbol name. Returns body, signature, the direct callers and callees (each list with its total). |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
No output schema declared.
No examples provided.
get_template_instances ~943
Find all template instantiations for a C/C++ class or function template — libclang template-aware lookup. Finds concrete instantiations spread across all translation units, each with its full type signature. Text-based search cannot resolve template specializations across translation units. Returns concrete instantiations of the template — each with its full type signature (e.g. ``Callback<void(int)>``). They are nested in the ``instances`` list of one dict that describes the template itself. Uses the ``template_usr`` column populated during indexing via libclang's ``cursor.specialized_template``. **Known limitation:** libclang's ``specialized_template`` does not reliably resolve implicit instantiations or template methods of template classes. Header-only templates (e.g. ``RingBuffer<T>``) may report zero instances even when used in the codebase. Explicit specializations and class/struct instantiations are detected more reliably than method-level instantiations. For finding the template declaration itself use ``lookup_symbol``. Read-only. No side effects. Args: template_name: Template name to find instantiations for. E.g. ``'Callback'`` or ``'mbed::Callback'``. project_root: Project root. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Maximum results (default 50, max 200). offset: Skip this many instances. Reads the next page; the page notice names the offset to use. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-context does not select a build. One query answers for ONE build.…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results (default 50, max 200). |
| offset | integer | – | Skip this many instances. Reads the next page of a template with many instances. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| template_name | string | yes | Template name to find instantiations for. E.g. 'Callback' or 'mbed::Callback'. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
get_vector_table ~2,995
Read the interrupt vector table, and say what services each interrupt. The vector table is how an interrupt reaches code. Nothing CALLS a handler — the hardware reads a slot and jumps — so a handler has no caller, and every other tool shows it as unreferenced. This tool reads the table itself, from the assembly the build compiles. Use it to answer "which interrupts does this firmware service", to find the handler for one interrupt, or to find the interrupts that reach the trap loop. **The slot number is the position in the table.** What that position means belongs to the architecture, not to the index. On Cortex-M slots 0 to 15 are the system exceptions and slot 16 + n is external interrupt n, so ``TIM2_IRQHandler`` in slot 44 is ``TIM2_IRQn = 28``. On other architectures the same position means something else. The ``status`` field says what services the interrupt: * ``"c"`` — a definition outside assembly, or a C declaration of a function that a library defines (then ``file`` is the header). Code runs. When the index also holds the weak definition that this one replaced, the row has ``overridden`` with its file and line. * ``"assembly"`` — an assembly definition that is not an alias. Assembly services the interrupt. * ``"unhandled"`` — an assembly name that is an alias (``.thumb_set``) of another symbol, and nothing overrode it. The row holds ``aliases``, the name, file and line of the alias target. A CMSIS startup file aliases each unserviced interrupt to ``Default_Handler``, which is an infinite loop. If the interrupt fires, the device stops. * ``"runtime"`` — the image holds that same alias, and the code installs a real handler into this slot by calling ``NVIC_SetVector``. A target that defines ``CMSIS_VECTAB_VIRTUAL`` keeps its vector table in RAM and fills it that way, so the interrupt IS serviced once the registering code has run — and not before it. The row holds ``installed``, one entry per call site with the…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum slots (default 400, max 1000). |
| offset | integer | – | Skip this many slots. Reads the next page of a long table. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| unhandled_only | boolean | – | Return only the slots with status 'unhandled' (an alias of a default handler, nothing installed at run time). |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
list_projects ~673
List all indexed firmware projects with their statistics. Read-only. No side effects. Use it to find another project; call ``get_project_status`` for the builds and the health of one project. ``indexed_at`` and ``first_indexed_at`` are UTC, in ``"YYYY-MM-DD HH:MM:SS"`` format — the same format that ``get_project_status`` returns. ``indexed_at`` is the time of the newest build. A project of several builds gets no counts here (``symbol_count``, ``file_count``, ``description`` and ``analysis`` are None): a file that two images compile is in the index of each, thus a sum counts shared code once for each build. ``get_project_status`` gives the counts of each build. ``analysis`` holds the ``project`` and ``vendor`` counts only. For the ``model``, ``analyze_vendor``, and ``complete`` fields, call ``get_build_info`` for that build. Args: project_root: Project root whose config names the index directory (``index.db_dir``). Omitted, the global config does. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. Returns: list of dicts, each with: project_id, name, root_path, build_system, symbol_count, file_count, indexed_at (str — UTC), description (str), first_indexed_at (str — UTC), schema_version, current_schema, reindex_needed (bool — the schema is outdated, the compile_commands.json of a build changed or is missing, or a build holds rows of an older row format; each (variant, image) build counts), status (str — "ready" or "reindex_needed"), db (path to SQLite database file), build_count (int — number of builds, each a (variant, image) pair), analysis (dict — LLM-analysis coverage {project: {analyzed, skipped, total}, vendor: {analyzed, skipped, total}}, or None when no build is indexed)…
| Name | Type | Req | Description |
|---|---|---|---|
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root whose config names the index directory; pass it to distinguish multiple indexed projects that keep separate index directories. Omitted = the global config. Every project in that director… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
lookup_symbol ~1,585
Look up a C/C++ symbol by name via libclang index — exact or prefix matching. Finds symbols text-based search can miss: build-conditional code, template instantiations, macro-expanded names. Macros are extracted via ``clang -dM -E`` during indexing so ``#ifdef``-conditional macros resolve correctly for the build of the query. Prefer this over search_code when you know the exact symbol name or a prefix (``uart_`` finds all UART symbols). Use search_code for keyword/concept search. *name* matches the name or the qualified name. A name with ``::`` that matches nothing is tried once more by its last part, kept where the qualified name ends with *name*: ``Foo::bar`` finds ``ns::Foo::bar``. Macros are searched only when no symbol matches. Read-only: yes. May auto-reindex stale files (non-blocking). Args: name: Symbol name (exact match) or prefix (set exact=False). E.g. 'uart_init' finds the exact function; 'uart_' finds all symbols starting with 'uart_'. project_root: Project directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. exact: True = exact name match, False = prefix LIKE match (default). limit: Maximum results of one page (default 50, max 100). offset: Skip this many results (default 0). A common method name lives in many classes — ``read`` and ``write`` match dozens of symbols — and this walks past the ones already seen. The page notice names the offset to use. The order is stable (a definition first, then the line, then the file and the USR), thus two pages never overlap and never skip a symbol. variant: Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the…
| Name | Type | Req | Description |
|---|---|---|---|
| exact | boolean | – | True = exact name match, False = prefix LIKE match (default). |
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results returned (capped at 100, default 50). |
| name | string | yes | Symbol name. Exact match if exact=True, prefix LIKE match otherwise. E.g. 'uart_init' or 'uart_'. |
| offset | integer | – | Skip this many results. Pages through a name that many classes share, such as 'read' or 'write'. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root directory. Auto-detected from CWD if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
read_file ~1,701
Read a C/C++ source file, one page at a time, with **ifdef-filtered** content — only code that actually compiles for the build of the query. Inactive ``#ifdef`` branches are replaced with blank lines (preserving original line numbers). Use this to read a file without leaving the fw-context ecosystem. Unlike generic file readers, this tool returns build-accurate content: code gated behind ``#ifdef BOARD_V2`` stays visible only when ``BOARD_V2`` is actually defined for this build. Line numbers match the original file — inactive branches appear as blank lines, and the text spans the whole file, thus ``lines`` is the length of the file. A blank line is an answer, and not a defect: it says that the line is in a branch the build does not take. When EVERY line of the file is blank, the dict carries ``all_lines_inactive`` and a ``warning`` — such a file holds code, and the build of the query compiles none of it. ``content`` is bare text by default and carries NO line-number prefix — unlike the ``source`` of ``get_source``, which numbers every line. Never count the lines here to find a number. Take it from a field instead: the ``match_lines`` of ``search_bodies`` or ``search_content``, the ``line`` / ``end_line`` of ``get_source`` and ``get_file_map``, or pass ``line_numbers=True`` and read the number off the line. ``start_line`` and ``end_line`` cut a window out of the file (1-based, both ends inclusive, 0 = no bound on that side). Reading around a known line costs a fraction of the whole file — 40 lines around a match instead of 2000 lines of a header. Without ``end_line`` the answer is ONE PAGE of at most 2000 lines from ``start_line`` on, and ``page`` holds the page notice: ``total`` is the number of lines of the file, ``offset`` the number of lines before the page, ``shown`` the lines on it. When ``more`` is true, the ``hint`` names the ``read_file`` call with the next ``start_line``. An explicit ``end_line`` gives the whole range that it names. A comment an…
| Name | Type | Req | Description |
|---|---|---|---|
| end_line | integer | – | Last line to return, 1-based inclusive. 0 = one page of at most 2000 lines. |
| file_path | string | yes | Path to source file — relative to project root or just filename. |
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| line_numbers | boolean | – | Prefix every line with its line number, like get_source. Default False (bare text). |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| start_line | integer | – | First line to return, 1-based inclusive. 0 = from the start of the file. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
No output schema declared.
No examples provided.
reindex_file ~1,661
Re-parse a single source file with libclang and update its symbols in the index. Not read-only — uses the exact compiler flags from ``compile_commands.json``. Use after editing a file to keep the index current without a full rebuild. Without ``variant`` and ``image`` the file is re-parsed in EACH build of the project that compiles it: an edit on disk changes the file for every build of the tree. A build that does not compile the file is named in ``builds_without_file``. With the two arguments of one build, as ``get_project_status`` lists them, only that build is re-parsed; a part of a pair gets an error that lists the builds. The call runs in a thread of the server and sends a notice each 5 s. It holds the lock of the query tools: another query waits 5 s, then gets "server busy". After 300 s the call returns an ``error``, and a part of the work can continue or fail. Call ``get_project_status`` for the state of each build, and repeat the call for a build that is not current. The answer holds no ``index_state``, except when a manual ``fw-context index`` run holds the index (see Returns). A source file must be listed in ``compile_commands.json``. A header is not listed there — compile_commands.json names translation units — so it is re-parsed through one unit of each build. A header goes to the unit that owns it in the index (the unit that wrote its rows in the last index run). Only a header without an owner goes to an including unit from the manifest. That answer describes a single compilation context, thus the result carries a ``warning``: another unit can see the header under a different set of ``#define`` values and still hold stale symbols. Only a full ``fw-context index`` covers every context. One unit and not all of them is a cost decision — an application header reaches a median of 3 units but as many as 266 on a real project, at tens of seconds each. Each re-parse writes only the files that the parsed unit owns, as an index run does. When a h…
| Name | Type | Req | Description |
|---|---|---|---|
| file_path | string | yes | Absolute or project-relative path to the file to re-parse. A source file must have an entry in compile_commands.json. A header is re-parsed through one translation unit that includes it, and the resu… |
| image | – | – | Image of the one build to re-parse: a separate program, such as the application or the bootloader. Give it when that build has an image name. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root directory. Auto-detected from cwd if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| variant | – | – | Variant of the one build to re-parse. Omit it and image to re-parse the file in each build that compiles it. A part of a pair gets an error that lists the builds. |
| with_analysis | boolean | – | When True (default), also regenerates the LLM symbol analysis and the embeddings — slower, because the two need a model. Set False for a fast update: the tool skips the two, and get_project_status th… |
No output schema declared.
No examples provided.
reset_index ~579
Delete the entire symbol index for a project. Not read-only — permanently deletes the SQLite database and WAL files. Call with ``confirm=False`` first (dry-run) to see what would be deleted. Re-index with ``fw-context index`` afterwards. Handles corrupt databases gracefully — you can delete a corrupt index without needing to open it first. Args: project_root: Project root directory. Auto-detected if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. confirm: Must be True to execute. Call without first as dry-run. Returns: dict: {project_root, db, project_id, action: "dry_run"|"deleted", message, build_count, symbol_count, indexed_at}. ``build_count`` counts the completed builds of the project, as ``get_project_status`` lists them. ``symbol_count`` counts every symbol row in the database, the rows that the reset deletes: also the rows of a build that an index run writes now, and of an older build of a pair that an interrupted run left behind. ``indexed_at`` is the time of the newest build. The three are present only when a build config is readable. A ``warning`` key means that the database is corrupt — the integrity check or a read of the database failed, thus the tool counts nothing and the three count fields are absent. On failure the dict holds only ``error`` with the reason. When another process holds the index of the project, the tool does nothing and ``error`` names it. A manual ``fw-context index`` run adds ``index_state: "reindexing"``: wait for its end, then call again. For ``fw-context analyze``: call again after the analysis. A background index run is no reason: the tool stops it, and the daemon runs it again after the tool.
| Name | Type | Req | Description |
|---|---|---|---|
| confirm | boolean | – | Must be True to execute. Call without confirm first as dry-run. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
No output schema declared.
No examples provided.
search_bodies ~2,310
Find patterns in the TEXT OF A DEFINITION — the code inside its extent. Searches **ifdef-filtered** text — only the code that compiles for the build of the query. A line of an inactive ``#if`` branch holds nothing, thus a pattern that lives only in a dead branch gives no result here. That empty answer is the correct one: the code does not compile. Searches the stored text of every definition (``is_definition=1``), and a definition is not only a callable. Measured on one project of 60,877 symbols, the text covers: - Callables — ``function``, ``method``, ``constructor``, ``destructor``, ``lambda``. Call patterns (``.attach(``, ``.rise(``, ``callback(&``), ISR registration, one ``case`` label of a long ``switch``. - Types — ``class``, ``struct``, ``union``, ``enum``, ``namespace``. An enum constant, a bit field, a member declaration such as ``InterruptIn _pin;`` — all inside the body of the type that holds them. - Definitions of data — ``varglobal``, ``varlocal``, ``typedef``. A table with a multi-line initializer is found by its content. A match on a type reports the type as the result, thus a query for one enum constant answers with the enum, and ``match_lines`` gives the line of the constant itself. **Only the text matches.** The query is bound to the stored body: a hit in the NAME, the signature, the docstring or the ``llm_analysis`` of a symbol is not a hit here. Measured on one project, ``sensor`` used to give 36 results of which 22 matched only through a summary that a model wrote — untrusted text that cannot be cited, and a ``_match_snippet`` with no match in it. Use ``search_code`` to reach a name or a concept. A column filter you write yourself (``summary : sensor``) overrides the binding. **When to use ``search_bodies`` and when ``search_code``:** - ``search_bodies`` — patterns in the code (what the code DOES or DECLARES): ``self test``, ``attach``, ``SELF_TEST``. - ``search_code`` — symbols by NAME (what the code IS): ``modem…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| kind | – | – | Optional kind filter: function, method, class, etc. |
| limit | integer | – | Maximum results of one page (default 20, max 100). |
| offset | integer | – | Skip this many results. Reads the next page of a pattern with many hits. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_only | boolean | – | Exclude vendor SDK code. When True, only application code. Default False. |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| query | string | yes | FTS5 search terms for the body of a definition. 1-3 words. E.g. 'attach', 'callback', 'rise'. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
search_code ~2,096
Find C/C++ symbols by name — searches function/class/enum NAMES. Searches symbol names, qualified names, signatures, docstrings, and pre-computed name tokens (CamelCase/snake_case split). Does NOT search function bodies — for patterns in code like ``.attach(``, interrupt handler registrations, callback attachments use ``search_bodies`` instead. Use when you know the concept but not the exact name (``"interrupt handler"``, ``"modem init"``). Prefer ``lookup_symbol`` when you already know the exact or prefix name. Results hold the metadata of each symbol — name, location, signature, docstring — not its implementation code. **FTS5 syntax:** - Every bare term gets a trailing ``*`` and the terms are OR-joined: ``modem init`` goes to FTS5 as ``modem* OR init*`` and answers with the symbols that hold EITHER word. ``search_bodies`` does the opposite — it takes the query literally, where a space is an AND. A query that holds a double quote, ``AND``, ``OR``, ``NEAR`` or a column filter goes to FTS5 as written. - ``init*`` matches init, init_uart, initialize (trailing wildcard) - ``"spi init"`` matches the exact phrase "spi init" - Do NOT use an underscore in a query. The tokenizer splits ``modem_init`` into two tokens and looks for them NEXT TO EACH OTHER. That is a phrase and not an AND, thus the query misses ``modem_parser_oob_init``. Measured on one firmware index, ``serial_write`` gave 1 result and ``serial write`` gave 200. Write ``modem init`` instead. - Punctuation is not searchable. The tokenizer drops it, thus ``.attach(`` becomes a phrase that looks for the token ``attach``. The query is repaired, never rejected. **Progressive relaxation:** when a step matches nothing, the next one runs. Six steps can run. Step 1 is the primary path and its results carry NO ``_fallback`` key; each step after it names itself there: 1. FTS5 with the ``kind`` filter. No ``_fallback`` key. 2. FTS5 without the kind, when the kind matched nothing;…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| kind | – | – | Optional kind filter: function, method, constructor, destructor, class, struct, union, enum, enum_constant, typedef, varglobal, varlocal, variable, field, namespace, label, lambda. |
| limit | integer | – | Maximum results of one page (default 20, max 100). |
| offset | integer | – | Skip this many results. Reads the next page of a topic that many symbols carry. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_only | boolean | – | Exclude vendor SDK code. When True, only application code. Default False. |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| query | string | yes | FTS5 search terms. 1-3 words, omit underscores. E.g. 'modem init' not 'modem_init'. Supports trailing wildcard 'modem*'. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
search_content ~1,445
Find patterns in FULL file content — the whole file, not only the text that belongs to a definition. Searches **ifdef-filtered** file text — only code that actually compiles for the build of the query. Inactive ``#ifdef`` branches are replaced with blank lines (preserving original line numbers). A pattern that lives only in a dead branch therefore gives no result, and that empty answer is the correct one: the code does not compile. Covers the text that belongs to no definition, which is what ``search_bodies`` cannot see: ``#include``, ``#define``, ``#ifdef``, ``extern "C"``, and a comment or declaration at file scope. It covers the text of definitions too. To find a symbol by NAME (``modem init``, ``interrupt handler``), use ``search_code``. **Not a fallback of ``search_bodies`` — its complement.** The two answer different questions and reach different text: - ``search_bodies`` answers WHICH DEFINITION holds the pattern, and takes the query literally (no wildcard, space = AND). - ``search_content`` answers WHICH FILES the topic touches, and widens the query: every term gets a trailing ``*`` and the terms are OR-joined. The wider query reaches text the literal one misses — measured on one project, ``SELF_TEST`` found 6 files here and the same word found 5 through ``search_bodies``, the extra file holding the comment ``Self tester``. For the footprint of one feature, run both. Results are file-level — one entry per matching file, with ``match_lines`` for the lines that hold a query term. ``project_only=True`` filters to ``is_project = 1`` files; the default False includes the vendor SDK files. When ``files_fts`` is missing (legacy index), falls back to LIKE search on ``files.content`` — results include ``_fallback: "like"`` and no snippet highlighting. Run ``fw-context index`` to upgrade. The LIKE search splits the query on spaces and underscores and needs EVERY word as a substring (AND, not OR). Read-only: yes. Requires the FTS5 index with…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results of one page (default 20, max 100). |
| offset | integer | – | Skip this many results. Reads the next page of a topic that many files touch. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_only | boolean | – | Exclude vendor SDK code. When True, only application code. Default False. |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| query | string | yes | FTS5 search terms for full file content. 1-3 words. E.g. 'InterruptIn', 'extern C'. Bare multi-word = OR-joined. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
semantic_search ~1,898
Semantic search using pre-computed libclang symbol embeddings. Finds symbols by meaning, not by text — matches concepts even when query words don't appear literally in the code. Uses cosine similarity over variable-dimension embeddings generated during ``fw-context index``. Dimensions vary by model: mxbai-embed-large → 1024, qwen3-embedding:0.6b → 1024, qwen3-embedding:4b → 2560, qwen3-embedding:8b → 4096. **When to prefer over search_code:** When you're describing a *concept* rather than searching for a known keyword. Examples: - ``"motor overcurrent protection"`` finds the current-limit and the PWM-shutdown functions even though "overcurrent" doesn't appear in their names. - ``"cell modem"`` finds the AT command parser and the ``Modem*`` classes. - ``"data logging"`` finds ``log_write`` and the flash append functions. - ``"power consumption"`` finds ``get_load_power`` and INA260 class. **When to prefer search_code instead:** When you know the exact keyword or symbol name (``"fram_write"``, ``"cbor encode"``). FTS5 is faster and more precise for lexical matches. **Threshold guidance (mxbai-embed-large model):** - ``0.50`` — exploratory: more results, lower precision - ``0.55`` — balanced (~1000 results) - ``0.60`` — precise: ~175 avg, high precision (default) - ``0.65`` — strict: few results, may miss relevant symbols **Source-aware ranking:** the similarity of a project symbol is multiplied by 1.2, and the similarity of every other symbol by 0.85. The index marks each file as project code or not, thus the two tiers are all there are. The multiplied score sets the order. ``_similarity`` in the result holds the raw cosine similarity, thus it is on the same scale as ``threshold`` and never above 1.0. **Requires** ``[llm] enabled = true``, embeddings in the index, and for an Ollama embedding model a running Ollama server at the ``url`` of the profile of the embeddings (``[llm] embed_profile``, else the Ollama profile of the chat, else ``http://localhost:1…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results on one page (default 20). Held between 1 and 100. |
| offset | integer | – | Skip this many results. Reads the next page of the symbols above the threshold. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| query | string | yes | Natural language description, 5-15 words. E.g. 'motor overcurrent protection' or 'how does the modem connect?'. |
| threshold | number | – | Minimum cosine similarity (0.0-1.0). Default 0.60. Use 0.55 for exploratory, 0.50 for broad search. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
smart_search ~1,326
Natural-language search: an LLM generates FTS5 keywords, then searches the libclang index. Finds concepts by meaning rather than exact text match. Prefer this when you don't know the exact keywords and want to describe what you're looking for ("how does the modem connect?", "handle BLE pairing failure"). Read-only: yes. Slow (10-30 s) — delegates to the full ``SMART_SEARCH`` pipeline (translate → rough_search → llm_query → fts5_search → refine → embedding → adaptive_fusion → deduplicate → expand_context → format). Multi-phase approach: 1) Translate non-English queries 2) Rough search to gather sample symbols for naming conventions 3) LLM sees those samples + query and generates FTS5 terms 4) FTS5 search with generated terms 5) Refine: LLM checks results and course-corrects query terms 6) Semantic embedding search (cosine similarity re-rank) 7) Deduplicate, score, and format results **When to prefer over search_code:** When you don't know the exact keywords and want to describe what you're looking for ("how does the modem connect?", "handle BLE pairing failure"). **Fallback:** When LLM is unavailable, falls back to direct FTS5 search with word-split terms from the query. When the LLM call or the embedding step fails, a metadata dict gives the reason in ``warning`` or ``detail``. Args: query: Natural language description of what you're looking for. Be specific — 5–15 words works best. project_root: Project root directory. Auto-detected from CWD if omitted. project: Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root path. Give one of the two, not both. limit: Maximum number of results on one page (default 20, max 100). The search itself always ranks up to 100 symbols. offset: Skip this many results of the previous search of the same query. 0, the…
| Name | Type | Req | Description |
|---|---|---|---|
| image | – | – | Image of the build: a separate program, such as the application or the bootloader. On a project of more than one build, give it when that build has an image name, as the refusal lists it. |
| limit | integer | – | Maximum results on one page (default 20). Held between 1 and 100. |
| offset | integer | – | Skip this many results of the previous search of this query. 0 (the default) is a new search. |
| project | – | – | Project name or project_id — call list_projects to get them. Use it to ask about a project that is not the project of the current directory. It is an alternative to project_root, which takes a root p… |
| project_root | – | – | Project root. Auto-detected if omitted. This field also accepts a project name or a project_id, but project is the clear field for those. |
| query | string | yes | Natural language description, 5-15 words. E.g. 'how does the modem connect?' or 'handle BLE pairing failure'. |
| variant | – | – | Variant of the build (a board, or a PlatformIO environment). On a project of more than one build, give the arguments of one build as the refusal lists them: the variant, the image, or the two. fw-con… |
| Name | Type | Req | Description |
|---|---|---|---|
| result | array | yes | – |
No examples provided.
How do I install the io.github.turbyho/fw-context-mcp server?
io.github.turbyho/fw-context-mcp runs locally as a PyPI package, launched with uvx fw-context-mcp. Ready-made configuration for Claude, Cursor, VS Code, Codex and 5 more is on this page, copied from each client's own documentation.
pypi · fw-context-mcp
claude mcp add turbyho-fw-context-mcp -- uvx fw-context-mcp
What is the io.github.turbyho/fw-context-mcp server?
io.github.turbyho/fw-context-mcp is listed in the public MCP registry as io.github.turbyho/fw-context-mcp. Build-aware code intelligence for embedded C/C++ firmware, libclang, FTS5, call graphs, 37 tools. This page covers its PyPI package (fw-context-mcp).
Is the io.github.turbyho/fw-context-mcp server safe to use?
io.github.turbyho/fw-context-mcp scores 59 out of 100 on VerifyMCP. We found no known CVEs affecting it as of 21 November 2026. That is a record of what we were able to check automatically, not an endorsement. The category breakdown on this page shows every signal behind the number, including the ones we could not confirm.
What tools does the io.github.turbyho/fw-context-mcp server expose?
io.github.turbyho/fw-context-mcp exposes 37 tools: check_dependencies, check_ollama, configure_llm, get_build_info, get_project_info, and 32 more. Their descriptions and schemas cost roughly 50,984 tokens of context every time the server is loaded.
Is the io.github.turbyho/fw-context-mcp server still maintained?
io.github.turbyho/fw-context-mcp is still listed as active in the MCP registry. We last reached this channel on 21 November 2026. Those dates come from our own scans of the registry and the channel itself, not from anything the publisher announced.
What licence is the io.github.turbyho/fw-context-mcp server under?
io.github.turbyho/fw-context-mcp declares the MIT AND Apache-2.0 WITH LLVM-exception licence, which is OSI-approved. That covers the source only, and says nothing about the cost of any service it calls.
What did VerifyMCP test on the io.github.turbyho/fw-context-mcp server?
VerifyMCP ran 15 checks on io.github.turbyho/fw-context-mcp, covering Known CVEs, Install scripts, Dependency health, Source repository and 11 more. One item could not be completed, a gap on our side rather than a finding about io.github.turbyho/fw-context-mcp: Malware scan. Endpoint Security and Transport & Reachability do not apply to a PyPI package, so they were not tested. The score does not measure everything, and the scoring documentation lists what it leaves out.