fabtally-belt-mcp

# FabTally Utility Belt — MCP server

The deterministic micro-utilities AI agents call constantly, as an MCP server (stdio + streamable-HTTP)
**and** a pay-per-call HTTP API. One reliable bundle instead of thirteen flaky npm deps.

- **Free tools** return real results with no wallet: `convert`, `text`, `hash`, `encode`, `id`, `regex`.
- **Paid tools** ($0.001/call, x402 · USDC on Base): `timezone`, `cron`, `rrule`, `currency`, `diff`,
  `jsonschema`, `datemath`. With no payment a paid tool returns the decoded **x402 402 challenge**
  (price / network / asset / payTo) so an agent can pay and retry with `x_payment`. Humans can instead
  prepay by card and use an `X-FabTally-Key` credit key against the HTTP API.

This server holds **no private key**. It fronts `https://belt.fabtally.com`. Every utility is a pure,
deterministic function with strict input validation; **bad input → 400, never charged**; nothing is stored.

## Tools

| Tool | Tier | What it does |
|---|---|---|
| `convert` | free | Unit conversion (length/mass/temperature/volume/data/time/area/speed/angle/pressure/energy). |
| `text` | free | slugify · case-convert (camel/pascal/snake/kebab/constant/…) · `{{template}}` fill. |
| `hash` | free | sha256/sha512/sha384/sha1/md5/sha3-256/keccak256/ripemd160, optional HMAC, hex/base64 out. |
| `encode` | free | base64 / base64url / hex / url / html encode & decode. |
| `id` | free | uuid v4/v7, ULID, nanoid, random hex/base64url/int (count up to 1000). |
| `regex` | free | test/match/extract/replace with catastrophic-backtracking protection (killable worker + timeout). |
| `timezone` | $0.001 | Instant → IANA zone with historically-correct DST; offsets, abbreviations, DST flags. |
| `cron` | $0.001 | Cron expression → next N run times + plain-English description. |
| `rrule` | $0.001 | iCal RRULE (RFC 5545) → next N occurrences. |
| `currency` | $0.001 | Live currency conversion at reference/mid-market rates (keyless ECB feed, cached). |
| `diff` | $0.001 | Text diff: unified patch + structured op-list + add/remove/hunk stats. |
| `jsonschema` | $0.001 | Validate against JSON Schema (draft 2020-12) and explain every error in plain English. |
| `datemath` | $0.001 | Add/subtract ISO-8601 durations, diff into chosen units, business-day add/diff. |

## Install / run

### stdio (Claude Desktop, Cursor, any MCP client)

```jsonc
// claude_desktop_config.json
{
  "mcpServers": {
    "fabtally-belt": { "command": "npx", "args": ["-y", "fabtally-belt-mcp"] }
  }
}
```

Or clone and run: `node index.js` (speaks MCP over stdio).

### streamable-HTTP (remote)

Hosted: `https://belt.fabtally.com/mcp`. Or self-host: `MCP_HTTP_PORT=8108 node http.js`.

### Config

- `FABTALLY_BELT_BASE` — API base (default `https://belt.fabtally.com`).

## Paying for paid tools

A paid tool with no `x_payment` returns:

```json
{ "payment_required": true, "http_status": 402,
  "challenge": { "x402Version": 2, "accepts": [ { "scheme": "exact", "network": "eip155:8453",
    "amount": "1000", "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "payTo": "0x…" } ] } }
```

Build an x402 payment authorization (EIP-3009 `transferWithAuthorization` to `payTo`) for the `accepts`
entry and call the tool again with the token in `x_payment`. `amount` is atomic USDC (1000 = $0.001).

## Guarantees

Deterministic. Stateless — no PII or request data stored. Receive-only wallet (no custody). Currency
figures are reference/mid-market rates for informational use, not a dealable quote. MIT licensed.