@utilix-tech/mcp 0.41.0 → 0.43.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.43.0
+- Add `build_vary_header`, `parse_vary_header` tools: build a `Vary` response header from request-header names with a plain-English caching note per header, or parse an existing Vary header into the same shape.
+
+## 0.42.0
+- Add `build_range_header`, `parse_content_range_header` tools: build an HTTP `Range` request header from explicit, open-ended, or suffix ("last N bytes") byte ranges, and parse a server's `Content-Range` response to verify what it actually sent back.
+- Add `find_csv_duplicate_rows` tool: group CSV/TSV rows that share the same value across a chosen set of key columns, or the entire row, and report each duplicate group's occurrence count and data row numbers.
+
 ## 0.41.0
 - Add `calculate_cash_breakdown`, `calculate_change` tools: break a cash amount down into the minimum count of bills/coins from a set of denominations (largest first), or compute change owed for a payment/tender pair and its breakdown.
 - Add `generate_etag` tool: compute a content-hash ETag (MD5/SHA-1/SHA-256) for a response header, with an optional weak-validator (W/) prefix.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 168 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 173 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.
 
@@ -189,7 +189,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `calculate_cash_breakdown` | Break a cash amount down into the minimum count of bills/coins from a set of denominations, largest first |
 | `calculate_change` | Compute change owed for a payment/tender pair and break it down into the minimum count of bills/coins |
 
-### API / Network (16 tools)
+### API / Network (20 tools)
 | Tool | Description |
 |------|-------------|
 | `decode_jwt` | Decode a JWT: header, payload, and expiry |
@@ -208,6 +208,10 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `build_link_header` | Build and explain an HTTP Link response header from URL/rel pairs (preload, preconnect, prefetch, canonical, pagination, etc.) |
 | `check_set_cookie_header` | Parse a Set-Cookie header and validate its attribute combination: SameSite=None requires Secure, __Host-/__Secure- prefix rules, missing Secure, overly long Max-Age |
 | `analyze_email_headers` | Parse a raw email header block into structured fields, the Received hop chain, and SPF/DKIM/DMARC results from an Authentication-Results header |
+| `build_range_header` | Build an HTTP Range request header from explicit, open-ended, or suffix ("last N bytes") byte ranges |
+| `parse_content_range_header` | Parse a Content-Range response header into its unit, byte bounds, and total resource size |
+| `build_vary_header` | Build a Vary response header from request-header names, with a plain-English caching note per header |
+| `parse_vary_header` | Parse an existing Vary header value into its individual header names, each with a caching note |
 
 ### Color (4 tools)
 | Tool | Description |
@@ -233,7 +237,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `lint_conventional_commit` | Lint a commit message against the Conventional Commits v1.0.0 spec: header format, blank-line separation, footer tokens, and BREAKING CHANGE casing |
 | `test_gitignore_patterns` | Test a list of paths against a .gitignore file's patterns, following git's last-match-wins and negation rules |
 
-### Data (9 tools)
+### Data (10 tools)
 | Tool | Description |
 |------|-------------|
 | `validate_yaml` | Validate YAML syntax |
@@ -245,6 +249,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `parse_markdown_front_matter` | Split a Markdown document into its YAML front matter fields and body content |
 | `generate_markdown_toc` | Scan a Markdown document's ATX headings and build a nested table of contents with GitHub-style anchor slugs |
 | `csv_to_sql_insert` | Convert CSV data with a header row into parameterless SQL INSERT statements, with basic type inference and ANSI/MySQL identifier quoting |
+| `find_csv_duplicate_rows` | Group CSV/TSV rows that share the same value across a chosen set of key columns, or the entire row |
 
 ### CSS (2 tools)
 | Tool | Description |

package/dist/index.js

@@ -6931,5 +6931,272 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+function _round2Mcp(n) {
+  return Math.round(n * 100) / 100;
+}
+function _buildRangeHeaderMcp(entries, totalSize, unitRaw) {
+  if (!Array.isArray(entries) || entries.length === 0) {
+    return { error: "At least one range is required" };
+  }
+  const unit = unitRaw?.trim() || "bytes";
+  if (totalSize !== void 0 && (!Number.isFinite(totalSize) || totalSize <= 0)) {
+    return { error: "totalSize must be a positive number when provided" };
+  }
+  const parsed = [];
+  for (const entry of entries) {
+    if (entry.suffixLength !== void 0) {
+      if (!Number.isFinite(entry.suffixLength) || entry.suffixLength <= 0) {
+        return { error: "suffixLength must be a positive number" };
+      }
+      const suffixLength = Math.floor(entry.suffixLength);
+      const byteLength = totalSize !== void 0 ? Math.min(suffixLength, totalSize) : suffixLength;
+      parsed.push({
+        spec: `-${suffixLength}`,
+        start: null,
+        end: null,
+        suffixLength,
+        byteLength,
+        percentOfTotal: totalSize !== void 0 ? _round2Mcp(byteLength / totalSize * 100) : null
+      });
+      continue;
+    }
+    if (entry.start === void 0) {
+      return { error: "Each range requires either a start byte or a suffixLength" };
+    }
+    if (!Number.isFinite(entry.start) || entry.start < 0) {
+      return { error: "start must be a non-negative number" };
+    }
+    const start = Math.floor(entry.start);
+    if (totalSize !== void 0 && start >= totalSize) {
+      return { error: `start byte ${start} is beyond totalSize (${totalSize})` };
+    }
+    if (entry.end !== void 0) {
+      if (!Number.isFinite(entry.end) || entry.end < 0) {
+        return { error: "end must be a non-negative number" };
+      }
+      const end = Math.floor(entry.end);
+      if (end < start) return { error: `range end (${end}) must be >= start (${start})` };
+      if (totalSize !== void 0 && end >= totalSize) {
+        return { error: `end byte ${end} is beyond totalSize (${totalSize})` };
+      }
+      const byteLength = end - start + 1;
+      parsed.push({
+        spec: `${start}-${end}`,
+        start,
+        end,
+        suffixLength: null,
+        byteLength,
+        percentOfTotal: totalSize !== void 0 ? _round2Mcp(byteLength / totalSize * 100) : null
+      });
+    } else {
+      const byteLength = totalSize !== void 0 ? totalSize - start : null;
+      parsed.push({
+        spec: `${start}-`,
+        start,
+        end: null,
+        suffixLength: null,
+        byteLength,
+        percentOfTotal: byteLength !== null && totalSize !== void 0 ? _round2Mcp(byteLength / totalSize * 100) : null
+      });
+    }
+  }
+  const warnings = [];
+  const resolvable = parsed.map((r, i) => ({ i, start: r.start ?? (totalSize !== void 0 && r.suffixLength !== null ? totalSize - Math.min(r.suffixLength, totalSize) : null), end: r.end ?? (totalSize !== void 0 ? totalSize - 1 : null) })).filter((r) => r.start !== null && r.end !== null).sort((a, b) => a.start - b.start);
+  for (let i = 1; i < resolvable.length; i++) {
+    if (resolvable[i].start <= resolvable[i - 1].end) {
+      warnings.push(`ranges "${parsed[resolvable[i - 1].i].spec}" and "${parsed[resolvable[i].i].spec}" overlap \u2014 servers may reject overlapping multi-range requests`);
+    }
+  }
+  if (parsed.length > 1 && parsed.some((r) => r.byteLength === null)) {
+    warnings.push("totalSize was not provided, so open-ended ranges cannot be checked for overlap or total byte count");
+  }
+  const totalBytesRequested = parsed.every((r) => r.byteLength !== null) ? parsed.reduce((sum, r) => sum + (r.byteLength ?? 0), 0) : null;
+  const headerValue = `${unit}=${parsed.map((r) => r.spec).join(",")}`;
+  return { header: `Range: ${headerValue}`, headerValue, ranges: parsed, totalBytesRequested, warnings };
+}
+function _parseContentRangeHeaderMcp(header) {
+  if (!header || header.trim() === "") return { error: "Input is empty" };
+  const match = header.trim().match(/^(\S+)\s+(\*|\d+-\d+)\/(\*|\d+)$/);
+  if (!match) {
+    return { error: 'Could not parse Content-Range header. Expected a format like "bytes 200-1000/67589" or "bytes */67589"' };
+  }
+  const [, unit, range, totalRaw] = match;
+  const isUnsatisfiable = range === "*";
+  const isTotalUnknown = totalRaw === "*";
+  const total = isTotalUnknown ? null : Number(totalRaw);
+  if (isUnsatisfiable) {
+    return { unit, start: null, end: null, total, isUnsatisfiable, isTotalUnknown, byteLength: null };
+  }
+  const [startRaw, endRaw] = range.split("-");
+  const start = Number(startRaw);
+  const end = Number(endRaw);
+  if (end < start) return { error: `Invalid range: end (${end}) is before start (${start})` };
+  return { unit, start, end, total, isUnsatisfiable, isTotalUnknown, byteLength: end - start + 1 };
+}
+server.tool(
+  "build_range_header",
+  'Build an HTTP Range request-header value (RFC 7233) from one or more byte ranges: explicit start-end pairs, open-ended "start to end of file" ranges, or suffix "last N bytes" ranges. Pass totalSize to resolve open-ended/suffix byte lengths and get overlap warnings. Pure string assembly and arithmetic; never makes a network request.',
+  {
+    ranges: z.array(z.object({
+      start: z.number().optional().describe("First byte offset (inclusive)"),
+      end: z.number().optional().describe('Last byte offset (inclusive); omit for "to end of file"'),
+      suffixLength: z.number().optional().describe("Request the last N bytes instead of start/end")
+    })).min(1).describe("One or more byte ranges to request"),
+    totalSize: z.number().optional().describe("Total resource size in bytes, used to resolve open-ended/suffix ranges and detect overlap"),
+    unit: z.string().optional().describe('Range unit (default "bytes")')
+  },
+  async ({ ranges, totalSize, unit }) => {
+    const result = _buildRangeHeaderMcp(ranges, totalSize, unit);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+server.tool(
+  "parse_content_range_header",
+  'Parse a Content-Range response header (e.g. "bytes 200-1000/67589" or "bytes */67589" for an unsatisfiable range) into its unit, byte bounds, and total resource size, so you can verify what a server actually sent back for a partial/resumable request.',
+  {
+    header: z.string().min(1).describe("The Content-Range header value to parse")
+  },
+  async ({ header }) => {
+    const result = _parseContentRangeHeaderMcp(header);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+function _normalizeDuplicateValueMcp(value, caseSensitive, trimWhitespace) {
+  let v = value;
+  if (trimWhitespace) v = v.trim();
+  if (!caseSensitive) v = v.toLowerCase();
+  return v;
+}
+function _findCsvDuplicateRowsMcp(input, delimiter, hasHeader, keyColumns, caseSensitive, trimWhitespace) {
+  if (!input || input.trim() === "") return { error: "Input is empty" };
+  const delim = delimiter?.trim() || ",";
+  const header = hasHeader !== false;
+  const cs = caseSensitive !== false;
+  const tw = trimWhitespace !== false;
+  const lines = input.replace(/\r\n/g, "\n").split("\n").filter((l) => l.trim() !== "");
+  if (lines.length === 0) return { error: "No data found" };
+  const allRows = lines.map((l) => _parseCsvRowForSqlMcp(l, delim));
+  const headers = header ? allRows[0].map((h) => h.trim()) : allRows[0].map((_, idx) => `Column ${idx + 1}`);
+  const dataRows = header ? allRows.slice(1) : allRows;
+  if (dataRows.length === 0) return { error: "No data rows found" };
+  let keyIndexes;
+  if (keyColumns && keyColumns.length > 0) {
+    keyIndexes = [];
+    for (const col of keyColumns) {
+      const idx = headers.indexOf(col);
+      if (idx === -1) return { error: `Column "${col}" not found. Available columns: ${headers.join(", ")}` };
+      keyIndexes.push(idx);
+    }
+  } else {
+    keyIndexes = headers.map((_, idx) => idx);
+  }
+  const groups = /* @__PURE__ */ new Map();
+  dataRows.forEach((row, i) => {
+    const key = keyIndexes.map((idx) => row[idx] ?? "");
+    const normalizedKey = keyIndexes.map((idx) => _normalizeDuplicateValueMcp(row[idx] ?? "", cs, tw));
+    const mapKey = JSON.stringify(normalizedKey);
+    const rowNumber = i + 1;
+    const existing = groups.get(mapKey);
+    if (existing) existing.rowNumbers.push(rowNumber);
+    else groups.set(mapKey, { key, rowNumbers: [rowNumber] });
+  });
+  const duplicateGroups = [];
+  let duplicateRowCount = 0;
+  for (const group of groups.values()) {
+    if (group.rowNumbers.length > 1) {
+      duplicateGroups.push({ key: group.key, rowNumbers: group.rowNumbers, count: group.rowNumbers.length });
+      duplicateRowCount += group.rowNumbers.length;
+    }
+  }
+  duplicateGroups.sort((a, b) => b.count - a.count);
+  return {
+    headers,
+    totalRows: dataRows.length,
+    duplicateGroups,
+    duplicateRowCount,
+    uniqueRowCount: dataRows.length - duplicateRowCount + duplicateGroups.length
+  };
+}
+server.tool(
+  "find_csv_duplicate_rows",
+  "Parse CSV/TSV data and group rows that share the same value across a chosen set of key columns, or the entire row if no key columns are given, so you can spot and clean up accidental duplicates before an import. Row numbers count data rows only (the header row, if any, is not counted).",
+  {
+    csv: z.string().min(1).describe("CSV/TSV data to scan for duplicate rows"),
+    delimiter: z.string().optional().describe('Field delimiter (default ",")'),
+    hasHeader: z.boolean().default(true).describe("Whether the first row is a header"),
+    keyColumns: z.array(z.string()).optional().describe("Column names to compare; omit to compare the entire row"),
+    caseSensitive: z.boolean().default(true).describe("Whether comparison is case-sensitive"),
+    trimWhitespace: z.boolean().default(true).describe("Whether to trim whitespace before comparing")
+  },
+  async ({ csv, delimiter, hasHeader, keyColumns, caseSensitive, trimWhitespace }) => {
+    const result = _findCsvDuplicateRowsMcp(csv, delimiter, hasHeader, keyColumns, caseSensitive, trimWhitespace);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+var _VARY_HEADER_NOTES_MCP = {
+  "accept-encoding": "Caches must store a separate response per compression scheme (gzip, br, etc.) the client accepts.",
+  "accept-language": "Caches must store a separate response per requested language, which can fragment a shared cache badly if Accept-Language values are highly varied.",
+  "accept": "Caches must store a separate response per requested content type (e.g. JSON vs HTML).",
+  "user-agent": "Caches must store a separate response per distinct User-Agent string, which is often unique enough to make caching nearly ineffective.",
+  "authorization": "Signals the response is user-specific; most shared caches will refuse to cache it at all rather than key on this header.",
+  "cookie": "Same effect as Authorization: shared caches typically treat the response as private and skip caching rather than key on cookie values.",
+  "origin": "Caches must store a separate response per requesting Origin, needed whenever a response includes CORS headers that differ by origin.",
+  "x-requested-with": "Caches must store a separate response depending on whether the request was made via an XHR/fetch client hint.",
+  "x-forwarded-proto": "Caches must store a separate response for HTTP vs HTTPS requests, relevant behind a proxy or load balancer that terminates TLS."
+};
+function _buildVaryHeaderMcp(headers) {
+  if (!Array.isArray(headers) || headers.length === 0) return { error: "At least one header is required" };
+  const trimmed = headers.map((h) => typeof h === "string" ? h.trim() : "").filter((h) => h.length > 0);
+  if (trimmed.length === 0) return { error: "At least one header is required" };
+  const warnings = [];
+  if (trimmed.some((h) => h === "*") && trimmed.length > 1) {
+    warnings.push('"*" makes every request effectively uncacheable; combining it with other header names is redundant, most caches will just skip caching entirely');
+  }
+  const seen = /* @__PURE__ */ new Map();
+  for (const h of trimmed) {
+    const key = h.toLowerCase();
+    if (!seen.has(key)) seen.set(key, h);
+  }
+  if (seen.size < trimmed.length) warnings.push("duplicate header names were removed");
+  const entries = Array.from(seen.values()).map((h) => ({
+    header: h,
+    note: h === "*" ? "Every response is considered unique; most caches will not store it at all." : _VARY_HEADER_NOTES_MCP[h.toLowerCase()] ?? `Caches must store a separate response per distinct ${h} value.`
+  }));
+  const headerValue = entries.map((e) => e.header).join(", ");
+  return { header: `Vary: ${headerValue}`, headerValue, entries, warnings };
+}
+function _parseVaryHeaderMcp(raw) {
+  if (!raw || raw.trim() === "") return { error: "Input is empty" };
+  const withoutLabel = raw.trim().replace(/^vary:\s*/i, "");
+  const headers = withoutLabel.split(",").map((h) => h.trim()).filter((h) => h.length > 0);
+  return _buildVaryHeaderMcp(headers);
+}
+server.tool(
+  "build_vary_header",
+  "Build a Vary response-header value from a list of request-header names (e.g. Accept-Encoding, Accept-Language, Authorization), de-duplicating case-insensitively and attaching a plain-English caching note for each well-known header explaining what it does to shared caches.",
+  {
+    headers: z.array(z.string()).min(1).describe("Request-header names to vary the response by")
+  },
+  async ({ headers }) => {
+    const result = _buildVaryHeaderMcp(headers);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+server.tool(
+  "parse_vary_header",
+  'Parse an existing Vary header value (with or without a leading "Vary:" label) into its individual header names, each with a plain-English note on what it does to shared caching.',
+  {
+    header: z.string().min(1).describe("The Vary header value to parse")
+  },
+  async ({ header }) => {
+    const result = _parseVaryHeaderMcp(header);
+    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.41.0",
+  "version": "0.43.0",
   "description": "MCP server exposing 168 Utilix developer tools to Claude, Cursor, VS Code Copilot, and any MCP-compatible AI assistant.",
   "author": "Utilix <hello@utilix.tech>",
   "license": "MIT",