# Agent Utils MCP Server 🛠️

A Swiss-army-knife utility server for AI agents — 18 tools via MCP (Streamable HTTP) + REST API.

[![Smithery](https://smithery.ai/badge/@aparajithn/agent-utils-mcp)](https://smithery.ai/server/@aparajithn/agent-utils-mcp)
[![Glama](https://glama.ai/badge/mcp/agent-utils-mcp)](https://glama.ai/mcp/servers/agent-utils-mcp)

**Live at:** https://agent-utils-mcp.onrender.com

## Add to Your MCP Client

### Claude Desktop / Cursor / Windsurf

Add to your MCP config:

```json
{
  "mcpServers": {
    "agent-utils": {
      "url": "https://agent-utils-mcp.onrender.com/mcp"
    }
  }
}
```

### Smithery

```bash
smithery mcp add aparajithn/agent-utils
```

## Tools (18)

| Tool | Description |
|------|-------------|
| `tool_json_validate` | Validate JSON string, return parsed or error |
| `tool_json_format` | Pretty-print or minify JSON |
| `tool_base64_encode` | Encode string to base64 |
| `tool_base64_decode` | Decode base64 string |
| `tool_hash_generate` | MD5, SHA256, SHA512 hash |
| `tool_uuid_generate` | UUID v4 or v7 |
| `tool_url_parse` | Parse URL into components |
| `tool_regex_test` | Test regex pattern, return matches |
| `tool_markdown_to_html` | Markdown → HTML |
| `tool_html_to_markdown` | HTML → Markdown |
| `tool_text_stats` | Word count, char count, reading time |
| `tool_slug_generate` | URL-safe slug from text |
| `tool_datetime_convert` | Convert between timezones/formats/Unix timestamps |
| `tool_cron_parse` | Human-readable cron description + next N runs |
| `tool_diff_text` | Unified diff between two texts |
| `tool_csv_to_json` | CSV → JSON array |
| `tool_json_to_csv` | JSON array → CSV |
| `tool_jwt_decode` | Decode JWT payload (no verification) |

## REST API

All tools also available as REST endpoints at `/api/v1/{tool_name}`.

```bash
# Hash a string
curl -X POST https://agent-utils-mcp.onrender.com/api/v1/hash_generate \
  -H "Content-Type: application/json" \
  -d '{"text": "hello world", "algorithm": "sha256"}'

# Generate UUID
curl -X POST https://agent-utils-mcp.onrender.com/api/v1/uuid_generate \
  -H "Content-Type: application/json" \
  -d '{"version": 4}'

# Convert datetime
curl -X POST https://agent-utils-mcp.onrender.com/api/v1/datetime_convert \
  -H "Content-Type: application/json" \
  -d '{"dt_string": "2025-01-01 12:00", "from_tz": "UTC", "to_tz": "America/New_York"}'
```

OpenAPI docs: https://agent-utils-mcp.onrender.com/docs

## Discovery

- **Google A2A:** `/.well-known/agent-card.json`
- **Smithery:** `/.well-known/mcp/server-card.json`
- **OpenAPI:** `/openapi.json`

## Pricing

- **Free tier:** 100 requests per IP per 24 hours
- **Paid tier:** x402 protocol — $0.001/request in USDC (Base network)

### Paying with x402

When you exhaust the free tier, the server replies with HTTP 402 carrying
machine-readable payment requirements (x402 v1). Any x402-aware client pays
and retries automatically:

```python
from x402_fetch import x402_fetch  # pip install x402-fetch
response = x402_fetch("https://agent-utils-mcp.onrender.com/api/v1/hash_generate", method="POST",
                      body={"text": "hello", "algorithm": "sha256"})
```

Or attach the payment header yourself: the `X-Payment` header must be a
base64-encoded JSON envelope containing an EIP-3009 `TransferWithAuthorization`
(USDC on Base) signed with the payer's EIP-712 key for the exact price,
addressed to the server's wallet, with an unused nonce. Payments are verified
cryptographically (signature recovery + amount/recipient/deadline/replay
checks) before the request is served.

### Payment configuration (environment variables)

| Variable | Default | Purpose |
|----------|---------|---------|
| `X402_WALLET_ADDRESS` | *(unset — paywall disabled)* | Wallet that receives payments |
| `X402_PRICE_MICROUSD` | `1000` ($0.001) | Price per request in USDC atomic units |
| `X402_NETWORK` / `X402_CHAIN_ID` / `X402_USDC_CONTRACT` | `base` / `8453` / Base USDC | Payment network |
| `X402_MAX_TIMEOUT_SECONDS` | `60` | Payment validity window |
| `RATE_LIMIT_FREE` | `100` | Free requests per IP per 24h |

### Collecting revenue (on-chain settlement)

With `X402_SETTLER_PRIVATE_KEY` set, every verified payment is executed
on-chain within seconds: the EIP-3009 `transferWithAuthorization` is submitted
to the USDC contract on Base and the USDC moves from the payer to
`X402_WALLET_ADDRESS`. The settler key does **not** need to be the receiving
wallet's key — EIP-3009 authorizations can be executed by any address, so a
dedicated gas-only burner key can do the submitting while the funds land in
your main wallet. It only needs a small ETH balance on Base for gas.

| Variable | Default | Purpose |
|----------|---------|---------|
| `X402_SETTLER_PRIVATE_KEY` | *(unset — verify only, no funds move)* | Key that submits settlement transactions |
| `X402_RPC_URL` | `https://mainnet.base.org` | Base JSON-RPC endpoint |
| `X402_SETTLE_MIN_MICROUSD` | `0` (settle each payment immediately) | Batch payments until pending value reaches this |

Failed settlements are retried with exponential backoff; if all retries fail,
the full payment authorization is written to the logs (CRITICAL) so it can be
redeemed manually — no payment is silently lost.

## Tech Stack

- Python 3.11 + FastAPI + MCP SDK (Streamable HTTP)
- Deployed on Render (auto-scaling)
- GitHub: https://github.com/aparajithn/agent-utils-mcp

## License

MIT