@utilix-tech/mcp 0.70.0 → 0.72.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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.72.0
+- Add `validate_vin` tool: validate a 17-character VIN via the ISO 3779 / NHTSA weighted mod-11 check digit and split it into its WMI, VDS, and VIS sections.
+- Add `validate_isin` tool: validate a 12-character ISIN via its Luhn-style mod-10 check digit and break it into its country code and security identifier.
+
+## 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 239 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.
 
@@ -162,7 +162,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `convert_timezone` | Convert a date/time between timezones |
 | `convert_iso8601_duration` | Parse an ISO 8601 duration into components and total seconds, or format seconds into a duration string |
 
-### Units (39 tools)
+### Units (42 tools)
 | Tool | Description |
 |------|-------------|
 | `convert_bytes` | Convert between B, KB, MB, GB, TB, KiB, MiB, GiB, TiB |
@@ -205,6 +205,8 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `calculate_extra_payment_payoff` | Compute how much faster a fixed-rate loan pays off, and how much interest is saved, when a fixed extra amount is added to every monthly payment |
 | `plan_debt_payoff` | Simulate paying off a list of debts under both the snowball (smallest balance first) and avalanche (highest rate first) strategies given a fixed extra monthly payment, and compare months to payoff and total interest |
 | `calculate_loan_refinance` | Compare a current loan's remaining payments against a new refinanced loan on the same outstanding balance, and compute the monthly savings and the break-even month where cumulative savings recoup the closing costs |
+| `validate_vin` | Validate a 17-character VIN via the ISO 3779 / NHTSA weighted mod-11 check digit and split it into its WMI, VDS, and VIS sections |
+| `validate_isin` | Validate a 12-character ISIN via its Luhn-style mod-10 check digit and break it into its country code and security identifier |
 
 ### API / Network (48 tools)
 | Tool | Description |
@@ -371,12 +373,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)) {
@@ -11264,5 +11397,113 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+var _VIN_TRANSLITERATION_MCP = {
+  A: 1,
+  B: 2,
+  C: 3,
+  D: 4,
+  E: 5,
+  F: 6,
+  G: 7,
+  H: 8,
+  J: 1,
+  K: 2,
+  L: 3,
+  M: 4,
+  N: 5,
+  P: 7,
+  R: 9,
+  S: 2,
+  T: 3,
+  U: 4,
+  V: 5,
+  W: 6,
+  X: 7,
+  Y: 8,
+  Z: 9
+};
+var _VIN_WEIGHTS_MCP = [8, 7, 6, 5, 4, 3, 2, 10, 0, 9, 8, 7, 6, 5, 4, 3, 2];
+function _validateVin(input) {
+  if (!input || !input.trim()) return { error: "Input is empty" };
+  const cleaned = input.replace(/\s/g, "").toUpperCase();
+  if (cleaned.length !== 17) return { error: `VIN length (${cleaned.length}) must be exactly 17 characters` };
+  if (!/^[A-HJ-NPR-Z0-9]{17}$/.test(cleaned)) {
+    return { error: "VIN must contain only letters and digits, excluding I, O, and Q" };
+  }
+  let sum = 0;
+  for (let i = 0; i < 17; i++) {
+    const ch = cleaned[i];
+    const value = /[0-9]/.test(ch) ? Number(ch) : _VIN_TRANSLITERATION_MCP[ch];
+    sum += value * _VIN_WEIGHTS_MCP[i];
+  }
+  const remainder = sum % 11;
+  const expectedCheckDigit = remainder === 10 ? "X" : String(remainder);
+  const checkDigit = cleaned[8];
+  return {
+    valid: checkDigit === expectedCheckDigit,
+    vin: cleaned,
+    checkDigit,
+    expectedCheckDigit,
+    wmi: cleaned.slice(0, 3),
+    vds: cleaned.slice(3, 9),
+    vis: cleaned.slice(9, 17)
+  };
+}
+server.tool(
+  "validate_vin",
+  "Validate a 17-character VIN via the ISO 3779 / NHTSA weighted mod-11 check digit at position 9, and split it into its World Manufacturer Identifier (WMI), Vehicle Descriptor Section (VDS), and Vehicle Identifier Section (VIS). Does not decode make, model, or model year.",
+  { vin: z.string().describe("The 17-character VIN, with or without spaces") },
+  async ({ vin }) => {
+    const result = _validateVin(vin);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+function _isinLuhnCheckDigitMcp(payloadDigits) {
+  let sum = 0;
+  let shouldDouble = true;
+  for (let i = payloadDigits.length - 1; i >= 0; i--) {
+    let d = parseInt(payloadDigits[i], 10);
+    if (shouldDouble) {
+      d *= 2;
+      if (d > 9) d -= 9;
+    }
+    sum += d;
+    shouldDouble = !shouldDouble;
+  }
+  return (10 - sum % 10) % 10;
+}
+function _validateIsin(input) {
+  if (!input || !input.trim()) return { error: "Input is empty" };
+  const cleaned = input.replace(/\s/g, "").toUpperCase();
+  if (cleaned.length !== 12) return { error: `ISIN length (${cleaned.length}) must be exactly 12 characters` };
+  if (!/^[A-Z]{2}[A-Z0-9]{9}\d$/.test(cleaned)) {
+    return { error: "ISIN must be a 2-letter country code, 9 alphanumeric characters, then 1 numeric check digit" };
+  }
+  const countryCode = cleaned.slice(0, 2);
+  const securityIdentifier = cleaned.slice(2, 11);
+  const checkDigit = Number(cleaned[11]);
+  const payload = cleaned.slice(0, 11).split("").map((ch) => /[A-Z]/.test(ch) ? String(ch.charCodeAt(0) - 55) : ch).join("");
+  const expectedCheckDigit = _isinLuhnCheckDigitMcp(payload);
+  return {
+    valid: checkDigit === expectedCheckDigit,
+    isin: cleaned,
+    countryCode,
+    securityIdentifier,
+    checkDigit,
+    expectedCheckDigit,
+    formatted: `${countryCode} ${securityIdentifier} ${checkDigit}`
+  };
+}
+server.tool(
+  "validate_isin",
+  "Validate a 12-character ISIN (ISO 6166) via its Luhn-style mod-10 check digit. The 2-letter country code and 9-character alphanumeric security identifier are transliterated (A=10 ... Z=35) into a numeric string before the Luhn algorithm is applied, the same way credit card numbers are checksummed.",
+  { isin: z.string().describe("The 12-character ISIN, with or without spaces") },
+  async ({ isin }) => {
+    const result = _validateIsin(isin);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
 var transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@utilix-tech/mcp",
-  "version": "0.70.0",
+  "version": "0.72.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",