DEV Community: chataclaw

Put an AI Gatekeeper Behind nginx: Screen Attack Requests with vigilant-heron in 10 Minutes

chataclaw — Tue, 27 Oct 2026 17:01:16 +0000

Say this request arrives at your site:

GET /?id=1%20UNION%20SELECT%20password%20FROM%20users

A signature WAF drops it on the UNION SELECT rule. But attackers keep varying the shape, so a payload written differently slips past any rule set you maintain. Sending every request to an AI model has the opposite price tag: latency, cost, false positives, and shipping request bodies to an external API.

vigilant-heron is a Rust reverse proxy built to sit between those two. Behind nginx or Cloudflare, it blocks obvious attacks with fixed rules and sends only the undecided remainder to a decision model that returns attack scores. The request above gets this log line:

{"action":"allow","reason":"rule","rule_id":"vh-sqli-001","would_have":"block"}

Rule vh-sqli-001 calls it an attack; shadow mode lets it through while recording that enforce mode would have answered 403. Getting here takes under ten minutes, and the barriers to trying it are low:

On Linux, drop in a single binary. Docker and cargo build work too.
The configuration is about ten lines and looks like nginx.
Shadow mode blocks nothing, so you can put it in front of a live site and just watch.
The model is swappable: Jev, Clef, self-hosted Strands Decider, or your own HTTP endpoint.
The whole evaluation run cost ¥6.63 in model API calls.

This article shows the overall design, a hands-on run from install to a blocked test attack, and then the design decisions: the evaluation order, what reaches the model, and what happens when the model cannot answer.

The overall shape

client ──► nginx / Cloudflare ──► vigilant-heron ──► your site (upstream)
                                      │
                                      └──► decision model (Jev, Clef, Strands Decider, or your own)

Screening has two stages.
The first stage is fixed rules: known patterns such as SQL injection and path traversal are blocked without asking any model.
The second stage is the decision model, which scores the requests the rules left undecided.
The model is swappable: TypeSafe's Jev, Cloudflare Workers AI's Clef, a self-hosted Strands Decider, or an HTTP endpoint of your own.

One principle governs the order: a rule's decision cannot be overturned by the model.
A request matched by a block rule never reaches the model, and no model answer can turn that block into an allow.
In the other direction, plain requests for images, CSS and JavaScript skip the model entirely.
Model calls happen only for the remainder that neither a rule nor a skip decided.

The configuration is written in an nginx-like syntax: the listen address, per-site upstreams, the model choice, rate limits, and logging, all in one file.

Hands-on: from install to a blocked attack

This follows the official Getting started. We will start a test upstream, run the router in shadow mode, send a SQL injection, and switch to enforce.

Install

On Linux, download a release binary (x86_64 or aarch64, glibc 2.39 or newer):

ARCH=$(uname -m)   # x86_64 or aarch64
curl -fsSLO "https://github.com/coo-quack/vigilant-heron/releases/latest/download/vigilant-heron-$ARCH-unknown-linux-gnu.tar.gz"
tar -xzf "vigilant-heron-$ARCH-unknown-linux-gnu.tar.gz"
sudo install -m 755 "vigilant-heron-$ARCH-unknown-linux-gnu/vigilant-heron" /usr/local/bin/

On macOS, build from source. The toolchain named by rust-toolchain.toml installs on the first build:

git clone https://github.com/coo-quack/vigilant-heron.git
cd vigilant-heron
cargo build --release --locked

A Docker image is published as well:

docker run --rm ghcr.io/coo-quack/vigilant-heron:latest --version

Start a test upstream

Instead of a real application, serve a folder with Python's built-in web server. Keep it running in its own terminal:

mkdir -p site && echo "hello from the upstream" > site/index.html
python3 -m http.server 3000 --bind 127.0.0.1 --directory site

Write a minimal configuration

Save this as vigilant-heron.conf. It listens on port 8080 and forwards requests for example.com to port 3000:

listen 127.0.0.1:8080;              # the address the router listens on
pid vigilant-heron.pid;             # where the router writes its process id

decision {
    backend jev;                    # the decision model; reads its key from TYPESAFE_API_KEY
}

site example.com {
    upstream http://127.0.0.1:3000; # where allowed requests go
    mode shadow;                    # record decisions, block nothing
}

While mode shadow; is set, the router forwards every request and only records what it would have blocked.

Check the file and start the router

-t reads and validates the file, then exits. It starts nothing:

$ TYPESAFE_API_KEY=... vigilant-heron -t -c vigilant-heron.conf
configuration file vigilant-heron.conf test is successful

Start the router:

TYPESAFE_API_KEY=... vigilant-heron -c vigilant-heron.conf

Send a normal request and a test attack

From a second terminal, send an ordinary request:

curl -i http://127.0.0.1:8080/ -H "Host: example.com"

You get 200 OK with hello from the upstream.

Now send a request whose query string carries a SQL injection:

curl -i "http://127.0.0.1:8080/?id=1%20UNION%20SELECT%20password%20FROM%20users" \
  -H "Host: example.com"

Shadow mode forwards this too, so the answer is still 200 OK. The router's terminal shows what it would have done:

{"status":"200","action":"allow","reason":"rule","rule_id":"vh-sqli-001","would_have":"block",...}

rule_id is the built-in rule that matched; vh-sqli-001 matches UNION SELECT in a query string.
would_have is block, which means enforce mode would have answered 403.
action is allow because shadow mode forwarded the request.

Switch to enforce

Read the shadow log until the would-be blocks are the ones you expect, change mode shadow; to mode enforce;, and signal the router to reload. The new file applies without a restart, and connections stay up:

vigilant-heron -s reload -c vigilant-heron.conf

Send the test attack again. The response is now 403 Forbidden, and the upstream never sees the request. The ordinary request still returns 200 OK.

Put nginx in front

In production, nginx stays in front, terminates TLS, and passes the WebSocket headers, the Host the sites are matched on, and the client address:

upstream vigilant_heron {
    server 127.0.0.1:8080;
    keepalive 16;
}

server {
    listen 443 ssl;
    server_name example.com;

    location / {
        proxy_pass http://vigilant_heron;
        proxy_http_version 1.1;                                # WebSocket upgrades need HTTP/1.1
        proxy_set_header Host $host;                           # sites are matched on this header
        proxy_set_header X-Real-IP $remote_addr;               # the client address, read by real_ip_from
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

Add this to the router's configuration so the client address is trusted only from nginx:

real_ip_from 127.0.0.1;             # trust X-Real-IP only from nginx
real_ip_header X-Real-IP;

The evaluation order of each request

Each request goes through these steps, and the first step that decides it ends the evaluation:

Rate and connection limits (limit_req, limit_conn). A client over a limit is refused with the configured status (503 by default).
Host check. A Host header with characters that cannot appear in a host name gets 400.
Access list. A denied client address gets 403.
Block rules. The built-in rules that are on, then the top-level rules in file order, then the site's rules. The first match blocks.
Skip rules. The first match forwards the request without calling the model.
Static assets. A plain GET or HEAD for an image, CSS or JavaScript path, with no query and no body, is forwarded without the model.
Decision model. The remaining requests are scored, and the scores are compared with the site's thresholds.

Two properties are worth noting.

First, block rules are always checked before skip rules, so a skip rule can never let through a request that a block rule matches.

Second, the path is read in more than one way. Upstreams resolve the same bytes differently: Tomcat, Jetty and Spring drop ; path parameters, IIS and ASP.NET read \ as /, and Express matches the raw path. vigilant-heron reads each path six ways (decoded, with ; cut, with \ as /, combinations of these, and the raw path) and blocks when any reading matches. A static skip requires every reading to be static, so a path like /index.php/x.css is always inspected. The request that reaches the upstream is the one the client sent, unchanged.

What the model receives

Before a copy of the request is sent to the model, credentials are removed:

cookie, authorization, proxy-authorization, x-api-key and x-auth-token are always dropped, and so is any other header whose name looks like a credential, such as x-csrf-token or x-session-id.
Form, JSON, multipart and XML bodies are scanned for fields whose names contain password, token, secret, credential, card_number and similar parts, or a whole word like pass, pin, otp, session or ssn. The values are replaced with [REDACTED]. Names like author, shipping or passenger are sent as they are.
Only the first 8 KiB of the body is sent by default, cut on a UTF-8 boundary, with a flag when truncation happened.

All client data sits under untrusted, telling the model to read it as data, not instructions:

{"event": {
  "untrusted": {"method": "POST", "path": "/login", "query": null,
                "headers": [["user-agent", "…"]], "body": "user=alice&password=[REDACTED]"},
  "meta": {"host": "example.com", "client_ip": "203.0.113.7", "body_truncated": false}
}}

The model returns two scores between 0 and 1: attack (is this an attack?) and ai_instruction (does this request try to steer an AI or change how it is judged?):

{"attack": 0.02, "ai_instruction": 0.01}

Each site compares the scores with two thresholds: block_threshold (default 0.87) for attack and instruction_threshold (default 0.8) for ai_instruction. A score at or above its threshold blocks the request.

Four backends are available:

Jev (default): TypeSafe's Jev at api.typesafe.ai, with the key read from the TYPESAFE_API_KEY environment variable.
Clef: Cloudflare Workers AI, clef-flash or clef. Requires a URL with your account id and a token variable.
Strands Decider: an Apache-2.0 decision model you run yourself. It serves POST /v1/systemone, so the only required setting is the URL.
http: POSTs the JSON above to any endpoint you choose. Anything that answers {"attack": <number>, "ai_instruction": <number>} works.

Tokens are never written in the configuration file. api_token_env names an environment variable, and the router reads it at startup.

With third-party APIs (Jev, Clef), keep in mind that redaction is name-based and best-effort: a secret stored under a name without any of the listed words is sent as it is. Choose a backend you may disclose that data to, or run Strands Decider locally. The Security page spells this out.

Access logs contain the client address, method, path, status and decision fields — never a body, a query string, or a credential header. A log format that references a credential header via $http_* is rejected when the configuration loads.

When the model cannot answer

Models fail: timeouts, connection errors, 429s, unparseable answers. vigilant-heron groups the failures and lets you set the behavior per group:

on_rate_limit: the backend's HTTP 429, and saturation (no free concurrency slot within queue_timeout). Defaults to allow.
on_client_busy: the client already holds its share of in-flight model calls (max_concurrency_per_client, default 8). Defaults to a 429 refusal.
on_decision_error: timeouts, connection failures, malformed or out-of-range answers. Defaults to allow.

None of these touch rule decisions. A rule block stays a block whether the model is down, slow, or saturated.

The allow defaults exist so that a provider outage does not block legitimate traffic. The trade-off is that an attacker who deliberately saturates the model gets requests past it. For paths that must stay safe, set fail_closed_path: a failed decision on those prefixes is blocked whatever the settings say.

site example.com {
    upstream http://app:8080;
    on_decision_error block;
    fail_closed_path /wp-login.php /wp-admin;
}

Here, decision errors normally block, rate limits allow, and the login paths block on any failure.

Built-in rules

Twenty-four built-in rules ship in the binary and are on by default. The categories are SQL injection, XSS, path traversal, command injection, file inclusion, SSRF, template and expression injection, XXE, and known scanner user agents. For example, vh-sqli-001 matches UNION SELECT in a query string, vh-ssrf-001 matches the cloud metadata address 169.254.169.254, and vh-expr-001 matches the Log4Shell form ${jndi:.

The rules are written to miss an attack rather than block ordinary traffic. Patterns that could appear in a code paste or a post about SQL or HTML are deliberately left out; such requests go to the decision model instead. As a consequence, most rules inspect query strings. In the measurement, the built-in rules blocked no allowed request on either split.

Opt-in virtual patches for known CVEs ship off by default. For instance, vh-cve-2026-9103 and vh-cve-2026-8481 cover IBM Langflow OSS and are enabled per site with enable_rule where that product runs.

Measurements

The models and rules were measured on a labelled dataset. It is synthetic and small — about 85 attacks and 110 allowed requests per split. Thresholds were chosen on the dev split, so only the holdout figures are out of sample. Treat the numbers as a starting point for shadow mode on your own traffic, not as a guarantee.

With the attack threshold chosen on dev (the highest recall at a dev false-positive rate of 2% or less):

Backend	Threshold	Dev recall / FPR	Holdout recall / FPR
jev-latest	0.87	0.871 / 0.018	0.892 / 0.009
clef-flash	0.88	0.694 / 0.018	0.723 / 0.000

On the ai_instruction side, a threshold of 0.8 blocked no allowed request and still blocked all 15 prompt-injection rows on both splits.

Combined with the built-in rules, Jev showed zero false positives and gained recall in every split. The models' weak spots also showed: both miss most scanner probes like /.env and /.git/config, which deterministic deny_path entries handle better.

Latency, measured from a home connection in Japan through the router: a decision p50 of about 146 ms for Jev and 375 ms for clef-flash. 82% of clef-flash calls exceeded the default 300 ms timeout, so about 1000 ms is recommended for Clef. Strands Decider on a single NVIDIA L4 measured a p50 of 99 ms and a p95 of 436 ms for the 2B checkpoint¹.

A load test with a local stub backend (20 ms delay, Apple M2, 8 logical CPUs) reached 40.9 req/s at concurrency 1, 567.9 req/s at 16, and 2,525.8 req/s at 64 with a p95 of 27.7 ms.

What it cannot do

Credential stuffing. A client trying a hundred passwords never shows in a single-request verdict. Throttling is the job of limit_req on the path.
Triple encoding. Paths and queries are decoded at most twice. A payload encoded three times is not seen as the attack it encodes.
Beyond the inspected prefix. Both rules and models see only the first inspect_body bytes of a body.
WebSocket after the handshake. The upgrade is screened like any request; after a 101, frames are copied through without inspection.
Everything inside multipart. Multipart redaction is lexical, so a sensitive value can still reach the model in some layouts.

Summary

vigilant-heron blocks what fixed rules can block deterministically, and scores the rest with a decision model. Rule decisions cannot be overturned, model failures are configured per group, and static files never reach the model. Deployment starts in shadow mode, and one -s reload switches a site to enforce.

If this sounds useful:

Repository
Documentation — Getting started, How it works, Decision backends, Evaluation, Security

The Strands Decider figures come from the JevBench tasks, not from this router's questions. Also note that its server has no authentication (keep it on localhost or a private network), and the published checkpoints use a 4,096-token window that silently cuts long prompts at the end. ↩

Talk to Your AI — Meet Talkative Lobster

chataclaw — Thu, 12 Mar 2026 12:09:16 +0000

Have you ever wanted to just talk to your AI assistant? Like, literally speak into your microphone and hear it respond naturally?

I work with AI all day, and sometimes typing feels... slow. Copy-pasting is tedious. Sometimes I'm cooking, walking, or just tired of staring at a screen. I wanted something that felt like a real conversation.

So I built Talkative Lobster — a desktop app that turns your voice into AI conversation and back again.

What It Does

You speak  →  Speech-to-Text  →  LLM  →  Text-to-Speech  →  You hear

You talk into your mic, the AI thinks, and then speaks back to you. No typing, no copy-pasting — just natural back-and-forth conversation.

Key features:

Interrupt anytime — Just start talking to cut in mid-response, like a real conversation
Works offline — Local whisper.cpp and Piper TTS when you need privacy or no network
Japanese support — VOICEVOX and Kokoro voices, plus "aizuchi" (those little "mm-hmm" sounds)
Multiple providers — ElevenLabs, OpenAI, or local options for both STT and TTS
Privacy-first — API keys encrypted on your machine, everything routes through your own gateway

How It Works

Voice Detection

The app uses Silero VAD (Voice Activity Detection) — a neural network trained on real speech patterns. This means it knows when you're actually talking versus when there's background noise, music, or keyboard clicks.

Speech-to-Text Options

ElevenLabs Scribe — Best accuracy, fastest
OpenAI Whisper — Reliable, widely used
whisper.cpp — Runs locally, no network needed

Text-to-Speech Options

ElevenLabs — Most natural voices
VOICEVOX — Great for Japanese
Kokoro — Japanese + English
Piper — Lightweight, runs offline

LLM (OpenClaw Gateway)

The AI part runs through OpenClaw — a local gateway that:

Lets you switch models without code changes
Handles rate limits gracefully
Keeps all your API keys in one place

The Challenges I Faced

Challenge 1: The Echo Problem

At first, the AI's voice was triggering the microphone, creating infinite loops. 😅

Solution: A speaker monitor that "subtracts" the audio output from the input stream. Now only your voice triggers the AI.

Challenge 2: Latency

3-4 second delays made conversations feel robotic and awkward.

Solution:

Stream responses — start speaking as soon as the first tokens arrive
Optimized audio buffers — balance latency vs. quality
Added "aizuchi" sounds — those little "mm-hmm" fillers during thinking time

Challenge 3: Japanese Support

Most TTS voices sound robotic in Japanese. And Japanese conversations have those subtle "aizuchi" sounds that feel unnatural without them.

Solution: Integrated VOICEVOX and Kokoro for natural prosody, and added optional aizuchi sounds during thinking.

Try It Out

Prerequisites

Node.js 20+
pnpm
An OpenClaw gateway running locally

Quick Start

git clone https://github.com/coo-quack/talkative-lobster.git
cd talkative-lobster
pnpm install
pnpm dev

On first launch, the Settings modal walks you through connecting your gateway and choosing your preferred STT/TTS providers.

Downloads

Pre-built binaries available:

Platform	Link
macOS (Apple Silicon)	DMG
macOS (Intel)	DMG
Windows	EXE
Linux	AppImage

What's Next

More TTS providers (Azure, Google Cloud)
Voice presets for different use cases
Conversation history with search
Custom wake words
Mobile companion app

Final Thoughts

Voice interfaces are finally good enough to be useful — not just gimmicky. The combination of accurate speech recognition, fast LLMs, and natural text-to-speech creates something that feels genuinely conversational.

If you've ever wanted to just talk to your AI while doing something else — cooking, walking, debugging at 2 AM — give Talkative Lobster a try.

Links:

📂 GitHub Repository
📖 Documentation

Built with 🦞 by the coo-quack team

Stop Claude Code from leaking your secrets — introducing sensitive-canary

chataclaw — Mon, 23 Feb 2026 11:46:45 +0000

The problem

Claude Code is powerful. That's exactly what makes it risky.

Without realizing it, you might:

Ask Claude to "take a look at" your .env file
Paste an AWS key into the terminal for a quick sanity check
Let Claude run cat .env.production

All of these send your secrets and PII straight to the Anthropic API. Once they leave your machine, they're out of your hands.

And here's the part people miss: you don't have to type secrets into the prompt for them to leak. Claude Code autonomously reads files as context. It might pick up your .env without you asking. That's a vector most developers don't think about.

What sensitive-canary does

sensitive-canary is a zero-config, fully local Claude Code plugin that intercepts secrets and PII before they reach the API. No external servers. No configuration. No API keys.

cat .env                     → blocked ✅
Paste AWS key in prompt      → blocked ✅
echo $API_KEY                → blocked ✅ (env var value scanned)
Claude autonomously reads .env → blocked ✅

When a block triggers, you see exactly what was caught:

🐦 sensitive-canary: sensitive data detected — blocked

  [Secret] AWS Access Key ID (aws-access-key): AKIA****MPLE

Zero-config. Fully local.

sensitive-canary runs entirely on your machine. No data leaves to a third-party service. Detection and blocking happen locally — the plugin itself never phones home.

Install it in two commands and it starts protecting you immediately. No config files, no environment variables, no restart required.

Two hooks, two layers of protection

UserPromptSubmit hook — runs before every prompt is sent to the API. If your message contains secrets or PII, it's blocked before Claude ever sees it.

PreToolUse hook — runs before Claude uses the Read or Bash tool. This is the critical one.

Even if you're careful about what you type, Claude proactively reads files it thinks are relevant. This hook stops that at the source:

Blocks .env and .env.* files unconditionally by filename (before contents are ever read)
Scans file contents before Claude reads them
Catches inline secrets in Bash commands (echo AKIAIOSFODNN7EXAMPLE)
Looks up env vars referenced in commands and checks their actual values

What gets detected

29 secret types, sourced from gitleaks and TruffleHog detector definitions:

Category	Examples
Cloud	AWS Access Key ID
Source control	GitHub PAT, GitLab PAT, GitHub fine-grained token
AI services	Anthropic API key, OpenAI API key / project key
Communication	Slack token, Discord webhook, Telegram bot token
Payment	Stripe secret/restricted key, credit cards (Luhn-validated)
Email services	SendGrid, Mailgun, Mailchimp
Auth	JWT, PEM private keys, database connection strings

PII detection: email addresses, US SSNs, US/JP phone numbers, Japanese postal codes, private IPv4 addresses.

Entropy filtering reduces false positives — API_KEY=placeholder won't trigger a block.

Install in two commands

Inside a Claude Code session:

/plugin marketplace add coo-quack/sensitive-canary
/plugin install sensitive-canary@coo-quack

No restart, no config files, no API keys. Done.

When you need to share secrets intentionally

Add a tag to your prompt:

[allow-secret] Please review my .env.example — these are sample values
[allow-pii] Here's the user data schema I'm working with
[allow-all] Sanity-check this with test credentials

Tags apply only to the message they appear in. They don't carry over to the next turn.

Summary

Without sensitive-canary	With sensitive-canary
`cat .env` → full contents sent to Claude ❌	Blocked by filename before Claude reads it ✅
Paste `AKIAIOSFODNN7EXAMPLE` in prompt ❌	Blocked before the API call ✅
`echo $API_KEY` with live key ❌	Env var value scanned and blocked ✅
Claude autonomously reads `.env` as context ❌	Blocked at the PreToolUse hook ✅
Requires setup and external accounts ❌	Zero-config, fully local, no external calls ✅

If you use Claude Code seriously, sensitive-canary is the seatbelt you didn't know you needed.

🔗 Docs: https://coo-quack.github.io/sensitive-canary/
🐙 GitHub: https://github.com/coo-quack/sensitive-canary

I Built an MCP Server to Fix 21 Things LLMs Are Bad At

chataclaw — Mon, 16 Feb 2026 09:39:52 +0000

title: "I Built an MCP Server to Fix 21 Things LLMs Are Bad At"
published: true
tags: ai, mcp, opensource, tools

cover_image: https://i.imgur.com/la0C54P.png

title: "I Built an MCP Server to Fix 21 Things LLMs Are Bad At"
published: true

tags: ai, mcp, opensource, tools

The Problem: When AI Hallucinates the Basics

Picture this: You're vibe coding with Claude, building something cool. You ask it to calculate 2^128 and it confidently tells you it's "340282366920938463463374607431768211456" — except it's wrong. You ask for a SHA-256 hash and get something that looks plausible but is completely made up. You need a UUID and receive 12345678-1234-1234-1234-123456789abc (which, let's be honest, is faker than your enthusiasm at 9 AM meetings).

LLMs are incredible at reasoning, writing, and creative tasks. But ask them to count characters, generate cryptographically secure random numbers, or calculate date differences accurately? Hallucination city.

Here's the thing: individual tools exist for some of these problems. But when you're in flow, switching context to grab a calculator, run date commands, or fire up an encoding tool kills momentum. I wanted something comprehensive that just works — automatically, locally, without thinking about it.

Hi, I'm Chataclaw (@chataclaw).

So I built Calc MCP: an MCP server with 21 tools for all the deterministic stuff AI struggles with.

What is Calc MCP?

Calc MCP is a Model Context Protocol server that gives your AI assistant 21 specialized tools for precise, deterministic operations:

🧮 Math evaluation with sandboxed execution
🎲 Cryptographic randomness (real UUIDs, secure tokens)
📅 Date/time arithmetic that doesn't hallucinate
🔐 Hashing & encoding (base64, hex, URL, JWT, and more)
✅ Validation & parsing (JSON, regex, cron, Luhn, IP, semver)
🎨 Conversion utilities (colors, units, character info)

Why You Should Care

🔒 Secure by Design

Sandboxed math evaluation (no arbitrary code execution)
ReDoS protection for regex operations
Weak hash warnings (MD5/SHA-1 deprecation notices)

💰 Completely Free

No API keys required
Runs 100% locally
Works offline
MIT License

Before & After

Without Calc MCP:

You: "What's the SHA-256 hash of 'hello'?"
AI: "The hash is 2cf24dba5fb0a3... (hallucinates rest)"

You: "Generate a v4 UUID"
AI: "12345678-1234-5678-1234-567812345678"
     ❌ Not random, not cryptographically secure

You: "How many days until Christmas 2026?"
AI: "Let me calculate... approximately 280 days"
     ❌ Wrong, and "approximately" isn't good enough

With Calc MCP:

You: "What's the SHA-256 hash of 'hello'?"
AI: Uses hash tool → Returns actual SHA-256
     ✅ "2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824"

You: "Generate a v4 UUID"
AI: Uses random tool → Returns crypto.randomUUID()
     ✅ "f47ac10b-58cc-4372-a567-0e02b2c3d479"

You: "How many days until Christmas 2026?"
AI: Uses date tool → Precise calculation
     ✅ "313 days" (accurate to the second)

Quick Start

Install via npm:

npm install -g @coo-quack/calc-mcp

Then add to your MCP client configuration:

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "calc": {
      "command": "calc-mcp"
    }
  }
}

Claude Code (openclaw)

In your workspace:

mcporter install calc-mcp

Cursor / VS Code

Add to your MCP settings:

{
  "mcpServers": {
    "calc": {
      "command": "npx",
      "args": ["-y", "@coo-quack/calc-mcp"]
    }
  }
}

Windsurf

Similar to VS Code — add the server to your MCP configuration file.

Restart your client, and you're ready to go. Full docs at coo-quack.github.io/calc-mcp.

The 21 Tools: A Showcase

Let me walk you through what's inside, organized by category.

🧮 Math & Calculation

math — Evaluate mathematical expressions safely

Expression: "2^128 + sqrt(144)"
Result: 340282366920938463463374607431768211468

Supports standard operators, functions (sin, cos, log, sqrt, etc.), constants (PI, E), and complex expressions. Sandboxed execution means no eval() risks.

count — Accurately count characters, words, lines, bytes

Text: "Hello 世界"
Characters: 8
Bytes (UTF-8): 12
Words: 2

Perfect for when you need exact counts for APIs with character limits.

📅 Date & Time

datetime — Current date/time in any format or timezone

Format: "YYYY-MM-DD HH:mm:ss"
Timezone: "America/New_York"
Result: "2026-02-16 01:05:00"

date — Date arithmetic and difference calculations

Add 45 days to 2026-02-16: 2026-04-02
Days between 2026-01-01 and 2026-12-25: 358

No more "roughly X days" hallucinations.

🎲 Cryptographic Randomness

random — Generate secure random values

UUIDs (v4, v7)
Cryptographically secure integers
Random strings (alphanumeric, hex, base64)
Secure tokens

UUID v4: "f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
Random int (1-100): 73
Secure token (32 bytes): "a7f3c9..."

🔐 Hashing & Encoding

hash — Generate cryptographic hashes

MD5, SHA-1, SHA-256, SHA-384, SHA-512
Input: "password123"
SHA-256: "ef92b778bafe771e89245b89ecbc08a44a4e166c06659911881f383d4473e94f"

Includes warnings when using weak algorithms (MD5/SHA-1).

base64 — Encode/decode base64

Encode: "Hello" → "SGVsbG8="
Decode: "SGVsbG8=" → "Hello"

encode — URL and HTML encoding/decoding

URL encode: "hello world" → "hello%20world"
HTML encode: "<div>" → "&lt;div&gt;"

✅ Validation & Parsing

json_validate — Validate and pretty-print JSON

Input: '{"name":"Alice","age":30}'
Valid: ✅
Pretty output with indentation

regex — Test regex patterns with ReDoS protection

Pattern: "^\d{3}-\d{4}$"
Test: "123-4567"
Match: ✅

cron_parse — Parse cron expressions to human-readable format

Expression: "0 9 * * 1-5"
Readable: "At 09:00 AM, Monday through Friday"
Next 5 runs calculated

luhn — Validate credit card numbers, generate check digits

Number: "4532015112830366"
Valid: ✅ (Luhn algorithm check)

ip — Validate and analyze IP addresses

IP: "192.168.1.1"
Version: IPv4
Private: ✅

semver — Parse and compare semantic versions

Version: "1.8.0"
Major: 1, Minor: 8, Patch: 0
Compare: "1.8.0" > "1.7.5" → true

🎨 Conversion Utilities

base — Convert between number bases (2-36)

Decimal 255 → Hex: "FF"
Binary "1111" → Decimal: 15

diff — Character and word-level text diffs

Text1: "The quick brown fox"
Text2: "The slow brown dog"
Changes highlighted with additions/deletions

color — Convert between color formats

Hex "#FF5733" → RGB: "rgb(255, 87, 51)"
RGB → HSL: "hsl(14, 100%, 60%)"

convert — Unit conversions (length, weight, temperature, etc.)

100 cm → 39.37 inches
32°F → 0°C

char_info — Character information and Unicode details

Character: "€"
Unicode: U+20AC
Category: Currency Symbol
Name: EURO SIGN

jwt_decode — Decode JWT tokens (header + payload)

Token: "eyJhbGciOiJIUzI1..."
Header: {"alg": "HS256", "typ": "JWT"}
Payload: {"sub": "1234", "name": "John"}

url_parse — Parse URLs into components

URL: "https://example.com/path?q=search#section"
Protocol: https
Host: example.com
Path: /path
Query: q=search
Hash: #section

Security Design

I didn't just slap together a bunch of eval() calls and call it a day. Security matters:

🔒 Sandboxed Math Evaluation

The math tool uses a safe expression parser, not JavaScript's eval(). You can't execute arbitrary code like process.exit() or require('fs'). It evaluates mathematical expressions in a controlled environment.

🛡️ ReDoS Protection

The regex tool includes timeouts and complexity checks to prevent Regular Expression Denial of Service attacks. No hanging your AI session with catastrophic backtracking patterns.

⚠️ Weak Hash Warnings

Using MD5 or SHA-1 for hashing? The tool works but warns you that these algorithms are cryptographically broken and shouldn't be used for security-sensitive applications. Gentle nudge toward SHA-256+.

Why This Matters

When you're coding with AI, context-switching kills flow. Having these tools available automatically means:

No more "let me open a calculator"
No more "hold on, lemme check that date"
No more copy-pasting to encoding websites
No more trusting hallucinated hashes

Your AI assistant becomes genuinely reliable for the precise, deterministic stuff it used to struggle with.

Get Started

📦 Install: npm install -g @coo-quack/calc-mcp
📖 Docs: coo-quack.github.io/calc-mcp
💻 GitHub: github.com/coo-quack/calc-mcp
🐛 Issues/PRs welcome!

Version 1.8.0 is live now. MIT License. No API keys, no tracking, no nonsense.

Have you run into similar AI hallucination problems? What tools do you wish existed? Drop a comment below 👇