neosyn-fpga-mcp

neosyn-fpga-mcp

AI エージェントに C⏚ FPGA ツールチェーンを提供する MCP サーバーです。 モデルがハードウェアを記述し、サーバーが実際のコンパイラーでコンパイル、シミュレーション、合成チェックを行い、モデルが対処できる構造化された診断情報を返します。

ここが重要な違いです。Verilog を求められた LLM は、ビルドできない、合成できない、あるいは何もない状態へひそかに畳み込まれるコードを自信満々に出力します。このサーバーでは、各ステップを人間が使うものと同じコンパイラーで判定します。

次の 2 つが連携して動作します。

1. cg_context.md — ナレッジパックです。システムプロンプトとして読み込むと、モデルが C⏚ をそれらしく記述できるようになります。メンタルモデル、型、ポート、構造体／列挙型／ジェネリック、標準ライブラリ、そして最初の草稿を台無しにする落とし穴が含まれています。
2. MCP サーバー — コンパイラーをツールとして提供することで、モデルが記憶を頼りにするのではなく、自身の出力を検証できるようにします。

ナレッジが良い初稿を生み、コンパイラーをループに組み込むことで正しいものになります。どちらもモデルに依存しません。stdio-MCP ホスト（Claude Desktop、Claude Code、Cursor、Cline）であれば動作し、コンテキストパックはどの LLM とも使えます。

なぜファインチューニングではないのですか？ C⏚ は公開コードが少ないニッチな言語で、リリースごとに機能が追加されます。ファインチューニング済みモデルは高価で、すぐに古くなります。コンテキスト内のナレッジと検証ループなら再トレーニングのコストがかからず、コンパイラーの進化に合わせて言語に追随し、記憶ではなくコードを実行することで精度が高まります。

インストール

pip install neosyn-fpga-mcp

次に、C⏚ コンパイラーの jar を指定します。

export CG_JAR=/path/to/cg-language-server.jar

jar を入手する方法は 2 つあります。

• オープンソース — cg-compiler releases のビルド済み jar を入手するか、ソースからビルドします。
• 商用 — インストール済みの Neosyn C⏚ extension に含まれる jar を使います。高速なバイトコードシミュレーターと VHDL 出力が追加されます。 ライセンスファイルが必要です。NEOSYN_CG_LICENSE にそのファイルを指定するか、拡張機能が使うデフォルトのパスに保存してください。ライセンスファイルがない場合、すべてのツールは実行されず、ライセンスの問題を報告します。

cg_capabilities は、どちらを使っているかと、その機能を推測ではなく実際に調べて報告します。

要件

• Python 3.10 以降
• Java 17 以降が PATH 上にあること — jar のバイトコードは 17 を対象としています。
• 任意： cg_synth 用に yosys が PATH 上にあること（$YOSYS で上書き可能）。cg_simulate(simulator='iverilog') 用に iverilog があること。cg_check、cg_generate_verilog、バイトコードシミュレーターには、どちらも必要ありません。

MCP クライアントなしで検証コアをスモークテストします。

python3 - <<'EOF'
from neosyn_fpga_mcp import cg_mcp_server as cg
print(cg.simulate("package d;\ntask T { properties { test: { v:[1,2,3] } }\n"
                  "  out push u8 v; u8 c; void setup(){c=0;}\n"
                  "  void loop(){c=c+1; v.write(c);} }"))
EOF

MCP ホストに接続する

サーバーエントリーを追加します。絶対パスを使用してください。

{
  "mcpServers": {
    "cg": {
      "command": "neosyn-fpga-mcp",
      "args": [],
      "env": {
        "CG_JAR": "/abs/path/to/cg-language-server.jar"
      }
    }
  }
}

同じ command／args／env の形式は、Claude Desktop、Claude Code、Cursor、Cline、その他の stdio-MCP ホストで使えます。

次に、cg_context.md をシステムプロンプトとして読み込みます（または会話の先頭に貼り付けます）。これでモデルは言語を理解し、さらに検証もできるようになります。

サーバーが公開するツール

ツールは 13 個です。ソースを受け取るすべてのツールは、source（C⏚ 文字列）と、インポートするバンドル／タスク用の任意の extra_files マップ（{"Defs.cg": "..."}）を受け付けます。

存在するツール名はこれだけです。サーバーはこの表を読んだと仮定するのではなく、そのことを明示します。存在しないツールを呼び出すと、実在するツール名の一覧と最も近い名前（cg_compile → 「cg_check のことですか？」）が返されます。cg_capabilities にも一覧が含まれ、セッションの最初の呼び出しでも一覧が一度返されます。この一覧はツールレジストリから生成されるため、以下の表との不一致は起こりません。

ツール	パラメーター（source／extra_files 以外）	戻り値	使用するタイミング
cg_check	—	{ok, diagnostics:[…], warnings:[…], summary}	cg_lint の後、あらゆるドラフトに対して実行します。シミュレーションの前に、すべての診断結果を修正してください。warnings には、コンパイラーが受け入れるものの問題視するバリデーターの指摘（bool == 1、const への代入）が含まれます。プログラムはコンパイルできているため ok は true のままで、summary にもその旨が示されます。実際の処理で参照されるフィールドは ok だからです。コンパイラー 2.10.0 以上が必要です。古いバージョンでは、ここに何も報告されません。
cg_simulate	timeout=60, simulator='bytecode'	{ok, simulator, timed_out, diagnostics, output}	正しさを確認するための基準です。output にはポートの値と print() の行が格納されます。properties { test: {...} } ブロックで自己検証できます。ok になるまで繰り返してください。
cg_generate_verilog	target='verilog', output_dir=None, top=None	{ok, file_count, files:{path:content}}（永続化した場合は {output_dir, written} も追加）	シミュレーションに合格した後、RTL を引き渡すために使用します。target は 'verilog' または 'vhdl' です。output_dir（$PROJECT_ROOT からの相対パス）を渡すと、ファイルをディスクに書き込んで保持します。top（エンティティ名）を渡すと、そのエンティティと、それがインスタンス化するものだけを出力します。コンパイラー 3.4.0 より新しいバージョンが必要です。古いバージョンではすべてを出力せず、処理を拒否します。
cg_synth	top=None, timeout=180, flow='generic'	{ok, verdict, top, flow, cells, arith_ops, latches, warnings, stat, problems, output}	最も強力な正しさの指標です。Verilog を yosys で合成します。verdict は REAL / FOLDED（定数畳み込み済み。入力がポートにありません） / SUSPECT（ラッチが推論されました） / ERROR のいずれかなので、成功を捏造できません。warnings には、データパスが縮退している場合やラッチが推論された場合の説明が含まれます。
cg_capabilities	—	{ok, jar, jar_present, bytecode_simulator:{available,reason,detail}, simulators:[…], tools:{…}, advice}	このホストが実際にできることを、仮定ではなくプローブで確認します。高速なバイトコードシミュレーターは商用ディストリビューションに含まれ、オープンソースのコンパイラーには含まれません。そのため、どちらかの環境ではシミュレーターに関する一律の断言が誤りになります。検証方法を決める前に、このツールを呼び出してください。
cg_scaffold	kind='task', name, package, inputs, outputs, verify=True	{ok, kind, source, holes:[{line,text}], verified:{check,simulate}, message}	空のファイルから新しい C⏚ を書くときは、ここから始めてください。 データパスを >>> FILL IN の穴として残した、完全でコンパイル可能な自己検証型スケルトンを返します。受け取る前に緑の検証結果が確認されるため、その後に失敗した場合は自分の編集が原因です。kind は task（デフォルトで最も強力な形式。test: ブロックが各サイクルですべての出力値を検証する sync タスク） / fsm / stream / network / generic のいずれかです。inputs／outputs は "name:type" 形式の文字列で、task と stream に適用されます。cg_example を補完するツールです。新しく何かを書く場合は scaffold を、カーネルの検証済み実装がすでにある場合は example を使用してください。
cg_example	pattern='', k=1	pattern なしの場合は {ok, index:[{name,kind,use_when,tags}]}、pattern ありの場合は {ok, name, kind, source, …, runners_up:[…]}	検証済みコードの辞書から、スコア付きで必要に応じて検索します（検索ではありません）。具体性に応じて重み付けするため、1/sqrt は RSqrt に、sqrt は FixedSqrt に対応します。自己修正できるよう、次点候補を 1～2 件返します。k>1 を指定すると、組み合わせに使えるソースをさらに返します。
cg_lint	—	{ok, findings:[{rule,line,severity,message,fix}]}	コンパイラーが受け入れるものの、依然として誤っているコードを静的にチェックします。主に、入力を駆動しているのに出力を比較しない test: フィクスチャを検出します。設計が何もしていなくても合格してしまうためです。jar もシミュレーターも必要ないので、すべてのドラフトに対して cg_check の前に実行し、設計が検証済みだと表明する前にも再度実行してください。
cg_suggest_for_error	message	{ok, recipe, hint, source}	コンパイラーによる拒否を、修正パターンを含むレシピに対応付けます（変数による除算／シフト → Recip、データ依存のループ境界 → SeqDiv）。診断結果が一致すると、cg_check／cg_simulate／cg_generate_verilog はこれを suggestion として自動的に添付します。
cg_report	report_dir='fpga/build', schematics=True	{ok, report, kernels, sim_ok, message}	FPGA レポートを完成させます。<report_dir>/report.html を生成します（REAL/FOLDED/SUSPECT の判定とセル数を示す合成テーブル、シミュレーションの PASS/FAIL、生成された Verilog の一覧、ベストエフォートのデータパス SVG を含みます）。合成は行いません。同じ report_dir を cg_synth と cg_simulate に渡して合格した際の副産物として、各行が蓄積されます。
cg_fsm	task=None	{ok, diagnostics, fsm}	タスクのコンパイル済みステートマシンに、意図した状態と遷移が含まれていることを確認します。
cg_graph	network=None	{ok, diagnostics, graph}	ネットワークのコンパイル済み配線（インスタンス、幅／インターフェース付きポート、接続）を確認します。
cg_docs	topic=''	topic なしの場合は {ok, topics:[{topic,description}]}、topic ありの場合は {ok, topic, description, content}	Markdown 形式のナレッジドキュメントを必要に応じて取得します。context は C⏚ 言語のコアパックです。riscv は RV32I CPU の実例リファレンスです（ロード可能なシングルサイクルコアと、CPU 形式のハードウェア向けに再利用できるパターン：バレルシフター、符号付き／符号なしの拡張、サブワードのロード／ストア、ブートストリームによるプログラム読み込み、テストベンチでのキャプチャ）。プロセッサー／デコーダー／データパス／スタックマシンを構築する際は、riscv を読み込んでください。

バックエンドの選択

バックエンドセレクターを受け取るツールは2つあります。

• cg_simulate(source, simulator=…) — 設計のシミュレーションに使用するシミュレーターです。

  • 'bytecode' (デフォルト) — コンパイラーの高速なバイトコードシミュレーターです。HDLツールチェーンは不要です。properties { test: {...} } ブロックで自己検証できます。 cg_simulate(src) または cg_simulate(src, simulator="bytecode")。
  • 'iverilog' — Verilogとテストベンチを生成してIcarus Verilog（vvp）を実行し、Verilogレベルでクロスチェックします。テストベンチが出力されるのは、名前に大文字のTを含むネットワークだけです（例：network TestFoo）。小文字の _test ネットワークは、バイトコードシミュレーターの test プロパティのみを実行し、iverilogでは実行しません。PATH 上に iverilog が必要です。 cg_simulate(src, simulator="iverilog")。
  • 'verilator' — 将来の互換性のために受け付けられますが、verilator バイナリがインストールされていない場合は、利用不可と報告されます。cg_simulate(src, simulator="verilator")。

• cg_synth(source, flow=…) — 実行するyosys合成フローです。

  • 'generic' (デフォルト) — 移植性のある合成可能性チェック（synth）です。 cg_synth(src) または cg_synth(src, flow="generic")。
  • ベンダーのFPGAファミリー — 'ice40'、'ecp5'、'xilinx'、'gowin'、'intel' — 対応する部品のプリミティブ（LUT／BRAM／DSP）にマッピングします。 cg_synth(src, flow="ice40")。

  top のデフォルトは、最初のテストベンチ以外のタスク／ネットワーク（合成可能なDUT）です。1つのファイルに複数の設計が含まれる場合は指定してください。$YOSYS でyosysバイナリを上書きできます。

モデルでの使用方法

1. C⏚を作成します（必ず package から始めます）。
2. cg_lint → 無料かつ即時に実行でき、コンパイラーがそのまま受け入れてしまうミス、特に何も検証しない test: ブロックを検出します。
3. cg_check → すべての診断を修正し、warnings を読みます。これは、コードを受け入れはするものの、コンパイラー自身が問題視している点です。
4. cg_simulate → ok: true であることと、出力が意図どおりであることを確認します。
5. シミュレーションに成功したら cg_generate_verilog を実行し、RTLを引き渡します。
6. cg_synth（任意）→ Verilogが実際のハードウェアにマッピングされること（ok: true、妥当な cells 数、problems がないこと）を確認します。

ステップ2が必要なのは、何もしない設計でもステップ3～4の両方を通過できるためです。出力ベクターのないテストフィクスチャは、機能しないDUTに対しても合格になります。これを検出できるのは cg_lint だけで、実行コストもかかりません。

ステップ2～3の反復が重要です。モデルが記述し、コンパイラーが評価し、モデルが修正します。cg_context.md の末尾にも同じ手順が記載されているため、個別の指示がなくてもモデルはこれに従います。

最初から最後までの反復

from neosyn_fpga_mcp import cg_mcp_server as cg

src = '''package com.example.demo;
task Counter {
    properties { test: { value: [1, 2, 3] } }
    out push u8 value;
    u8 count;
    void setup() { count = 0; }
    void loop()  { count = count + 1; value.write(count); }
}'''

cg.check(src)                              # {'ok': True, 'diagnostics': [], ...}
cg.simulate(src)                           # {'ok': True, 'simulator': 'bytecode', ...}
cg.generate(src, output_dir="build/v")     # {'ok': True, 'file_count': N, 'written': [...]}
cg.synth(src, flow="ice40")                # {'ok': True, 'top': 'Counter', 'cells': ..., 'problems': []}

MCP ツールを通じて同じ呼び出しを行う場合は、cg_check → cg_simulate → cg_generate_verilog → cg_synth の順です。作成したらリストに沿って進み、各段階で診断を修正します。cg_synth が最終的なハードウェアの関門です。

シード＆アダプト：検証済みのベースから始める

知識と検証があれば、モデルは驚くほど先まで進めますが、限界があります。 本当に難しい固定小数点データパス（たとえば、1/r²·√r² の項を含む n 体力カーネル）を、モデルに ゼロから 書かせようとすると、C⏚ でも Verilog でもうまくいきません。信頼できるパターンは シード＆アダプト です。小さな 検証済み ベースをモデルに渡し、データフローだけを変更させます。モデルが 発明できない部分（Q16.16 の積和演算、タスク／ネットワーク／モニターの構成）はそのまま維持します。

cg_example(pattern) を呼び出して、ベースを取得します。これは、スコア付きの遅延アクセスが可能な 検証済みコードの厳選辞書（自由形式の検索ではありません）です。パターンを指定しない場合はインデックスを返します。名前または意図（"1/sqrt"、"distance"、"divide a by b"、 …）を指定すると、最も一致度の高いソースと、次点の候補を1～2件返すため、 モデルは自ら修正できます。一致度は具体性に基づいて重み付けされるため、"1/sqrt" は RSqrt に一致し、単なる "sqrt" は FixedSqrt に一致します。コンパイラーが何かを 拒否 した場合は、 cg_suggest_for_error(msg) が合成可能なパターンを含むレシピを示します。

examples/ には検証済みのエントリーが格納されています。すべてシミュレーションと Verilog の生成を行い、yosys synth に合格します。kind は、再利用可能な プリミティブ（Recip、Divide、 SeqDiv、FixedSqrt、RSqrt、SqrDist、DotProduct、Fir、Integ、Distance、Counter）と、アプリケーションの サンプル（Force、GalaxyForce — n 体の組み合わせ）を区別します。 use_when／タグ／セル数を含む全表は examples/RECIPES.md を参照してください。デモで定数入力を駆動するプリミティブ（DotProduct、FixedSqrt、Distance）は、 cg_synth が verdict: FOLDED を報告します。データパスを保持するには、（SqrDist のように） in push ポートで駆動してください。

リポジトリの cg_adapt_demo.py では、シード＆アダプトのループが最初から最後まで実行される様子を確認できます。また、EVAL.md では、小規模なタスクで C⏚ と Verilog の記述成功率をどのように測定したかを説明しています。この測定で示されないことも含まれています。

ドキュメント

• セットアップとツールの完全なリファレンス
• C⏚ のインストール — 拡張機能と CLI
• ライセンス

以前の名称

このプロジェクトは 1.0.0 まで cg-agent-kit として公開されていました。「cg」は C⏚ の略称ですが、FPGA ツールを検索する人には何の意味もありませんでした。PyPI では、この名前は現在も本パッケージをインストールするためのシムとして機能します。また、パッケージ内では python -m cg_agent_kit.cg_mcp_server と cg-mcp-server コマンドのどちらも引き続き解決されるため、既存の手順やホスト設定は引き続き機能します。新規インストールでは neosyn-fpga-mcp を使用してください。

ライセンス

MIT。Copyright (c) 2026 Neosyn.

本ソフトウェアは**「現状のまま」提供され、明示的または黙示的を問わず、いかなる種類の保証もありません**。これには、商品性、特定目的への適合性、および非侵害性の保証が含まれますが、これらに限定されません。いかなる場合も、作者または著作権者は、本ソフトウェアまたは本ソフトウェアの使用その他の取引に起因または関連して生じる、契約、不法行為その他の訴訟における請求、損害、その他の責任について、一切責任を負いません。全文は LICENSE としてパッケージに同梱されています。

C⏚、Cg、および Neosyn は Neosyn の商標です。C⏚ コンパイラーは独自のライセンスに基づく別個の著作物です。neosyn.io/open を参照してください。