@hidechae/eztab-mcp 0.4.0 → 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;
 }
@@ -724,6 +798,18 @@ function parseBeat(text2, stringCount, where) {
     return { cells, chord };
   });
 }
+var STRAIGHT = [1, 2, 4, 8];
+function uniformBeats(beats) {
+  const target = Math.max(0, ...beats.map((b) => b.length).filter((n) => STRAIGHT.includes(n)));
+  return beats.map((slots) => {
+    if (!STRAIGHT.includes(slots.length) || slots.length === target) return slots;
+    const step = target / slots.length;
+    return Array.from(
+      { length: target },
+      (_, i) => i % step === 0 ? slots[i / step] : { cells: /* @__PURE__ */ new Map(), chord: null }
+    );
+  });
+}
 function buildMeasure(spec, stringCount, fallback, where = "measure") {
   const time = spec.time ? parseTime(spec.time) : fallback;
   if (spec.beats.length !== time.beats) {
@@ -731,7 +817,9 @@ function buildMeasure(spec, stringCount, fallback, where = "measure") {
       `${where}: ${spec.beats.length} beats given but the time signature ${time.beats}/${time.beatUnit} has ${time.beats}`
     );
   }
-  const beats = spec.beats.map((b, i) => parseBeat(b, stringCount, `${where} beat ${i + 1}`));
+  const beats = uniformBeats(
+    spec.beats.map((b, i) => parseBeat(b, stringCount, `${where} beat ${i + 1}`))
+  );
   const measure = createMeasure(
     stringCount,
     time.beats,
@@ -794,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) {
@@ -857,11 +949,11 @@ 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.
-- Subdivision per beat = the fewest slots that put every onset of the beat on a slot: quarter \u2192 1, eighths \u2192 2, 16ths or dotted-8th + 16th \u2192 4, triplet \u2192 3. Only onsets are stored; a held note is just empty slots ("-") after it.
+- Subdivision per beat = the fewest slots that put every onset of the beat on a slot: quarter \u2192 1, eighths \u2192 2, 16ths or dotted-8th + 16th \u2192 4, triplet \u2192 3. Only onsets are stored; a held note is just empty slots ("-") after it. write_measures then evens out the straight beats of each measure to the finest one (a bar with any 16ths is stored all in 16ths; triplet / sextuplet beats stay as they are), so you do not need to pad beats yourself.
 - Use the TAB numbers for frets, and the staff notation (when present) to settle rhythm and ambiguous digits. String 1 is the TOP line of the TAB.
 - Chord names printed above the staff go on the chord row with @Name at the slot where the chord changes (usually beat 1).
 - Rests: write S:r on the string that was ringing only when the line clearly stops (a rest symbol); otherwise leave "-".
@@ -893,7 +985,7 @@ var state = {
   source: null
 };
 var server = new McpServer(
-  { name: "eztab", version: "0.4.0" },
+  { 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."
   }
@@ -924,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;
 }
@@ -1141,7 +1233,7 @@ server.tool(
 );
 server.tool(
   "write_measures",
-  'Write whole measures, one text string per beat \u2014 the easiest way to transcribe a score. Each listed measure is replaced entirely (notes, chords, per-beat subdivisions). `measure` is the 0-based index; using the current measure count appends, so a transcription can be written in order without add_measures. `time` (e.g. "4/4", "6/8") is optional: it defaults to the measure being replaced, or the previous measure when appending. `beats` has exactly one string per beat of the time signature.\n\nA beat string is space-separated slots; the slot count is that beat\'s subdivision (1 = quarter, 2 = eighths, 3 = eighth triplet, 4 = sixteenths, 6 = sixteenth triplet \u2026). Pick the smallest count that puts every onset of the beat on a slot (a dotted eighth + sixteenth = 4 slots: note - - note). A slot is "-" (nothing starts there; the previous note rings on) or items joined by "+":\n  S:F    string S (1 = top line of the TAB, as printed) at fret F\n  S:~F   tied / slurred from the previous note on that string (hammer-on, pull-off, slide into F, or a tie when F is the same fret)\n  S:Fb / S:FB / S:F^   choke (bend) \xBD / 1 / 1\xBD steps\n  S:Fp   palm (bridge) mute; combines, e.g. S:~5p, S:7Bp\n  S:<P>  natural harmonic touched at fret P (S:<12>, S:<7>; between frets S:<2.4>)\n  S:F<P> artificial harmonic: fret F, harmonic at P (S:7<19>); S:Fa = artificial, position not written\n  S:Fh   pinch harmonic (P.H.); S:F<P>h = pinch harmonic at P (S:7<19>h)\n  S:x    muted dead-note stroke (brushing)\n  S:r    rest: stops the note ringing on that string\n  @Name  chord name onset for the chord row (e.g. @Am7, @N.C.)\nExamples: ["6:5 6:7", "5:5 5:7", "4:5 - 4:7", "@F+4:3+3:2+2:1+1:1"].',
+  'Write whole measures, one text string per beat \u2014 the easiest way to transcribe a score. Each listed measure is replaced entirely (notes, chords, per-beat subdivisions). `measure` is the 0-based index; using the current measure count appends, so a transcription can be written in order without add_measures. `time` (e.g. "4/4", "6/8") is optional: it defaults to the measure being replaced, or the previous measure when appending. `beats` has exactly one string per beat of the time signature.\n\nA beat string is space-separated slots; the slot count is that beat\'s subdivision (1 = quarter, 2 = eighths, 3 = eighth triplet, 4 = sixteenths, 6 = sixteenth triplet \u2026). Pick the smallest count that puts every onset of the beat on a slot (a dotted eighth + sixteenth = 4 slots: note - - note). Within a measure the straight beats are evened out to the finest one (a quarter-note beat next to a sixteenth beat is stored as 4 slots), so write each beat as is; tuplet beats keep their own count. A slot is "-" (nothing starts there; the previous note rings on) or items joined by "+":\n  S:F    string S (1 = top line of the TAB, as printed) at fret F\n  S:~F   tied / slurred from the previous note on that string (hammer-on, pull-off, slide into F, or a tie when F is the same fret)\n  S:Fb / S:FB / S:F^   choke (bend) \xBD / 1 / 1\xBD steps\n  S:Fp   palm (bridge) mute; combines, e.g. S:~5p, S:7Bp\n  S:<P>  natural harmonic touched at fret P (S:<12>, S:<7>; between frets S:<2.4>)\n  S:F<P> artificial harmonic: fret F, harmonic at P (S:7<19>); S:Fa = artificial, position not written\n  S:Fh   pinch harmonic (P.H.); S:F<P>h = pinch harmonic at P (S:7<19>h)\n  S:x    muted dead-note stroke (brushing)\n  S:r    rest: stops the note ringing on that string\n  @Name  chord name onset for the chord row (e.g. @Am7, @N.C.)\nExamples: ["6:5 6:7", "5:5 5:7", "4:5 - 4:7", "@F+4:3+3:2+2:1+1:1"].',
   {
     measures: z.array(
       z.object({
@@ -1266,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) => {
-    doc.tempo = a.bpm;
+    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) => {
+    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(
@@ -1331,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;
     }
   })
 );
@@ -1344,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.0",
+  "version": "0.5.0",
   "description": "MCP server for EZTab \u2014 lets an AI agent build and edit guitar/bass tablature.",
   "type": "module",
   "bin": {