@zakotoys/dglab-mcp

English | 简体中文 | 日本語

一个以安全为先的 Model Context Protocol 服务器，用于 DG-LAB Coyote V2/V3 硬件。它通过本地 stdio 进程将 Claude Desktop、Cursor、OpenCode、Codex 或任何 MCP 客户端连接到 DG-LAB 4 V4 WebSocket 中继。

安全第一

本软件控制的是向人体传递真实电刺激的设备。请仅在知情同意、有真人监督且实体设备触手可及的情况下使用。

• 默认上限：30/200（DGLAB_MAX_INTENSITY）；更高的目标会被拒绝。

• 默认步进限制：每条向上命令为 5（DGLAB_MAX_STEP）。

• 看门狗：在 20 秒内没有命令或心跳时，输出会被设为零。

• 紧急停止：dglab_emergency_stop 会清除所有设备和排队中的任务。

Related MCP server: InstrMCP

功能

• 通过标准 MCP 工具进行自然语言控制。

• 与 DG-LAB 4 移动应用进行 QR 配对；无需电脑蓝牙。

• 实时的电池、连接、通道和任务遥测。

• 内置预设、自定义波形和热加载的 .pulse 文件。

• 硬性安全上限、步进保护、遥测门控、每通道队列以及全局控制租约。

环境要求

• Node.js 22 或更高版本。

• iOS 或 Android 上的 DG-LAB 4，并已通过蓝牙配对 Coyote V2 或 V3。

• Claude Desktop、Cursor、OpenCode、Codex、MCP Inspector 或其他 MCP 客户端。

快速开始

Claude Desktop、Cursor、OpenCode 或 Codex

在客户端的配置中使用以下 MCP 服务器命令：

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

对于有此需要的 Windows 客户端，请使用 cmd：

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

将上面的对象嵌入到客户端的 MCP 服务器映射中。示例：

Claude Desktop（claude_desktop_config.json）：

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

Cursor（~/.cursor/mcp.json 或 .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

通过 stdio 连接，然后调用 dglab_connect 以显示配对 QR 码。

配对设备

1. 从你的 MCP 客户端调用 dglab_connect。

2. 使用 DG-LAB 4 应用扫描返回的 QR 码，或打开其会话链接。

3. 调用 dglab_get_status，确认 Coyote 已配对且遥测数据为最新。

4. 从低强度开始，例如使用 target: 3 调用 dglab_set_intensity，然后播放波形。完成后调用 dglab_disconnect；它会先停止输出。

可以同时连接多个应用和设备。需要时传入 clientId 和 slotId；仅当恰好有一个兼容的 Coyote 可用时，才接受省略 target 的操作。

MCP 工具

非零输出要求已配对、受支持且具有已知遥测数据的 Coyote。错误使用稳定的错误码，例如 NOT_CONNECTED、AMBIGUOUS_TARGET、SAFETY_LIMIT 和 INVALID_WAVEFORM。

配置

所有变量均为可选：

有效通道上限是配置的限制与应用或设备通告的所有限制中的最小值。

外部波形

将官方格式的 .pulse 文件直接放入 DGLAB_PULSE_DIR：

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

每次 list/play 调用都会重新扫描该目录。文件大小限制为 64 KiB，目录最多接受 100 个文件。名称与内置 id 和标签的匹配不区分大小写和分隔符，但匹配是精确的而非模糊的。

开发

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

测试套件使用模拟的 V4 中继和模拟的 DG-LAB 应用，因此不需要硬件。

发布

GitHub Actions 使用 npm Trusted Publishing 和来源证明发布匹配的 vX.Y.Z 标签，然后创建带有自动生成的变更日志说明的 GitHub Release。如果工作流重新运行，现有的 Release 将保持不变。将 npm 包的 Trusted Publisher 配置为：

• 提供方：GitHub Actions

• 组织/用户：zakotoys

• 仓库：dglab-mcp

• 工作流文件名：publish.yml

• 环境：留空

• 允许的操作：npm publish

对于新的检出，请在登录 npm 组织后，一次性初始化这个 scoped 公共包：

npm login
npm publish --access public

然后从干净的检出中发布后续版本：

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

该工作流会运行完整的 CI 套件，并且仅在标签与 package.json 中的版本匹配时才发布。

范围

本项目仅通过 DG-LAB 4 V4 中继支持 Coyote V2/V3。旧版 V3 中继、直接 BLE、HTTP 传输、GUI、原始帧和 Opossum 输出控制不在当前范围内。

许可证

GPL-3.0