@utilix-tech/mcp 0.94.0 → 0.95.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 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.95.0
+- Add `read_png_chunks` tool: walk a PNG's chunk stream directly from its bytes to report every chunk's type, offset, size, and CRC-32 validity, plus the decoded IHDR header and common ancillary chunks (tEXt, pHYs, gAMA, tIME, acTL).
+- Add `estimate_audio_file_size` tool: estimate an audio file's size before recording or exporting it, uncompressed PCM size from sample rate/bit depth/channels or compressed size from a target bitrate.
+
 ## 0.94.0
 - Add `build_alt_svc_header`/`parse_alt_svc_header` tools: build an `Alt-Svc` response header (RFC 7838) from one or more alternative services with a plain-English note per protocol-id, flagging outdated HTTP/3 draft protocol-ids, or parse an existing header back into its alternatives, including the special `clear` value.
 

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 281 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 283 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.
 
@@ -400,13 +400,14 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `calculate_retry_backoff_schedule` | Compute the full sequence of delays an exponential-backoff retry policy would actually produce, given a base delay, multiplier, and max retry count, optionally capped at a max delay and with full/equal jitter ranges |
 | `extract_prompt_template_variables` | Extract every {{variable}}-style placeholder from a prompt template, report occurrence counts, flag duplicates, and optionally cross-check against a list of provided variable names |
 
-### Image (4 tools)
+### Image (5 tools)
 | Tool | Description |
 |------|-------------|
 | `read_image_info` | Read format, dimensions, bit depth, and alpha channel from image bytes: no decoding required. Supports PNG, JPEG, GIF, WebP, BMP |
 | `read_exif_data` | Read camera make/model, orientation, timestamps, exposure settings, and GPS coordinates from a JPEG's EXIF data |
 | `read_ico_info` | Read how many images a .ico file embeds and each one's width, height, color depth, and size from its ICONDIR header |
 | `inspect_gif_frames` | Walk a GIF87a/89a file's block structure to report frame count, total animation duration, and loop count, without decoding any LZW-compressed pixel data |
+| `read_png_chunks` | Walk a PNG's chunk stream directly from its bytes to report every chunk's type, offset, size, and CRC-32 validity, plus the decoded IHDR header and common ancillary chunks (tEXt, pHYs, gAMA, tIME, acTL) |
 
 ### PDF (3 tools)
 | Tool | Description |
@@ -415,13 +416,14 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `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 |
 | `read_pdf_outline` | Walk a PDF's /Outlines bookmark tree (Root -> Outlines -> First/Next/First chain) and list every bookmark's title, nesting level, and link target, in document order: no PDF rendering library required |
 
-### Audio (4 tools)
+### Audio (5 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 |
+| `estimate_audio_file_size` | Estimate an audio file's size before recording or exporting it: uncompressed PCM size from sample rate/bit depth/channels, or compressed size from a target bitrate |
 
 ### Video (1 tool)
 | Tool | Description |

package/dist/index.js

@@ -15090,5 +15090,169 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+var _PNG_SIGNATURE_MCP = [137, 80, 78, 71, 13, 10, 26, 10];
+function _readU32BEMcp(bytes, offset) {
+  return (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+}
+var _pngCrcTableMcp = null;
+function _pngCrc32Mcp(bytes) {
+  if (!_pngCrcTableMcp) {
+    const table = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+      let c = n;
+      for (let k = 0; k < 8; k++) c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+      table[n] = c;
+    }
+    _pngCrcTableMcp = table;
+  }
+  let crc = 4294967295;
+  for (let i = 0; i < bytes.length; i++) crc = _pngCrcTableMcp[(crc ^ bytes[i]) & 255] ^ crc >>> 8;
+  return (crc ^ 4294967295) >>> 0;
+}
+var _PNG_COLOR_TYPES_MCP = { 0: "grayscale", 2: "rgb", 3: "palette", 4: "grayscale+alpha", 6: "rgba" };
+function _pad2Mcp(n) {
+  return n < 10 ? `0${n}` : `${n}`;
+}
+function _readPngChunksMcp(bytes) {
+  if (bytes.length < 8) return { error: "File too small to be a valid PNG file" };
+  for (let i = 0; i < 8; i++) {
+    if (bytes[i] !== _PNG_SIGNATURE_MCP[i]) return { error: "Not a valid PNG file (bad 8-byte signature)" };
+  }
+  const chunks = [];
+  const textChunks = [];
+  let header = null;
+  let physicalDimensions = null;
+  let gamma = null;
+  let lastModified = null;
+  let isAnimated = false;
+  let offset = 8;
+  while (offset + 8 <= bytes.length) {
+    const dataLength = _readU32BEMcp(bytes, offset);
+    const type = String.fromCharCode(bytes[offset + 4], bytes[offset + 5], bytes[offset + 6], bytes[offset + 7]);
+    const dataStart = offset + 8;
+    const dataEnd = dataStart + dataLength;
+    const crcOffset = dataEnd;
+    if (crcOffset + 4 > bytes.length) return { error: `Truncated chunk "${type}" at offset ${offset}` };
+    const data = bytes.subarray(dataStart, dataEnd);
+    const expectedCrc = _readU32BEMcp(bytes, crcOffset);
+    const actualCrc = _pngCrc32Mcp(bytes.subarray(offset + 4, dataEnd));
+    const firstChar = type.charCodeAt(0);
+    const critical = firstChar >= 65 && firstChar <= 90;
+    chunks.push({ type, offset, dataLength, crcValid: actualCrc === expectedCrc, critical });
+    if (type === "IHDR" && data.length >= 13) {
+      const colorTypeNum = data[9];
+      header = {
+        width: _readU32BEMcp(data, 0),
+        height: _readU32BEMcp(data, 4),
+        bitDepth: data[8],
+        colorType: _PNG_COLOR_TYPES_MCP[colorTypeNum] ?? "unknown",
+        hasAlpha: colorTypeNum === 4 || colorTypeNum === 6,
+        interlace: data[12] === 1
+      };
+    } else if (type === "tEXt") {
+      const nullIdx = data.indexOf(0);
+      if (nullIdx !== -1) {
+        textChunks.push({
+          keyword: Buffer.from(data.subarray(0, nullIdx)).toString("latin1"),
+          text: Buffer.from(data.subarray(nullIdx + 1)).toString("latin1"),
+          compressed: false
+        });
+      }
+    } else if (type === "zTXt" || type === "iTXt") {
+      const nullIdx = data.indexOf(0);
+      if (nullIdx !== -1) {
+        textChunks.push({ keyword: Buffer.from(data.subarray(0, nullIdx)).toString("latin1"), text: null, compressed: true });
+      }
+    } else if (type === "pHYs" && data.length >= 9) {
+      physicalDimensions = { pixelsPerUnitX: _readU32BEMcp(data, 0), pixelsPerUnitY: _readU32BEMcp(data, 4), unit: data[8] === 1 ? "meter" : "unknown" };
+    } else if (type === "gAMA" && data.length >= 4) {
+      gamma = _readU32BEMcp(data, 0) / 1e5;
+    } else if (type === "tIME" && data.length >= 7) {
+      const year = data[0] << 8 | data[1];
+      lastModified = `${year}-${_pad2Mcp(data[2])}-${_pad2Mcp(data[3])}T${_pad2Mcp(data[4])}:${_pad2Mcp(data[5])}:${_pad2Mcp(data[6])}Z`;
+    } else if (type === "acTL") {
+      isAnimated = true;
+    }
+    offset = crcOffset + 4;
+    if (type === "IEND") break;
+  }
+  if (chunks.length === 0) return { error: "No chunks found after the PNG signature" };
+  if (!header) return { error: "Missing required IHDR chunk" };
+  return { valid: true, fileSize: bytes.length, chunkCount: chunks.length, chunks, header, textChunks, physicalDimensions, gamma, lastModified, isAnimated };
+}
+server.tool(
+  "read_png_chunks",
+  "Walk a PNG file's chunk stream directly from its bytes to report every chunk's type, byte offset, data length, and whether its stored CRC-32 matches the data, plus the decoded IHDR header and a handful of common ancillary chunks (tEXt, pHYs, gAMA, tIME, acTL). No pixel decoding, and zTXt/iTXt text is listed but not zlib-inflated.",
+  { png_base64: z.string().describe("Base64-encoded PNG file bytes, optionally prefixed with a data: URL scheme") },
+  async ({ png_base64 }) => {
+    const bytes = new Uint8Array(Buffer.from(png_base64.replace(/^data:.*;base64,/, ""), "base64"));
+    const result = _readPngChunksMcp(bytes);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+function _estimateAudioFileSizeMcp(mode, durationSeconds, sampleRateHz, bitDepth, channels, bitrateKbps) {
+  if (!Number.isFinite(durationSeconds) || durationSeconds <= 0) {
+    return { error: "durationSeconds must be a positive number" };
+  }
+  const round2 = (n) => Math.round(n * 100) / 100;
+  if (mode === "pcm") {
+    if (typeof sampleRateHz !== "number" || !Number.isFinite(sampleRateHz) || sampleRateHz <= 0) {
+      return { error: 'sampleRateHz must be a positive number for mode "pcm"' };
+    }
+    if (typeof bitDepth !== "number" || !Number.isFinite(bitDepth) || bitDepth <= 0) {
+      return { error: 'bitDepth must be a positive number for mode "pcm"' };
+    }
+    if (typeof channels !== "number" || !Number.isInteger(channels) || channels <= 0) {
+      return { error: 'channels must be a positive whole number for mode "pcm"' };
+    }
+    const dataBytes = sampleRateHz * (bitDepth / 8) * channels * durationSeconds;
+    const fileSizeBytes = dataBytes + 44;
+    return {
+      mode,
+      durationSeconds,
+      sampleRateHz,
+      bitDepth,
+      channels,
+      dataBytes: Math.round(dataBytes),
+      fileSizeBytes: Math.round(fileSizeBytes),
+      fileSizeMB: round2(fileSizeBytes / 1e6),
+      fileSizeMiB: round2(fileSizeBytes / 1048576)
+    };
+  }
+  if (mode === "compressed") {
+    if (typeof bitrateKbps !== "number" || !Number.isFinite(bitrateKbps) || bitrateKbps <= 0) {
+      return { error: 'bitrateKbps must be a positive number for mode "compressed"' };
+    }
+    const dataBytes = bitrateKbps * 1e3 * durationSeconds / 8;
+    return {
+      mode,
+      durationSeconds,
+      bitrateKbps,
+      dataBytes: Math.round(dataBytes),
+      fileSizeBytes: Math.round(dataBytes),
+      fileSizeMB: round2(dataBytes / 1e6),
+      fileSizeMiB: round2(dataBytes / 1048576)
+    };
+  }
+  return { error: 'mode must be "pcm" or "compressed"' };
+}
+server.tool(
+  "estimate_audio_file_size",
+  'Estimate how large an audio file will be before recording or exporting it. Mode "pcm" computes the uncompressed size from sample rate, bit depth, and channel count, plus a canonical 44-byte WAV header. Mode "compressed" computes it from a target bitrate. Pure arithmetic: no file is read, written, or encoded.',
+  {
+    mode: z.enum(["pcm", "compressed"]).describe('"pcm" requires sampleRateHz/bitDepth/channels; "compressed" requires bitrateKbps'),
+    durationSeconds: z.number().describe("Audio duration in seconds"),
+    sampleRateHz: z.number().optional().describe('Required for mode "pcm", e.g. 44100 for CD quality'),
+    bitDepth: z.number().optional().describe('Required for mode "pcm", bits per sample, e.g. 16 or 24'),
+    channels: z.number().optional().describe('Required for mode "pcm", e.g. 1 = mono, 2 = stereo'),
+    bitrateKbps: z.number().optional().describe('Required for mode "compressed", e.g. 192 for a typical MP3')
+  },
+  async ({ mode, durationSeconds, sampleRateHz, bitDepth, channels, bitrateKbps }) => {
+    const result = _estimateAudioFileSizeMcp(mode, durationSeconds, sampleRateHz, bitDepth, channels, bitrateKbps);
+    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,7 +1,7 @@
 {
   "name": "@utilix-tech/mcp",
-  "version": "0.94.0",
-  "description": "MCP server exposing 279 Utilix developer tools to Claude, Cursor, VS Code Copilot, and any MCP-compatible AI assistant.",
+  "version": "0.95.0",
+  "description": "MCP server exposing 283 Utilix developer tools to Claude, Cursor, VS Code Copilot, and any MCP-compatible AI assistant.",
   "author": "Utilix <hello@utilix.tech>",
   "license": "MIT",
   "homepage": "https://utilix.tech/mcp",