@azurestacknerd/roon-mcp 1.0.1

package/README.md

@@ -0,0 +1,180 @@
+# Roon MCP Server
+
+An MCP (Model Context Protocol) server that lets Claude Desktop control [Roon](https://roon.app/) music playback. Search your library, play music, control volume, and manage zones — all through natural language.
+
+## Features
+
+- **20 MCP tools** for full Roon control
+- Search and play artists, albums, tracks, and playlists
+- Playback controls: play, pause, stop, skip, seek, shuffle, loop
+- Volume control with mute support
+- Zone management and now-playing info
+- Queue management (add tracks, albums, playlists)
+- Direct WebSocket connection to Roon Core (no discovery needed)
+- Auto-reconnect on connection loss
+- Persistent pairing (only authorize once in Roon)
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 18 or later
+- A [Roon](https://roon.app/) Core running on your network
+- [Claude Desktop](https://claude.ai/download)
+
+## Installation
+
+```bash
+git clone https://github.com/AzureStackNerd/roon-mcp.git
+cd roon-mcp
+npm install
+npm run build
+```
+
+## Configuration
+
+Add the server to your Claude Desktop configuration file:
+
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "roon": {
+      "command": "node",
+      "args": ["C:\\path\\to\\roon-mcp\\build\\index.js"],
+      "env": {
+        "ROON_HOST": "192.168.1.100",
+        "ROON_PORT": "9330"
+      }
+    }
+  }
+}
+```
+
+### Environment Variables
+
+| Variable    | Default         | Description                      |
+| ----------- | --------------- | -------------------------------- |
+| `ROON_HOST` | `192.168.1.100` | IP address of your Roon Core     |
+| `ROON_PORT` | `9100`          | WebSocket port of your Roon Core |
+
+> **Finding your Roon Core port**: In Roon, go to **Settings > General** and look for the HTTP port displayed under your Core name. The default is 9100, but it may differ.
+
+## First-Time Setup
+
+1. Start Claude Desktop with the MCP server configured
+2. In Roon, go to **Settings > Extensions**
+3. Find **Roon MCP for Claude** and click **Enable**
+4. The extension will remember its authorization for future restarts
+
+## Available Tools
+
+### Zone & Status
+
+| Tool          | Parameters | Description                                              |
+| ------------- | ---------- | -------------------------------------------------------- |
+| `list_zones`  | —          | List all zones with current playback status              |
+| `now_playing` | `zone?`    | Get current track info for a zone (or all playing zones) |
+| `get_queue`   | `zone`     | Get the play queue for a zone                            |
+
+### Playback Controls
+
+| Tool             | Parameters                     | Description                                            |
+| ---------------- | ------------------------------ | ------------------------------------------------------ |
+| `play`           | `zone`                         | Start playback                                         |
+| `pause`          | `zone`                         | Pause playback                                         |
+| `play_pause`     | `zone`                         | Toggle play/pause                                      |
+| `stop`           | `zone`                         | Stop playback and release audio device                 |
+| `next_track`     | `zone`                         | Skip to next track                                     |
+| `previous_track` | `zone`                         | Go to previous track                                   |
+| `seek`           | `zone`, `seconds`, `relative?` | Seek to position (absolute or relative)                |
+| `shuffle`        | `zone`, `enabled`              | Enable or disable shuffle                              |
+| `loop`           | `zone`, `mode`                 | Set loop mode (`loop`, `loop_one`, `disabled`, `next`) |
+
+### Volume
+
+| Tool            | Parameters              | Description                                             |
+| --------------- | ----------------------- | ------------------------------------------------------- |
+| `change_volume` | `zone`, `value`, `how?` | Change volume (`absolute`, `relative`, `relative_step`) |
+| `mute`          | `zone`, `mute`          | Mute or unmute                                          |
+| `get_volume`    | `zone`                  | Get current volume level and mute status                |
+
+### Search & Play
+
+| Tool            | Parameters                   | Description                                                     |
+| --------------- | ---------------------------- | --------------------------------------------------------------- |
+| `search`        | `query`, `zone?`             | Search the library (returns artists, albums, tracks, playlists) |
+| `play_artist`   | `artist`, `zone`             | Search and play an artist                                       |
+| `play_album`    | `album`, `zone`              | Search and play an album                                        |
+| `play_playlist` | `playlist`, `zone`           | Search and play a playlist                                      |
+| `play_track`    | `track`, `zone`              | Search and play a specific track                                |
+| `add_to_queue`  | `query`, `zone`, `category?` | Search and add to the queue                                     |
+
+## Usage Examples
+
+Once configured, you can ask Claude things like:
+
+- _"What zones are available?"_
+- _"What's playing right now?"_
+- _"Play Blue by Joni Mitchell in the living room"_
+- _"Play the album Bad by Michael Jackson in Bedroom"_
+- _"Skip to the next track"_
+- _"Turn the volume down a bit in the kitchen"_
+- _"Add Bohemian Rhapsody to the queue"_
+- _"Enable shuffle mode"_
+- _"Search for Miles Davis"_
+
+## Architecture
+
+```text
+src/
+  index.ts              # Entry point, MCP server setup
+  roon-connection.ts    # Roon connection management, zone cache
+  tools/
+    zone.ts             # list_zones, now_playing, get_queue
+    playback.ts         # play, pause, stop, seek, shuffle, loop
+    volume.ts           # change_volume, mute, get_volume
+    browse.ts           # search, play_artist/album/playlist/track, add_to_queue
+types/
+  node-roon-api.d.ts            # Type declarations for node-roon-api
+  node-roon-api-transport.d.ts  # Type declarations for node-roon-api-transport
+  node-roon-api-browse.d.ts     # Type declarations for node-roon-api-browse
+  node-roon-api-status.d.ts     # Type declarations for node-roon-api-status
+```
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Run directly
+npm start
+
+# Test interactively with MCP Inspector
+npx @modelcontextprotocol/inspector node build/index.js
+```
+
+## Troubleshooting
+
+### "Not connected to Roon"
+
+- Verify `ROON_HOST` and `ROON_PORT` point to your Roon Core
+- Check that the extension is enabled in Roon > Settings > Extensions
+
+### Extension requires re-enabling after every restart
+
+- The pairing token is stored in `roon-mcp/config.json`. After the first authorization it should persist across restarts. If you still need to re-enable, check that the `config.json` file exists in the project root after the first pairing.
+
+### Search finds wrong version of a track/album
+
+- Include the artist name in your query for better matching, e.g. _"Dirty Diana Michael Jackson"_ instead of just _"Dirty Diana"_
+
+### Playback doesn't start after search
+
+- Check the Roon Core logs for errors
+- Ensure the zone is available and not in use by another controller
+
+## License
+
+MIT

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { roonConnection } from "./roon-connection.js";
+import { registerZoneTools } from "./tools/zone.js";
+import { registerPlaybackTools } from "./tools/playback.js";
+import { registerVolumeTools } from "./tools/volume.js";
+import { registerBrowseTools } from "./tools/browse.js";
+// Prevent process crashes from unhandled errors in node-roon-api's WebSocket.
+// The ws library emits EventEmitter 'error' events, but node-roon-api only sets
+// DOM-style .onerror handlers, leaving EventEmitter errors unhandled.
+process.on("uncaughtException", (error) => {
+    console.error("[roon-mcp] Uncaught exception (kept alive):", error.message);
+});
+process.on("unhandledRejection", (reason) => {
+    console.error("[roon-mcp] Unhandled rejection (kept alive):", reason);
+});
+const server = new McpServer({
+    name: "roon-mcp",
+    version: "1.0.1",
+});
+registerZoneTools(server);
+registerPlaybackTools(server);
+registerVolumeTools(server);
+registerBrowseTools(server);
+async function main() {
+    // Start Roon connection (runs in background with auto-reconnect)
+    roonConnection.connect();
+    // Start MCP server on stdio
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[roon-mcp] MCP server running on stdio");
+}
+main().catch((error) => {
+    console.error("[roon-mcp] Fatal error:", error);
+    process.exit(1);
+});

package/build/roon-connection.d.ts

@@ -0,0 +1,21 @@
+import RoonApiTransport from "node-roon-api-transport";
+import RoonApiBrowse from "node-roon-api-browse";
+import type { Zone } from "node-roon-api-transport";
+export declare class RoonConnection {
+    private roon;
+    private status;
+    private core;
+    private zones;
+    constructor();
+    connect(): void;
+    private subscribeZones;
+    private getTransportUnsafe;
+    getTransport(): RoonApiTransport;
+    private getBrowseUnsafe;
+    getBrowse(): RoonApiBrowse;
+    isConnected(): boolean;
+    getZones(): Zone[];
+    findZone(nameOrId: string): Zone | null;
+    findZoneOrThrow(nameOrId: string): Zone;
+}
+export declare const roonConnection: RoonConnection;

package/build/roon-connection.js

@@ -0,0 +1,202 @@
+import RoonApi from "node-roon-api";
+import RoonApiTransport from "node-roon-api-transport";
+import RoonApiBrowse from "node-roon-api-browse";
+import RoonApiStatus from "node-roon-api-status";
+import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+const ROON_HOST = process.env.ROON_HOST || "192.168.1.100";
+const ROON_PORT = (() => {
+    const port = parseInt(process.env.ROON_PORT || "9100", 10);
+    if (isNaN(port) || port < 1 || port > 65535) {
+        console.error(`[roon-mcp] Invalid ROON_PORT: ${process.env.ROON_PORT}. Using default 9100.`);
+        return 9100;
+    }
+    return port;
+})();
+// Fixed path for config.json so pairing token persists across restarts
+// regardless of CWD when Claude Desktop launches the process
+const CONFIG_DIR = dirname(dirname(fileURLToPath(import.meta.url)));
+const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+function loadPersistedState() {
+    try {
+        const content = readFileSync(CONFIG_PATH, { encoding: "utf8" });
+        return JSON.parse(content)?.roonstate || {};
+    }
+    catch {
+        return {};
+    }
+}
+function savePersistedState(state) {
+    try {
+        let config = {};
+        try {
+            const content = readFileSync(CONFIG_PATH, { encoding: "utf8" });
+            config = JSON.parse(content) || {};
+        }
+        catch {
+            // file doesn't exist yet
+        }
+        config.roonstate = state;
+        mkdirSync(dirname(CONFIG_PATH), { recursive: true });
+        writeFileSync(CONFIG_PATH, JSON.stringify(config, null, "    "));
+    }
+    catch (e) {
+        console.error("[roon-mcp] Failed to save config:", e);
+    }
+}
+export class RoonConnection {
+    roon;
+    status;
+    core = null;
+    zones = new Map();
+    constructor() {
+        this.roon = new RoonApi({
+            extension_id: "com.roon-mcp.claude",
+            display_name: "Roon MCP for Claude",
+            display_version: "1.0.1",
+            publisher: "roon-mcp",
+            email: "noreply@roon-mcp.local",
+            log_level: "none",
+            get_persisted_state: loadPersistedState,
+            set_persisted_state: savePersistedState,
+            core_paired: (core) => {
+                console.error(`[roon-mcp] Paired with core: ${core.display_name}`);
+                this.core = core;
+                this.subscribeZones();
+            },
+            core_unpaired: (core) => {
+                console.error(`[roon-mcp] Unpaired from core: ${core.display_name}`);
+                this.core = null;
+                this.zones.clear();
+            },
+        });
+        this.status = new RoonApiStatus(this.roon);
+        this.roon.init_services({
+            required_services: [RoonApiTransport, RoonApiBrowse],
+            provided_services: [this.status],
+        });
+    }
+    connect() {
+        console.error(`[roon-mcp] Connecting to Roon Core at ${ROON_HOST}:${ROON_PORT}...`);
+        this.status.set_status("Connecting...", false);
+        const doConnect = () => {
+            this.roon.ws_connect({
+                host: ROON_HOST,
+                port: ROON_PORT,
+                onclose: () => {
+                    console.error("[roon-mcp] Connection lost, reconnecting in 3s...");
+                    this.core = null;
+                    this.zones.clear();
+                    setTimeout(doConnect, 3000);
+                },
+                onerror: () => {
+                    console.error("[roon-mcp] WebSocket error");
+                },
+            });
+        };
+        doConnect();
+    }
+    subscribeZones() {
+        const transport = this.getTransportUnsafe();
+        if (!transport)
+            return;
+        transport.subscribe_zones((response, msg) => {
+            if (response === "Subscribed" && msg.zones) {
+                this.zones.clear();
+                for (const zone of msg.zones) {
+                    this.zones.set(zone.zone_id, zone);
+                }
+                console.error(`[roon-mcp] Subscribed to ${this.zones.size} zone(s)`);
+                this.status.set_status("Connected", false);
+            }
+            else if (response === "Changed") {
+                if (msg.zones_removed) {
+                    for (const id of msg.zones_removed) {
+                        this.zones.delete(id);
+                    }
+                }
+                if (msg.zones_added) {
+                    for (const zone of msg.zones_added) {
+                        this.zones.set(zone.zone_id, zone);
+                    }
+                }
+                if (msg.zones_changed) {
+                    for (const zone of msg.zones_changed) {
+                        this.zones.set(zone.zone_id, zone);
+                    }
+                }
+                if (msg.zones_seek_changed) {
+                    for (const update of msg.zones_seek_changed) {
+                        const zone = this.zones.get(update.zone_id);
+                        if (zone) {
+                            if (zone.now_playing) {
+                                zone.now_playing.seek_position = update.seek_position;
+                            }
+                            zone.queue_time_remaining = update.queue_time_remaining;
+                        }
+                    }
+                }
+            }
+        });
+    }
+    getTransportUnsafe() {
+        if (!this.core)
+            return null;
+        return this.core.services.RoonApiTransport ?? null;
+    }
+    getTransport() {
+        const transport = this.getTransportUnsafe();
+        if (!transport) {
+            throw new Error("Not connected to Roon. Please approve the extension in Roon Settings > Extensions.");
+        }
+        return transport;
+    }
+    getBrowseUnsafe() {
+        if (!this.core)
+            return null;
+        return this.core.services.RoonApiBrowse ?? null;
+    }
+    getBrowse() {
+        const browse = this.getBrowseUnsafe();
+        if (!browse) {
+            throw new Error("Not connected to Roon. Please approve the extension in Roon Settings > Extensions.");
+        }
+        return browse;
+    }
+    isConnected() {
+        return this.core !== null;
+    }
+    getZones() {
+        return Array.from(this.zones.values());
+    }
+    findZone(nameOrId) {
+        // Try exact zone_id match first
+        const byId = this.zones.get(nameOrId);
+        if (byId)
+            return byId;
+        // Try case-insensitive display_name match
+        const lower = nameOrId.toLowerCase();
+        for (const zone of this.zones.values()) {
+            if (zone.display_name.toLowerCase() === lower)
+                return zone;
+        }
+        // Try partial match
+        for (const zone of this.zones.values()) {
+            if (zone.display_name.toLowerCase().includes(lower))
+                return zone;
+        }
+        return null;
+    }
+    findZoneOrThrow(nameOrId) {
+        const zone = this.findZone(nameOrId);
+        if (!zone) {
+            const available = this.getZones()
+                .map((z) => z.display_name)
+                .join(", ");
+            throw new Error(`Zone '${nameOrId}' not found. Available zones: ${available || "(none - is Roon paired?)"}`);
+        }
+        return zone;
+    }
+}
+export const roonConnection = new RoonConnection();

package/build/tools/browse.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerBrowseTools(server: McpServer): void;