fpgaZero MCP

Открытый сервер Model Context Protocol, который даёт AI-ассистентам полный инструментарий для FPGA: линт, симуляция, синтез, place-and-route, программирование битстрима и живой реестр IP-ядер на базе GitHub.

Попросите вашего ИИ искать ядра, подтягивать их, линтовать HDL, синтезировать многопроектный VHDL или Verilog с диска, запускать симуляцию, а затем прошивать битстрим на вашу плату — не покидая чат.

Возможности

• Мультиязычность: Verilog, SystemVerilog и VHDL (через ghdl-yosys-plugin)

• Три режима ввода: строка code, словарь files для нескольких файлов, или путь project_dir на диске

• Поддержка файловых списков: files.f/sources.f с +incdir+, +define+ и вложенными директивами -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, сборки Xilinx через LiteX, структурированный разбор логов Vivado в build_status

• Разбор вердикта симуляции: PASS/FAIL обнаружение паттернов UVM с VCD-сводкой

• Фоновые сборки: длительные синтез/PnR с опросом статуса и строгим allowlist только EDA-команд

• Параллельные запросы: ping, статус сборки и cancel обрабатываются, пока медленный вызов инструмента ещё выполняется; notifications/cancelled прерывает выполняющийся вызов

• Машиночитаемые результаты: structuredContent на результатах инструментов (MCP 2025-06-18) и единая таксономия error_code для ретраев/фолбэков

• Уведомления о прогрессе: notifications/progress на этапах синтеза, place-and-route и LiteX, когда клиент отправляет requestToken

• Реестр IP-ядер: живой поиск и импорт из GitHub с метаданными FuseSoC CAPI2

• Проверка здоровья: определяет, какие инструменты 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-сервер запускается как локальный подпроцесс. Ваш ИИ вызывает его инструменты через JSON-RPC (stdio). Сервер выполняется через Yosys, nextpnr, iverilog, Verilator и другие из OSS CAD Suite — а также может подтягивать открытые исходники FPGA прямо с GitHub.

Предварительные требования

Добавьте 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-ядро master и импортируй его."

• "Синтезируй VHDL-файлы в ~/projects/my_fpga и скажи мне количество LUT."

• "PnR моего проекта для платы iCEBreaker, затем прошей."

• "Запусти place-and-route с сидом 42 для попытки улучшить тайминг."

• "Пройдись линтом по этому Verilog и исправь ошибки."

• "Симулируй этот FIFO и скажи, прошёл ли тестбенч."

• "Отформатируй этот SystemVerilog-файл."

• "Какие инструменты OSS CAD у меня установлены?"

Инструменты

Качество HDL

Маршрут проектирования

Реестр IP-ядер

LiteX

Управление сборкой

Сервер / реестр

Реестр IP-ядер

Ядра живут в cores/<имя>/ — манифест 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})

Сервер автоматически использует CAPI2 .core-файлы FuseSoC, когда находит их в репозитории, что даёт более богатую информацию о параметрах и нагрузке. Принимаются только репозитории с разрешённой лицензией.

Добавление ядра

Не открывайте PR с добавлением ядер в этот репозиторий. Вместо этого:

1. Опубликуйте свой HDL-репозиторий на GitHub с темой fpga и лицензией MIT

2. По желанию добавьте FuseSoC CAPI2 .core для более богатых метаданных

3. Любой может затем напрямую сделать import_github("you/your-core")

Это сохраняет сервер лёгким и даёт сообществу расти на GitHub.

Цели синтеза

Общие значения корпуса для place_and_route:

| Корпус | device / пакет | | Имя | строка | ice40 | hx1k hx8k up5k lp1k | tq144 qn84 sg48 cm48 | | ecp5 | 25k 85k | CABGA256 CABGA381 | | nexus | LIFCL-40-9BG400 | (встроено в строку устройства) | | gowin | GW1N-UV4LQ144C5/I5 | (встроено в строку устройства) |

LiteX

LiteX — это Python SoC-фреймворк для многих FPGA-плат. fpgaZeroMCP предоставляет три выделенных инструмента LiteX, а также принимает backend="litex" в synthesize и place_and_route.

# 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"

Конфигурационный файл (~/.фотографии_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-идентификаторы через запятую):

# 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"

Идентификаторы лицензий соответствуют нотации SPDX. Проверка выполняется при импорте; search_github_cores возвращает результаты независимо от лицензии, чтобы вы могли провести оценку перед импортом.

Тестирование

pip install -e ".[dev]"
python -m pytest tests/ -v

Для некоторых тестов требуются инструменты OSS CAD Suite в PATH. Тесты, которым не хватает нужных инструментов, автоматически пропускаются.

Снижение объёма памяти

Сервер запускается как субпроцесс в режиме «один процесс на сессию» через stdio transport (именно так его запускают MCP-клиенты вроде Claude Desktop). Каждая сессия занимает ~60–90 МБ RSS в состоянии простоя на Linux, в основном за счёт интерпретатора 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.