Content
# DG-LAB Kit Agent Tools
This repository provides two independent Codex Skills: one for directly controlling devices through MCP, and another for developing integrations using the `dglab-kit` SDK.
## Choose Your Use Case Before Installation
The installer or LLM should not install both Skills by default, nor should they depend on each other. If the user does not specify a scenario, ask:
> Do you want Codex to directly connect and control DG-LAB devices, or do you want Codex to help you write integration code using the `dglab-kit` SDK in your project?
| Use Case | Installation Content | Additional Dependencies |
| --- | --- | --- |
| Directly connect, pair, and control devices using natural language | `skills/dglab-control` | Configure the `mcp/` Server in this repository |
| Install and use the SDK in TypeScript/JavaScript projects | `skills/dglab-kit-sdk` | The target project installs `dglab-kit` separately; no MCP from this repository is needed |
| Both scenarios are needed | Install both separately | Configure separately; still no shared state or dependencies |
- MCP Server: Maintains V4 Relay, device connections, target selection, and security restrictions.
- `dglab-control`: Converts natural language into explicit, restricted MCP tool calls.
- `dglab-kit-sdk`: Guides Agents to use the SDK for best practices in connection, pairing, state management, command boundaries, and cleanup.
- Relay: Can connect to remote services or be started by Bun as a built-in service.
> For Agent/LLM integration, read [README_llm.md](README_llm.md) directly, which includes installation diversion, MCP tool conventions, parameters, and security rules.
## Direct Device Control
Recommended to use [Bun](https://bun.sh/):
```bash
cd mcp
bun install
```
Add MCP Server to Codex's `config.toml`, and replace the path with the absolute path of the repository:
```toml
[mcp_servers.dglab]
command = "bun"
args = ["run", "/absolute/path/to/dglab-kit-skill/mcp/src/index.ts"]
startup_timeout_sec = 20
tool_timeout_sec = 30
[mcp_servers.dglab.env]
DGLAB_RELAY_MODE = "remote"
DGLAB_RELAY = "wss://trex.dungeon-lab.cn/v4"
```
Then, copy or link `skills/dglab-control` to the Codex skills directory to use it via `$dglab-control`. This Skill does not depend on `dglab-kit-sdk`.
Node.js 22+ can also connect to a remote Relay:
```toml
command = "npm"
args = ["--prefix", "/absolute/path/to/dglab-kit-skill/mcp", "run", "start:node"]
```
The built-in Relay uses `Bun.serve()`, so it does not support Node.js mode.
Complete usage example:
```text
Create a dglab socket control client using the built-in server v4 protocol. When I send the test message again, temporarily output a 5-second squeeze waveform to channel A with an intensity of 5.
```
## Developing with SDK
Just copy or link `skills/dglab-kit-sdk` to the Codex skills directory, and use `$dglab-kit-sdk` to let the Agent install and use `dglab-kit` in the target project:
```text
Use $dglab-kit-sdk to implement V4 pairing, device selection, and security cleanup for this TypeScript project.
```
This Skill does not call the MCP in this repository and does not depend on `dglab-control`. SDK dependencies should be installed separately by the Agent according to the Bun, pnpm, Yarn, or npm used by the target project.
## Usage
After configuration, you can directly tell the Agent:
- “Use the official server connection.”
- “View devices and select channel A.”
- “Increase channel A by 2.”
- “Set intensity to 10 for 2 seconds.”
- “Play V3 custom waveform `0A0A0A0A00000000`, `0A0A0A0A64646464` for 2 seconds.”
- “Stop.”
The complete process is: connect to Relay → APP scans the code → view devices → explicitly select devices and channels → execute control.
## Built-in Relay
When pairing mobile devices in the same local area network, the Agent can list available addresses and start the built-in Relay. Example configuration:
```toml
[mcp_servers.dglab.env]
DGLAB_RELAY_MODE = "embedded"
DGLAB_EMBEDDED_BIND_HOST = "0.0.0.0"
DGLAB_EMBEDDED_PORT = "9998"
DGLAB_EMBEDDED_PREFIX = "/v4"
DGLAB_EMBEDDED_CONTROLLER_URL = "ws://127.0.0.1:9998/v4"
DGLAB_EMBEDDED_ADVERTISED_URL = "ws://192.168.1.20:9998/v4"
DGLAB_EMBEDDED_ALLOW_NETWORK_EXPOSURE = "true"
```
Replace `192.168.1.20` with the address of the computer running MCP. Both the mobile device and computer need to be on a network that can communicate with each other, and the firewall should allow the corresponding port.
Do not expose the built-in Relay directly to the public internet. Non-loopback listening must be explicitly allowed by the user and provide an `advertisedUrl` accessible to the mobile device.
## Default Security Restrictions
| Item | Default Upper Limit |
| --- | ---: |
| Single intensity change | `5` |
| Temporary intensity | `20` |
| Temporary intensity or waveform duration | `5000 ms` |
| Custom waveform frames | `50` |
You can set stricter values separately through `DGLAB_MAX_DELTA`, `DGLAB_MAX_INTENSITY`, and `DGLAB_MAX_DURATION_MS`.
`dglab_stop` will cancel the current channel's unexecuted operations first; when disconnecting, MCP will try to clean up the channels controlled by this process.
## Project Structure
```text
mcp/ TypeScript stdio MCP Server
src/controller.ts Sessions, devices, queues, and security restrictions
src/relay/ Built-in Bun V4 Relay
skills/dglab-control/ Codex Skill with protocol/security reference
skills/dglab-kit-sdk/ Best practice Skill for developing integrations using dglab-kit SDK
README_llm.md Agent/LLM Integration Manual
```
## Development
```bash
cd mcp
bun run typecheck
```
