vunit-mcp

Servidor MCP (stdio) que permite a un LLM/agente manejar un proyecto VUnit (pruebas unitarias HDL) de principio a fin: listar pruebas, compilar, ejecutar e inspeccionar informes y registros por prueba.

VUnit no tiene una CLI independiente y VUnit.main() llama a sys.exit(), por lo que el servidor nunca ejecuta vunit en el proceso: lo lanza al run.py del propio proyecto, exactamente como lo haría un humano. Una excepción deliberada: vunit_test_dependencies construye un modelo de proyecto en el proceso para responder "¿qué archivos necesito para implementar esta prueba?". vunit-hdl es una dependencia dura de este paquete, por lo que la importación siempre está disponible; aun así, se importa de forma perezosa, solo cuando se llama a esa herramienta.

Logo

Logotipos candidatos, todos basados en la insignia oficial de VUnit (azul #0c479d, anillo blanco, V gruesa). Las fuentes SVG están en logos/; los PNG son vistas previas de 400×400.

Related MCP server: Lupa MCP Server

Configuración

uv venv .venv
uv pip install -e .            # installs vunit-mcp + mcp + pydantic + vunit-hdl
# compile/run also need a simulator, in the env that runs run.py
# (default: this same venv):
uv pip install ghdl

Configuración (variables de entorno)

Configuración del cliente MCP (Claude Code)

{
  "mcpServers": {
    "vunit": {
      "command": "/home/sebbe/git/vunit-mcp/.venv/bin/vunit-mcp",
      "env": {
        "VUNIT_MCP_PROJECT_DIR": "/path/to/your/vunit/project"
      }
    }
  }
}

O con MCP Inspector para pruebas manuales:

VUNIT_MCP_PROJECT_DIR=/path/to/project npx @modelcontextprotocol/inspector \
  /home/sebbe/git/vunit-mcp/.venv/bin/python -m vunit_mcp

Habilidad

Este repositorio incluye una habilidad de agente, skills/vunit-mcp/SKILL.md, que le dice al LLM cuándo y cómo usar las herramientas: qué herramienta responde a cada solicitud, recetas de flujo de trabajo ("¿por qué falló la prueba X?" → vunit_get_test_log), el formato de nombre de prueba lib.entity[.proc] y la configuración VUNIT_MCP_*. Instálala junto al servidor para que el agente la recoja automáticamente.

Claude Code

El enlace simbólico mantiene el checkout del repositorio como única fuente de verdad (copia con cp -r si prefieres una instalación estática):

# personal — available in every project
ln -s /path/to/vunit-mcp/skills/vunit-mcp ~/.claude/skills/vunit-mcp

# or project-local — available only in that project
mkdir -p <your-project>/.claude/skills
ln -s /path/to/vunit-mcp/skills/vunit-mcp <your-project>/.claude/skills/vunit-mcp

Maki

Maki carga las habilidades desde el mismo directorio ~/.claude/skills/:

ln -s /path/to/vunit-mcp/skills/vunit-mcp ~/.claude/skills/vunit-mcp

Herramientas

Caché de exportación

vunit_export_json y vunit_test_dependencies no re-ejecutan run.py --export-json en cada llamada: el modelo exportado se escribe en <project>/.vunit-mcp-cache/export.json junto con una huella de sus entradas, y se sirve desde ese archivo mientras la huella coincida. La caché se invalida cuando:

• cambia el mtime o el tamaño de cualquier archivo fuente registrado, o el archivo desaparece;

• run.py en sí cambia (cubre agregar/eliminar/reubicar archivos);

• cambian VUNIT_MCP_PYTHON, VUNIT_MCP_SIMULATOR o VUNIT_MCP_EXTRA_ARGS.

Los archivos que coinciden con VUNIT_MCP_FINGERPRINT_EXCLUDE (globos fnmatch separados por comas sobre el nombre del archivo o la ruta relativa al proyecto, o un nombre de directorio) están exentos de la primera regla: su mtime/tamaño no se rastrean, para archivos generados o volátiles cuyas reescrituras agitarían la caché. Su nombre y existencia aún se rastrean, por lo que agregar o eliminar uno invalida como de costumbre.

Para forzar una exportación nueva, elimina .vunit-mcp-cache/export.json. El modelo de proyecto en el proceso utilizado por vunit_test_dependencies se almacena en caché adicionalmente, en memoria, con clave por contenido de exportación.

Andamiaje interno

Algunas preguntas de VUnit no se pueden responder a través de la CLI del propio run.py del proyecto — por ejemplo, "¿qué archivos necesito para implementar esta prueba?". Para esas, vunit-mcp construye un proyecto VUnit en el proceso ("el andamiaje") a partir del modelo --export-json en caché: una instancia real de VUnit con las bibliotecas y archivos fuente del proyecto registrados, utilizada solo para llamar a la API interna de VUnit (hoy get_implementation_subset a través de vunit_test_dependencies; más consultas internas se basarán en ella).

El andamiaje nunca se ejecuta a través de la CLI: el modelo de exportación no contiene todos los detalles específicos del run.py del usuario (opciones personalizadas, atributos de prueba, requisitos, …), por lo que cualquier cosa que compile o ejecute debe pasar por el run.py del propio proyecto. La instancia en el proceso vive en project_model.InternalProject, se almacena en caché en memoria por contenido de exportación y usa <project>/.vunit-mcp-cache como su directorio de trabajo (nunca el vunit_out del proyecto, que VUnit borraría).

Política de tamaño de registros

La salida de las herramientas está deliberadamente limitada para que sea amigable para el LLM — los registros crudos nunca se vuelcan completos:

• vunit_get_test_log devuelve las últimas 100 líneas por defecto y lo dice (por ejemplo, "mostrando las últimas 100 de 3421 líneas"); aumenta lines para más. Incluso una lectura explícita "completa" está limitada a ~24 KB (la cola del archivo).

• vunit_compile devuelve una cola de 10 líneas en éxito y un extracto de líneas de error (líneas de error/fatal/fallo + 2 líneas de contexto) en fallo.

• Todos los demás respaldos de salida cruda (run.py fallido, salida no analizable) se truncan a 4 000 caracteres, manteniendo el final donde viven los errores y las líneas de resultado.

• vunit_run_tests / vunit_get_report devuelven el resumen JUnit analizado (recuentos + nombres de pruebas fallidas) en lugar de la salida cruda.

• vunit_export_json incluye el JSON solo por debajo de 8 000 caracteres; por encima devuelve recuentos + listas de nombres de archivos/pruebas.

• vunit_list_files / vunit_export_json listan solo los archivos del proyecto; las fuentes de biblioteca integradas de VUnit (archivos de paquete instalados) se resumen como un recuento, ya que son estables y no forman parte del proyecto.

Desarrollo

uv pip install -e ".[dev]"
uv run pytest tests/          # pure parsers — no simulator required
uv run ruff check src/ tests/
uv run mypy src/vunit_mcp/