@hidechae/eztab-mcp 0.1.0 → 0.1.2

package/README.md

@@ -79,9 +79,12 @@ These act on the live shared document (no file path needed):
 
 | Tool | What it does |
 |------|--------------|
-| `get_tab` | Readable ASCII rendering of the current document |
+| `get_tab` | Readable ASCII rendering of the open tab (says so if the app is closed / on the library screen) |
+| `list_tabs` | List the library's tabs (id, title, artist, measures, tempo) — answered by the app |
+| `list_playlists` | List playlists (id, name, song count) — answered by the app |
+| `get_playlist` | A playlist's songs in order, by `id` or `name` — answered by the app |
 | `new_tab` | Replace the document with a fresh one (title, artist, tuning/preset, measures, tempo) |
-| `load_from_file` / `save_to_file` | Seed from / persist to an `.eztab` file |
+| `open_in_app` | Ask the connected app to open a tab by path (the app reads/saves it — the server never touches the filesystem) |
 | `set_title` | Set the document title |
 | `set_artist` | Set the document artist |
 | `set_cells` | Set tab cells: a fret number, `rest`, `mute` (cutting "x"), or `clear` (empty = sustain). Optional `bend` (0.5/1/1.5) chokes a fret note; optional `tie` ties/slurs it to the previous note (same pitch = just sustain) |

package/dist/server.js

@@ -125,11 +125,6 @@ function setMeasureSubdivisions(measure, subdivisions) {
 }
 
 // eztab.ts
-import { readFile, writeFile } from "fs/promises";
-import path from "path";
-function resolvePath(p) {
-  return path.isAbsolute(p) ? p : path.resolve(process.cwd(), p);
-}
 function normalize(data) {
   if (!data || !Array.isArray(data.tuning) || !Array.isArray(data.measures)) {
     throw new Error("Not a valid EZTab document");
@@ -163,13 +158,6 @@ function normalize(data) {
   data.version = 1;
   return data;
 }
-async function loadTab(p) {
-  const text2 = await readFile(resolvePath(p), "utf8");
-  return normalize(JSON.parse(text2));
-}
-async function saveTab(p, doc) {
-  await writeFile(resolvePath(p), JSON.stringify(doc, null, 2), "utf8");
-}
 function cellText(cell) {
   if (cell === null) return "--";
   if (cell === "rest") return "-R";
@@ -229,7 +217,57 @@ var state = {
 var mode = "host";
 var clients = /* @__PURE__ */ new Set();
 var upstream = null;
+var appView = null;
 var appEditable = null;
+var pending = /* @__PURE__ */ new Map();
+var reqSeq = 0;
+var reqTag = Math.random().toString(36).slice(2, 8);
+function findAppClient() {
+  for (const c of clients) {
+    if (c._isApp && c.readyState === WebSocket.OPEN) return c;
+  }
+  return void 0;
+}
+function requestFromApp(action, params = {}, timeoutMs = 6e3) {
+  const reqId = `${reqTag}-${++reqSeq}`;
+  return new Promise((resolve, reject) => {
+    const out = JSON.stringify({ type: "request", reqId, action, params });
+    if (mode === "host") {
+      const app = findAppClient();
+      if (!app) {
+        reject(
+          new Error(
+            "No EZTab app is connected. Ask the user to open the app and enable Live (toolbar)."
+          )
+        );
+        return;
+      }
+      const timer = setTimeout(() => {
+        pending.delete(reqId);
+        reject(new Error("The EZTab app didn't respond in time."));
+      }, timeoutMs);
+      pending.set(reqId, { resolve, reject, timer });
+      app.send(out);
+    } else if (upstream && upstream.readyState === WebSocket.OPEN) {
+      const timer = setTimeout(() => {
+        pending.delete(reqId);
+        reject(new Error("The EZTab app didn't respond in time."));
+      }, timeoutMs);
+      pending.set(reqId, { resolve, reject, timer });
+      upstream.send(out);
+    } else {
+      reject(new Error("Not connected to the hub."));
+    }
+  });
+}
+function settleResponse(reqId, data) {
+  const p = pending.get(reqId);
+  if (p) {
+    clearTimeout(p.timer);
+    pending.delete(reqId);
+    p.resolve(data);
+  }
+}
 function pushState() {
   if (mode === "host") {
     const msg = JSON.stringify({
@@ -244,24 +282,6 @@ function pushState() {
     upstream.send(JSON.stringify({ type: "set", doc: state.doc }));
   }
 }
-function sendCommand(cmd) {
-  const out = JSON.stringify(cmd);
-  if (mode === "host") {
-    let sent = false;
-    for (const c of clients) {
-      if (c.readyState === WebSocket.OPEN) {
-        c.send(out);
-        sent = true;
-      }
-    }
-    return sent;
-  }
-  if (upstream && upstream.readyState === WebSocket.OPEN) {
-    upstream.send(out);
-    return true;
-  }
-  return false;
-}
 function broadcastExcept(except) {
   const msg = JSON.stringify({
     type: "state",
@@ -303,14 +323,19 @@ wss.on("connection", (ws) => {
           version: state.version
         })
       );
-    } else if (msg.type === "editstate") {
+    } else if (msg.type === "appstate") {
+      appView = msg.view === "editor" || msg.view === "library" ? msg.view : null;
       appEditable = typeof msg.editable === "boolean" ? msg.editable : null;
       ws._isApp = true;
-      const out = JSON.stringify({ type: "editstate", editable: appEditable });
+      const out = JSON.stringify({ type: "appstate", view: appView, editable: appEditable });
       for (const c of clients) {
         if (c !== ws && c.readyState === WebSocket.OPEN) c.send(out);
       }
-    } else if (msg.type === "command") {
+    } else if (msg.type === "request" && msg.reqId) {
+      const app = findAppClient();
+      if (app) app.send(JSON.stringify(msg));
+    } else if (msg.type === "response" && msg.reqId) {
+      settleResponse(msg.reqId, msg.data);
       const out = JSON.stringify(msg);
       for (const c of clients) {
         if (c !== ws && c.readyState === WebSocket.OPEN) c.send(out);
@@ -320,8 +345,9 @@ wss.on("connection", (ws) => {
   const onGone = () => {
     clients.delete(ws);
     if (ws._isApp) {
+      appView = null;
       appEditable = null;
-      const out = JSON.stringify({ type: "editstate", editable: null });
+      const out = JSON.stringify({ type: "appstate", view: null, editable: null });
       for (const c of clients) {
         if (c.readyState === WebSocket.OPEN) c.send(out);
       }
@@ -350,8 +376,11 @@ function enterClientMode() {
         if (msg.type === "state" && msg.doc) {
           state.doc = normalize(msg.doc);
           state.version = msg.version;
-        } else if (msg.type === "editstate") {
+        } else if (msg.type === "appstate") {
+          appView = msg.view === "editor" || msg.view === "library" ? msg.view : null;
           appEditable = typeof msg.editable === "boolean" ? msg.editable : null;
+        } else if (msg.type === "response" && msg.reqId) {
+          settleResponse(msg.reqId, msg.data);
         }
       } catch {
       }
@@ -364,22 +393,32 @@ function enterClientMode() {
   };
   connect();
 }
-var server = new McpServer({ name: "eztab", version: "0.2.0" });
+var server = new McpServer(
+  { name: "eztab", version: "0.2.0" },
+  {
+    instructions: "All indices are 0-based: measure 0 is the first measure, beat 0 is the first beat of a measure, string 0 is the top (highest) string, and column 0 is the first column. add_measures `at` is a 0-based insert position too. No need to ask the user about indexing."
+  }
+);
 function text(s) {
   return { content: [{ type: "text", text: s }] };
 }
 function requireDoc() {
   if (!state.doc) {
     throw new Error(
-      "No document is open. Open the EZTab app (it will connect), or call new_tab / load_from_file first."
+      "No document is open. Open the EZTab app (it will connect and share its tab), or call new_tab first."
     );
   }
   return state.doc;
 }
 function assertEditable() {
+  if (appView === "library") {
+    throw new Error(
+      "The EZTab app is on the library screen \u2014 no tab is open to edit. Ask the user to open a tab in the app and switch it to Edit mode, then retry."
+    );
+  }
   if (appEditable === false) {
     throw new Error(
-      "The EZTab app has this tab open in View mode, so it can't be changed. Switch the tab to Edit mode in the app, then retry. (Reading is always allowed.)"
+      "The open tab is in View mode, so it can't be changed. Ask the user to switch the tab to Edit mode in the app, then retry. (Reading is always allowed.)"
     );
   }
 }
@@ -410,9 +449,63 @@ function assertMeasure(doc, m) {
 }
 server.tool(
   "get_tab",
-  "Return a readable rendering of the document currently open/shared with the app.",
+  "Return a readable rendering of the tab the EZTab app currently has open. If the app isn't connected, or is on the library screen (no tab open), this says so instead \u2014 relay that to the user (ask them to open the app / open a tab) rather than guessing.",
   {},
-  async () => text(render(requireDoc()))
+  async () => {
+    if (appView === "library") {
+      return text(
+        "The EZTab app is open on the library screen \u2014 no tab is selected, so there's nothing to show. Ask the user to open a tab in the app."
+      );
+    }
+    if (appView === "editor" && state.doc) {
+      return text(render(state.doc));
+    }
+    if (state.doc) {
+      return text(render(state.doc));
+    }
+    return text(
+      "No tab is open. Ask the user to open the EZTab app and open a tab (it will be shared here automatically), or call new_tab to start a fresh one."
+    );
+  }
+);
+server.tool(
+  "list_tabs",
+  "List the tabs in the user's EZTab library (id, title, artist, measures, tempo). Read-only. Requires the app to be open with Live enabled.",
+  {},
+  async () => {
+    try {
+      const tabs = await requestFromApp("list_tabs");
+      return text(JSON.stringify(tabs, null, 2));
+    } catch (e) {
+      return text(String(e?.message ?? e));
+    }
+  }
+);
+server.tool(
+  "list_playlists",
+  "List the user's playlists (id, name, song count). Read-only. Requires the app to be open with Live enabled.",
+  {},
+  async () => {
+    try {
+      const pls = await requestFromApp("list_playlists");
+      return text(JSON.stringify(pls, null, 2));
+    } catch (e) {
+      return text(String(e?.message ?? e));
+    }
+  }
+);
+server.tool(
+  "get_playlist",
+  "Show a playlist's songs in order (resolved to titles). Provide its `id` or `name` (use list_playlists first). Read-only. Requires the app open with Live enabled.",
+  { id: z.string().optional(), name: z.string().optional() },
+  async (a) => {
+    try {
+      const pl = await requestFromApp("get_playlist", { id: a.id, name: a.name });
+      return text(JSON.stringify(pl, null, 2));
+    } catch (e) {
+      return text(String(e?.message ?? e));
+    }
+  }
 );
 server.tool(
   "new_tab",
@@ -450,39 +543,9 @@ server.tool(
     doc.artist = a.artist;
   })
 );
-server.tool(
-  "load_from_file",
-  "Load an .eztab file into the live document and push it to the app.",
-  { path: z.string() },
-  async (a) => setDoc(await loadTab(a.path))
-);
-server.tool(
-  "save_to_file",
-  "Save the current live document to an .eztab file.",
-  { path: z.string() },
-  async (a) => {
-    await saveTab(a.path, requireDoc());
-    return text(`Saved ${resolvePath(a.path)}`);
-  }
-);
-server.tool(
-  "open_in_app",
-  "Ask the connected EZTab app to open the tab file at `path` (the app must have Live enabled). The app loads it into its editor and shares it back.",
-  { path: z.string() },
-  async (a) => {
-    const sent = sendCommand({
-      type: "command",
-      action: "open",
-      path: resolvePath(a.path)
-    });
-    return text(
-      sent ? `Asked the app to open ${resolvePath(a.path)}` : "No app is connected. Enable Live in the EZTab app first."
-    );
-  }
-);
 server.tool(
   "set_cells",
-  "Set tab cells. value: a fret number (0-24), 'rest' (stops a sustaining note), 'mute' (a muted/dead 'x' stroke for cutting), or 'clear' (empty = previous note sustains through). Optional `bend` (0.5, 1, or 1.5 semitones) chokes a fret-number note. Optional `tie` (boolean) ties/slurs a fret-number note to the previous note on the same string \u2014 a matching pitch just sustains (no re-pick), a different pitch is a slur. string/column are 0-based; string 0 is the top line.",
+  "Set tab cells. value: a fret number (0-24), 'rest' (stops a sustaining note), 'mute' (a muted/dead 'x' stroke for cutting), or 'clear' (empty = previous note sustains through). Optional `bend` (0.5, 1, or 1.5 semitones) chokes a fret-number note. Optional `tie` (boolean) ties/slurs a fret-number note to the previous note on the same string \u2014 a matching pitch just sustains (no re-pick), a different pitch is a slur. measure/string/column are all 0-based (measure 0 = the first measure, string 0 = the top line).",
   {
     edits: z.array(
       z.object({
@@ -527,7 +590,7 @@ server.tool(
 );
 server.tool(
   "set_chords",
-  "Set chord labels per beat (0-based). An empty label clears that beat's chord.",
+  "Set chord labels per beat. `measure` and `beat` are 0-based (measure 0 = the first measure, beat 0 = the first beat). An empty label clears that beat's chord.",
   {
     edits: z.array(
       z.object({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hidechae/eztab-mcp",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "MCP server for EZTab — lets an AI agent edit the tab the EZTab app has open, live.",
   "type": "module",
   "bin": {