deep-roon-mcp 0.4.8 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -22,7 +22,7 @@ server of its own and sends nothing anywhere else. What you ask goes to your MCP
22
22
 
23
23
  ## Status
24
24
 
25
- Version 0.4: fifty-nine tools. Qobuz, TIDAL or both — whatever is signed in on your Core.
25
+ Version 0.5: fifty-nine tools (fifty-three with a read-only library). Qobuz, TIDAL or both — whatever is signed in on your Core.
26
26
 
27
27
  **Reading** — changes nothing in Roon:
28
28
 
@@ -80,7 +80,14 @@ Version 0.4: fifty-nine tools. Qobuz, TIDAL or both — whatever is signed in on
80
80
  | `roon_play_mix` | One of today's Daily Mixes |
81
81
  | `roon_play_radio` | A Live Radio station on a zone |
82
82
 
83
- **Changing your library or sound** — only on your request; each one reads the result back and says if Roon didn't follow:
83
+ **Changing your library or sound** — only on your request; each one reads the result back and says if Roon didn't follow.
84
+
85
+ > **A word of care.** These six tools write into your Core's library and settings through Roon's *internal* protocol —
86
+ > the same wiring Roon's own apps use, but not an API Roon Labs supports for others. Deep Roon is careful with it (one
87
+ > change at a time, read back, nothing in bulk), but a Roon update can change that wiring under it. **Keep a recent backup
88
+ > of your Roon database** (Roon › Settings › Backups) before you let an assistant change things — and if you only want to
89
+ > ask and listen, switch on **Read-only library** below: then these six tools aren't there at all.
90
+
84
91
 
85
92
  | Tool | What it does |
86
93
  |---|---|
@@ -111,6 +118,7 @@ The settings (Claude Desktop › Settings › Extensions › Deep Roon MCP):
111
118
  | Roon Core address | Empty: found on your network. Fill in the Core's address for another subnet or a private VPN (Tailscale) |
112
119
  | Essentials only | Seventeen tools instead of fifty-nine, for small models |
113
120
  | Use Roon's internal protocol | Off: only the official API — zones, playback, volume, grouping; no search, reviews, Focus or history |
121
+ | Read-only library | On: Deep Roon never changes your library — no playlists, hearts, Listen Later, library additions or DSP. Playing still works |
114
122
 
115
123
  ### Other clients
116
124
 
@@ -136,7 +144,7 @@ or by hand in `~/.codex/config.toml`:
136
144
  [mcp_servers.deep-roon]
137
145
  command = "npx"
138
146
  args = ["-y", "deep-roon-mcp"]
139
- # env = { ROON_HOST = "", DEEP_ROON_TOOLS = "", DEEP_ROON_INTERNAL = "" }
147
+ # env = { ROON_HOST = "", DEEP_ROON_TOOLS = "", DEEP_ROON_INTERNAL = "", DEEP_ROON_READ_ONLY = "" }
140
148
  ```
141
149
 
142
150
  ChatGPT on the web can't run a server on your computer — use the desktop app.
@@ -149,14 +157,15 @@ ChatGPT on the web can't run a server on your computer — use the desktop app.
149
157
  "deep-roon": {
150
158
  "command": "npx",
151
159
  "args": ["-y", "deep-roon-mcp"],
152
- "env": { "ROON_HOST": "", "DEEP_ROON_TOOLS": "", "DEEP_ROON_INTERNAL": "" }
160
+ "env": { "ROON_HOST": "", "DEEP_ROON_TOOLS": "", "DEEP_ROON_INTERNAL": "", "DEEP_ROON_READ_ONLY": "" }
153
161
  }
154
162
  }
155
163
  }
156
164
  ```
157
165
 
158
- The same three settings as environment variables: `ROON_HOST` (the Core's address, empty = find it), `DEEP_ROON_TOOLS=essentials`,
159
- `DEEP_ROON_INTERNAL=off`. Leave out what you don't need. VS Code calls the block `"servers"` instead of `"mcpServers"`.
166
+ The same settings as environment variables: `ROON_HOST` (the Core's address, empty = find it), `DEEP_ROON_TOOLS=essentials`,
167
+ `DEEP_ROON_INTERNAL=off`, `DEEP_ROON_READ_ONLY=library` (nothing changes the library; playing works) or `DEEP_ROON_READ_ONLY=all`
168
+ (Deep Roon only looks: no playing, queueing or zone changes either). Leave out what you don't need. VS Code calls the block `"servers"` instead of `"mcpServers"`.
160
169
 
161
170
  Then, once, in Roon: Settings › Extensions › **Enable** next to "Deep Roon MCP". Until then the tools say so.
162
171
 
@@ -200,6 +209,9 @@ status; it holds no secrets).
200
209
  - Several clients at once (Claude Desktop and Claude Code, or ChatGPT next to them) work: Roon keeps one connection
201
210
  per extension, and the client that asks a question takes it over for that moment.
202
211
  - Album, track and artist keys stay valid between calls.
212
+ - Track artists: a track's `artist` is its album's artist (on a compilation that is often "Various Artists"). Where the
213
+ track's own main artist differs, it comes as `track_artist` — in search, `roon_tracks`, albums, playlists, the queue
214
+ and what plays now. Roon keeps it in the track's credits.
203
215
  - Covers: every `image` key comes with an `image_url` to load it from your Core. Roon has two kinds of image keys that
204
216
  aren't interchangeable. Deep Roon reads Roon's internal library, so most keys are internal ones (short, like
205
217
  `doicaaaa`): the Core serves them at `http://<core>:9330/image/<key>.jpg`, or scaled at `/image/<key>.300.jpg` (any
@@ -42,6 +42,7 @@ var __toESM = (mod, isNodeMode, target2) => (target2 = mod != null ? __create(__
42
42
  isNodeMode || !mod || !mod.__esModule ? __defProp(target2, "default", { value: mod, enumerable: true }) : target2,
43
43
  mod
44
44
  ));
45
+ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
45
46
 
46
47
  // node_modules/ajv/dist/compile/codegen/code.js
47
48
  var require_code = __commonJS({
@@ -15525,7 +15526,7 @@ var require_lib2 = __commonJS({
15525
15526
  var version2;
15526
15527
  var init_package = __esm({
15527
15528
  "package.json"() {
15528
- version2 = "0.4.8";
15529
+ version2 = "0.5.0";
15529
15530
  }
15530
15531
  });
15531
15532
 
@@ -16033,6 +16034,7 @@ function resultRow(c, o) {
16033
16034
  if (t === "TrackLite" || t === "Track") {
16034
16035
  const al = obj(c, field2(o, "Album"));
16035
16036
  const r = { kind: "track", key: String(field2(o, "TrackId") ?? ""), title: field2(o, "Title") ?? "", artist: clean(field2(al, "PerformedBy") ?? field2(o, "PerformedBy") ?? "") };
16037
+ trackArtist(c, r, o, al);
16036
16038
  const album2 = field2(al, "Title");
16037
16039
  if (album2) r.album = album2;
16038
16040
  const ak = field2(al, "AlbumId");
@@ -16048,6 +16050,17 @@ function resultRow(c, o) {
16048
16050
  }
16049
16051
  return { kind: t, title: field2(o, "Title") ?? field2(o, "Name") ?? "" };
16050
16052
  }
16053
+ function trackArtist(c, r, tr, al) {
16054
+ const namen = [];
16055
+ for (const cr of items(c, field2(tr, "Credits"))) {
16056
+ if (field2(cr, "Type") !== 3) continue;
16057
+ const n = field2(obj(c, field2(cr, "Performer")), "Name");
16058
+ if (typeof n === "string" && n && !namen.includes(n)) namen.push(n);
16059
+ }
16060
+ const albumArtiest = clean(field2(al, "PerformedBy") ?? "");
16061
+ if (!namen.length || namen.includes(albumArtiest) || namen.every((n) => albumArtiest.includes(n))) return;
16062
+ r.track_artist = namen.join(", ");
16063
+ }
16051
16064
  var obj, clean, typeOf, items, strings, flag, yearOf, wait;
16052
16065
  var init_graph = __esm({
16053
16066
  "src/roon/graph.ts"() {
@@ -16082,6 +16095,7 @@ var init_graph = __esm({
16082
16095
  __name(sourceOf, "sourceOf");
16083
16096
  __name(albumRow, "albumRow");
16084
16097
  __name(resultRow, "resultRow");
16098
+ __name(trackArtist, "trackArtist");
16085
16099
  }
16086
16100
  });
16087
16101
 
@@ -16326,6 +16340,7 @@ async function album(key, withCredits) {
16326
16340
  const n = field2(t, "TrackNumber");
16327
16341
  if (n != null) r.n = n;
16328
16342
  r.title = field2(t, "Title");
16343
+ trackArtist(c, r, t, al);
16329
16344
  const l = field2(t, "LengthSeconds");
16330
16345
  if (typeof l === "number") {
16331
16346
  r.length = duration3(l);
@@ -17006,6 +17021,8 @@ var init_focus = __esm({
17006
17021
  });
17007
17022
 
17008
17023
  // src/index.ts
17024
+ var index_exports = {};
17025
+ module.exports = __toCommonJS(index_exports);
17009
17026
  var import_http = __toESM(require("http"));
17010
17027
 
17011
17028
  // node_modules/zod/v3/helpers/util.js
@@ -49615,6 +49632,7 @@ async function nowPlaying() {
49615
49632
  r.title = field2(tr, "Title");
49616
49633
  r.artist = clean(field2(al, "PerformedBy"));
49617
49634
  r.album = field2(al, "Title");
49635
+ trackArtist(c, r, tr, al);
49618
49636
  const tk = field2(tr, "TrackId");
49619
49637
  if (tk !== void 0 && tk !== null) r.track_key = String(tk);
49620
49638
  const ak = field2(al, "AlbumId");
@@ -49870,6 +49888,7 @@ function queueRow(c, oid) {
49870
49888
  const tr = obj(c, field2(items(c, field2(c.graph.getObject(oid), "Tracks"))[0], "Track"));
49871
49889
  const al = obj(c, field2(tr, "Album"));
49872
49890
  const r = { title: field2(tr, "Title") ?? null, artist: clean(field2(al, "PerformedBy") ?? "") };
49891
+ trackArtist(c, r, tr, al);
49873
49892
  const album2 = field2(al, "Title");
49874
49893
  if (album2) r.album = album2;
49875
49894
  const l = field2(tr, "LengthSeconds");
@@ -51010,6 +51029,7 @@ async function playlist(key, limit3) {
51010
51029
  const tr = obj(c, field2(obj(c, x), "Track"));
51011
51030
  const al = obj(c, field2(tr, "Album"));
51012
51031
  const r = { n: i + 1, key: String(field2(tr, "TrackId") ?? ""), title: field2(tr, "Title") ?? null, artist: clean(field2(al, "PerformedBy") ?? ""), album: field2(al, "Title") ?? void 0 };
51032
+ trackArtist(c, r, tr, al);
51013
51033
  const ak = field2(al, "AlbumId");
51014
51034
  if (ak !== void 0 && ak !== null) r.album_key = String(ak);
51015
51035
  const im = imageKey(c, al);
@@ -51868,30 +51888,53 @@ var INSTRUCTIONS = `Deep Roon MCP connects to the user's own Roon Core (music pl
51868
51888
  - What plays changes all the time: read roon_now_playing afresh before describing it.
51869
51889
  - "Daily Mixes" are Roon's own (roon_mixes); the user's TIDAL mixes (My Mix 1 \u2026, My Daily Discovery) are roon_tidal_playlists with shelf my_mixes, and their tracks can be read with roon_playlist.
51870
51890
  - Unofficial: this uses Roon's internal protocol, which a Roon update can change; if a tool says so, tell the user to check for an update.`;
51871
- function buildServer(internal, essentials) {
51872
- const server = new McpServer({ name: "deep-roon-mcp", title: "Deep Roon MCP", version: version2, websiteUrl: "https://github.com/renebouwmeester/deep-roon-mcp" }, { instructions: INSTRUCTIONS });
51873
- if (essentials) {
51874
- const keep = /* @__PURE__ */ new Set([
51875
- "roon_status",
51876
- "roon_search",
51877
- "roon_album",
51878
- "roon_review",
51879
- "roon_bio",
51880
- "roon_artist",
51881
- "roon_zones",
51882
- "roon_now_playing",
51883
- "roon_play",
51884
- "roon_play_tracks",
51885
- "roon_control",
51886
- "roon_volume",
51887
- "roon_queue",
51888
- "roon_playlists",
51889
- "roon_play_playlist",
51890
- "roon_daily_picks",
51891
- "roon_top"
51892
- ]);
51891
+ var LIBRARY_WRITES = /* @__PURE__ */ new Set(["roon_playlist_create", "roon_favorite", "roon_radio_favorite", "roon_listen_later_set", "roon_library_add", "roon_dsp_set"]);
51892
+ var PLAYBACK = /* @__PURE__ */ new Set([
51893
+ "roon_play",
51894
+ "roon_play_tracks",
51895
+ "roon_play_radio",
51896
+ "roon_play_mix",
51897
+ "roon_play_playlist",
51898
+ "roon_control",
51899
+ "roon_seek",
51900
+ "roon_volume",
51901
+ "roon_settings",
51902
+ "roon_queue_jump",
51903
+ "roon_queue_remove",
51904
+ "roon_queue_move",
51905
+ "roon_queue_clear",
51906
+ "roon_transfer",
51907
+ "roon_group",
51908
+ "roon_ungroup",
51909
+ "roon_sleep",
51910
+ "roon_standby"
51911
+ ]);
51912
+ function buildServer(internal, essentials, readOnly = "off") {
51913
+ const instructions = readOnly === "off" ? INSTRUCTIONS : INSTRUCTIONS + (readOnly === "all" ? "\n- Read-only (set by the user): Deep Roon only looks \u2014 it can't play, queue, change a zone, or change the library. Say so when asked." : "\n- Read-only library (set by the user): Deep Roon can play and control zones, but it can't change the library, playlists, hearts, Listen Later or DSP. Say so when asked.");
51914
+ const server = new McpServer({ name: "deep-roon-mcp", title: "Deep Roon MCP", version: version2, websiteUrl: "https://github.com/renebouwmeester/deep-roon-mcp" }, { instructions });
51915
+ const essentialSet = /* @__PURE__ */ new Set([
51916
+ "roon_status",
51917
+ "roon_search",
51918
+ "roon_album",
51919
+ "roon_review",
51920
+ "roon_bio",
51921
+ "roon_artist",
51922
+ "roon_zones",
51923
+ "roon_now_playing",
51924
+ "roon_play",
51925
+ "roon_play_tracks",
51926
+ "roon_control",
51927
+ "roon_volume",
51928
+ "roon_queue",
51929
+ "roon_playlists",
51930
+ "roon_play_playlist",
51931
+ "roon_daily_picks",
51932
+ "roon_top"
51933
+ ]);
51934
+ const keep = /* @__PURE__ */ __name((name) => (!essentials || essentialSet.has(name)) && !(readOnly !== "off" && LIBRARY_WRITES.has(name)) && !(readOnly === "all" && PLAYBACK.has(name)), "keep");
51935
+ if (essentials || readOnly !== "off") {
51893
51936
  const original = server.registerTool.bind(server);
51894
- server.registerTool = (name, cfg, cb) => keep.has(name) ? original(name, cfg, cb) : void 0;
51937
+ server.registerTool = (name, cfg, cb) => keep(name) ? original(name, cfg, cb) : void 0;
51895
51938
  }
51896
51939
  registerStatusTool(server, internal);
51897
51940
  registerReadTools(server, internal);
@@ -51900,7 +51943,7 @@ function buildServer(internal, essentials) {
51900
51943
  return server;
51901
51944
  }
51902
51945
  __name(buildServer, "buildServer");
51903
- function serveHttp(spec, internal, essentials) {
51946
+ function serveHttp(spec, internal, essentials, readOnly) {
51904
51947
  const m = /^(?:(.+):)?(\d+)$/.exec(spec.trim());
51905
51948
  if (!m) {
51906
51949
  log(`DEEP_ROON_HTTP should be [host:]port, not "${spec}"`);
@@ -51925,7 +51968,7 @@ function serveHttp(spec, internal, essentials) {
51925
51968
  res.writeHead(400).end("Parse error");
51926
51969
  return;
51927
51970
  }
51928
- const server = buildServer(internal, essentials);
51971
+ const server = buildServer(internal, essentials, readOnly);
51929
51972
  const transport2 = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0, enableJsonResponse: true });
51930
51973
  res.on("close", () => {
51931
51974
  transport2.close().catch(() => {
@@ -51947,14 +51990,16 @@ __name(serveHttp, "serveHttp");
51947
51990
  async function main() {
51948
51991
  const internal = !/^(off|false|0|no)$/i.test(process.env.DEEP_ROON_INTERNAL ?? "");
51949
51992
  const essentials = /^(essentials|true|1|yes)$/i.test(process.env.DEEP_ROON_TOOLS ?? process.env.DEEP_ROON_ESSENTIALS ?? "");
51993
+ const ro = (process.env.DEEP_ROON_READ_ONLY ?? "").trim().toLowerCase();
51994
+ const readOnly = ro === "all" ? "all" : /^(library|true|1|yes)$/.test(ro) ? "library" : "off";
51950
51995
  if (internal) afterFirstConnect(() => selfTest(runSelfTest));
51951
51996
  checkForUpdate().catch(() => {
51952
51997
  });
51953
- log(`${internal ? "internal protocol on" : "internal protocol OFF \u2014 official API only"}${essentials ? ", essentials" : ""}`);
51998
+ log(`${internal ? "internal protocol on" : "internal protocol OFF \u2014 official API only"}${essentials ? ", essentials" : ""}${readOnly === "off" ? "" : readOnly === "all" ? ", READ-ONLY (looks only)" : ", read-only library"}`);
51954
51999
  const httpSpec = process.env.DEEP_ROON_HTTP;
51955
- if (httpSpec) serveHttp(httpSpec, internal, essentials);
52000
+ if (httpSpec) serveHttp(httpSpec, internal, essentials, readOnly);
51956
52001
  else {
51957
- await buildServer(internal, essentials).connect(new StdioServerTransport());
52002
+ await buildServer(internal, essentials, readOnly).connect(new StdioServerTransport());
51958
52003
  log(`${version2} ready (stdio)`);
51959
52004
  process.stdin.on("close", () => {
51960
52005
  shutdown();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "deep-roon-mcp",
3
- "version": "0.4.8",
3
+ "version": "0.5.0",
4
4
  "description": "An MCP server for Roon that reaches the parts the official API doesn't: reviews, biographies, Qobuz's and TIDAL's shelves, TIDAL's playlists, your history, search across your library and the streaming services",
5
5
  "license": "Apache-2.0",
6
6
  "author": "René Bouwmeester <21277119+renebouwmeester@users.noreply.github.com>",