@utilix-tech/mcp 0.20.0 → 0.22.0

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 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.22.0
+- Add `calculate_percentage_change` tool: percentage change between two numbers, with absolute change, direction, and multiplier.
+- Add `resolve_json_pointer` tool: resolve an RFC 6901 JSON Pointer against a document, with ~0/~1 escaping and not-found reasons.
+
+## 0.21.0
+- Add `build_cache_control` tool: build and explain a `Cache-Control` response header from directives.
+- Add `detect_filler_words` tool: scan text for filler words, hedge phrases, and clichés.
+
 ## 0.20.0
 - Add `detect_redos` tool: statically analyze a regex for ReDoS (catastrophic-backtracking) risk.
 

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 128 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 132 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.
 
@@ -75,7 +75,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 
 ## Tools
 
-### JSON (13 tools)
+### JSON (14 tools)
 | Tool | Description |
 |------|-------------|
 | `format_json` | Pretty-print and validate a JSON string |
@@ -84,6 +84,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `json_to_csv` | Convert a JSON array of objects to CSV |
 | `csv_to_json` | Convert CSV text to a JSON array |
 | `jsonpath` | Evaluate a JSONPath expression |
+| `resolve_json_pointer` | Resolve an RFC 6901 JSON Pointer against a JSON document |
 | `validate_json` | Validate JSON against a JSON Schema |
 | `yaml_to_json` | Convert YAML to JSON |
 | `json_to_yaml` | Convert JSON to YAML |
@@ -125,7 +126,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `generate_qr` | Generate a QR code as an SVG string |
 | `generate_random_data` | Generate random mock data: names, emails, UUIDs, IPs, etc. |
 
-### Text (11 tools)
+### Text (12 tools)
 | Tool | Description |
 |------|-------------|
 | `convert_case` | Convert text case: camelCase, snake_case, PascalCase, etc. |
@@ -139,6 +140,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `line_operations` | Sort, deduplicate, reverse, shuffle, trim, or number lines |
 | `detect_passive_voice` | Flag sentences written in passive voice, e.g. "was written", "were approved by the team" |
 | `score_readability` | Score text with Flesch Reading Ease, Flesch-Kincaid Grade Level, and Gunning Fog Index |
+| `detect_filler_words` | Scan text for filler words, hedge phrases, and clichés with per-phrase counts and a density score |
 
 ### Time (5 tools)
 | Tool | Description |
@@ -149,7 +151,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `date_diff` | Calculate the difference between two dates |
 | `convert_timezone` | Convert a date/time between timezones |
 
-### Units (12 tools)
+### Units (13 tools)
 | Tool | Description |
 |------|-------------|
 | `convert_bytes` | Convert between B, KB, MB, GB, TB, KiB, MiB, GiB, TiB |
@@ -164,8 +166,9 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `calculate_tip_split` | Compute a tip on a bill amount and split the bill, tip, and total evenly across N people |
 | `calculate_simple_interest` | Compute simple (non-compounding) interest as principal x rate x time, plus the total payoff |
 | `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 |
 
-### API / Network (9 tools)
+### API / Network (10 tools)
 | Tool | Description |
 |------|-------------|
 | `decode_jwt` | Decode a JWT: header, payload, and expiry |
@@ -177,6 +180,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `validate_sitemap` | Validate a sitemap.xml or sitemap index against the sitemaps.org protocol |
 | `validate_robots_txt` | Validate a robots.txt file: User-agent groups, rules, and directive syntax |
 | `parse_user_agent` | Parse a browser User-Agent string into browser, engine, OS, and device type |
+| `build_cache_control` | Build and explain an HTTP Cache-Control response header from directives (max-age, no-store, immutable, etc.) |
 
 ### Color (4 tools)
 | Tool | Description |

package/dist/index.js

@@ -3714,5 +3714,203 @@ server.tool(
     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";
+  const units = [[86400, "day"], [3600, "hour"], [60, "minute"], [1, "second"]];
+  const parts = [];
+  let rem = s;
+  for (const [size, label] of units) {
+    if (rem >= size) {
+      const n = Math.floor(rem / size);
+      rem -= n * size;
+      parts.push(`${n} ${label}${n === 1 ? "" : "s"}`);
+    }
+  }
+  return parts.slice(0, 2).join(" ");
+}
+function _buildCacheControlMcp(options) {
+  const nums = { maxAge: null, sMaxAge: null, staleWhileRevalidate: null, staleIfError: null };
+  for (const field of _CC_NUM_FIELDS_MCP) {
+    const v = options[field];
+    if (v === void 0 || v === null) continue;
+    if (typeof v !== "number" || !Number.isFinite(v) || !Number.isInteger(v) || v < 0) {
+      return { error: `${field} must be a non-negative integer number of seconds` };
+    }
+    nums[field] = v;
+  }
+  const d = [];
+  const warnings = [];
+  if (options.visibility === "public") d.push({ name: "public", value: null, explanation: "Any cache, including shared caches and CDNs, may store this response." });
+  if (options.visibility === "private") d.push({ name: "private", value: null, explanation: "Only the user's browser may cache this response; shared caches and CDNs must not." });
+  if (options.noCache) d.push({ name: "no-cache", value: null, explanation: "A cache may store the response but must revalidate it with the origin before every reuse." });
+  if (options.noStore) d.push({ name: "no-store", value: null, explanation: "No cache may store any part of this request or response." });
+  if (nums.maxAge !== null) d.push({ name: "max-age", value: String(nums.maxAge), explanation: `Considered fresh for ${_humanizeCacheSecondsMcp(nums.maxAge)} (${nums.maxAge}s), after which it becomes stale.` });
+  if (nums.sMaxAge !== null) d.push({ name: "s-maxage", value: String(nums.sMaxAge), explanation: `For shared caches (CDNs, proxies) it is fresh for ${_humanizeCacheSecondsMcp(nums.sMaxAge)} (${nums.sMaxAge}s), overriding max-age there.` });
+  if (options.mustRevalidate) d.push({ name: "must-revalidate", value: null, explanation: "Once stale, a cache must revalidate with the origin and never serve the stale copy." });
+  if (options.proxyRevalidate) d.push({ name: "proxy-revalidate", value: null, explanation: "Like must-revalidate, but the requirement applies only to shared caches." });
+  if (options.immutable) d.push({ name: "immutable", value: null, explanation: "The body will not change while fresh, so browsers should not revalidate it on reload." });
+  if (options.noTransform) d.push({ name: "no-transform", value: null, explanation: "Intermediaries must not modify the response body (for example, recompressing images)." });
+  if (nums.staleWhileRevalidate !== null) d.push({ name: "stale-while-revalidate", value: String(nums.staleWhileRevalidate), explanation: `A cache may serve the stale response for up to ${_humanizeCacheSecondsMcp(nums.staleWhileRevalidate)} (${nums.staleWhileRevalidate}s) while it revalidates in the background.` });
+  if (nums.staleIfError !== null) d.push({ name: "stale-if-error", value: String(nums.staleIfError), explanation: `A cache may serve the stale response for up to ${_humanizeCacheSecondsMcp(nums.staleIfError)} (${nums.staleIfError}s) if the origin returns an error.` });
+  if (options.mustUnderstand) d.push({ name: "must-understand", value: null, explanation: "A cache should store the response only if it understands the caching requirements of the response's status code." });
+  if (options.noStore && d.length > 1) warnings.push("no-store means nothing is cached, so the other directives have no effect.");
+  if (options.noCache && nums.maxAge !== null) warnings.push("no-cache forces revalidation on every use, so max-age has little practical effect alongside it.");
+  if (options.immutable && nums.maxAge === null) warnings.push("immutable only applies while the response is fresh \u2014 add a max-age so it has a freshness lifetime.");
+  if (d.length === 0) warnings.push("No directives set \u2014 an empty Cache-Control header has no effect.");
+  const header = d.map((x) => x.value === null ? x.name : `${x.name}=${x.value}`).join(", ");
+  return { header, headerName: "Cache-Control", snippet: `Cache-Control: ${header}`, directives: d, warnings };
+}
+server.tool(
+  "build_cache_control",
+  "Build an HTTP Cache-Control response-header value from a set of directives (public/private, no-cache, no-store, max-age, s-maxage, must-revalidate, immutable, stale-while-revalidate, etc.), with a plain-English explanation of each directive and warnings for combinations that cancel each other out. Pure string assembly, not validated against a live origin.",
+  {
+    visibility: z.enum(["public", "private"]).optional().describe("public (any cache) or private (browser only)"),
+    noCache: z.boolean().optional(),
+    noStore: z.boolean().optional(),
+    noTransform: z.boolean().optional(),
+    mustRevalidate: z.boolean().optional(),
+    proxyRevalidate: z.boolean().optional(),
+    immutable: z.boolean().optional(),
+    mustUnderstand: z.boolean().optional(),
+    maxAge: z.number().int().nonnegative().optional().describe("Freshness lifetime in seconds"),
+    sMaxAge: z.number().int().nonnegative().optional().describe("Freshness lifetime for shared caches, in seconds"),
+    staleWhileRevalidate: z.number().int().nonnegative().optional(),
+    staleIfError: z.number().int().nonnegative().optional()
+  },
+  async (opts) => {
+    const result = _buildCacheControlMcp(opts);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+var _FILLER_WORDS_MCP = ["very", "really", "just", "actually", "basically", "literally", "simply", "totally", "definitely", "certainly", "essentially", "absolutely", "completely", "extremely", "truly", "honestly", "seriously", "obviously", "clearly", "quite", "rather", "somewhat", "fairly", "virtually"];
+var _HEDGE_PHRASES_MCP = ["maybe", "perhaps", "probably", "possibly", "arguably", "kind of", "sort of", "a bit", "a little", "more or less", "in my opinion", "i think", "i believe", "to some extent"];
+var _CLICHE_PHRASES_MCP = ["at the end of the day", "think outside the box", "low-hanging fruit", "move the needle", "circle back", "touch base", "on the same page", "hit the ground running", "paradigm shift", "win-win", "game changer", "best of both worlds", "only time will tell", "back to the drawing board", "the tip of the iceberg", "a perfect storm", "needle in a haystack", "raise the bar", "push the envelope", "the elephant in the room", "boil the ocean", "when it rains it pours"];
+var _FILLER_DICTIONARY_MCP = [
+  ..._FILLER_WORDS_MCP.map((phrase) => ({ phrase, category: "filler" })),
+  ..._HEDGE_PHRASES_MCP.map((phrase) => ({ phrase, category: "hedge" })),
+  ..._CLICHE_PHRASES_MCP.map((phrase) => ({ phrase, category: "cliche" }))
+];
+function _fillerRegexMcp(phrase) {
+  const tokens = phrase.split(/\s+/).map((t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"));
+  return new RegExp("\\b" + tokens.join("\\s+") + "\\b", "gi");
+}
+function _detectFillerWordsMcp(input) {
+  const totalWords = (input.match(/[A-Za-z0-9']+/g) ?? []).length;
+  const matches = [];
+  for (const entry of _FILLER_DICTIONARY_MCP) {
+    const re = _fillerRegexMcp(entry.phrase);
+    const indices = [];
+    let m;
+    while ((m = re.exec(input)) !== null) {
+      indices.push(m.index);
+      if (m.index === re.lastIndex) re.lastIndex++;
+    }
+    if (indices.length > 0) matches.push({ phrase: entry.phrase, category: entry.category, count: indices.length, indices });
+  }
+  matches.sort((a, b) => b.count - a.count || a.category.localeCompare(b.category) || a.phrase.localeCompare(b.phrase));
+  const fillerCount = matches.filter((x) => x.category === "filler").reduce((s, x) => s + x.count, 0);
+  const hedgeCount = matches.filter((x) => x.category === "hedge").reduce((s, x) => s + x.count, 0);
+  const clicheCount = matches.filter((x) => x.category === "cliche").reduce((s, x) => s + x.count, 0);
+  const totalMatches = fillerCount + hedgeCount + clicheCount;
+  const density = totalWords > 0 ? Math.round(totalMatches / totalWords * 1e3) / 10 : 0;
+  return { totalWords, totalMatches, fillerCount, hedgeCount, clicheCount, density, matches };
+}
+server.tool(
+  "detect_filler_words",
+  "Scan prose for filler words (very, just, really), hedge phrases (kind of, I think), and clich\xE9s (at the end of the day, circle back), returning each matched phrase with its category, occurrence count, and character offsets, plus an overall density. Dictionary-based heuristic: a flagged word is a candidate to reconsider, not always wrong in context.",
+  { text: z.string().describe("The prose to scan for filler words and clich\xE9s") },
+  async ({ text: input }) => {
+    return text(JSON.stringify(_detectFillerWordsMcp(input), null, 2));
+  }
+);
+function _calculatePercentageChangeMcp(oldValue, newValue) {
+  if (!Number.isFinite(oldValue)) return { error: "Original value must be a finite number" };
+  if (!Number.isFinite(newValue)) return { error: "New value must be a finite number" };
+  if (oldValue === 0 && newValue !== 0) return { error: "Percentage change from zero is undefined (division by zero); use a nonzero original value" };
+  const round4 = (n) => Math.round(n * 1e4) / 1e4;
+  const absoluteChange = newValue - oldValue;
+  const percentChange = oldValue === 0 ? 0 : absoluteChange / Math.abs(oldValue) * 100;
+  const multiplier = oldValue === 0 ? 1 : newValue / oldValue;
+  let direction;
+  if (absoluteChange > 0) direction = "increase";
+  else if (absoluteChange < 0) direction = "decrease";
+  else direction = "no change";
+  return {
+    oldValue,
+    newValue,
+    absoluteChange: round4(absoluteChange),
+    percentChange: round4(percentChange),
+    direction,
+    multiplier: round4(multiplier)
+  };
+}
+server.tool(
+  "calculate_percentage_change",
+  "Compute the percentage change from an original value to a new value as ((new - old) / |old|) * 100, plus the absolute difference, the direction (increase/decrease/no change), and the multiplier (new / old). The original value cannot be zero unless the new value is also zero.",
+  {
+    oldValue: z.number().describe("The original / starting value"),
+    newValue: z.number().describe("The new / ending value")
+  },
+  async ({ oldValue, newValue }) => {
+    const result = _calculatePercentageChangeMcp(oldValue, newValue);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+function _unescapePointerTokenMcp(token) {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function _resolveJsonPointerMcp(json, pointer) {
+  let parsed;
+  try {
+    parsed = JSON.parse(json);
+  } catch {
+    return { pointer, found: false, tokens: [], error: "Invalid JSON input" };
+  }
+  let ptr = pointer;
+  if (ptr.startsWith("#")) {
+    ptr = ptr.slice(1);
+    try {
+      ptr = decodeURIComponent(ptr);
+    } catch {
+      return { pointer, found: false, tokens: [], error: "Invalid percent-encoding in URI-fragment pointer" };
+    }
+  }
+  if (ptr === "") return { pointer, found: true, value: parsed, tokens: [] };
+  if (!ptr.startsWith("/")) return { pointer, found: false, tokens: [], error: "Pointer must be empty or start with '/' (RFC 6901)" };
+  const tokens = ptr.split("/").slice(1).map(_unescapePointerTokenMcp);
+  let current = parsed;
+  for (const token of tokens) {
+    if (Array.isArray(current)) {
+      if (token === "-") return { pointer, found: false, tokens, failedAt: token, reason: '"-" refers to the nonexistent element after the end of the array' };
+      if (!/^(0|[1-9][0-9]*)$/.test(token)) return { pointer, found: false, tokens, failedAt: token, reason: `"${token}" is not a valid array index` };
+      const idx = Number(token);
+      if (idx >= current.length) return { pointer, found: false, tokens, failedAt: token, reason: `array index ${idx} is out of bounds (length ${current.length})` };
+      current = current[idx];
+    } else if (current !== null && typeof current === "object") {
+      const obj = current;
+      if (!Object.prototype.hasOwnProperty.call(obj, token)) return { pointer, found: false, tokens, failedAt: token, reason: `key "${token}" not found` };
+      current = obj[token];
+    } else {
+      return { pointer, found: false, tokens, failedAt: token, reason: `cannot descend into ${current === null ? "null" : typeof current} at "${token}"` };
+    }
+  }
+  return { pointer, found: true, value: current, tokens };
+}
+server.tool(
+  "resolve_json_pointer",
+  'Resolve an RFC 6901 JSON Pointer against a JSON document, in both the plain form ("" for the whole document, or "/foo/0") and the URI-fragment form ("#/foo/0"). Handles ~1 -> / and ~0 -> ~ escaping, and distinguishes an invalid document / malformed pointer from a syntactically valid pointer whose target is simply absent.',
+  {
+    json: z.string().describe("The JSON document to resolve against"),
+    pointer: z.string().describe("The RFC 6901 JSON Pointer, e.g. /users/0/name")
+  },
+  async ({ json, pointer }) => {
+    const result = _resolveJsonPointerMcp(json, pointer);
+    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.20.0",
+  "version": "0.22.0",
   "description": "MCP server exposing 125 Utilix developer tools to Claude, Cursor, VS Code Copilot, and any MCP-compatible AI assistant.",
   "author": "Utilix <hello@utilix.tech>",
   "license": "MIT",