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 등) — 대상/장치/패키지/클럭 자동 설정

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

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

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

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

• IP 코어 레지스트리: FuseSoC CAPI2 메타데이터를 사용하여 GitHub에서 실시간 검색 및 가져오기

• 상태 확인: 설치되어 있고 접근 가능한 OSS CAD Suite 도구 확인

목차

• 기능

• 작동 원리

• 전제 조건

• 설치

• 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 설정(설정 → MCP 서버)에 추가:

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

예시 프롬프트

• "I2C 마스터 코어를 찾아서 가져와줘."

• "~/projects/my_fpga에 있는 VHDL 파일을 합성하고 LUT 개수를 알려줘."

• "iCEBreaker 보드용으로 내 프로젝트를 PnR하고 플래싱해줘."

• "더 나은 타이밍을 위해 시드 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. fpga 토픽과 MIT 라이선스로 GitHub에 HDL 저장소를 게시하세요.

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

3. 누구나 import_github_core("you/your-core")를 통해 직접 가져올 수 있습니다.

이렇게 하면 서버가 가볍게 유지되고 커뮤니티가 GitHub에서 유기적으로 성장할 수 있습니다.

합성 대상

place_and_route에 대한 일반적인 장치/패키지 값:

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

환경 변수

독립 실행형 / 스크립팅

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