@coo-quack/calc-mcp 1.4.0 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v1.5.0 (2026-02-11)
+
+### Features
+
+- **Password generation** — fine-grained options: `uppercase`, `numbers`, `symbols` (on/off), `readable` mode (excludes ambiguous chars like l/1/I/O/0/o), `excludeChars` for custom exclusions
+- **Shuffle** — Fisher-Yates algorithm with `crypto.getRandomValues` for unbiased list shuffling
+
+### Documentation
+
+- README title: `@coo-quack/calc-mcp` → `Calc MCP`
+- Added "Why?" section with AI-alone vs calc-mcp comparison
+- Quick Start moved to top
+- Install guides consolidated (Claude Desktop/Cursor/Windsurf share same JSON format)
+
+### Tests
+
+- Random tool tests: 12 → 27 (+15)
+- Total: 194 tests, 280 assertions
+
 ## v1.4.0 (2026-02-11)
 
 ### Features

package/README.md

@@ -1,10 +1,35 @@
-# @coo-quack/calc-mcp
+# Calc MCP
 
 [![npm version](https://img.shields.io/npm/v/@coo-quack/calc-mcp)](https://www.npmjs.com/package/@coo-quack/calc-mcp)
 [![CI](https://github.com/coo-quack/calc-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/coo-quack/calc-mcp/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-An MCP server with 21 tools for things AI is bad at — math, hashing, encoding, date arithmetic, and more.
+**21 tools for things AI is bad at** — deterministic math, cryptographic randomness, accurate date arithmetic, encoding, hashing, and more.
+
+LLMs hallucinate calculations, can't generate true random numbers, and struggle with timezones. This MCP server fixes that.
+
+### Quick Start
+
+```bash
+# Claude Code
+claude mcp add -s user calc-mcp -- npx -y @coo-quack/calc-mcp
+
+# Or just run it
+npx -y @coo-quack/calc-mcp
+```
+
+> Works with Claude Desktop, VS Code Copilot, Cursor, Windsurf — [setup guides below](#install).
+
+---
+
+## Why?
+
+| AI alone | With calc-mcp |
+|----------|---------------|
+| "10 + 34 × 341 ÷ 23 = 507.8" ❌ | `514.087` ✅ (math) |
+| "Here's a UUID: 550e8400-..." 🤷 fake | Cryptographically random UUID v4/v7 ✅ (random) |
+| "100 days from now is..." 🤔 guess | `2026-05-22` ✅ (date) |
+| "SHA-256 of password123 is..." 💀 hallucinated | `ef92b778bafe...` ✅ (hash) |
 
 ## Examples
 
@@ -43,7 +68,8 @@ Ask in natural language — the AI picks the right tool automatically.
 | You ask | You get | Tool |
 |---------|---------|------|
 | Generate a UUID v7 | `019c4b54-aad2-7e52-...` | random |
-| Generate a 20-char password | `h#tjZDojX6sH!RJt8vaS` | random |
+| Generate a readable 20-char password | `hT9jZDojX6sHRJt8vaKS` | random |
+| Shuffle ["Alice", "Bob", "Charlie"] | `["Charlie", "Alice", "Bob"]` | random |
 
 ### Conversion
 
@@ -71,14 +97,14 @@ Ask in natural language — the AI picks the right tool automatically.
 | Decode this JWT: eyJhbGci... | `{ alg: "HS256", name: "John Doe" }` | jwt_decode |
 | Parse https://example.com/search?q=hello | `host: example.com, q: "hello"` | url_parse |
 
-## All Tools
+## All 21 Tools
 
 | Tool | Description |
 |------|-------------|
 | `math` | Evaluate expressions, statistics |
 | `count` | Characters (grapheme-aware), words, lines, bytes |
 | `datetime` | Current time, timezone conversion, UNIX timestamps |
-| `random` | UUID v4/v7, ULID, passwords, random numbers |
+| `random` | UUID v4/v7, ULID, passwords (readable, custom charset), shuffle |
 | `hash` | MD5, SHA-1, SHA-256, SHA-512, CRC32 |
 | `base64` | Encode / decode |
 | `encode` | URL, HTML entity, Unicode escape |
@@ -91,7 +117,7 @@ Ask in natural language — the AI picks the right tool automatically.
 | `luhn` | Validate / generate check digits |
 | `ip` | IPv4/IPv6 info, CIDR range |
 | `color` | HEX ↔ RGB ↔ HSL |
-| `convert` | 8 categories, 72 units: length (m, km, mi, ft, ...), weight (kg, lb, oz, ...), temperature (°C, °F, K), area (m², ha, acre, tsubo, tatami), volume (l, gal, cup, tbsp, ...), speed (km/h, mph, kn, ...), data (kb, mb, gb, tb, ...), time (ms, s, min, h, d, wk, mo, yr) |
+| `convert` | 8 categories, 72 units: length, weight, temperature, area (tsubo, tatami), volume, speed, data, time |
 | `char_info` | Unicode code point, block, category |
 | `jwt_decode` | Decode header + payload (no verification) |
 | `url_parse` | Protocol, host, path, params, hash |
@@ -105,12 +131,16 @@ Ask in natural language — the AI picks the right tool automatically.
 claude mcp add -s user calc-mcp -- npx -y @coo-quack/calc-mcp
 ```
 
-### Claude Desktop
+### Claude Desktop / Cursor / Windsurf
 
 Add to your config file:
 
-- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
+| App | Config path |
+|-----|-------------|
+| Claude Desktop (macOS) | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Claude Desktop (Windows) | `%APPDATA%\Claude\claude_desktop_config.json` |
+| Cursor | `~/.cursor/mcp.json` |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` |
 
 ```json
 {
@@ -138,57 +168,12 @@ Add to `.vscode/mcp.json` in your workspace:
 }
 ```
 
-Or add globally via settings.json:
-
-```json
-{
-  "mcp": {
-    "servers": {
-      "calc-mcp": {
-        "command": "npx",
-        "args": ["-y", "@coo-quack/calc-mcp"]
-      }
-    }
-  }
-}
-```
-
-### Cursor
-
-Add to `~/.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "calc-mcp": {
-      "command": "npx",
-      "args": ["-y", "@coo-quack/calc-mcp"]
-    }
-  }
-}
-```
-
-### Windsurf
-
-Add to `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "calc-mcp": {
-      "command": "npx",
-      "args": ["-y", "@coo-quack/calc-mcp"]
-    }
-  }
-}
-```
-
 ## Development
 
 ```bash
 bun install
 bun run dev       # Start dev server
-bun test          # 160 tests
+bun test          # Run tests
 bun run lint      # Biome
 bun run format    # Biome
 ```

package/dist/index.js

@@ -75870,16 +75870,56 @@ var tool17 = {
 
 // src/tools/random.ts
 var schema18 = {
-  type: exports_external.enum(["uuid", "ulid", "password", "number"]).describe("Type of random value to generate"),
+  type: exports_external.enum(["uuid", "ulid", "password", "number", "shuffle"]).describe("Type of random value to generate: uuid, ulid, password, number, or shuffle"),
   uuidVersion: exports_external.enum(["v4", "v7"]).optional().describe("UUID version: v4 (random, default) or v7 (time-ordered)"),
   length: exports_external.number().int().min(1).max(256).optional().describe("Length for password generation (default: 16)"),
   min: exports_external.number().optional().describe("Minimum value for number generation (default: 0)"),
   max: exports_external.number().optional().describe("Maximum value for number generation (default: 100)"),
-  charset: exports_external.string().optional().describe("Character set for password generation")
+  charset: exports_external.string().optional().describe("Custom character set for password (overrides uppercase/numbers/symbols options)"),
+  uppercase: exports_external.boolean().optional().describe("Include uppercase letters in password (default: true)"),
+  numbers: exports_external.boolean().optional().describe("Include numbers in password (default: true)"),
+  symbols: exports_external.boolean().optional().describe("Include symbols in password (default: true)"),
+  excludeChars: exports_external.string().optional().describe('Characters to exclude from password (e.g. "\\\\|{}")'),
+  readable: exports_external.boolean().optional().describe("Readable mode: excludes ambiguous characters (l/1/I/O/0/o) for easy reading"),
+  items: exports_external.array(exports_external.string()).optional().describe("Items to shuffle (for type=shuffle)")
 };
 var inputSchema18 = exports_external.object(schema18);
-var DEFAULT_CHARSET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789!@#$%^&*";
+var LOWERCASE = "abcdefghijklmnopqrstuvwxyz";
+var UPPERCASE = "ABCDEFGHIJKLMNOPQRSTUVWXYZ";
+var NUMBERS = "0123456789";
+var SYMBOLS = "!@#$%^&*()-_=+[]{}|;:,.<>?/~`";
+var AMBIGUOUS = "lI1O0o";
 var ULID_ENCODING = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+function buildCharset(input) {
+  if (input.charset) {
+    let cs2 = input.charset;
+    if (input.excludeChars) {
+      const exclude = new Set(input.excludeChars);
+      cs2 = cs2.split("").filter((c) => !exclude.has(c)).join("");
+    }
+    if (cs2.length === 0)
+      throw new Error("Charset is empty after exclusions");
+    return cs2;
+  }
+  let cs = LOWERCASE;
+  if (input.uppercase !== false)
+    cs += UPPERCASE;
+  if (input.numbers !== false)
+    cs += NUMBERS;
+  if (input.symbols !== false)
+    cs += SYMBOLS;
+  if (input.readable) {
+    const ambiguous = new Set(AMBIGUOUS);
+    cs = cs.split("").filter((c) => !ambiguous.has(c)).join("");
+  }
+  if (input.excludeChars) {
+    const exclude = new Set(input.excludeChars);
+    cs = cs.split("").filter((c) => !exclude.has(c)).join("");
+  }
+  if (cs.length === 0)
+    throw new Error("Charset is empty after exclusions");
+  return cs;
+}
 function generatePassword(length, charset) {
   const array3 = new Uint32Array(length);
   crypto.getRandomValues(array3);
@@ -75933,6 +75973,18 @@ function generateULID() {
   }
   return timeStr + randomStr;
 }
+function shuffle(items) {
+  if (items.length === 0)
+    throw new Error("Items array must not be empty");
+  const result = [...items];
+  for (let i2 = result.length - 1;i2 > 0; i2--) {
+    const array3 = new Uint32Array(1);
+    crypto.getRandomValues(array3);
+    const j = array3[0] % (i2 + 1);
+    [result[i2], result[j]] = [result[j], result[i2]];
+  }
+  return result;
+}
 function execute18(input) {
   switch (input.type) {
     case "uuid":
@@ -75941,7 +75993,7 @@ function execute18(input) {
       return generateULID();
     case "password": {
       const length = input.length ?? 16;
-      const charset = input.charset ?? DEFAULT_CHARSET;
+      const charset = buildCharset(input);
       return generatePassword(length, charset);
     }
     case "number": {
@@ -75949,11 +76001,17 @@ function execute18(input) {
       const max3 = input.max ?? 100;
       return String(generateRandomNumber(min3, max3));
     }
+    case "shuffle": {
+      if (!input.items || input.items.length === 0) {
+        throw new Error("Items array is required for shuffle");
+      }
+      return JSON.stringify(shuffle(input.items));
+    }
   }
 }
 var tool18 = {
   name: "random",
-  description: "Generate random values: UUID, ULID, secure password, or random number",
+  description: "Generate random values: UUID, ULID, secure password (with fine-grained options), random number, or shuffle a list",
   schema: schema18,
   handler: async (args) => {
     const input = inputSchema18.parse(args);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@coo-quack/calc-mcp",
-	"version": "1.4.0",
+	"version": "1.5.0",
 	"type": "module",
 	"bin": {
 		"calc-mcp": "dist/index.js"