fpgaZeroMCP

Ein Open-Source Model Context Protocol-Server, der KI-Assistenten eine vollständige FPGA-Toolchain an die Hand gibt — Linting, Simulation, Synthese, Place-and-Route, Programmierung des Bitstreams sowie eine Live-IP-Core-Registry, die auf GitHub basiert.

Bitten Sie Ihre KI, nach Cores zu suchen, diese einzubinden, HDL zu linten, ein VHDL- oder Verilog-Projekt mit mehreren Dateien von der Festplatte zu synthetisieren, eine Simulation auszuführen und dann den Bitstream auf Ihr Board zu flashen — alles, ohne Ihr Chat-Fenster zu verlassen.

Funktionen

• Mehrsprachig: Verilog, SystemVerilog und VHDL (via ghdl-yosys-plugin)

• Drei Eingabemodi: Inline code-String, files-Dictionary mit mehreren Dateien oder project_dir-Pfad auf der Festplatte

• Unterstützung von Dateilisten: files.f/sources.f mit +incdir+, +define+ und verschachtelten -f-Direktiven

• Board-Presets: 11 integrierte Boards (iCEBreaker, ULX3S, TinyFPGA BX, Tang Nano, etc.) — setzt Ziel/Gerät/Gehäuse/Takt automatisch

• Automatische Erkennung von Constraints: Findet .pcf/.lpf/.pdc/.cst in Ihrem Projektverzeichnis

• Bitstream-Programmierung: Flashen via iceprog (iCE40) oder openFPGALoader (ECP5/Gowin/Nexus)

• Analyse von Simulationsergebnissen: PASS/FAIL/UVM-Mustererkennung mit VCD-Signalzusammenfassung

• Hintergrund-Builds: Lang laufende Synthese/PnR mit Statusabfrage und einer strikten Positivliste für EDA-Befehle

• IP-Core-Registry: Live-Suche und Import von GitHub mit FuseSoC CAPI2-Metadaten

• Systemprüfung: Ermittlung, welche OSS CAD Suite-Tools installiert und erreichbar sind

Inhaltsverzeichnis

• Funktionen

• Funktionsweise

• Voraussetzungen

• Installation

• MCP-Client-Einrichtung

• Tools

• IP-Core-Registry

• Synthese-Ziele

• LiteX

• Lokale Core-Repositories

• Testen

• Umgebungsvariablen

• Standalone / Skripting

• core.json-Schema

• Lizenz

Funktionsweise

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

Der MCP-Server läuft als lokaler Subprozess. Ihre KI ruft Tools über JSON-RPC (stdio) auf. Der Server greift auf Yosys, nextpnr, iverilog, Verilator und andere aus der OSS CAD Suite zu — und kann Open-Source-FPGA-Cores direkt von GitHub beziehen.

Voraussetzungen

Fügen Sie die OSS CAD Suite nach der Installation zu Ihrem PATH hinzu. Alle Tool-Wrapper reagieren tolerant, falls ein Tool fehlt.

GitHub API-Zugriff

GitHub API-Anfragen sind standardmäßig nicht authentifiziert und unterliegen Ratenbegrenzungen. Setzen Sie ein persönliches Zugriffstoken, um die Limits zu erhöhen:

# Linux/macOS
export GITHUB_TOKEN=ghp_...

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

Installation

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

MCP-Client-Einrichtung

Claude Desktop

Fügen Sie dies zu claude_desktop_config.json hinzu:

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

VS Code (GitHub Copilot)

Fügen Sie dies zu .vscode/mcp.json in Ihrem Arbeitsbereich hinzu:

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

Cursor / Windsurf

Fügen Sie dies zu Ihren MCP-Einstellungen hinzu (Settings → MCP Servers):

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

Beispiel-Prompts

• "Suche mir einen I2C-Master-Core und importiere ihn."

• "Synthetisiere die VHDL-Dateien in ~/projects/my_fpga und nenne mir die LUT-Anzahl."

• "PnR mein Projekt für das iCEBreaker-Board und flashe es dann."

• "Führe Place-and-Route mit Seed 42 aus, um ein besseres Timing zu erreichen."

• "Linte dieses Verilog und behebe alle Fehler."

• "Simuliere diesen FIFO und sage mir, ob der Testbench bestanden hat."

• "Formatiere diese SystemVerilog-Datei."

• "Welche OSS CAD Suite-Tools habe ich installiert?"

Tools

HDL-Qualität

Design-Flow

IP-Core-Registry

LiteX

Build-Management

Server / Registry

IP-Core-Registry

Cores befinden sich in cores/<name>/ — ein core.json-Manifest und eine oder mehrere HDL-Dateien. Der Server erkennt sie beim Start automatisch und lädt sie nach jedem Import neu.

Zwei Referenz-Cores sind enthalten (uart_tx, fifo), um das Format zu demonstrieren. Die Registry ist nicht dazu gedacht, hier zu wachsen — sie wird von GitHub angetrieben.

Cores zur Laufzeit abrufen

# 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})

Der Server verwendet automatisch FuseSoC CAPI2-Metadaten (.core-Dateien), wenn sie im Repo gefunden werden, was reichhaltigere Parameter- und Portinformationen liefert. Nur Repos mit einer erlaubten Lizenz werden akzeptiert.

Einen Core beisteuern

Eröffnen Sie keine PRs, um Cores zu diesem Repo hinzuzufügen. Stattdessen:

1. Veröffentlichen Sie Ihr HDL-Repo auf GitHub mit dem Topic fpga und einer MIT-Lizenz

2. Fügen Sie optional eine FuseSoC CAPI2 .core-Datei für reichhaltigere Metadaten hinzu

3. Jeder kann dann import_github_core("you/your-core") direkt ausführen

Dies hält den Server schlank und lässt die Community organisch auf GitHub wachsen.

Synthese-Ziele

Allgemeine Geräte-/Gehäusewerte für place_and_route:

LiteX

LiteX ist ein Python-SoC-Framework, das auf viele FPGA-Boards abzielen kann. fpgaZeroMCP stellt drei dedizierte LiteX-Tools bereit und akzeptiert auch backend="litex" in synthesize und place_and_route.

# 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"])

Lokale Core-Repositories

Sie können die Registry auf zwei Arten auf Ihre eigenen lokalen HDL-Verzeichnisse verweisen:

Umgebungsvariable:

Linux/macOS (durch Doppelpunkt getrennt):

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

Windows (durch Semikolon getrennt, PowerShell):

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

Konfigurationsdatei (~/.fpgazero_mcp/config.json):

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

Alle Pfade werden beim Start neben dem integrierten cores/-Verzeichnis gescannt.

Erlaubte Lizenzen

Standardmäßig akzeptiert import_github_core Repos mit einer dieser SPDX-Lizenzen:

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

Überschreiben Sie dies mit der Umgebungsvariablen FPGAZERO_ALLOWED_LICENSES (durch Komma getrennte SPDX-IDs):

# 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"

Lizenz-IDs folgen der SPDX-Notation. Die Prüfung erfolgt zum Importzeitpunkt; search_github_cores liefert Ergebnisse unabhängig von der Lizenz, damit Sie diese vor dem Import bewerten können.

Testen

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

Einige Tests erfordern OSS CAD Suite-Tools im PATH. Tests, die fehlende Tools benötigen, werden automatisch übersprungen.

Umgebungsvariablen

Standalone / Skripting

Die Python-API kann direkt ohne MCP-Client verwendet werden:

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-Schema

{
  "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"]
}

Autor

Leonardo Capossio (bard0) — hello@bard0.com

Lizenz

MIT — siehe LICENSE.