@utilix-tech/mcp 0.86.0 → 0.87.0

package/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 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.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 267 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.
 
@@ -317,7 +317,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 +337,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)(: ?| #)(.*)$/;

package/package.json

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