@zakotoys/dglab-mcp

v0.1.3

Published

a month ago

Local MCP server bridging desktop AI tools to DG-LAB e-stim hardware through the DG-LAB 4 V4 WebSocket relay, with a hardware safety enforcer.

Downloads

640

0High
0Medium
0Low

ddsrem

@zakotoys/dglab-mcp

English | 简体中文 | 日本語

面向安全的 Model Context Protocol 服务，让 Claude Desktop、Cursor、OpenCode、Codex 或其他 MCP 客户端通过本地 stdio 进程，经 DG-LAB 4 V4 WebSocket 中继控制 DG-LAB Coyote V2/V3 设备。

先阅读安全须知

本软件控制的设备会向人体施加真实电刺激。只应在获得明确知情同意、有人持续监督，并且实体设备始终触手可及的情况下使用。

默认上限：30/200（DGLAB_MAX_INTENSITY），超过的目标会被拒绝。
默认步长：每次增加最多 5（DGLAB_MAX_STEP）。
看门狗：连续 20 秒没有指令或心跳时，所有输出自动归零。
紧急停止：dglab_emergency_stop 会清除所有设备和排队任务。

功能

通过标准 MCP 工具进行自然语言控制。
使用 DG-LAB 4 手机 App 扫码配对；电脑不需要蓝牙。
实时查看电量、连接状态、通道强度和任务状态。
支持内置预设、自定义波形和动态加载 .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 服务命令。macOS 和 Linux：

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

要从支持的来源安装 .pulse 文件，请添加 --preset（或 -p）及其来源。例如，递归导入 GitHub tree：

{
  "command": "npx",
  "args": [
    "-y",
    "@zakotoys/dglab-mcp@latest",
    "--preset",
    "https://github.com/zakotoys/dglab-pulse-collect/tree/main/pulses/pulse-001"
  ]
}

默认情况下，只要下载到的任意 .pulse 文件格式无效，同步就会失败。添加 --skip-invalid-presets 后会忽略错误的波形，只导入来源中的有效文件。下载失败、响应过大和其他来源错误仍会导致同步失败。

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 查看配对二维码。

配对设备

在 MCP 客户端调用 dglab_connect。
使用 DG-LAB 4 App 扫描返回的二维码，或打开返回的会话链接。
调用 dglab_get_status，确认 Coyote 已配对且遥测数据是最新的。
从低强度开始，例如调用 dglab_set_intensity 设置 target: 3，再播放波形。结束时调用 dglab_disconnect，它会先停止输出。

可以同时连接多个 App 和设备。需要时传入 clientId、slotId；省略目标时，只有在恰好存在一个兼容 Coyote 时才会执行操作。

MCP 工具

| 工具 | 用途 | | --- | --- | | dglab_connect | 创建或复用中继会话并返回二维码。 | | dglab_disconnect | 停止所有输出并销毁会话。 | | dglab_get_status | 查看中继、安全、设备、通道和任务状态。 | | dglab_set_intensity | 通过安全校验后设置 A/B 通道目标值。 | | dglab_adjust_intensity | 通过安全校验后按增量调整通道。 | | dglab_list_waveforms | 列出内置和外部波形。 | | dglab_play_waveform | 在限定时长内播放命名波形。 | | dglab_play_custom_waveform | 编译并播放 ramp/hold/pulse/silence 片段。 | | dglab_stop_channel | 停止任务并重置一个通道。 | | dglab_emergency_stop | 立即停止所有通道和任务。 | | dglab_heartbeat | 续期当前控制租约。 |

非零输出必须满足：Coyote 已配对、设备受支持，并且遥测数据已知。错误使用 NOT_CONNECTED、AMBIGUOUS_TARGET、SAFETY_LIMIT、INVALID_WAVEFORM 等稳定代码。

配置

所有变量都是可选的：

| 变量 | 默认值 | 说明 | | --- | --- | --- | | DGLAB_MAX_INTENSITY | 30 | 0-200 强度刻度上的绝对上限。 | | DGLAB_MAX_STEP | 5 | 每条指令允许增加的最大值。 | | DGLAB_HEARTBEAT_TIMEOUT_MS | 20000 | 控制租约的看门狗超时时间。 | | DGLAB_MAX_WAVEFORM_DURATION_MS | 10000 | 波形允许的最大时长。 | | DGLAB_RELAY_URL | wss://trex.dungeon-lab.cn/v4 | DG-LAB V4 中继地址。 | | DGLAB_PULSE_DIR | ~/.dglab-mcp/pulses | 外部 .pulse 文件目录。 |

通道实际可用上限取配置上限与 App/设备公布的全部限制中的最小值。

外部波形

将官方格式的 .pulse 文件放入 DGLAB_PULSE_DIR 的任意层级：

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

每次列出或播放波形时都会递归重新扫描目录。单文件上限为 64 KiB，目录最多加载 100 个文件。名称支持对大小写和分隔符不敏感的精确匹配，不进行模糊匹配。

启动时，--preset <source>... 或 -p <source>... 使用与 npx skills 相同的来源格式：本地路径、 GitHub/GitLab 仓库或 tree 来源、GitHub 简写（owner/repo）、直接 .pulse 下载和 HTTP(S) 目录列表。GitHub 和 GitLab 仓库树通过对应 API 遍历；普通 HTTP 目录会在同源范围内递归爬取。也支持包含 .pulse 文件的直接 git clone 来源。归档 URL 会被识别为 download 来源，但不会解压；请改用直接 .pulse URL。多个来源会按命令行中的顺序依次同步；可以重复使用 --preset/-p 追加来源。服务会在 DGLAB_PULSE_DIR 中生成 manifest.json，记录来源 URL、本地路径和 SHA-256 哈希。后续启动时，如果本地文件仍与清单一致，就不会再次发起网络请求；缺失或被修改的托管文件会重新下载。下载和缓存诊断只写入 stderr， stdout 始终仅用于 MCP JSON-RPC。

开发

npm install
npm run ci          # 类型检查、Lint、覆盖率、构建和打包检查
npm run build       # 编译 dist/ 并设置 CLI 可执行权限
npm test
npm run lint:fix

测试使用模拟的 V4 中继和 DG-LAB App，不需要真实硬件。

发布版本

GitHub Actions 会在匹配的 vX.Y.Z tag 上，通过 npm Trusted Publishing 和 provenance 发布，然后创建 GitHub Release 并自动生成 changelog。重复运行 workflow 时，已有的 Release 会保持不变。npm 包的 Trusted Publisher 配置如下：

Provider：GitHub Actions
Organization/user：zakotoys
Repository：dglab-mcp
Workflow filename：publish.yml
Environment：留空
Allowed action：npm publish

如果 scoped 包尚未存在，先在已登录 npm 组织的本地终端执行一次：

npm login
npm publish --access public

之后从干净工作区发布新版本：

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

Workflow 会执行完整 CI，只有 tag 与 package.json 版本一致时才会发布。

项目范围

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

许可证

GPL-3.0

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@zakotoys/dglab-mcp

先阅读安全须知

功能

环境要求

快速开始

Claude Desktop、Cursor、OpenCode 或 Codex

MCP Inspector

配对设备

MCP 工具

配置

外部波形

开发

发布版本

项目范围

许可证