coyote-mcp

Console MCP server for DG-LAB Coyote 3.0 on Node.js.

What it does:

• Starts a DG-LAB-compatible WebSocket bridge for the mobile app.
• Generates a QR image file so the app can pair by scanning it.
• Can run in a demo mode where no real app or device is connected, but MCP tools still behave like a live session.
• Can run either as an MCP stdio server for npx-based clients or as a local Streamable HTTP endpoint.
• Provides English resources, prompts, and read/write tools for connection status, strength control, pulse playback, queue clearing, and raw app commands.
• Supports higher-level timed game scenarios built from multi-step action timelines.

Quick start with npx

npx -y coyote-mcp

By default the package starts in MCP stdio mode, which is the mode expected by most desktop MCP clients.

Server logs and pairing instructions are written to stderr so they do not break the MCP protocol on stdout.

If your MCP client hides stderr, call the get_pairing_qr tool or read the coyote://pairing/guide resource to retrieve the current QR image path and pairing payload through MCP itself.

Example MCP client configuration:

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

HTTP mode

If you want to run the bridge as a standalone local HTTP MCP endpoint instead of stdio:

npx -y coyote-mcp --transport http

Or locally from the repo:

npm install
npm run build
npm start

Demo mode

For testing without a physical DG-LAB session:

npx -y coyote-mcp --demo

Or:

COYOTE_DEMO_MODE=true npx -y coyote-mcp

In demo mode the server:

• auto-pairs a virtual app session after startup;
• reports mode: "demo" in connection status;
• simulates strength acknowledgements, pulse acceptance, queue clearing, reconnect after QR rotation, and basic feedback events;
• never talks to a real phone or device.

Default HTTP endpoints:

• MCP: http://127.0.0.1:8869/mcp
• DG-LAB WebSocket bridge: ws://<your-lan-ip>:8765/<controller-id>

Pairing flow

1. Start the server.
2. Scan the generated QR image with the DG-LAB app.
3. Wait for the console to print App paired successfully.
4. In stdio mode, keep the MCP client connected.
5. In HTTP mode, add the MCP endpoint to your AI agent: http://127.0.0.1:8869/mcp

CLI options

• --transport stdio: start as a standard MCP stdio server. This is the default.
• --transport http: expose the local Streamable HTTP MCP endpoint.
• --stdio: shorthand for --transport stdio.
• --http: shorthand for --transport http.
• --demo: enable virtual demo mode with no real DG-LAB app/device.
• --help: print usage information.

Environment variables

• COYOTE_MCP_TRANSPORT: default transport when CLI flags are not provided.
• COYOTE_DEMO_MODE: true/1 enables the virtual demo session.
• MCP_HOST / MCP_PORT / MCP_PATH: local MCP HTTP endpoint settings.
• COYOTE_WS_HOST / COYOTE_WS_PORT: bind address for the DG-LAB WebSocket bridge. By default the server uses the computer's detected LAN IP instead of localhost.
• COYOTE_WS_PUBLIC_ORIGIN: optional public ws:// or wss:// origin used inside the QR code.
• COYOTE_WS_PUBLIC_HOST: optional host used for QR generation when COYOTE_WS_PUBLIC_ORIGIN is not set.
• COYOTE_WS_PROTOCOL: ws or wss for QR generation when COYOTE_WS_PUBLIC_ORIGIN is not set.
• COYOTE_HEARTBEAT_INTERVAL_MS: heartbeat interval sent to the paired app.
• COYOTE_DEFAULT_REPEAT_SECONDS: default pulse resend duration for send_pulse_sequence.
• COYOTE_DEFAULT_REPEAT_HZ: default pulse resend frequency for send_pulse_sequence.

Tooling highlights

• get_active_scenario
• validate_game_scenario
• start_game_scenario
• stop_game_scenario
• get_pairing_qr
• get_connection_status
• get_recent_events
• build_waveform_frames
• refresh_pairing_qr
• set_channel_strength
• adjust_channel_strength
• clear_pulse_queue
• send_pulse_sequence
• stop_all_output
• send_raw_app_command

Complex game scenarios

For richer scene orchestration, the server now exposes scenario tools that work as a timed action runner over the low-level DG-LAB controls.

A scenario is a JSON object with:

• name and optional description
• steps: an ordered array of timeline steps
• each step contains delayMs, optional label, and one or more actions

Supported action types:

• setStrength
• adjustStrength
• clearPulseQueue
• sendPulse
• sendRawCommand
• stopAllOutput

Recommended flow:

1. Generate any pulse frames you need with build_waveform_frames.
2. Validate the timeline with validate_game_scenario.
3. Start it with start_game_scenario.
4. Track progress with get_active_scenario.
5. Cancel it with stop_game_scenario if needed.