@utilix-tech/mcp 0.8.0 → 0.10.0

package/CHANGELOG.md

@@ -2,6 +2,24 @@
 
 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.10.0
+- Added Sitemap.xml Validator (`validate_sitemap`).
+
+## 0.9.0
+- Added ID3 Tag Reader and .env.example Diff Checker.
+
+## 0.8.0
+- Added WAV Audio Info and Readability Score Calculator.
+
+## 0.7.0
+- Added EXIF Viewer and Commit Message Generator (AI).
+
+## 0.6.0
+- Added PDF Metadata Reader and JWK Viewer.
+
+## 0.5.0
+- Added HAR File Viewer and NDJSON Formatter/Validator.
+
 ## 0.4.1
 - Bumped the `@utilix-tech/sdk` dependency from `^0.2.0` to `^0.3.0` to match the SDK version actually in use, closing a gap where a future tool addition could have silently pinned to a stale SDK release.
 - Corrected repository/bug tracker links.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 104 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 107 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.
 
@@ -151,7 +151,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `convert_bytes` | Convert between B, KB, MB, GB, TB, KiB, MiB, GiB, TiB |
 | `px_to_units` | Convert pixels to rem, em, pt, and vw |
 
-### API / Network (6 tools)
+### API / Network (7 tools)
 | Tool | Description |
 |------|-------------|
 | `decode_jwt` | Decode a JWT: header, payload, and expiry |
@@ -160,6 +160,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `curl_to_code` | Convert a cURL command to fetch, axios, Python, Go, PHP, or Ruby |
 | `cors_headers` | Generate CORS response headers for a configuration |
 | `parse_har` | Parse a DevTools .har network export into requests and summary stats |
+| `validate_sitemap` | Validate a sitemap.xml or sitemap index against the sitemaps.org protocol |
 
 ### Color (4 tools)
 | Tool | Description |
@@ -180,7 +181,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `parse_env` | Parse a .env file and return all key-value pairs |
 | `parse_docker_image` | Parse a Docker image reference into its components |
 
-### Data (5 tools)
+### Data (6 tools)
 | Tool | Description |
 |------|-------------|
 | `validate_yaml` | Validate YAML syntax |
@@ -188,6 +189,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `xml_to_json` | Convert XML to JSON |
 | `parse_csv` | Parse a CSV string and return the data as JSON |
 | `format_ndjson` | Validate and pretty-print newline-delimited JSON (NDJSON) |
+| `diff_env_example` | Diff a .env file against its .env.example template: flags keys missing from either side, plus empty placeholder values |
 
 ### CSS (2 tools)
 | Tool | Description |
@@ -242,10 +244,11 @@ 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 |
 
-### Audio (1 tool)
+### Audio (2 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 |
 
 ## Requirements
 

package/dist/index.js

@@ -1479,6 +1479,106 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+var _SITEMAP_VALID_CHANGEFREQ = /* @__PURE__ */ new Set(["always", "hourly", "daily", "weekly", "monthly", "yearly", "never"]);
+function _sitemapLineNumber(xml, index) {
+  let line = 1;
+  for (let i = 0; i < index; i++) {
+    if (xml[i] === "\n") line++;
+  }
+  return line;
+}
+function _extractSitemapTag(block, tag) {
+  const m = block.match(new RegExp(`<${tag}[^>]*>([\\s\\S]*?)</${tag}>`, "i"));
+  return m ? m[1].trim() : void 0;
+}
+function _isValidW3CDatetime(s) {
+  return /^\d{4}(-\d{2}(-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2}))?)?)?$/.test(s);
+}
+function _isAbsoluteHttpUrl(s) {
+  return /^https?:\/\//i.test(s);
+}
+function _validateSitemap(xml) {
+  if (!xml || !xml.trim()) return { error: "Input is empty" };
+  const trimmed = xml.trim();
+  const issues = [];
+  if (!/^\s*<\?xml/i.test(trimmed)) {
+    issues.push({ severity: "warning", line: 1, message: 'Missing XML declaration (<?xml version="1.0" encoding="UTF-8"?>)' });
+  }
+  const isUrlset = /<urlset[\s>]/i.test(trimmed);
+  const isSitemapIndex = /<sitemapindex[\s>]/i.test(trimmed);
+  if (!isUrlset && !isSitemapIndex) {
+    return { error: "Not a valid sitemap: root element must be <urlset> or <sitemapindex>" };
+  }
+  if (isUrlset && isSitemapIndex) {
+    return { error: "Ambiguous file: contains both <urlset> and <sitemapindex> root elements" };
+  }
+  const type = isUrlset ? "urlset" : "sitemapindex";
+  if (isUrlset && !/xmlns\s*=\s*["']http:\/\/www\.sitemaps\.org\/schemas\/sitemap\/0\.9["']/i.test(trimmed)) {
+    issues.push({ severity: "warning", line: 1, message: "Missing or non-standard xmlns namespace (expected http://www.sitemaps.org/schemas/sitemap/0.9)" });
+  }
+  const blockTag = isUrlset ? "url" : "sitemap";
+  const blockRe = new RegExp(`<${blockTag}>([\\s\\S]*?)</${blockTag}>`, "gi");
+  const seenLocs = /* @__PURE__ */ new Set();
+  const entries = [];
+  let match;
+  while ((match = blockRe.exec(trimmed)) !== null) {
+    const block = match[1];
+    const line = _sitemapLineNumber(trimmed, match.index);
+    const loc = _extractSitemapTag(block, "loc");
+    if (!loc) {
+      issues.push({ severity: "error", line, message: `<${blockTag}> entry is missing required <loc>` });
+      continue;
+    }
+    if (!_isAbsoluteHttpUrl(loc)) {
+      issues.push({ severity: "error", line, message: `<loc>${loc}</loc> must be an absolute URL starting with http:// or https://` });
+    }
+    if (/&(?!amp;|lt;|gt;|apos;|quot;|#\d+;)/.test(loc)) {
+      issues.push({ severity: "error", line, message: `<loc>${loc}</loc> contains an unescaped '&' (use &amp; instead)` });
+    }
+    if (seenLocs.has(loc)) {
+      issues.push({ severity: "warning", line, message: `Duplicate <loc>${loc}</loc>` });
+    }
+    seenLocs.add(loc);
+    const lastmod = _extractSitemapTag(block, "lastmod");
+    if (lastmod !== void 0 && !_isValidW3CDatetime(lastmod)) {
+      issues.push({ severity: "warning", line, message: `<lastmod>${lastmod}</lastmod> is not a valid W3C datetime` });
+    }
+    if (type === "urlset") {
+      const changefreq = _extractSitemapTag(block, "changefreq");
+      if (changefreq !== void 0 && !_SITEMAP_VALID_CHANGEFREQ.has(changefreq.toLowerCase())) {
+        issues.push({ severity: "error", line, message: `<changefreq>${changefreq}</changefreq> must be one of: ${[..._SITEMAP_VALID_CHANGEFREQ].join(", ")}` });
+      }
+      const priority = _extractSitemapTag(block, "priority");
+      if (priority !== void 0) {
+        const p = Number(priority);
+        if (Number.isNaN(p) || p < 0 || p > 1) {
+          issues.push({ severity: "error", line, message: `<priority>${priority}</priority> must be a number between 0.0 and 1.0` });
+        }
+      }
+      entries.push({ loc, lastmod, changefreq, priority, line });
+    } else {
+      entries.push({ loc, lastmod, line });
+    }
+  }
+  if (entries.length === 0) {
+    issues.push({ severity: "error", line: 1, message: `No <${blockTag}> entries found` });
+  }
+  if (type === "urlset" && entries.length > 5e4) {
+    issues.push({ severity: "error", line: 1, message: `Sitemap contains ${entries.length} URLs, exceeding the 50,000 URL limit per the sitemaps.org spec` });
+  }
+  const valid = !issues.some((i) => i.severity === "error");
+  return { type, urlCount: entries.length, entries, issues, valid };
+}
+server.tool(
+  "validate_sitemap",
+  "Validate a sitemap.xml (urlset) or sitemap index (sitemapindex) against the sitemaps.org protocol: required <loc>, absolute URLs, valid <changefreq>/<priority>/<lastmod> values, the 50,000-URL limit, and duplicate entries.",
+  { xml: z.string().describe("The sitemap.xml or sitemap index XML contents") },
+  async ({ xml }) => {
+    const result = _validateSitemap(xml);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
 server.tool(
   "format_ndjson",
   "Validate newline-delimited JSON (NDJSON/JSON Lines), report per-line errors, and pretty-print each valid line.",
@@ -2007,5 +2107,291 @@ function _scoreReadability(input) {
 server.tool("score_readability", "Score text with Flesch Reading Ease, Flesch-Kincaid Grade Level, and Gunning Fog Index, using a heuristic syllable counter.", { text: z.string() }, async ({ text: input }) => {
   return { content: [{ type: "text", text: JSON.stringify(_scoreReadability(input), null, 2) }] };
 });
+var _ID3V1_GENRES = [
+  "Blues",
+  "Classic Rock",
+  "Country",
+  "Dance",
+  "Disco",
+  "Funk",
+  "Grunge",
+  "Hip-Hop",
+  "Jazz",
+  "Metal",
+  "New Age",
+  "Oldies",
+  "Other",
+  "Pop",
+  "R&B",
+  "Rap",
+  "Reggae",
+  "Rock",
+  "Techno",
+  "Industrial",
+  "Alternative",
+  "Ska",
+  "Death Metal",
+  "Pranks",
+  "Soundtrack",
+  "Euro-Techno",
+  "Ambient",
+  "Trip-Hop",
+  "Vocal",
+  "Jazz+Funk",
+  "Fusion",
+  "Trance",
+  "Classical",
+  "Instrumental",
+  "Acid",
+  "House",
+  "Game",
+  "Sound Clip",
+  "Gospel",
+  "Noise",
+  "AlternRock",
+  "Bass",
+  "Soul",
+  "Punk",
+  "Space",
+  "Meditative",
+  "Instrumental Pop",
+  "Instrumental Rock",
+  "Ethnic",
+  "Gothic",
+  "Darkwave",
+  "Techno-Industrial",
+  "Electronic",
+  "Pop-Folk",
+  "Eurodance",
+  "Dream",
+  "Southern Rock",
+  "Comedy",
+  "Cult",
+  "Gangsta",
+  "Top 40",
+  "Christian Rap",
+  "Pop/Funk",
+  "Jungle",
+  "Native American",
+  "Cabaret",
+  "New Wave",
+  "Psychedelic",
+  "Rave",
+  "Showtunes",
+  "Trailer",
+  "Lo-Fi",
+  "Tribal",
+  "Acid Punk",
+  "Acid Jazz",
+  "Polka",
+  "Retro",
+  "Musical",
+  "Rock & Roll",
+  "Hard Rock"
+];
+function _id3ReadSynchsafeUInt32(bytes, offset) {
+  return (bytes[offset] & 127) << 21 | (bytes[offset + 1] & 127) << 14 | (bytes[offset + 2] & 127) << 7 | bytes[offset + 3] & 127;
+}
+function _id3ReadUInt32BE(bytes, offset) {
+  return (bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3]) >>> 0;
+}
+function _decodeId3Text(frameBytes) {
+  if (frameBytes.length === 0) return "";
+  const encodingByte = frameBytes[0];
+  const content = frameBytes.subarray(1);
+  let out = "";
+  if (encodingByte === 3) {
+    out = Buffer.from(content).toString("utf8");
+  } else if (encodingByte === 1 || encodingByte === 2) {
+    let little = encodingByte === 1;
+    let start = 0;
+    if (encodingByte === 1 && content.length >= 2) {
+      if (content[0] === 255 && content[1] === 254) {
+        little = true;
+        start = 2;
+      } else if (content[0] === 254 && content[1] === 255) {
+        little = false;
+        start = 2;
+      }
+    }
+    for (let i = start; i + 1 < content.length; i += 2) {
+      const code = little ? content[i] | content[i + 1] << 8 : content[i] << 8 | content[i + 1];
+      if (code === 0) break;
+      out += String.fromCharCode(code);
+    }
+  } else {
+    for (const b of content) {
+      if (b === 0) break;
+      out += String.fromCharCode(b);
+    }
+  }
+  return out.replace(/\0+$/, "").trim();
+}
+function _readId3v2(bytes) {
+  if (bytes.length < 10 || bytes[0] !== 73 || bytes[1] !== 68 || bytes[2] !== 51) return null;
+  const majorVersion = bytes[3];
+  const revision = bytes[4];
+  const tagSize = _id3ReadSynchsafeUInt32(bytes, 6);
+  const version = `ID3v2.${majorVersion}.${revision}`;
+  if (majorVersion !== 3 && majorVersion !== 4) {
+    return { version, frames: {}, frameCount: 0 };
+  }
+  const frames = {};
+  let offset = 10;
+  const end = Math.min(10 + tagSize, bytes.length);
+  let frameCount = 0;
+  while (offset + 10 <= end) {
+    const frameId = String.fromCharCode(bytes[offset], bytes[offset + 1], bytes[offset + 2], bytes[offset + 3]);
+    if (frameId === "\0\0\0\0") break;
+    const frameSize = majorVersion === 4 ? _id3ReadSynchsafeUInt32(bytes, offset + 4) : _id3ReadUInt32BE(bytes, offset + 4);
+    const frameStart = offset + 10;
+    if (frameSize <= 0 || frameStart + frameSize > bytes.length) break;
+    const frameBytes = bytes.subarray(frameStart, frameStart + frameSize);
+    if (frameId[0] === "T" && frameId !== "TXXX") {
+      frames[frameId] = _decodeId3Text(frameBytes);
+    } else if (frameId === "COMM" && frameBytes.length > 4) {
+      const rebuilt = new Uint8Array(frameBytes.length - 3);
+      rebuilt[0] = frameBytes[0];
+      rebuilt.set(frameBytes.subarray(4), 1);
+      const decoded = _decodeId3Text(rebuilt);
+      const parts = decoded.split("\0");
+      frames["COMM"] = (parts[parts.length - 1] || decoded).trim();
+    }
+    frameCount++;
+    offset = frameStart + frameSize;
+  }
+  return { version, frames, frameCount };
+}
+function _readId3v1(bytes) {
+  if (bytes.length < 128) return null;
+  const start = bytes.length - 128;
+  if (String.fromCharCode(bytes[start], bytes[start + 1], bytes[start + 2]) !== "TAG") return null;
+  const readField = (offset, length) => {
+    let s = "";
+    for (let i = 0; i < length; i++) {
+      const b = bytes[start + offset + i];
+      if (b === 0) break;
+      s += String.fromCharCode(b);
+    }
+    return s.trim();
+  };
+  const title = readField(3, 30);
+  const artist = readField(33, 30);
+  const album = readField(63, 30);
+  const year = readField(93, 4);
+  const isV11 = bytes[start + 125] === 0 && bytes[start + 126] !== 0;
+  const comment = readField(97, isV11 ? 28 : 30);
+  const genreIndex = bytes[start + 127];
+  const genre = _ID3V1_GENRES[genreIndex] ?? `Unknown (${genreIndex})`;
+  const result = { genre };
+  if (title) result.title = title;
+  if (artist) result.artist = artist;
+  if (album) result.album = album;
+  if (year) result.year = year;
+  if (comment) result.comment = comment;
+  if (isV11) result.trackNumber = String(bytes[start + 126]);
+  return result;
+}
+function _readId3Tags(bytes) {
+  const v2 = _readId3v2(bytes);
+  const v1 = _readId3v1(bytes);
+  if (v2 && Object.keys(v2.frames).length > 0) {
+    const f = v2.frames;
+    const result = { version: v2.version, frameCount: v2.frameCount };
+    if (f["TIT2"]) result.title = f["TIT2"];
+    if (f["TPE1"]) result.artist = f["TPE1"];
+    if (f["TALB"]) result.album = f["TALB"];
+    const year = f["TYER"] || f["TDRC"];
+    if (year) result.year = year;
+    if (f["TCON"]) result.genre = f["TCON"];
+    if (f["COMM"]) result.comment = f["COMM"];
+    if (f["TRCK"]) result.trackNumber = f["TRCK"];
+    return result;
+  }
+  if (v1) {
+    return { version: v1.trackNumber !== void 0 ? "ID3v1.1" : "ID3v1", ...v1 };
+  }
+  if (v2) {
+    return { error: `Unsupported ID3 tag version: ${v2.version} (only ID3v2.3, ID3v2.4, and ID3v1/1.1 are supported)` };
+  }
+  return { error: "No ID3v1 or ID3v2.3/2.4 tags found in this file" };
+}
+server.tool("read_id3_tags", "Read ID3 tags (title, artist, album, year, genre, comment, track number) directly from an MP3 file's bytes. Prefers an ID3v2.3/2.4 header; falls back to a classic ID3v1/1.1 128-byte trailer. No audio library required.", { mp3_base64: z.string().describe("Base64-encoded MP3 file bytes, optionally prefixed with a data: URL scheme") }, async ({ mp3_base64 }) => {
+  const bytes = new Uint8Array(Buffer.from(mp3_base64.replace(/^data:.*;base64,/, ""), "base64"));
+  const result = _readId3Tags(bytes);
+  if ("error" in result) return errText(result);
+  return text(JSON.stringify(result, null, 2));
+});
+function _parseEnvForDiff(input) {
+  const entries = [];
+  const errors = [];
+  const rawLines = input.split("\n");
+  const lines = [];
+  let i = 0;
+  while (i < rawLines.length) {
+    let line = rawLines[i];
+    while (line.endsWith("\\") && i + 1 < rawLines.length) {
+      line = line.slice(0, -1) + rawLines[i + 1];
+      i++;
+    }
+    lines.push(line);
+    i++;
+  }
+  for (let lineIdx = 0; lineIdx < lines.length; lineIdx++) {
+    const lineNum = lineIdx + 1;
+    const trimmed = lines[lineIdx].trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const eqIdx = trimmed.indexOf("=");
+    if (eqIdx === -1) {
+      errors.push(`Line ${lineNum}: missing '='`);
+      continue;
+    }
+    const key = trimmed.slice(0, eqIdx).trim();
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+      errors.push(`Line ${lineNum}: Invalid key: '${key}'`);
+      continue;
+    }
+    const rest = trimmed.slice(eqIdx + 1);
+    let value = "";
+    if (rest.startsWith('"')) {
+      const closeIdx = rest.indexOf('"', 1);
+      if (closeIdx === -1) {
+        errors.push(`Line ${lineNum}: Unclosed double quote for key '${key}'`);
+        continue;
+      }
+      value = rest.slice(1, closeIdx);
+    } else if (rest.startsWith("'")) {
+      const closeIdx = rest.indexOf("'", 1);
+      if (closeIdx === -1) {
+        errors.push(`Line ${lineNum}: Unclosed single quote for key '${key}'`);
+        continue;
+      }
+      value = rest.slice(1, closeIdx);
+    } else {
+      const hashIdx = rest.indexOf("#");
+      value = (hashIdx !== -1 ? rest.slice(0, hashIdx) : rest).trim();
+    }
+    entries.push({ key, value });
+  }
+  return { entries, errors };
+}
+function _diffEnvExample(envInput, exampleInput) {
+  const envParsed = _parseEnvForDiff(envInput);
+  if (envParsed.errors.length > 0) return { error: `.env: ${envParsed.errors.join("; ")}` };
+  const exampleParsed = _parseEnvForDiff(exampleInput);
+  if (exampleParsed.errors.length > 0) return { error: `.env.example: ${exampleParsed.errors.join("; ")}` };
+  const envKeys = new Set(envParsed.entries.map((e) => e.key));
+  const exampleValues = new Map(exampleParsed.entries.map((e) => [e.key, e.value]));
+  const missingInExample = [...envKeys].filter((k) => !exampleValues.has(k)).sort();
+  const missingInEnv = [...exampleValues.keys()].filter((k) => !envKeys.has(k)).sort();
+  const emptyValueInExample = [...exampleValues.entries()].filter(([k, v]) => envKeys.has(k) && v === "").map(([k]) => k).sort();
+  const keysInBoth = [...envKeys].filter((k) => exampleValues.has(k)).length;
+  return { missingInExample, missingInEnv, emptyValueInExample, keysInBoth };
+}
+server.tool("diff_env_example", "Diff a .env file against its .env.example template: flags keys missing from either side, plus keys present in both with an empty placeholder value in the example.", { env: z.string().describe("The .env file contents"), example: z.string().describe("The .env.example file contents") }, async ({ env, example }) => {
+  const result = _diffEnvExample(env, example);
+  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.8.0",
-  "description": "MCP server exposing 104 Utilix developer tools to Claude, Cursor, VS Code Copilot, and any MCP-compatible AI assistant.",
+  "version": "0.10.0",
+  "description": "MCP server exposing 107 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",