@hidechae/eztab-mcp 0.1.0

package/README.md

@@ -0,0 +1,103 @@
+# EZTab MCP server (live)
+
+An [MCP](https://modelcontextprotocol.io) server that lets an AI agent (e.g.
+Claude) edit the **same document the desktop app has open**, live.
+
+The server holds the authoritative document and runs a localhost WebSocket
+**hub**. The desktop app connects to it (toggle **Live** in the toolbar) and
+syncs both ways: the agent's tool calls appear in the app instantly, and your
+edits in the app are visible to the agent.
+
+## How it works
+
+```
+ Claude ──stdio──> MCP server ──┐
+                   (hub, ws)    ├── authoritative document
+ EZTab app ──websocket────────┘
+```
+
+- The app sends its document when you enable **Live** (seeds the hub if empty),
+  then pushes every local edit.
+- Each agent tool call mutates the shared document and broadcasts it to the app.
+- Last write wins on conflict (intended for turn-taking, not simultaneous typing
+  in the same cell).
+
+Default port `47823` (override with `EZTAB_LIVE_PORT`).
+
+## Install (published package)
+
+Published to npm as **`@hidechae/eztab-mcp`**. Add it to any MCP client:
+
+```json
+{
+  "mcpServers": {
+    "eztab": { "command": "npx", "args": ["-y", "@hidechae/eztab-mcp"] }
+  }
+}
+```
+
+Requires the EZTab desktop app (toggle **Live** in its toolbar) on the same
+machine — the server runs a localhost WebSocket hub the app connects to.
+
+### Releasing a new version
+
+npm versions are immutable, so publishing is deliberate (tag-driven):
+
+```sh
+# bump mcp/package.json "version", commit, then:
+git tag mcp-v0.1.1 && git push --tags
+```
+
+The `Publish MCP to npm` GitHub Action builds and publishes on `mcp-v*` tags
+(needs the `NPM_TOKEN` repo secret).
+
+## Setup (local dev)
+
+Dependencies are in the repo's `package.json` (`npm install`). This repo ships a
+project-scoped `.mcp.json`, so Claude Code running here offers the `eztab`
+server automatically (approve it when asked). Then click **Live** in the app.
+
+For Claude Desktop or elsewhere:
+
+```json
+{
+  "mcpServers": {
+    "eztab": {
+      "command": "npx",
+      "args": ["tsx", "mcp/server.ts"],
+      "cwd": "/absolute/path/to/eztab"
+    }
+  }
+}
+```
+
+Run standalone for testing: `task mcp` (or `npx tsx mcp/server.ts`).
+
+## Tools
+
+These act on the live shared document (no file path needed):
+
+| Tool | What it does |
+|------|--------------|
+| `get_tab` | Readable ASCII rendering of the current document |
+| `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 |
+| `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) |
+| `set_chords` | Set chord labels per beat |
+| `set_key` / `remove_key` | Set/add or remove a key (key change) at a measure |
+| `set_section` | Set/remove a section marker (e.g. "Verse", "Chorus") |
+| `set_tempo` | Set playback BPM |
+| `set_resolution` | Set a measure's subdivisions per beat (8th/16th/triplets) |
+| `add_measures` / `remove_measure` | Insert/remove measures (keys & sections re-anchored) |
+| `set_tuning` | Replace tuning / string count |
+
+These cover the editor's current model: variable string count, per-beat chords,
+keys with mid-piece changes, section markers, per-measure resolution, tempo, and
+title/artist metadata. (Playback, the on-screen keypad, undo/redo and the local
+library/archive are app-only UI concerns and intentionally have no MCP tools.)
+
+Indices are 0-based. `string` 0 is the top line; tuning is ordered high→low.
+If no app is connected, edits still apply to the in-memory document and sync
+when the app connects.

package/dist/server.js

@@ -0,0 +1,678 @@
+#!/usr/bin/env node
+
+// server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { WebSocket, WebSocketServer } from "ws";
+
+// ../src/types/tab.ts
+var TAB_FILE_VERSION = 1;
+var DEFAULT_TEMPO = 120;
+var DEFAULT_MIX = { melody: 1, backing: 0.4 };
+function shiftSectionsForInsert(sections, index) {
+  return sections.map(
+    (s) => s.measure >= index ? { ...s, measure: s.measure + 1 } : s
+  );
+}
+function shiftSectionsForDelete(sections, index) {
+  return sections.filter((s) => s.measure !== index).map((s) => s.measure > index ? { ...s, measure: s.measure - 1 } : s);
+}
+function activeKeyAt(keys, measure) {
+  let result = keys[0];
+  for (const k of keys) {
+    if (k.measure <= measure) result = k;
+    else break;
+  }
+  return result;
+}
+function shiftKeysForInsert(keys, index) {
+  const shifted = keys.map(
+    (k) => k.measure >= index ? { ...k, measure: k.measure + 1 } : k
+  );
+  if (!shifted.some((k) => k.measure === 0)) {
+    shifted.unshift({ measure: 0, tonic: keys[0].tonic, mode: keys[0].mode });
+  }
+  return shifted;
+}
+function shiftKeysForDelete(keys, index) {
+  const next = keys.filter((k) => k.measure !== index).map((k) => k.measure > index ? { ...k, measure: k.measure - 1 } : k);
+  if (!next.some((k) => k.measure === 0)) {
+    next.unshift({ measure: 0, tonic: keys[0].tonic, mode: keys[0].mode });
+  }
+  return next;
+}
+function setMeasureTimeSignature(measure, beats, beatUnit) {
+  const cols = beats * measure.subdivisions;
+  const cells = measure.cells.map(
+    (row) => Array.from({ length: cols }, (_, c) => row[c] ?? null)
+  );
+  const chords = Array.from(
+    { length: beats },
+    (_, b) => measure.chords?.[b] ?? null
+  );
+  return { ...measure, beats, beatUnit, cells, chords };
+}
+function columnCount(measure) {
+  return measure.beats * measure.subdivisions;
+}
+var PRESET_TUNINGS = {
+  "Guitar (6)": ["E4", "B3", "G3", "D3", "A2", "E2"],
+  "Bass (4)": ["G2", "D2", "A1", "E1"],
+  "Bass (5)": ["G2", "D2", "A1", "E1", "B0"],
+  "Ukulele (4)": ["A4", "E4", "C4", "G4"]
+};
+var DEFAULT_BEATS = 4;
+var DEFAULT_BEAT_UNIT = 4;
+var DEFAULT_SUBDIVISIONS = 2;
+function createMeasure(stringCount, beats = DEFAULT_BEATS, subdivisions = DEFAULT_SUBDIVISIONS, beatUnit = DEFAULT_BEAT_UNIT) {
+  const columns = beats * subdivisions;
+  return {
+    beats,
+    beatUnit,
+    subdivisions,
+    cells: Array.from(
+      { length: stringCount },
+      () => Array.from({ length: columns }, () => null)
+    ),
+    chords: Array.from({ length: beats }, () => null)
+  };
+}
+function newTabId() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  return `id-${Date.now()}-${Math.floor(Math.random() * 1e9)}`;
+}
+function createDocument(tuning = PRESET_TUNINGS["Guitar (6)"], measureCount = 4) {
+  return {
+    version: TAB_FILE_VERSION,
+    id: newTabId(),
+    title: "Untitled",
+    artist: "",
+    tuning: [...tuning],
+    measures: Array.from(
+      { length: measureCount },
+      () => createMeasure(tuning.length)
+    ),
+    keys: [{ measure: 0, tonic: "C", mode: "major" }],
+    sections: [],
+    tempo: DEFAULT_TEMPO,
+    mix: { ...DEFAULT_MIX }
+  };
+}
+function resizeMeasureStrings(measure, stringCount) {
+  const cols = columnCount(measure);
+  const cells = Array.from(
+    { length: stringCount },
+    (_, s) => Array.from({ length: cols }, (_2, c) => measure.cells[s]?.[c] ?? null)
+  );
+  return { ...measure, cells };
+}
+function setMeasureSubdivisions(measure, subdivisions) {
+  const oldCols = columnCount(measure);
+  const newCols = measure.beats * subdivisions;
+  const cells = measure.cells.map((row) => {
+    const next = Array.from({ length: newCols }, () => null);
+    for (let c = 0; c < oldCols; c++) {
+      if (row[c] == null) continue;
+      const ni = Math.round(c * subdivisions / measure.subdivisions);
+      if (ni >= 0 && ni < newCols) next[ni] = row[c];
+    }
+    return next;
+  });
+  return { ...measure, subdivisions, cells };
+}
+
+// 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");
+  }
+  data.measures = data.measures.map((m) => {
+    let beats = m.beats;
+    let subdivisions = m.subdivisions;
+    if (typeof beats !== "number" || typeof subdivisions !== "number") {
+      const cols2 = m.cells?.[0]?.length ?? m.columns ?? 8;
+      subdivisions = cols2 % 4 === 0 ? cols2 / 4 : 2;
+      beats = cols2 % 4 === 0 ? 4 : Math.max(1, Math.round(cols2 / subdivisions));
+    }
+    const beatUnit = typeof m.beatUnit === "number" ? m.beatUnit : 4;
+    const cols = beats * subdivisions;
+    const cells = (m.cells ?? []).map(
+      (row) => Array.from({ length: cols }, (_, c) => row?.[c] ?? null)
+    );
+    let chords = Array.isArray(m.chords) ? m.chords.slice(0, beats) : [];
+    while (chords.length < beats) chords.push(null);
+    return { beats, beatUnit, subdivisions, cells, chords };
+  });
+  if (!Array.isArray(data.keys) || data.keys.length === 0) {
+    data.keys = [{ measure: 0, tonic: "C", mode: "major" }];
+  }
+  if (typeof data.artist !== "string") data.artist = "";
+  if (!Array.isArray(data.sections)) data.sections = [];
+  if (typeof data.tempo !== "number") data.tempo = 120;
+  if (!data.mix || typeof data.mix.melody !== "number") {
+    data.mix = { melody: 1, backing: 0.4 };
+  }
+  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";
+  if (cell === "mute") return "-x";
+  if (typeof cell === "object") {
+    const bend = cell.bend ?? 0;
+    if (cell.tie) return `~${cell.fret}`.padStart(2, "-").slice(-2);
+    const mark = bend === 0.5 ? "b" : bend === 1.5 ? "^" : bend === 1 ? "B" : "";
+    return `${cell.fret}${mark}`.padStart(2, "-").slice(-2);
+  }
+  return String(cell).padStart(2, "-");
+}
+function render(doc) {
+  const lines = [];
+  lines.push(
+    `Title: ${doc.title}${doc.artist ? ` \u2014 ${doc.artist}` : ""}   tempo=${doc.tempo}`
+  );
+  lines.push(
+    `Tuning (top\u2192bottom): ${doc.tuning.join(" ")}   measures=${doc.measures.length}`
+  );
+  const ann = [];
+  doc.measures.forEach((_, m) => {
+    const k = doc.keys.find((x) => x.measure === m);
+    const s = doc.sections.find((x) => x.measure === m);
+    if (k) ann.push(`m${m + 1}:key=${k.tonic} ${k.mode}`);
+    if (s && s.label) ann.push(`m${m + 1}:section="${s.label}"`);
+  });
+  if (ann.length) lines.push(`Markers: ${ann.join(", ")}`);
+  doc.measures.forEach((m, mi) => {
+    const key = activeKeyAt(doc.keys, mi);
+    lines.push("");
+    lines.push(
+      `--- Measure ${mi + 1}  (${m.beats}/${m.beatUnit}, ${m.subdivisions}/beat, ${columnCount(m)} cols, key ${key.tonic} ${key.mode}) ---`
+    );
+    const chordRow = (m.chords ?? []).map((c, b) => `b${b + 1}:${c ?? "-"}`).join("  ");
+    lines.push(`chords: ${chordRow}`);
+    const ruler = Array.from(
+      { length: columnCount(m) },
+      (_, c) => String(c).padStart(2, " ")
+    ).join(" ");
+    lines.push(`col:   ${ruler}`);
+    m.cells.forEach((row, s) => {
+      const label = (doc.tuning[s] ?? "?").padEnd(3, " ");
+      const cells = row.map(cellText).join(" ");
+      lines.push(`${label}| ${cells}`);
+    });
+  });
+  return lines.join("\n");
+}
+
+// server.ts
+var PORT = Number(process.env.EZTAB_LIVE_PORT ?? 47823);
+var state = {
+  doc: null,
+  version: 0
+};
+var mode = "host";
+var clients = /* @__PURE__ */ new Set();
+var upstream = null;
+var appEditable = null;
+function pushState() {
+  if (mode === "host") {
+    const msg = JSON.stringify({
+      type: "state",
+      doc: state.doc,
+      version: state.version
+    });
+    for (const c of clients) {
+      if (c.readyState === WebSocket.OPEN) c.send(msg);
+    }
+  } else if (upstream && upstream.readyState === WebSocket.OPEN) {
+    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",
+    doc: state.doc,
+    version: state.version
+  });
+  for (const c of clients) {
+    if (c !== except && c.readyState === WebSocket.OPEN) c.send(msg);
+  }
+}
+var wss = new WebSocketServer({ port: PORT });
+wss.on("connection", (ws) => {
+  clients.add(ws);
+  ws.send(
+    JSON.stringify({ type: "state", doc: state.doc, version: state.version })
+  );
+  ws.on("message", (data) => {
+    let msg;
+    try {
+      msg = JSON.parse(data.toString());
+    } catch {
+      return;
+    }
+    if (msg.type === "set" && msg.doc) {
+      state.doc = normalize(msg.doc);
+      state.version += 1;
+      broadcastExcept(ws);
+    } else if (msg.type === "seed" && msg.doc) {
+      if (!state.doc) {
+        state.doc = normalize(msg.doc);
+        state.version += 1;
+        broadcastExcept(ws);
+      }
+    } else if (msg.type === "get") {
+      ws.send(
+        JSON.stringify({
+          type: "state",
+          doc: state.doc,
+          version: state.version
+        })
+      );
+    } else if (msg.type === "editstate") {
+      appEditable = typeof msg.editable === "boolean" ? msg.editable : null;
+      ws._isApp = true;
+      const out = JSON.stringify({ type: "editstate", editable: appEditable });
+      for (const c of clients) {
+        if (c !== ws && c.readyState === WebSocket.OPEN) c.send(out);
+      }
+    } else if (msg.type === "command") {
+      const out = JSON.stringify(msg);
+      for (const c of clients) {
+        if (c !== ws && c.readyState === WebSocket.OPEN) c.send(out);
+      }
+    }
+  });
+  const onGone = () => {
+    clients.delete(ws);
+    if (ws._isApp) {
+      appEditable = null;
+      const out = JSON.stringify({ type: "editstate", editable: null });
+      for (const c of clients) {
+        if (c.readyState === WebSocket.OPEN) c.send(out);
+      }
+    }
+  };
+  ws.on("close", onGone);
+  ws.on("error", onGone);
+});
+wss.on("error", (e) => {
+  if (e.code === "EADDRINUSE") {
+    enterClientMode();
+  } else {
+    console.error("hub error:", e);
+  }
+});
+function enterClientMode() {
+  mode = "client";
+  console.error(`port ${PORT} in use; proxying to existing hub as a client`);
+  const connect = () => {
+    const ws = new WebSocket(`ws://127.0.0.1:${PORT}`);
+    upstream = ws;
+    ws.on("open", () => ws.send(JSON.stringify({ type: "get" })));
+    ws.on("message", (data) => {
+      try {
+        const msg = JSON.parse(data.toString());
+        if (msg.type === "state" && msg.doc) {
+          state.doc = normalize(msg.doc);
+          state.version = msg.version;
+        } else if (msg.type === "editstate") {
+          appEditable = typeof msg.editable === "boolean" ? msg.editable : null;
+        }
+      } catch {
+      }
+    });
+    ws.on("close", () => {
+      upstream = null;
+      setTimeout(connect, 2e3);
+    });
+    ws.on("error", () => ws.close());
+  };
+  connect();
+}
+var server = new McpServer({ name: "eztab", version: "0.2.0" });
+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."
+    );
+  }
+  return state.doc;
+}
+function assertEditable() {
+  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.)"
+    );
+  }
+}
+function applyEdit(mutate) {
+  assertEditable();
+  const doc = requireDoc();
+  mutate(doc);
+  state.version += 1;
+  pushState();
+  const connected = mode === "host" ? clients.size > 0 : upstream != null;
+  return text(
+    `${connected ? "Pushed to app. " : "No app connected (will sync when it opens). "}
+
+${render(doc)}`
+  );
+}
+function setDoc(doc) {
+  assertEditable();
+  state.doc = doc;
+  state.version += 1;
+  pushState();
+  return text(render(doc));
+}
+function assertMeasure(doc, m) {
+  if (!Number.isInteger(m) || m < 0 || m >= doc.measures.length) {
+    throw new Error(`measure ${m} out of range (0..${doc.measures.length - 1})`);
+  }
+}
+server.tool(
+  "get_tab",
+  "Return a readable rendering of the document currently open/shared with the app.",
+  {},
+  async () => text(render(requireDoc()))
+);
+server.tool(
+  "new_tab",
+  "Replace the live document with a fresh one and push it to the app. Tuning is top (highest) to bottom (lowest).",
+  {
+    title: z.string().optional(),
+    artist: z.string().optional(),
+    preset: z.enum(["Guitar (6)", "Bass (4)", "Bass (5)", "Ukulele (4)"]).optional(),
+    tuning: z.array(z.string()).optional(),
+    measures: z.number().int().min(1).max(512).optional(),
+    tempo: z.number().int().min(20).max(400).optional()
+  },
+  async (a) => {
+    const tuning = a.tuning ?? (a.preset ? PRESET_TUNINGS[a.preset] : void 0);
+    const doc = createDocument(tuning, a.measures ?? 4);
+    if (a.title) doc.title = a.title;
+    if (a.artist) doc.artist = a.artist;
+    if (a.tempo) doc.tempo = a.tempo;
+    return setDoc(doc);
+  }
+);
+server.tool(
+  "set_title",
+  "Set the document title.",
+  { title: z.string() },
+  async (a) => applyEdit((doc) => {
+    doc.title = a.title;
+  })
+);
+server.tool(
+  "set_artist",
+  "Set the document artist (may be empty).",
+  { artist: z.string() },
+  async (a) => applyEdit((doc) => {
+    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.",
+  {
+    edits: z.array(
+      z.object({
+        measure: z.number().int(),
+        string: z.number().int(),
+        column: z.number().int(),
+        value: z.union([
+          z.number().int().min(0).max(24),
+          z.enum(["rest", "mute", "clear"])
+        ]),
+        bend: z.union([z.literal(0.5), z.literal(1), z.literal(1.5)]).optional(),
+        tie: z.boolean().optional()
+      })
+    )
+  },
+  async (a) => applyEdit((doc) => {
+    for (const e of a.edits) {
+      assertMeasure(doc, e.measure);
+      const m = doc.measures[e.measure];
+      if (e.string < 0 || e.string >= doc.tuning.length) {
+        throw new Error(
+          `string ${e.string} out of range (0..${doc.tuning.length - 1})`
+        );
+      }
+      const cols = columnCount(m);
+      if (e.column < 0 || e.column >= cols) {
+        throw new Error(
+          `column ${e.column} out of range for measure ${e.measure} (0..${cols - 1})`
+        );
+      }
+      let value = e.value === "clear" ? null : e.value;
+      if (typeof e.value === "number" && (e.bend != null || e.tie)) {
+        value = {
+          fret: e.value,
+          ...e.bend != null ? { bend: e.bend } : {},
+          ...e.tie ? { tie: true } : {}
+        };
+      }
+      m.cells[e.string][e.column] = value;
+    }
+  })
+);
+server.tool(
+  "set_chords",
+  "Set chord labels per beat (0-based). An empty label clears that beat's chord.",
+  {
+    edits: z.array(
+      z.object({
+        measure: z.number().int(),
+        beat: z.number().int(),
+        label: z.string()
+      })
+    )
+  },
+  async (a) => applyEdit((doc) => {
+    for (const e of a.edits) {
+      assertMeasure(doc, e.measure);
+      const m = doc.measures[e.measure];
+      if (e.beat < 0 || e.beat >= m.beats) {
+        throw new Error(
+          `beat ${e.beat} out of range for measure ${e.measure} (0..${m.beats - 1})`
+        );
+      }
+      if (!m.chords) m.chords = Array.from({ length: m.beats }, () => null);
+      m.chords[e.beat] = e.label.trim() || null;
+    }
+  })
+);
+server.tool(
+  "set_key",
+  "Set or add a key (key change) starting at `measure`. measure 0 is the initial key.",
+  {
+    measure: z.number().int(),
+    tonic: z.string(),
+    mode: z.enum(["major", "minor"])
+  },
+  async (a) => applyEdit((doc) => {
+    assertMeasure(doc, a.measure);
+    const existing = doc.keys.find((k) => k.measure === a.measure);
+    if (existing) {
+      existing.tonic = a.tonic;
+      existing.mode = a.mode;
+    } else {
+      doc.keys.push({ measure: a.measure, tonic: a.tonic, mode: a.mode });
+      doc.keys.sort((x, y) => x.measure - y.measure);
+    }
+  })
+);
+server.tool(
+  "remove_key",
+  "Remove the key change at `measure` (measure 0 cannot be removed).",
+  { measure: z.number().int() },
+  async (a) => applyEdit((doc) => {
+    if (a.measure === 0) throw new Error("cannot remove the initial key");
+    doc.keys = doc.keys.filter((k) => k.measure !== a.measure);
+  })
+);
+server.tool(
+  "set_section",
+  "Set a section marker (e.g. 'Intro', 'Verse', 'Chorus') at `measure`. Empty label removes it.",
+  { measure: z.number().int(), label: z.string() },
+  async (a) => applyEdit((doc) => {
+    assertMeasure(doc, a.measure);
+    const label = a.label.trim();
+    doc.sections = doc.sections.filter((s) => s.measure !== a.measure);
+    if (label) {
+      doc.sections.push({ measure: a.measure, label });
+      doc.sections.sort((x, y) => x.measure - y.measure);
+    }
+  })
+);
+server.tool(
+  "set_tempo",
+  "Set the playback tempo (BPM).",
+  { bpm: z.number().int().min(20).max(400) },
+  async (a) => applyEdit((doc) => {
+    doc.tempo = a.bpm;
+  })
+);
+server.tool(
+  "set_time_signature",
+  "Set a measure's time signature, e.g. beats=6 beatUnit=8 for 6/8. Resizes the measure, preserving cells/chords by index.",
+  {
+    measure: z.number().int(),
+    beats: z.number().int().min(1).max(32),
+    beatUnit: z.number().int().refine((v) => [2, 4, 8, 16].includes(v), {
+      message: "beatUnit must be 2, 4, 8, or 16"
+    })
+  },
+  async (a) => applyEdit((doc) => {
+    assertMeasure(doc, a.measure);
+    doc.measures[a.measure] = setMeasureTimeSignature(
+      doc.measures[a.measure],
+      a.beats,
+      a.beatUnit
+    );
+  })
+);
+server.tool(
+  "set_resolution",
+  "Set a measure's subdivisions per beat (1=quarter, 2=eighth, 4=sixteenth, 3=eighth triplet, 6=sixteenth triplet). Existing notes are remapped.",
+  { measure: z.number().int(), subdivisions: z.number().int().min(1).max(12) },
+  async (a) => applyEdit((doc) => {
+    assertMeasure(doc, a.measure);
+    doc.measures[a.measure] = setMeasureSubdivisions(
+      doc.measures[a.measure],
+      a.subdivisions
+    );
+  })
+);
+server.tool(
+  "add_measures",
+  "Insert `count` empty measures. Without `at`, appends; otherwise inserts before index `at`.",
+  {
+    count: z.number().int().min(1).max(256).optional(),
+    at: z.number().int().optional()
+  },
+  async (a) => applyEdit((doc) => {
+    const count = a.count ?? 1;
+    for (let i = 0; i < count; i++) {
+      const at = a.at == null ? doc.measures.length : a.at + i;
+      doc.measures.splice(at, 0, createMeasure(doc.tuning.length));
+      doc.keys = shiftKeysForInsert(doc.keys, at);
+      doc.sections = shiftSectionsForInsert(doc.sections, at);
+    }
+  })
+);
+server.tool(
+  "remove_measure",
+  "Remove the measure at index `measure` (at least one is kept).",
+  { measure: z.number().int() },
+  async (a) => applyEdit((doc) => {
+    assertMeasure(doc, a.measure);
+    if (doc.measures.length <= 1) throw new Error("cannot remove last measure");
+    doc.measures.splice(a.measure, 1);
+    doc.keys = shiftKeysForDelete(doc.keys, a.measure);
+    doc.sections = shiftSectionsForDelete(doc.sections, a.measure);
+  })
+);
+server.tool(
+  "set_tuning",
+  "Replace the tuning / string count. Existing frets are preserved where strings overlap. Order is top (highest) to bottom (lowest).",
+  { tuning: z.array(z.string()).min(1) },
+  async (a) => applyEdit((doc) => {
+    doc.tuning = [...a.tuning];
+    doc.measures = doc.measures.map(
+      (m) => resizeMeasureStrings(m, a.tuning.length)
+    );
+  })
+);
+var transport = new StdioServerTransport();
+await server.connect(transport);
+console.error(`eztab MCP server running (stdio) + live hub on ws://127.0.0.1:${PORT}`);

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@hidechae/eztab-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for EZTab — lets an AI agent edit the tab the EZTab app has open, live.",
+  "type": "module",
+  "bin": {
+    "eztab-mcp": "dist/server.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "eztab",
+    "guitar",
+    "tablature"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hidechae/eztab.git",
+    "directory": "mcp"
+  },
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "ws": "^8.21.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "tsup": "^8.3.0",
+    "typescript": "^5.8.3"
+  }
+}