WEFT — WEFT 详解 FPGA 工具链

一个 MCP 服务器，为 LLM 客户端提供安全、结构化的接口，以访问 Intel Quartus Prime 25.1 FPGA 流程：秒级完成 lint 和仿真， 异步编译，并以 JSON 格式读回结果，而不是数兆字节的日志。

这个名字是一个 GNU 风格递归缩写。weft（纬线）是横穿 经线（warp）织成的织物（fabric），而将布线逻辑织入 FPGA 的 fabric 正是它的工作。

状态

WEFT 正在建设中，按里程碑推进。目前已完成的内容：

两种传输方式均可用：stdio 用于本地客户端，Streamable HTTP 配合 静态 bearer token 用于局域网内的客户端。

Related MCP server: fpgaZeroMCP

这是做什么的，如果你不了解 MCP

假设一个 testbench 失败了，你想请模型帮忙。今天你的做法是：把 文件复制到聊天窗口，自己运行 Verilator，把一屏 %Warning-WIDTHEXPAND 粘贴进去，阅读回答，手动修复，然后 再来一轮。设计涉及三个文件，所以你要么把三个都粘贴进去，要么 模型只能猜测你没贴的那两个——而它会自信地猜。你得到的回答 基于你粘贴的文本，而不一定反映磁盘上的真实内容。

MCP（模型上下文协议）省去了这些来回搬运。服务器公布一份 工具列表及每个工具的参数。LLM 客户端——Claude Desktop、 Claude Code，或任何支持该协议的程序——把这份列表呈现在 模型面前。你继续用自然语言描述。模型选择工具、填写参数， 客户端发送调用。WEFT 就是远端的服务器。它 不承载模型、不运行推理，运行时也不发起任何网络调用。

当模型调用 lint 时，WEFT 会将每个路径解析并校验在你的工作区 根目录之内，拒绝任何越界路径，然后运行大致这样的命令：

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

Verilator 输出它一贯的输出。WEFT 将其转换为结构化记录——文件、 行号、严重级别、消息——然后容器即告结束。simulate 是同样的流程， 只是围绕 Verilator、Icarus 或 GHDL，返回通过/失败、日志尾部以及 波形文件的路径。

边界比管道更重要：模型选择要尝试什么，而 WEFT 决定什么可以执行。 远端没有 shell。模型无法发明一个标志参数，无法访问你未开放的路径， 也无法运行不在列表中的任何命令。

另一个包装工具的理由是体积。一次 Quartus 编译会留下数兆字节 的 .rpt 文件，而你真正想要的只是一个资源数据行、每个 时钟域的一个 Fmax 值，以及真正重要的那两条警告。这里工具的输出 只有几 KB 的 JSON；原始日志保留在磁盘上，仅在确实 需要时才按名称读取。

这里没有任何设计行为。它不会编写你的 RTL，不会收敛你的 时序，也不会知道你的板卡上是什么器件。它运行你本来就会运行的命令， 然后把结果压缩到足以供模型推理的规模。

它是如何组成的

Quartus 在宿主机上运行——WEFT 驱动你已经安装好的工具， 不会尝试自行安装或容器化它。其他所有 WEFT 需要执行的程序 都运行在同一个 Podman 镜像中，weft-tools：Verilator、Icarus Verilog、GHDL 和 Verible 用于 HDL 工作，Tesseract 和 Poppler 用于阅读文档。该 容器以 --network=none 运行，除了你的工作区之外什么都看不到。

MCP 客户端提供的每个路径都会在触及文件系统之前，被解析并 对照配置的工作区根目录进行校验——宿主机和 容器内都是如此。

运行时没有任何网络访问，也不上报任何遥测数据。

完整设计——每个工具的参数和返回结构、各个里程碑， 以及那些别扭之处背后的理由——都在 PROJECT.md 中。

环境要求

• Quartus Prime 25.1（Lite、Standard 或 Pro 版），由你自己安装并获得许可

• Podman，rootless 模式

• Python 3.11 或更新版本

• jtagd 用于器件编程，待该里程碑完成后需要

快速开始

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 只是 podman 的一个 Recommends（推荐）依赖，所以普通的 apt install 会 把它装进来，但 --no-install-recommends 不会。Rootless Podman 需要它。

Ubuntu 22.04 自带 Python 3.10，低于 WEFT 的要求。要么 升级到 24.04，要么安装更新的解释器，例如通过 uv：

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

构建镜像

该镜像从不分发——由你自己构建，这样 WEFT 自身的 分发范围仅限于 GPL-3.0-only 代码，也避免了打包 第三方二进制文件所带来的混合许可证问题。podman build 是唯一 需要网络访问的步骤；之后的一切都在离线状态下运行。

GHDL 在构建过程中从源码编译，所以第一次 会需要一些时间。

配置

WEFT 读取一个 TOML 文件，默认位置是 ~/.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 的路径始终来自这里。WEFT 从不猜测，也从不搜索 PATH。没有安装 Quartus 的机器只需省略该节——lint 和 simulate 不需要它。

未知的键会被拒绝而不是忽略，所以一个拼写错误会在启动时 直接报错，而不是静默地什么都不做。

运行

本地客户端，通过 stdio：

weft --transport stdio

对于 Claude Desktop 或 Claude Code，将其注册为 MCP 服务器：

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

在局域网内，通过 Streamable HTTP：

weft --transport http

每个请求都必须携带 Authorization: Bearer <token>；其他任何情况都会得到 401。配置中必须设置真实的 token——HTTP 传输方式在没有 token 时拒绝启动。

为什么需要 HTTP 传输方式

本地客户端并不需要它；stdio 更简单，也没有 token 泄露的风险。 HTTP 的存在是为了对接这样一个场景：你自行托管一个模型， 而网络环境没有出口。这样的模型部署在 一个兼容 OpenAI 的端点后面，它访问的是同一个 /mcp 端点，服务器端 无需任何改动。WEFT 运行时本就不发起网络调用，所以 已安装的服务器也不需要额外的网络配置。

构建那样的部署——推理集群、服务栈、把 镜像和依赖包搬运过网络隔离区——不属于本仓库的范畴。 PROJECT.md 的附录 A 记录了需要哪些步骤，然后 刻意就此打住。

演示工程

examples/counter/ 是一个小型 MAX 10 计数器，同时用 SystemVerilog、Verilog-2001 和 VHDL 编写。三种语言正是 重点所在：没有哪个开源仿真器能同时读取超过一种语言，因此这个工程 是对工具是否真正处理混合层次结构、还是仅仅声称如此的公平检验。

贡献

欢迎提交补丁。WEFT 遵循 Linux 内核的习惯：每个提交只包含一个 逻辑变更，主题采用 子系统: 摘要 格式，正文说明为什么， 用 rebase 而非 merge，并且所有内容都带有 Signed-off-by: 行。详见 CONTRIBUTING.md。

作者

WEFT 由 Mateusz Okulanis 编写并维护—— fpgartktic.github.io， @FPGArtktic，FPGArtktic@outlook.com。

欢迎提交错误报告、补丁和不同意见——尤其是最后一种， 如果你比我更深入地使用过这套工具链的话。

许可证

版权所有 (C) 2026 Mateusz Okulanis。

GPL-3.0-only。全文见 COPYING。

WEFT 以独立程序的方式调用 Quartus 和容器化工具， 不随附分发其中任何一个。

商标

Intel、Altera 和 Quartus 是其各自所有者的商标。本 项目与 Intel 或 Altera 无任何关联，未获得其认可或赞助。 本项目不包含任何 Intel 或 Altera 的代码、文件或文档，也 不安装或再分发其软件。