fpgaZeroMCP

Un servidor de Model Context Protocol de código abierto que proporciona a los asistentes de IA una cadena de herramientas FPGA completa: lint, simular, sintetizar, place-and-route, programar el bitstream y un registro de núcleos IP en vivo respaldado por GitHub.

Pide a tu IA que busque núcleos, los importe, realice linting de HDL, sintetice un proyecto VHDL o Verilog de varios archivos desde el disco, ejecute una simulación y luego grabe el bitstream en tu placa, todo sin salir de tu ventana de chat.

Características

• Multilenguaje: Verilog, SystemVerilog y VHDL (vía ghdl-yosys-plugin)

• Tres modos de entrada: cadena code en línea, diccionario files de varios archivos o ruta project_dir en el disco

• Soporte de listas de archivos: files.f/sources.f con directivas +incdir+, +define+ y -f anidadas

• Preajustes de placa: 11 placas integradas (iCEBreaker, ULX3S, TinyFPGA BX, Tang Nano, etc.) — establece automáticamente el objetivo/dispositivo/paquete/reloj

• Detección automática de restricciones: encuentra .pcf/.lpf/.pdc/.cst en el directorio de tu proyecto

• Programación de bitstream: grabación vía iceprog (iCE40) o openFPGALoader (ECP5/Gowin/Nexus)

• Análisis de veredicto de simulación: detección de patrones PASS/FAIL/UVM con resumen de señales VCD

• Compilaciones en segundo plano: síntesis/PnR de larga duración con sondeo de estado y una lista blanca estricta de comandos solo para EDA

• Registro de núcleos IP: búsqueda e importación en vivo desde GitHub con metadatos CAPI2 de FuseSoC

• Verificación de estado: descubre qué herramientas de OSS CAD Suite están instaladas y accesibles

Tabla de contenidos

• Características

• Cómo funciona

• Requisitos previos

• Instalación

• Configuración del cliente MCP

• Herramientas

• Registro de núcleos IP

• Objetivos de síntesis

• LiteX

• Repositorios de núcleos locales

• Pruebas

• Variables de entorno

• Autónomo / Scripting

• Esquema core.json

• Licencia

Cómo funciona

Your AI assistant  <-->  fpgaZeroMCP (stdio MCP server)  <-->  OSS tools
                                    |
                           cores/   registry on GitHub
                           (uart_tx, fifo + any imported)

El servidor MCP se ejecuta como un subproceso local. Tu IA llama a las herramientas a través de JSON-RPC (stdio). El servidor invoca a Yosys, nextpnr, iverilog, Verilator y otros de OSS CAD Suite, y puede extraer núcleos FPGA de código abierto directamente desde GitHub.

Requisitos previos

Agrega OSS CAD Suite a tu PATH después de la instalación. Todos los envoltorios de herramientas se degradan correctamente si falta una herramienta.

Acceso a la API de GitHub

Las solicitudes a la API de GitHub no están autenticadas por defecto y están sujetas a límites de tasa. Establece un token de acceso personal para aumentar los límites:

# Linux/macOS
export GITHUB_TOKEN=ghp_...

# Windows (PowerShell)
$env:GITHUB_TOKEN = "ghp_..."

Instalación

git clone https://github.com/lcapossio/fpgaZeroMCP
cd fpgaZeroMCP
pip install -e .

Configuración del cliente MCP

Claude Desktop

Agrega a claude_desktop_config.json:

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

VS Code (GitHub Copilot)

Agrega a .vscode/mcp.json en tu espacio de trabajo:

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

Cursor / Windsurf

Agrega a tu configuración de MCP (Settings → MCP Servers):

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

Ejemplos de prompts

• "Búscame un núcleo maestro I2C e impórtalo."

• "Sintetiza los archivos VHDL en ~/projects/my_fpga y dime el recuento de LUT."

• "Haz PnR de mi proyecto para la placa iCEBreaker, luego grábalo."

• "Ejecuta place-and-route con semilla 42 para intentar mejorar la temporización."

• "Haz linting de este Verilog y corrige cualquier error."

• "Simula este FIFO y dime si el banco de pruebas pasó."

• "Formatea este archivo SystemVerilog."

• "¿Qué herramientas de OSS CAD Suite tengo instaladas?"

Herramientas

Calidad de HDL

Flujo de diseño

Registro de núcleos IP

LiteX

Gestión de compilaciones

Servidor / registro

Registro de núcleos IP

Los núcleos residen en cores/<name>/ — un manifiesto core.json y uno o más archivos HDL. El servidor los descubre automáticamente al iniciar y los recarga después de cualquier importación.

Se incluyen dos núcleos de referencia (uart_tx, fifo) para demostrar el formato. El registro no está destinado a crecer aquí — está impulsado por GitHub.

Obtención de núcleos en tiempo de ejecución

# 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})

El servidor utiliza automáticamente metadatos CAPI2 de FuseSoC (archivos .core) cuando se encuentran en el repositorio, proporcionando información más rica sobre parámetros y puertos. Solo se aceptan repositorios con una licencia permitida.

Contribuir con un núcleo

No abras PRs agregando núcleos a este repositorio. En su lugar:

1. Publica tu repositorio HDL en GitHub con el tema fpga y una licencia MIT

2. Opcionalmente, agrega un archivo .core de FuseSoC CAPI2 para obtener metadatos más ricos

3. Cualquiera puede entonces hacer import_github_core("you/your-core") directamente

Esto mantiene el servidor ligero y permite que la comunidad crezca orgánicamente en GitHub.

Objetivos de síntesis

Valores comunes de dispositivo/paquete para place_and_route:

LiteX

LiteX es un framework SoC de Python que puede apuntar a muchas placas FPGA. fpgaZeroMCP expone tres herramientas LiteX dedicadas y también acepta backend="litex" en synthesize y 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"])

Repositorios de núcleos locales

Puedes apuntar el registro a tus propios directorios HDL locales de dos maneras:

Variable de entorno:

Linux/macOS (separado por dos puntos):

export USERCORES_PATH=/home/you/my-cores:/home/you/work-cores

Windows (separado por punto y coma, PowerShell):

$env:USERCORES_PATH = "C:\Users\you\my-cores;C:\Users\you\work-cores"

Archivo de configuración (~/.fpgazero_mcp/config.json):

{
  "core_paths": [
    "/home/you/my-cores",
    "/home/you/work-cores"
  ]
}

Todas las rutas se escanean al inicio junto con el directorio cores/ integrado.

Licencias permitidas

Por defecto, import_github_core acepta repositorios con cualquiera de estas licencias SPDX:

MIT, BSD-2-Clause, BSD-3-Clause, Apache-2.0, ISC, GPL-2.0, GPL-3.0, LGPL-2.1, LGPL-3.0

Anula con la variable de entorno FPGAZERO_ALLOWED_LICENSES (IDs SPDX separados por comas):

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

Los IDs de licencia siguen la notación SPDX. La verificación se realiza en el momento de la importación; search_github_cores devuelve resultados independientemente de la licencia para que puedas evaluar antes de importar.

Pruebas

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

Algunas pruebas requieren herramientas de OSS CAD Suite en el PATH. Las pruebas que necesitan herramientas faltantes se omiten automáticamente.

Variables de entorno

Autónomo / Scripting

La API de Python se puede utilizar directamente sin un cliente 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

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

Autor

Leonardo Capossio (bard0) — hello@bard0.com

Licencia

MIT — ver LICENSE.