Fw Context Mcp

fw-context

为使用嵌入式 C 和 C++ 固件的 AI 编码 Agent 提供感知构建的代码智能。

fw-context 从 compile_commands.json 和 libclang AST 构建持久化语义索引，然后通过 MCP 将其提供给编码 Agent。Agent 无需反复读取文件和搜索文本来重建固件，就能查询一次构建所生成的程序结构。

它可以帮助 Agent 解答以下问题：

• 此次构建启用了哪个实现？
• 哪些代码会直接或间接调用此函数？
• 此回调注册在何处？
• 哪些函数指针赋值可能到达此调用点？
• 哪些代码被预处理排除？
• 如果此 API 发生变化，会影响哪些内容？
• 执行如何从 ISR 流转到应用代码？

我们的目标不是向模型提供更多源代码，而是为当前任务提供所需的最精简且感知构建的上下文。

真实固件审查的结果

在随附的固件审查案例研究中，fw-context 被用于一个包含约 67,000 行 C 和 C++ 代码的 nRF52/Mbed OS 项目：

• 8 个并行子 Agent 审查了 115 个变更文件
• 在内存安全、并发、API 使用和死代码方面发现 19 个问题
• 其中 9 个问题依赖于仅靠常规文本搜索无法获取的语义关系
• fw-context 查询使用了约 54,000 个上下文 Token
• 使用等效的广泛 grep 和文件读取工作流，预计需要 580 万个 Token

案例研究包含审查结果、方法和各工具的 Token 分析，便于读者检验这些结论，而不是将其视为黑盒基准测试。

快速开始

前置条件

• Python 3.11 或更高版本
• libclang
• 能够生成 compile_commands.json 的项目
• 支持 MCP 的编码 Agent，例如 Claude Code 或 OpenCode

核心索引可不依赖 Ollama：符号、全文搜索、调用图和源代码都仅由 libclang 和 SQLite 提供。在默认配置下，Ollama 也会计算向量嵌入（semantic_search、smart_search 的重排步骤）和符号分析（explain_symbol、符号描述）。不使用 Ollama 时，这些功能会回退到全文搜索或返回原始提示词，状态工具也会提示嵌入尚未完成。不使用嵌入模型和大模型时，请设置 [llm] enabled = false。请参阅 Ollama。

通过 pip 安装（推荐）

pip install fw-context-mcp

安装当前源代码版本

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

将 fw-context 注册到项目中检测到的受支持编码 Agent：

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

构建固件并建立索引：

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

然后重启编码 Agent，并向它提问有关项目的问题。索引持久化且采用增量更新；首次运行后，系统会重新处理发生变化的翻译单元，而不是重建整个索引。

请参阅快速开始和安装指南，了解特定平台的设置方法和支持的构建系统。

fw-context 带来的改变

如果没有语义项目索引，AI 编码 Agent 通常会先打开文件、搜索名称、跟踪包含关系，并尝试推断构建过程中隐含的关系。在嵌入式固件项目中，这种重建往往占据任务的大部分工作。

这种方法可能会导致一些常见问题：

• 审查不属于所查询构建的源文件
• 跟踪到错误的预处理分支
• 遗漏回调注册和间接调用
• 选中未激活的驱动程序或平台实现
• 将通过文本搜索找到的声明视为可达代码
• 在供应商代码和无关文件上消耗大量上下文

fw-context 将大部分重建工作转移到可重复使用的编译器派生索引中。Agent 可以请求精确的符号主体、调用方、被调用方、引用、有效宏、回调关系、继承边以及其他有针对性的信息，无需读取整个源代码树。

嵌入式固件有何不同

在许多应用级项目中，仓库中可见的源文件与实际执行的程序相差不大。而在嵌入式 C 和 C++ 项目中，源代码树与最终程序之间往往存在更大的差异。

当前有效的固件取决于以下因素：

• 编译器标志和预处理器定义
• 目标、开发板和产品配置
• 包含路径和生成的头文件
• Kconfig 和 Devicetree 选项
• 选定的驱动程序和 HAL 实现
• 模板、继承和虚函数分派
• 回调、中断处理程序和函数指针
• 供应商 SDK 和 RTOS 配置

因此，仓库中可能包含同一子系统的多个可行实现，但针对所选目标，实际编译的只有一个。如果 Agent 未能先正确重建构建上下文，就可能对错误的实现作出看似合理的分析。

工作原理

fw-context 使用构建工具和语言服务器所用的同一编译数据库为项目建立索引。

flowchart LR
    CCJ[compile_commands.json] & SRC[(source files)] --> LIBCLANG[libclang<br/>AST parser]
    LIBCLANG --> SYMBOLS[symbols<br/>name, kind, USR<br/>signature, ifdef-filtered source body<br/>docstring, tokens] & FILES[files<br/>path, language<br/>ifdef-filtered content<br/>project/SDK sources] & REFS[refs &amp; call graph<br/>fp_assignments<br/>indirect_call_sites] & INHERIT[inheritance<br/>&amp; overrides<br/>virtual dispatch] & MACROS[macros<br/>params, value<br/>&amp; expanded value<br/>FTS5 searchable] & ENRICH[optional enrichment<br/>embeddings &amp; summaries<br/>hotspot cache]
    SYMBOLS & FILES & REFS & INHERIT & MACROS & ENRICH --> MCP[MCP server<br/>37 tools]
    MCP --> LLM[AI coding agent]

索引包含：

• 符号定义、签名、源代码范围和文档
• 引用、直接调用边和递归调用方路径
• 函数指针赋值和间接调用位置
• 回调注册和调用关系
• 生效且经过预处理过滤的文件内容
• 宏参数列表、替换文本和展开值
• 继承、重写和虚函数分派关系
• 翻译单元以及项目和供应商元数据
• 可选的嵌入向量和由 LLM 生成的摘要

MCP 服务将这些信息作为精简的高层查询提供，便于 AI Agent 重复使用。

典型用例

• 基于构建配置审查固件提交
• 跟踪跨 ISR、工作队列、任务和回调的执行过程
• 查找 API 的所有调用方和引用
• 确定当前构建选用的实现
• 更改函数签名或数据类型前进行影响分析
• 无需通读完整文件即可了解陌生固件
• 查找可能的死代码和未引用符号
• 区分项目代码与 SDK 及供应商代码
• 减少发送给模型的无关源代码文本

fw-context 支持 Zephyr、PlatformIO、Mbed OS、Arduino、ESP-IDF、通用 CMake、基于 Makefile 的项目，以及能够提供编译数据库的自定义构建。文档还介绍了 Keil、IAR、STM32CubeIDE 和 TI Code Composer Studio 的其他配置方法。

为什么不直接使用 clangd 或其他 LSP？

clangd 已经会使用编译命令，并且非常适合诊断、代码补全、跳转到定义和引用查找等面向编辑器的任务。fw-context 并不取代它。

fw-context 面向的是不同的接口和工作负载：

• 为重复的 Agent 查询准备的持久化项目级数据
• 返回紧凑、结构化语义上下文的 MCP 工具
• 递归调用方和影响分析查询
• 回调和函数指针关系建模
• 适合定向检索的活动源代码内容
• 项目／供应商分类和固件专用工作流
• 可选的缓存增强信息，可供重复分析共享

交互式编辑时使用 clangd。AI Agent 需要结构化、可复用的上下文来审查、理解或浏览已构建固件时，使用 fw-context。

文档

• 快速入门
• 安装
• 配置
• MCP 工具参考
• MCP 服务说明
• 固件审查案例研究

项目成熟度

fw-context 已具备实用功能，并已用于真实的嵌入式 C 和 C++ 项目，但其接口和索引行为仍在不断演进。错误报告、错误结果、不受支持的构建配置以及可复现的边缘情况尤其有价值。

本项目优先在本地运行：除非明确配置了可选的外部服务，否则源代码和编译器生成的索引都会保留在开发者的计算机上。

背景

这个项目源于 AI 辅助固件开发中反复出现的一种问题：编码 Agent 经常花费更多精力重建当前运行的程序，而不是思考工程问题本身。

如需了解更详细的说明，请阅读： 为什么 AI 编码 Agent 分析嵌入式固件时总会犯同样的错误

---

编译器已经重建了你的程序。让编码 Agent 利用它。