WEFT — WEFT erläutert FPGA-Toolchains

Ein MCP-Server, der einem LLM-Client eine sichere, strukturierte Schnittstelle zu einem Intel Quartus Prime 25.1 FPGA-Flow bietet: Lint- und Simulationsläufe in Sekunden, asynchrones Kompilieren und das Zurücklesen von Ergebnissen als JSON statt Megabyte an Logs.

Der Name ist ein rekursives Akronym im GNU-Stil. Der Weft ist der Faden, der über die Kette gewebt wird, um Stoff zu erzeugen, und das Routen von Logik in FPGA-Fabric ist genau diese Aufgabe.

Status

WEFT befindet sich im Aufbau, Meilenstein für Meilenstein. Was heute fertig ist:

Beide Transporte funktionieren: stdio für einen lokalen Client, Streamable HTTP hinter einem statischen Bearer-Token für einen Client im LAN.

Related MCP server: fpgaZeroMCP

Wofür das ist, wenn MCP neu für dich ist

Angenommen, eine Testbench schlägt fehl und du möchtest die Hilfe eines Modells. Heute kopierst du die Datei in ein Chatfenster, führst Verilator selbst aus, fügst einen Bildschirm voll %Warning-WIDTHEXPAND danach ein, liest die Antwort, wendest die Korrektur von Hand an und beginnst von vorn. Das Design ist drei Dateien tief, also fügst du entweder alle drei ein oder das Modell rät bei den beiden, die du weggelassen hast – und es wird selbstbewusst raten. Die Antwort, die du bekommst, bezieht sich auf den Text, den du eingefügt hast, was nicht unbedingt dem entspricht, was auf der Festplatte liegt.

MCP, das Model Context Protocol, beseitigt das Hin- und Hertragen. Ein Server bewirbt eine Liste von Werkzeugen und die Argumente, die jedes benötigt. Ein LLM-Client – Claude Desktop, Claude Code oder etwas anderes, das das Protokoll spricht – legt diese Liste dem Modell vor. Du tippst weiterhin Prosa. Das Modell wählt ein Werkzeug, füllt die Argumente aus, und der Client sendet den Aufruf. WEFT ist der Server am anderen Ende. Es enthält kein Modell, führt keine Inferenz aus und tätigt zur Laufzeit keine Netzwerkaufrufe.

Wenn das Modell lint aufruft, löst WEFT jeden Pfad relativ zum Workspace-Root auf, verweigert alles, was ihn verlässt, und führt ungefähr Folgendes aus:

podman run --rm --network=none -v <workspace>:/work -w /work weft-tools \
    verilator --lint-only -Isrc src/updown_counter.sv

Verilator gibt aus, was es immer ausgibt. WEFT wandelt das in Datensätze um – Datei, Zeile, Schweregrad, Meldung – und der Container ist weg. simulate ist dieselbe Schleife um Verilator, Icarus oder GHDL und liefert bestanden/nicht bestanden, einen Teil des Logs und den Pfad zur Wellenform zurück.

Die Grenze ist wichtiger als die Verkabelung: Das Modell wählt, was es versucht, WEFT wählt, was ausgeführt werden darf. Am anderen Ende gibt es keine Shell. Das Modell kann kein Flag erfinden, keinen Pfad erreichen, den du ihm nicht geöffnet hast, und nichts ausführen, das nicht auf der Liste steht.

Der andere Grund, die Werkzeuge zu kapseln, ist die Größe. Eine Quartus-Kompilierung hinterlässt Megabyte an .rpt-Dateien, und was du davon wolltest, war eine Ressourcenzeile, ein Fmax pro Takt-Domäne und die zwei Warnungen, die wichtig waren. Werkzeugergebnisse sind hier ein paar Kilobyte JSON; die rohen Logs bleiben auf der Festplatte und werden bei Bedarf namentlich abgerufen.

Nichts davon entwirft etwas. Es wird nicht dein RTL schreiben, dein Timing schließen oder wissen, welches Board auf deinem Schreibtisch liegt. Es führt die Befehle aus, die du ausgeführt hättest, und gibt etwas zurück, das klein genug ist, um darüber nachzudenken.

Wie es aufgebaut ist

Quartus läuft auf dem Host – WEFT steuert die Installation, die du bereits hast, und versucht nie, sie zu installieren oder zu containerisieren. Alles andere, was WEFT ausführt, lebt in einem Podman-Image, weft-tools: Verilator, Icarus Verilog, GHDL und Verible für HDL-Arbeit, Tesseract und Poppler zum Lesen von Dokumenten. Der Container läuft mit --network=none und sieht nichts außer deinem Workspace.

Jeder Pfad, den ein MCP-Client liefert, wird aufgelöst und gegen das konfigurierte Workspace-Root geprüft, bevor er das Dateisystem erreicht, sowohl auf dem Host als auch im Container.

Zur Laufzeit erreicht nichts das Netzwerk, und nichts meldet Telemetrie.

Das vollständige Design – die Argumente und Rückgabestrukturen jedes Werkzeugs, die Meilensteine und die Begründung hinter den schwierigen Teilen – steht in PROJECT.md.

Voraussetzungen

• Quartus Prime 25.1 (Lite, Standard oder Pro), von dir installiert und lizenziert

• Podman, rootless

• Python 3.11 oder neuer

• jtagd für die Programmierung von Hardware, sobald dieser Meilenstein erreicht ist

Schnellstart

Arch Linux

sudo pacman -S --needed podman python git

git clone https://github.com/FPGArtktic/weft-mcp.git
cd weft-mcp
podman build -t weft-tools -f containers/Containerfile.weft-tools .
pip install --user .

Ubuntu 24.04 LTS

sudo apt update
sudo apt install podman uidmap python3 python3-pip git

git clone https://github.com/FPGArtktic/weft-mcp.git
cd weft-mcp
podman build -t weft-tools -f containers/Containerfile.weft-tools .
pip install --user .

uidmap ist nur ein Recommends von podman, also zieht ein einfaches apt install es mit, aber --no-install-recommends nicht. Rootless Podman benötigt es.

Ubuntu 22.04 bringt Python 3.10 mit, was unter dem liegt, was WEFT benötigt. Entweder auf 24.04 wechseln oder einen neueren Interpreter installieren, zum Beispiel mit uv:

uv venv --python 3.12 && uv pip install .

Das Image erstellen

Das Image wird niemals verteilt – du baust es, was WEFTs eigene Verteilung auf GPL-3.0-only-Code beschränkt und vermeidet, ein Aggregat von Drittanbieter-Binärdateien unter gemischten Lizenzen auszuliefern. podman build ist der einzige Schritt, der Netzwerkzugriff benötigt; alles danach läuft offline.

GHDL wird während des Builds aus dem Quellcode kompiliert, also rechne beim ersten Mal mit etwas Zeit.

Konfiguration

WEFT liest eine TOML-Datei, standardmäßig ~/.config/weft/weft.toml:

[workspace]
# Nothing outside this directory can be read or written.
root = "/home/you/fpga"

[container]
image = "weft-tools"

[quartus]
edition = "lite"          # omit when only one edition is configured

[quartus.lite]
root = "/home/you/intelFPGA_lite/25.1std/quartus"

[quartus.pro]
root = "/opt/intelFPGA_pro/25.1/quartus"
# FlexLM variables are passed through to every Pro invocation.
env = { LM_LICENSE_FILE = "1800@licence-server" }

[jobs]
timeout_s = 7200

[http]
host = "127.0.0.1"
port = 8080
token = "put-a-long-random-string-here"

Quartus-Pfade kommen immer von hier. WEFT rät sie nie und durchsucht nie PATH. Eine Maschine ohne Quartus lässt den Abschnitt einfach weg – Lint und Simulation benötigen ihn nicht.

Unbekannte Schlüssel werden abgelehnt statt ignoriert, sodass ein Tippfehler beim Start fehlschlägt, anstatt stillschweigend nichts zu tun.

Ausführen

Lokaler Client über stdio:

weft --transport stdio

Für Claude Desktop oder Claude Code als MCP-Server registrieren:

{
  "mcpServers": {
    "weft": {
      "command": "weft",
      "args": ["--transport", "stdio", "--config", "/home/you/.config/weft/weft.toml"]
    }
  }
}

Im LAN über Streamable HTTP:

weft --transport http

Jede Anfrage muss Authorization: Bearer <token> enthalten; alles andere erhält eine 401. Setze ein echtes Token in der Konfiguration – der HTTP-Transport weigert sich, ohne eines zu starten.

Warum es überhaupt einen HTTP-Transport gibt

Ein lokaler Client braucht keinen; stdio ist einfacher und hat kein Token, das auslaufen könnte. HTTP existiert, weil es der Übergabepunkt ist, um dies hinter einem selbst gehosteten Modell zu betreiben, in einem Netzwerk ohne Ausweg. Ein solches Modell, das hinter einem OpenAI-kompatiblen Endpunkt bereitgestellt wird, spricht mit demselben /mcp-Endpunkt, und auf der Serverseite ändert sich nichts. WEFT tätigt zur Laufzeit bereits keine Netzwerkaufrufe, also benötigt ein installierter Server nichts weiter.

Der Aufbau dieser Bereitstellung – der Inferenzcluster, der Serving-Stack, das Transportieren des Images und der Wheels über die Lücke – ist nicht Teil dieses Repositorys. Anhang A von PROJECT.md hält fest, was es bräuchte, und hört dort bewusst auf.

Das Demo-Projekt

examples/counter/ ist ein kleiner MAX-10-Zähler, der gleichzeitig in SystemVerilog, Verilog-2001 und VHDL geschrieben ist. Die drei Sprachen sind der Punkt: Kein Open-Source-Simulator liest mehr als eine, also ist das Projekt ein fairer Test, ob ein Werkzeug wirklich eine gemischte Hierarchie verarbeitet oder es nur behauptet.

Mitwirken

Patches sind willkommen. WEFT folgt den Gewohnheiten des Linux-Kernels: eine logische Änderung pro Commit, Betreffzeilen im Format subsystem: summary, ein Textkörper, der das Warum erklärt, Rebase statt Merge und eine Signed-off-by:-Zeile auf allem. Siehe CONTRIBUTING.md.

Autor

WEFT wird geschrieben und gepflegt von Mateusz Okulanis – fpgartktic.github.io, @FPGArtktic, FPGArtktic@outlook.com.

Fehlerberichte, Patches und Meinungsverschiedenheiten sind alle willkommen – letztere besonders, wenn du diese Toolchain härter benutzt hast als ich.

Lizenz

Copyright (C) 2026 Mateusz Okulanis.

GPL-3.0-only. Der vollständige Text steht in COPYING.

WEFT ruft Quartus und die containerisierten Werkzeuge als separate Programme auf und vertreibt keines davon.

Marken

Intel, Altera und Quartus sind Marken ihrer jeweiligen Inhaber. Dieses Projekt ist nicht mit Intel oder Altera verbunden, wird von ihnen nicht unterstützt oder gesponsert. Es enthält keinen Intel- oder Altera-Code, keine Dateien oder Dokumentation und installiert oder vertreibt deren Software weder.