@utilix-tech/mcp 0.79.0 → 0.81.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.81.0
+- Add `validate_fence_language_tags` tool: scan a Markdown document's fenced code blocks and flag a missing, unknown, or inconsistently-cased language tag against a curated list of common syntax-highlighter identifiers.
+- Add `count_sql_placeholders` tool: count positional (`?`, `$1`) and named (`:name`, `@name`) parameter placeholders in a SQL query, flagging mixed styles and numbered-sequence gaps or duplicates.
+
+## 0.80.0
+- Add `diff_json_patch`, `apply_json_patch` tools: diff two JSON documents into an RFC 6902 JSON Patch operation list (add/remove/replace/move/copy/test), or apply a patch to a target document.
+- Add `parse_connection_string` tool: parse a database connection URI (postgres, mysql, mongodb, redis, amqp, and similar) into its scheme, credentials, hosts, database, and query parameters.
+
 ## 0.79.0
 - Add `calculate_real_rate_of_return` tool: apply the Fisher equation to solve for whichever of the nominal rate, inflation rate, or inflation-adjusted real rate is missing, given exactly two of the three.
 - Add `calculate_retry_backoff_schedule` tool: compute the full sequence of delays an exponential-backoff retry policy would actually produce, optionally capped and with full/equal jitter ranges, plus the total best-case and worst-case wait across all retries.

package/README.md

@@ -1,6 +1,6 @@
 # @utilix-tech/mcp
 
-MCP server exposing 250 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 257 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 (16 tools)
+### JSON (18 tools)
 | Tool | Description |
 |------|-------------|
 | `format_json` | Pretty-print and validate a JSON string |
@@ -86,6 +86,8 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `jsonpath` | Evaluate a JSONPath expression |
 | `resolve_json_pointer` | Resolve an RFC 6901 JSON Pointer against a JSON document |
 | `apply_json_merge_patch` | Apply an RFC 7396 JSON Merge Patch document to a target JSON document |
+| `diff_json_patch` | Compare two JSON documents and generate an RFC 6902 JSON Patch operation list |
+| `apply_json_patch` | Apply a sequence of RFC 6902 JSON Patch operations (add, remove, replace, move, copy, test) to a target document |
 | `validate_json` | Validate JSON against a JSON Schema |
 | `yaml_to_json` | Convert YAML to JSON |
 | `json_to_yaml` | Convert JSON to YAML |
@@ -279,7 +281,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 (21 tools)
+### Code (24 tools)
 | Tool | Description |
 |------|-------------|
 | `format_sql` | Format a SQL query with proper indentation |
@@ -303,6 +305,9 @@ claude mcp add utilix -- npx -y @utilix-tech/mcp
 | `parse_commit_trailers` | Parse a commit message's trailer block (Co-authored-by, Signed-off-by, Fixes, Reviewed-by, etc.) per git's RFC 822-style trailer convention, returning each trailer's key/value plus the body with the trailer block removed |
 | `extract_markdown_footnotes` | Extract every Markdown-Extra-style footnote reference and definition from a document, flagging references with no matching definition and definitions that are never referenced |
 | `validate_aria` | Parse an HTML snippet and check every role and aria-* attribute against a curated table of WAI-ARIA 1.2 roles: unknown role names, an aria-* attribute not permitted on the given role, and a widget role missing its required aria-* state |
+| `parse_connection_string` | Parse a database connection URI (postgres, mysql, mongodb, redis, amqp, and similar) into its scheme, credentials, hosts, database, and query parameters |
+| `validate_fence_language_tags` | Scan a Markdown document's fenced code blocks and flag a missing, unknown, or inconsistently-cased language tag against a curated list of common syntax-highlighter identifiers |
+| `count_sql_placeholders` | Count positional (`?`, `$1`) and named (`:name`, `@name`) parameter placeholders in a SQL query, flagging mixed styles and numbered-sequence gaps or duplicates |
 
 ### Data (16 tools)
 | Tool | Description |

package/dist/index.js

@@ -12446,5 +12446,666 @@ server.tool(
     return text(JSON.stringify(result, null, 2));
   }
 );
+function _escapeJsonPointerTokenMcp(token) {
+  return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function _unescapeJsonPointerTokenMcp(token) {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+function _parseJsonPointerTokensMcp(pointer) {
+  if (pointer === "") return [];
+  if (!pointer.startsWith("/")) throw new Error(`Invalid JSON Pointer "${pointer}": must start with "/"`);
+  return pointer.slice(1).split("/").map(_unescapeJsonPointerTokenMcp);
+}
+function _isJsonPatchObjectMcp(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function _jsonPatchDeepEqualMcp(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (Array.isArray(a) || Array.isArray(b)) {
+    if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+    return a.every((v, i) => _jsonPatchDeepEqualMcp(v, b[i]));
+  }
+  if (_isJsonPatchObjectMcp(a) && _isJsonPatchObjectMcp(b)) {
+    const aKeys = Object.keys(a);
+    const bKeys = Object.keys(b);
+    if (aKeys.length !== bKeys.length) return false;
+    return aKeys.every((k) => k in b && _jsonPatchDeepEqualMcp(a[k], b[k]));
+  }
+  return false;
+}
+function _jsonPatchGetByTokensMcp(doc, tokens) {
+  let current = doc;
+  for (const token of tokens) {
+    if (Array.isArray(current)) {
+      const index = token === "-" ? current.length - 1 : parseInt(token, 10);
+      if (!Number.isInteger(index) || index < 0 || index >= current.length) return { found: false, value: void 0 };
+      current = current[index];
+    } else if (_isJsonPatchObjectMcp(current)) {
+      if (!(token in current)) return { found: false, value: void 0 };
+      current = current[token];
+    } else {
+      return { found: false, value: void 0 };
+    }
+  }
+  return { found: true, value: current };
+}
+function _diffJsonPatchMcp(a, b) {
+  const ops = [];
+  _diffJsonPatchValueMcp(a, b, "", ops);
+  return ops;
+}
+function _diffJsonPatchValueMcp(a, b, path, ops) {
+  if (_jsonPatchDeepEqualMcp(a, b)) return;
+  if (_isJsonPatchObjectMcp(a) && _isJsonPatchObjectMcp(b)) {
+    for (const key of Object.keys(a)) {
+      if (!(key in b)) ops.push({ op: "remove", path: `${path}/${_escapeJsonPointerTokenMcp(key)}` });
+    }
+    for (const key of Object.keys(b)) {
+      const childPath = `${path}/${_escapeJsonPointerTokenMcp(key)}`;
+      if (!(key in a)) {
+        ops.push({ op: "add", path: childPath, value: b[key] });
+      } else {
+        _diffJsonPatchValueMcp(a[key], b[key], childPath, ops);
+      }
+    }
+    return;
+  }
+  if (Array.isArray(a) && Array.isArray(b)) {
+    const minLen = Math.min(a.length, b.length);
+    for (let i = 0; i < minLen; i++) _diffJsonPatchValueMcp(a[i], b[i], `${path}/${i}`, ops);
+    if (b.length > a.length) {
+      for (let i = a.length; i < b.length; i++) ops.push({ op: "add", path: `${path}/${i}`, value: b[i] });
+    } else if (a.length > b.length) {
+      for (let i = a.length - 1; i >= b.length; i--) ops.push({ op: "remove", path: `${path}/${i}` });
+    }
+    return;
+  }
+  ops.push({ op: "replace", path, value: b });
+}
+function _applyJsonPatchMcp(target, operations) {
+  let doc = JSON.parse(JSON.stringify(target ?? null));
+  const applyOne = (op, index) => {
+    if (op.path === void 0 || op.op === void 0) return `Operation ${index}: missing "op" or "path"`;
+    let tokens;
+    try {
+      tokens = _parseJsonPointerTokensMcp(op.path);
+    } catch (e) {
+      return `Operation ${index}: ${e.message}`;
+    }
+    const setAt = (tgtTokens, value) => {
+      if (tgtTokens.length === 0) {
+        doc = value;
+        return null;
+      }
+      const parentTokens = tgtTokens.slice(0, -1);
+      const lastToken = tgtTokens[tgtTokens.length - 1];
+      const { found, value: parent } = _jsonPatchGetByTokensMcp(doc, parentTokens);
+      if (!found) return `Operation ${index}: path "${op.path}" has no parent`;
+      if (Array.isArray(parent)) {
+        const idx = lastToken === "-" ? parent.length : parseInt(lastToken, 10);
+        if (!Number.isInteger(idx) || idx < 0 || idx > parent.length) return `Operation ${index}: array index "${lastToken}" out of bounds`;
+        parent.splice(idx, 0, value);
+      } else if (_isJsonPatchObjectMcp(parent)) {
+        parent[lastToken] = value;
+      } else {
+        return `Operation ${index}: cannot add into a non-object, non-array value at "${op.path}"`;
+      }
+      return null;
+    };
+    const replaceAt = (tgtTokens, value) => {
+      if (tgtTokens.length === 0) {
+        doc = value;
+        return null;
+      }
+      const parentTokens = tgtTokens.slice(0, -1);
+      const lastToken = tgtTokens[tgtTokens.length - 1];
+      const { found, value: parent } = _jsonPatchGetByTokensMcp(doc, parentTokens);
+      if (!found) return `Operation ${index}: path "${op.path}" has no parent`;
+      if (Array.isArray(parent)) {
+        const idx = lastToken === "-" ? parent.length - 1 : parseInt(lastToken, 10);
+        if (!Number.isInteger(idx) || idx < 0 || idx >= parent.length) return `Operation ${index}: array index "${lastToken}" out of bounds`;
+        parent[idx] = value;
+      } else if (_isJsonPatchObjectMcp(parent)) {
+        if (!(lastToken in parent)) return `Operation ${index}: path "${op.path}" does not exist`;
+        parent[lastToken] = value;
+      } else {
+        return `Operation ${index}: cannot replace into a non-object, non-array value at "${op.path}"`;
+      }
+      return null;
+    };
+    const removeAt = (tgtTokens) => {
+      if (tgtTokens.length === 0) return { error: `Operation ${index}: cannot remove the whole document (path "")` };
+      const parentTokens = tgtTokens.slice(0, -1);
+      const lastToken = tgtTokens[tgtTokens.length - 1];
+      const { found, value: parent } = _jsonPatchGetByTokensMcp(doc, parentTokens);
+      if (!found) return { error: `Operation ${index}: path "${op.path}" has no parent` };
+      if (Array.isArray(parent)) {
+        const idx = lastToken === "-" ? parent.length - 1 : parseInt(lastToken, 10);
+        if (!Number.isInteger(idx) || idx < 0 || idx >= parent.length) return { error: `Operation ${index}: array index "${lastToken}" out of bounds` };
+        const [removed] = parent.splice(idx, 1);
+        return { error: null, removed };
+      }
+      if (_isJsonPatchObjectMcp(parent)) {
+        if (!(lastToken in parent)) return { error: `Operation ${index}: path "${op.path}" does not exist` };
+        const removed = parent[lastToken];
+        delete parent[lastToken];
+        return { error: null, removed };
+      }
+      return { error: `Operation ${index}: cannot remove from a non-object, non-array value at "${op.path}"` };
+    };
+    switch (op.op) {
+      case "add":
+        return setAt(tokens, op.value);
+      case "replace":
+        return replaceAt(tokens, op.value);
+      case "remove":
+        return removeAt(tokens).error;
+      case "test": {
+        const { found, value } = _jsonPatchGetByTokensMcp(doc, tokens);
+        if (!found) return `Operation ${index}: path "${op.path}" does not exist`;
+        if (!_jsonPatchDeepEqualMcp(value, op.value)) return `Operation ${index}: test failed at "${op.path}"`;
+        return null;
+      }
+      case "move": {
+        if (!op.from) return `Operation ${index}: "move" requires "from"`;
+        let fromTokens;
+        try {
+          fromTokens = _parseJsonPointerTokensMcp(op.from);
+        } catch (e) {
+          return `Operation ${index}: ${e.message}`;
+        }
+        const removal = removeAt(fromTokens);
+        if (removal.error) return removal.error;
+        return setAt(tokens, removal.removed);
+      }
+      case "copy": {
+        if (!op.from) return `Operation ${index}: "copy" requires "from"`;
+        let fromTokens;
+        try {
+          fromTokens = _parseJsonPointerTokensMcp(op.from);
+        } catch (e) {
+          return `Operation ${index}: ${e.message}`;
+        }
+        const { found, value } = _jsonPatchGetByTokensMcp(doc, fromTokens);
+        if (!found) return `Operation ${index}: "from" path "${op.from}" does not exist`;
+        return setAt(tokens, JSON.parse(JSON.stringify(value)));
+      }
+      default:
+        return `Operation ${index}: unknown op "${op.op}"`;
+    }
+  };
+  for (let i = 0; i < operations.length; i++) {
+    const err = applyOne(operations[i], i);
+    if (err) return { error: err };
+  }
+  return { result: doc };
+}
+server.tool(
+  "diff_json_patch",
+  "Compare two JSON documents and generate an RFC 6902 JSON Patch (a list of add/remove/replace operations) that transforms the first into the second. Object keys produce add/remove/replace; arrays are compared position by position (not a minimal edit-distance diff, so a reordering is not detected as a move).",
+  {
+    a: z.string().describe("The source JSON document, as a JSON string"),
+    b: z.string().describe("The target JSON document, as a JSON string")
+  },
+  async ({ a, b }) => {
+    let aParsed;
+    try {
+      aParsed = JSON.parse(a);
+    } catch {
+      return errText({ error: "First document is not valid JSON" });
+    }
+    let bParsed;
+    try {
+      bParsed = JSON.parse(b);
+    } catch {
+      return errText({ error: "Second document is not valid JSON" });
+    }
+    return text(JSON.stringify({ patch: _diffJsonPatchMcp(aParsed, bParsed) }, null, 2));
+  }
+);
+server.tool(
+  "apply_json_patch",
+  "Apply a sequence of RFC 6902 JSON Patch operations (add, remove, replace, move, copy, test) to a target JSON document and return the result, or an error naming the first operation that failed and why.",
+  {
+    target: z.string().describe("The document to patch, as a JSON string"),
+    patch: z.string().describe("The RFC 6902 JSON Patch operation array, as a JSON string")
+  },
+  async ({ target, patch }) => {
+    let targetParsed;
+    try {
+      targetParsed = JSON.parse(target);
+    } catch {
+      return errText({ error: "Target is not valid JSON" });
+    }
+    let operations;
+    try {
+      operations = JSON.parse(patch);
+    } catch {
+      return errText({ error: "Patch is not valid JSON" });
+    }
+    if (!Array.isArray(operations)) return errText({ error: "Patch must be a JSON array of RFC 6902 operations" });
+    const result = _applyJsonPatchMcp(targetParsed, operations);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+var _CONNECTION_STRING_RE_MCP = /^([a-zA-Z][a-zA-Z0-9+.-]*):\/\/(?:([^@/?#]*)@)?([^/?#]*)(?:\/([^?#]*))?(?:\?([^#]*))?$/;
+function _parseConnectionHostMcp(segment) {
+  const ipv6Match = segment.match(/^\[([^\]]+)\](?::(\d+))?$/);
+  if (ipv6Match) return { host: ipv6Match[1], port: ipv6Match[2] ? parseInt(ipv6Match[2], 10) : null };
+  const lastColon = segment.lastIndexOf(":");
+  if (lastColon === -1) return { host: segment, port: null };
+  const portPart = segment.slice(lastColon + 1);
+  if (!/^\d+$/.test(portPart)) return { host: segment, port: null };
+  return { host: segment.slice(0, lastColon), port: parseInt(portPart, 10) };
+}
+function _parseConnectionStringMcp(input) {
+  if (!input || !input.trim()) return { error: "Connection string is empty" };
+  const trimmed = input.trim();
+  const match = trimmed.match(_CONNECTION_STRING_RE_MCP);
+  if (!match) return { error: "Not a valid scheme://[user[:password]@]host[,host2][/database][?params] connection string" };
+  const [, scheme, userinfo, hostPart, databasePart, queryPart] = match;
+  let user = null;
+  let password = null;
+  if (userinfo) {
+    const sepIndex = userinfo.indexOf(":");
+    if (sepIndex === -1) {
+      user = decodeURIComponent(userinfo);
+    } else {
+      user = decodeURIComponent(userinfo.slice(0, sepIndex));
+      password = decodeURIComponent(userinfo.slice(sepIndex + 1));
+    }
+  }
+  const hosts = hostPart ? hostPart.split(",").filter(Boolean).map(_parseConnectionHostMcp) : [];
+  const database = databasePart ? decodeURIComponent(databasePart) : null;
+  const params = {};
+  if (queryPart) {
+    for (const pair of queryPart.split("&")) {
+      if (!pair) continue;
+      const eqIndex = pair.indexOf("=");
+      const key = eqIndex === -1 ? pair : pair.slice(0, eqIndex);
+      const value = eqIndex === -1 ? "" : pair.slice(eqIndex + 1);
+      params[decodeURIComponent(key)] = decodeURIComponent(value);
+    }
+  }
+  return { scheme, user, password, hosts, database, params };
+}
+server.tool(
+  "parse_connection_string",
+  "Parse a database connection URI (postgres://, mysql://, mongodb://, mongodb+srv://, redis://, amqp://, and similar generic scheme:// connection strings) into its scheme, credentials, one or more hosts (mongodb-style comma-separated host lists included), database/path, and query parameters. Pure offline parse: never connects, resolves DNS, or validates the driver/scheme combination.",
+  {
+    connectionString: z.string().describe("The database connection string to parse")
+  },
+  async ({ connectionString }) => {
+    const result = _parseConnectionStringMcp(connectionString);
+    if ("error" in result) return errText(result);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+var _KNOWN_LANGUAGE_TAGS_MCP = /* @__PURE__ */ new Set([
+  "js",
+  "jsx",
+  "mjs",
+  "cjs",
+  "javascript",
+  "ts",
+  "tsx",
+  "typescript",
+  "json",
+  "json5",
+  "jsonc",
+  "jsonl",
+  "ndjson",
+  "yaml",
+  "yml",
+  "toml",
+  "ini",
+  "cfg",
+  "conf",
+  "properties",
+  "env",
+  "dotenv",
+  "html",
+  "htm",
+  "xml",
+  "svg",
+  "xhtml",
+  "css",
+  "scss",
+  "sass",
+  "less",
+  "stylus",
+  "styl",
+  "markdown",
+  "md",
+  "mdx",
+  "bash",
+  "sh",
+  "shell",
+  "zsh",
+  "fish",
+  "console",
+  "powershell",
+  "ps1",
+  "bat",
+  "cmd",
+  "python",
+  "py",
+  "py3",
+  "ipynb",
+  "ruby",
+  "rb",
+  "erb",
+  "php",
+  "java",
+  "kotlin",
+  "kt",
+  "kts",
+  "groovy",
+  "gradle",
+  "swift",
+  "objectivec",
+  "objc",
+  "go",
+  "golang",
+  "rust",
+  "rs",
+  "c",
+  "h",
+  "cpp",
+  "cc",
+  "cxx",
+  "hpp",
+  "c++",
+  "csharp",
+  "cs",
+  "fsharp",
+  "fs",
+  "perl",
+  "pl",
+  "lua",
+  "r",
+  "matlab",
+  "m",
+  "scala",
+  "nim",
+  "zig",
+  "julia",
+  "jl",
+  "haskell",
+  "hs",
+  "elixir",
+  "ex",
+  "exs",
+  "erlang",
+  "erl",
+  "clojure",
+  "clj",
+  "cljs",
+  "dart",
+  "ocaml",
+  "ml",
+  "sql",
+  "mysql",
+  "postgresql",
+  "plsql",
+  "sqlite",
+  "graphql",
+  "gql",
+  "dockerfile",
+  "docker",
+  "makefile",
+  "make",
+  "cmake",
+  "nginx",
+  "apache",
+  "diff",
+  "patch",
+  "git",
+  "http",
+  "proto",
+  "protobuf",
+  "csv",
+  "tsv",
+  "vim",
+  "viml",
+  "tex",
+  "latex",
+  "bibtex",
+  "plaintext",
+  "text",
+  "txt",
+  "nohighlight",
+  "none",
+  "asciidoc",
+  "adoc",
+  "rst",
+  "vue",
+  "svelte",
+  "astro",
+  "wasm",
+  "wat",
+  "handlebars",
+  "hbs",
+  "pug",
+  "jade",
+  "coffee",
+  "coffeescript",
+  "actionscript",
+  "terraform",
+  "tf",
+  "hcl",
+  "puppet",
+  "ansible"
+]);
+function _parseFenceLineMcp(line) {
+  const match = line.match(/^( {0,3})(`{3,}|~{3,})(.*)$/);
+  if (!match) return null;
+  const [, , marker, rest] = match;
+  const char = marker[0];
+  if (char === "`" && rest.includes("`")) return null;
+  return { char, length: marker.length, infoString: rest.trim() };
+}
+function _isClosingFenceMcp(line, fenceChar, fenceLength) {
+  const match = line.match(/^ {0,3}(`+|~+)\s*$/);
+  if (!match) return false;
+  const marker = match[1];
+  return marker[0] === fenceChar && marker.length >= fenceLength;
+}
+function _validateFenceLanguageTagsMcp(markdown) {
+  const lines = markdown.split("\n");
+  const issues = [];
+  let totalFences = 0;
+  let open = null;
+  for (let i = 0; i < lines.length; i++) {
+    const lineNumber = i + 1;
+    const line = lines[i];
+    if (open) {
+      if (_isClosingFenceMcp(line, open.char, open.length)) open = null;
+      continue;
+    }
+    const fence = _parseFenceLineMcp(line);
+    if (!fence) continue;
+    totalFences++;
+    const tag = fence.infoString.split(/\s+/)[0] ?? "";
+    open = { char: fence.char, length: fence.length };
+    if (tag === "") {
+      issues.push({ line: lineNumber, tag, issue: "missing" });
+      continue;
+    }
+    const lower = tag.toLowerCase();
+    if (!_KNOWN_LANGUAGE_TAGS_MCP.has(lower)) {
+      issues.push({ line: lineNumber, tag, issue: "unknown" });
+      continue;
+    }
+    if (tag !== lower) {
+      issues.push({ line: lineNumber, tag, issue: "inconsistent-case", suggestion: lower });
+    }
+  }
+  return { totalFences, issues };
+}
+server.tool(
+  "validate_fence_language_tags",
+  "Scan a Markdown document's fenced code blocks (``` or ~~~) and flag ones with a missing, unknown, or inconsistently-cased language tag, checked against a curated list of common syntax-highlighter language identifiers.",
+  {
+    markdown: z.string().describe("The Markdown document to scan")
+  },
+  async ({ markdown }) => {
+    const result = _validateFenceLanguageTagsMcp(markdown);
+    return text(JSON.stringify(result, null, 2));
+  }
+);
+var _SQL_IDENT_START_MCP = /[A-Za-z_]/;
+var _SQL_IDENT_CHAR_MCP = /[A-Za-z0-9_]/;
+function _readSqlIdentifierMcp(sql, start) {
+  let end = start;
+  while (end < sql.length && _SQL_IDENT_CHAR_MCP.test(sql[end])) end++;
+  return sql.slice(start, end);
+}
+function _countSqlPlaceholdersMcp(sql) {
+  const placeholders = [];
+  let state = "normal";
+  let i = 0;
+  while (i < sql.length) {
+    const ch = sql[i];
+    const next = sql[i + 1];
+    if (state === "single") {
+      if (ch === "'" && next === "'") {
+        i += 2;
+        continue;
+      }
+      if (ch === "'") {
+        state = "normal";
+        i++;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (state === "double") {
+      if (ch === '"' && next === '"') {
+        i += 2;
+        continue;
+      }
+      if (ch === '"') {
+        state = "normal";
+        i++;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (state === "line-comment") {
+      if (ch === "\n") state = "normal";
+      i++;
+      continue;
+    }
+    if (state === "block-comment") {
+      if (ch === "*" && next === "/") {
+        state = "normal";
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (ch === "'") {
+      state = "single";
+      i++;
+      continue;
+    }
+    if (ch === '"') {
+      state = "double";
+      i++;
+      continue;
+    }
+    if (ch === "-" && next === "-") {
+      state = "line-comment";
+      i += 2;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      state = "block-comment";
+      i += 2;
+      continue;
+    }
+    if (ch === "?") {
+      placeholders.push({ style: "anonymous", raw: "?", index: i });
+      i++;
+      continue;
+    }
+    if (ch === "$" && /[0-9]/.test(next ?? "")) {
+      let end = i + 1;
+      while (end < sql.length && /[0-9]/.test(sql[end])) end++;
+      const raw = sql.slice(i, end);
+      placeholders.push({ style: "numbered", raw, index: i, number: parseInt(raw.slice(1), 10) });
+      i = end;
+      continue;
+    }
+    if (ch === ":") {
+      if (next === ":") {
+        i += 2;
+        continue;
+      }
+      if (next && _SQL_IDENT_START_MCP.test(next)) {
+        const name = _readSqlIdentifierMcp(sql, i + 1);
+        placeholders.push({ style: "named-colon", raw: `:${name}`, index: i, name });
+        i += 1 + name.length;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    if (ch === "@") {
+      if (next === "@") {
+        i += 2;
+        continue;
+      }
+      if (next && _SQL_IDENT_START_MCP.test(next)) {
+        const name = _readSqlIdentifierMcp(sql, i + 1);
+        placeholders.push({ style: "named-at", raw: `@${name}`, index: i, name });
+        i += 1 + name.length;
+        continue;
+      }
+      i++;
+      continue;
+    }
+    i++;
+  }
+  const counts = { anonymous: 0, numbered: 0, "named-colon": 0, "named-at": 0 };
+  for (const p of placeholders) counts[p.style]++;
+  const stylesUsed = ["anonymous", "numbered", "named-colon", "named-at"].filter((s) => counts[s] > 0);
+  const numbers = placeholders.filter((p) => p.style === "numbered").map((p) => p.number);
+  const maxNumber = numbers.length > 0 ? Math.max(...numbers) : 0;
+  const seen = new Set(numbers);
+  const numberedGaps = [];
+  for (let n = 1; n < maxNumber; n++) {
+    if (!seen.has(n)) numberedGaps.push(n);
+  }
+  const countedMap = /* @__PURE__ */ new Map();
+  for (const n of numbers) countedMap.set(n, (countedMap.get(n) ?? 0) + 1);
+  const numberedDuplicates = [...countedMap.entries()].filter(([, c]) => c > 1).map(([n]) => n).sort((a, b) => a - b);
+  return {
+    placeholders,
+    counts,
+    stylesUsed,
+    mixedStyles: stylesUsed.length > 1,
+    numberedGaps,
+    numberedDuplicates
+  };
+}
+server.tool(
+  "count_sql_placeholders",
+  "Count and list positional (?, $1) and named (:name, @name) parameter placeholders in a SQL query string, flagging a mix of placeholder styles in the same query and, for numbered placeholders, a gap or duplicate in the sequence. String literals and comments are skipped.",
+  {
+    sql: z.string().describe("The SQL query string to scan")
+  },
+  async ({ sql }) => {
+    const result = _countSqlPlaceholdersMcp(sql);
+    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.79.0",
+  "version": "0.81.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",