emic-mcp — el MCP del integrador EMIC

Servidor MCP por stdio que le da a tu cliente de IA (Claude Code, Claude Desktop, Cursor…) las herramientas para crear, programar y compilar soluciones EMIC contra la API de soluciones de emic.io (/api/v1/solutions). Todo en JSON: el modelo nunca ve archivos, rutas ni fuentes del SDK. Grabar y depurar el hardware desde el chat va por el paquete emic-bus (F5): list_ports, detect_modules, program_module (con confirmación), bus_capture, smoke_after_program y save_test_report.

Requisitos

• Node.js 20 o superior.
• Una cuenta en https://emic.io y una de estas dos credenciales:
  • una API key personal creada en https://emic.io/Profile/ApiKeys (scopes solutions:read, solutions:write, compile), configurada como EMIC_API_KEY; o
  • emic-mcp login: abre el navegador, autorizás el MCP (OAuth con PKCE) y guarda las credenciales en ~/.emic/credentials.json (solo tu usuario) con renovación automática.

Instalación

Desde npm (cuando esté publicado):

npx emic-mcp --version

Desde el repo (hoy):

cd emic-mcp
npm install
npm run build
node dist/index.js --version

Configuración en tu cliente

Claude Code (proyecto o usuario), Claude Desktop (claude_desktop_config.json) y Cursor usan el mismo bloque:

{
  "mcpServers": {
    "emic": {
      "command": "npx",
      "args": ["-y", "emic-mcp"],
      "env": { "EMIC_API_KEY": "emic_pat_..." }
    }
  }
}

Con el paquete construido desde el repo, reemplazá command/args por "command": "node", "args": ["C:/ruta/CircuitEMIC/emic-mcp/dist/index.js"]. Si preferís emic-mcp login, omití EMIC_API_KEY.

| Variable | Default | Para qué | |---|---|---| | EMIC_API_KEY | — | API key personal; tiene prioridad sobre el login | | EMIC_SERVER | https://emic.io | base del server (p. ej. https://localhost:7181 en desarrollo) | | EMIC_MCP_MAX_CHARS | 40000 | tope de caracteres por respuesta (se recorta con truncated) | | EMIC_MCP_LOG_LEVEL | warn | debug / info / warn / error; siempre a stderr | | EMIC_MCP_COMPILE_TIMEOUT_SECONDS | 660 | espera máxima de compile | | EMIC_INSECURE_TLS | — | 1 para aceptar el certificado autofirmado de un server local | | EMIC_HOME | ~/.emic | dónde guardar credenciales y hex descargados |

Qué ofrece

Tools (29): catálogo (list_sdks, search_modules, get_module_card, list_element_types, get_element_manifest), proyecto (list_projects, get_project, create_project, delete_project), módulos (add_module, remove_module, get_configurator, configure_module, get_module_resources), programa (read_program, build_program, write_program, edit_program, validate_program, list_data, add_variable, add_array, remove_data_item), build (compile, get_job, list_jobs, cancel_job, download_hex) y get_guide.

Recursos emic://guide/{id}: guia-mcp (flujo y reglas), spec (dialecto de build_program), program-xml, tabs, mensajes, vocabulario, especificacion.

Prompts: crear_solucion, revisar_proyecto, explicar_modulo, depurar.

Detalles de diseño y contratos: INFO/DEV-APP/SOLUTIONS-API/SOLUTIONS_API_F4_MCP.md en el repo.

Guardas

• Identificadores validados antes de salir a la red; tools destructivas anotadas y con confirmación (delete_project exige confirm igual al nombre).
• Escrituras del programa con If-Match automático; si alguien más cambió el programa, el modelo recibe el resumen nuevo en lugar de pisar.
• Errores de la API tal cual los devuelve el server (código, hint, dónde, hallazgos anclados, cuota), nunca un stack.
• El hex se guarda en disco (~/.emic/hex/<proyecto>/<módulo>.hex); al chat solo van sus metadatos.
• Respuestas recortadas al tope configurado (el catálogo de elementos y el XML pueden ser largos).

Desarrollo

npm test          # vitest: cliente, guardas y tools por el protocolo MCP (server en memoria + fetch falso)
npm run typecheck
npm run gen:api   # regenera src/api.d.ts desde openapi/solutions.json
EMIC_SERVER=https://localhost:7181 EMIC_INSECURE_TLS=1 EMIC_API_KEY=... npm run smoke   # flujo real por stdio
EMIC_SERVER=... EMIC_API_KEY=... npm run hw-smoke -- --port COM12            # hardware real, solo lectura (pasarela V3)
EMIC_SERVER=... EMIC_API_KEY=... npm run hw-e2e -- --confirm --port COM12     # hardware real, GRABA el unico modulo del bus (E2E F5)