@hidechae/eztab-mcp 0.4.1 → 0.5.0

package/README.md

@@ -96,7 +96,7 @@ Run standalone for testing: `task mcp` (or `npx tsx mcp/server.ts`).
 | `set_chords` | Set chord labels per column |
 | `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_tempo` / `remove_tempo` | Set the start BPM, or set/remove a tempo change at a measure |
 | `set_time_signature` | Set a measure's time signature |
 | `set_resolution` | Set a measure's subdivisions per beat (8th/16th/triplets/quintuplets) |
 | `add_measures` / `remove_measure` | Insert/remove measures (keys & sections re-anchored) |

package/dist/server.js

@@ -7,12 +7,15 @@ import { z } from "zod";
 
 // ../src/types/tab.ts
 var TAB_FILE_VERSION = 1;
-var SUPPORTED_FORMAT_REVISION = 3;
+var SUPPORTED_FORMAT_REVISION = 4;
 var MULTI_TRACK_FORMAT_REVISION = 2;
 var HARMONICS_FORMAT_REVISION = 3;
+var TEMPO_CHANGES_FORMAT_REVISION = 4;
 var MAX_TRACKS = 4;
 var DEFAULT_MAIN_TRACK_NAME = "Guitar";
 var DEFAULT_TEMPO = 120;
+var MIN_TEMPO = 20;
+var MAX_TEMPO = 400;
 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);
@@ -28,6 +31,68 @@ function activeKeyAt(keys, measure) {
   }
   return result;
 }
+function tempoSourceAt(doc, measure) {
+  let result = 0;
+  for (const t of doc.tempoChanges ?? []) {
+    if (t.measure <= measure) result = t.measure;
+    else break;
+  }
+  return result;
+}
+function validTempo(raw) {
+  if (typeof raw !== "number" || !Number.isFinite(raw)) return null;
+  const bpm = Math.round(raw);
+  return bpm >= MIN_TEMPO && bpm <= MAX_TEMPO ? bpm : null;
+}
+function normalizeTempoChanges(tempo, raw, measureCount) {
+  if (!Array.isArray(raw)) return void 0;
+  const byMeasure = /* @__PURE__ */ new Map();
+  for (const t of raw) {
+    const measure = t?.measure;
+    const bpm = validTempo(t?.bpm);
+    if (!Number.isInteger(measure) || measure < 1 || measure >= measureCount || bpm === null) {
+      continue;
+    }
+    byMeasure.set(measure, bpm);
+  }
+  const out = [];
+  let prev = tempo;
+  for (const measure of [...byMeasure.keys()].sort((a, b) => a - b)) {
+    const bpm = byMeasure.get(measure);
+    if (bpm === prev) continue;
+    out.push({ measure, bpm });
+    prev = bpm;
+  }
+  return out.length > 0 ? out : void 0;
+}
+function withNormalizedTempoChanges(doc) {
+  const changes = normalizeTempoChanges(doc.tempo, doc.tempoChanges, doc.measures.length);
+  const { tempoChanges: _t, ...rest } = doc;
+  return changes ? { ...rest, tempoChanges: changes } : rest;
+}
+function shiftTempoChangesForInsert(doc, index) {
+  if (!doc.tempoChanges) return doc;
+  return {
+    ...doc,
+    tempoChanges: doc.tempoChanges.map(
+      (t) => t.measure >= index ? { ...t, measure: t.measure + 1 } : t
+    )
+  };
+}
+function shiftTempoChangesForDelete(doc, index) {
+  if (!doc.tempoChanges) return doc;
+  let tempo = doc.tempo;
+  const changes = [];
+  for (const t of doc.tempoChanges) {
+    if (t.measure === index) continue;
+    const measure = t.measure > index ? t.measure - 1 : t.measure;
+    if (measure === 0) tempo = t.bpm;
+    else changes.push({ ...t, measure });
+  }
+  const canonical = normalizeTempoChanges(tempo, changes, Number.POSITIVE_INFINITY);
+  const { tempoChanges: _t, ...rest } = doc;
+  return canonical ? { ...rest, tempo, tempoChanges: canonical } : { ...rest, tempo };
+}
 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)) {
@@ -211,6 +276,9 @@ function normalizeDocument(data) {
   if (typeof data.artist !== "string") data.artist = "";
   if (!Array.isArray(data.sections)) data.sections = [];
   if (typeof data.tempo !== "number") data.tempo = DEFAULT_TEMPO;
+  const tempoChanges = normalizeTempoChanges(data.tempo, data.tempoChanges, data.measures.length);
+  if (tempoChanges) data.tempoChanges = tempoChanges;
+  else delete data.tempoChanges;
   if (!data.mix || typeof data.mix.melody !== "number") {
     data.mix = { ...DEFAULT_MIX };
   }
@@ -458,8 +526,10 @@ function closeWorkspace(doc) {
     mainTrack: _mt,
     tracks: _tr,
     formatRevision,
+    tempoChanges: rawTempoChanges,
     ...rest
   } = doc;
+  const tempoChanges = normalizeTempoChanges(doc.tempo, rawTempoChanges, main.measures.length);
   const out = {
     ...rest,
     tuning: [...main.tuning],
@@ -476,10 +546,14 @@ function closeWorkspace(doc) {
   const mainIsDefault = mainMeta.name === DEFAULT_MAIN_TRACK_NAME && mainMeta.volume === 1 && !mainMeta.muted;
   if (extras.length > 0 || !mainIsDefault) out.mainTrack = mainMeta;
   if (extras.length > 0) out.tracks = extras;
+  if (tempoChanges) out.tempoChanges = tempoChanges;
   let required = 1;
-  if (extras.length > 0) required = MULTI_TRACK_FORMAT_REVISION;
-  if (bodies.some((b) => measuresHaveHarmonics(b.measures))) required = HARMONICS_FORMAT_REVISION;
-  const revision = formatRevision != null && formatRevision > HARMONICS_FORMAT_REVISION ? formatRevision : required;
+  if (extras.length > 0) required = Math.max(required, MULTI_TRACK_FORMAT_REVISION);
+  if (bodies.some((b) => measuresHaveHarmonics(b.measures))) {
+    required = Math.max(required, HARMONICS_FORMAT_REVISION);
+  }
+  if (tempoChanges) required = Math.max(required, TEMPO_CHANGES_FORMAT_REVISION);
+  const revision = formatRevision != null && formatRevision > SUPPORTED_FORMAT_REVISION ? formatRevision : required;
   if (revision > 1) out.formatRevision = revision;
   return out;
 }
@@ -808,24 +882,28 @@ function render(doc, from = 0, to = doc.measures.length - 1, track) {
   main.measures.forEach((_, m) => {
     const k = doc.keys.find((x) => x.measure === m);
     const s = doc.sections.find((x) => x.measure === m);
+    const t = doc.tempoChanges?.find((x) => x.measure === m);
     if (k) ann.push(`m${m}:key=${k.tonic} ${k.mode}`);
+    if (t) ann.push(`m${m}:tempo=${t.bpm}`);
     if (s && s.label) ann.push(`m${m}:section="${s.label}"`);
   });
   if (ann.length) lines.push(`Markers: ${ann.join(", ")}`);
   main.measures.forEach((m, mi) => {
     if (mi < from || mi > to) return;
     const key = activeKeyAt(doc.keys, mi);
+    const change = doc.tempoChanges?.find((x) => x.measure === mi);
+    const tempoNote = change ? `, tempo ${change.bpm}` : "";
     lines.push("");
     if (!multi) {
       lines.push(
-        `--- measure ${mi} (bar ${mi + 1})  (${m.beats}/${m.beatUnit}, ${subText(m)}, ${columnCount(m)} cols, key ${key.tonic} ${key.mode}) ---`
+        `--- measure ${mi} (bar ${mi + 1})  (${m.beats}/${m.beatUnit}, ${subText(m)}, ${columnCount(m)} cols, key ${key.tonic} ${key.mode}${tempoNote}) ---`
       );
       lines.push(chordLine(m));
       measureRows(lines, m, main.tuning);
       return;
     }
     lines.push(
-      `--- measure ${mi} (bar ${mi + 1})  (${m.beats}/${m.beatUnit}, key ${key.tonic} ${key.mode}) ---`
+      `--- measure ${mi} (bar ${mi + 1})  (${m.beats}/${m.beatUnit}, key ${key.tonic} ${key.mode}${tempoNote}) ---`
     );
     lines.push(`${chordLine(m)}   (columns of track 0)`);
     for (const t of shown) {
@@ -871,7 +949,7 @@ var IMPORT_TAB_FROM_IMAGE = `Transcribe the TAB in the attached image(s) into an
 - From the image work out: instrument and string count (6 lines = guitar, 4 = bass), tuning if printed (assume standard otherwise), time signature, key signature, tempo mark, and how many bars you will transcribe. Printed bar numbers (e.g. 35, 36 \u2026) are just labels \u2014 the document starts at measure 0.
 - Start with new_tab (preset "Guitar (6)" / "Bass (4)" / \u2026, measures: 1, title if known). If the user is adding to a document already open in this session, append to it instead.
 - To transcribe several parts into one tab (e.g. guitar + bass), write the first part on track 0, then add_track for each further part and pass its \`track\` index to write_measures. Measures and time signatures are shared by all tracks; chords (@Name) go on track 0 only.
-- Set the key with set_key when there is a key signature (1 flat \u2192 F major, or D minor if the harmony says so), and the tempo with set_tempo when one is printed.
+- Set the key with set_key when there is a key signature (1 flat \u2192 F major, or D minor if the harmony says so), and the tempo with set_tempo when one is printed. A tempo mark printed later in the piece (e.g. \u2669=96 over a bar) is a tempo change: set_tempo with that bar's 0-based \`measure\`.
 
 ## 2. Write bar by bar with write_measures
 Read each bar's rhythm first (beams, flags, dots, tuplet brackets, rests), then the fret numbers, then write it. Send a few bars per call, in order. In a fresh document the first bar goes to measure 0 (replacing the empty measure new_tab made); after that append at the current measure count.
@@ -907,7 +985,7 @@ var state = {
   source: null
 };
 var server = new McpServer(
-  { name: "eztab", version: "0.4.1" },
+  { name: "eztab", version: "0.5.0" },
   {
     instructions: "All indices are 0-based: measure 0 is the first measure, string 0 is the top (highest) string, and column 0 is the first column. Notes and chords share the same column grid. Subdivisions are per beat and can differ within a measure (e.g. [2,2,3,2] mixes a triplet beat into straight eighths), so columns per measure = the sum of its per-beat subdivisions; get_tab's ruler shows the column indices. add_measures `at` is a 0-based insert position too. No need to ask the user about indexing. Exception: write_measures uses guitar string numbers (1 = top line), matching the labels get_tab prints. To write whole measures (e.g. transcribing a score or an image), prefer write_measures over set_cells \u2014 it takes one string per beat and does the column arithmetic for you. For transcribing from an image, follow the import_tab_from_image prompt. To deliver a result to the EZTab app, call send_to_eztab; to fix an existing tab, list_tabs \u2192 open_tab \u2192 edit \u2192 send_to_eztab. A tab can hold up to 4 tracks (parts, e.g. guitar + bass); track 0 is the main track. Tools that edit notes take an optional 0-based `track` (default 0). Measures and time signatures are shared by all tracks (adding/removing a measure affects every track); subdivisions are per track; chords belong to track 0 and use its columns."
   }
@@ -938,7 +1016,7 @@ function edit(track, mutate) {
   const before = onTrack(current, track);
   const doc = structuredClone(before);
   mutate(doc);
-  state.doc = reconcileTracks(before, doc);
+  state.doc = reconcileTracks(before, withNormalizedTempoChanges(doc));
   state.version += 1;
   return state.doc;
 }
@@ -1280,10 +1358,33 @@ server.tool(
 );
 server.tool(
   "set_tempo",
-  "Set the playback tempo (BPM).",
-  { bpm: z.number().int().min(20).max(400) },
+  "Set the playback tempo (quarter-note BPM). Without `measure` (or 0) this is the tempo at the start of the song; with `measure` >= 1 it sets a tempo change starting at that measure (an existing change there is updated). A tempo lasts until the next change. A change equal to the tempo before it is dropped.",
+  {
+    bpm: z.number().int().min(20).max(400),
+    measure: z.number().int().min(0).optional()
+  },
+  async (a) => applyEdit((doc) => {
+    const measure = a.measure ?? 0;
+    assertMeasure(doc, measure);
+    if (measure === 0) {
+      doc.tempo = a.bpm;
+      return;
+    }
+    const changes = (doc.tempoChanges ?? []).filter((t) => t.measure !== measure);
+    changes.push({ measure, bpm: a.bpm });
+    doc.tempoChanges = changes.sort((x, y) => x.measure - y.measure);
+  })
+);
+server.tool(
+  "remove_tempo",
+  "Remove the tempo change at `measure` (>= 1); the tempo before it then carries on. The start tempo (measure 0) cannot be removed.",
+  { measure: z.number().int() },
   async (a) => applyEdit((doc) => {
-    doc.tempo = a.bpm;
+    if (a.measure === 0) throw new Error("cannot remove the start tempo; use set_tempo");
+    if (tempoSourceAt(doc, a.measure) !== a.measure) {
+      throw new Error(`no tempo change at measure ${a.measure}`);
+    }
+    doc.tempoChanges = doc.tempoChanges?.filter((t) => t.measure !== a.measure);
   })
 );
 server.tool(
@@ -1345,6 +1446,7 @@ server.tool(
       doc.measures.splice(at, 0, createMeasure(doc.tuning.length));
       doc.keys = shiftKeysForInsert(doc.keys, at);
       doc.sections = shiftSectionsForInsert(doc.sections, at);
+      doc.tempoChanges = shiftTempoChangesForInsert(doc, at).tempoChanges;
     }
   })
 );
@@ -1358,6 +1460,9 @@ server.tool(
     doc.measures.splice(a.measure, 1);
     doc.keys = shiftKeysForDelete(doc.keys, a.measure);
     doc.sections = shiftSectionsForDelete(doc.sections, a.measure);
+    const shifted = shiftTempoChangesForDelete(doc, a.measure);
+    doc.tempo = shifted.tempo;
+    doc.tempoChanges = shifted.tempoChanges;
   })
 );
 server.tool(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hidechae/eztab-mcp",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "MCP server for EZTab \u2014 lets an AI agent build and edit guitar/bass tablature.",
   "type": "module",
   "bin": {