@hidechae/eztab-mcp 0.3.0 → 0.4.1

package/README.md

@@ -92,7 +92,7 @@ Run standalone for testing: `task mcp` (or `npx tsx mcp/server.ts`).
 | `set_title` | Set the document title |
 | `set_artist` | Set the document artist |
 | `write_measures` | 小節単位の一括入力。1拍を1文字列で書き(`"6:5 6:~7"` など)、列番号への割り付けはサーバ側で行う。譜面・画像からの書き起こし向け |
-| `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); optional `pm` palm-mutes it |
+| `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); optional `pm` palm-mutes it; optional `harm` (`natural` / `artificial` / `pinch` / `none`) + `harmAt` writes a harmonic |
 | `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") |

package/dist/server.js

@@ -7,8 +7,9 @@ import { z } from "zod";
 
 // ../src/types/tab.ts
 var TAB_FILE_VERSION = 1;
-var SUPPORTED_FORMAT_REVISION = 2;
+var SUPPORTED_FORMAT_REVISION = 3;
 var MULTI_TRACK_FORMAT_REVISION = 2;
+var HARMONICS_FORMAT_REVISION = 3;
 var MAX_TRACKS = 4;
 var DEFAULT_MAIN_TRACK_NAME = "Guitar";
 var DEFAULT_TEMPO = 120;
@@ -41,9 +42,92 @@ function shiftKeysForDelete(keys, index) {
   }
   return next;
 }
+var HARMONIC_KINDS = ["natural", "artificial", "pinch"];
+var MAX_HARM_AT = 36;
+function checkHarmonic(fret, harm, harmAt) {
+  if (harm == null) {
+    if (harmAt != null) {
+      return { ok: false, field: "harmAt", reason: "a harmonic position needs a harmonic kind" };
+    }
+    return { ok: true, value: { fret } };
+  }
+  if (!HARMONIC_KINDS.includes(harm)) {
+    return { ok: false, field: "harm", reason: `unknown harmonic kind "${String(harm)}"` };
+  }
+  const kind = harm;
+  if (harmAt == null) {
+    if (kind === "natural" && !(fret > 0)) {
+      return { ok: false, field: "harm", reason: "a natural harmonic needs a fret above 0" };
+    }
+    return { ok: true, value: { fret, harm: kind } };
+  }
+  if (typeof harmAt !== "number" || !Number.isFinite(harmAt) || harmAt <= 0 || harmAt > MAX_HARM_AT) {
+    return {
+      ok: false,
+      field: "harmAt",
+      reason: `harmonic position must be a number above 0 and up to ${MAX_HARM_AT}`
+    };
+  }
+  if (Math.abs(harmAt * 10 - Math.round(harmAt * 10)) > 1e-6) {
+    return { ok: false, field: "harmAt", reason: "harmonic position has at most one decimal" };
+  }
+  const at = Math.round(harmAt * 10) / 10;
+  if (kind === "natural") {
+    const touch = Math.round(at);
+    if (touch > MAX_FRET) {
+      return { ok: false, field: "harmAt", reason: `natural harmonic above fret ${MAX_FRET}` };
+    }
+    return {
+      ok: true,
+      value: Number.isInteger(at) ? { fret: touch, harm: kind } : { fret: touch, harm: kind, harmAt: at }
+    };
+  }
+  if (at <= fret) {
+    return {
+      ok: false,
+      field: "harmAt",
+      reason: `the harmonic position (${at}) must be above the fretted note (${fret})`
+    };
+  }
+  return { ok: true, value: { fret, harm: kind, harmAt: at } };
+}
+function normalizeCell(c) {
+  if (typeof c !== "object" || c === null || !("harm" in c || "harmAt" in c)) return c;
+  const { harm, harmAt, ...rest } = c;
+  let r = checkHarmonic(c.fret, harm, harmAt);
+  if (!r.ok && r.field === "harmAt" && harm != null) r = checkHarmonic(c.fret, harm, void 0);
+  const h = r.ok ? r.value : { fret: c.fret };
+  return { ...rest, ...h };
+}
+function measuresHaveHarmonics(measures) {
+  return measures.some((m) => m.cells.some((row) => row.some((c) => cellHarm(c) != null)));
+}
+function cellFret(c) {
+  if (typeof c === "number") return c;
+  if (typeof c === "object" && c !== null) return c.fret;
+  return null;
+}
 function cellPalmMute(c) {
   return typeof c === "object" && c !== null && !!c.pm;
 }
+function cellHarm(c) {
+  return typeof c === "object" && c !== null ? c.harm : void 0;
+}
+function cellHarmAt(c) {
+  return typeof c === "object" && c !== null && c.harm ? c.harmAt : void 0;
+}
+function makeNoteCell(fret, bend, tie, pm, harmonic) {
+  const harm = harmonic?.harm;
+  if (!(bend > 0 || tie || pm || harm)) return fret;
+  return {
+    fret,
+    ...bend > 0 ? { bend } : {},
+    ...tie ? { tie: true } : {},
+    ...pm ? { pm: true } : {},
+    ...harm ? { harm } : {},
+    ...harm && harmonic?.harmAt != null ? { harmAt: harmonic.harmAt } : {}
+  };
+}
 var CHORD_REST = "rest";
 var CHORD_REST_LABEL = "N.C.";
 function chordDisplay(label) {
@@ -115,7 +199,7 @@ function normalizeDocument(data) {
     });
     const cols = subdivisions.reduce((a, b) => a + b, 0);
     const cells = (m.cells ?? []).map(
-      (row) => Array.from({ length: cols }, (_, c) => row?.[c] ?? null)
+      (row) => Array.from({ length: cols }, (_, c) => normalizeCell(row?.[c] ?? null))
     );
     const rawChords = Array.isArray(m.chords) ? m.chords : typeof m.chord === "string" && m.chord ? [m.chord] : [];
     const chords = normalizeChords(rawChords, subdivisions);
@@ -179,7 +263,7 @@ function fitTrackMeasure(raw, main, stringCount) {
   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)
+    (_, s) => Array.from({ length: cols }, (_2, c) => normalizeCell(rows[s]?.[c] ?? null))
   );
   return { subdivisions, cells };
 }
@@ -307,7 +391,7 @@ function newUid() {
   return newTabId();
 }
 function storedMeasure(m) {
-  const { uid: _uid, ...rest } = m;
+  const { uid: _uid, beatWidthOverride: _w, ...rest } = m;
   return rest;
 }
 function openWorkspace(doc) {
@@ -391,12 +475,12 @@ function closeWorkspace(doc) {
   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;
-  }
+  if (extras.length > 0) out.tracks = extras;
+  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 (revision > 1) out.formatRevision = revision;
   return out;
 }
 function reconcileTracks(prev, next) {
@@ -554,96 +638,6 @@ var cloud = {
   }
 };
 
-// eztab.ts
-function normalize(data) {
-  return normalizeDocument(data);
-}
-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, 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}`);
-  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 = [];
-  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(", ")}`);
-  main.measures.forEach((m, mi) => {
-    if (mi < from || mi > to) return;
-    const key = activeKeyAt(doc.keys, mi);
-    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}, key ${key.tonic} ${key.mode}) ---`
-    );
-    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];
 var BENDS = { b: 0.5, B: 1, "^": 1.5 };
@@ -659,18 +653,44 @@ function parseTime(text2) {
 function parseValue(raw, where) {
   if (raw === "x") return "mute";
   if (raw === "r") return "rest";
-  const m = /^(~?)(\d+)([bB^p]*)$/.exec(raw);
+  const m = /^(~?)(?:<(\d+(?:\.\d+)?)>|(\d+)(?:<(\d+(?:\.\d+)?)>)?)([bB^pah]*)$/.exec(raw);
   if (!m) throw new Error(`${where}: bad value "${raw}"`);
-  const fret = Number(m[2]);
+  const natural = m[2] != null;
+  const at = natural ? Number(m[2]) : m[4] != null ? Number(m[4]) : void 0;
+  const fret = natural ? Math.round(Number(m[2])) : Number(m[3]);
   if (fret > MAX_FRET) throw new Error(`${where}: fret ${fret} is above ${MAX_FRET}`);
-  const mods = m[3];
+  const mods = m[5];
   const bendMarks = [...mods].filter((c) => c in BENDS);
   if (bendMarks.length > 1) throw new Error(`${where}: more than one choke mark in "${raw}"`);
-  const note = { fret };
-  if (bendMarks.length) note.bend = BENDS[bendMarks[0]];
-  if (m[1]) note.tie = true;
-  if (mods.includes("p")) note.pm = true;
-  return Object.keys(note).length === 1 ? fret : note;
+  const a = mods.includes("a");
+  const h = mods.includes("h");
+  if (a && h) throw new Error(`${where}: "a" and "h" cannot be combined in "${raw}"`);
+  if (natural && (a || h)) {
+    throw new Error(`${where}: a natural harmonic <pos> takes no "a"/"h" in "${raw}"`);
+  }
+  if (a && at != null) {
+    throw new Error(`${where}: "${raw}" \u2014 a position <pos> already means artificial; drop "a"`);
+  }
+  const harm = natural ? "natural" : h ? "pinch" : a || at != null ? "artificial" : void 0;
+  const checked = checkHarmonic(fret, harm, at);
+  if (!checked.ok) throw new Error(`${where}: ${checked.reason} in "${raw}"`);
+  const bend = bendMarks.length ? BENDS[bendMarks[0]] : 0;
+  return makeNoteCell(checked.value.fret, bend, !!m[1], mods.includes("p"), checked.value);
+}
+function noteText(cell) {
+  if (typeof cell === "number") return String(cell);
+  const bend = cell.bend ?? 0;
+  const bendMark = bend === 0.5 ? "b" : bend === 1.5 ? "^" : bend === 1 ? "B" : "";
+  let body;
+  let harmMark = "";
+  if (cell.harm === "natural") {
+    body = `<${cell.harmAt ?? cell.fret}>`;
+  } else {
+    body = cell.harm && cell.harmAt != null ? `${cell.fret}<${cell.harmAt}>` : String(cell.fret);
+    if (cell.harm === "pinch") harmMark = "h";
+    else if (cell.harm === "artificial" && cell.harmAt == null) harmMark = "a";
+  }
+  return `${cell.tie ? "~" : ""}${body}${bendMark}${harmMark}${cell.pm ? "p" : ""}`;
 }
 function parseBeat(text2, stringCount, where) {
   const slots = text2.trim().split(/\s+/);
@@ -704,6 +724,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) {
@@ -711,7 +743,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,
@@ -729,6 +763,105 @@ function buildMeasure(spec, stringCount, fallback, where = "measure") {
   }
   return measure;
 }
+function setCellNote(prev, e, where) {
+  if (e.harm === "none" && e.harmAt != null) {
+    throw new Error(`${where}: harmAt cannot be set with harm "none"`);
+  }
+  const sameNote = cellFret(prev) === e.fret;
+  const harm = e.harm === "none" ? void 0 : e.harm ?? (sameNote ? cellHarm(prev) : void 0);
+  const keptAt = e.harmAt == null && harm != null && sameNote ? cellHarmAt(prev) : void 0;
+  let checked = checkHarmonic(e.fret, harm, e.harmAt ?? keptAt);
+  if (!checked.ok && keptAt != null) checked = checkHarmonic(e.fret, harm, void 0);
+  if (!checked.ok) throw new Error(`${where}: ${checked.reason}`);
+  return makeNoteCell(checked.value.fret, e.bend ?? 0, !!e.tie, !!e.pm, checked.value);
+}
+
+// eztab.ts
+function normalize(data) {
+  return normalizeDocument(data);
+}
+function cellText(cell) {
+  if (cell === null) return "";
+  if (cell === "rest") return "R";
+  if (cell === "mute") return "x";
+  return noteText(cell);
+}
+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}`);
+  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 = [];
+  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(", ")}`);
+  main.measures.forEach((m, mi) => {
+    if (mi < from || mi > to) return;
+    const key = activeKeyAt(doc.keys, mi);
+    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}, key ${key.tonic} ${key.mode}) ---`
+    );
+    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 texts = m.cells.map((row) => row.map(cellText));
+  const width = Math.max(2, ...texts.flat().map((t) => t.length));
+  const ruler = Array.from(
+    { length: columnCount(m) },
+    (_, c) => String(c).padStart(width, " ")
+  ).join(" ");
+  lines.push(`col:    ${ruler}`);
+  texts.forEach((row, s) => {
+    const label = `${s + 1} ${tuning[s] ?? "?"}`.padEnd(6, " ");
+    lines.push(`${label}| ${row.map((t) => t.padStart(width, "-")).join(" ")}`);
+  });
+  const pm = Array.from(
+    { length: columnCount(m) },
+    (_, c) => (m.cells.some((row) => cellPalmMute(row[c] ?? null)) ? "PM" : "").padStart(width, " ")
+  );
+  if (pm.some((x) => x.trim() !== "")) lines.push(`pm:     ${pm.join(" ")}`);
+}
 
 // prompts.ts
 var IMPORT_TAB_FROM_IMAGE = `Transcribe the TAB in the attached image(s) into an EZTab document with the eztab tools.
@@ -742,7 +875,7 @@ var IMPORT_TAB_FROM_IMAGE = `Transcribe the TAB in the attached image(s) into an
 
 ## 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 "-".
@@ -753,7 +886,12 @@ Read each bar's rhythm first (beams, flags, dots, tuplet brackets, rests), then
 - Choke / bend (C, Cho., "full", "1/2", up arrow): S:FB for full, S:Fb for \xBD, S:F^ for 1\xBD. A release / down choke: write the returning note tied.
 - Bridge mute (M, P.M. bracket in Japanese band scores = \u30DF\u30E5\u30FC\u30C8): add p to every note under the bracket.
 - Dead notes / brushing (x): S:x.
-- Natural/artificial harmonics (o, Harm., <7>): plain fret. Vibrato, slide-in from nowhere (/6), slide-out, arpeggio wavy line, grace notes: write the main note only.
+- Harmonics:
+  - Natural harmonic (fret in angle brackets <12>, <7>, "Harm.", "N.H.", a diamond notehead): S:<12>. Between frets (<2.4>, <3.2>, <5.8>): S:<2.4> as printed.
+  - Artificial harmonic (7<19>, "A.H.", "T.H." with the fretted note and the touch point): S:7<19>. Only the fretted note printed with "A.H." / "T.H.": S:7a.
+  - Pinch harmonic ("P.H." bracket, like P.M.): add h to every note under it, S:7h; with a printed position, S:7<19>h.
+  - "AH" / "A.H." is used for both artificial and pinch harmonics. Decide from context: a picked note under a P.H.-like bracket or marked over a distorted riff is pinch (h); a tapped / touched octave (typically +12) on a clean part is artificial. If unsure, choose one and list those bars in the report.
+- Vibrato, slide-in from nowhere (/6), slide-out, arpeggio wavy line, grace notes: write the main note only.
 - Chord diagrams / chord-form boxes drawn inside the TAB staff (no fret numbers): write the chord name on the chord row. Write the voicing as notes only if the user asks or the diagram is unambiguous.
 - Repeats, D.S., Coda, 1st/2nd endings: transcribe the bars as printed and tell the user; do not expand them unless asked.
 
@@ -769,7 +907,7 @@ var state = {
   source: null
 };
 var server = new McpServer(
-  { name: "eztab", version: "0.3.0" },
+  { name: "eztab", version: "0.4.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."
   }
@@ -969,7 +1107,7 @@ server.tool(
 );
 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. Optional `pm` (boolean) palm-mutes (bridge-mutes) a fret-number note. measure/string/column are all 0-based (measure 0 = the first measure, string 0 = the top line).",
+  "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. Optional `pm` (boolean) palm-mutes (bridge-mutes) a fret-number note. Optional `harm` makes it a harmonic: 'natural' (touch the open string at `harmAt`, or at the fret when omitted \u2014 `harmAt` may be between frets, e.g. 2.4, and then the fret is its rounded value), 'artificial' / 'pinch' (fret the note, harmonic at `harmAt` above it; pinch without `harmAt` = wherever it is picked), or 'none' to remove it. When `harm` is omitted and the cell already holds a harmonic at the same fret, the harmonic is kept. measure/string/column are all 0-based (measure 0 = the first measure, string 0 = the top line).",
   {
     edits: z.array(
       z.object({
@@ -979,7 +1117,9 @@ server.tool(
         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(),
-        pm: z.boolean().optional()
+        pm: z.boolean().optional(),
+        harm: z.enum(["natural", "artificial", "pinch", "none"]).optional(),
+        harmAt: z.number().optional()
       })
     ),
     track: trackParam
@@ -997,22 +1137,25 @@ server.tool(
           `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 || e.pm)) {
-        value = {
-          fret: e.value,
-          ...e.bend != null ? { bend: e.bend } : {},
-          ...e.tie ? { tie: true } : {},
-          ...e.pm ? { pm: true } : {}
-        };
+      const where = `measure ${e.measure} string ${e.string} column ${e.column}`;
+      if (typeof e.value !== "number") {
+        if (e.harm != null || e.harmAt != null) {
+          throw new Error(`${where}: harm / harmAt need a fret-number value`);
+        }
+        m.cells[e.string][e.column] = e.value === "clear" ? null : e.value;
+        continue;
       }
-      m.cells[e.string][e.column] = value;
+      m.cells[e.string][e.column] = setCellNote(
+        m.cells[e.string][e.column],
+        { fret: e.value, bend: e.bend, tie: e.tie, pm: e.pm, harm: e.harm, harmAt: e.harmAt },
+        where
+      );
     }
   }, a.track)
 );
 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: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({

package/package.json

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