@coo-quack/calc-mcp 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # 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

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

@@ -4,6 +4,8 @@
 [![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)
 
+📖 **[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.
@@ -12,10 +14,10 @@ LLMs hallucinate calculations, can't generate true random numbers, and struggle
 
 ```bash
 # Claude Code
-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
 
 # Or just run it
-npx -y @coo-quack/calc-mcp
+npx --prefix /tmp -y @coo-quack/calc-mcp
 ```
 
 > Works with Claude Desktop, VS Code Copilot, Cursor, Windsurf — [setup guides below](#install).
@@ -128,7 +130,7 @@ 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 / Cursor / Windsurf
@@ -147,7 +149,7 @@ Add to your config file:
   "mcpServers": {
     "calc-mcp": {
       "command": "npx",
-      "args": ["-y", "@coo-quack/calc-mcp"]
+      "args": ["--prefix", "/tmp", "-y", "@coo-quack/calc-mcp"]
     }
   }
 }
@@ -162,7 +164,7 @@ Add to `.vscode/mcp.json` in your workspace:
   "servers": {
     "calc-mcp": {
       "command": "npx",
-      "args": ["-y", "@coo-quack/calc-mcp"]
+      "args": ["--prefix", "/tmp", "-y", "@coo-quack/calc-mcp"]
     }
   }
 }

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).

package/docs/examples.md

@@ -0,0 +1,419 @@
+# Examples
+
+Ask in natural language — the AI picks the right tool automatically. Here are real examples you can try:
+
+## Math & Numbers
+
+### Calculations
+
+```
+What's 10 + 34 × 341 ÷ 23?
+→ 514.087 (math)
+
+Calculate sqrt(144) + 2^8
+→ 268 (math)
+
+What's the sum of [10, 20, 30, 40, 50]?
+→ 150 (math)
+```
+
+### Statistics
+
+```
+Calculate mean and stddev of [1, 2, 3, 4, 5]
+→ { mean: 3, median: 3, stddev: 1.414, min: 1, max: 5 } (math)
+
+What's the median of [100, 50, 200, 75, 150]?
+→ 100 (math)
+```
+
+### Base Conversion
+
+```
+Convert 255 to binary
+→ 11111111 (base)
+
+Convert FF from hex to decimal
+→ 255 (base)
+
+Convert 12 from decimal to base 5
+→ 22 (base)
+```
+
+### Card Validation
+
+```
+Is 4539578763621486 a valid card number?
+→ true (luhn)
+
+Generate check digit for 453957876362148
+→ 6 (luhn)
+```
+
+## Text & Encoding
+
+### Counting
+
+```
+How many characters in "Hello, World! 🌍"?
+→ 15 chars, 18 bytes (count)
+
+Count words in "The quick brown fox jumps"
+→ 5 words (count)
+
+How many lines in this text? (multiline input)
+→ 10 lines (count)
+```
+
+### Base64
+
+```
+Base64 encode "Hello World"
+→ SGVsbG8gV29ybGQ= (base64)
+
+Base64 decode "eyJhbGciOiJIUzI1NiJ9"
+→ {"alg":"HS256"} (base64)
+```
+
+### URL Encoding
+
+```
+URL-encode "hello world"
+→ hello%20world (encode)
+
+URL-decode "hello%20world"
+→ "hello world" (encode)
+
+HTML-encode "<script>alert('XSS')</script>"
+→ &lt;script&gt;alert(&#39;XSS&#39;)&lt;/script&gt; (encode)
+
+HTML-decode "&lt;script&gt;"
+→ <script> (encode)
+```
+
+### Hashing
+
+```
+SHA-256 hash of "password123"
+→ ef92b778bafe771e89b862eebf... (hash)
+
+MD5 of "hello world"
+→ 5eb63bbbe01eeed093cb22bb8f5acdc3 (hash)
+
+CRC32 checksum of "test"
+→ d87f7e0c (hash)
+```
+
+## Date & Time
+
+### Current Time
+
+```
+What time is it in New York?
+→ 2026-02-10T19:00:00-05:00 (datetime)
+
+What time is it in Tokyo?
+→ 2026-02-11T09:00:00+09:00 (datetime)
+
+What's the current UNIX timestamp?
+→ 1707638400 (datetime)
+```
+
+### Date Arithmetic
+
+```
+What's 100 days after 2026-02-11?
+→ 2026-05-22 (date)
+
+What's 30 days before 2026-03-01?
+→ 2026-01-30 (date)
+
+Add 6 months to 2026-01-15
+→ 2026-07-15 (date)
+```
+
+### Date Differences
+
+```
+How many days between 2026-01-01 and 2026-12-31?
+→ 364 days (date)
+
+Difference in months between 2025-01-01 and 2026-01-01
+→ 12 months (date)
+```
+
+### Weekdays
+
+```
+What day of the week is 2026-02-11?
+→ Wednesday (水曜日) (date)
+```
+
+### Cron Expressions
+
+```
+When does "30 9 * * 1-5" run?
+→ Mon–Fri at 9:30 (cron_parse)
+
+Parse "0 0 1 * *"
+→ Monthly on the 1st at midnight (cron_parse)
+
+Next 5 runs of "*/15 * * * *"
+→ Every 15 minutes: 10:00, 10:15, 10:30... (cron_parse)
+```
+
+## Generation
+
+### UUIDs
+
+```
+Generate a UUID v4
+→ 550e8400-e29b-41d4-a716-446655440000 (random)
+
+Generate a UUID v7 (time-ordered)
+→ 019c4b54-aad2-7e52-8a3b-... (random)
+
+Generate a ULID
+→ 01HN8B6ZK9PQRSTVWXY0123456 (random)
+```
+
+### Passwords
+
+```
+Generate a 20-character password
+→ hT9jZDojX6sHRJt8vaKS (random)
+
+Generate a readable password (no ambiguous chars)
+→ rTbPkWnF8sHuDxYz (random)
+
+Generate a 16-char password with only letters and numbers
+→ aB3dE5fG7hJ9kL2m (random)
+
+Generate a password without symbols
+→ xYz4AbC8DeFgHiJk (random)
+```
+
+### Random Numbers
+
+```
+Random number between 1 and 100
+→ 42 (random)
+
+Random number between 1 and 6 (dice roll)
+→ 4 (random)
+```
+
+### Shuffle
+
+```
+Shuffle ["Alice", "Bob", "Charlie"]
+→ ["Charlie", "Alice", "Bob"] (random)
+
+Randomize order: ["A", "B", "C", "D", "E"]
+→ ["D", "A", "E", "B", "C"] (random)
+```
+
+## Conversion
+
+### Length
+
+```
+100 miles in kilometers?
+→ 160.93 km (convert)
+
+5 feet in meters?
+→ 1.524 m (convert)
+```
+
+### Temperature
+
+```
+72°F in Celsius?
+→ 22.22°C (convert)
+
+100°C in Fahrenheit?
+→ 212°F (convert)
+
+300 Kelvin in Celsius?
+→ 26.85°C (convert)
+```
+
+### Weight
+
+```
+10 pounds in kilograms?
+→ 4.536 kg (convert)
+
+500 grams in ounces?
+→ 17.637 oz (convert)
+```
+
+### Area (including Japanese units)
+
+```
+10 tsubo in square meters?
+→ 33.06 m² (convert)
+
+100 m² in tatami?
+→ 60.5 tatami (convert)
+
+1 acre in square meters?
+→ 4046.86 m² (convert)
+```
+
+### Data
+
+```
+5 GB in megabytes?
+→ 5120 MB (convert)
+
+1000 kilobytes in bits?
+→ 8192000 bits (convert)
+```
+
+### Time
+
+```
+3600 seconds in hours?
+→ 1 hour (convert)
+
+2 weeks in days?
+→ 14 days (convert)
+
+1000000 milliseconds in minutes?
+→ 16.667 minutes (convert)
+```
+
+## Analysis & Parsing
+
+### Regular Expressions
+
+```
+Extract numbers from "abc123def456"
+→ ["123", "456"] (regex)
+
+Does "hello@example.com" match an email pattern?
+→ true (regex)
+
+Replace all spaces with dashes in "hello world"
+→ "hello-world" (regex)
+```
+
+### Text Diff
+
+```
+Edit distance: "kitten" → "sitting"
+→ 3 (diff)
+
+Line diff between two code snippets
+→ - old line
+→ + new line
+→   unchanged line
+(diff)
+```
+
+### IP Addresses
+
+```
+IP range of 192.168.1.0/24?
+→ 192.168.1.1 – .254 (254 hosts) (ip)
+
+Is 192.168.1.50 in 192.168.1.0/24?
+→ true (ip)
+
+Parse IPv6 address 2001:db8::1
+→ { version: 6, address: "2001:0db8:0000:..." } (ip)
+```
+
+### Colors
+
+```
+Convert #FF5733 to RGB
+→ rgb(255, 87, 51) (color)
+
+Convert rgb(100, 200, 50) to HSL
+→ hsl(100, 60%, 49%) (color)
+
+Convert hsl(120, 100%, 50%) to HEX
+→ #00FF00 (color)
+```
+
+### Semver
+
+```
+Does 1.5.3 satisfy ^1.0.0?
+→ true (semver)
+
+Compare 2.0.0 and 1.9.9
+→ 2.0.0 is greater (semver)
+
+Is "1.2.3-beta.1" a valid semver?
+→ true (semver)
+```
+
+## Decode & Parse
+
+### JSON Validation
+
+```
+Is '{"name":"test"}' valid JSON?
+→ valid, object, keys: ["name"] (json_validate)
+
+Validate CSV with 3 columns
+→ valid, 10 rows, 3 columns (json_validate)
+
+Is this valid XML? (XML input)
+→ valid (json_validate)
+```
+
+### JWT Decoding
+
+```
+Decode this JWT: eyJhbGci...
+→ { 
+    header: { alg: "HS256", typ: "JWT" }, 
+    payload: { sub: "1234567890", name: "John Doe" } 
+  }
+(jwt_decode)
+```
+
+### URL Parsing
+
+```
+Parse https://example.com/search?q=hello&lang=en
+→ {
+    host: "example.com",
+    pathname: "/search",
+    searchParams: { q: "hello", lang: "en" }
+  }
+(url_parse)
+
+Extract query params from https://api.github.com/search?q=mcp&sort=stars
+→ { q: "mcp", sort: "stars" } (url_parse)
+```
+
+### Unicode Info
+
+```
+Unicode info for "€"
+→ U+20AC, Currency Symbols (char_info)
+
+What's the code point for "🌍"?
+→ U+1F30D, Miscellaneous Symbols and Pictographs (char_info)
+
+Character info for "あ"
+→ U+3042, Hiragana (char_info)
+```
+
+---
+
+## Tips for Natural Language Queries
+
+The AI automatically selects the right tool based on your question. For best results:
+
+1. **Be specific** — "Convert 100°F to Celsius" is better than "temperature conversion"
+2. **Include units** — "5 miles in km" is clearer than "5 miles"
+3. **Use examples** — "Extract numbers from 'abc123'" shows what you want
+4. **Ask naturally** — The AI understands conversational queries
+
+Try asking in your own words — the AI will figure it out! 🚀