@coo-quack/calc-mcp 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## v1.6.0 (2026-02-12)
+
+### Features
+
+- **Documentation site** — Full VitePress-powered docs at [coo-quack.github.io/calc-mcp](https://coo-quack.github.io/calc-mcp/) with tool reference, examples, install guides, and changelog (#13)
+
+### Documentation
+
+- Added documentation site link to README
+- Added release checklist to CONTRIBUTING.md (#15)
+- Updated npx examples with `--prefix /tmp` for better node_modules compatibility
+- Added common ignore patterns to .gitignore
+
+## 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/CONTRIBUTING.md

@@ -27,6 +27,17 @@ bun run build     # Build for production
 3. Register in `src/index.ts` — import and add to the `tools` array
 4. Update `README.md` — add to examples and tool table
 
+## Release Checklist
+
+When bumping a version:
+
+1. Update `CHANGELOG.md` with new version entry
+2. Update `docs/changelog.md` to match
+3. Review `docs/tools.md` — add/update any changed tool parameters or examples
+4. Review `docs/examples.md` — add examples for new features
+5. Review `README.md` — update tool table and examples if needed
+6. Create GitHub Release with release notes
+
 ## Pull Requests
 
 - Branch from `main`

package/README.md

@@ -1,10 +1,37 @@
-# @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.
+📖 **[Documentation](https://coo-quack.github.io/calc-mcp/)** — Full tool reference, examples, and install guides.
+
+**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 --prefix /tmp -y @coo-quack/calc-mcp
+
+# Or just run it
+npx --prefix /tmp -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 +70,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 +99,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 +119,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 |
@@ -102,22 +130,26 @@ Ask in natural language — the AI picks the right tool automatically.
 ### Claude Code
 
 ```bash
-claude mcp add -s user calc-mcp -- npx -y @coo-quack/calc-mcp
+claude mcp add -s user calc-mcp -- npx --prefix /tmp -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
 {
   "mcpServers": {
     "calc-mcp": {
       "command": "npx",
-      "args": ["-y", "@coo-quack/calc-mcp"]
+      "args": ["--prefix", "/tmp", "-y", "@coo-quack/calc-mcp"]
     }
   }
 }
@@ -132,52 +164,7 @@ Add to `.vscode/mcp.json` in your workspace:
   "servers": {
     "calc-mcp": {
       "command": "npx",
-      "args": ["-y", "@coo-quack/calc-mcp"]
-    }
-  }
-}
-```
-
-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"]
+      "args": ["--prefix", "/tmp", "-y", "@coo-quack/calc-mcp"]
     }
   }
 }
@@ -188,7 +175,7 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
 ```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/docs/.vitepress/config.ts

@@ -0,0 +1,56 @@
+import { defineConfig } from "vitepress";
+
+export default defineConfig({
+	title: "Calc MCP",
+	description: "21 tools for things AI is bad at",
+	base: "/calc-mcp/",
+
+	themeConfig: {
+		logo: "/logo.svg",
+
+		nav: [
+			{ text: "Home", link: "/" },
+			{ text: "Tools", link: "/tools" },
+			{ text: "Install", link: "/install" },
+			{ text: "Examples", link: "/examples" },
+			{ text: "Changelog", link: "/changelog" },
+		],
+
+		sidebar: [
+			{
+				text: "Guide",
+				items: [
+					{ text: "Getting Started", link: "/" },
+					{ text: "Installation", link: "/install" },
+					{ text: "Examples", link: "/examples" },
+				],
+			},
+			{
+				text: "Reference",
+				items: [
+					{ text: "All Tools", link: "/tools" },
+					{ text: "Changelog", link: "/changelog" },
+				],
+			},
+		],
+
+		socialLinks: [
+			{ icon: "github", link: "https://github.com/coo-quack/calc-mcp" },
+			{
+				icon: "npm",
+				link: "https://www.npmjs.com/package/@coo-quack/calc-mcp",
+			},
+		],
+
+		footer: {
+			message: "Released under the MIT License.",
+			copyright: "Copyright © 2026 coo-quack",
+		},
+
+		search: {
+			provider: "local",
+		},
+	},
+
+	head: [["link", { rel: "icon", href: "/calc-mcp/favicon.ico" }]],
+});

package/docs/.vitepress/theme/index.ts

@@ -0,0 +1,4 @@
+import DefaultTheme from "vitepress/theme";
+import "./style.css";
+
+export default DefaultTheme;

package/docs/.vitepress/theme/style.css

@@ -0,0 +1,21 @@
+:root {
+	--vp-c-brand-1: #00a000;
+	--vp-c-brand-2: #00c000;
+	--vp-c-brand-3: #00e000;
+	--vp-c-brand-soft: rgba(0, 160, 0, 0.14);
+}
+
+.dark {
+	--vp-c-brand-1: #00d000;
+	--vp-c-brand-2: #00b000;
+	--vp-c-brand-3: #00a000;
+	--vp-c-brand-soft: rgba(0, 208, 0, 0.16);
+}
+
+.vp-doc a {
+	color: var(--vp-c-brand-1);
+}
+
+.vp-doc a:hover {
+	color: var(--vp-c-brand-2);
+}

package/docs/changelog.md

@@ -0,0 +1,111 @@
+# Changelog
+
+All notable changes to Calc MCP are documented here.
+
+## v1.6.0 (2026-02-12)
+
+### Features
+
+- **Documentation site** — Full VitePress-powered docs at [coo-quack.github.io/calc-mcp](https://coo-quack.github.io/calc-mcp/) with tool reference, examples, install guides, and changelog (#13)
+
+### Documentation
+
+- Added documentation site link to README
+- Added release checklist to CONTRIBUTING.md (#15)
+- Updated npx examples with `--prefix /tmp` for better node_modules compatibility
+- Added common ignore patterns to .gitignore
+
+## 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
+
+- **Time conversion** — ms, s, min, h, d, wk, mo, yr (now 8 categories, 72 units)
+- **`--version` flag** — `npx @coo-quack/calc-mcp --version`
+
+### Improvements
+
+- serverInfo.version synced with package.json (was hardcoded "0.1.0")
+- Error messages now list all supported units on unknown unit
+- Semver test coverage: 9 → 23 tests
+- CI git config for tag authoring
+- README badges (npm, CI, license)
+- CONTRIBUTING.md added
+- GitHub topics set
+- README examples: Japanese text replaced with English alternatives
+
+## v1.3.0 (2026-02-11)
+
+### Documentation
+
+- Overhaul README with natural language examples (22 verified examples)
+- Add install guides for Claude Code, Claude Desktop, VS Code, Cursor, Windsurf
+- Add unit conversion coverage details (7 categories, 58 units)
+- Add encode/decode examples (Base64, URL, HTML)
+
+## v1.1.0 (2026-02-11)
+
+### Features
+
+- **random**: Add UUID v7 support (`uuidVersion: "v7"`) — Time-ordered UUIDs, ideal for database primary keys
+
+## v1.0.0 (2026-02-11)
+
+### Features
+
+Initial release with **21 MCP tools** for calculations and operations AI models struggle with:
+
+- **random** — UUID (v4), ULID, secure password, random number
+- **hash** — SHA-1, SHA-256, SHA-512, MD5
+- **base64** — Encode/decode Base64
+- **encode** — URL encode/decode, HTML entity encode/decode
+- **datetime** — Current time, convert, format, Unix timestamp
+- **count** — Character, word, line, byte counting (grapheme-aware)
+- **math** — Precise math evaluation via mathjs
+- **date** — Date arithmetic (add/subtract/diff)
+- **regex** — Test, match, replace with regex
+- **base** — Number base conversion (bin/oct/dec/hex/custom)
+- **diff** — Text diff between two strings
+- **json_validate** — JSON schema validation
+- **cron_parse** — Cron expression to human-readable description
+- **luhn** — Luhn algorithm validation (credit cards, etc.)
+- **ip** — IPv4/IPv6 parsing, CIDR subnet info
+- **color** — Color format conversion (hex/rgb/hsl/hwb)
+- **convert** — Unit conversion (length, weight, temp, data, time)
+- **char_info** — Unicode character info (codepoint, name, category)
+- **jwt_decode** — Decode JWT tokens (header + payload)
+- **url_parse** — URL parsing into components
+- **semver** — Semantic versioning operations (compare, satisfy, sort)
+
+### CI/CD
+
+- GitHub Actions: test + lint on push/PR
+- Publish workflow: test + lint gate before npm publish on tag
+
+### Infrastructure
+
+- Biome for linting and formatting
+- Renovate with OSV vulnerability alerts
+- 160 tests, 92%+ line coverage
+
+---
+
+For the latest changes, see [GitHub Releases](https://github.com/coo-quack/calc-mcp/releases).