@coo-quack/calc-mcp 1.5.0 โ†’ 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (13) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/CONTRIBUTING.md +11 -0
  3. package/README.md +7 -5
  4. package/docs/.vitepress/config.ts +56 -0
  5. package/docs/.vitepress/theme/index.ts +4 -0
  6. package/docs/.vitepress/theme/style.css +21 -0
  7. package/docs/changelog.md +111 -0
  8. package/docs/examples.md +419 -0
  9. package/docs/index.md +101 -0
  10. package/docs/install.md +163 -0
  11. package/docs/public/logo.svg +79 -0
  12. package/docs/tools.md +427 -0
  13. package/package.json +8 -3
package/docs/index.md ADDED
@@ -0,0 +1,101 @@
1
+ ---
2
+ layout: home
3
+
4
+ hero:
5
+ name: Calc MCP
6
+ text: 21 tools for things AI is bad at
7
+ tagline: Deterministic math, cryptographic randomness, accurate date arithmetic, encoding, hashing, and more
8
+ actions:
9
+ - theme: brand
10
+ text: Get Started
11
+ link: /install
12
+ - theme: alt
13
+ text: View Tools
14
+ link: /tools
15
+ - theme: alt
16
+ text: GitHub
17
+ link: https://github.com/coo-quack/calc-mcp
18
+
19
+ features:
20
+ - icon: ๐Ÿงฎ
21
+ title: Precise Math
22
+ details: No more hallucinated calculations. Evaluate complex expressions with mathjs, compute statistics, all deterministic.
23
+ - icon: ๐ŸŽฒ
24
+ title: True Randomness
25
+ details: Cryptographically secure UUIDs, ULIDs, passwords, and shuffling. No fake random numbers from AI.
26
+ - icon: ๐Ÿ“…
27
+ title: Accurate Dates
28
+ details: Timezone conversion, date arithmetic, cron parsing. No more guessing what day it is 100 days from now.
29
+ - icon: ๐Ÿ”
30
+ title: Hashing & Encoding
31
+ details: SHA-256, Base64, URL encoding, JWT decoding. Real cryptographic operations, not hallucinated hashes.
32
+ - icon: ๐ŸŒˆ
33
+ title: Conversions
34
+ details: 8 categories, 72 units. Length, weight, temperature, area, volume, speed, data, time. Including Japanese units (tsubo, tatami).
35
+ - icon: ๐Ÿ”
36
+ title: Parsing & Validation
37
+ details: IP addresses, URLs, JSON, semver, Luhn checksums. Deterministic validation and parsing.
38
+ ---
39
+
40
+ ## Why Calc MCP?
41
+
42
+ LLMs are incredible at natural language understanding, but terrible at things that require **precision**.
43
+
44
+ | AI alone | With calc-mcp |
45
+ |----------|---------------|
46
+ | "10 + 34 ร— 341 รท 23 = 507.8" โŒ | `514.087` โœ… (math) |
47
+ | "Here's a UUID: 550e8400-..." ๐Ÿคท fake | Cryptographically random UUID v4/v7 โœ… (random) |
48
+ | "100 days from now is..." ๐Ÿค” guess | `2026-05-22` โœ… (date) |
49
+ | "SHA-256 of password123 is..." ๐Ÿ’€ hallucinated | `ef92b778bafe...` โœ… (hash) |
50
+
51
+ Calc MCP gives your AI assistant the tools to **delegate** these tasks to deterministic, tested code.
52
+
53
+ ## Quick Start
54
+
55
+ ```bash
56
+ # Claude Code
57
+ claude mcp add -s user calc-mcp -- npx -y @coo-quack/calc-mcp
58
+ ```
59
+
60
+ Works with **Claude Desktop**, **VS Code Copilot**, **Cursor**, **Windsurf** โ€” see [installation guides](/install).
61
+
62
+ ## Usage
63
+
64
+ Just ask in natural language. The AI picks the right tool automatically:
65
+
66
+ ```
67
+ You: What's 10 + 34 ร— 341 รท 23?
68
+ AI: [uses math tool] โ†’ 514.087
69
+
70
+ You: Generate a UUID v7
71
+ AI: [uses random tool] โ†’ 019c4b54-aad2-7e52-8a3b-...
72
+
73
+ You: What's 100 days after 2026-02-11?
74
+ AI: [uses date tool] โ†’ 2026-05-22
75
+
76
+ You: SHA-256 hash of "password123"
77
+ AI: [uses hash tool] โ†’ ef92b778bafe771e89b862eebf...
78
+ ```
79
+
80
+ See more [examples โ†’](/examples)
81
+
82
+ ## All 21 Tools
83
+
84
+ | Category | Tools |
85
+ |----------|-------|
86
+ | **Math** | math, count, convert, base |
87
+ | **Random** | random (UUID, ULID, password, number, shuffle) |
88
+ | **Dates** | datetime, date, cron_parse |
89
+ | **Text** | base64, encode, hash, regex, diff, char_info |
90
+ | **Validation** | json_validate, luhn, semver |
91
+ | **Parsing** | ip, color, jwt_decode, url_parse |
92
+
93
+ [View all tools โ†’](/tools)
94
+
95
+ ## Features
96
+
97
+ - โœ… **21 MCP tools** covering calculations, randomness, dates, encoding, parsing
98
+ - โœ… **Tested** โ€” 194 tests, 280 assertions, 92%+ coverage
99
+ - โœ… **Fast** โ€” Pure JavaScript/TypeScript, no heavy dependencies
100
+ - โœ… **Cross-platform** โ€” Works with Claude Desktop, VS Code, Cursor, Windsurf
101
+ - โœ… **MIT Licensed** โ€” Free to use, modify, distribute
package/docs/install.md ADDED
@@ -0,0 +1,163 @@
1
+ # Installation
2
+
3
+ Calc MCP works with any MCP-compatible client. Below are setup guides for popular AI assistants.
4
+
5
+ ## Claude Code
6
+
7
+ The fastest way to add Calc MCP to Claude Code:
8
+
9
+ ```bash
10
+ claude mcp add -s user calc-mcp -- npx --prefix /tmp -y @coo-quack/calc-mcp
11
+ ```
12
+
13
+ This adds the server to your user config (`~/.config/openclaw/config.yml`).
14
+
15
+ To verify it's working:
16
+
17
+ ```bash
18
+ claude mcp list
19
+ ```
20
+
21
+ You should see `calc-mcp` in the list.
22
+
23
+ ## Claude Desktop
24
+
25
+ Add to your Claude Desktop config file:
26
+
27
+ **macOS:**
28
+ ```bash
29
+ ~/Library/Application Support/Claude/claude_desktop_config.json
30
+ ```
31
+
32
+ **Windows:**
33
+ ```bash
34
+ %APPDATA%\Claude\claude_desktop_config.json
35
+ ```
36
+
37
+ **Config:**
38
+ ```json
39
+ {
40
+ "mcpServers": {
41
+ "calc-mcp": {
42
+ "command": "npx",
43
+ "args": ["--prefix", "/tmp", "-y", "@coo-quack/calc-mcp"]
44
+ }
45
+ }
46
+ }
47
+ ```
48
+
49
+ After editing, restart Claude Desktop. You should see "MCP" in the bottom-right corner with the 21 tools available.
50
+
51
+ ## Cursor
52
+
53
+ Add to `~/.cursor/mcp.json`:
54
+
55
+ ```json
56
+ {
57
+ "mcpServers": {
58
+ "calc-mcp": {
59
+ "command": "npx",
60
+ "args": ["--prefix", "/tmp", "-y", "@coo-quack/calc-mcp"]
61
+ }
62
+ }
63
+ }
64
+ ```
65
+
66
+ Restart Cursor after adding the config.
67
+
68
+ ## Windsurf
69
+
70
+ Add to `~/.codeium/windsurf/mcp_config.json`:
71
+
72
+ ```json
73
+ {
74
+ "mcpServers": {
75
+ "calc-mcp": {
76
+ "command": "npx",
77
+ "args": ["--prefix", "/tmp", "-y", "@coo-quack/calc-mcp"]
78
+ }
79
+ }
80
+ }
81
+ ```
82
+
83
+ Restart Windsurf after adding the config.
84
+
85
+ ## VS Code (GitHub Copilot)
86
+
87
+ For workspace-specific setup, add `.vscode/mcp.json` in your project:
88
+
89
+ ```json
90
+ {
91
+ "servers": {
92
+ "calc-mcp": {
93
+ "command": "npx",
94
+ "args": ["--prefix", "/tmp", "-y", "@coo-quack/calc-mcp"]
95
+ }
96
+ }
97
+ }
98
+ ```
99
+
100
+ Reload VS Code after creating the file.
101
+
102
+ ## Direct Usage
103
+
104
+ You can also run the server directly for testing:
105
+
106
+ ```bash
107
+ npx --prefix /tmp -y @coo-quack/calc-mcp
108
+ ```
109
+
110
+ Or install globally:
111
+
112
+ ```bash
113
+ npm install -g @coo-quack/calc-mcp
114
+ calc-mcp
115
+ ```
116
+
117
+ ## Troubleshooting
118
+
119
+ ### "npx: command not found"
120
+
121
+ Make sure Node.js (v18+) is installed:
122
+
123
+ ```bash
124
+ node --version
125
+ npm --version
126
+ ```
127
+
128
+ Install from [nodejs.org](https://nodejs.org/) if needed.
129
+
130
+ ### Tools not showing up
131
+
132
+ 1. **Restart the app** after editing the config file
133
+ 2. **Check the config path** โ€” make sure you edited the right file
134
+ 3. **Validate JSON** โ€” use a JSON validator to check for syntax errors
135
+ 4. **Check logs** โ€” Claude Desktop and other apps may have logs showing connection errors
136
+
137
+ ### "calc-mcp: command not found" inside a Node.js project
138
+
139
+ If you run `npx` inside a directory that contains `node_modules`, npx may fail with:
140
+
141
+ ```
142
+ sh: calc-mcp: command not found
143
+ ```
144
+
145
+ This happens because npx resolves the scoped package locally but fails to link the binary correctly. All the examples on this page already include the fix (`--prefix /tmp`), which forces npx to use a separate directory for package resolution:
146
+
147
+ ```bash
148
+ npx --prefix /tmp -y @coo-quack/calc-mcp
149
+ ```
150
+
151
+ ### Version info
152
+
153
+ To check the installed version:
154
+
155
+ ```bash
156
+ npx --prefix /tmp @coo-quack/calc-mcp --version
157
+ ```
158
+
159
+ ## Next Steps
160
+
161
+ - [View all tools โ†’](/tools)
162
+ - [See examples โ†’](/examples)
163
+ - [Read the changelog โ†’](/changelog)
package/docs/public/logo.svg ADDED
@@ -0,0 +1,79 @@
1
+ <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
2
+ <defs>
3
+ <!-- Background gradient -->
4
+ <linearGradient id="bgGrad" x1="0" y1="0" x2="1" y2="1">
5
+ <stop offset="0%" stop-color="#5CB85C"/>
6
+ <stop offset="100%" stop-color="#2E7D32"/>
7
+ </linearGradient>
8
+ <!-- Calculator body gradient -->
9
+ <linearGradient id="bodyGrad" x1="0" y1="0" x2="0" y2="1">
10
+ <stop offset="0%" stop-color="#FDFDFD"/>
11
+ <stop offset="100%" stop-color="#E8E8E8"/>
12
+ </linearGradient>
13
+ <!-- Display gradient -->
14
+ <linearGradient id="displayGrad" x1="0" y1="0" x2="0" y2="1">
15
+ <stop offset="0%" stop-color="#1A1A2E"/>
16
+ <stop offset="100%" stop-color="#16213E"/>
17
+ </linearGradient>
18
+ <!-- Green button gradient -->
19
+ <linearGradient id="greenBtn" x1="0" y1="0" x2="0" y2="1">
20
+ <stop offset="0%" stop-color="#6ABF47"/>
21
+ <stop offset="100%" stop-color="#4A8C2A"/>
22
+ </linearGradient>
23
+ <!-- Orange button gradient -->
24
+ <linearGradient id="orangeBtn" x1="0" y1="0" x2="0" y2="1">
25
+ <stop offset="0%" stop-color="#FF8C42"/>
26
+ <stop offset="100%" stop-color="#E8621A"/>
27
+ </linearGradient>
28
+ <!-- Gray button gradient -->
29
+ <linearGradient id="grayBtn" x1="0" y1="0" x2="0" y2="1">
30
+ <stop offset="0%" stop-color="#E0E0E0"/>
31
+ <stop offset="100%" stop-color="#BDBDBD"/>
32
+ </linearGradient>
33
+ <!-- Accent green button -->
34
+ <linearGradient id="accentBtn" x1="0" y1="0" x2="0" y2="1">
35
+ <stop offset="0%" stop-color="#4CAF50"/>
36
+ <stop offset="100%" stop-color="#2E7D32"/>
37
+ </linearGradient>
38
+ <!-- Shadow filter -->
39
+ <filter id="shadow" x="-10%" y="-10%" width="130%" height="130%">
40
+ <feDropShadow dx="0" dy="4" stdDeviation="8" flood-color="#000" flood-opacity="0.3"/>
41
+ </filter>
42
+ <filter id="btnShadow" x="-20%" y="-20%" width="140%" height="160%">
43
+ <feDropShadow dx="0" dy="2" stdDeviation="3" flood-color="#000" flood-opacity="0.15"/>
44
+ </filter>
45
+ <filter id="innerGlow">
46
+ <feDropShadow dx="0" dy="1" stdDeviation="1" flood-color="#FFF" flood-opacity="0.3"/>
47
+ </filter>
48
+ </defs>
49
+
50
+ <!-- Background rounded square -->
51
+ <rect x="0" y="0" width="512" height="512" rx="96" ry="96" fill="url(#bgGrad)"/>
52
+ <!-- Subtle highlight on top-left -->
53
+ <rect x="0" y="0" width="512" height="256" rx="96" ry="96" fill="url(#bgGrad)" opacity="0.15" style="filter: blur(2px)"/>
54
+
55
+ <!-- Calculator body -->
56
+ <rect x="88" y="64" width="336" height="400" rx="36" ry="36" fill="url(#bodyGrad)" filter="url(#shadow)"/>
57
+
58
+ <!-- Display -->
59
+ <rect x="116" y="92" width="280" height="88" rx="16" ry="16" fill="url(#displayGrad)"/>
60
+ <!-- Display dots -->
61
+ <circle cx="336" cy="136" r="4" fill="#4A5568" opacity="0.6"/>
62
+ <circle cx="356" cy="136" r="4" fill="#4A5568" opacity="0.6"/>
63
+ <circle cx="376" cy="136" r="4" fill="#48BB78"/>
64
+
65
+ <!-- Row 1: Green, Green, Orange -->
66
+ <rect x="116" y="204" width="76" height="60" rx="14" ry="14" fill="url(#greenBtn)" filter="url(#btnShadow)"/>
67
+ <rect x="218" y="204" width="76" height="60" rx="14" ry="14" fill="url(#greenBtn)" filter="url(#btnShadow)"/>
68
+ <rect x="320" y="204" width="76" height="60" rx="14" ry="14" fill="url(#orangeBtn)" filter="url(#btnShadow)"/>
69
+
70
+ <!-- Row 2: Gray, Gray, Orange -->
71
+ <rect x="116" y="284" width="76" height="60" rx="14" ry="14" fill="url(#grayBtn)" filter="url(#btnShadow)"/>
72
+ <rect x="218" y="284" width="76" height="60" rx="14" ry="14" fill="url(#grayBtn)" filter="url(#btnShadow)"/>
73
+ <rect x="320" y="284" width="76" height="60" rx="14" ry="14" fill="url(#orangeBtn)" filter="url(#btnShadow)"/>
74
+
75
+ <!-- Row 3: Gray, Gray, Accent Green -->
76
+ <rect x="116" y="364" width="76" height="60" rx="14" ry="14" fill="url(#grayBtn)" filter="url(#btnShadow)"/>
77
+ <rect x="218" y="364" width="76" height="60" rx="14" ry="14" fill="url(#grayBtn)" filter="url(#btnShadow)"/>
78
+ <rect x="320" y="364" width="76" height="60" rx="14" ry="14" fill="url(#accentBtn)" filter="url(#btnShadow)"/>
79
+ </svg>