fpgaZeroMCP

Сервер с открытым исходным кодом Model Context Protocol, который предоставляет ИИ-ассистентам полный набор инструментов FPGA: линтинг, симуляция, синтез, размещение и трассировка, прошивка битстрима, а также реестр 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 и др.) — автоматически устанавливает цель/устройство/корпус/частоту

• Автоматическое обнаружение ограничений: поиск .pcf/.lpf/.pdc/.cst в директории вашего проекта

• Программирование битстрима: прошивка через iceprog (iCE40) или openFPGALoader (ECP5/Gowin/Nexus)

• Парсинг результатов симуляции: обнаружение шаблонов PASS/FAIL/UVM со сводкой сигналов VCD

• Фоновые сборки: длительный синтез/PnR с опросом состояния и строгим списком разрешенных команд EDA

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

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

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

Добавьте OSS CAD Suite в ваш PATH после установки. Все обертки инструментов корректно обрабатывают отсутствие того или иного инструмента.

Доступ к API GitHub

Запросы к API GitHub по умолчанию не аутентифицированы и ограничены по частоте. Установите персональный токен доступа, чтобы увеличить лимиты:

# 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 master и импортируй его."

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

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

• "Запусти размещение и трассировку с 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-репозиторий на GitHub с темой fpga и лицензией MIT

2. Опционально добавьте файл FuseSoC CAPI2 .core для более богатых метаданных

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

Это позволяет серверу оставаться легким и дает сообществу органично расти на GitHub.

Цели синтеза

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

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"

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

# 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. Тесты, которым нужны отсутствующие инструменты, пропускаются автоматически.

Переменные окружения

Автономный режим / Скрипты

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"]
}

Автор

Леонардо Капоссио (bard0) — hello@bard0.com