@utilix-tech/mcp 0.69.0 → 0.71.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.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.
+
 ## 0.69.0
 - Add `parse_commit_trailers` tool: parse a commit message's trailer block (Co-authored-by, Signed-off-by, Fixes, Reviewed-by, etc.) per git's RFC 822-style trailer convention, returning each trailer's key and value plus the body with the trailer block removed.
 - Add `extract_markdown_footnotes` tool: extract every Markdown-Extra-style footnote reference and definition from a document, flagging references with no matching definition and definitions that are never referenced.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 233 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.
 
@@ -179,6 +179,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `calculate_time_value` | Convert between present and future value (time value of money) in either direction |
 | `calculate_percentage_change` | Compute the percentage change between two numbers, with absolute change, direction, and multiplier |
 | `convert_apr_apy` | Convert between a nominal APR and effective APY for a given compounding frequency, in both directions |
+| `calculate_tax_equivalent_yield` | Convert between a tax-free municipal bond yield and its taxable equivalent given a marginal federal (plus optional state) tax rate, in both directions |
 | `calculate_margin_markup` | Given any two of cost, price, margin percent, and markup percent, solve for the other two plus gross profit |
 | `calculate_discount` | Solve a sale price, amount saved, or discount percent from any one of them, or stack successive discounts in order |
 | `convert_subtitles` | Convert subtitles between SubRip (.srt) and WebVTT (.vtt), with an optional time shift to resync every cue |
@@ -211,6 +212,8 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `decode_jwt` | Decode a JWT: header, payload, and expiry |
 | `parse_jwks` | Parse a JWKS (or a single bare JWK): type, use, algorithm, key ID, and size per key |
 | `compute_jwk_thumbprint` | Compute the RFC 7638 canonical thumbprint of a single JWK (SHA-256/384/512) |
+| `generate_hotp` | Generate an HOTP code (RFC 4226) for a counter value from a base32-encoded shared secret |
+| `generate_totp` | Generate the current TOTP code (RFC 6238) from a base32-encoded shared secret, plus seconds until rotation |
 | `build_curl` | Build a cURL command from method, URL, headers, and body |
 | `curl_to_code` | Convert a cURL command to fetch, axios, Python, Go, PHP, or Ruby |
 | `cors_headers` | Generate CORS response headers for a configuration |
@@ -368,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

@@ -4,7 +4,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { createHash, randomBytes } from "crypto";
+import { createHash, createHmac, randomBytes } from "crypto";
 import * as yaml from "js-yaml";
 import {
   parseJson,
@@ -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)) {
@@ -11120,5 +11253,149 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+function _calculateTaxEquivalentYieldMcp(inputYieldPercent, federalTaxRatePercent, stateTaxRatePercent, direction) {
+  if (typeof inputYieldPercent !== "number" || !Number.isFinite(inputYieldPercent) || inputYieldPercent < 0) {
+    return { error: "Yield must be zero or a positive number" };
+  }
+  if (typeof federalTaxRatePercent !== "number" || !Number.isFinite(federalTaxRatePercent) || federalTaxRatePercent < 0 || federalTaxRatePercent >= 100) {
+    return { error: "Federal tax rate must be a percentage between 0 and 100 (exclusive of 100)" };
+  }
+  const stateRate = stateTaxRatePercent ?? 0;
+  if (typeof stateRate !== "number" || !Number.isFinite(stateRate) || stateRate < 0 || stateRate >= 100) {
+    return { error: "State tax rate must be a percentage between 0 and 100 (exclusive of 100)" };
+  }
+  if (direction !== "tax-free-to-taxable" && direction !== "taxable-to-tax-free") {
+    return { error: 'Direction must be "tax-free-to-taxable" or "taxable-to-tax-free"' };
+  }
+  const combinedTaxRatePercent = federalTaxRatePercent + stateRate;
+  if (combinedTaxRatePercent >= 100) {
+    return { error: "Combined federal and state tax rate must be less than 100%" };
+  }
+  const round6 = (n) => Math.round(n * 1e6) / 1e6;
+  const combinedRateDecimal = combinedTaxRatePercent / 100;
+  let taxFreeYield;
+  let taxableYield;
+  if (direction === "tax-free-to-taxable") {
+    taxFreeYield = inputYieldPercent;
+    taxableYield = taxFreeYield / (1 - combinedRateDecimal);
+  } else {
+    taxableYield = inputYieldPercent;
+    taxFreeYield = taxableYield * (1 - combinedRateDecimal);
+  }
+  return {
+    direction,
+    inputYield: round6(inputYieldPercent),
+    federalTaxRatePercent: round6(federalTaxRatePercent),
+    stateTaxRatePercent: round6(stateRate),
+    combinedTaxRatePercent: round6(combinedTaxRatePercent),
+    taxFreeYield: round6(taxFreeYield),
+    taxableYield: round6(taxableYield),
+    yieldDifference: round6(taxableYield - taxFreeYield)
+  };
+}
+server.tool(
+  "calculate_tax_equivalent_yield",
+  'Convert between a tax-free municipal bond yield and the equivalent taxable-bond yield given a marginal federal tax rate (plus an optional state rate, summed into a combined rate). With direction "tax-free-to-taxable", taxableYield = taxFreeYield / (1 - combinedRate); with "taxable-to-tax-free", taxFreeYield = taxableYield * (1 - combinedRate). Pure formula, no live bond pricing.',
+  {
+    inputYield: z.number().min(0).describe('The known yield as a percent: the tax-free yield when direction is "tax-free-to-taxable", or the taxable yield when direction is "taxable-to-tax-free"'),
+    federalTaxRatePercent: z.number().min(0).max(99.999).describe("Marginal federal tax rate as a percent"),
+    stateTaxRatePercent: z.number().min(0).max(99.999).optional().describe("Optional marginal state tax rate as a percent, summed with the federal rate"),
+    direction: z.enum(["tax-free-to-taxable", "taxable-to-tax-free"]).describe("Which yield the input represents and which to compute")
+  },
+  async ({ inputYield, federalTaxRatePercent, stateTaxRatePercent, direction }) => {
+    const result = _calculateTaxEquivalentYieldMcp(inputYield, federalTaxRatePercent, stateTaxRatePercent ?? 0, direction);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+var _OTP_ALG_TO_NODE_HASH_MCP = { SHA1: "sha1", SHA256: "sha256", SHA512: "sha512" };
+function _decodeBase32SecretMcp(secret) {
+  const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+  const cleaned = (secret ?? "").toUpperCase().replace(/[\s=]/g, "");
+  if (!cleaned) return { error: "Secret must not be empty" };
+  const bytes = [];
+  let buffer = 0;
+  let bitsLeft = 0;
+  for (const char of cleaned) {
+    const val = alphabet.indexOf(char);
+    if (val === -1) return { error: `Invalid base32 character '${char}' in secret` };
+    buffer = buffer << 5 | val;
+    bitsLeft += 5;
+    if (bitsLeft >= 8) {
+      bitsLeft -= 8;
+      bytes.push(buffer >> bitsLeft & 255);
+    }
+  }
+  return Buffer.from(bytes);
+}
+function _hotpFromCounterMcp(keyBytes, counter, digits, algorithm) {
+  const counterBuffer = Buffer.alloc(8);
+  counterBuffer.writeUInt32BE(Math.floor(counter / 4294967296), 0);
+  counterBuffer.writeUInt32BE(counter % 4294967296, 4);
+  const hmac = createHmac(_OTP_ALG_TO_NODE_HASH_MCP[algorithm], keyBytes).update(counterBuffer).digest();
+  const offset = hmac[hmac.length - 1] & 15;
+  const binCode = (hmac[offset] & 127) << 24 | (hmac[offset + 1] & 255) << 16 | (hmac[offset + 2] & 255) << 8 | hmac[offset + 3] & 255;
+  return (binCode % 10 ** digits).toString().padStart(digits, "0");
+}
+function _generateHotpMcp(secret, counter, digits, algorithm) {
+  if (!Number.isInteger(counter) || counter < 0) {
+    return { error: "Counter must be a non-negative whole number" };
+  }
+  if (!Number.isInteger(digits) || digits < 6 || digits > 8) {
+    return { error: "Digits must be an integer between 6 and 8" };
+  }
+  if (!(algorithm in _OTP_ALG_TO_NODE_HASH_MCP)) {
+    return { error: "Algorithm must be one of SHA1, SHA256, SHA512" };
+  }
+  const keyBytes = _decodeBase32SecretMcp(secret);
+  if ("error" in keyBytes) return keyBytes;
+  return { code: _hotpFromCounterMcp(keyBytes, counter, digits, algorithm), counter, digits, algorithm };
+}
+function _generateTotpMcp(secret, digits, algorithm, periodSeconds, timestamp) {
+  const period = periodSeconds ?? 30;
+  const ts = timestamp ?? Math.floor(Date.now() / 1e3);
+  if (!Number.isFinite(period) || period <= 0) {
+    return { error: "Period must be a positive number of seconds" };
+  }
+  if (!Number.isFinite(ts) || ts < 0) {
+    return { error: "Timestamp must be a non-negative number of seconds" };
+  }
+  const counter = Math.floor(ts / period);
+  const hotp = _generateHotpMcp(secret, counter, digits, algorithm);
+  if ("error" in hotp) return hotp;
+  const secondsRemaining = period - ts % period;
+  return { ...hotp, periodSeconds: period, secondsRemaining };
+}
+server.tool(
+  "generate_hotp",
+  "Generate an HOTP code (RFC 4226) for a given counter value from a base32-encoded shared secret. Supports 6-8 digit codes and SHA-1/SHA-256/SHA-512 (SHA-1 is the default per the RFC). The secret is never stored, only used for this one HMAC computation.",
+  {
+    secret: z.string().min(1).describe("The base32-encoded shared secret (RFC 4648, case-insensitive, padding optional)"),
+    counter: z.number().int().min(0).describe("The HOTP counter value"),
+    digits: z.number().int().min(6).max(8).optional().describe("Code length, default 6"),
+    algorithm: z.enum(["SHA1", "SHA256", "SHA512"]).optional().describe("HMAC algorithm, default SHA1")
+  },
+  async ({ secret, counter, digits, algorithm }) => {
+    const result = _generateHotpMcp(secret, counter, digits ?? 6, algorithm ?? "SHA1");
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+server.tool(
+  "generate_totp",
+  "Generate the current TOTP code (RFC 6238) from a base32-encoded shared secret, plus how many seconds remain before it rotates. Defaults (30s period, 6 digits, SHA-1) match what Google Authenticator and most other authenticator apps use. Pass an explicit timestamp for deterministic/testable output.",
+  {
+    secret: z.string().min(1).describe("The base32-encoded shared secret (RFC 4648, case-insensitive, padding optional)"),
+    digits: z.number().int().min(6).max(8).optional().describe("Code length, default 6"),
+    algorithm: z.enum(["SHA1", "SHA256", "SHA512"]).optional().describe("HMAC algorithm, default SHA1"),
+    periodSeconds: z.number().int().min(1).optional().describe("Time-step window in seconds, default 30"),
+    timestamp: z.number().int().min(0).optional().describe("Unix timestamp in seconds to compute the code for; defaults to the current time")
+  },
+  async ({ secret, digits, algorithm, periodSeconds, timestamp }) => {
+    const result = _generateTotpMcp(secret, digits ?? 6, algorithm ?? "SHA1", periodSeconds ?? 30, timestamp);
+    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.69.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",