@hidechae/eztab-mcp 0.2.0 → 0.3.0

package/README.md

@@ -47,11 +47,16 @@ npm versions are immutable, so publishing is deliberate (tag-driven):
 
 ```sh
 # bump mcp/package.json "version", commit, then:
-git tag mcp-v0.1.3 && git push --tags
+git tag mcp-vX.Y.Z origin/main && git push origin mcp-vX.Y.Z
 ```
 
-The `Publish MCP to npm` GitHub Action builds and publishes on `mcp-v*` tags
-(needs the `NPM_TOKEN` repo secret).
+The `Publish MCP to npm` GitHub Action builds and publishes on `mcp-v*` tags.
+認証は npm の Trusted Publishing(GitHub Actions の OIDC)で、トークンの Secret は不要。
+npmjs.com のパッケージ設定で `hidechae/eztab` の `publish-mcp.yml` を Trusted Publisher に
+登録してある前提。タグ名と `mcp/package.json` の version が一致しないと公開しない。
+公開に失敗したタグをやり直すときは、失敗した run の re-run ではなく(古いワークフローのまま
+再実行される)、`Publish MCP to npm` を workflow_dispatch し、`tag` にそのタグを指定する
+(`gh workflow run publish-mcp.yml -f tag=mcp-vX.Y.Z`)。指定したタグの中身が公開される。
 
 ## Setup (local dev)
 
@@ -95,7 +100,21 @@ Run standalone for testing: `task mcp` (or `npx tsx mcp/server.ts`).
 | `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) |
-| `set_tuning` | Replace tuning / string count |
+| `set_tuning` | Replace tuning / string count (`track` で対象パートを指定) |
+| `add_track` / `remove_track` | パート(ベース・2本目のギターなど)の追加・削除。メインを含めて最大4、track 0(メイン)は削除不可 |
+
+### 複数パート(トラック)
+
+1つのタブにメインを含めて最大4パートを持てる(docs/design/0001-multiple-tracks.md)。
+
+- `set_cells` / `write_measures` / `set_resolution` / `set_tuning` は任意の `track`(0 始まり、既定 0 = メイン)を取る
+- 小節と拍子は全パート共通。`add_measures` / `remove_measure` / `set_time_signature` は全パートに作用し、
+  `write_measures` で末尾に書き足すと全パートに小節が増える。分割(subdivisions)はパートごと
+- コードは 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 以降)は読めるが編集・送信できない
 
 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,6 +7,10 @@ import { z } from "zod";
 
 // ../src/types/tab.ts
 var TAB_FILE_VERSION = 1;
+var SUPPORTED_FORMAT_REVISION = 2;
+var MULTI_TRACK_FORMAT_REVISION = 2;
+var MAX_TRACKS = 4;
+var DEFAULT_MAIN_TRACK_NAME = "Guitar";
 var DEFAULT_TEMPO = 120;
 var DEFAULT_MIX = { melody: 1, backing: 0.4 };
 function shiftSectionsForInsert(sections, index) {
@@ -126,9 +130,59 @@ function normalizeDocument(data) {
   if (!data.mix || typeof data.mix.melody !== "number") {
     data.mix = { ...DEFAULT_MIX };
   }
+  normalizeTracks(data);
   data.version = TAB_FILE_VERSION;
   return data;
 }
+function normalizeTrackMeta(raw, fallbackName) {
+  const volume = Number(raw?.volume);
+  return {
+    id: typeof raw?.id === "string" && raw.id ? raw.id : newTabId(),
+    name: typeof raw?.name === "string" && raw.name.trim() ? raw.name : fallbackName,
+    volume: Number.isFinite(volume) ? Math.max(0, Math.min(1, volume)) : 1,
+    muted: raw?.muted === true
+  };
+}
+function defaultMainTrack() {
+  return { id: newTabId(), name: DEFAULT_MAIN_TRACK_NAME, volume: 1, muted: false };
+}
+function normalizeTracks(data) {
+  if (data.trackMismatch !== true) delete data.trackMismatch;
+  delete data.workspace;
+  const rawTracks = Array.isArray(data.tracks) ? data.tracks : [];
+  if (data.mainTrack != null || rawTracks.length > 0) {
+    data.mainTrack = normalizeTrackMeta(data.mainTrack, DEFAULT_MAIN_TRACK_NAME);
+  }
+  if (rawTracks.length === 0) {
+    delete data.tracks;
+    return;
+  }
+  const measures = data.measures;
+  data.tracks = rawTracks.slice(0, MAX_TRACKS - 1).map((t, i) => {
+    const tuning = Array.isArray(t?.tuning) && t.tuning.length > 0 && t.tuning.every((n) => typeof n === "string") ? [...t.tuning] : [...PRESET_TUNINGS["Guitar (6)"]];
+    const rawMeasures = Array.isArray(t?.measures) ? t.measures : [];
+    if (rawMeasures.length !== measures.length) data.trackMismatch = true;
+    return {
+      ...normalizeTrackMeta(t, `Track ${i + 2}`),
+      tuning,
+      measures: measures.map((m, mi) => fitTrackMeasure(rawMeasures[mi], m, tuning.length))
+    };
+  });
+}
+function fitTrackMeasure(raw, main, stringCount) {
+  const rawSubs = Array.isArray(raw?.subdivisions) ? raw.subdivisions : [];
+  const subdivisions = Array.from({ length: main.beats }, (_, b) => {
+    const v = rawSubs[Math.min(b, rawSubs.length - 1)];
+    return typeof v === "number" && Number.isInteger(v) && v >= 1 && v <= MAX_SUBDIVISION ? v : DEFAULT_SUBDIVISIONS;
+  });
+  const cols = subdivisions.reduce((a, b) => a + b, 0);
+  const rows = Array.isArray(raw?.cells) ? raw.cells : [];
+  const cells = Array.from(
+    { length: stringCount },
+    (_, s) => Array.from({ length: cols }, (_2, c) => rows[s]?.[c] ?? null)
+  );
+  return { subdivisions, cells };
+}
 var MAX_SUBDIVISION = 12;
 var PRESET_TUNING_GROUPS = [
   {
@@ -248,6 +302,202 @@ function setBeatSubdivision(measure, beat, subdivision) {
   return remapToSubdivisions(measure, subs);
 }
 
+// ../src/lib/tracks.ts
+function newUid() {
+  return newTabId();
+}
+function storedMeasure(m) {
+  const { uid: _uid, ...rest } = m;
+  return rest;
+}
+function openWorkspace(doc) {
+  if (doc.workspace) return doc;
+  const measures = doc.measures.map((m) => ({ ...m, uid: m.uid ?? newUid() }));
+  const extras = doc.tracks ?? [];
+  const metas = [
+    doc.mainTrack ?? defaultMainTrack(),
+    ...extras.map(({ tuning: _t, measures: _m, ...meta }) => meta)
+  ];
+  const parked = [
+    null,
+    ...extras.map(
+      (t) => ({
+        tuning: [...t.tuning],
+        measures: measures.map(
+          (main, i) => trackMeasureToMeasure(
+            main,
+            t.measures[i]?.subdivisions,
+            t.measures[i]?.cells,
+            t.tuning.length
+          )
+        )
+      })
+    )
+  ];
+  const { mainTrack: _mt, tracks: _tr, ...rest } = doc;
+  return { ...rest, measures, workspace: { active: 0, metas, parked } };
+}
+function trackMeasureToMeasure(main, subdivisions, cells, stringCount) {
+  const base = createMeasure(
+    stringCount,
+    main.beats,
+    subdivisions ?? main.subdivisions,
+    main.beatUnit
+  );
+  return {
+    ...base,
+    cells: base.cells.map((row, s) => row.map((_, c) => cells?.[s]?.[c] ?? null)),
+    uid: main.uid
+  };
+}
+function trackBodies(doc) {
+  const ws = doc.workspace;
+  if (!ws) return [{ tuning: doc.tuning, measures: doc.measures }];
+  return ws.parked.map(
+    (b, i) => i === ws.active ? { tuning: doc.tuning, measures: doc.measures } : b
+  );
+}
+function trackMetas(doc) {
+  return doc.workspace?.metas ?? [doc.mainTrack ?? defaultMainTrack()];
+}
+function mainMeasures(doc) {
+  return trackBodies(doc)[0].measures;
+}
+function closeWorkspace(doc) {
+  const ws = doc.workspace;
+  if (!ws) return doc;
+  const bodies = trackBodies(doc);
+  const main = bodies[0];
+  const {
+    workspace: _ws,
+    trackMismatch: _tm,
+    mainTrack: _mt,
+    tracks: _tr,
+    formatRevision,
+    ...rest
+  } = doc;
+  const out = {
+    ...rest,
+    tuning: [...main.tuning],
+    measures: main.measures.map(storedMeasure)
+  };
+  const extras = bodies.slice(1).map(
+    (b, i) => ({
+      ...ws.metas[i + 1],
+      tuning: [...b.tuning],
+      measures: b.measures.map((m) => ({ subdivisions: m.subdivisions, cells: m.cells }))
+    })
+  );
+  const mainMeta = ws.metas[0];
+  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;
+    out.formatRevision = Math.max(formatRevision ?? 1, MULTI_TRACK_FORMAT_REVISION);
+  } else if (formatRevision != null && formatRevision > MULTI_TRACK_FORMAT_REVISION) {
+    out.formatRevision = formatRevision;
+  }
+  return out;
+}
+function reconcileTracks(prev, next) {
+  let doc = next.workspace ? next : openWorkspace(next);
+  const ws = doc.workspace;
+  const measures = assignUids(prev, doc.measures);
+  if (measures !== doc.measures) doc = { ...doc, measures };
+  let changed = false;
+  const parked = ws.parked.map((body) => {
+    if (!body) return body;
+    const fitted = fitBody(body, measures);
+    if (fitted !== body) changed = true;
+    return fitted;
+  });
+  if (changed) doc = { ...doc, workspace: { ...ws, parked } };
+  return doc;
+}
+function assignUids(prev, measures) {
+  const seen = /* @__PURE__ */ new Set();
+  let out = null;
+  const present = new Set(measures.map((m) => m.uid).filter(Boolean));
+  measures.forEach((m, i) => {
+    let uid = m.uid;
+    if (uid && seen.has(uid)) uid = void 0;
+    if (!uid) {
+      const old = prev?.measures[i]?.uid;
+      uid = old && !present.has(old) && !seen.has(old) ? old : newUid();
+      out ??= [...measures];
+      out[i] = { ...m, uid };
+    }
+    seen.add(uid);
+  });
+  return out ?? measures;
+}
+function fitBody(body, measures) {
+  const same = body.measures.length === measures.length && body.measures.every(
+    (m, i) => m.uid === measures[i].uid && m.beats === measures[i].beats && m.beatUnit === measures[i].beatUnit
+  );
+  if (same) return body;
+  const byUid = new Map(body.measures.map((m) => [m.uid, m]));
+  const stringCount = body.tuning.length;
+  const out = [];
+  measures.forEach((m) => {
+    let pm = byUid.get(m.uid);
+    if (!pm) {
+      const before = out[out.length - 1];
+      const subs = before && before.beats === m.beats ? before.subdivisions : void 0;
+      pm = createMeasure(stringCount, m.beats, subs, m.beatUnit);
+    } else if (pm.beats !== m.beats || pm.beatUnit !== m.beatUnit) {
+      pm = setMeasureTimeSignature(pm, m.beats, m.beatUnit);
+    }
+    out.push({ ...pm, uid: m.uid });
+  });
+  return { ...body, measures: out };
+}
+function switchTrack(doc, index) {
+  const ws = doc.workspace;
+  if (!ws || index === ws.active || index < 0 || index >= ws.metas.length) return doc;
+  const parked = [...ws.parked];
+  parked[ws.active] = { tuning: doc.tuning, measures: doc.measures };
+  const body = parked[index];
+  parked[index] = null;
+  return {
+    ...doc,
+    tuning: body.tuning,
+    measures: body.measures,
+    workspace: { ...ws, active: index, parked }
+  };
+}
+function addTrack(doc, name, tuning) {
+  const ws = doc.workspace;
+  if (!ws || ws.metas.length >= MAX_TRACKS) return doc;
+  const main = mainMeasures(doc);
+  const body = {
+    tuning: [...tuning],
+    measures: main.map((m) => ({
+      ...createMeasure(tuning.length, m.beats, m.subdivisions, m.beatUnit),
+      uid: m.uid
+    }))
+  };
+  const meta = { id: newTabId(), name, volume: 1, muted: false };
+  const added = {
+    ...doc,
+    workspace: { ...ws, metas: [...ws.metas, meta], parked: [...ws.parked, body] }
+  };
+  return switchTrack(added, ws.metas.length);
+}
+function removeTrack(doc, index) {
+  const ws = doc.workspace;
+  if (!ws || index <= 0 || index >= ws.metas.length) return doc;
+  const shown = ws.active === index ? switchTrack(doc, 0) : doc;
+  const w = shown.workspace;
+  const metas = w.metas.filter((_, i) => i !== index);
+  const parked = w.parked.filter((_, i) => i !== index);
+  const active = w.active > index ? w.active - 1 : w.active;
+  return { ...shown, workspace: { active, metas, parked } };
+}
+function storedSize(doc) {
+  return new TextEncoder().encode(JSON.stringify(closeWorkspace(doc))).length;
+}
+
 // ../src/lib/config.ts
 var CLOUD_BASE_URL = "https://eztab-sync-736328841982.asia-northeast1.run.app";
 
@@ -293,7 +543,12 @@ var cloud = {
   async sendToInbox(payload) {
     await req("/inbox", {
       method: "POST",
-      headers: { "content-type": "application/json" },
+      headers: {
+        "content-type": "application/json",
+        // The newest tab format this build edits safely; the server refuses
+        // newer tabs from older builds (docs/design/0001-multiple-tracks.md).
+        "x-eztab-format-revision": String(SUPPORTED_FORMAT_REVISION)
+      },
       body: JSON.stringify(payload)
     });
   }
@@ -315,46 +570,79 @@ function cellText(cell) {
   }
   return String(cell).padStart(2, "-");
 }
-function render(doc, from = 0, to = doc.measures.length - 1) {
+function render(doc, from = 0, to = doc.measures.length - 1, track) {
+  const bodies = trackBodies(doc);
+  const metas = trackMetas(doc);
+  const multi = bodies.length > 1;
+  const main = bodies[0];
+  const shown = bodies.map((_, i) => i).filter((i) => track == null || i === track);
   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}`);
+  if (multi) {
+    lines.push(`Tracks (track index: name, tuning top\u2192bottom)   measures=${main.measures.length}`);
+    metas.forEach((t, i) => {
+      lines.push(
+        `  ${i}: ${t.name}  ${bodies[i].tuning.join(" ")}${i === 0 ? "  (main: carries the chords)" : ""}`
+      );
+    });
+  } else {
+    lines.push(`Tuning (top\u2192bottom): ${main.tuning.join(" ")}   measures=${main.measures.length}`);
+  }
   const ann = [];
-  doc.measures.forEach((_, m) => {
+  main.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}:key=${k.tonic} ${k.mode}`);
     if (s && s.label) ann.push(`m${m}:section="${s.label}"`);
   });
   if (ann.length) lines.push(`Markers: ${ann.join(", ")}`);
-  doc.measures.forEach((m, mi) => {
+  main.measures.forEach((m, mi) => {
     if (mi < from || mi > to) return;
     const key = activeKeyAt(doc.keys, mi);
-    const sub = uniformSubdivision(m);
-    const subText = sub != null ? `${sub}/beat` : `[${m.subdivisions.join(",")}]/beat`;
     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}) ---`
+      );
+      lines.push(chordLine(m));
+      measureRows(lines, m, main.tuning);
+      return;
+    }
     lines.push(
-      `--- measure ${mi} (bar ${mi + 1})  (${m.beats}/${m.beatUnit}, ${subText}, ${columnCount(m)} cols, key ${key.tonic} ${key.mode}) ---`
+      `--- measure ${mi} (bar ${mi + 1})  (${m.beats}/${m.beatUnit}, key ${key.tonic} ${key.mode}) ---`
     );
-    const chordRow = (m.chords ?? []).map((label, c) => label ? `c${c}:${chordDisplay(label)}` : null).filter(Boolean).join("  ");
-    lines.push(`chords: ${chordRow || "(none)"}`);
-    const ruler = Array.from({ length: columnCount(m) }, (_, c) => String(c).padStart(2, " ")).join(
-      " "
-    );
-    lines.push(`col:    ${ruler}`);
-    m.cells.forEach((row, s) => {
-      const label = `${s + 1} ${doc.tuning[s] ?? "?"}`.padEnd(6, " ");
-      const cells = row.map(cellText).join(" ");
-      lines.push(`${label}| ${cells}`);
-    });
-    const pm = Array.from(
-      { length: columnCount(m) },
-      (_, c) => m.cells.some((row) => cellPalmMute(row[c] ?? null)) ? "PM" : "  "
-    );
-    if (pm.some((x) => x !== "  ")) lines.push(`pm:     ${pm.join(" ")}`);
+    lines.push(`${chordLine(m)}   (columns of track 0)`);
+    for (const t of shown) {
+      const tm = bodies[t].measures[mi];
+      lines.push(`[track ${t}: ${metas[t].name}]  ${subText(tm)}, ${columnCount(tm)} cols`);
+      measureRows(lines, tm, bodies[t].tuning);
+    }
   });
   return lines.join("\n");
 }
+function subText(m) {
+  const sub = uniformSubdivision(m);
+  return sub != null ? `${sub}/beat` : `[${m.subdivisions.join(",")}]/beat`;
+}
+function chordLine(m) {
+  const row = (m.chords ?? []).map((label, c) => label ? `c${c}:${chordDisplay(label)}` : null).filter(Boolean).join("  ");
+  return `chords: ${row || "(none)"}`;
+}
+function measureRows(lines, m, tuning) {
+  const ruler = Array.from({ length: columnCount(m) }, (_, c) => String(c).padStart(2, " ")).join(
+    " "
+  );
+  lines.push(`col:    ${ruler}`);
+  m.cells.forEach((row, s) => {
+    const label = `${s + 1} ${tuning[s] ?? "?"}`.padEnd(6, " ");
+    lines.push(`${label}| ${row.map(cellText).join(" ")}`);
+  });
+  const pm = Array.from(
+    { length: columnCount(m) },
+    (_, c) => m.cells.some((row) => cellPalmMute(row[c] ?? null)) ? "PM" : "  "
+  );
+  if (pm.some((x) => x !== "  ")) lines.push(`pm:     ${pm.join(" ")}`);
+}
 
 // notation.ts
 var BEAT_UNITS2 = [2, 4, 8, 16];
@@ -449,6 +737,7 @@ var IMPORT_TAB_FROM_IMAGE = `Transcribe the TAB in the attached image(s) into an
 - Identify which staff to take. A band score has several parts (Vocal, Guitar I/II, Keyboard, Bass, Drums). If a part was not named and more than one has TAB, list the parts you see and ask which one \u2014 do not guess.
 - 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.
 
 ## 2. Write bar by bar with write_measures
@@ -480,9 +769,9 @@ var state = {
   source: null
 };
 var server = new McpServer(
-  { name: "eztab", version: "0.2.0" },
+  { name: "eztab", version: "0.3.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."
+    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."
   }
 );
 function text(s) {
@@ -494,24 +783,44 @@ function requireDoc() {
   }
   return state.doc;
 }
-function applyEdit(mutate) {
-  const doc = requireDoc();
+function onTrack(doc, track = 0) {
+  const n = trackMetas(doc).length;
+  if (!Number.isInteger(track) || track < 0 || track >= n) {
+    throw new Error(`track ${track} out of range (0..${n - 1}); get_tab lists the tracks`);
+  }
+  return switchTrack(doc, track);
+}
+function edit(track, mutate) {
+  const current = requireDoc();
+  if ((current.formatRevision ?? 1) > SUPPORTED_FORMAT_REVISION) {
+    throw new Error(
+      "This tab was saved by a newer EZTab and can only be read here. Update the EZTab MCP server (npx -y @hidechae/eztab-mcp@latest)."
+    );
+  }
+  const before = onTrack(current, track);
+  const doc = structuredClone(before);
   mutate(doc);
+  state.doc = reconcileTracks(before, doc);
   state.version += 1;
-  return text(render(doc));
+  return state.doc;
 }
-function applyEditRange(mutate) {
-  const doc = structuredClone(requireDoc());
-  const [from, to] = mutate(doc);
-  state.doc = doc;
-  state.version += 1;
-  return text(render(doc, from, to));
+function applyEdit(mutate, track) {
+  return text(render(edit(track, mutate)));
+}
+function applyEditRange(mutate, track) {
+  let range = [0, 0];
+  const doc = edit(track, (d) => {
+    range = mutate(d);
+  });
+  return text(render(doc, range[0], range[1], track));
 }
 function setDoc(doc) {
-  state.doc = doc;
+  state.doc = openWorkspace(doc);
   state.version += 1;
-  return text(render(doc));
+  return text(render(state.doc));
 }
+var MISMATCH_NOTE = "Warning: this tab's extra tracks may be shifted against the main track \u2014 an older EZTab app added or removed measures without them. Check that the tracks line up (get_tab) and ask the user before sending it back.";
+var trackParam = z.number().int().min(0).optional().describe("0-based track (part) index from get_tab; default 0, the main track.");
 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})`);
@@ -522,10 +831,14 @@ server.tool(
   "Return a readable rendering of the document currently under edit in this session. `from`/`to` (0-based, inclusive) limit it to a range of measures. If nothing has been created yet, say so and offer new_tab.",
   {
     from: z.number().int().min(0).optional(),
-    to: z.number().int().min(0).optional()
+    to: z.number().int().min(0).optional(),
+    track: trackParam.describe("Show only this track (default: all tracks).")
   },
   async (a) => {
-    if (state.doc) return text(render(state.doc, a.from, a.to));
+    if (state.doc) {
+      if (a.track != null) onTrack(state.doc, a.track);
+      return text(render(state.doc, a.from, a.to, a.track));
+    }
     return text("No document is open in this session. Call new_tab to start one.");
   }
 );
@@ -585,7 +898,17 @@ server.tool(
     if (!meta) throw new Error(`No tab with id ${a.id}. Use list_tabs to find it.`);
     const doc = normalize(await cloud.get(a.id));
     state.source = { tabId: a.id, title: meta.title, baseUpdatedAt: meta.updatedAt };
-    return setDoc(doc);
+    const shown = setDoc(doc);
+    if (doc.trackMismatch) {
+      shown.content.unshift({ type: "text", text: MISMATCH_NOTE });
+    }
+    if ((doc.formatRevision ?? 1) > SUPPORTED_FORMAT_REVISION) {
+      shown.content.unshift({
+        type: "text",
+        text: "Note: this tab was saved by a newer EZTab; it can be read but not edited here. Update the EZTab MCP server to edit it."
+      });
+    }
+    return shown;
   })
 );
 server.tool(
@@ -593,12 +916,30 @@ server.tool(
   "Send the current document to the EZTab app's inbox. The user then chooses in the app what to do with it \u2014 insert its measures at the cursor, create a new tab, or (for a document opened with open_tab) replace that tab \u2014 and it stays unsaved until they press Save. Call this once the document has been checked with get_tab.",
   {
     label: z.string().optional().describe("Short description shown in the app, e.g. 'Guitar II, bars 1\u20138'."),
+    tracks_checked: z.boolean().optional().describe(
+      "Set to true after checking with the user that the extra tracks line up, when open_tab warned that they may be shifted."
+    ),
     as_new: z.boolean().optional().describe(
       "For a document opened with open_tab: send it as new material instead of a revision of that tab."
     )
   },
   async (a) => withCloud(async () => {
-    const doc = requireDoc();
+    if (requireDoc().trackMismatch && !a.tracks_checked) {
+      throw new Error(
+        `${MISMATCH_NOTE} Not sent: confirm the alignment, then call send_to_eztab again with tracks_checked: true.`
+      );
+    }
+    const doc = closeWorkspace(requireDoc());
+    if ((doc.formatRevision ?? 1) > SUPPORTED_FORMAT_REVISION) {
+      throw new Error(
+        "This tab was saved by a newer EZTab; update the EZTab MCP server before sending it."
+      );
+    }
+    if (storedSize(doc) > 4.5 * 1024 * 1024) {
+      throw new Error(
+        "The tab is too large to send (over 4.5 MB). Remove measures or tracks, or send part of it as new material."
+      );
+    }
     const target = state.source && !a.as_new ? state.source : null;
     await cloud.sendToInbox({
       doc,
@@ -640,7 +981,8 @@ server.tool(
         tie: z.boolean().optional(),
         pm: z.boolean().optional()
       })
-    )
+    ),
+    track: trackParam
   },
   async (a) => applyEdit((doc) => {
     for (const e of a.edits) {
@@ -666,7 +1008,7 @@ server.tool(
       }
       m.cells[e.string][e.column] = value;
     }
-  })
+  }, a.track)
 );
 server.tool(
   "write_measures",
@@ -678,7 +1020,10 @@ server.tool(
         time: z.string().optional(),
         beats: z.array(z.string()).min(1)
       })
-    ).min(1)
+    ).min(1),
+    track: trackParam.describe(
+      "0-based track (part) to write; default 0. On a track other than 0, chord items (@Name) are rejected (chords belong to track 0) and `time` may not change an existing measure's time signature (it is shared by all tracks \u2014 change it on track 0). Appending adds the measure to every track."
+    )
   },
   async (a) => applyEditRange((doc) => {
     let lo = Infinity;
@@ -698,17 +1043,30 @@ server.tool(
         fallback,
         `measure ${i}`
       );
-      if (i === doc.measures.length) doc.measures.push(built);
+      const existing = doc.measures[i];
+      if (a.track) {
+        if (built.chords?.some((c) => c)) {
+          throw new Error(
+            `measure ${i}: chord items (@Name) can only be written on track 0, which carries the chords`
+          );
+        }
+        if (existing && (existing.beats !== built.beats || existing.beatUnit !== built.beatUnit)) {
+          throw new Error(
+            `measure ${i}: the time signature is shared by all tracks; change it on track 0 (time "${existing.beats}/${existing.beatUnit}" here)`
+          );
+        }
+      }
+      if (!existing) doc.measures.push(built);
       else doc.measures[i] = built;
       lo = Math.min(lo, i);
       hi = Math.max(hi, i);
     }
     return [lo, hi];
-  })
+  }, a.track)
 );
 server.tool(
   "set_chords",
-  'Set chord-name onsets per column (the same time grid as tab cells, so chords can sit on any subdivision). `measure` and `column` are 0-based; column = the sum of earlier beats\' subdivisions + slot-within-beat (see get_tab\'s ruler). A label of "rest" (or "N.C.") places a chord rest that stops the previous chord (rendered as N.C.). An empty label clears that column\'s chord.',
+  'Set chord-name onsets per column of track 0 (chords belong to the main track; the same time grid as its tab cells, so chords can sit on any subdivision). `measure` and `column` are 0-based; column = the sum of earlier beats\' subdivisions + slot-within-beat (see get_tab\'s ruler). A label of "rest" (or "N.C.") places a chord rest that stops the previous chord (rendered as N.C.). An empty label clears that column\'s chord.',
   {
     edits: z.array(
       z.object({
@@ -787,7 +1145,7 @@ server.tool(
 );
 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.",
+  "Set a measure's time signature, e.g. beats=6 beatUnit=8 for 6/8. Shared by all tracks: every track's measure is resized, preserving cells/chords by index.",
   {
     measure: z.number().int(),
     beats: z.number().int().min(1).max(32),
@@ -810,7 +1168,10 @@ server.tool(
   {
     measure: z.number().int(),
     subdivisions: z.number().int().min(1).max(12),
-    beat: z.number().int().min(0).optional()
+    beat: z.number().int().min(0).optional(),
+    track: trackParam.describe(
+      "0-based track whose grid to change; default 0. Each track has its own subdivisions."
+    )
   },
   async (a) => applyEdit((doc) => {
     assertMeasure(doc, a.measure);
@@ -825,11 +1186,11 @@ server.tool(
     } else {
       doc.measures[a.measure] = setMeasureSubdivisions(m, a.subdivisions);
     }
-  })
+  }, a.track)
 );
 server.tool(
   "add_measures",
-  "Insert `count` empty measures. Without `at`, appends; otherwise inserts before index `at`.",
+  "Insert `count` empty measures into every track. Without `at`, appends; otherwise inserts before index `at`.",
   {
     count: z.number().int().min(1).max(256).optional(),
     at: z.number().int().optional()
@@ -846,7 +1207,7 @@ server.tool(
 );
 server.tool(
   "remove_measure",
-  "Remove the measure at index `measure` (at least one is kept).",
+  "Remove the measure at index `measure` from every track (at least one is kept).",
   { measure: z.number().int() },
   async (a) => applyEdit((doc) => {
     assertMeasure(doc, a.measure);
@@ -859,11 +1220,54 @@ server.tool(
 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) },
+  { tuning: z.array(z.string()).min(1), track: trackParam },
   async (a) => applyEdit((doc) => {
     doc.tuning = [...a.tuning];
     doc.measures = doc.measures.map((m) => resizeMeasureStrings(m, a.tuning.length));
-  })
+  }, a.track)
+);
+var TRACK_PRESETS = [
+  "Guitar (6)",
+  "Guitar (7)",
+  "Bass (4)",
+  "Bass (5)",
+  "Bass (6)",
+  "Ukulele (4)"
+];
+server.tool(
+  "add_track",
+  "Add a track (part) to the tab, e.g. a bass line or a second guitar \u2014 up to 4 tracks including the main one. It starts empty, on track 0's measures and grid; write it with write_measures / set_cells using the new `track` index.",
+  {
+    name: z.string().min(1).describe("Shown in the app, e.g. 'Bass' or 'Guitar 2'."),
+    preset: z.enum(TRACK_PRESETS).optional(),
+    tuning: z.array(z.string()).min(1).optional().describe("Top (highest) to bottom; overrides preset.")
+  },
+  async (a) => {
+    const before = trackMetas(requireDoc()).length;
+    const tuning = a.tuning ?? PRESET_TUNINGS[a.preset ?? "Bass (4)"];
+    const doc = edit(0, () => {
+    });
+    const next = addTrack(doc, a.name, tuning);
+    if (trackMetas(next).length === before) {
+      throw new Error("a tab can hold at most 4 tracks");
+    }
+    state.doc = next;
+    return text(`Added track ${before} "${a.name}".
+
+${render(next)}`);
+  }
+);
+server.tool(
+  "remove_track",
+  "Remove a track (part) and its notes. Track 0 (the main track) cannot be removed.",
+  { track: z.number().int().min(1) },
+  async (a) => {
+    const doc = edit(0, () => {
+    });
+    onTrack(doc, a.track);
+    state.doc = removeTrack(doc, a.track);
+    return text(render(state.doc));
+  }
 );
 server.prompt(
   "import_tab_from_image",

package/package.json

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