Fw Context Mcp

fw-context

組み込み C／C++ ファームウェアを扱う AI コーディングエージェント向けの、ビルドを考慮したコードインテリジェンスです。

fw-context は、compile_commands.json と libclang AST から永続的なセマンティックインデックスを構築し、MCP を通じてコーディングエージェントに公開します。ファイルの読み込みやテキスト検索を繰り返してファームウェアの構造を再構築する代わりに、エージェントは1回のビルドで生成されるプログラム構造を問い合わせることができます。

エージェントが次のような質問に答えるのに役立ちます。

• このビルドで有効な実装はどれですか？
• この関数を直接または間接的に呼び出しているのはどれですか？
• このコールバックはどこで登録されていますか？
• この呼び出し箇所に到達する可能性がある関数ポインターの代入はどれですか？
• プリプロセスによって除外されるコードはどれですか？
• この API を変更すると、どこに影響しますか？
• ISR からアプリケーションコードへの実行フローはどのようになっていますか？

目指しているのは、モデルにソースコードをさらに与えることではありません。現在のタスクに必要な、最小限で有用な、ビルドを考慮したコンテキストを与えることです。

実際のファームウェアレビューでの結果

同梱のファームウェアレビューのケーススタディでは、約67,000行の C／C++ を含む nRF52／Mbed OS プロジェクトで fw-context を使用しました。

• 8つの並列サブエージェントで115個の変更ファイルをレビュー
• メモリー安全性、並行処理、API の使用、デッドコードに関する19件の指摘
• 通常のテキスト検索だけでは得られないセマンティックな関係に依存する9件の指摘
• fw-context のクエリで使用したコンテキストは約54,000トークン
• 同等の広範な grep とファイル読み込みのワークフローでは、推定580万トークン

ケーススタディには、レビュー結果、手法、ツールごとのトークン分析が含まれているため、ブラックボックスのベンチマークとして扱うのではなく、主張を検証できます。

クイックスタート

前提条件

• Python 3.11 以降
• libclang
• compile_commands.json を生成できるプロジェクト
• Claude Code や OpenCode などの MCP 対応コーディングエージェント

コアインデックスには Ollama は不要です。シンボル、全文検索、呼び出しグラフ、ソースは libclang と SQLite のみから取得されます。デフォルト設定では、Ollama はベクトル埋め込み（semantic_search、smart_search の再ランク付けステップ）とシンボル分析（explain_symbol、シンボルの説明）も計算します。Ollama がない場合、これらの機能は全文検索にフォールバックするか、生のプロンプトを返します。また、ステータスツールによって埋め込みが完了していないことが示されます。埋め込みモデルも LLM も使用しない場合は、[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 を登録します。

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

ファームウェアをビルドしてインデックスを作成します。

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

その後、コーディングエージェントを再起動し、プロジェクトについて質問してください。インデックスは永続的かつ増分的です。初回実行後は、インデックス全体を再構築するのではなく、変更された翻訳単位のみが再処理されます。

プラットフォーム固有の設定と対応するビルドシステムについては、クイックスタートとインストールガイドを参照してください。

fw-context が変えること

セマンティックなプロジェクトインデックスがない場合、AI コーディングエージェントは通常、ファイルを開き、名前を検索し、インクルードをたどり、ビルドに暗黙的に含まれる関係を推測するところから始めます。組み込みファームウェアでは、この再構築がタスクの大部分を占めることがよくあります。

この方法では、次のような問題が予測されます。

• 問い合わせ対象のビルドに含まれていないソースファイルを確認してしまう
• 誤ったプリプロセッサ分岐をたどってしまう
• コールバックの登録や間接呼び出しを見落とす
• 無効なドライバーやプラットフォーム実装を選んでしまう
• テキスト検索で見つかった宣言を、到達可能なコードとして扱ってしまう
• ベンダーコードや無関係なファイルにコンテキストを大量に消費する

fw-context は、こうした再構築の多くを再利用可能なコンパイラー由来のインデックスに移します。エージェントは、ソースツリー全体を読み込むことなく、正確なシンボル本体、呼び出し元、呼び出し先、参照、アクティブなマクロ、コールバックの関係、継承関係など、対象を絞った情報を取得できます。

組み込みファームウェアが異なる理由

多くのアプリケーションレベルのプロジェクトでは、リポジトリに表示されるソースファイルと実行されるプログラムは、かなり近いものです。一方、組み込み C および C++ プロジェクトでは、ソースツリーと生成されるプログラムの間に、はるかに大きな隔たりがあることがよくあります。

アクティブなファームウェアは、次のような要素に依存します。

• コンパイラーフラグとプリプロセッサ定義
• ターゲット、ボード、製品の構成
• インクルードパスと生成されたヘッダー
• Kconfig と Devicetree の選択
• 選択されたドライバーおよび HAL の実装
• テンプレート、継承、仮想ディスパッチ
• コールバック、割り込みハンドラー、関数ポインター
• ベンダー SDK と RTOS の構成

そのため、リポジトリには同じサブシステムに対する複数の有力な実装が含まれていても、選択されたターゲット向けにコンパイルされるのはそのうちの 1 つだけ、という場合があります。エージェントは、まずビルドコンテキストを正しく再構築しなければ、誤った実装について説得力のある推論をしてしまう可能性があります。

仕組み

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 エージェントが繰り返し利用できるよう最適化された、簡潔で高水準なクエリとして公開します。

代表的なユースケース

• ビルドを考慮したファームウェアコミットのレビュー
• 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 は clangd に取って代わるものではありません。

fw-context は、異なるインターフェースとワークロードを対象としています。

• エージェントによる繰り返しのクエリに備えて用意する、プロジェクト全体の永続的なデータ
• コンパクトで構造化されたセマンティックコンテキストを返す MCP ツール
• 呼び出し元の再帰的な検索と影響分析のクエリ
• コールバックと関数ポインターの関係モデリング
• 対象を絞った取得に適した、アクティブなソースコードの内容
• プロジェクト／ベンダーの分類と、ファームウェアに特化したワークフロー
• 繰り返しの分析で共有できる、任意のキャッシュ済み情報拡充

対話的な編集には clangd を使用してください。AI エージェントが、ビルド済みファームウェアのレビュー、理解、移動に再利用できる構造化コンテキストを必要とする場合は、fw-context を使用してください。

ドキュメント

• クイックスタート
• インストール
• 設定
• MCP ツールリファレンス
• MCP サーバーに関する注記
• ファームウェアレビューのケーススタディ

プロジェクトの成熟度

fw-context は実用可能で、実際の組み込み C および C++ プロジェクトで使用されていますが、インターフェースとインデックス作成の動作は現在も進化しています。バグ報告、誤った結果、未対応のビルド設定、再現可能なエッジケースは、特に有益です。

このプロジェクトはローカルファーストです。任意の外部サービスを明示的に設定しない限り、ソースコードとコンパイラーから導出されたインデックスは開発者のマシン上に保持されます。

背景

このプロジェクトは、AI を活用したファームウェア開発で繰り返し発生する問題をきっかけに生まれました。コーディングエージェントは、エンジニアリング上の問い自体を考えるよりも、実行中のプログラムを再構築することに多くの労力を費やしがちでした。

詳しい説明については、以下をお読みください。 AI コーディングエージェントが組み込みファームウェアの分析で同じ間違いを繰り返す理由

---

コンパイラーはすでにプログラムを再構築しています。コーディングエージェントにも活用させましょう。