@utilix-tech/mcp 0.22.0 → 0.24.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.24.0
+- Add `calculate_margin_markup` tool: given exactly two of cost, price, margin percent, and markup percent, solve for the other two plus the gross profit.
+
+## 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.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 132 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 135 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.
 
@@ -142,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 |
@@ -150,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 (13 tools)
+### Units (15 tools)
 | Tool | Description |
 |------|-------------|
 | `convert_bytes` | Convert between B, KB, MB, GB, TB, KiB, MiB, GiB, TiB |
@@ -167,6 +168,8 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `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 |
+| `calculate_margin_markup` | Given any two of cost, price, margin percent, and markup percent, solve for the other two plus gross profit |
 
 ### API / Network (10 tools)
 | Tool | Description |

package/dist/index.js

@@ -3912,5 +3912,217 @@ server.tool(
     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 _MARGIN_FIELDS_MCP = ["cost", "price", "marginPercent", "markupPercent"];
+function _calculateMarginMarkupMcp(input) {
+  const provided = (v) => typeof v === "number" && Number.isFinite(v);
+  const given = _MARGIN_FIELDS_MCP.filter((f) => provided(input[f]));
+  if (given.length !== 2) {
+    return { error: `Provide exactly two of cost, price, marginPercent, markupPercent (got ${given.length})` };
+  }
+  const has = (f) => given.includes(f);
+  const cost0 = input.cost;
+  const price0 = input.price;
+  const margin0 = input.marginPercent;
+  const markup0 = input.markupPercent;
+  if (has("cost") && cost0 <= 0) return { error: "Cost must be greater than zero" };
+  if (has("price") && price0 <= 0) return { error: "Price must be greater than zero" };
+  if (has("marginPercent") && margin0 >= 100) return { error: "Margin percent must be below 100 (a 100% margin implies a zero cost)" };
+  if (has("markupPercent") && markup0 <= -100) return { error: "Markup percent must be greater than -100" };
+  let cost;
+  let price;
+  if (has("cost") && has("price")) {
+    cost = cost0;
+    price = price0;
+  } else if (has("cost") && has("marginPercent")) {
+    cost = cost0;
+    price = cost0 / (1 - margin0 / 100);
+  } else if (has("cost") && has("markupPercent")) {
+    cost = cost0;
+    price = cost0 * (1 + markup0 / 100);
+  } else if (has("price") && has("marginPercent")) {
+    price = price0;
+    cost = price0 * (1 - margin0 / 100);
+  } else if (has("price") && has("markupPercent")) {
+    price = price0;
+    cost = price0 / (1 + markup0 / 100);
+  } else {
+    return { error: "Margin and markup alone cannot be solved: also provide a cost or a price" };
+  }
+  if (!Number.isFinite(cost) || !Number.isFinite(price)) return { error: "Inputs produce a non-finite result" };
+  if (cost <= 0) return { error: "Those inputs imply a cost of zero or less" };
+  if (price <= 0) return { error: "Those inputs imply a price of zero or less" };
+  const round4 = (n) => Math.round(n * 1e4) / 1e4;
+  const profit = price - cost;
+  return {
+    cost: round4(cost),
+    price: round4(price),
+    profit: round4(profit),
+    marginPercent: round4(profit / price * 100),
+    markupPercent: round4(profit / cost * 100),
+    given,
+    solvedFor: _MARGIN_FIELDS_MCP.filter((f) => !given.includes(f))
+  };
+}
+server.tool(
+  "calculate_margin_markup",
+  "Solve a pricing triangle: given exactly two of cost, price, gross margin percent, and markup percent, derive the other two plus the gross profit. Margin is profit as a share of the selling price (profit / price) while markup is profit as a share of the cost (profit / cost), so a 20% margin equals a 25% markup. Margin plus markup alone cannot be solved, since neither carries an absolute amount.",
+  {
+    cost: z.number().optional().describe("Unit cost (what you pay). Provide exactly two of the four fields."),
+    price: z.number().optional().describe("Selling price (what the customer pays). Provide exactly two of the four fields."),
+    marginPercent: z.number().optional().describe("Gross margin as a percent of the selling price (must be below 100)"),
+    markupPercent: z.number().optional().describe("Markup as a percent of the cost (must be greater than -100)")
+  },
+  async ({ cost, price, marginPercent, markupPercent }) => {
+    const result = _calculateMarginMarkupMcp({ cost, price, marginPercent, markupPercent });
+    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.22.0",
+  "version": "0.24.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",