@utilix-tech/mcp 0.65.0 → 0.67.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.67.0
+- Add `analyze_regex_groups` tool: parse a regex pattern's capture groups (numbered and named) and backreferences, flagging any backreference pointing at a group that doesn't exist or hasn't finished being defined yet at that point in the pattern.
+
+## 0.66.0
+- Add `build_x_robots_tag`, `parse_x_robots_tag` tools: build an X-Robots-Tag response header from flag directives (noindex, nofollow, etc.) plus max-snippet/max-image-preview/max-video-preview/unavailable_after value directives, optionally scoped to a crawler user-agent, or parse an existing header into the same shape.
+- Add `lookup_websocket_opcode`, `list_websocket_opcodes` tools: look up what a WebSocket frame opcode means per RFC 6455's 4-bit opcode space, or list every opcode.
+
 ## 0.65.0
 - Add `build_hsts_header`, `parse_hsts_header` tools: build a Strict-Transport-Security response header from a max-age plus includeSubDomains/preload flags, flagging combinations that won't qualify for browser HSTS preload lists, or parse an existing header into the same shape.
 - Add `align_markdown_tables` tool: reformat every GitHub-Flavored-Markdown pipe table in a document so each column's pipes line up visually, preserving left/center/right alignment markers and skipping tables inside fenced code blocks.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 223 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 228 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.
 
@@ -205,7 +205,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `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 |
 
-### API / Network (40 tools)
+### API / Network (44 tools)
 | Tool | Description |
 |------|-------------|
 | `decode_jwt` | Decode a JWT: header, payload, and expiry |
@@ -250,6 +250,10 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `parse_multipart_form_data` | Parse a raw multipart/form-data request body into its individual parts: field name, filename, headers, and decoded value, per RFC 7578 |
 | `build_hsts_header` | Build a Strict-Transport-Security response header from a max-age plus includeSubDomains/preload flags, flagging combinations that won't qualify for browser HSTS preload lists |
 | `parse_hsts_header` | Parse an existing Strict-Transport-Security header value into the same shape, with preload-list eligibility flagged |
+| `build_x_robots_tag` | Build an X-Robots-Tag response header from directives (noindex, nofollow, max-snippet, etc.), optionally scoped to a crawler user-agent |
+| `parse_x_robots_tag` | Parse an existing X-Robots-Tag header value into the same shape |
+| `lookup_websocket_opcode` | Look up what a WebSocket frame opcode means, per RFC 6455's 4-bit opcode space |
+| `list_websocket_opcodes` | List every WebSocket frame opcode (0x0-0xF) |
 
 ### Color (4 tools)
 | Tool | Description |
@@ -272,6 +276,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `lookup_mime` | Look up the MIME type for a file extension, or the extension(s) for a MIME type |
 | `parse_github_url` | Parse a github.com URL (repo, pull request, issue, commit, file, or release) into structured components |
 | `detect_redos` | Statically flag catastrophic-backtracking (ReDoS) risk in a regex: nested quantifiers, overlapping alternation, adjacent overlapping quantifiers |
+| `analyze_regex_groups` | Parse a regex's capture groups (numbered and named) and backreferences, flagging a backreference pointing at a group that doesn't exist or hasn't finished being defined yet |
 | `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 |
 | `validate_editorconfig` | Validate an .editorconfig file: root flag, glob sections, and structural mistakes against the EditorConfig spec |

package/dist/index.js

@@ -4318,6 +4318,123 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+function _analyzeRegexGroupsMcp(pattern) {
+  let valid = true;
+  let compileError;
+  try {
+    new RegExp(pattern);
+  } catch (e) {
+    valid = false;
+    compileError = e instanceof Error ? e.message : String(e);
+  }
+  const groups = [];
+  const openStack = [];
+  const backreferences = [];
+  const issues = [];
+  let groupCount = 0;
+  let inClass = false;
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i];
+    if (ch === "\\" && i + 1 < pattern.length) {
+      const next = pattern[i + 1];
+      if (!inClass && /[1-9]/.test(next)) {
+        let j = i + 1;
+        while (j < pattern.length && /[0-9]/.test(pattern[j])) j++;
+        const raw = pattern.slice(i, j);
+        const target = parseInt(pattern.slice(i + 1, j), 10);
+        backreferences.push({ raw, target, start: i, resolved: false, definedBeforeUse: false });
+        i = j - 1;
+        continue;
+      }
+      if (!inClass && next === "k" && pattern[i + 2] === "<") {
+        const close = pattern.indexOf(">", i + 3);
+        if (close !== -1) {
+          const name = pattern.slice(i + 3, close);
+          const raw = pattern.slice(i, close + 1);
+          backreferences.push({ raw, target: name, start: i, resolved: false, definedBeforeUse: false });
+          i = close;
+          continue;
+        }
+      }
+      i++;
+      continue;
+    }
+    if (ch === "[" && !inClass) {
+      inClass = true;
+      continue;
+    }
+    if (ch === "]" && inClass) {
+      inClass = false;
+      continue;
+    }
+    if (inClass) continue;
+    if (ch === "(") {
+      if (pattern[i + 1] === "?") {
+        const c2 = pattern[i + 2];
+        if (c2 === ":" || c2 === "=" || c2 === "!") {
+          openStack.push({ index: -1, name: null, start: i });
+          continue;
+        }
+        if (c2 === "<" && (pattern[i + 3] === "=" || pattern[i + 3] === "!")) {
+          openStack.push({ index: -1, name: null, start: i });
+          continue;
+        }
+        if (c2 === "<") {
+          const close = pattern.indexOf(">", i + 3);
+          const name = close !== -1 ? pattern.slice(i + 3, close) : null;
+          groupCount++;
+          openStack.push({ index: groupCount, name, start: i });
+          if (close !== -1) i = close;
+          continue;
+        }
+        openStack.push({ index: -1, name: null, start: i });
+        continue;
+      }
+      groupCount++;
+      openStack.push({ index: groupCount, name: null, start: i });
+      continue;
+    }
+    if (ch === ")") {
+      const open = openStack.pop();
+      if (open && open.index !== -1) {
+        groups.push({ index: open.index, name: open.name, start: open.start, end: i });
+      }
+      continue;
+    }
+  }
+  for (const open of openStack) {
+    if (open.index !== -1) groups.push({ index: open.index, name: open.name, start: open.start, end: -1 });
+  }
+  groups.sort((a, b) => a.index - b.index);
+  const byIndex = new Map(groups.map((g) => [g.index, g]));
+  const byName = new Map(groups.filter((g) => g.name !== null).map((g) => [g.name, g]));
+  for (const b of backreferences) {
+    const g = typeof b.target === "number" ? byIndex.get(b.target) : byName.get(b.target);
+    if (!g) {
+      b.resolved = false;
+      b.definedBeforeUse = false;
+      const label = typeof b.target === "number" ? `group ${b.target}` : `named group "${b.target}"`;
+      issues.push({ severity: "error", message: `Backreference ${b.raw} at position ${b.start} points to ${label}, which doesn't exist in this pattern.` });
+    } else {
+      b.resolved = true;
+      b.definedBeforeUse = g.end !== -1 && g.end < b.start;
+      if (!b.definedBeforeUse) {
+        const label = `group ${g.index}${g.name ? ` ("${g.name}")` : ""}`;
+        issues.push({ severity: "error", message: `Backreference ${b.raw} at position ${b.start} references ${label}, which hasn't finished being defined yet at that point in the pattern.` });
+      }
+    }
+  }
+  return { pattern, valid, ...compileError ? { compileError } : {}, groups, backreferences, issues };
+}
+server.tool(
+  "analyze_regex_groups",
+  "Parse a regex pattern's capture groups (numbered and named) and backreferences, and flag any backreference pointing at a group that doesn't exist or hasn't finished being defined yet at that point in the pattern (a forward reference or self-reference). Structural, non-AI check. Pass the pattern body only, no delimiters or flags.",
+  { pattern: z.string().describe("The regex pattern body to analyze, e.g. (?<year>\\d{4})-(?<month>\\d{2})\\k<year>") },
+  async ({ pattern }) => {
+    const result = _analyzeRegexGroupsMcp(pattern);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
 var _CC_NUM_FIELDS_MCP = ["maxAge", "sMaxAge", "staleWhileRevalidate", "staleIfError"];
 function _humanizeCacheSecondsMcp(s) {
   if (s === 0) return "0 seconds";
@@ -10221,6 +10338,182 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+var _X_ROBOTS_TAG_FLAGS_MCP = /* @__PURE__ */ new Set(["noindex", "nofollow", "noarchive", "nosnippet", "notranslate", "noimageindex", "none", "all", "indexifembedded"]);
+var _X_ROBOTS_TAG_FLAG_NOTES_MCP = {
+  noindex: "Do not show this page in search results.",
+  nofollow: "Do not follow, or pass ranking credit through, any links on this page.",
+  noarchive: "Do not show a cached copy of this page in search results.",
+  nosnippet: "Do not show a text snippet or video preview for this page in search results.",
+  notranslate: "Do not offer a translation of this page in search results.",
+  noimageindex: "Do not index images on this page.",
+  none: "Shorthand for noindex plus nofollow combined.",
+  all: "Explicitly allow indexing and following, the default with no directives at all.",
+  indexifembedded: "Allow indexing of this page's content when embedded via iframe in another page, even if this page also carries noindex. Only Google supports this directive."
+};
+var _X_ROBOTS_TAG_VALUED_DIRECTIVES_MCP = /* @__PURE__ */ new Set(["max-snippet", "max-image-preview", "max-video-preview", "unavailable_after"]);
+function _isXRobotsTagFlagMcp(value) {
+  return _X_ROBOTS_TAG_FLAGS_MCP.has(value);
+}
+function _buildXRobotsTagMcp(options) {
+  const { flags = [], maxSnippet, maxImagePreview, maxVideoPreview, unavailableAfter, userAgent } = options;
+  for (const flag of flags) {
+    if (!_isXRobotsTagFlagMcp(flag)) return { error: `Unknown directive "${flag}"` };
+  }
+  if (maxSnippet !== void 0 && (!Number.isInteger(maxSnippet) || maxSnippet < -1)) return { error: "maxSnippet must be an integer >= -1" };
+  if (maxVideoPreview !== void 0 && (!Number.isInteger(maxVideoPreview) || maxVideoPreview < -1)) return { error: "maxVideoPreview must be an integer >= -1" };
+  if (maxImagePreview !== void 0 && !["none", "standard", "large"].includes(maxImagePreview)) return { error: 'maxImagePreview must be one of "none", "standard", "large"' };
+  if (unavailableAfter !== void 0 && (unavailableAfter.trim() === "" || Number.isNaN(Date.parse(unavailableAfter)))) return { error: "unavailableAfter must be a valid, parseable date string" };
+  const uniqueFlags = Array.from(new Set(flags));
+  if (uniqueFlags.length === 0 && maxSnippet === void 0 && maxImagePreview === void 0 && maxVideoPreview === void 0 && unavailableAfter === void 0) {
+    return { error: "At least one directive is required" };
+  }
+  const warnings = [];
+  if (uniqueFlags.includes("none") && (uniqueFlags.includes("noindex") || uniqueFlags.includes("nofollow"))) {
+    warnings.push('"none" already implies noindex and nofollow; combining it with either is redundant.');
+  }
+  if (uniqueFlags.includes("all") && uniqueFlags.some((f) => f !== "all" && f !== "indexifembedded")) {
+    warnings.push('"all" explicitly allows indexing and following, which contradicts any restrictive directive combined with it.');
+  }
+  const directives = [...uniqueFlags];
+  const notes = uniqueFlags.map((f) => `${f}: ${_X_ROBOTS_TAG_FLAG_NOTES_MCP[f]}`);
+  if (maxSnippet !== void 0) {
+    directives.push(`max-snippet: ${maxSnippet}`);
+    notes.push(`max-snippet: ${maxSnippet === 0 ? "Show no text snippet at all." : maxSnippet === -1 ? "No limit on snippet length." : `Limit the text snippet to at most ${maxSnippet} characters.`}`);
+  }
+  if (maxImagePreview !== void 0) {
+    directives.push(`max-image-preview: ${maxImagePreview}`);
+    notes.push(`max-image-preview: Limit any image preview shown in search results to the "${maxImagePreview}" size.`);
+  }
+  if (maxVideoPreview !== void 0) {
+    directives.push(`max-video-preview: ${maxVideoPreview}`);
+    notes.push(`max-video-preview: ${maxVideoPreview === 0 ? "Show no video preview at all, a static image only." : maxVideoPreview === -1 ? "No limit on video preview length." : `Limit the video preview to at most ${maxVideoPreview} seconds.`}`);
+  }
+  if (unavailableAfter !== void 0) {
+    directives.push(`unavailable_after: ${unavailableAfter}`);
+    notes.push("unavailable_after: Stop showing this page in search results after this date.");
+  }
+  const directivesJoined = directives.join(", ");
+  const header = userAgent ? `${userAgent}: ${directivesJoined}` : directivesJoined;
+  return { header, headerName: "X-Robots-Tag", snippet: `X-Robots-Tag: ${header}`, directives, notes, warnings };
+}
+function _parseXRobotsTagMcp(raw) {
+  if (!raw || raw.trim() === "") return { error: "Input is empty" };
+  let withoutLabel = raw.trim().replace(/^x-robots-tag:\s*/i, "");
+  let userAgent;
+  const firstColon = withoutLabel.indexOf(":");
+  const firstComma = withoutLabel.indexOf(",");
+  if (firstColon !== -1 && (firstComma === -1 || firstColon < firstComma)) {
+    const candidate = withoutLabel.slice(0, firstColon).trim();
+    const candidateLower = candidate.toLowerCase();
+    if (candidate !== "" && !_X_ROBOTS_TAG_VALUED_DIRECTIVES_MCP.has(candidateLower) && !_isXRobotsTagFlagMcp(candidateLower)) {
+      userAgent = candidate;
+      withoutLabel = withoutLabel.slice(firstColon + 1).trim();
+    }
+  }
+  const tokens = withoutLabel.split(",").map((t) => t.trim()).filter((t) => t !== "");
+  if (tokens.length === 0) return { error: "No directives found" };
+  const flags = [];
+  let maxSnippet;
+  let maxImagePreview;
+  let maxVideoPreview;
+  let unavailableAfter;
+  for (const token of tokens) {
+    const eq = token.indexOf(":");
+    const name = (eq === -1 ? token : token.slice(0, eq)).trim().toLowerCase();
+    const value = eq === -1 ? "" : token.slice(eq + 1).trim();
+    if (eq === -1) {
+      if (!_isXRobotsTagFlagMcp(name)) return { error: `Unrecognized directive "${token}"` };
+      flags.push(name);
+      continue;
+    }
+    if (name === "max-snippet") {
+      const n = Number(value);
+      if (value === "" || !Number.isInteger(n) || n < -1) return { error: `max-snippet value "${value}" is not a valid integer >= -1` };
+      maxSnippet = n;
+    } else if (name === "max-image-preview") {
+      if (!["none", "standard", "large"].includes(value)) return { error: `max-image-preview value "${value}" must be one of "none", "standard", "large"` };
+      maxImagePreview = value;
+    } else if (name === "max-video-preview") {
+      const n = Number(value);
+      if (value === "" || !Number.isInteger(n) || n < -1) return { error: `max-video-preview value "${value}" is not a valid integer >= -1` };
+      maxVideoPreview = n;
+    } else if (name === "unavailable_after") {
+      if (value === "" || Number.isNaN(Date.parse(value))) return { error: `unavailable_after value "${value}" is not a valid, parseable date` };
+      unavailableAfter = value;
+    } else {
+      return { error: `Unrecognized directive "${token}"` };
+    }
+  }
+  return _buildXRobotsTagMcp({ flags, maxSnippet, maxImagePreview, maxVideoPreview, unavailableAfter, userAgent });
+}
+server.tool(
+  "build_x_robots_tag",
+  `Build an X-Robots-Tag response-header value from flag directives (noindex, nofollow, noarchive, nosnippet, notranslate, noimageindex, none, all, indexifembedded) plus optional max-snippet, max-image-preview, max-video-preview, and unavailable_after value directives, per Google's documented robots directive syntax. Optionally scope the header to a single crawler with userAgent (e.g. "googlebot").`,
+  {
+    flags: z.array(z.enum(["noindex", "nofollow", "noarchive", "nosnippet", "notranslate", "noimageindex", "none", "all", "indexifembedded"])).optional().describe("Flag directives to include"),
+    maxSnippet: z.number().int().min(-1).optional().describe("Max text snippet length in characters; 0 shows no snippet, -1 means no limit"),
+    maxImagePreview: z.enum(["none", "standard", "large"]).optional().describe("Max image preview size shown in search results"),
+    maxVideoPreview: z.number().int().min(-1).optional().describe("Max video preview length in seconds; 0 shows no preview, -1 means no limit"),
+    unavailableAfter: z.string().optional().describe("Stop showing this page in search results after this date/time"),
+    userAgent: z.string().optional().describe('Optional crawler name to scope the header to, e.g. "googlebot"')
+  },
+  async ({ flags, maxSnippet, maxImagePreview, maxVideoPreview, unavailableAfter, userAgent }) => {
+    const result = _buildXRobotsTagMcp({ flags, maxSnippet, maxImagePreview, maxVideoPreview, unavailableAfter, userAgent });
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+server.tool(
+  "parse_x_robots_tag",
+  'Parse an existing X-Robots-Tag header value (with or without a leading "X-Robots-Tag:" label, and with or without a leading crawler user-agent token) into the same shape build_x_robots_tag returns.',
+  {
+    header: z.string().min(1).describe("The X-Robots-Tag header value to parse")
+  },
+  async ({ header }) => {
+    const result = _parseXRobotsTagMcp(header);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+var _WELL_KNOWN_OPCODES_MCP = {
+  0: { name: "Continuation Frame", description: "Continues a fragmented message whose first frame was a text or binary frame sent with the FIN bit unset.", category: "data" },
+  1: { name: "Text Frame", description: "Carries a UTF-8 encoded text payload.", category: "data" },
+  2: { name: "Binary Frame", description: "Carries an arbitrary binary payload.", category: "data" },
+  8: { name: "Connection Close", description: "Initiates or acknowledges closing the connection, optionally carrying a 2-byte close code and a UTF-8 reason in its payload.", category: "control" },
+  9: { name: "Ping", description: "A control frame used to check the connection is alive; the receiver should reply with a Pong carrying the same application data.", category: "control" },
+  10: { name: "Pong", description: "Sent in response to a Ping (or unprompted as a heartbeat), carrying the same application data as the Ping it answers.", category: "control" }
+};
+var _RESERVED_NON_CONTROL_OPCODES_MCP = /* @__PURE__ */ new Set([3, 4, 5, 6, 7]);
+function _describeOpcodeMcp(opcode) {
+  const known = _WELL_KNOWN_OPCODES_MCP[opcode];
+  const hex = `0x${opcode.toString(16).toUpperCase()}`;
+  if (known) return { opcode, hex, name: known.name, description: known.description, category: known.category, isControl: known.category === "control" };
+  if (_RESERVED_NON_CONTROL_OPCODES_MCP.has(opcode)) {
+    return { opcode, hex, name: "Reserved (non-control)", description: "Reserved for future non-control frame types by a later revision of the WebSocket protocol. No meaning is defined yet; a compliant endpoint must fail the connection if it receives one.", category: "reserved-non-control", isControl: false };
+  }
+  return { opcode, hex, name: "Reserved (control)", description: "Reserved for future control frame types by a later revision of the WebSocket protocol. No meaning is defined yet; a compliant endpoint must fail the connection if it receives one.", category: "reserved-control", isControl: true };
+}
+server.tool(
+  "lookup_websocket_opcode",
+  "Look up what a WebSocket frame opcode means per RFC 6455: 0x0-0x2 are data frames (continuation, text, binary), 0x8-0xA are control frames (close, ping, pong), and the rest of the 4-bit opcode space is reserved for future protocol revisions.",
+  {
+    opcode: z.number().int().min(0).max(15).describe("The WebSocket frame opcode to look up (0-15 / 0x0-0xF)")
+  },
+  async ({ opcode }) => {
+    const result = _describeOpcodeMcp(opcode);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+server.tool(
+  "list_websocket_opcodes",
+  "List every WebSocket frame opcode (0x0-0xF), the full 4-bit opcode space defined by RFC 6455, in ascending order.",
+  {},
+  async () => {
+    const opcodes = [];
+    for (let opcode = 0; opcode <= 15; opcode++) opcodes.push(_describeOpcodeMcp(opcode));
+    return text(JSON.stringify({ opcodes }, null, 2));
+  }
+);
 var _DEBT_PAYOFF_MAX_MONTHS_MCP = 1200;
 function _simulateDebtPayoffMcp(debts, order, extraMonthlyPayment) {
   const round2 = (n) => Math.round(n * 100) / 100;

package/package.json

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