schematic-mcp

Contexto de esquemas de hardware para agentes de IA mediante MCP.

schematic-mcp permite que los agentes compatibles con MCP inspeccionen esquemas de hardware como datos eléctricos estructurados, en lugar de tratarlos como capturas de pantalla o grandes bloques de texto.

Estado: V0.1 / alpha. El primer adaptador apunta a archivos .kicad_sch modernos de KiCad.

Por qué existe esto

Un agente de IA que escribe firmware a menudo necesita respuestas como:

• ¿Qué pin del ESP32 está conectado a SENSOR_OUT?

• ¿Qué está conectado a U4.GPIO12?

• ¿Qué dispositivos comparten esta red I2C?

• ¿Cuáles son todos los pines y las redes resueltas en la MCU?

• ¿Coincide realmente el mapa de GPIO asumido por el firmware con el esquema?

El servidor analiza el archivo EDA de forma determinista, construye un modelo canónico de componentes/pines/redes y expone ese modelo a través de herramientas y recursos de MCP.

El principio de diseño es conservador: cuando la conectividad no puede resolverse con confianza, se muestra una advertencia en lugar de inventar una conexión eléctrica.

Enfoque de diseño

schematic-mcp es intencionadamente una capa de contexto de hardware basada en archivos, no un servidor de automatización de GUI EDA de propósito general. Los flujos de trabajo normales de lectura/consulta de KiCad no requieren una aplicación KiCad en ejecución. Los adaptadores específicos de EDA producen un grafo eléctrico canónico, mientras que el contrato MCP orientado al agente permanece neutral en cuanto al formato.

Eso hace que el proyecto sea complementario a la automatización de editor/IPC: las herramientas de editor son valiosas para cambios de diseño interactivos, mientras que schematic-mcp se centra en hechos de hardware deterministas que los agentes de codificación, los sistemas de CI y los futuros adaptadores de EDA pueden consumir. La verificación firmware ↔ esquema es un primer caso de uso concreto.

Consulta docs/project-positioning.md para conocer los límites del proyecto y la tesis del ecosistema.

Related MCP server: mcp-kicad-sch-api

Características de V0.1

• Analizar archivos S-expression .kicad_sch modernos de KiCad

• Leer componentes, referencias, valores e IDs de biblioteca

• Resolver la geometría de pines de biblioteca en coordenadas de esquema

• Seleccionar pines según la unidad KiCad activa para símbolos de múltiples unidades

• Construir la conectividad a partir de cables, etiquetas y uniones

• Resolver redes con nombre y anónimas

• Inspeccionar un componente o pin

• Trazar un pin hasta todos los extremos en la misma red eléctrica

• Generar mapas de pines de MCU compactos

• Comparar las expectativas de pines del firmware con las redes del esquema por número de pin físico o nombre de pin simbólico

• Exponer el modelo canónico actual como recursos MCP

• Restringir el acceso al sistema de archivos con SCHEMATIC_MCP_ROOT o --root

• Ejecutar localmente sobre stdio o Streamable HTTP

• Pruebas automatizadas de analizador, grafo y límites del sistema de archivos en GitHub Actions

Herramientas MCP

Recursos:

• schematic://current/summary

• schematic://current/model

Instalación desde GitHub

Se requiere Python 3.10+. Hasta que se publique el primer lanzamiento en el registro de paquetes, la rama main actual se puede instalar directamente desde GitHub:

python -m pip install "git+https://github.com/vonpanda/schematic-mcp.git"
schematic-mcp --help

Para un uso de producción reproducible, fija una etiqueta de lanzamiento o un commit en lugar de seguir una rama de desarrollo sin fijar. El primer lanzamiento empaquetado se sigue en issue #8.

Instalación para desarrollo

git clone https://github.com/vonpanda/schematic-mcp.git
cd schematic-mcp
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

El proyecto usa la línea estable v2 del SDK oficial de MCP para Python.

Ejecución

stdio local

schematic-mcp

o:

python -m schematic_mcp

Puedes restringir los archivos legibles sin establecer una variable de entorno:

schematic-mcp --root /absolute/path/to/your/hardware-projects

Prueba el fixture incluido

El repositorio contiene un pequeño esquema KiCad sintético que es seguro para demos y pruebas:

schematic-mcp --root "$PWD/examples"

Entonces un cliente compatible con MCP puede llamar:

open_schematic("minimal.kicad_sch")
schematic_summary()
list_components()
trace_signal("U1", "1")

El ejemplo debería resolver U1.1 en SENSOR_OUT y mostrar U2.1 como otro extremo. Consulta examples/README.md.

Demo de validación firmware ↔ esquema

Un segundo ejemplo sintético demuestra un error de hardware que un agente de codificación no puede detectar de forma segura solo con el código fuente. El firmware intercambia intencionadamente las asignaciones de GPIO de SENSOR_INT y LED_STATUS mientras que el esquema conserva el mapeo eléctrico correcto.

Ejecuta la demo local determinista:

python examples/demo_firmware_validation.py

Extrae el contrato GPIO simple de examples/firmware_with_pin_bug.c, analiza examples/esp32_firmware_validation.kicad_sch e informa de dos coincidencias y dos discrepancias.

A través de MCP, la misma comparación es:

open_schematic("esp32_firmware_validation.kicad_sch")
validate_pinmap(
  "U1",
  {
    "GPIO8": "I2C_SDA",
    "GPIO9": "I2C_SCL",
    "GPIO12": "LED_STATUS",
    "GPIO13": "SENSOR_INT"
  }
)

Consulta docs/firmware-validation-demo.md para ver el flujo de trabajo completo del agente y el resultado esperado.

Streamable HTTP

schematic-mcp --transport streamable-http --host 127.0.0.1 --port 8000

El endpoint MCP está disponible en http://127.0.0.1:8000/mcp. El host predeterminado es solo de bucle local; no expongas un servidor de desarrollo sin autenticación directamente al Internet público.

Para el MCP Inspector:

mcp dev src/schematic_mcp/server.py

Ejemplo de configuración de cliente MCP

{
  "mcpServers": {
    "schematic": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/schematic-mcp", "run", "schematic-mcp"],
      "env": {"SCHEMATIC_MCP_ROOT": "/absolute/path/to/your/hardware-projects"}
    }
  }
}

Entonces un agente puede llamar:

open_schematic("board/main.kicad_sch")
get_component("U4")
get_mcu_pinmap("U4")
trace_signal("U4", "12")

Seguridad del sistema de archivos

De forma predeterminada, un servidor local puede abrir rutas accesibles para su proceso. Para agentes en los que no confíes plenamente, establece SCHEMATIC_MCP_ROOT o pasa --root a un directorio de proyecto permitido. Los intentos de abrir archivos fuera de él se rechazan, incluidas las rutas que se resuelven fuera de la raíz permitida.

Consulta SECURITY.md para informar sobre vulnerabilidades y obtener orientación de despliegue.

Limitaciones actuales

V0.1 es intencionadamente pequeño. Las hojas jerárquicas secundarias se descubren pero aún no se fusionan recursivamente en un único grafo de hojas. Las construcciones inusuales de múltiples unidades/bibliotecas y las exportaciones de KiCad de terceros aún necesitan fixtures de compatibilidad más amplios. La semántica de bus aún no se reconstruye. PDF, Altium y EasyEDA aún no están implementados.

trace_signal solo sigue la conectividad de red resuelta; no asume que los pines separados dentro de un IC estén conectados eléctricamente. validate_pinmap compara un mapeo esperado explícito; la extracción automática de frameworks de firmware arbitrarios aún no forma parte del analizador principal.

Hoja de ruta

• V0.2 — grafo de proyecto KiCad jerárquico y semántica de bus/red más rica

• V0.3 — adaptador de esquemas PDF/vectorial con metadatos de confianza

• V0.4 — adaptadores de Altium y EasyEDA

• V0.5 — contexto de hoja de datos y razonamiento de reglas eléctricas

• V0.6 — extracción de firmware específica de framework (ESP-IDF/Arduino/Zephyr) y comprobaciones de contrato de pines en CI

• Más adelante — contexto de PCB, BOM, Gerber y fabricación

El objetivo a largo plazo es un servidor de contexto de hardware neutral para agentes de IA.

Contribuciones

Los ingenieros de hardware, los desarrolladores de sistemas embebidos y los usuarios de EDA pueden contribuir más añadiendo fixtures de compatibilidad mínimos, casos límite del analizador, pruebas y flujos de trabajo reales de agentes.

Empieza con CONTRIBUTING.md. Los agentes de codificación y los mantenedores también deberían leer AGENTS.md para conocer los invariantes de arquitectura, las restricciones de seguridad y el bucle de desarrollo esperado. Por favor, nunca contribuyas con esquemas de clientes propietarios a menos que tengas permiso explícito para publicarlos.

Documentación útil para mantenedores/proyecto:

• AGENTS.md — reglas para agentes de codificación y mantenedores

• docs/project-positioning.md — límites del proyecto y valor del ecosistema

• docs/architecture.md — arquitectura de parser/modelo/MCP

• docs/firmware-validation-demo.md — demo de validación firmware ↔ esquema

• examples/README.md — fixtures sintéticos ejecutables

• CHANGELOG.md — historial de lanzamientos

• SECURITY.md — política de seguridad

• docs/oss-readiness.md — lista de verificación de preparación para adopción pública y programas OSS

Licencia y atribución

Licenciado bajo la Apache License 2.0. El uso comercial, la modificación y la redistribución están permitidos según los términos de la licencia. Las redistribuciones deben conservar la información de copyright, licencia y NOTICE aplicable según lo exige Apache-2.0.

Consulta LICENSE y NOTICE.

Desarrollado originalmente bajo SYANKOR.