@hidechae/eztab-mcp 0.4.1 → 0.5.1

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) |
@@ -113,8 +113,16 @@ Run standalone for testing: `task mcp` (or `npx tsx mcp/server.ts`).
 - コードは track 0 のもの(`set_chords` は track 0 の列で指定)。`write_measures(track > 0)` ではコード指定と、
   既存小節の拍子を変える `time` を拒否する
 - `get_tab` は全パートを小節ごとに並べて表示する(`track` で1パートに絞れる)
-- `send_to_eztab` は `x-eztab-format-revision: 2` を付けて送る。0.2.0 以前の MCP は複数パートのタブを
-  送り返せない(サーバが 409 で拒否する)。新しい形式のタブ(リビジョン 3 以降)は読めるが編集・送信できない
+- `send_to_eztab` は対応する最新の形式リビジョンをヘッダーに付けて送る(0.5.1では `5`)。
+  対応上限を超える形式のタブは閲覧のみで、編集・送信できない。
+  0.2.0以前のMCPは複数パートのタブを送り返せない(サーバが409で拒否する)。
+
+### 小節メモの保持
+
+0.5.1以降はアプリで入力した小節共通メモ(形式リビジョン5)を保持して編集・送信できます。
+メモ専用の入力ツールはなく、追加・変更・削除はアプリの「小節メモ…」で行います。
+`write_measures` で既存小節を書き換えた場合もメモを残します。小節削除ではその小節のメモも削除し、
+挿入した空小節はメモなしになります。旧MCPはメモのあるタブを編集・送信できません。
 
 These cover the editor's current model: variable string count, per-beat chords,
 keys with mid-piece changes, section markers, per-measure resolution, time

package/dist/server.js

@@ -7,12 +7,16 @@ import { z } from "zod";
 
 // ../src/types/tab.ts
 var TAB_FILE_VERSION = 1;
-var SUPPORTED_FORMAT_REVISION = 3;
+var SUPPORTED_FORMAT_REVISION = 5;
 var MULTI_TRACK_FORMAT_REVISION = 2;
 var HARMONICS_FORMAT_REVISION = 3;
+var TEMPO_CHANGES_FORMAT_REVISION = 4;
+var MEASURE_MEMOS_FORMAT_REVISION = 5;
 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 +32,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)) {
@@ -128,6 +194,15 @@ function makeNoteCell(fret, bend, tie, pm, harmonic) {
     ...harm && harmonic?.harmAt != null ? { harmAt: harmonic.harmAt } : {}
   };
 }
+var MAX_MEASURE_MEMO_LENGTH = 1e3;
+function normalizeMeasureMemo(raw) {
+  if (typeof raw !== "string") return void 0;
+  const memo = raw.replace(/\r\n?|\n/g, "\n");
+  if (memo.length > MAX_MEASURE_MEMO_LENGTH) {
+    throw new Error(`Measure memo exceeds ${MAX_MEASURE_MEMO_LENGTH} characters`);
+  }
+  return memo.trim() ? memo : void 0;
+}
 var CHORD_REST = "rest";
 var CHORD_REST_LABEL = "N.C.";
 function chordDisplay(label) {
@@ -203,7 +278,15 @@ function normalizeDocument(data) {
     );
     const rawChords = Array.isArray(m.chords) ? m.chords : typeof m.chord === "string" && m.chord ? [m.chord] : [];
     const chords = normalizeChords(rawChords, subdivisions);
-    return { beats, beatUnit, subdivisions, cells, chords };
+    const memo = normalizeMeasureMemo(m.memo);
+    return {
+      beats,
+      beatUnit,
+      subdivisions,
+      cells,
+      chords,
+      ...memo !== void 0 ? { memo } : {}
+    };
   });
   if (!Array.isArray(data.keys) || data.keys.length === 0) {
     data.keys = [{ measure: 0, tonic: "C", mode: "major" }];
@@ -211,6 +294,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 };
   }
@@ -391,8 +477,9 @@ function newUid() {
   return newTabId();
 }
 function storedMeasure(m) {
-  const { uid: _uid, beatWidthOverride: _w, ...rest } = m;
-  return rest;
+  const { uid: _uid, beatWidthOverride: _w, memo, ...rest } = m;
+  const normalizedMemo = normalizeMeasureMemo(memo);
+  return normalizedMemo === void 0 ? rest : { ...rest, memo: normalizedMemo };
 }
 function openWorkspace(doc) {
   if (doc.workspace) return doc;
@@ -458,8 +545,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 +565,17 @@ 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);
+  if (out.measures.some((m) => m.memo !== void 0)) {
+    required = Math.max(required, MEASURE_MEMOS_FORMAT_REVISION);
+  }
+  const revision = formatRevision != null && formatRevision > SUPPORTED_FORMAT_REVISION ? formatRevision : required;
   if (revision > 1) out.formatRevision = revision;
   return out;
 }
@@ -488,6 +584,20 @@ function reconcileTracks(prev, next) {
   const ws = doc.workspace;
   const measures = assignUids(prev, doc.measures);
   if (measures !== doc.measures) doc = { ...doc, measures };
+  if (ws.active === 0 && prev) {
+    const oldMemos = new Map(mainMeasures(prev).map((m) => [m.uid, m.memo]));
+    let restored = null;
+    measures.forEach((m, i) => {
+      const memo = oldMemos.get(m.uid);
+      if (memo !== void 0 && !("memo" in m)) {
+        restored ??= [...measures];
+        restored[i] = { ...m, memo };
+      }
+    });
+    if (restored) {
+      doc = { ...doc, measures: restored };
+    }
+  }
   let changed = false;
   const parked = ws.parked.map((body) => {
     if (!body) return body;
@@ -808,24 +918,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 +985,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 +1021,7 @@ var state = {
   source: null
 };
 var server = new McpServer(
-  { name: "eztab", version: "0.4.1" },
+  { name: "eztab", version: "0.5.1" },
   {
     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 +1052,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;
 }
@@ -1200,7 +1314,7 @@ server.tool(
         }
       }
       if (!existing) doc.measures.push(built);
-      else doc.measures[i] = built;
+      else doc.measures[i] = a.track ? built : { ...built, memo: existing.memo };
       lo = Math.min(lo, i);
       hi = Math.max(hi, i);
     }
@@ -1280,10 +1394,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(
@@ -1345,6 +1482,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 +1496,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.1",
   "description": "MCP server for EZTab \u2014 lets an AI agent build and edit guitar/bass tablature.",
   "type": "module",
   "bin": {