@utilix-tech/mcp 0.62.0 → 0.63.0

package/CHANGELOG.md

@@ -2,6 +2,10 @@
 
 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.63.0
+- Add `plan_debt_payoff` tool: 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.
+- Add `audit_dependency_ranges` tool: classify each dependency's version specifier range type and flag wildcard ranges, the "latest" tag, git/URL/file/link dependencies, and packages listed with conflicting or redundant ranges across sections.
+
 ## 0.62.0
 - Add `build_priority_header`, `parse_priority_header` tools: build an HTTP Priority request/response-header value from an urgency (0-7) and/or an incremental flag per RFC 9218, or parse an existing one into the same shape.
 - Add `lookup_close_code`, `list_close_codes` tools: look up what a WebSocket close code means per RFC 6455 and the IANA reserved ranges, or list every well-known code.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 216 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 218 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.
 
@@ -162,7 +162,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `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 (37 tools)
+### Units (38 tools)
 | Tool | Description |
 |------|-------------|
 | `convert_bytes` | Convert between B, KB, MB, GB, TB, KiB, MiB, GiB, TiB |
@@ -202,6 +202,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `calculate_blended_loan_rate` | Compute the single weighted-average interest rate across a list of loan balances, weighted by each loan's share of the combined balance, plus combined monthly and annual interest accrual |
 | `calculate_freelancer_rate` | Solve for the minimum hourly rate a freelancer must charge to hit a target annual income, given billable hours, weeks worked, overhead, and a profit margin |
 | `calculate_extra_payment_payoff` | Compute how much faster a fixed-rate loan pays off, and how much interest is saved, when a fixed extra amount is added to every monthly payment |
+| `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 |
 
 ### API / Network (37 tools)
 | Tool | Description |
@@ -254,7 +255,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `color_palette` | Generate a color palette from a base color |
 | `color_shades` | Generate shades or tints from a base color |
 
-### Code (15 tools)
+### Code (16 tools)
 | Tool | Description |
 |------|-------------|
 | `format_sql` | Format a SQL query with proper indentation |
@@ -272,6 +273,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `validate_editorconfig` | Validate an .editorconfig file: root flag, glob sections, and structural mistakes against the EditorConfig spec |
 | `validate_tsconfig` | Validate a tsconfig.json file (JSONC-aware): unknown keys, unknown compilerOptions, and type mismatches |
 | `validate_package_exports` | Validate a package.json "exports" field: dual-package (ESM/CJS) misconfigurations like a missing default fallback or a require/import pointing at the wrong extension |
+| `audit_dependency_ranges` | Classify each package.json dependency's version range type and flag wildcard ranges, the "latest" tag, git/URL/file/link dependencies, and packages listed with conflicting or redundant ranges across sections |
 
 ### Data (14 tools)
 | Tool | Description |

package/dist/index.js

@@ -9968,5 +9968,224 @@ server.tool(
     return text(JSON.stringify({ codes }, null, 2));
   }
 );
+var _DEBT_PAYOFF_MAX_MONTHS_MCP = 1200;
+function _simulateDebtPayoffMcp(debts, order, extraMonthlyPayment) {
+  const round2 = (n) => Math.round(n * 100) / 100;
+  const balances = debts.map((d) => d.balance);
+  const totalMinPayment = debts.reduce((sum, d) => sum + d.minPayment, 0);
+  const totalBudget = totalMinPayment + extraMonthlyPayment;
+  let totalInterestPaid = 0;
+  let totalPaid = 0;
+  const schedule = [];
+  let month = 0;
+  while (balances.some((b) => b > 5e-3) && month < _DEBT_PAYOFF_MAX_MONTHS_MCP) {
+    month++;
+    for (let i = 0; i < balances.length; i++) {
+      if (balances[i] <= 0) continue;
+      const interest = balances[i] * debts[i].ratePercent / 100 / 12;
+      balances[i] += interest;
+      totalInterestPaid += interest;
+    }
+    let remainingBudget = totalBudget;
+    for (let i = 0; i < balances.length; i++) {
+      if (balances[i] <= 0) continue;
+      const pay = Math.min(balances[i], debts[i].minPayment);
+      balances[i] -= pay;
+      remainingBudget -= pay;
+      totalPaid += pay;
+    }
+    for (const i of order) {
+      if (remainingBudget <= 0) break;
+      if (balances[i] <= 0) continue;
+      const pay = Math.min(balances[i], remainingBudget);
+      balances[i] -= pay;
+      remainingBudget -= pay;
+      totalPaid += pay;
+    }
+    for (const i of order) {
+      if (balances[i] <= 5e-3 && !schedule.some((s) => s.label === debts[i].label)) {
+        schedule.push({ label: debts[i].label, monthPaidOff: month });
+      }
+    }
+  }
+  if (balances.some((b) => b > 5e-3)) return null;
+  return {
+    order: order.map((i) => debts[i].label),
+    monthsToPayoff: month,
+    totalInterestPaid: round2(totalInterestPaid),
+    totalPaid: round2(totalPaid),
+    schedule
+  };
+}
+function _planDebtPayoffMcp(debtsInput, extraMonthlyPayment) {
+  if (!Array.isArray(debtsInput) || debtsInput.length === 0) {
+    return { error: "debts must be a non-empty array" };
+  }
+  if (typeof extraMonthlyPayment !== "number" || !Number.isFinite(extraMonthlyPayment) || extraMonthlyPayment < 0) {
+    return { error: "extraMonthlyPayment must be a finite, non-negative number" };
+  }
+  const normalized = [];
+  for (let i = 0; i < debtsInput.length; i++) {
+    const d = debtsInput[i];
+    if (typeof d.balance !== "number" || !Number.isFinite(d.balance) || d.balance <= 0) {
+      return { error: `debt ${i + 1}: balance must be a finite number greater than zero` };
+    }
+    if (typeof d.ratePercent !== "number" || !Number.isFinite(d.ratePercent) || d.ratePercent < 0) {
+      return { error: `debt ${i + 1}: ratePercent must be a finite, non-negative number` };
+    }
+    if (typeof d.minPayment !== "number" || !Number.isFinite(d.minPayment) || d.minPayment <= 0) {
+      return { error: `debt ${i + 1}: minPayment must be a finite number greater than zero` };
+    }
+    normalized.push({ label: d.label?.trim() || `Debt ${i + 1}`, balance: d.balance, ratePercent: d.ratePercent, minPayment: d.minPayment });
+  }
+  const snowballOrder = normalized.map((_, i) => i).sort((a, b) => normalized[a].balance - normalized[b].balance);
+  const avalancheOrder = normalized.map((_, i) => i).sort((a, b) => normalized[b].ratePercent - normalized[a].ratePercent);
+  const snowball = _simulateDebtPayoffMcp(normalized, snowballOrder, extraMonthlyPayment);
+  const avalanche = _simulateDebtPayoffMcp(normalized, avalancheOrder, extraMonthlyPayment);
+  if (!snowball || !avalanche) {
+    return { error: `debts cannot be paid off within ${_DEBT_PAYOFF_MAX_MONTHS_MCP} months at this payment level; increase a minimum payment or the extra monthly payment` };
+  }
+  const round2 = (n) => Math.round(n * 100) / 100;
+  const snowballMonths = snowball.monthsToPayoff;
+  const avalancheMonths = avalanche.monthsToPayoff;
+  const snowballInterest = snowball.totalInterestPaid;
+  const avalancheInterest = avalanche.totalInterestPaid;
+  const fasterStrategy = snowballMonths === avalancheMonths ? "tie" : snowballMonths < avalancheMonths ? "snowball" : "avalanche";
+  const cheaperStrategy = snowballInterest === avalancheInterest ? "tie" : snowballInterest < avalancheInterest ? "snowball" : "avalanche";
+  return {
+    debts: normalized,
+    totalMonthlyBudget: round2(normalized.reduce((sum, d) => sum + d.minPayment, 0) + extraMonthlyPayment),
+    extraMonthlyPayment,
+    snowball,
+    avalanche,
+    comparison: {
+      fasterStrategy,
+      monthsDifference: Math.abs(snowballMonths - avalancheMonths),
+      cheaperStrategy,
+      interestDifference: round2(Math.abs(snowballInterest - avalancheInterest))
+    }
+  };
+}
+server.tool(
+  "plan_debt_payoff",
+  "Simulate paying off a list of debts under both the snowball strategy (smallest balance first) and the avalanche strategy (highest interest rate first), given a fixed extra monthly payment stacked on top of everyone's minimum payment, and compare months to payoff and total interest between the two.",
+  {
+    debts: z.array(z.object({
+      label: z.string().optional().describe("Optional debt label"),
+      balance: z.number().positive().describe("Current balance owed"),
+      ratePercent: z.number().min(0).describe("Annual interest rate for this debt, as a percent"),
+      minPayment: z.number().positive().describe("Minimum monthly payment required on this debt")
+    })).min(1).describe("A non-empty list of debts"),
+    extraMonthlyPayment: z.number().min(0).optional().describe("Extra amount paid each month on top of every debt's minimum payment, default 0")
+  },
+  async ({ debts, extraMonthlyPayment }) => {
+    const result = _planDebtPayoffMcp(debts, extraMonthlyPayment ?? 0);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+var _DEPENDENCY_SECTIONS_MCP = ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"];
+var _EXACT_SEMVER_RE_MCP = /^\d+\.\d+\.\d+(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$/;
+function _classifyDependencyRangeMcp(version) {
+  const v = version.trim();
+  if (v === "" || v === "*" || v.toLowerCase() === "x") return "wildcard";
+  if (v.startsWith("workspace:")) return "workspace";
+  if (v.startsWith("file:")) return "file";
+  if (v.startsWith("link:")) return "link";
+  if (v.startsWith("http://") || v.startsWith("https://")) return "url";
+  if (v.startsWith("git+") || v.startsWith("git://") || v.startsWith("github:") || v.endsWith(".git") || /^[\w-]+\/[\w.-]+$/.test(v)) return "git";
+  if (v.startsWith("^")) return "caret";
+  if (v.startsWith("~")) return "tilde";
+  if (v.includes("||") || v.includes(" ") || v.startsWith(">") || v.startsWith("<") || v.startsWith("=")) return "range";
+  if (_EXACT_SEMVER_RE_MCP.test(v)) return "exact";
+  if (/^[A-Za-z][\w.-]*$/.test(v)) return "tag";
+  return "unknown";
+}
+function _auditDependencyRangesMcp(packageJsonText) {
+  if (!packageJsonText || !packageJsonText.trim()) return { error: "Input is empty" };
+  let parsed;
+  try {
+    parsed = JSON.parse(packageJsonText);
+  } catch (e) {
+    return { error: `Invalid JSON: ${e.message}` };
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    return { error: "Root of package.json must be an object" };
+  }
+  const obj = parsed;
+  const presentSections = _DEPENDENCY_SECTIONS_MCP.filter((s) => obj[s] && typeof obj[s] === "object");
+  if (presentSections.length === 0) {
+    return { error: "package.json has no dependencies, devDependencies, peerDependencies, or optionalDependencies field" };
+  }
+  const dependencies = [];
+  const issues = [];
+  const byName = /* @__PURE__ */ new Map();
+  for (const section of presentSections) {
+    const map = obj[section];
+    for (const [name, versionRaw] of Object.entries(map)) {
+      const version = typeof versionRaw === "string" ? versionRaw : String(versionRaw);
+      const rangeType = _classifyDependencyRangeMcp(version);
+      const entryIssues = [];
+      if (rangeType === "wildcard") {
+        entryIssues.push("no real version constraint; any version, including breaking ones, could be installed");
+      }
+      if (rangeType === "tag" && version.trim().toLowerCase() === "latest") {
+        entryIssues.push('"latest" is not reproducible; a fresh install can pull in a different, potentially breaking version at any time');
+      }
+      if (rangeType === "git" || rangeType === "url") {
+        entryIssues.push(`not resolved from the npm registry (${rangeType}); can't be checked against registry advisories the same way`);
+      }
+      if (rangeType === "file" || rangeType === "link") {
+        entryIssues.push(`local ${rangeType === "file" ? "path" : "symlink"} dependency; not portable to a machine or CI runner without the same local path`);
+      }
+      const entry = { name, version, section, rangeType, issues: entryIssues };
+      dependencies.push(entry);
+      for (const issue of entryIssues) {
+        issues.push({ severity: "warning", name, message: issue });
+      }
+      const existing = byName.get(name);
+      if (existing) existing.push(entry);
+      else byName.set(name, [entry]);
+    }
+  }
+  const duplicates = [];
+  for (const [name, entries] of byName) {
+    if (entries.length < 2) continue;
+    const versions = new Set(entries.map((e) => e.version));
+    const sameVersion = versions.size === 1;
+    duplicates.push({ name, sections: entries.map((e) => e.section), sameVersion });
+    if (!sameVersion) {
+      issues.push({ severity: "error", name, message: `listed with different version ranges in ${entries.map((e) => `${e.section} ("${e.version}")`).join(" and ")}` });
+    } else {
+      issues.push({ severity: "warning", name, message: `listed in more than one section (${entries.map((e) => e.section).join(", ")}) with the same range; redundant` });
+    }
+  }
+  const rangeTypeCounts = {};
+  for (const dep of dependencies) {
+    const rt = dep.rangeType;
+    rangeTypeCounts[rt] = (rangeTypeCounts[rt] ?? 0) + 1;
+  }
+  return {
+    parsed: true,
+    sections: presentSections,
+    totalDependencies: dependencies.length,
+    dependencies,
+    duplicates,
+    rangeTypeCounts,
+    issues
+  };
+}
+server.tool(
+  "audit_dependency_ranges",
+  `Parse a package.json's dependencies, devDependencies, peerDependencies, and optionalDependencies fields, classify each version specifier's range type, and flag wildcard ranges, the non-reproducible "latest" tag, git/URL/file/link dependencies, and packages listed with conflicting or redundant ranges across sections.`,
+  {
+    text: z.string().min(1).describe("The full package.json file contents")
+  },
+  async ({ text: packageJsonText }) => {
+    const result = _auditDependencyRangesMcp(packageJsonText);
+    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.62.0",
+  "version": "0.63.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",