@utilix-tech/mcp 0.21.0 → 0.23.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.23.0
+- Add `convert_apr_apy` tool: convert between a nominal APR and effective APY for a given compounding frequency, in both directions.
+- Add `convert_iso8601_duration` tool: parse an ISO 8601 duration into components and total seconds, or format seconds into a canonical duration string.
+
+## 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.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 130 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 134 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 |
@@ -141,7 +142,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `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)
+### Time (6 tools)
 | Tool | Description |
 |------|-------------|
 | `unix_timestamp` | Convert a Unix timestamp to human-readable date |
@@ -149,8 +150,9 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `cron_next_runs` | Show the next N scheduled run times for a cron expression |
 | `date_diff` | Calculate the difference between two dates |
 | `convert_timezone` | Convert a date/time between timezones |
+| `convert_iso8601_duration` | Parse an ISO 8601 duration into components and total seconds, or format seconds into a duration string |
 
-### Units (12 tools)
+### Units (14 tools)
 | Tool | Description |
 |------|-------------|
 | `convert_bytes` | Convert between B, KB, MB, GB, TB, KiB, MiB, GiB, TiB |
@@ -165,6 +167,8 @@ 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 |
+| `convert_apr_apy` | Convert between a nominal APR and effective APY for a given compounding frequency, in both directions |
 
 ### API / Network (10 tools)
 | Tool | Description |

package/dist/index.js

@@ -3825,5 +3825,238 @@ server.tool(
     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));
+  }
+);
+function _convertAprApyMcp(rate, compoundsPerYear, direction) {
+  if (!Number.isFinite(rate) || rate < 0) return { error: "Rate must be zero or a positive number" };
+  if (!Number.isInteger(compoundsPerYear) || compoundsPerYear <= 0) return { error: "Compounding frequency must be a positive whole number of periods per year" };
+  if (direction !== "apr-to-apy" && direction !== "apy-to-apr") return { error: 'Direction must be "apr-to-apy" or "apy-to-apr"' };
+  const round6 = (n2) => Math.round(n2 * 1e6) / 1e6;
+  const round8 = (n2) => Math.round(n2 * 1e8) / 1e8;
+  const n = compoundsPerYear;
+  let aprDecimal;
+  let apyDecimal;
+  if (direction === "apr-to-apy") {
+    aprDecimal = rate / 100;
+    apyDecimal = Math.pow(1 + aprDecimal / n, n) - 1;
+  } else {
+    apyDecimal = rate / 100;
+    aprDecimal = n * (Math.pow(1 + apyDecimal, 1 / n) - 1);
+  }
+  const apr = round6(aprDecimal * 100);
+  const apy = round6(apyDecimal * 100);
+  return {
+    direction,
+    compoundsPerYear: n,
+    apr,
+    apy,
+    aprDecimal: round8(aprDecimal),
+    apyDecimal: round8(apyDecimal),
+    difference: round6(apy - apr)
+  };
+}
+server.tool(
+  "convert_apr_apy",
+  'Convert between a nominal annual rate (APR) and the effective annual yield (APY) for a given compounding frequency. With direction "apr-to-apy" the input is the nominal APR and the effective APY is computed as (1 + apr/n)^n - 1; with "apy-to-apr" the input is the effective APY and the APR is recovered as n * ((1 + apy)^(1/n) - 1). Both rates are percentages.',
+  {
+    rate: z.number().describe('The known rate as a percent: the nominal APR when direction is "apr-to-apy", or the effective APY when direction is "apy-to-apr"'),
+    compoundsPerYear: z.number().int().describe("Compounding periods per year (12 = monthly, 365 = daily)"),
+    direction: z.enum(["apr-to-apy", "apy-to-apr"]).describe("Which rate the input represents and which to compute")
+  },
+  async ({ rate, compoundsPerYear, direction }) => {
+    const result = _convertAprApyMcp(rate, compoundsPerYear, direction);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+var _DURATION_SECONDS_PER_YEAR_MCP = 365 * 86400;
+var _DURATION_SECONDS_PER_MONTH_MCP = 30 * 86400;
+var _DURATION_RE_MCP = /^P(?:(\d+)Y)?(?:(\d+)M)?(?:(\d+)W)?(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/;
+function _humanizeDurationPartsMcp(parts) {
+  const pieces = [];
+  for (const [value, label] of parts) {
+    if (value === 0) continue;
+    pieces.push(`${value} ${label}${value === 1 ? "" : "s"}`);
+  }
+  return pieces.length > 0 ? pieces.join(", ") : "0 seconds";
+}
+function _parseIso8601DurationMcp(input) {
+  const trimmed = input.trim();
+  if (trimmed.length === 0) return { error: "Duration is empty" };
+  const match = trimmed.match(_DURATION_RE_MCP);
+  if (!match) return { error: 'Not a valid ISO 8601 duration (expected a form like "P3DT4H30M")' };
+  const years = match[1] ? parseInt(match[1], 10) : 0;
+  const months = match[2] ? parseInt(match[2], 10) : 0;
+  const weeks = match[3] ? parseInt(match[3], 10) : 0;
+  const days = match[4] ? parseInt(match[4], 10) : 0;
+  const hours = match[5] ? parseInt(match[5], 10) : 0;
+  const minutes = match[6] ? parseInt(match[6], 10) : 0;
+  const seconds = match[7] ? parseFloat(match[7]) : 0;
+  if (years + months + weeks + days + hours + minutes + seconds === 0) {
+    return { error: 'Duration has no components (a bare "P" or "PT" is not valid)' };
+  }
+  const approximate = years > 0 || months > 0;
+  const totalSeconds = years * _DURATION_SECONDS_PER_YEAR_MCP + months * _DURATION_SECONDS_PER_MONTH_MCP + weeks * 7 * 86400 + days * 86400 + hours * 3600 + minutes * 60 + seconds;
+  return {
+    input: trimmed,
+    years,
+    months,
+    weeks,
+    days,
+    hours,
+    minutes,
+    seconds,
+    totalSeconds: Math.round(totalSeconds * 1e6) / 1e6,
+    approximate,
+    human: _humanizeDurationPartsMcp([
+      [years, "year"],
+      [months, "month"],
+      [weeks, "week"],
+      [days, "day"],
+      [hours, "hour"],
+      [minutes, "minute"],
+      [seconds, "second"]
+    ])
+  };
+}
+function _formatIso8601DurationMcp(seconds) {
+  if (!Number.isFinite(seconds) || seconds < 0) return { error: "Seconds must be zero or a positive number" };
+  const totalDays = Math.floor(seconds / 86400);
+  let rem = seconds - totalDays * 86400;
+  const hours = Math.floor(rem / 3600);
+  rem -= hours * 3600;
+  const minutes = Math.floor(rem / 60);
+  let secs = rem - minutes * 60;
+  secs = Math.round(secs * 1e6) / 1e6;
+  let iso = "P";
+  if (totalDays > 0) iso += `${totalDays}D`;
+  const hasTime = hours > 0 || minutes > 0 || secs > 0;
+  if (hasTime) {
+    iso += "T";
+    if (hours > 0) iso += `${hours}H`;
+    if (minutes > 0) iso += `${minutes}M`;
+    if (secs > 0) iso += `${secs}S`;
+  }
+  if (iso === "P") iso = "PT0S";
+  return {
+    seconds,
+    iso,
+    days: totalDays,
+    hours,
+    minutes,
+    human: _humanizeDurationPartsMcp([
+      [totalDays, "day"],
+      [hours, "hour"],
+      [minutes, "minute"],
+      [secs, "second"]
+    ])
+  };
+}
+server.tool(
+  "convert_iso8601_duration",
+  'Parse or format an ISO 8601 duration. With mode "parse", break a duration string like "P3DT4H30M" into its components and a total number of seconds (years and months use nominal 365-day / 30-day conversions and set an "approximate" flag). With mode "format", render a non-negative number of seconds into a canonical duration string using days/hours/minutes/seconds.',
+  {
+    mode: z.enum(["parse", "format"]).describe("parse an ISO string, or format a number of seconds"),
+    input: z.string().optional().describe('The ISO 8601 duration to parse (required when mode is "parse")'),
+    seconds: z.number().optional().describe('The number of seconds to format (required when mode is "format")')
+  },
+  async ({ mode, input, seconds }) => {
+    let result;
+    if (mode === "parse") {
+      if (typeof input !== "string") return errText({ error: 'input is required when mode is "parse"' });
+      result = _parseIso8601DurationMcp(input);
+    } else {
+      if (typeof seconds !== "number") return errText({ error: 'seconds is required when mode is "format"' });
+      result = _formatIso8601DurationMcp(seconds);
+    }
+    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.21.0",
+  "version": "0.23.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",