dg-lab-mcp-sse-server 1.0.3

package/README.md

@@ -0,0 +1,179 @@
+# DG-LAB MCP SSE Server
+
+基于 MCP (Model Context Protocol) 的 DG-LAB 设备控制服务器，支持通过 AI 助手控制 DG-LAB 设备。
+
+## 功能特性
+
+- **MCP 协议支持**: 通过 SSE (Server-Sent Events) 实现 MCP 协议通信
+- **内置 WebSocket 服务器**: 无需外部 WS 后端，直接与 DG-LAB APP 通信
+- **单端口设计**: HTTP/SSE 和 WebSocket 共享同一端口
+- **波形管理**: 支持解析、保存、发送 DG-LAB 波形数据
+- **持续播放**: 支持波形持续循环播放
+- **会话管理**: 支持设备别名、多设备管理
+
+## 安装
+
+```bash
+# 全局安装
+npm install -g dg-lab-mcp-sse-server
+
+# 或使用 npx 直接运行
+npx dg-lab-mcp-sse-server
+```
+
+## 快速开始
+
+### 直接运行
+
+```bash
+# 使用默认配置
+npx dg-lab-mcp-sse-server
+
+# 设置公网 IP
+PUBLIC_IP=1.2.3.4 npx dg-lab-mcp-sse-server
+
+# 设置端口
+PORT=8080 npx dg-lab-mcp-sse-server
+```
+
+### 配置 MCP 客户端
+
+在 Claude Desktop 或其他 MCP 客户端的配置文件中添加：
+
+```json
+{
+  "mcpServers": {
+    "dg-lab": {
+      "command": "npx",
+      "args": ["dg-lab-mcp-sse-server"],
+      "env": {
+        "PUBLIC_IP": "你的公网IP"
+      }
+    }
+  }
+}
+```
+
+**Windows 配置文件位置**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+**macOS 配置文件位置**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+### 完整配置示例
+
+```json
+{
+  "mcpServers": {
+    "dg-lab": {
+      "command": "npx",
+      "args": ["dg-lab-mcp-sse-server"],
+      "env": {
+        "PUBLIC_IP": "your.public.ip",
+        "PORT": "3323",
+        "CONNECTION_TIMEOUT_MINUTES": "10"
+      }
+    }
+  }
+}
+```
+
+## 环境变量
+
+通过环境变量配置服务器：
+
+| 变量 | 默认值 | 说明 |
+|------|--------|------|
+| `PORT` | 3323 | 服务端口 (HTTP/WebSocket 共享) |
+| `PUBLIC_IP` | (自动检测) | 公网 IP 地址，用于生成二维码。留空则使用本地 IP |
+| `SSE_PATH` | /sse | SSE 端点路径 |
+| `POST_PATH` | /message | POST 端点路径 |
+| `CONNECTION_TIMEOUT_MINUTES` | 5 | 未绑定设备的超时时间（分钟） |
+| `HEARTBEAT_INTERVAL` | 30000 | WebSocket 心跳间隔 (ms) |
+| `STALE_DEVICE_TIMEOUT` | 3600000 | 设备活跃超时 (ms)，默认 1 小时 |
+| `WAVEFORM_STORE_PATH` | ./data/waveforms.json | 波形存储路径 |
+
+## 使用流程
+
+1. **创建设备**: 调用 `dg_create_device` 获取二维码内容
+2. **扫码绑定**: 用户使用 DG-LAB APP 扫描二维码
+3. **检查状态**: 调用 `dg_get_device_status` 确认 `boundToApp: true`
+4. **控制设备**: 使用强度控制或波形控制工具
+
+## 可用工具 (16 个)
+
+### 设备管理
+| 工具 | 说明 |
+|------|------|
+| `dg_create_device` | 创建新设备会话，返回二维码内容 |
+| `dg_list_devices` | 列出所有设备及状态 |
+| `dg_get_device_status` | 获取指定设备的详细状态 |
+| `dg_delete_device` | 删除设备会话 |
+
+### 强度控制
+| 工具 | 说明 |
+|------|------|
+| `dg_set_strength` | 设置 A/B 通道强度 (0-200) |
+| `dg_adjust_strength` | 增量调整强度 |
+| `dg_get_strength` | 获取当前强度值 |
+
+### 波形控制
+| 工具 | 说明 |
+|------|------|
+| `dg_send_waveform` | 发送单次波形 |
+| `dg_start_continuous_playback` | 开始持续播放波形 |
+| `dg_stop_continuous_playback` | 停止持续播放 |
+| `dg_get_playback_status` | 获取播放状态 |
+
+### 波形管理
+| 工具 | 说明 |
+|------|------|
+| `dg_parse_waveform` | 解析 DungeonLab+pulse 格式波形并保存 |
+| `dg_list_waveforms` | 列出所有已保存的波形 |
+| `dg_get_waveform` | 获取波形详情和 hexWaveforms |
+| `dg_delete_waveform` | 删除已保存的波形 |
+
+## 开发
+
+### 从源码运行
+
+```bash
+# 克隆仓库
+git clone https://github.com/admilkjs/sse-dg-lab.git
+cd sse-dg-lab/dg-lab-mcp-server
+
+# 安装依赖
+bun install
+
+# 启动开发服务器
+bun run dev
+
+# 运行测试
+bun test
+```
+
+### 项目结构
+
+```
+src/
+├── index.ts           # 入口文件
+├── cli.ts             # CLI 入口 (npx)
+├── app.ts             # 应用初始化
+├── config.ts          # 配置管理
+├── server.ts          # HTTP/SSE 服务器
+├── ws-server.ts       # WebSocket 服务器
+├── session-manager.ts # 会话管理
+├── tool-manager.ts    # MCP 工具管理
+├── waveform-parser.ts # 波形解析
+├── waveform-storage.ts # 波形存储
+└── tools/
+    ├── device-tools.ts   # 设备管理工具
+    ├── control-tools.ts  # 设备控制工具
+    └── waveform-tools.ts # 波形管理工具
+```
+
+## 许可证
+
+MIT
+
+## 声明
+
+本项目基于 [DG-LAB 开源协议](https://github.com/DG-LAB-OPENSOURCE/DG-LAB-OPENSOURCE) 实现设备通信功能。DG-LAB 开源协议仅供爱好者自由使用设备，未经授权请勿将相关内容用于任何商业用途。

package/dist/app.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @fileoverview 应用初始化模块
+ * @description 封装应用的初始化逻辑，包括依赖注入和模块组装
+ */
+import type { ServerConfig } from "./config";
+import { type MCPServer } from "./server";
+import { ToolManager } from "./tool-manager";
+import { SessionManager } from "./session-manager";
+import { DGLabWSServer } from "./ws-server";
+import { WaveformStorage } from "./waveform-storage";
+/**
+ * 应用实例，包含所有核心组件的引用
+ */
+export interface App {
+    config: ServerConfig;
+    server: MCPServer;
+    toolManager: ToolManager;
+    sessionManager: SessionManager;
+    wsServer: DGLabWSServer;
+    waveformStorage: WaveformStorage;
+    shutdown: () => Promise<void>;
+}
+/**
+ * 创建并初始化应用
+ *
+ * 这个函数负责：
+ * 1. 加载配置
+ * 2. 创建各个核心组件
+ * 3. 注册工具和协议处理器
+ * 4. 设置组件间的回调关系
+ *
+ * @returns 初始化完成的应用实例
+ */
+export declare function createApp(): App;
+/**
+ * 启动应用
+ *
+ * 启动 HTTP 服务器并附加 WebSocket 服务器。
+ *
+ * @param app - 应用实例
+ */
+export declare function startApp(app: App): Promise<void>;
+//# sourceMappingURL=app.d.ts.map

package/dist/app.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAE7C,OAAO,EAAuC,KAAK,SAAS,EAAE,MAAM,UAAU,CAAC;AAE/E,OAAO,EAAE,WAAW,EAAwB,MAAM,gBAAgB,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAI5C,OAAO,EAAE,eAAe,EAAiB,MAAM,oBAAoB,CAAC;AAGpE;;GAEG;AACH,MAAM,WAAW,GAAG;IAClB,MAAM,EAAE,YAAY,CAAC;IACrB,MAAM,EAAE,SAAS,CAAC;IAClB,WAAW,EAAE,WAAW,CAAC;IACzB,cAAc,EAAE,cAAc,CAAC;IAC/B,QAAQ,EAAE,aAAa,CAAC;IACxB,eAAe,EAAE,eAAe,CAAC;IACjC,QAAQ,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,IAAI,GAAG,CA+C/B;AA4HD;;;;;;GAMG;AACH,wBAAsB,QAAQ,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAqBtD"}

package/dist/cli.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview DG-LAB MCP SSE 服务器 CLI 入口
+ * @description 用于 npx 启动的命令行入口
+ */
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA;;;GAGG"}