Return to Dark Tower — AI MCP Server

An MCP server that lets AI assistants like Claude, ChatGPT, and Gemini control the physical Return to Dark Tower board game tower via Bluetooth. Connect, calibrate, play sounds, animate lights, rotate drums, break seals, and run dramatic game sequences — all through natural language.

Features

• 31 MCP tools across 6 domains — connection, audio, lights, drums, seals, state & glyphs

• 15 tower state resources — connection status, battery, drum positions, glyphs, seals, audio library, light effects

• 8 game knowledge resources — rules, heroes, items, quests, adversaries, buildings, lore, glossary

• 8 prompt templates — dramatic entrance, victory/defeat sequences, monthly transitions, dungeon runs, battle starts, game master setup, sound browser

• Dual transport — stdio for desktop AI tools, Streamable HTTP for web apps

• Zero custom BLE code — built on UltimateDarkTower adapter pattern

AI Agents

Ready-to-use AI agents for this server and the ultimatedarktower library: 👉 return-to-dark-tower-agents

• Return to Dark Tower agent — system prompt for Claude.ai, ChatGPT, and other web AI tools; knows all 31 tools, 15 resources, and 8 prompts

• Ultimate Dark Tower agent — VS Code / GitHub Copilot coding agent for building apps with the ultimatedarktower npm library

Supported in VS Code (GitHub Copilot), Claude.ai, ChatGPT, and 20+ tools via the AGENTS.md standard.

📚 Table of Contents

• Return to Dark Tower — AI MCP Server

  • ⚡ Quick Start

    • 🌐 For Web AI Chat Apps (Claude.ai, ChatGPT, etc.)

    • 🖥️ For Desktop AI Tools (Claude Desktop, Cursor, VS Code, etc.)

  • What is MCP?

  • Getting Started

    • Prerequisites

    • Install

  • 🖥️ Setup with Your AI Tool

    • Claude Desktop

    • 🎯 Cursor

    • 🐙 VS Code (GitHub Copilot)

    • 🌊 Windsurf

    • ⚡ Zed

    • 🔎 Perplexity (macOS App)

    • 🐋 DeepSeek

    • Summary

  • 🌐 Web-Based AI Chat Apps

    • Start the HTTP Server

    • Claude.ai (Web)

    • ChatGPT / OpenAI

    • Custom Web Applications

  • Available Tools

    • Connection (8 tools)

    • Audio (3 tools)

    • Lights (5 tools)

    • Drums (4 tools)

    • Seals (5 tools)

    • State & Glyphs (7 tools)

  • Available Resources

    • Tower State Resources

    • Game Knowledge Resources

    • Glyph Icon Resources

  • Available Prompts

  • Architecture

  • CLI Options

  • Dependencies

  • Development

  • License

  • Acknowledgments

Related MCP server: matter-mcp-server

⚡ Quick Start

Requires Node.js 18+. Run node --version to check.

🌐 For Web AI Chat Apps (Claude.ai, ChatGPT, etc.)

Step 1 — Open a terminal and start the server:

npx -y mcp-server-return-to-dark-tower --http-only --port 3001

npx fetches the package from npm on first run (cached after that) and starts the server. Keep this terminal open — the server runs as long as the window is open.

Step 2 — Connect your web AI app to the server.

In your AI app's settings, add a new MCP connection pointing at:

http://localhost:3001/mcp

See Web-Based AI Chat Apps for step-by-step instructions for Claude.ai and ChatGPT.

Step 3 — Ask it something like:

"Connect to the tower, calibrate it, then turn on all the north doorway lights."

🖥️ For Desktop AI Tools (Claude Desktop, Cursor, VS Code, etc.)

Step 1 — Add this to your AI tool's config file (find the exact file path for your tool in Setup with Your AI Tool):

{
  "mcpServers": {
    "return-to-dark-tower": {
      "command": "npx",
      "args": ["-y", "mcp-server-return-to-dark-tower", "--stdio-only"]
    }
  }
}

Step 2 — Restart your AI tool.

When it starts, it runs the npx command above — npx fetches the package from npm (first run only, cached after that) and launches the server as a background process. No separate terminal needed.

Step 3 — Ask it something like:

"Connect to the tower, calibrate it, then turn on all the north doorway lights."

What is MCP?

MCP (Model Context Protocol) is an open standard that lets AI assistants use tools and access data from external systems — similar to how a browser loads plugins. Instead of the AI just knowing about your tower, it can control it.

This server implements the MCP standard. Once configured, your AI assistant gains 31 tools it can call by name — things like tower_play_sound, tower_break_seal, or tower_rotate_drum — and it can chain them together to run full dramatic game sequences on command.

Two ways to connect:

Getting Started

Prerequisites

Before you begin, make sure you have:

1. Node.js 18 or newer — Download from nodejs.org. To check your version, run node --version in a terminal.

2. Bluetooth Low Energy (BLE) hardware — Built into most Macs made after 2011 and most modern Windows PCs.

3. A physical Return to Dark Tower tower, though you could use the resources in the server without a tower.

Platform-specific setup:

Install

The easiest way is to use npx, which runs the package directly from npm without any installation step:

# Test that it works — this starts the server in stdio mode
npx -y mcp-server-return-to-dark-tower --stdio-only

What is npx? It's a tool that comes bundled with Node.js. It downloads and runs a package from the npm registry on demand, so you don't have to install anything globally.

If you'd rather install it globally (for faster startup after the first run):

npm install -g mcp-server-return-to-dark-tower

Pick your AI tool below for the exact config to paste in. You do not need to run the server yourself — your AI tool will start it for you using stdio.

git clone https://github.com/your-org/mcp-server-return-to-dark-tower.git
cd mcp-server-return-to-dark-tower
npm install
npm run build

Then in all config snippets below, replace:

"command": "npx",
"args": ["-y", "mcp-server-return-to-dark-tower", "--stdio-only"]

with:

"command": "node",
"args": ["/absolute/path/to/dist/index.js", "--stdio-only"]

🖥️ Setup with Your AI Tool

Each section is self-contained — jump straight to the tool you use.

All desktop AI tools use stdio transport. The config tells the AI app how to launch this server; the app handles the rest. You just edit a JSON (or YAML) config file, save it, and restart your AI app.

If the config file doesn't exist yet, create it as a new empty file at the path shown. All configs shown below are complete and valid — you can paste them as-is if you're starting fresh.

If the file already exists, add the "return-to-dark-tower" block inside the existing "mcpServers" (or equivalent) object. Don't replace the whole file.

Claude Desktop

Claude Desktop reads its config file at startup. After saving changes, you must fully quit and reopen the app (⌘Q on Mac, not just closing the window).

Config file location:

Tip (macOS): Open the file quickly in Terminal: open -e ~/Library/Application\ Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "return-to-dark-tower": {
      "command": "npx",
      "args": ["-y", "mcp-server-return-to-dark-tower", "--stdio-only"]
    }
  }
}

After restarting Claude, you should see a hammer icon (🔨) in the chat input area indicating MCP tools are available.

Windows note: If npx doesn't work, try replacing "command": "npx" with "command": "node" and adding the full path to node_modules/.bin/mcp-server-dark-tower.js as the first arg, or install globally first.

🎯 Cursor

Cursor can load MCP config from a project-specific file or a global file.

Config file locations:

{
  "mcpServers": {
    "return-to-dark-tower": {
      "command": "npx",
      "args": ["-y", "mcp-server-return-to-dark-tower", "--stdio-only"]
    }
  }
}

Cursor picks up changes automatically — no restart required.

Important: MCP tools only appear when you're in Agent mode. In the Cursor chat panel, look for the mode selector and switch from "Normal" to "Agent" before asking the AI to use the tower.

🐙 VS Code (GitHub Copilot)

VS Code supports two config locations. The .vscode/mcp.json file can be committed to your repo so your whole team shares the same MCP setup.

Requires: VS Code 1.99 or newer. Update via Help → Check for Updates.

Option A — Workspace config (recommended, shareable with your team):

Create or edit .vscode/mcp.json in your project root:

{
  "servers": {
    "return-to-dark-tower": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-server-return-to-dark-tower", "--stdio-only"]
    }
  }
}

Option B — User settings (applies to all your projects):

Open settings.json (Cmd/Ctrl+Shift+P → "Open User Settings JSON") and add:

{
  "mcp": {
    "servers": {
      "return-to-dark-tower": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "mcp-server-return-to-dark-tower", "--stdio-only"]
      }
    }
  }
}

Important: Switch the Copilot Chat panel to Agent mode (look for the mode dropdown in the chat panel). MCP tools are not available in Ask or Edit modes.

🌊 Windsurf

Windsurf uses a single global config file for all MCP servers.

Config file location:

You can also open it from within Windsurf: click the MCP icon in the top-right of the Cascade panel → Configure.

{
  "mcpServers": {
    "return-to-dark-tower": {
      "command": "npx",
      "args": ["-y", "mcp-server-return-to-dark-tower", "--stdio-only"]
    }
  }
}

Restart Windsurf after saving. The tower tools will appear in the Cascade agent panel.

⚡ Zed

Zed's MCP servers are configured in its global settings file.

Config file location:

Add the context_servers block (alongside any existing settings in the file):

{
  "context_servers": {
    "return-to-dark-tower": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "mcp-server-return-to-dark-tower", "--stdio-only"],
      "env": {}
    }
  }
}

Restart Zed after saving. Open the Agent Panel and look for a green dot next to the server name — that means it connected successfully.

🔎 Perplexity (macOS App)

Perplexity's native MCP support is available in the Mac App (download from the App Store). The web interface does not support MCP.

Requirements:

• macOS only

• Paid Perplexity plan (Pro or higher)

• The free tier does not include MCP

Setup:

1. Install the Perplexity Mac App from the App Store if you haven't already

2. Open the app and go to Account Settings → Connectors

3. Click "Install Helper" and install the PerplexityXPC helper app when prompted — this is a one-time step required by macOS's App Store sandbox rules

4. Click "Add Connector" → Simple → "Add MCP Connector"

5. Fill in:

   • Server Name: return-to-dark-tower (or anything you like)

   • Command: npx

   • Arguments: -y mcp-server-return-to-dark-tower --stdio-only

6. Click Save and wait for the status indicator to show Running

7. In a Perplexity chat, click Sources and enable the return-to-dark-tower connector

There is no config file to edit — everything is done through Perplexity's UI.

Note: Remote MCP support (for the web interface) is on Perplexity's roadmap but not yet available.

🐋 DeepSeek

DeepSeek's web chat (chat.deepseek.com) and API do not currently support MCP — there is no config file or UI to connect an MCP server to DeepSeek directly.

If you're using DeepSeek through an IDE that supports it (Cursor and VS Code both allow you to switch the underlying AI model to DeepSeek while keeping their MCP layer), MCP tools work fine. The IDE handles the MCP connection; it's independent of which AI model is powering the responses. Configure the tower using the Cursor or VS Code section above, then switch your model to DeepSeek in that IDE's settings.

If you use DeepSeek's own web or API interface, MCP is not available at this time. Check DeepSeek's documentation for updates.

Summary

🌐 Web-Based AI Chat Apps

Web-based AI tools can't launch processes on your machine the way desktop apps can. Instead, you start the HTTP server yourself and point the web app at it.

Start the HTTP Server

Open a terminal and run:

npx mcp-server-return-to-dark-tower --http-only --port 3001

Keep this terminal window open while you use your web AI tool. The server exposes:

• http://localhost:3001/mcp — the main MCP endpoint

• http://localhost:3001/health — returns {"status":"ok"} if it's running

To verify it's up, open http://localhost:3001/health in your browser. You should see {"status":"ok"}.

What is localhost? It means "this computer". The server is running on your machine and is only accessible from your own browser — it's not exposed to the internet by default.

Claude.ai (Web)

Remote MCP connections are available on Pro, Max, Team, and Enterprise plans (not the free tier).

1. Go to claude.ai and open Settings → Integrations

2. Click Add Integration (or Add MCP Server)

3. Enter the URL: http://localhost:3001/mcp

4. Save. The tower tools will appear in your next conversation.

Heads up: Claude.ai connects from your browser to localhost, which works as long as your browser and the server are on the same machine. If you want to use it from another device (like a phone), you'll need to expose the server publicly — see the note below.

Use a tunneling tool like ngrok to create a public URL for your local server:

# In a second terminal (while the server is running)
ngrok http 3001

ngrok will print a public URL like https://abc123.ngrok.io. Use that URL instead of http://localhost:3001 in your AI app's settings.

⚠️ Anyone with that URL can send commands to your tower. Use ngrok's auth features or keep the session short.

ChatGPT / OpenAI

ChatGPT added MCP support in late 2025, available through Developer Mode (requires ChatGPT Plus or higher).

1. In ChatGPT, open Settings → Developer Mode (enable it if you haven't)

2. Go to Connectors → Add Connector

3. Select Streamable HTTP as the transport type

4. Enter the URL: http://localhost:3001/mcp

5. Save and start a new conversation. Tower tools will be available.

Note: OpenAI's MCP UI is evolving quickly. If "Connectors" has been renamed to "Apps" or similar, look for the MCP integration option there. Check OpenAI's help docs for the latest steps.

Custom Web Applications

Building your own web app to control the tower? Use the HTTP endpoint directly.

Start the server with both transports running simultaneously:

npx mcp-server-return-to-dark-tower
# stdio on stdin/stdout  +  HTTP on http://localhost:3001/mcp

Send a command with fetch:

// Generate a session ID once per user session
const sessionId = crypto.randomUUID();

const response = await fetch("http://localhost:3001/mcp", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "mcp-session-id": sessionId, // keeps this session's context consistent
  },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: 1,
    method: "tools/call",
    params: {
      name: "tower_play_sound_by_name",
      arguments: { name: "Ashstrider" },
    },
  }),
});

const result = await response.json();
console.log(result);

Subscribe to streaming events (SSE):

const eventSource = new EventSource("http://localhost:3001/mcp");
eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log("Tower event:", data);
};

CORS: If your web app runs on a different port (e.g., localhost:5173), the browser will block requests to localhost:3001 due to CORS. Configure your dev server to proxy /mcp requests, or add a CORS header to the MCP server. See the Architecture section for details on how HTTP and stdio share a single tower connection.

Available Tools

Connection (8 tools)

Audio (3 tools)

Lights (5 tools)

Drums (4 tools)

Seals (5 tools)

State & Glyphs (7 tools)

Available Resources

Resources are read-only data the AI can pull in for context (e.g., checking battery level before a long sequence).

Tower State Resources

Game Knowledge Resources

Glyph Icon Resources

Available Prompts

Prompts are pre-built instruction templates you can invoke by name. They chain multiple tools together into a single dramatic sequence.

Architecture

┌─────────────────┐     ┌──────────────────┐
│  Claude Desktop │────▶│  stdio transport  │──┐
└─────────────────┘     └──────────────────┘  │    ┌───────────────────┐     ┌─────────┐
                                               ├───▶│ TowerController   │────▶│  Tower  │
┌─────────────────┐     ┌──────────────────┐  │    │ (singleton)       │ BLE │  (HW)   │
│   React App     │────▶│  HTTP transport   │──┘    └───────────────────┘     └─────────┘
└─────────────────┘     └──────────────────┘

The TowerController singleton wraps UltimateDarkTower (v2.0.0) and is shared by both transports. The library's BluetoothAdapterFactory auto-detects the Node.js environment and uses @stoprocent/noble for BLE communication.

CLI Options

Dependencies

Development

npm run dev      # Watch mode with tsx
npm run build    # Compile TypeScript
npm run lint     # Run ESLint + Prettier check
npm test         # Run tests

License

MIT — see LICENSE.

Acknowledgments

• UltimateDarkTower — the BLE library that makes this possible

• Return to Dark Tower by Restoration Games

• The original Dark Tower (1981) by Milton Bradley