fpgaZeroMCP

Un servidor de código abierto Model Context Protocol que brinda a los asistentes de IA una cadena de herramientas FPGA completa: lint, simulación, síntesis, place-and-route, programación del bitstream y un registro de núcleos IP en vivo respaldado por GitHub.

Pídele a tu IA que busque núcleos, los importe, aplique lint al HDL, sintetice un proyecto VHDL o Verilog de varios archivos desde el disco, ejecute una simulación y luego cargue el bitstream en tu placa, todo sin salir de tu ventana de chat.

Características

• Multilenguaje: Verilog, SystemVerilog y VHDL (mediante ghdl-yosys-plugin)

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

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

• Ajustes predefinidos de placa: 11 placas integradas (iCEBreaker, ULX3S, TinyFPGA BX, Tang Nano, etc.) — establece target/device/package/clock automáticamente

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

• Programación de bitstream: graba mediante iceprog (iCE40) u openFPGALoader (ECP5/Gowin/Nexus/Xilinx)

• Vivado: ejecuciones por lotes mediante start_build, compilaciones de Xilinx a través de LiteX, análisis estructurado de registros de Vivado en build_status

• Análisis de veredictos 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 estricta lista blanca de comandos solo EDA

• Solicitudes concurrentes: ping, estado de compilación y cancelación se responden mientras una llamada de herramienta lenta sigue en ejecución; notifications/cancelled aborta una llamada en curso

• Resultados legibles por máquina: structuredContent en los resultados de las herramientas (MCP 2025-06-18) y una taxonomía uniforme de error_code para decisiones de reintento/fallback

• Notificaciones de progreso: notifications/progress en los límites de fase de ejecuciones de síntesis, place-and-route y LiteX cuando el cliente envía un progressToken

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

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

Related MCP server: vivado-mcp-agent

Tabla de contenido

• 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

• Uso independiente / Scripting

• Esquema de 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 invoca herramientas a través de JSON-RPC (stdio). El servidor recurre a Yosys, nextpnr, iverilog, Verilator y otras herramientas de OSS CAD Suite — y puede descargar núcleos FPGA de código abierto directamente desde GitHub.

Requisitos previos

Añade 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 de forma predeterminada y están sujetas a límites de tasa. Configura 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

Añade a claude_desktop_config.json:

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

VS Code (GitHub Copilot)

Añade 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

Añade a tu configuración de MCP (Configuración → Servidores MCP):

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

Ejemplos de prompts

• "Encuentra 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 y luego grábalo."

• "Ejecuta place-and-route con la semilla 42 para intentar mejorar el timing."

• "Aplica lint a este Verilog y corrige los errores."

• "Simula este FIFO y dime si el testbench 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 se encuentran en cores/<name>/ — un manifiesto core.json y uno o más archivos HDL. El servidor los descubre automáticamente al iniciarse 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á pensado para 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 los metadatos de FuseSoC CAPI2 (archivos .core) cuando los encuentra en el repositorio, lo que proporciona información más detallada sobre parámetros y puertos. Solo se aceptan repositorios con una licencia permitida.

Cómo contribuir con un núcleo

No abras PRs que añadan 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, añade un archivo .core de FuseSoC CAPI2 para obtener metadatos más ricos

3. Cualquiera puede entonces ejecutar 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 device/package para place_and_route:

LiteX

LiteX es un framework de SoC en 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 integrado cores/.

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

Sobrescribe con la variable de entorno FPGAZERO_ALLOWED_LICENSES (identificadores 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 identificadores de licencia siguen la notación SPDX. La comprobación se realiza en el momento de la importación; search_github_cores devuelve resultados independientemente de la licencia para que puedas evaluarlos antes de importar.

Pruebas

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

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

Reducción de la huella de memoria

El servidor se ejecuta como un subproceso por sesión bajo transporte stdio (así es como los clientes MCP como Claude Desktop lo lanzan). Cada sesión ocupa ~60-90 MB de RSS en reposo en Linux, principalmente por el intérprete de Python y las dependencias.

Si ejecutas muchas sesiones MCP concurrentes, establece estas variables de entorno antes de lanzar tu cliente 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

Estos cambios no requieren código y son totalmente transparentes.

Variables de entorno

Uso independiente / Scripting

La API de Python se puede usar 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 de 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.