<div align="center">

DG-MCP

让 Claude Desktop 等 MCP 客户端直接控制 DG-Lab 郊狼 2.0 / 3.0

中文 | English

</div>

这是什么

DG-MCP 把郊狼设备暴露成一组 Model Context Protocol 工具，让任何 MCP 兼容的 LLM 客户端（Claude Desktop、Continue 等）能通过蓝牙直接驱动你的设备——scan / connect / start / stop / adjust_strength / change_wave / burst / design_wave / emergency_stop 全套都是普通的工具调用。

跑在 Node.js 里，通过 stdio 跟客户端通信。基于 @dg-kit/* 中台，跟 DG-Agent / DG-Chat 共享一份协议代码。

状态

• 1.0.0 正式版，已发布到 npm
• v0.1.x 的 Python 实现归档在 archive/0.x-py 分支，PyPI 上仍可下载但不再更新

快速开始

安装

不需要预装，npx 直接拉：

npx dg-mcp --version

或者全局装：

npm install -g dg-mcp

Claude Desktop 配置

打开 Claude Desktop 的配置文件，加入：

{
  "mcpServers": {
    "dg-lab": {
      "command": "npx",
      "args": ["-y", "dg-mcp"]
    }
  }
}

要预加载波形包：

{
  "mcpServers": {
    "dg-lab": {
      "command": "npx",
      "args": ["-y", "dg-mcp", "--waveforms-dir", "/Users/you/wave-pack"]
    }
  }
}

重启 Claude Desktop，对话框里跟 Claude 说"扫描一下郊狼"，它就会调 scan 工具找设备。

CLI 选项

dg-mcp [options]

  --waveforms <path>      启动时加载一个 .pulse 或 .zip 文件（可重复）
  --waveforms-dir <dir>   加载目录下所有 .pulse / .zip
  --library-dir <dir>     用户导入的 / AI 设计的波形持久化到这个目录
  --help, -h
  --version, -v

  环境变量等价：
  DG_MCP_WAVEFORMS        冒号分隔的多路径
  DG_MCP_WAVEFORMS_DIR    同 --waveforms-dir
  DG_MCP_LIBRARY_DIR      同 --library-dir

工具列表

设备控制（来自 @dg-kit/tools）

工具	用途
start	冷启动通道，一次设强度 + 波形
stop	停止通道；省略 channel 停全部
adjust_strength	相对调整强度（±10/步，5s 内最多 2 次）
change_wave	不动强度，仅换波形
burst	短时拉到目标强度后自动回落（5s 内最多 1 次）
design_wave	用 ramp / hold / pulse / silence 段落组合新波形

MCP 专属

工具	用途
scan	扫描附近设备
connect / disconnect	蓝牙连接管理
get_status	当前连接 / 强度 / 波形 / 电池
list_waveforms	列出所有可用波形
load_waveforms	运行时导入新的 .pulse / .zip
emergency_stop	立即归零

安全

• 强度量程是 0-200。冷启动工具自动钳制初始强度 ≤10，请从低强度开始
• 默认软上限是 200；如果你需要更严格的硬限制，让 LLM 客户端策略层加约束
• 设备物理拨轮可以单独叠加强度——MCP 只是输入源，不是绝对天花板
• 任何时候说"紧急停止"，AI 会调 emergency_stop 立即归零

系统要求

• Node.js ≥ 20
• 支持 BLE 的主机（macOS / Linux 走 BlueZ / Windows 配 noble 兼容适配器）
• DG-Lab 郊狼 2.0（D-LAB ESTIM…）或 3.0（47L121…）

macOS

首次跑会弹蓝牙权限申请，允许即可。

Linux

noble 需要 BLE 抓包权限：

sudo setcap cap_net_raw+eip $(eval readlink -f $(which node))

架构

        ┌─────────────────────┐
        │ MCP 客户端           │  Claude Desktop / Continue / ...
        └──────────┬──────────┘
                   │ stdio
        ┌──────────▼──────────┐
        │      dg-mcp         │  本仓库
        ├─────────────────────┤
        │  src/server.ts      │  → 把 @dg-kit/tools 工具定义转 MCP schema
        │  src/coyote-device  │  → DeviceClient，驱动 @dg-kit/protocol
        │  src/waveform-lib   │  → 内置 + .pulse/.zip + JSON 持久化
        │  src/noble-shim     │  → noble Characteristic → CharacteristicLike
        └──────────┬──────────┘
                   │ shared
        ┌──────────▼──────────┐
        │     @dg-kit/*       │  core / protocol / tools / waveforms
        └─────────────────────┘
                   │ BLE
        ┌──────────▼──────────┐
        │  Coyote 2.0 / 3.0   │
        └─────────────────────┘

开发

git clone https://github.com/0xNullAI/DG-MCP.git
cd DG-MCP
npm install
npm run build
npm run dev          # tsx 热重载

相关项目

项目	用途
DG-Kit	共享的 TypeScript 中台（被本项目消费）
DG-Agent	浏览器版 AI 控制器
DG-Chat	多人 P2P 房间

协议

MIT