@utilix-tech/mcp 0.3.0 → 0.4.0

package/README.md

@@ -1,8 +1,8 @@
 # @utilix-tech/mcp
 
-MCP server exposing 70 developer utility tools to Claude, Cursor, VS Code Copilot, and any [Model Context Protocol](https://modelcontextprotocol.io) compatible AI assistant.
+MCP server exposing 97 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.
+No API key required. All tools run locally. Requires Node.js 18 or later.
 
 ## Installation
 
@@ -52,6 +52,27 @@ Add to `.vscode/mcp.json`:
 }
 ```
 
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "utilix": {
+      "command": "npx",
+      "args": ["-y", "@utilix-tech/mcp"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add utilix -- npx -y @utilix-tech/mcp
+```
+
 ## Tools
 
 ### JSON (13 tools)
@@ -100,7 +121,7 @@ Add to `.vscode/mcp.json`:
 | `generate_qr` | Generate a QR code as an SVG string |
 | `generate_random_data` | Generate random mock data: names, emails, UUIDs, IPs, etc. |
 
-### Text (9 tools)
+### Text (10 tools)
 | Tool | Description |
 |------|-------------|
 | `convert_case` | Convert text case: camelCase, snake_case, PascalCase, etc. |
@@ -112,6 +133,7 @@ Add to `.vscode/mcp.json`:
 | `text_diff` | Diff two text blocks line-by-line |
 | `html_to_markdown` | Convert HTML to Markdown |
 | `line_operations` | Sort, deduplicate, reverse, shuffle, trim, or number lines |
+| `detect_passive_voice` | Flag sentences written in passive voice, e.g. "was written", "were approved by the team" |
 
 ### Time (5 tools)
 | Tool | Description |
@@ -176,12 +198,52 @@ Add to `.vscode/mcp.json`:
 | `unicode_inspect` | Inspect Unicode code points of a string |
 | `optimize_svg` | Optimize and minify an SVG string |
 
+### AI / Agent (25 tools)
+| Tool | Description |
+|------|-------------|
+| `estimate_tokens` | Estimate token count and cost for an LLM prompt |
+| `trim_to_tokens` | Trim text to fit a token budget |
+| `chunk_text` | Split text into overlapping chunks for RAG pipelines |
+| `rerank_chunks` | Rerank retrieved chunks by relevance to a query |
+| `score_relevance` | Score a chunk's relevance to a query |
+| `expand_query` | Expand a search query with synonyms/related terms |
+| `summarize_for_llm` | Summarize text to fit a target length or token budget |
+| `detect_pii` | Find emails, phones, SSNs, credit cards in text |
+| `detect_secrets` | Scan text for leaked API keys, tokens, passwords |
+| `detect_prompt_injection` | Score and flag adversarial/injection-style inputs |
+| `repair_json` | Fix malformed JSON with a list of applied fixes |
+| `sanitize_html` | Strip unsafe tags/attributes from HTML |
+| `flatten_json` | Flatten nested JSON into dot-notation keys |
+| `merge_json` | Deep or shallow merge two JSON objects |
+| `extract_json` | Extract JSON blocks embedded in free text |
+| `extract_urls` | Extract all URLs from text |
+| `extract_entities` | Extract named entities from text |
+| `extract_keywords` | Extract keywords from text |
+| `extract_tables` | Extract tabular data from text |
+| `deduplicate_lines` | Remove duplicate lines from text |
+| `validate_json_schema` | Validate JSON against a JSON Schema |
+| `compress_html` | Compress HTML for LLM context budgets |
+| `compress_markdown` | Compress Markdown for LLM context budgets |
+| `compress_json` | Compress JSON for LLM context budgets |
+| `diff_json_detailed` | Diff two parsed JSON values, returning every path with its op and unchanged paths |
+
+### Image (1 tool)
+| Tool | Description |
+|------|-------------|
+| `read_image_info` | Read format, dimensions, bit depth, and alpha channel from image bytes — no decoding required. Supports PNG, JPEG, GIF, WebP, BMP |
+
 ## Requirements
 
 - Node.js 18+
 
+## Publishing (maintainers)
+
+CI publishes automatically via npm Trusted Publishing (OIDC) on every push to `main` that bumps `version`. Requires npm **>=11.5.1** — older versions (e.g. the npm bundled with Node 20) sign provenance but skip the OIDC auth exchange, so `npm publish` fails with a 404 as if unauthenticated.
+
 ## Links
 
 - [Utilix web app](https://utilix.tech) — use these tools in the browser
+- [API Playground](https://utilix.tech/api) — try 10 endpoints live, no signup required
+- [REST API docs](https://utilix.tech/docs#rest-api) — 100+ endpoints at `api.utilix.tech/v1` (1,000 req/day free)
 - [Node.js SDK](https://www.npmjs.com/package/@utilix-tech/sdk) — use in your Node.js projects
 - [Python SDK](https://pypi.org/project/utilix-sdk/) — use in your Python projects

package/dist/index.js

@@ -7,6 +7,7 @@ import { z } from "zod";
 import {
   parseJson,
   minifyJson,
+  diffJson,
   jsonToCsv,
   csvToJson,
   evaluateJsonPath,
@@ -73,7 +74,7 @@ import { formatSql, formatHtml, testRegex, minifyJs, formatGql, parseDockerImage
 import { validateYaml, tomlToJson, xmlToJson, parseCsv } from "@utilix-tech/sdk/data";
 import { generateGradient, minifyCss } from "@utilix-tech/sdk/css";
 import { optimizeSvg, charToCodePoint, numberToWords } from "@utilix-tech/sdk/misc";
-import { estimateTokens, estimateCost, detectPii, redactPii, detectSecrets, detectPromptInjection, repairJson, trimToTokens, chunkText, extractUrls, sanitizeHtml, flattenJson, unflattenJson, mergeJson, extractJson, deduplicateLines, extractKeywords, validateJsonSchema, diffJson, extractTables, extractEntities, compressHtml, compressMarkdown, compressJson, rerankChunks, scoreRelevance, expandQuery, summarizeForLlm } from "@utilix-tech/sdk/ai_agent";
+import { estimateTokens, estimateCost, detectPii, redactPii, detectSecrets, detectPromptInjection, repairJson, trimToTokens, chunkText, extractUrls, sanitizeHtml, flattenJson, unflattenJson, mergeJson, extractJson, deduplicateLines, extractKeywords, validateJsonSchema, diffJson as diffJsonDetailed, extractTables, extractEntities, compressHtml, compressMarkdown, compressJson, rerankChunks, scoreRelevance, expandQuery, summarizeForLlm } from "@utilix-tech/sdk/ai_agent";
 var CRON_DAY_MAP = {
   SUN: "0",
   MON: "1",
@@ -1112,8 +1113,8 @@ server.tool("extract_keywords", "Extract top keywords using TF-IDF scoring.", {
 server.tool("validate_json_schema", "Validate JSON data against a JSON Schema (Draft-07).", { data: z.unknown(), schema: z.record(z.unknown()) }, async ({ data, schema }) => {
   return { content: [{ type: "text", text: JSON.stringify(validateJsonSchema(data, schema), null, 2) }] };
 });
-server.tool("diff_json", "Diff two JSON objects \u2014 returns added, removed, changed, and unchanged paths.", { a: z.unknown(), b: z.unknown() }, async ({ a, b }) => {
-  return { content: [{ type: "text", text: JSON.stringify(diffJson(a, b), null, 2) }] };
+server.tool("diff_json_detailed", "Diff two JSON objects (parsed values, not strings) \u2014 returns a flat list of every path with its op (added/removed/changed/unchanged), plus counts.", { a: z.unknown(), b: z.unknown() }, async ({ a, b }) => {
+  return { content: [{ type: "text", text: JSON.stringify(diffJsonDetailed(a, b), null, 2) }] };
 });
 server.tool("extract_tables", "Extract HTML tables into JSON arrays with headers and rows.", { html: z.string() }, async ({ html }) => {
   return { content: [{ type: "text", text: JSON.stringify(extractTables(html), null, 2) }] };
@@ -1142,5 +1143,260 @@ server.tool("expand_query", "Expand a search query with synonyms and stemmed var
 server.tool("summarize_for_llm", "Extractive summarization \u2014 pick key sentences to fit a token budget.", { text: z.string(), max_tokens: z.number().int().min(10).default(200), strategy: z.enum(["extractive", "first", "last"]).default("extractive") }, async ({ text: text2, max_tokens, strategy }) => {
   return { content: [{ type: "text", text: JSON.stringify(summarizeForLlm(text2, max_tokens, strategy), null, 2) }] };
 });
+var _BE_VERBS = /* @__PURE__ */ new Set(["am", "is", "are", "was", "were", "be", "been", "being"]);
+var _IRREGULAR_PARTICIPLES = /* @__PURE__ */ new Set([
+  "awoken",
+  "been",
+  "become",
+  "begun",
+  "bent",
+  "bet",
+  "bitten",
+  "bled",
+  "blown",
+  "born",
+  "bought",
+  "bound",
+  "bred",
+  "broken",
+  "brought",
+  "built",
+  "burnt",
+  "burst",
+  "caught",
+  "chosen",
+  "clung",
+  "come",
+  "cost",
+  "crept",
+  "cut",
+  "dealt",
+  "dived",
+  "done",
+  "drawn",
+  "dreamt",
+  "driven",
+  "drunk",
+  "dug",
+  "eaten",
+  "fallen",
+  "fed",
+  "felt",
+  "fit",
+  "fled",
+  "flown",
+  "forbidden",
+  "forgiven",
+  "forgotten",
+  "fought",
+  "found",
+  "frozen",
+  "given",
+  "gone",
+  "gotten",
+  "grown",
+  "hidden",
+  "held",
+  "hung",
+  "hurt",
+  "kept",
+  "knelt",
+  "knit",
+  "known",
+  "laid",
+  "lain",
+  "led",
+  "left",
+  "lent",
+  "let",
+  "lit",
+  "lost",
+  "made",
+  "meant",
+  "met",
+  "mistaken",
+  "paid",
+  "proven",
+  "put",
+  "quit",
+  "read",
+  "rid",
+  "ridden",
+  "risen",
+  "run",
+  "said",
+  "sat",
+  "sawn",
+  "seen",
+  "sent",
+  "set",
+  "sewn",
+  "shaken",
+  "shed",
+  "shone",
+  "shot",
+  "shown",
+  "shrunk",
+  "shut",
+  "sold",
+  "sought",
+  "sown",
+  "spent",
+  "spoken",
+  "spread",
+  "sprung",
+  "stolen",
+  "stood",
+  "stuck",
+  "stung",
+  "struck",
+  "strung",
+  "sung",
+  "sunk",
+  "swept",
+  "sworn",
+  "swum",
+  "swung",
+  "taken",
+  "taught",
+  "thought",
+  "thrown",
+  "told",
+  "torn",
+  "understood",
+  "upset",
+  "woken",
+  "won",
+  "worn",
+  "wound",
+  "woven",
+  "written"
+]);
+function _isPastParticiple(word) {
+  const w = word.toLowerCase();
+  if (_IRREGULAR_PARTICIPLES.has(w)) return true;
+  return w.length > 3 && /^[a-z]+ed$/.test(w);
+}
+function _splitIntoSentences(text2) {
+  const matches = text2.match(/[^.!?]+[.!?]*/g);
+  if (!matches) return [];
+  return matches.map((s) => s.trim()).filter((s) => s.length > 0);
+}
+function _detectPassiveVoice(text2) {
+  const sentences = _splitIntoSentences(text2);
+  const analyzed = sentences.map((sentence, index) => {
+    const words = sentence.match(/[a-zA-Z']+/g) ?? [];
+    const matches = [];
+    for (let i = 0; i < words.length; i++) {
+      if (!_BE_VERBS.has(words[i].toLowerCase())) continue;
+      let j = i + 1;
+      let adverbCount = 0;
+      while (j < words.length && adverbCount < 2 && /ly$/i.test(words[j]) && !_isPastParticiple(words[j])) {
+        j++;
+        adverbCount++;
+      }
+      if (j < words.length && _isPastParticiple(words[j])) {
+        const hasAgent = words.slice(j + 1, j + 5).some((w) => w.toLowerCase() === "by");
+        matches.push({ phrase: words.slice(i, j + 1).join(" "), hasAgent });
+        i = j;
+      }
+    }
+    return { index, text: sentence, isPassive: matches.length > 0, matches };
+  });
+  const totalSentences = analyzed.length;
+  const passiveSentences = analyzed.filter((s) => s.isPassive).length;
+  const passivePercent = totalSentences > 0 ? Math.round(passiveSentences / totalSentences * 1e3) / 10 : 0;
+  return { sentences: analyzed, totalSentences, passiveSentences, passivePercent };
+}
+var _PNG_COLOR_TYPES = { 0: "grayscale", 2: "rgb", 3: "palette", 4: "grayscale+alpha", 6: "rgba" };
+var _JPEG_SOF_MARKERS = /* @__PURE__ */ new Set([192, 193, 194, 195, 197, 198, 199, 201, 202, 203, 205, 206, 207]);
+function _readImageInfo(bytes) {
+  if (bytes.length < 10) return { error: "File too small to determine format" };
+  if (bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71 && bytes[4] === 13 && bytes[5] === 10 && bytes[6] === 26 && bytes[7] === 10) {
+    if (bytes.length < 33) return { error: "Truncated PNG file" };
+    const width = (bytes[16] << 24 | bytes[17] << 16 | bytes[18] << 8 | bytes[19]) >>> 0;
+    const height = (bytes[20] << 24 | bytes[21] << 16 | bytes[22] << 8 | bytes[23]) >>> 0;
+    const bitDepth = bytes[24];
+    const colorTypeNum = bytes[25];
+    const colorType = _PNG_COLOR_TYPES[colorTypeNum] ?? "unknown";
+    const hasAlpha = colorTypeNum === 4 || colorTypeNum === 6;
+    return { format: "png", width, height, bitDepth, colorType, hasAlpha };
+  }
+  if (bytes[0] === 71 && bytes[1] === 73 && bytes[2] === 70) {
+    if (bytes.length < 10) return { error: "Truncated GIF file" };
+    const width = bytes[6] | bytes[7] << 8;
+    const height = bytes[8] | bytes[9] << 8;
+    return { format: "gif", width, height };
+  }
+  if (bytes[0] === 66 && bytes[1] === 77) {
+    if (bytes.length < 30) return { error: "Truncated BMP file" };
+    const width = bytes[18] | bytes[19] << 8 | bytes[20] << 16 | bytes[21] << 24;
+    const heightRaw = bytes[22] | bytes[23] << 8 | bytes[24] << 16 | bytes[25] << 24;
+    const bitDepth = bytes[28] | bytes[29] << 8;
+    return { format: "bmp", width: Math.abs(width), height: Math.abs(heightRaw), bitDepth };
+  }
+  if (bytes[0] === 82 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 70 && bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80) {
+    const fourCC = String.fromCharCode(bytes[12], bytes[13], bytes[14], bytes[15]);
+    if (fourCC === "VP8 ") {
+      if (bytes.length < 30) return { error: "Truncated WebP file" };
+      const width = (bytes[26] | bytes[27] << 8) & 16383;
+      const height = (bytes[28] | bytes[29] << 8) & 16383;
+      return { format: "webp", width, height };
+    }
+    if (fourCC === "VP8L") {
+      if (bytes.length < 25) return { error: "Truncated WebP file" };
+      const bits = bytes[21] | bytes[22] << 8 | bytes[23] << 16 | bytes[24] << 24;
+      const width = (bits & 16383) + 1;
+      const height = (bits >>> 14 & 16383) + 1;
+      const hasAlpha = !!(bits >>> 28 & 1);
+      return { format: "webp", width, height, hasAlpha };
+    }
+    if (fourCC === "VP8X") {
+      if (bytes.length < 30) return { error: "Truncated WebP file" };
+      const flags = bytes[20];
+      const hasAlpha = !!(flags & 16);
+      const width = (bytes[24] | bytes[25] << 8 | bytes[26] << 16) + 1;
+      const height = (bytes[27] | bytes[28] << 8 | bytes[29] << 16) + 1;
+      return { format: "webp", width, height, hasAlpha };
+    }
+    return { error: "Unrecognized WebP chunk format" };
+  }
+  if (bytes[0] === 255 && bytes[1] === 216) {
+    let offset = 2;
+    while (offset < bytes.length - 1) {
+      if (bytes[offset] !== 255) {
+        offset++;
+        continue;
+      }
+      const marker = bytes[offset + 1];
+      if (marker === 216 || marker === 1 || marker >= 208 && marker <= 215) {
+        offset += 2;
+        continue;
+      }
+      if (marker === 217) break;
+      if (offset + 3 >= bytes.length) break;
+      const segmentLength = bytes[offset + 2] << 8 | bytes[offset + 3];
+      if (_JPEG_SOF_MARKERS.has(marker)) {
+        if (offset + 9 >= bytes.length) return { error: "Truncated JPEG SOF segment" };
+        const bitDepth = bytes[offset + 4];
+        const height = bytes[offset + 5] << 8 | bytes[offset + 6];
+        const width = bytes[offset + 7] << 8 | bytes[offset + 8];
+        const components = bytes[offset + 9];
+        const colorType = components === 1 ? "grayscale" : components === 3 ? "rgb" : components === 4 ? "cmyk" : "unknown";
+        return { format: "jpeg", width, height, bitDepth, colorType };
+      }
+      offset += 2 + segmentLength;
+    }
+    return { error: "No SOF marker found in JPEG (file may be corrupt)" };
+  }
+  return { error: "Unrecognized image format \u2014 supported: PNG, JPEG, GIF, WebP, BMP" };
+}
+server.tool("detect_passive_voice", 'Heuristically flag sentences containing passive-voice constructions, e.g. "was written", "were approved by the team".', { text: z.string() }, async ({ text: text2 }) => {
+  return { content: [{ type: "text", text: JSON.stringify(_detectPassiveVoice(text2), null, 2) }] };
+});
+server.tool("read_image_info", "Read image format, dimensions, and color info directly from file bytes \u2014 no decoding required. Supports PNG, JPEG, GIF, WebP, BMP.", { image_base64: z.string().describe("Base64-encoded image bytes, optionally prefixed with a data: URL scheme") }, async ({ image_base64 }) => {
+  const bytes = new Uint8Array(Buffer.from(image_base64.replace(/^data:.*;base64,/, ""), "base64"));
+  return { content: [{ type: "text", text: JSON.stringify(_readImageInfo(bytes), null, 2) }] };
+});
 var transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@utilix-tech/mcp",
-  "version": "0.3.0",
-  "description": "MCP server exposing 70 Utilix developer tools to Claude, Cursor, VS Code Copilot, and any MCP-compatible AI assistant.",
+  "version": "0.4.0",
+  "description": "MCP server exposing 97 Utilix developer tools to Claude, Cursor, VS Code Copilot, and any MCP-compatible AI assistant.",
   "author": "Utilix <hello@utilix.tech>",
   "license": "MIT",
   "homepage": "https://utilix.tech/docs",
@@ -32,14 +32,15 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && chmod +x dist/index.js",
     "dev": "tsup --watch",
     "start": "node dist/index.js",
+    "test": "node scripts/check-duplicate-tools.mjs",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "@utilix-tech/sdk": "^0.1.4",
+    "@utilix-tech/sdk": "^0.2.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {

package/smithery.yaml

@@ -1,7 +1,8 @@
 name: utilix
-description: 70 developer utility tools — JSON, hashing, encoding, JWT, UUID, cron, color, SQL, regex, CSS, QR codes and more. All run locally, no API key required.
-homepage: https://utilix.tech
+description: 70 developer utility tools for Claude, Cursor, VS Code, Windsurf, and any MCP-compatible AI assistant. Covers JSON, hashing, encoding, JWT, UUID, cron, color, SQL, regex, CSS, QR codes, and more. All tools run locally — no API key required.
+homepage: https://utilix.tech/mcp
 license: MIT
+repository: https://github.com/utilix-tech/utilix-mcp
 
 startCommand:
   type: stdio