deep-roon-mcp 0.3.2 → 0.3.8

package/README.md

@@ -22,7 +22,7 @@ server of its own and sends nothing anywhere else. What you ask goes to your MCP
 
 ## Status
 
-Version 0.2: fifty-one tools. Qobuz, TIDAL or both — whatever is signed in on your Core.
+Version 0.3: fifty-three tools. Qobuz, TIDAL or both — whatever is signed in on your Core.
 
 **Reading** — changes nothing in Roon:
 
@@ -38,7 +38,7 @@ Version 0.2: fifty-one tools. Qobuz, TIDAL or both — whatever is signed in on
 | `roon_status` | How Deep Roon MCP stands: Core, pairing, internal protocol, self-test, newer version |
 | `roon_zones` | Roon's zones and groups |
 | `roon_now_playing` | What plays in each zone, with the volume |
-| `roon_queue` | A zone's queue |
+| `roon_queue` | A zone's queue, numbered (1 is what plays) |
 | `roon_cover` | The cover of what plays, as an image |
 | `roon_history` | Roon's play history, newest first |
 | `roon_top` | Most played albums, artists or tracks over your whole history |
@@ -68,6 +68,7 @@ Version 0.2: fifty-one tools. Qobuz, TIDAL or both — whatever is signed in on
 | `roon_seek` | A position in the playing track |
 | `roon_volume` | A zone's volume, mute |
 | `roon_settings` | Shuffle, repeat, Roon Radio |
+| `roon_queue_jump`, `roon_queue_remove` | Jump to an item of the queue, take items out of it |
 | `roon_queue_clear` | Clear what comes after the playing track (or everything) |
 | `roon_transfer` | Move what plays, with its queue, to another zone |
 | `roon_group`, `roon_ungroup` | Group zones, and undo it |
@@ -104,7 +105,7 @@ The settings (Claude Desktop › Settings › Extensions › Deep Roon MCP):
 | Setting | What it does |
 |---|---|
 | Roon Core address | Empty: found on your network. Fill in the Core's address for another subnet or a private VPN (Tailscale) |
-| Essentials only | Seventeen tools instead of fifty-one, for small models |
+| Essentials only | Seventeen tools instead of fifty-three, for small models |
 | Use Roon's internal protocol | Off: only the official API — zones, playback, volume, grouping; no search, reviews, Focus or history |
 
 ### Other clients

package/dist/deep-roon-mcp.js

@@ -15525,7 +15525,7 @@ var require_lib2 = __commonJS({
 var version2;
 var init_package = __esm({
   "package.json"() {
-    version2 = "0.3.2";
+    version2 = "0.3.8";
   }
 });
 
@@ -15852,6 +15852,11 @@ function field2(o, name) {
   for (const [k, v] of Object.entries(f)) if (k.endsWith("::" + name)) return v;
   return void 0;
 }
+function imageKey(c, o, name = "Image") {
+  const url2 = field2(obj(c, field2(o, name)), "Url");
+  const m = /^broker:\/\/\/image\/([^.]+)\./.exec(String(url2 ?? ""));
+  return m ? m[1] : void 0;
+}
 function dateParts(v) {
   if (!Buffer.isBuffer(v) || v.length < 2) return void 0;
   const n = new BinaryReader(Uint8Array.from(v)).flexInt();
@@ -15953,6 +15958,8 @@ function albumRow(c, o) {
   if (flag(field2(o, "IsListenLater"))) r.listen_later = true;
   const p = field2(o, "Popularity");
   if (typeof p === "number") r.popularity = Math.round(p * 100) / 100;
+  const img = imageKey(c, o);
+  if (img) r.image = img;
   return r;
 }
 function resultRow(c, o) {
@@ -15962,6 +15969,8 @@ function resultRow(c, o) {
     const r = { kind: "artist", key: String(field2(o, "PerformerId") ?? ""), name: field2(o, "Name") ?? "" };
     const n = field2(o, "MainPerformerAlbumCount");
     if (typeof n === "number" && n > 0) r.albums_in_library = n;
+    const img = imageKey(c, o, "Photo") ?? imageKey(c, o, "Avatar");
+    if (img) r.image = img;
     return r;
   }
   if (t === "TrackLite" || t === "Track") {
@@ -15976,6 +15985,8 @@ function resultRow(c, o) {
     const l = field2(o, "LengthSeconds");
     if (typeof l === "number") r.length = duration3(l);
     r.source = sourceOf(o, al) ?? "library";
+    const img = imageKey(c, al) ?? imageKey(c, o);
+    if (img) r.image = img;
     return r;
   }
   return { kind: t, title: field2(o, "Title") ?? field2(o, "Name") ?? "" };
@@ -15996,6 +16007,7 @@ var init_graph = __esm({
       return (o?.fields?.$items ?? o?.$items ?? []).filter((x) => typeof x === "string");
     }, "strings");
     flag = /* @__PURE__ */ __name((v) => v === true || Buffer.isBuffer(v) && v.length > 1 && v[0] >= 1, "flag");
+    __name(imageKey, "imageKey");
     __name(dateParts, "dateParts");
     yearOf = /* @__PURE__ */ __name((v) => dateParts(v)?.[0], "yearOf");
     __name(dateText, "dateText");
@@ -16341,7 +16353,12 @@ async function bio(key, max, wiki) {
       for (const n of names2) for (const x of list(n)) {
         const o = obj(c, x);
         const name = field2(o, "Name");
-        if (name && !out.some((y) => y.name === name)) out.push({ key: String(field2(o, "PerformerId") ?? "") || void 0, name });
+        if (name && !out.some((y) => y.name === name)) {
+          const r = { key: String(field2(o, "PerformerId") ?? "") || void 0, name };
+          const img2 = imageKey(c, o, "Photo") ?? imageKey(c, o, "Avatar");
+          if (img2) r.image = img2;
+          out.push(r);
+        }
       }
       return out.length ? out.slice(0, 12) : void 0;
     }, "people");
@@ -16357,6 +16374,8 @@ async function bio(key, max, wiki) {
     }
     const g = list("Genres").filter((x) => typeof x === "string");
     if (g.length) artist.genres = g;
+    const img = imageKey(c, p, "Photo") ?? imageKey(c, p, "Avatar");
+    if (img) artist.image = img;
     return {
       artist,
       texts,
@@ -16388,6 +16407,8 @@ async function discography(key, wanted) {
     if (typeof n === "number") artist.albums_in_library = n;
     const from = field2(p, "BirthPlace");
     if (from) artist.from = from;
+    const img = imageKey(c, p, "Photo") ?? imageKey(c, p, "Avatar");
+    if (img) artist.image = img;
     return { service: SERVICE_NAME[service2], artist, albums };
   });
 }
@@ -49281,7 +49302,15 @@ async function history(limit3) {
     closeSoon("after the history");
     return {
       total: out.total ?? null,
-      plays: out.events.map((e) => ({ at: localTime(e.playedAt), title: e.title, artist: clean(e.artist), album: e.album ?? void 0, played_pct: e.completionPct ?? void 0 }))
+      plays: out.events.map((e) => ({
+        at: localTime(e.playedAt),
+        title: e.title,
+        artist: clean(e.artist),
+        album: e.album ?? void 0,
+        played_pct: e.completionPct ?? void 0,
+        track_key: e.roonTrackId ?? void 0
+      }))
+      // for roon_play_tracks (13 Oct 2026, Rosso's history)
     };
   });
 }
@@ -49384,6 +49413,8 @@ async function nowPlaying() {
         r.volume_max = v.max;
         if (v.is_muted) r.muted = true;
       }
+      const img = off?.now_playing?.image_key;
+      if (img) r.image = img;
       const outs = c.graph.findByType("Endpoint").filter((e) => {
         const zz = field2(e, "Zone");
         return isRef2(zz) && String(zz.$ref) === String(z2.oid);
@@ -49405,6 +49436,10 @@ async function nowPlaying() {
         r.title = field2(tr, "Title");
         r.artist = clean(field2(al, "PerformedBy"));
         r.album = field2(al, "Title");
+        const tk = field2(tr, "TrackId");
+        if (tk !== void 0 && tk !== null) r.track_key = String(tk);
+        const ak = field2(al, "AlbumId");
+        if (ak !== void 0 && ak !== null) r.album_key = String(ak);
         const f = field2(tr, "Format");
         if (f) r.format = f;
         const l = field2(tr, "LengthSeconds");
@@ -49661,7 +49696,7 @@ function registerReadTools(server, internal = true) {
   const reg = /* @__PURE__ */ __name(((name, cfg, cb) => R(name) ? server.registerTool.call(server, name, cfg, cb) : void 0), "reg");
   reg("roon_search", {
     title: "Search Roon",
-    description: 'Search Roon \u2014 the user\'s Roon library and the catalogues of the streaming services signed in (Qobuz, TIDAL) at once; each row says its `source` (library, Qobuz, TIDAL). Returns albums (with format, e.g. FLAC 96kHz 24bit), artists and tracks. `kind` narrows to album, track or artist \u2014 use `kind: "track"` with the song title (and artist) to find one specific track; a broad query without `kind` can fill up with artists. Albums and tracks carry a `key` for `roon_album`; artists carry a `key` for `roon_artist` and `roon_bio`. Albums say their `year`, and `in_library` when the user has them in Roon. Keys stay valid between calls.',
+    description: 'Search Roon \u2014 the user\'s Roon library and the catalogues of the streaming services signed in (Qobuz, TIDAL) at once; each row says its `source` (library, Qobuz, TIDAL). Rows carry `image`, the key of the cover: the Core serves it at http://<core address>:9330/image/<key>.jpg, or scaled at /image/<key>.300.jpg (for clients that draw; a chat shows covers with roon_cover). The `image` of roon_now_playing is an official key, served at /api/image/<key>?scale=fit&width=600&height=600. Returns albums (with format, e.g. FLAC 96kHz 24bit), artists and tracks. `kind` narrows to album, track or artist \u2014 use `kind: "track"` with the song title (and artist) to find one specific track; a broad query without `kind` can fill up with artists. Albums and tracks carry a `key` for `roon_album`; artists carry a `key` for `roon_artist` and `roon_bio`. Albums say their `year`, and `in_library` when the user has them in Roon. Keys stay valid between calls.',
     inputSchema: { query: external_exports.string().min(1), kind: external_exports.enum(["album", "track", "artist"]).optional(), limit: limit(100, 30) },
     annotations: READ
   }, ({ query, kind, limit: n }) => run(() => search(query, n ?? 30, kind)));
@@ -49958,9 +49993,47 @@ function queueRow(c, oid) {
   if (album2) r.album = album2;
   const l = field2(tr, "LengthSeconds");
   if (typeof l === "number") r.length = duration3(l);
+  const k = field2(tr, "TrackId");
+  if (k !== void 0 && k !== null) r.key = String(k);
+  const img = imageKey(c, al) ?? imageKey(c, tr);
+  if (img) r.image = img;
   return r;
 }
 __name(queueRow, "queueRow");
+async function queueItemAt(c, zoneName, n) {
+  const { z: z2, q } = queueOf(c, zoneName);
+  const refs = await queueItems(c, q);
+  const at = Math.max(0, field2(c.graph.getObject(q.oid), "CurrentItemIndex") ?? 0);
+  const oid = refs[at + n - 1];
+  if (oid === void 0) throw new RoonError(`The queue of ${z2.name} has no item ${n} (${Math.max(0, refs.length - at)} from here)`, "invalid");
+  return { z: z2, q, oid, refs, at };
+}
+__name(queueItemAt, "queueItemAt");
+async function queueJump(zoneName, n) {
+  const r = await withCore(async (c) => {
+    const { z: z2, q, oid } = await queueItemAt(c, zoneName, n);
+    c.remoting.callMethodNoReply(q.oid, formatMethodSignature("Queue", "PlayFromHere", [{ type: "TransportItem", name: "item" }]), buildArgs([Arg.ref(oid)]));
+    log(`queue_jump: ${z2.name} \u2192 item ${n}`);
+    return { zone: z2.name, n };
+  });
+  return { ok: true, ...r, ...await started2(r.zone, PRIORITY["now"]) };
+}
+__name(queueJump, "queueJump");
+async function queueRemove(zoneName, ns) {
+  return withCore(async (c) => {
+    const { z: z2, q } = queueOf(c, zoneName);
+    const refs = await queueItems(c, q);
+    const at = Math.max(0, field2(c.graph.getObject(q.oid), "CurrentItemIndex") ?? 0);
+    const oids = [...new Set(ns)].map((n) => refs[at + n - 1]).filter((o) => o !== void 0);
+    if (!oids.length) throw new RoonError("No such items in the queue", "invalid");
+    c.remoting.callMethodNoReply(q.oid, formatMethodSignature("Queue", "RemoveItems", [{ type: "IEnumerable<TransportItem>", name: "items" }]), buildArgs([Arg.collection(oids.map((o) => buildArgs([Arg.ref(o)])))]));
+    log(`queue_remove: ${z2.name} \u2212 ${oids.length} item(s)`);
+    await wait(300);
+    const after = await queueItems(c, q);
+    return { ok: true, zone: z2.name, removed: oids.length, left: Math.max(0, after.length - at) };
+  });
+}
+__name(queueRemove, "queueRemove");
 async function queue2(zoneName, limit3) {
   return withCore(async (c) => {
     const { z: z2, q } = queueOf(c, zoneName);
@@ -50117,6 +50190,7 @@ __name(cover2, "cover");
 // src/tools/control.ts
 init_official();
 init_session();
+var CHANGES_QUEUE = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
 var PLAYS = { readOnlyHint: false, destructiveHint: false, openWorldHint: false };
 var REMOVES = { readOnlyHint: false, destructiveHint: true, openWorldHint: false };
 var zone = external_exports.string().describe("A Roon zone name (see roon_zones).");
@@ -50169,6 +50243,18 @@ function registerControlTools(server, internal = true) {
     inputSchema: { zone, limit: external_exports.number().int().min(1).max(200).optional() },
     annotations: { readOnlyHint: true, openWorldHint: false }
   }, ({ zone: zn, limit: limit3 }) => run(() => queue2(zn, limit3 ?? 50)));
+  reg("roon_queue_jump", {
+    title: "Jump in the queue",
+    description: "Play an item of the zone's queue now (`n` as roon_queue numbers them: 1 is what plays, 2 the next \u2026); what came before it is done. Only on an explicit request.",
+    inputSchema: { zone, n: external_exports.number().int().min(1) },
+    annotations: PLAYS
+  }, ({ zone: zn, n }) => run(() => queueJump(zn, n)));
+  reg("roon_queue_remove", {
+    title: "Remove from the queue",
+    description: "Take items out of the zone's queue, by their numbers from roon_queue (`ns`, e.g. [3, 4]). Only on an explicit request.",
+    inputSchema: { zone, ns: external_exports.array(external_exports.number().int().min(2)).min(1).max(100).describe("Positions from roon_queue (2 and up: 1 is what plays).") },
+    annotations: CHANGES_QUEUE
+  }, ({ zone: zn, ns }) => run(() => queueRemove(zn, ns)));
   reg("roon_queue_clear", {
     title: "Clear the queue",
     description: "Clear the queue of a Roon zone. By default the track that plays keeps playing and everything after it is removed; `everything: true` also removes the playing track (the zone falls silent). Only on an explicit request.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "deep-roon-mcp",
-  "version": "0.3.2",
+  "version": "0.3.8",
   "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",
   "license": "Apache-2.0",
   "author": "René Bouwmeester <21277119+renebouwmeester@users.noreply.github.com>",