@utilix-tech/mcp 0.70.0 → 0.71.0

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 Full release notes for all Utilix surfaces (browser tools, REST API, SDKs, MCP server) live at [utilix.tech/changelog](https://utilix.tech/changelog). This file tracks just this package.
 
+## 0.71.0
+- Add `read_midi_info` tool: parse a Standard MIDI File's header and every track chunk to report format, tick division, initial tempo, time signature, and per-track event/note-on counts, plus total duration in seconds accounting for tempo changes.
+
 ## 0.70.0
 - Add `generate_hotp`, `generate_totp` tools: generate an HOTP code (RFC 4226) for a counter value, or the current TOTP code (RFC 6238) plus seconds until rotation, from a base32-encoded shared secret, supporting SHA-1/SHA-256/SHA-512 and 6-8 digit codes.
 - Add `calculate_tax_equivalent_yield` tool: convert between a tax-free municipal bond yield and its taxable equivalent given a marginal federal (plus optional state) tax rate, in both directions.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 236 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 237 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
 
 No API key required. All tools run locally. Requires Node.js 18 or later.
 
@@ -371,12 +371,13 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `read_pdf_metadata` | Read title, author, dates, page count, and encryption flag from a PDF's trailer/Info dictionary: no PDF rendering library required |
 | `read_pdf_page_dimensions` | List each page's MediaBox width/height (points and inches), rotation, and orientation, walking the Root -> Pages -> Kids tree: no PDF rendering library required |
 
-### Audio (3 tools)
+### Audio (4 tools)
 | Tool | Description |
 |------|-------------|
 | `read_wav_info` | Read sample rate, channel count, bit depth, and duration from a WAV file's RIFF/fmt/data chunk headers: no audio library required |
 | `read_id3_tags` | Read title, artist, album, year, genre, comment, and track number from an MP3's ID3 tags: no audio library required |
 | `read_flac_info` | Read sample rate, channels, bit depth, total samples, and duration from a FLAC file's STREAMINFO block, plus Vorbis comment tags if present: no audio library required |
+| `read_midi_info` | Parse a Standard MIDI File's header and every track chunk to report format, tick division, initial tempo, time signature, and per-track event/note-on counts, plus total duration in seconds: no MIDI playback or synthesis |
 
 ### Video (1 tool)
 | Tool | Description |

package/dist/index.js

@@ -8768,6 +8768,139 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+function _readU16BEMcp(bytes, offset) {
+  return bytes[offset] << 8 | bytes[offset + 1];
+}
+function _readMidiVarLenMcp(bytes, pos) {
+  let value = 0;
+  let i = pos;
+  for (let n = 0; n < 4; n++) {
+    if (i >= bytes.length) return null;
+    const b = bytes[i];
+    value = value << 7 | b & 127;
+    i++;
+    if ((b & 128) === 0) return { value, next: i };
+  }
+  return null;
+}
+function _readMidiInfoMcp(bytes) {
+  if (bytes.length < 14) return { error: "File is too small to be a valid MIDI file" };
+  if (Buffer.from(bytes.subarray(0, 4)).toString("ascii") !== "MThd") {
+    return { error: 'Not a valid MIDI file (missing "MThd" header chunk)' };
+  }
+  const headerLength = (bytes[4] << 24 | bytes[5] << 16 | bytes[6] << 8 | bytes[7]) >>> 0;
+  if (headerLength < 6 || 8 + headerLength > bytes.length) return { error: "Truncated or invalid MThd header chunk" };
+  const format = _readU16BEMcp(bytes, 8);
+  if (format !== 0 && format !== 1 && format !== 2) return { error: `Unsupported MIDI format: ${format} (expected 0, 1, or 2)` };
+  const trackCount = _readU16BEMcp(bytes, 10);
+  if (trackCount < 1) return { error: "MIDI file declares zero tracks" };
+  const divisionRaw = _readU16BEMcp(bytes, 12);
+  const division = (divisionRaw & 32768) !== 0 ? { type: "smpte", framesPerSecond: -(divisionRaw >> 8 << 24 >> 24), ticksPerFrame: divisionRaw & 255 } : { type: "ppq", ticksPerQuarterNote: divisionRaw & 32767 };
+  const tracks = [];
+  const tempoChanges = [];
+  let timeSignature = null;
+  let maxEndTick = 0;
+  let offset = 8 + headerLength;
+  let tracksParsed = 0;
+  while (tracksParsed < trackCount && offset + 8 <= bytes.length) {
+    const chunkId = Buffer.from(bytes.subarray(offset, offset + 4)).toString("ascii");
+    const chunkLength = (bytes[offset + 4] << 24 | bytes[offset + 5] << 16 | bytes[offset + 6] << 8 | bytes[offset + 7]) >>> 0;
+    const dataStart = offset + 8;
+    const dataEnd = Math.min(dataStart + chunkLength, bytes.length);
+    if (chunkId !== "MTrk") {
+      offset = dataEnd;
+      continue;
+    }
+    let pos = dataStart;
+    let runningStatus = 0;
+    let absoluteTick = 0;
+    let eventCount = 0;
+    let noteOnCount = 0;
+    let name = null;
+    while (pos < dataEnd) {
+      const delta = _readMidiVarLenMcp(bytes, pos);
+      if (!delta) break;
+      pos = delta.next;
+      absoluteTick += delta.value;
+      if (pos >= dataEnd) break;
+      let statusByte = bytes[pos];
+      if (statusByte & 128) {
+        runningStatus = statusByte;
+        pos++;
+      }
+      statusByte = runningStatus;
+      eventCount++;
+      if (statusByte === 255) {
+        const metaType = bytes[pos];
+        pos++;
+        const len = _readMidiVarLenMcp(bytes, pos);
+        if (!len) break;
+        pos = len.next;
+        const data = bytes.subarray(pos, Math.min(pos + len.value, dataEnd));
+        pos += len.value;
+        if (metaType === 81 && data.length >= 3) {
+          tempoChanges.push({ tick: absoluteTick, usPerQuarter: data[0] << 16 | data[1] << 8 | data[2] });
+        } else if (metaType === 88 && data.length >= 2) {
+          if (!timeSignature) timeSignature = { numerator: data[0], denominator: 2 ** data[1] };
+        } else if (metaType === 3 && name === null) {
+          name = Buffer.from(data).toString("utf8").trim() || null;
+        } else if (metaType === 47) {
+          break;
+        }
+      } else if (statusByte === 240 || statusByte === 247) {
+        const len = _readMidiVarLenMcp(bytes, pos);
+        if (!len) break;
+        pos = len.next + len.value;
+      } else if (statusByte >= 128) {
+        const type = statusByte & 240;
+        if (type === 192 || type === 208) {
+          pos += 1;
+        } else {
+          if (type === 144 && (bytes[pos + 1] ?? 0) > 0) noteOnCount++;
+          pos += 2;
+        }
+      } else {
+        break;
+      }
+    }
+    tracks.push({ index: tracksParsed, name, eventCount, noteOnCount });
+    maxEndTick = Math.max(maxEndTick, absoluteTick);
+    offset = dataEnd;
+    tracksParsed++;
+  }
+  if (tracks.length === 0) return { error: "No MTrk track chunks found in this MIDI file" };
+  const DEFAULT_US_PER_QUARTER = 5e5;
+  const initialTempoBpm = Math.round(6e7 / (tempoChanges[0]?.usPerQuarter ?? DEFAULT_US_PER_QUARTER) * 100) / 100;
+  let durationSeconds = null;
+  if (division.type === "smpte") {
+    const ticksPerSecond = division.framesPerSecond * division.ticksPerFrame;
+    durationSeconds = ticksPerSecond > 0 ? Math.round(maxEndTick / ticksPerSecond * 1e3) / 1e3 : null;
+  } else {
+    const sorted = [...tempoChanges].sort((a, b) => a.tick - b.tick);
+    let seconds = 0;
+    let prevTick = 0;
+    let currentUsPerQuarter = DEFAULT_US_PER_QUARTER;
+    for (const change of sorted) {
+      seconds += (change.tick - prevTick) / division.ticksPerQuarterNote * (currentUsPerQuarter / 1e6);
+      prevTick = change.tick;
+      currentUsPerQuarter = change.usPerQuarter;
+    }
+    seconds += (maxEndTick - prevTick) / division.ticksPerQuarterNote * (currentUsPerQuarter / 1e6);
+    durationSeconds = Math.round(seconds * 1e3) / 1e3;
+  }
+  return { format, trackCount: tracks.length, division, initialTempoBpm, timeSignature, durationSeconds, tracks };
+}
+server.tool(
+  "read_midi_info",
+  "Parse a Standard MIDI File's header and every track chunk to report format (0/1/2), tick division, initial tempo, time signature, a per-track event/note-on count, and total duration in seconds, without any MIDI playback or synthesis.",
+  { midi_base64: z.string().describe("Base64-encoded MIDI (.mid/.midi) file bytes, optionally prefixed with a data: URL scheme") },
+  async ({ midi_base64 }) => {
+    const bytes = new Uint8Array(Buffer.from(midi_base64.replace(/^data:.*;base64,/, ""), "base64"));
+    const result = _readMidiInfoMcp(bytes);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
 function _calculateCashRoundingMcp(total, roundingUnit, mode = "nearest") {
   const round2 = (n) => Math.round(n * 100) / 100;
   if (typeof total !== "number" || !Number.isFinite(total)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilix-tech/mcp",
-  "version": "0.70.0",
+  "version": "0.71.0",
   "description": "MCP server exposing 198 Utilix developer tools to Claude, Cursor, VS Code Copilot, and any MCP-compatible AI assistant.",
   "author": "Utilix <hello@utilix.tech>",
   "license": "MIT",