@coo-quack/calc-mcp 1.5.0 → 1.6.1

package/docs/tools.md

@@ -0,0 +1,427 @@
+# All Tools
+
+Calc MCP provides 21 tools for operations that AI models struggle with. Each tool is designed to be called automatically by your AI assistant when you ask questions in natural language.
+
+## Math & Numbers
+
+### math
+
+Evaluate mathematical expressions or compute statistics on numbers.
+
+**Parameters:**
+- `expression` (string, optional) — Math expression to evaluate
+- `action` (enum, optional) — `eval` (default) or `statistics`
+- `values` (array of numbers, optional) — Array of numbers for statistics
+
+**Examples:**
+```
+What's 10 + 34 × 341 ÷ 23?
+→ 514.087
+
+Calculate mean and stddev of [1, 2, 3, 4, 5]
+→ { mean: 3, median: 3, stddev: 1.414, ... }
+```
+
+### count
+
+Count characters (grapheme-aware), words, lines, and bytes in text.
+
+**Parameters:**
+- `text` (string) — Text to analyze
+- `encoding` (enum, optional) — `utf8` (default) or `shift_jis` for byte count
+
+**Examples:**
+```
+How many characters in "Hello, World! 🌍"?
+→ 15 chars, 18 bytes
+
+Count words in "The quick brown fox"
+→ 4 words
+```
+
+### base
+
+Convert numbers between different bases (2–36).
+
+**Parameters:**
+- `value` (string | number) — Value to convert
+- `from` (number) — Source base (2–36)
+- `to` (number) — Target base (2–36)
+
+**Examples:**
+```
+Convert 255 to binary
+→ 11111111
+
+Convert FF from hex to decimal
+→ 255
+```
+
+### convert
+
+Convert between units across 8 categories: length, weight, temperature, area, volume, speed, data, time.
+
+**Parameters:**
+- `value` (number) — Value to convert
+- `from` (string) — Source unit
+- `to` (string) — Target unit
+- `category` (enum, optional) — Category (auto-detected if omitted)
+
+**Supported units:**
+- **Length:** m, km, cm, mm, in, ft, yd, mi, nm, um
+- **Weight:** kg, g, mg, lb, oz, t, st
+- **Temperature:** c, f, k (Celsius, Fahrenheit, Kelvin)
+- **Area:** m2, km2, cm2, ha, acre, ft2, in2, tsubo, jo, tatami
+- **Volume:** l, ml, m3, gal, qt, pt, cup, floz, tbsp, tsp
+- **Speed:** m/s, km/h, mph, kn, ft/s
+- **Data:** b, kb, mb, gb, tb, pb, bit, kbit, mbit
+- **Time:** ms, s, min, h, d, wk, mo, yr
+
+**Examples:**
+```
+100 miles in kilometers?
+→ 160.93 km
+
+72°F in Celsius?
+→ 22.22°C
+
+10 tsubo in square meters?
+→ 33.06 m²
+```
+
+## Random Generation
+
+### random
+
+Generate cryptographically random values: UUID, ULID, password, number, or shuffle a list.
+
+**Parameters:**
+- `type` (enum) — `uuid`, `ulid`, `password`, `number`, or `shuffle`
+- `uuidVersion` (enum, optional) — `v4` (random, default) or `v7` (time-ordered)
+- `length` (number, optional) — Length for password (default: 16, max: 256)
+- `min` (number, optional) — Minimum value for number (default: 0)
+- `max` (number, optional) — Maximum value for number (default: 100)
+- `charset` (string, optional) — Custom character set for password
+- `uppercase` (boolean, optional) — Include uppercase letters (default: true)
+- `numbers` (boolean, optional) — Include numbers (default: true)
+- `symbols` (boolean, optional) — Include symbols (default: true)
+- `excludeChars` (string, optional) — Characters to exclude (e.g., `"\\|{}"`)
+- `readable` (boolean, optional) — Exclude ambiguous characters (l/1/I/O/0/o)
+- `items` (array of strings, optional) — Items to shuffle (for `type=shuffle`)
+
+**Examples:**
+```
+Generate a UUID v7
+→ 019c4b54-aad2-7e52-8a3b-...
+
+Generate a readable 20-char password
+→ hT9jZDojX6sHRJt8vaKS
+
+Shuffle ["Alice", "Bob", "Charlie"]
+→ ["Charlie", "Alice", "Bob"]
+
+Random number between 1 and 100
+→ 42
+```
+
+## Date & Time
+
+### datetime
+
+Get current time, convert timezones, format datetime, or work with UNIX timestamps.
+
+**Parameters:**
+- `action` (enum) — `now`, `convert`, `format`, or `timestamp`
+- `timezone` (string, optional) — IANA timezone (e.g., `Asia/Tokyo`, `America/New_York`)
+- `datetime` (string, optional) — ISO8601 datetime string for convert/format
+- `fromTimezone` (string, optional) — Source timezone for conversion
+- `toTimezone` (string, optional) — Target timezone for conversion
+- `format` (string, optional) — Output format: `iso`, `date`, `time`, `full`, or Intl options
+- `timestamp` (number, optional) — UNIX timestamp in seconds for timestamp action
+
+**Examples:**
+```
+What time is it in New York?
+→ 2026-02-10T19:00:00-05:00
+
+Convert 1609459200 to ISO8601
+→ 2021-01-01T00:00:00Z
+```
+
+### date
+
+Perform date arithmetic: difference, add/subtract, get weekday, or convert to wareki (Japanese era).
+
+**Parameters:**
+- `action` (enum) — `diff`, `add`, `weekday`, or `wareki`
+- `date` (string) — Date string (ISO8601)
+- `date2` (string, optional) — Second date for diff
+- `amount` (number, optional) — Amount to add
+- `unit` (enum, optional) — `days`, `months`, `years`, `hours`, `minutes`
+
+**Examples:**
+```
+What's 100 days after 2026-02-11?
+→ 2026-05-22
+
+Difference between 2026-01-01 and 2026-12-31
+→ 364 days
+
+What day of the week is 2026-02-11?
+→ Wednesday (水曜日)
+```
+
+### cron_parse
+
+Parse cron expressions into human-readable descriptions and get next occurrences.
+
+**Parameters:**
+- `expression` (string) — Cron expression (5 fields: min hour dom mon dow)
+- `count` (number, optional) — Number of next occurrences to return (default: 5)
+- `timezone` (string, optional) — IANA timezone (default: UTC)
+
+**Examples:**
+```
+When does "30 9 * * 1-5" run?
+→ Mon–Fri at 9:30, next runs: ...
+```
+
+## Text Processing
+
+### hash
+
+Compute cryptographic hashes: MD5, SHA-1, SHA-256, SHA-512, CRC32.
+
+**Parameters:**
+- `input` (string) — String to hash
+- `algorithm` (enum) — `md5`, `sha1`, `sha256`, `sha512`, or `crc32`
+
+**Examples:**
+```
+SHA-256 hash of "password123"
+→ ef92b778bafe771e89b862eebf...
+
+MD5 of "hello world"
+→ 5eb63bbbe01eeed093cb22bb8f5acdc3
+```
+
+### base64
+
+Encode or decode Base64 strings.
+
+**Parameters:**
+- `input` (string) — String to encode or decode
+- `action` (enum) — `encode` or `decode`
+
+**Examples:**
+```
+Base64 encode "Hello World"
+→ SGVsbG8gV29ybGQ=
+
+Base64 decode "eyJhbGciOiJIUzI1NiJ9"
+→ {"alg":"HS256"}
+```
+
+### encode
+
+URL, HTML entity, or Unicode escape encoding/decoding.
+
+**Parameters:**
+- `input` (string) — String to encode or decode
+- `action` (enum) — `encode` or `decode`
+- `type` (enum) — `url`, `html`, or `unicode`
+
+**Examples:**
+```
+URL-encode "hello world"
+→ hello%20world
+
+HTML-decode "<script>"
+→ <script>
+```
+
+### regex
+
+Test, match, or replace with regular expressions.
+
+**Parameters:**
+- `pattern` (string) — Regular expression pattern
+- `flags` (string, optional) — Regex flags (g, i, m, etc.)
+- `text` (string) — Text to search
+- `action` (enum) — `match`, `test`, `replace`, or `matchAll`
+- `replacement` (string, optional) — Replacement string for replace
+
+**Examples:**
+```
+Extract numbers from "abc123def456"
+→ ["123", "456"]
+
+Replace all spaces with dashes in "hello world"
+→ "hello-world"
+```
+
+### diff
+
+Line diff or Levenshtein distance between two texts.
+
+**Parameters:**
+- `text1` (string) — First text
+- `text2` (string) — Second text
+- `action` (enum, optional) — `diff` (line diff, default) or `distance` (Levenshtein)
+
+**Examples:**
+```
+Edit distance: "kitten" → "sitting"
+→ 3
+
+Line diff between two texts
+→ - old line
+→ + new line
+```
+
+### char_info
+
+Get Unicode information about characters.
+
+**Parameters:**
+- `char` (string) — Character(s) to get info about
+
+**Examples:**
+```
+Unicode info for "€"
+→ U+20AC, Currency Symbols
+
+What's the code point for "🌍"?
+→ U+1F30D, Miscellaneous Symbols and Pictographs
+```
+
+## Validation & Parsing
+
+### json_validate
+
+Validate JSON, CSV, XML, or YAML format.
+
+**Parameters:**
+- `input` (string) — String to validate/parse
+- `format` (enum) — `json`, `csv`, `xml`, or `yaml`
+
+**Examples:**
+```
+Is '{"name":"test"}' valid JSON?
+→ valid, object, keys: ["name"]
+
+Validate CSV with 3 columns
+→ valid, 10 rows, 3 columns
+```
+
+### luhn
+
+Validate or generate Luhn check digits (credit cards, etc.).
+
+**Parameters:**
+- `number` (string) — Number string to validate or generate check digit for
+- `action` (enum, optional) — `validate` (default) or `generate`
+
+**Examples:**
+```
+Is 4539578763621486 a valid card number?
+→ true
+
+Generate check digit for 453957876362148
+→ 6
+```
+
+### semver
+
+Semantic versioning operations: compare, validate, or check range satisfaction.
+
+**Parameters:**
+- `action` (enum) — `compare`, `valid`, or `satisfies`
+- `version` (string) — Semver version string
+- `version2` (string, optional) — Second version for compare
+- `range` (string, optional) — Version range for satisfies (e.g., `^1.0.0`)
+
+**Examples:**
+```
+Does 1.5.3 satisfy ^1.0.0?
+→ true
+
+Compare 2.0.0 and 1.9.9
+→ 2.0.0 is greater
+```
+
+### ip
+
+IPv4/IPv6 address information, CIDR range calculations, and membership checks.
+
+**Parameters:**
+- `action` (enum) — `info`, `contains`, or `range`
+- `ip` (string, optional) — IP address
+- `cidr` (string, optional) — CIDR notation (e.g., `192.168.1.0/24`)
+- `target` (string, optional) — Target IP to check against CIDR
+
+**Examples:**
+```
+IP range of 192.168.1.0/24?
+→ 192.168.1.1 – .254 (254 hosts)
+
+Is 192.168.1.50 in 192.168.1.0/24?
+→ true
+```
+
+### color
+
+Convert between color formats: HEX ↔ RGB ↔ HSL.
+
+**Parameters:**
+- `color` (string) — Color value: `#hex`, `rgb(r,g,b)`, or `hsl(h,s%,l%)`
+- `to` (enum, optional) — `hex`, `rgb`, or `hsl` (returns all if omitted)
+
+**Examples:**
+```
+Convert #FF5733 to RGB
+→ rgb(255, 87, 51)
+
+Convert rgb(100, 200, 50) to HSL
+→ hsl(100, 60%, 49%)
+```
+
+### jwt_decode
+
+Decode JWT tokens (header + payload, no signature verification).
+
+**Parameters:**
+- `token` (string) — JWT token to decode
+
+**Examples:**
+```
+Decode this JWT: eyJhbGci...
+→ { header: { alg: "HS256" }, payload: { name: "John Doe" } }
+```
+
+### url_parse
+
+Parse URLs into components.
+
+**Parameters:**
+- `url` (string) — URL to parse
+
+**Examples:**
+```
+Parse https://example.com/search?q=hello
+→ host: example.com, pathname: /search, q: "hello"
+```
+
+---
+
+## Tool Categories Summary
+
+| Category | Count | Tools |
+|----------|-------|-------|
+| Math & Numbers | 4 | math, count, base, convert |
+| Random | 1 | random (5 types) |
+| Date & Time | 3 | datetime, date, cron_parse |
+| Text Processing | 6 | hash, base64, encode, regex, diff, char_info |
+| Validation & Parsing | 7 | json_validate, luhn, semver, ip, color, jwt_decode, url_parse |
+
+**Total: 21 tools**

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@coo-quack/calc-mcp",
-	"version": "1.5.0",
+	"version": "1.6.1",
 	"type": "module",
 	"bin": {
 		"calc-mcp": "dist/index.js"
@@ -12,13 +12,18 @@
 		"lint": "biome check .",
 		"format": "biome format . --write",
 		"changelog": "bunx changelogen",
-		"release": "bunx bumpp"
+		"release": "bunx bumpp",
+		"docs:dev": "vitepress dev docs",
+		"docs:build": "vitepress build docs",
+		"docs:preview": "vitepress preview docs"
 	},
 	"devDependencies": {
 		"@biomejs/biome": "^2.3.14",
 		"@types/bun": "latest",
-		"typescript": "^5.9.3"
+		"typescript": "^5.9.3",
+		"vitepress": "^1.6.4"
 	},
+	"homepage": "https://coo-quack.github.io/calc-mcp/",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/coo-quack/calc-mcp.git"

package/CHANGELOG.md

@@ -1,91 +0,0 @@
-# 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
-
-- **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
-
-- **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