fw-context-mcp

技能简介

fw-context-mcp 是一款专为嵌入式 C/C++ 固件设计的构建感知代码智能 MCP 服务器。它通过解析 compile_commands.json 编译数据库和 libclang AST，为 AI 编码智能体构建持久化的语义索引，使其能够精确理解当前固件构建配置下的程序结构，而非依靠重复文件扫描和文本搜索来猜测程序行为。

核心能力

• 构建感知索引：从编译数据库自动提取符号定义、调用关系、回调链和中断处理程序信息
• 间接调用追踪：追踪函数指针赋值和间接调用站点，识别固件中常见的动态分发路径
• 增量索引构建：持久化索引仅重处理变更的翻译单元，初次构建后可增量更新
• 多构建系统支持：支持 Zephyr、PlatformIO、Mbed OS、Arduino、ESP-IDF、CMake、Makefile 等主流嵌入式构建系统
• MCP 协议暴露：通过 37 个 MCP 工具向 AI 智能体提供结构化语义查询接口
• 上下文压缩：将大量文件扫描转化为精炼的目标信息，减少 token 消耗
• 案例验证：在 67,000 行 C/C++ 的 nRF52/Mbed OS 项目中验证，节省约 580 万 token

安装配置

前置条件：

• Python 3.11 或更高版本
• libclang 库（需预装）
• 支持生成 compile_commands.json 的构建系统
• MCP 兼容的 AI 编码智能体（如 Claude Code 或 OpenCode）

安装步骤：

1. 通过 pip 安装：pip install fw-context-mcp
2. 或克隆源码安装：git clone https://github.com/turbyho/fw-context-mcp.git ~/.fw-context/src && cd ~/.fw-context/src && make install
3. 在固件项目根目录运行初始化：fw-context init
4. 构建并索引固件：fw-context index --build

IDE/智能体集成： 运行 fw-context init 后自动检测当前项目的 MCP 兼容编码智能体并注册，重启编码智能体即可开始使用。

使用步骤

1. 进入固件项目目录：cd /path/to/your/firmware
2. 初始化索引环境：确保项目已生成 compile_commands.json，运行 fw-context init
3. 构建索引：fw-context index --build，等待索引完成
4. 重启 AI 编码智能体：让智能体加载 MCP 服务器
5. 查询固件结构：通过自然语言向智能体提问（如「哪些代码会影响这个 API 变更？」）
6. 增量更新：代码变更后运行 fw-context index 增量更新，无需全量重建

适用场景

• 固件代码评审：AI 智能体评审固件提交时，可精确追踪变更的传递影响，而非误评无关文件
• 中断与回调链追踪：从 ISR（中断服务程序）追溯到应用层代码的执行路径
• API 影响分析：变更函数签名或数据类型前，精确列出所有调用方和受影响路径
• 陌生固件导航：快速理解陌生固件项目的组织结构和关键符号关系
• 死代码发现：识别未被引用的符号和死代码候选
• 构建差异分析：识别源码树中哪些文件属于当前活动构建配置，哪些被预处理器排除

适用人群

• 从事嵌入式 C/C++ 固件开发的工程师
• 使用 AI 编码智能体处理固件任务的开发者
• 需要对固件变更进行安全审计和合规评审的团队
• 维护大型嵌入式代码库（Zephyr、ESP-IDF 等）的 contributors

工作原理

fw-context 的核心流程是「编译数据库 → libclang AST 解析 → 语义索引 → MCP 工具暴露」：

1. 编译数据库读取：读取项目生成的 compile_commands.json，获取编译器标志、宏定义、目标平台等构建配置
2. libclang AST 解析：对每个翻译单元（.c/.cpp 文件）进行 AST 解析，提取符号定义、引用关系、函数指针赋值、回调注册等语义信息
3. 语义索引构建：将解析结果存入 SQLite FTS5 索引数据库，包含符号表、调用图、文件内容宏过滤版本等
4. MCP 协议暴露：通过 MCP 服务器的 37 个工具（如 get_symbol_definition、get_callers、get_references 等）向 AI 智能体提供查询接口
5. 智能体查询循环：智能体发送结构化查询 → MCP 服务器返回精炼语义上下文 → 智能体基于上下文推理并更新下一步计划

关键差异于传统 LSP（如 clangd）：clangd 服务编辑器交互（跳转、补全、诊断），fw-context 服务 AI 智能体的持久化、递归、跨文件的语义理解任务。

官方链接

• PyPI：https://pypi.org/project/fw-context-mcp/
• GitHub：https://github.com/turbyho/fw-context-mcp
• 文档：https://github.com/turbyho/fw-context-mcp/blob/main/docs/README.md