@zakotoys/dglab-mcp

Inglés | 简体中文 | 日本語

Servidor Model Context Protocol que prioriza la seguridad para el hardware DG-LAB Coyote V2/V3. Conecta Claude Desktop, Cursor, OpenCode, Codex o cualquier cliente MCP al relay WebSocket DG-LAB 4 V4 a través de un proceso stdio local.

La seguridad es lo primero

Este software controla un dispositivo que aplica estimulación eléctrica real a un cuerpo humano. Úsalo solo con consentimiento informado, supervisión humana activa y el dispositivo físico al alcance.

• Límite máximo por defecto: 30/200 (DGLAB_MAX_INTENSITY); los objetivos superiores se rechazan.

• Límite de paso por defecto: 5 (DGLAB_MAX_STEP) para cada comando de subida.

• Watchdog: la salida se pone a cero después de 20 segundos sin un comando ni heartbeat.

• Parada de emergencia: dglab_emergency_stop limpia todos los dispositivos y tareas en cola.

Related MCP server: InstrMCP

Características

• Control en lenguaje natural mediante las herramientas MCP estándar.

• Emparejamiento por QR con la aplicación móvil DG-LAB 4; no se requiere Bluetooth del ordenador.

• Telemetría en vivo de batería, conexión, canal y tareas.

• Ajustes predefinidos integrados, formas de onda personalizadas y archivos .pulse cargados en caliente.

• Límites de seguridad estrictos, salvaguardas de paso, control de telemetría, colas por canal y una concesión de control global.

Requisitos

• Node.js 22 o superior.

• DG-LAB 4 en iOS o Android, con un Coyote V2 o V3 emparejado por Bluetooth.

• Claude Desktop, Cursor, OpenCode, Codex, MCP Inspector u otro cliente MCP.

Inicio rápido

Claude Desktop, Cursor, OpenCode o Codex

Usa este comando de servidor MCP en la configuración del cliente:

{
  "command": "npx",
  "args": ["-y", "@zakotoys/dglab-mcp@latest"]
}

Para clientes Windows que lo requieran, usa cmd:

{
  "command": "cmd",
  "args": ["/c", "npx", "-y", "@zakotoys/dglab-mcp@latest"]
}

Incorpora el objeto anterior en el mapa de servidores MCP del cliente. Ejemplos:

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "dglab": {
      "command": "npx",
      "args": ["-y", "@zakotoys/dglab-mcp@latest"]
    }
  }
}

Cursor (~/.cursor/mcp.json o .cursor/mcp.json):

{
  "mcpServers": {
    "dglab": {
      "command": "npx",
      "args": ["-y", "@zakotoys/dglab-mcp@latest"]
    }
  }
}

OpenCode (opencode.json):

{
  "mcp": {
    "dglab": {
      "type": "local",
      "command": ["npx", "-y", "@zakotoys/dglab-mcp@latest"]
    }
  }
}

Codex (~/.codex/config.toml):

[mcp_servers.dglab]
command = "npx"
args = ["-y", "@zakotoys/dglab-mcp@latest"]

MCP Inspector

npx @modelcontextprotocol/inspector -y @zakotoys/dglab-mcp@latest

Conéctate por stdio y luego llama a dglab_connect para mostrar el código QR de emparejamiento.

Emparejar un dispositivo

1. Llama a dglab_connect desde tu cliente MCP.

2. Escanea el código QR devuelto con la aplicación DG-LAB 4, o abre su enlace de sesión.

3. Llama a dglab_get_status y confirma que el Coyote está emparejado y que la telemetría está actualizada.

4. Empieza con un valor bajo, por ejemplo dglab_set_intensity con target: 3, y luego reproduce una forma de onda. Llama a dglab_disconnect al terminar; primero detiene la salida.

Se pueden conectar varias aplicaciones y dispositivos. Pasa clientId y slotId cuando sea necesario; un objetivo omitido solo se acepta cuando hay exactamente un Coyote compatible disponible.

Herramientas MCP

Una salida distinta de cero requiere un Coyote compatible y emparejado con telemetría conocida. Los errores usan códigos estables como NOT_CONNECTED, AMBIGUOUS_TARGET, SAFETY_LIMIT e INVALID_WAVEFORM.

Configuración

Todas las variables son opcionales:

El límite máximo efectivo del canal es el mínimo entre el límite configurado y todos los límites anunciados por la aplicación o el dispositivo.

Formas de onda externas

Coloca los archivos .pulse en formato oficial directamente en DGLAB_PULSE_DIR:

~/.dglab-mcp/pulses/
  waves.pulse
  my-favourite.pulse

El directorio se vuelve a escanear en cada llamada de listado/reproducción. Los archivos están limitados a 64 KiB y el catálogo acepta como máximo 100 archivos. Los nombres coinciden con los ids y etiquetas integrados sin distinguir mayúsculas ni separadores, pero la coincidencia es exacta, no aproximada.

Desarrollo

npm install
npm run ci          # typecheck, lint, coverage, build, and pack check
npm run build       # compile dist/ and make the CLI executable
npm test
npm run lint:fix

El conjunto de pruebas usa un relay V4 simulado y una aplicación DG-LAB simulada, por lo que no requiere hardware.

Lanzamientos

GitHub Actions publica las etiquetas vX.Y.Z correspondientes con npm Trusted Publishing y procedencia, y luego crea un GitHub Release con notas de changelog generadas automáticamente. Si el flujo de trabajo se vuelve a ejecutar, un Release existente se mantiene sin cambios. Configura el Trusted Publisher del paquete npm como:

• Proveedor: GitHub Actions

• Organización/usuario: zakotoys

• Repositorio: dglab-mcp

• Nombre del archivo del flujo de trabajo: publish.yml

• Entorno: en blanco

• Acción permitida: npm publish

Para un checkout nuevo, inicializa una vez el paquete público con ámbito mientras tienes sesión iniciada en la organización npm:

npm login
npm publish --access public

Luego publica las versiones futuras desde un checkout limpio:

npm version patch   # or minor / major
git push origin main --follow-tags

El flujo de trabajo ejecuta la suite de CI completa y publica solo cuando la etiqueta coincide con la versión en package.json.

Alcance

Este proyecto solo admite Coyote V2/V3 a través del relay DG-LAB 4 V4. El relay V3 heredado, el BLE directo, el transporte HTTP, la GUI, los frames sin procesar y el control de salida de Opossum están fuera del alcance actual.

Licencia

GPL-3.0