fpgaZeroMCP

AIアシスタントに完全なFPGAツールチェーン（リンティング、シミュレーション、合成、配置配線、ビットストリームの書き込み）と、GitHubで管理されるライブIPコアレジストリを提供するオープンソースのModel Context Protocolサーバーです。

AIにコアの検索や取り込み、HDLのリンティング、ディスク上の複数ファイルによるVHDL/Verilogプロジェクトの合成、シミュレーションの実行、そしてボードへのビットストリーム書き込みまで、チャットウィンドウを離れることなく実行させることができます。

機能

• マルチ言語対応: Verilog、SystemVerilog、VHDL（ghdl-yosys-plugin経由）

• 3つの入力モード: インラインの code 文字列、複数ファイルの files 辞書、またはディスク上の project_dir パス

• ファイルリスト対応: +incdir+、+define+、ネストされた -f ディレクティブを含む files.f/sources.f

• ボードプリセット: 11種類のボードを内蔵（iCEBreaker、ULX3S、TinyFPGA BX、Tang Nanoなど） — ターゲット/デバイス/パッケージ/クロックを自動設定

• 制約ファイルの自動検出: プロジェクトディレクトリ内の .pcf/.lpf/.pdc/.cst を検索

• ビットストリーム書き込み: iceprog (iCE40) または openFPGALoader (ECP5/Gowin/Nexus) 経由でフラッシュ

• シミュレーション結果の解析: VCD信号サマリー付きのPASS/FAIL/UVMパターン検出

• バックグラウンドビルド: ステータス監視機能付きの長時間実行される合成/配置配線、および厳格なEDAツールのみを許可するコマンドリスト

• IPコアレジストリ: FuseSoC CAPI2メタデータを使用したGitHubからのライブ検索とインポート

• ヘルスチェック: インストール済みで利用可能なOSS CAD Suiteツールの確認

目次

• 機能

• 仕組み

• 前提条件

• インストール

• MCPクライアントの設定

• ツール

• IPコアレジストリ

• 合成ターゲット

• LiteX

• ローカルコアリポジトリ

• テスト

• 環境変数

• スタンドアロン / スクリプト

• core.json スキーマ

• ライセンス

仕組み

Your AI assistant  <-->  fpgaZeroMCP (stdio MCP server)  <-->  OSS tools
                                    |
                           cores/   registry on GitHub
                           (uart_tx, fifo + any imported)

MCPサーバーはローカルのサブプロセスとして実行されます。AIはJSON-RPC (stdio) を介してサーバー上のツールを呼び出します。サーバーはOSS CAD SuiteのYosys、nextpnr、iverilog、Verilatorなどを呼び出し、GitHubから直接オープンソースのFPGAコアを取得できます。

前提条件

インストール後、OSS CAD Suiteを PATH に追加してください。ツールが見つからない場合、すべてのツールラッパーは適切に動作を停止します。

GitHub APIアクセス

GitHub APIリクエストはデフォルトで認証されておらず、レート制限の対象となります。制限を増やすにはパーソナルアクセストークンを設定してください：

# Linux/macOS
export GITHUB_TOKEN=ghp_...

# Windows (PowerShell)
$env:GITHUB_TOKEN = "ghp_..."

インストール

git clone https://github.com/lcapossio/fpgaZeroMCP
cd fpgaZeroMCP
pip install -e .

MCPクライアントの設定

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "fpgaZeroMCP": {
      "command": "python",
      "args": ["/path/to/fpgaZeroMCP/server.py"],
      "env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
    }
  }
}

VS Code (GitHub Copilot)

ワークスペースの .vscode/mcp.json に追加します：

{
  "servers": {
    "fpgaZeroMCP": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/fpgaZeroMCP/server.py"],
      "env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
    }
  }
}

Cursor / Windsurf

MCP設定（Settings → MCP Servers）に追加します：

{
  "fpgaZeroMCP": {
    "command": "python",
    "args": ["/path/to/fpgaZeroMCP/server.py"],
    "env": { "PYTHONPATH": "/path/to/fpgaZeroMCP" }
  }
}

プロンプト例

• "I2Cマスターコアを探してインポートして。"

• "~/projects/my_fpga にあるVHDLファイルを合成して、LUT数を確認して。"

• "iCEBreakerボード向けにプロジェクトを配置配線して、書き込んで。"

• "タイミングを改善するために、シード値42で配置配線を実行して。"

• "このVerilogをリンティングしてエラーを修正して。"

• "このFIFOをシミュレーションして、テストベンチがパスしたか教えて。"

• "このSystemVerilogファイルをフォーマットして。"

• "インストールされているOSS CAD Suiteツールは何？"

ツール

HDL品質

設計フロー

IPコアレジストリ

LiteX

ビルド管理

サーバー / レジストリ

IPコアレジストリ

コアは cores/<name>/ に配置されます。core.json マニフェストと1つ以上のHDLファイルで構成されます。サーバーは起動時に自動的に検出し、インポート後にリロードします。

フォーマットを示すために2つのリファレンスコア (uart_tx, fifo) が含まれています。このレジストリはここで成長させることを目的としていません — GitHubによって強化されています。

実行時のコア取得

# Find a RISC-V softcore
search_github_cores("riscv softcore", language="verilog")

# Pull it in
import_github_core("YosysHQ/picorv32")

# It is now in the local registry
get_ip_core("picorv32")
generate_ip("picorv32", {"COMPRESSED_ISA": 1})

サーバーはリポジトリ内にFuseSoC CAPI2メタデータ (.core ファイル) が見つかると自動的に使用し、より詳細なパラメータやポート情報を提供します。許可されたライセンスを持つリポジトリのみが受け入れられます。

コアの貢献

このリポジトリにコアを追加するプルリクエストは送らないでください。 代わりに：

1. fpga トピックとMITライセンスを付けて、HDLリポジトリをGitHubで公開する

2. 必要に応じて、より詳細なメタデータのためにFuseSoC CAPI2 .core ファイルを追加する

3. 誰でも import_github_core("you/your-core") で直接インポートできるようになる

これにより、サーバーを軽量に保ち、コミュニティがGitHub上で有機的に成長できるようになります。

合成ターゲット

place_and_route での一般的なデバイス/パッケージ値：

LiteX

LiteX は、多くのFPGAボードをターゲットにできるPython SoCフレームワークです。fpgaZeroMCPは3つの専用LiteXツールを公開しており、synthesize および place_and_route で backend="litex" を指定することも可能です。

# Dedicated tools
litex_build(board="arty", args=["--build"])
litex_soc(board="arty", args=["--no-compile"])
litex_flow(board="arty", args=["--build", "--output-dir", "build_arty"])

# As a backend in existing flow tools
synthesize(code="...", top_module="top", backend="litex", litex_board="arty")
place_and_route(code="...", top_module="top", target="ice40", device="hx1k",
                backend="litex", litex_board="arty", litex_args=["--build"])

ローカルコアリポジトリ

独自のローカルHDLディレクトリをレジストリに指定するには2つの方法があります：

環境変数：

Linux/macOS (コロン区切り)：

export USERCORES_PATH=/home/you/my-cores:/home/you/work-cores

Windows (セミコロン区切り、PowerShell)：

$env:USERCORES_PATH = "C:\Users\you\my-cores;C:\Users\you\work-cores"

設定ファイル (~/.fpgazero_mcp/config.json)：

{
  "core_paths": [
    "/home/you/my-cores",
    "/home/you/work-cores"
  ]
}

すべてのパスは、組み込みの cores/ ディレクトリとともに起動時にスキャンされます。

許可されたライセンス

デフォルトでは、import_github_core は以下のSPDXライセンスのいずれかを持つリポジトリを受け入れます：

MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, ISC, GPL-2.0, GPL-3.0, LGPL-2.1, LGPL-3.0

FPGAZERO_ALLOWED_LICENSES 環境変数（カンマ区切りのSPDX ID）で上書き可能です：

# Linux/macOS
export FPGAZERO_ALLOWED_LICENSES=MIT
export FPGAZERO_ALLOWED_LICENSES=MIT,Apache-2.0

# Windows (PowerShell)
$env:FPGAZERO_ALLOWED_LICENSES = "MIT"
$env:FPGAZERO_ALLOWED_LICENSES = "MIT,Apache-2.0"

ライセンスIDは SPDX表記 に従います。チェックはインポート時に行われます。search_github_cores はインポート前に評価できるよう、ライセンスに関係なく結果を返します。

テスト

pip install -e ".[dev]"
python -m pytest tests/ -v

一部のテストは、PATH上にOSS CAD Suiteツールを必要とします。必要なツールがないテストは自動的にスキップされます。

環境変数

スタンドアロン / スクリプト

Python APIはMCPクライアントなしで直接使用できます：

from registry.resolver import CoreRegistry
from tools.lint import lint_hdl

reg = CoreRegistry()

# Import a core from GitHub
reg.import_github_core("ben-marshall/uart")

# Generate a parameterized instantiation
result = reg.generate_ip("uart", {"CLKS_PER_BIT": 868})
print(result["instantiation"])

# Lint some HDL
lint_hdl(open("my_design.v").read())

python example.py   # runs the built-in demo

core.json スキーマ

{
  "name": "my_core",
  "version": "1.0.0",
  "description": "...",
  "author": "you",
  "license": "MIT",
  "language": "verilog",
  "category": "communication",
  "tags": ["spi", "serial"],
  "parameters": {
    "DATA_WIDTH": { "type": "integer", "default": 8, "description": "..." }
  },
  "ports": {
    "clk": { "direction": "input", "width": 1, "description": "System clock" }
  },
  "files": ["my_core.v"]
}

著者

Leonardo Capossio (bard0) — hello@bard0.com

ライセンス

MIT — LICENSE を参照。