@utilix-tech/mcp 0.86.0 → 0.88.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.88.0
+- Add `validate_mermaid_syntax` tool: check a Mermaid diagram definition for syntax errors with line numbers, including an unterminated subgraph, unbalanced node brackets, a malformed edge arrow, and a sequence-diagram participant referenced before its explicit declaration.
+- Add `calculate_annuity_payout` tool: solve the standard annuity formula in either direction, the periodic payout a lump sum funds, or the lump sum required to fund a target payout, for an ordinary or annuity-due structure.
+
+## 0.87.0
+- Add `validate_markdown_heading_hierarchy` tool: scan a Markdown document's ATX headings and flag heading-structure issues: skipped levels, multiple H1s, empty headings, duplicate headings at the same level, and a document that doesn't start at H1.
+
 ## 0.86.0
 - Add `calculate_sales_commission` tool: compute a flat or tiered (marginal) sales commission from a sale amount, where tiered mode applies each rate only to the slice of sales within that tier, plus an optional base salary added to the total payout.
 - Add `build_character_class` tool: assemble a `[...]` regex character class from named building blocks (lowercase, uppercase, digits, whitespace), custom ranges, and literal custom characters, with optional negation.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 266 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 269 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.
 
@@ -194,6 +194,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `calculate_rule_of_72` | Estimate years to double an investment from a rate, or the rate needed to double in a given number of years, via the Rule of 72 shortcut and the exact logarithmic result |
 | `calculate_emi` | Compute the Equated Monthly Installment for a loan from principal, annual rate, and tenure in years or months, with a year-by-year principal/interest breakdown |
 | `calculate_savings_goal` | Solve for months to reach a savings goal at a fixed monthly contribution, or the monthly contribution required to hit a goal by a target month count |
+| `calculate_annuity_payout` | Solve the standard annuity formula in either direction: the periodic payout a lump sum funds, or the lump sum required to fund a target payout, for an ordinary or annuity-due structure |
 | `calculate_roi` | Compute return on investment percent from an initial and final value, plus the annualized (CAGR) return given an optional holding period in years |
 | `compare_unit_prices` | Compare two or more package options by price and quantity to find the true cost per unit, flag the cheapest, and report how much more expensive each other option is |
 | `calculate_cash_breakdown` | Break a cash amount down into the minimum count of bills/coins from a set of denominations, largest first |
@@ -297,6 +298,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `parse_env` | Parse a .env file and return all key-value pairs |
 | `parse_docker_image` | Parse a Docker image reference into its components |
 | `lint_dockerfile` | Lint a Dockerfile for an unpinned base image, missing WORKDIR/USER, and misused ADD |
+| `validate_mermaid_syntax` | Check a Mermaid diagram definition for syntax errors with line numbers: unterminated subgraph, unbalanced brackets, malformed edges, and a sequence-diagram participant referenced before its declaration |
 | `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 |
@@ -317,7 +319,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `extract_markdown_link_references` | Extract every reference-style Markdown link ([text][ref], [text][], ![alt][ref]) and match it against its [ref]: url definition, flagging unresolved references and unused definitions |
 | `build_character_class` | Assemble a [...] regex character class from named building blocks (lowercase, uppercase, digits, whitespace), custom ranges, and literal custom characters, with optional negation |
 
-### Data (16 tools)
+### Data (18 tools)
 | Tool | Description |
 |------|-------------|
 | `validate_yaml` | Validate YAML syntax |
@@ -337,6 +339,7 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `analyze_caption_speed` | Parse an SRT or WebVTT file and report the words-per-minute reading speed of every cue, flagging ones that exceed common broadcast accessibility guidelines |
 | `infer_csv_column_types` | Parse CSV/TSV data and infer each column's data type (integer, float, boolean, ISO 8601 date, or string), flagging nullable columns and empty-cell counts |
 | `align_markdown_tables` | Reformat every GitHub-Flavored-Markdown pipe table in a document so each column's pipes line up visually, preserving left/center/right alignment markers |
+| `validate_markdown_heading_hierarchy` | Scan a Markdown document's ATX headings and flag heading-structure issues: skipped levels, multiple H1s, empty headings, duplicate headings, and a document that doesn't start at H1 |
 
 ### CSS (2 tools)
 | Tool | Description |

package/dist/index.js

@@ -6793,6 +6793,95 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+var _HEADING_HIERARCHY_RE_MCP = /^(#{1,6})(?!#)(?:[ \t]+(.*?))?[ \t]*#*[ \t]*$/;
+function _validateMarkdownHeadingHierarchyMcp(markdown) {
+  const lines = markdown.replace(/\r\n/g, "\n").split("\n");
+  const headings = [];
+  let inFence = false;
+  let fenceMarker = "";
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const fenceMatch = line.match(/^\s*(```+|~~~+)/);
+    if (fenceMatch) {
+      if (!inFence) {
+        inFence = true;
+        fenceMarker = fenceMatch[1][0];
+      } else if (fenceMatch[1][0] === fenceMarker) {
+        inFence = false;
+      }
+      continue;
+    }
+    if (inFence) continue;
+    const match = line.match(_HEADING_HIERARCHY_RE_MCP);
+    if (!match) continue;
+    const level = match[1].length;
+    const text2 = _stripInlineMarkdownMcp(match[2] ?? "");
+    headings.push({ line: i + 1, level, text: text2 });
+  }
+  const issues = [];
+  const seen = /* @__PURE__ */ new Map();
+  let h1Count = 0;
+  let firstH1Line = null;
+  let prevLevel = null;
+  headings.forEach((h, idx) => {
+    if (h.text === "") {
+      issues.push({ line: h.line, type: "empty-heading", message: `Heading at line ${h.line} has no text` });
+    }
+    if (idx === 0 && h.level !== 1) {
+      issues.push({
+        line: h.line,
+        type: "starts-below-h1",
+        message: `Document starts with an H${h.level} heading instead of H1`
+      });
+    }
+    if (h.level === 1) {
+      h1Count++;
+      if (h1Count === 1) {
+        firstH1Line = h.line;
+      } else {
+        issues.push({
+          line: h.line,
+          type: "multiple-h1",
+          message: `Multiple H1 headings found: another H1 at line ${h.line} (first was at line ${firstH1Line})`
+        });
+      }
+    }
+    if (prevLevel !== null && h.level > prevLevel + 1) {
+      const skipped = h.level - prevLevel > 2 ? `H${prevLevel + 1}-H${h.level - 1}` : `H${prevLevel + 1}`;
+      issues.push({
+        line: h.line,
+        type: "skipped-level",
+        message: `Heading level jumps from H${prevLevel} to H${h.level} at line ${h.line}, skipping ${skipped}`
+      });
+    }
+    prevLevel = h.level;
+    if (h.text !== "") {
+      const key = `${h.level}:${h.text.toLowerCase()}`;
+      const earlierLine = seen.get(key);
+      if (earlierLine !== void 0) {
+        issues.push({
+          line: h.line,
+          type: "duplicate-heading",
+          message: `Heading "${h.text}" at line ${h.line} duplicates an H${h.level} heading at line ${earlierLine}`
+        });
+      } else {
+        seen.set(key, h.line);
+      }
+    }
+  });
+  return { headings, issues, h1Count };
+}
+server.tool(
+  "validate_markdown_heading_hierarchy",
+  "Scan a Markdown document's ATX headings and flag heading-structure issues: a level that skips one or more levels going deeper, more than one H1, an empty heading, a duplicate heading at the same level, or a document that doesn't start at H1. Setext-style headings are not recognized, and headings inside fenced code blocks are ignored.",
+  {
+    markdown: z.string().describe("The Markdown document to scan")
+  },
+  async ({ markdown }) => {
+    const result = _validateMarkdownHeadingHierarchyMcp(markdown);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
 var _COMMIT_DEFAULT_TYPES_MCP = ["build", "chore", "ci", "docs", "feat", "fix", "perf", "refactor", "revert", "style", "test"];
 var _COMMIT_HEADER_RE_MCP = /^([A-Za-z][A-Za-z0-9-]*)(\(([^()]*)\))?(!)?: (.+)$/;
 var _COMMIT_FOOTER_LINE_RE_MCP = /^([A-Za-z][A-Za-z0-9-]*|BREAKING CHANGE)(: ?| #)(.*)$/;
@@ -7006,6 +7095,73 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+function _calculateAnnuityPayoutMcp(mode, structure, years, paymentsPerYear, annualRatePercent, principal, periodicPayout) {
+  if (mode !== "payout-from-principal" && mode !== "principal-from-payout") {
+    return { error: "mode must be 'payout-from-principal' or 'principal-from-payout'" };
+  }
+  if (structure !== "ordinary" && structure !== "due") {
+    return { error: "structure must be 'ordinary' or 'due'" };
+  }
+  if (!Number.isInteger(years) || years <= 0) return { error: "years must be a positive whole number" };
+  if (!Number.isInteger(paymentsPerYear) || paymentsPerYear <= 0) {
+    return { error: "paymentsPerYear must be a positive whole number" };
+  }
+  if (!Number.isFinite(annualRatePercent) || annualRatePercent < 0) {
+    return { error: "annualRatePercent must be a finite, non-negative number" };
+  }
+  const periods = years * paymentsPerYear;
+  const r = annualRatePercent / 100 / paymentsPerYear;
+  const round2 = (n) => Math.round(n * 100) / 100;
+  let factor = r === 0 ? periods : (1 - Math.pow(1 + r, -periods)) / r;
+  if (structure === "due") factor *= 1 + r;
+  let resolvedPrincipal;
+  let resolvedPayout;
+  if (mode === "payout-from-principal") {
+    if (typeof principal !== "number" || !Number.isFinite(principal) || principal <= 0) {
+      return { error: 'principal must be a finite number greater than zero for mode "payout-from-principal"' };
+    }
+    resolvedPrincipal = principal;
+    resolvedPayout = principal / factor;
+  } else {
+    if (typeof periodicPayout !== "number" || !Number.isFinite(periodicPayout) || periodicPayout <= 0) {
+      return { error: 'periodicPayout must be a finite number greater than zero for mode "principal-from-payout"' };
+    }
+    resolvedPayout = periodicPayout;
+    resolvedPrincipal = periodicPayout * factor;
+  }
+  const totalPaid = resolvedPayout * periods;
+  const totalInterest = totalPaid - resolvedPrincipal;
+  return {
+    mode,
+    structure,
+    years,
+    paymentsPerYear,
+    periods,
+    annualRatePercent,
+    principal: round2(resolvedPrincipal),
+    periodicPayout: round2(resolvedPayout),
+    totalPaid: round2(totalPaid),
+    totalInterest: round2(totalInterest)
+  };
+}
+server.tool(
+  "calculate_annuity_payout",
+  'Standard time-value-of-money annuity formula, solved in either direction. Mode "payout-from-principal" takes a lump sum and computes the fixed periodic payout a given number of periods at a given rate would produce; mode "principal-from-payout" takes a desired periodic payout and computes the lump sum required to fund it. Structure "ordinary" assumes payments at the end of each period, "due" at the start (worth one extra period of growth each). Pure closed-form formulas, no live rate data.',
+  {
+    mode: z.enum(["payout-from-principal", "principal-from-payout"]).describe("Which quantity to solve for"),
+    structure: z.enum(["ordinary", "due"]).describe('Whether payments land at the end ("ordinary") or start ("due") of each period'),
+    years: z.number().int().positive().describe("Payout term in years"),
+    paymentsPerYear: z.number().int().positive().describe("Payments per year, e.g. 12 = monthly"),
+    annualRatePercent: z.number().describe("Annual interest rate as a percent, e.g. 5 (cannot be negative)"),
+    principal: z.number().optional().describe('Required for mode "payout-from-principal": the lump sum to annuitize'),
+    periodicPayout: z.number().optional().describe('Required for mode "principal-from-payout": the desired payout per period')
+  },
+  async ({ mode, structure, years, paymentsPerYear, annualRatePercent, principal, periodicPayout }) => {
+    const result = _calculateAnnuityPayoutMcp(mode, structure, years, paymentsPerYear, annualRatePercent, principal, periodicPayout);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
 function _calculateRoiMcp(initialValue, finalValue, years) {
   if (typeof initialValue !== "number" || !Number.isFinite(initialValue) || initialValue <= 0) {
     return { error: "initialValue must be a finite number greater than zero" };
@@ -13507,6 +13663,117 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+var _MERMAID_DIAGRAM_TYPES_MCP = {
+  flowchart: "flowchart",
+  graph: "flowchart",
+  sequencediagram: "sequenceDiagram",
+  classdiagram: "classDiagram",
+  statediagram: "stateDiagram",
+  "statediagram-v2": "stateDiagram",
+  erdiagram: "erDiagram",
+  pie: "pie"
+};
+var _MERMAID_ARROW_RE_MCP = /(-\.->|==>|--x|--o|-\.-|-->|---|===)/i;
+function _checkMermaidFlowchartMcp(lines, fromLine, issues) {
+  const subgraphStack = [];
+  for (let i = fromLine; i < lines.length; i++) {
+    const lineNo = i + 1;
+    const trimmed = lines[i].split("%%")[0].trim();
+    if (trimmed === "") continue;
+    const firstToken = trimmed.split(/\s+/)[0];
+    if (firstToken === "subgraph") {
+      subgraphStack.push(lineNo);
+      continue;
+    }
+    if (trimmed === "end") {
+      if (subgraphStack.length === 0) {
+        issues.push({ rule: "unexpected-end", line: lineNo, message: "'end' with no matching 'subgraph' to close" });
+      } else {
+        subgraphStack.pop();
+      }
+      continue;
+    }
+    const opens = (trimmed.match(/[[({]/g) || []).length;
+    const closes = (trimmed.match(/[\])}]/g) || []).length;
+    if (opens !== closes) {
+      issues.push({ rule: "unbalanced-brackets", line: lineNo, message: `Unbalanced brackets in node/edge definition: ${opens} opening vs ${closes} closing` });
+    }
+    const segments = trimmed.split(_MERMAID_ARROW_RE_MCP);
+    if (segments.length > 1) {
+      let missingNode = false;
+      for (let s = 0; s < segments.length; s += 2) {
+        if (segments[s].trim() === "") missingNode = true;
+      }
+      if (missingNode) issues.push({ rule: "malformed-edge", line: lineNo, message: "Edge arrow is missing a node on one side" });
+    }
+  }
+  for (const openLine of subgraphStack) {
+    issues.push({ rule: "unterminated-subgraph", line: openLine, message: "'subgraph' opened here is never closed with a matching 'end'" });
+  }
+}
+var _MERMAID_SEQ_DECL_RE_MCP = /^(participant|actor)\s+(\S+)/i;
+var _MERMAID_SEQ_MSG_RE_MCP = /^([A-Za-z0-9_]+)\s*(-{1,2}>{1,2}|-{1,2}x|-{1,2}\))\s*([A-Za-z0-9_]+)\s*:/i;
+function _checkMermaidSequenceDiagramMcp(lines, fromLine, issues) {
+  const declaredAtLine = {};
+  for (let i = fromLine; i < lines.length; i++) {
+    const trimmed = lines[i].split("%%")[0].trim();
+    if (trimmed === "") continue;
+    const m = trimmed.match(_MERMAID_SEQ_DECL_RE_MCP);
+    if (m && declaredAtLine[m[2]] === void 0) declaredAtLine[m[2]] = i + 1;
+  }
+  for (let i = fromLine; i < lines.length; i++) {
+    const lineNo = i + 1;
+    const trimmed = lines[i].split("%%")[0].trim();
+    if (trimmed === "") continue;
+    const m = trimmed.match(_MERMAID_SEQ_MSG_RE_MCP);
+    if (!m) continue;
+    for (const id of [m[1], m[3]]) {
+      const declaredLine = declaredAtLine[id];
+      if (declaredLine !== void 0 && declaredLine > lineNo) {
+        issues.push({ rule: "participant-before-declared", line: lineNo, message: `Participant '${id}' is referenced here but not explicitly declared (with 'participant' or 'actor') until line ${declaredLine}` });
+      }
+    }
+  }
+}
+function _validateMermaidSyntaxMcp(input) {
+  if (!input || !input.trim()) return { error: "Diagram text is required" };
+  const lines = input.replace(/\r\n/g, "\n").split("\n");
+  const issues = [];
+  let headerLine = -1;
+  let headerText = "";
+  for (let i = 0; i < lines.length; i++) {
+    const trimmed = lines[i].trim();
+    if (trimmed === "" || trimmed.startsWith("%%")) continue;
+    headerLine = i + 1;
+    headerText = trimmed;
+    break;
+  }
+  if (headerLine === -1) return { error: "Diagram text is required" };
+  const firstWord = headerText.split(/\s+/)[0];
+  const diagramType = _MERMAID_DIAGRAM_TYPES_MCP[firstWord.toLowerCase()] ?? null;
+  if (!diagramType) {
+    issues.push({ rule: "unrecognized-diagram-type", line: headerLine, message: `"${firstWord}" is not a recognized Mermaid diagram type (expected one of: flowchart/graph, sequenceDiagram, classDiagram, stateDiagram, erDiagram, pie)` });
+    return { diagramType: null, valid: false, issues };
+  }
+  if (diagramType === "flowchart") {
+    _checkMermaidFlowchartMcp(lines, headerLine, issues);
+  } else if (diagramType === "sequenceDiagram") {
+    _checkMermaidSequenceDiagramMcp(lines, headerLine, issues);
+  }
+  return { diagramType, valid: issues.length === 0, issues };
+}
+server.tool(
+  "validate_mermaid_syntax",
+  "Heuristic syntax validation for a Mermaid diagram definition: recognizes flowchart/graph, sequenceDiagram, classDiagram, stateDiagram(-v2), erDiagram, and pie by their header keyword, then runs diagram-specific structural checks (unterminated subgraph, unbalanced brackets, malformed edges for flowcharts; a participant referenced before its explicit declaration for sequence diagrams). A line-based heuristic, not a full Mermaid grammar; never renders the diagram.",
+  {
+    diagram: z.string().min(1).describe("The full Mermaid diagram definition text")
+  },
+  async ({ diagram }) => {
+    const result = _validateMermaidSyntaxMcp(diagram);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
 server.tool(
   "find_cron_overlaps",
   "Given two or more standard 5-field cron expressions, find every minute over the next N days where two or more of them fire at the same time, for example a nightly backup job colliding with a report job. Returns each colliding minute with the zero-based indexes of every expression that matched.",

package/package.json

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