fpgaZeroMCP

AI 어시스턴트에게 완전한 FPGA 툴체인 — 린트, 시뮬레이션, 합성, 배치 및 라우팅, 비트스트림 프로그래밍, 그리고 GitHub 기반의 라이브 IP 코어 레지스트리 — 을 제공하는 오픈소스 Model Context Protocol 서버입니다.

AI에게 코어를 검색하고 가져오고, HDL을 린트하고, 디스크의 다중 파일 VHDL 또는 Verilog 프로젝트를 합성하고, 시뮬레이션을 실행한 다음, 보드에 비트스트림을 플래시하도록 요청하세요 — 채팅 창을 벗어나지 않고 모두 가능합니다.

기능

• 다중 언어: Verilog, SystemVerilog, VHDL(ghdl-yosys-plugin 사용)

• 세 가지 입력 모드: 인라인 code 문자열, 다중 파일 files 딕셔너리, 또는 디스크의 project_dir 경로

• 파일리스트 지원: +incdir+, +define+, 중첩 -f 지시문이 포함된 files.f/sources.f

• 보드 프리셋: 11개의 내장 보드(iCEBreaker, ULX3S, TinyFPGA BX, Tang Nano 등) — target/device/package/clock 자동 설정

• 제약 조건 자동 감지: 프로젝트 디렉터리에서 .pcf/.lpf/.pdc/.cst 자동 검색

• 비트스트림 프로그래밍: iceprog(iCE40) 또는 openFPGALoader(ECP5/Gowin/Nexus/Xilinx)를 통한 플래시

• Vivado: start_build를 통한 배치 실행, LiteX를 통한 Xilinx 빌드, build_status의 구조화된 Vivado 로그 파싱

• 시뮬레이션 판정 파싱: VCD 신호 요약과 함께 PASS/FAIL/UVM 패턴 감지

• 백그라운드 빌드: 상태 폴링과 엄격한 EDA 전용 명령 허용 목록을 갖춘 장시간 실행 합성/PnR

• 동시 요청: 느린 도구 호출이 실행되는 동안에도 ping, 빌드 상태, 취소에 응답합니다. notifications/cancelled는 진행 중인 호출을 중단합니다.

• 기계 판독 가능 결과: 도구 결과의 structuredContent(MCP 2025-06-18)와 재시도/폴백 결정을 위한 통일된 error_code 분류 체계

• 진행 알림: 클라이언트가 progressToken을 보내면 합성, 배치 및 라우팅, LiteX 실행의 단계 경계에서 notifications/progress 전송

• IP 코어 레지스트리: FuseSoC CAPI2 메타데이터를 포함한 GitHub 실시간 검색 및 가져오기

• 헬스 체크: 설치되어 있고 접근 가능한 OSS CAD Suite 도구 탐지

Related MCP server: vivado-mcp-agent

목차

• 기능

• 작동 방식

• 사전 요구 사항

• 설치

• 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 보드용 내 프로젝트를 PnR한 다음 플래시해 줘."

• "더 나은 타이밍을 위해 seed 42로 배치 및 라우팅을 실행해 줘."

• "이 Verilog를 린트하고 오류가 있으면 모두 고쳐 줘."

• "이 FIFO를 시뮬레이션하고 테스트벤치가 통과했는지 알려줘."

• "이 SystemVerilog 파일을 포맷해 줘."

• "어떤 OSS CAD Suite 도구가 설치되어 있나요?"

도구

HDL 품질

설계 흐름

IP 코어 레지스트리

LiteX

빌드 관리

서버 / 레지스트리

IP 코어 레지스트리

코어는 cores/<name>/에 위치합니다 — core.json 매니페스트와 하나 이상의 HDL 파일로 구성됩니다. 서버는 시작 시 이를 자동으로 발견하고, 가져오기 후에는 다시 로드합니다.

형식을 보여주기 위해 두 개의 참조 코어(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 파일)를 발견하면 이를 자동으로 사용하여 더 풍부한 파라미터 및 포트 정보를 제공합니다. 허용된 라이선스를 가진 저장소만 허용됩니다.

코어 기여하기

이 저장소에 코어를 추가하는 PR을 열지 마세요. 대신:

1. HDL 저장소를 fpga 토픽과 MIT 라이선스로 GitHub에 게시하세요

2. 선택 사항으로 더 풍부한 메타데이터를 위해 FuseSoC CAPI2 .core 파일을 추가하세요

3. 그러면 누구나 import_github_core("you/your-core")를 직접 사용할 수 있습니다

이렇게 하면 서버가 가벼워지고 커뮤니티가 GitHub에서 자연스럽게 성장할 수 있습니다.

합성 대상

place_and_route에 사용되는 일반적인 device/package 값:

LiteX

LiteX는 다양한 FPGA 보드를 대상으로 할 수 있는 Python SoC 프레임워크입니다. fpgaZeroMCP는 세 가지 전용 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 디렉터리를 가리키도록 설정하는 두 가지 방법이 있습니다:

환경 변수:

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 도구가 필요합니다. 누락된 도구가 필요한 테스트는 자동으로 건너뜁니다.

메모리 사용량 줄이기

서버는 stdio 전송에서 세션당 1개 프로세스로 실행되는 하위 프로세스입니다(Claude Desktop 같은 MCP 클라이언트가 이 방식으로 실행합니다). 각 세션은 Linux에서 유휴 상태일 때 약 60-90MB의 RSS를 차지하며, 대부분 Python 인터프리터와 종속성에서 비롯됩니다.

동시에 여러 MCP 세션을 실행하는 경우 MCP 클라이언트를 시작하기 전에 다음 환경 변수를 설정하세요:

# Linux — reduces glibc malloc arena fragmentation (can save 10-20 MB per session)
export MALLOC_ARENA_MAX=2

# Strip bytecode position annotations from tracebacks (saves a few MB)
export PYTHONNODEBUGRANGES=1

# Skip .pyc cache files (no memory impact, avoids disk writes)
export PYTHONDONTWRITEBYTECODE=1

이는 코드 변경 없이 적용할 수 있으며 완전히 투명합니다.

환경 변수

독립 실행 / 스크립팅

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를 참조하세요.