WEFT — WEFT가 FPGA 툴체인을 정교하게 다루다

LLM 클라이언트에게 Intel Quartus Prime 25.1 FPGA 플로우에 대한 안전하고 구조화된 인터페이스를 제공하는 MCP 서버입니다. 몇 초 만에 린트와 시뮬레이션을 수행하고, 비동기로 컴파일하며, 메가바이트 단위의 로그 대신 JSON으로 결과를 읽어옵니다.

이름은 GNU 스타일의 재귀 약어입니다. weft(씨실)는 날실(warp)을 가로질러 직물(fabric)을 만드는 실이며, FPGA 패브릭에 로직을 라우팅하는 것이 바로 그 일입니다.

상태

WEFT는 마일스톤 단위로 건설 중입니다. 오늘 완성된 것은 다음과 같습니다:

두 전송 방식 모두 작동합니다: 로컬 클라이언트용 stdio, LAN의 클라이언트용 정적 베어러 토큰 뒤의 Streamable HTTP.

Related MCP server: fpgaZeroMCP

MCP가 처음이라면, 이것이 무엇을 위한 것인지

테스트벤치가 실패했고 모델의 도움을 받고 싶다고 가정해 봅시다. 오늘날에는 파일을 채팅 창에 복사하고, 직접 Verilator를 실행하고, 그 뒤에 %Warning-WIDTHEXPAND 화면 한 가득을 붙여넣고, 답변을 읽고, 수정 사항을 직접 적용하고, 다시 반복합니다. 설계는 파일 세 개 깊이이므로, 세 개를 모두 붙여넣거나 모델이 빠뜨린 두 개를 추측하게 됩니다 — 그리고 그것은 자신 있게 추측할 것입니다. 얻는 답변은 붙여넣은 텍스트에 대한 것이지, 반드시 디스크에 있는 것에 대한 것은 아닙니다.

MCP(Model Context Protocol)는 이러한 수작업 운반을 제거합니다. 서버는 도구 목록과 각 도구가 받는 인자를 광고합니다. 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는 무엇이 실행될 수 있는지 선택합니다. 먼 쪽 끝에는 셸이 없습니다. 모델은 플래그를 발명할 수 없고, 당신이 열어주지 않은 경로에 도달할 수 없으며, 목록에 없는 것을 실행할 수 없습니다.

도구를 감싸는 또 다른 이유는 크기입니다. Quartus 컴파일은 메가바이트의 .rpt를 남기며, 당신이 원했던 것은 리소스 한 줄, 클록 도메인별 Fmax, 그리고 중요했던 두 개의 경고였습니다. 여기서 도구 결과는 몇 킬로바이트의 JSON입니다. 원시 로그는 디스크에 남아 있으며 실제로 필요할 때 이름으로 가져옵니다.

이 중 어느 것도 설계를 하지 않습니다. RTL을 작성하지 않고, 타이밍을 마감하지 않으며, 책상 위의 보드가 무엇인지 알지 못합니다. 당신이 실행했을 명령을 실행하고, 추론할 수 있을 만큼 작은 것을 돌려줍니다.

구성 방식

Quartus는 호스트에서 실행됩니다 — WEFT는 이미 설치된 것을 구동하며 설치하거나 컨테이너화하려 하지 않습니다. WEFT가 실행하는 다른 모든 것은 하나의 Podman 이미지 weft-tools에 있습니다: HDL 작업용 Verilator, Icarus Verilog, GHDL 및 Verible, 문서 읽기용 Tesseract와 Poppler. 컨테이너는 --network=none으로 실행되며 작업공간 외에는 아무것도 보지 못합니다.

MCP 클라이언트가 제공하는 모든 경로는 호스트와 컨테이너 내부 모두에서 파일시스템에 도달하기 전에 구성된 작업공간 루트에 대해 확인되고 검사됩니다.

런타임에 네트워크에 도달하는 것은 없으며, 텔레메트리를 보고하는 것도 없습니다.

전체 설계 — 모든 도구의 인자와 반환 형태, 마일스톤, 그리고 어색한 부분 뒤의 근거 — 는 PROJECT.md에 있습니다.

요구 사항

• Quartus Prime 25.1(Lite, Standard 또는 Pro)이 설치되고 사용자가 라이선스를 보유

• Podman, 루트리스

• 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는 가져오지 않습니다. 루트리스 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"]
    }
  }
}

LAN에서 Streamable HTTP를 통해:

weft --transport http

모든 요청은 Authorization: Bearer <token>을携带해야 합니다. 그 외에는 401을 받습니다. 구성에 실제 토큰을 설정하십시오 — HTTP 전송은 토큰 없이는 시작을 거부합니다.

HTTP 전송이 아예 존재하는 이유

로컬 클라이언트는 필요하지 않습니다. stdio가 더 간단하고 누출될 토큰도 없습니다. HTTP가 존재하는 이유는 나가는 길이 없는 네트워크에서 직접 호스팅하는 모델 뒤에서 실행하기 위한 인계 지점이기 때문입니다. OpenAI 호환 엔드포인트 뒤에서 서비스되는 그러한 모델은 동일한 /mcp 엔드포인트와 통신하며, 서버 측에서는 아무것도 바뀌지 않습니다. WEFT는 이미 런타임에 네트워크 호출을 하지 않으므로, 설치된 서버는 더 이상 아무것도 필요로 하지 않습니다.

그 배포 구축 — 추론 클러스터, 서빙 스택, 이미지와 휠을 그 간격을 가로질러 운반하는 것 — 은 이 저장소의 일부가 아닙니다. PROJECT.md의 부록 A는 그것이 무엇을 요구할지 기록하고, 의도적으로 거기서 멈춥니다.

데모 프로젝트

examples/counter/는 SystemVerilog, Verilog-2001 및 VHDL로 동시에 작성된 작은 MAX 10 카운터입니다. 세 언어가 핵심입니다: 오픈소스 시뮬레이터 중 하나 이상을 읽는 것은 없으므로, 이 프로젝트는 도구가 혼합 계층 구조를 실제로 처리하는지 아니면 단지 주장만 하는지에 대한 공정한 테스트입니다.

기여

패치는 환영합니다. WEFT는 Linux 커널의 관행을 따릅니다: 커밋당 하나의 논리적 변경, 하위시스템: 요약 제목, 이유를 설명하는 본문, 병합보다는 리베이스, 그리고 모든 것에 Signed-off-by: 줄. CONTRIBUTING.md를 참조하십시오.

저자

WEFT는 Mateusz Okulanis가 작성하고 유지 관리합니다 — fpgartktic.github.io, @FPGArtktic, FPGArtktic@outlook.com.

버그 보고서, 패치 및 의견 불일치 모두 환영합니다 — 특히 제가 이 툴체인을 더 세게 몰아본 적이 있다면, 그 마지막 것이 특히 그렇습니다.

라이선스

Copyright (C) 2026 Mateusz Okulanis.

GPL-3.0-only. 전문은 COPYING에 있습니다.

WEFT는 Quartus와 컨테이너화된 도구를 별도의 프로그램으로 호출하며 그중 어느 것도 배포하지 않습니다.

상표

Intel, Altera 및 Quartus는 각 소유자의 상표입니다. 이 프로젝트는 Intel 또는 Altera와 제휴, 보증 또는 후원 관계가 아닙니다. Intel 또는 Altera 코드, 파일 또는 문서를 포함하지 않으며, 그들의 소프트웨어를 설치하거나 재배포하지 않습니다.