# @mate-tools/mcp-server

[![npm version](https://img.shields.io/npm/v/@mate-tools/mcp-server.svg)](https://www.npmjs.com/package/@mate-tools/mcp-server)
[![npm downloads](https://img.shields.io/npm/dm/@mate-tools/mcp-server.svg)](https://www.npmjs.com/package/@mate-tools/mcp-server)
[![Node.js](https://img.shields.io/node/v/@mate-tools/mcp-server.svg)](https://nodejs.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

[Model Context Protocol](https://modelcontextprotocol.io) server for [mate.tools](https://mate.tools). **35 utility tools** for AI agents — text analysis, encoding, hashing, password generation, JSON/CSV/XML/sitemap parsing, regex, color, date, finance, URL metadata extraction, SEO meta-tag generation, text cleanup, CSPRNG random generators, hashtag tools, DNS lookup, SSL/TLS certificate inspection, JWT decoding and more. Wraps the public mate.tools JSON API so Claude Desktop, Claude Code, Cursor, Windsurf, and any other MCP-compatible client can call them directly.

**Zero dependencies · Free · No API key · CORS open · Node 18+**

## Quick install

Add this to your Claude Desktop / Claude Code / Cursor / Windsurf config:

```json
{
  "mcpServers": {
    "mate-tools": {
      "command": "npx",
      "args": ["-y", "@mate-tools/mcp-server"]
    }
  }
}
```

Restart your client and all 35 tools appear in the picker. That's it.

## All 35 tools, by category

### Text (8)

| Tool | What it does |
| --- | --- |
| `count_lines` | 16 text metrics: lines, words, sentences, paragraphs, characters, duplicates, line endings (LF/CRLF/CR), longest word, reading & speaking time. |
| `case_convert` | Convert text into 9 case styles in one call: upper, lower, title, sentence, snake, kebab, camel, pascal, constant. |
| `slugify` | Convert any text to a URL-safe slug. Unicode-aware, configurable separator/length, optional transliteration of non-Latin characters. |
| `sort_lines` | Sort lines: asc/desc, case-sensitivity, dedupe, natural-sort (line2 before line10), locale-aware collation. |
| `lorem_ipsum` | Generate placeholder text — paragraphs, sentences or words. |
| `regex_test` | Match / replace / split text with a PCRE regex. Returns capture-group offsets. ReDoS-protected. |
| `text_diff` | Diff two strings by line, word or character. Returns structured changes + unified diff string + Jaccard similarity. |
| `text_cleanup` | Chained cleanup pipeline: trim, collapse_spaces, dedupe_lines, strip HTML/emoji/URLs/emails, normalize quotes/dashes, lower/uppercase. |

### Encoding (4)

| Tool | What it does |
| --- | --- |
| `base64_encode` | Base64-encode text. Standard or URL-safe alphabet (RFC 4648 §5). |
| `base64_decode` | Base64-decode. Auto-fixes missing padding; returns hex when not valid UTF-8. |
| `url_encode` | Percent-encode a string. Component / form / path mode. |
| `url_decode` | Decode percent-encoded URL strings. |

### Crypto & auth (5)

| Tool | What it does |
| --- | --- |
| `hash` | MD5, SHA-1, SHA-256, SHA-384, SHA-512, SHA3-256, SHA3-512, CRC32 (or any subset of PHP's hash algorithms). |
| `password` | Generate cryptographically random passwords (CSPRNG). Configurable length, count, character classes, ambiguous-char exclusion. Reports entropy. |
| `password_strength` | Score a password 0–4 (zxcvbn-style), entropy bits, offline-GPU crack-time estimate, concerns and suggestions. |
| `credit_card_validate` | Luhn check + brand detection (Visa, MC, Amex, Discover, JCB, Diners, UnionPay, Maestro, RuPay). PAN never logged. |
| `jwt_decode` | Decode a JWT — header, payload, expiry status. Verify HS256/384/512 with a secret or RS256/384/512 with a PEM public key. Token never logged. |

### Data & structure (13)

| Tool | What it does |
| --- | --- |
| `json_format` | Validate, pretty-print, minify or analyse a JSON document. Returns structural summary (node counts, max depth, top keys). |
| `json_to_csv` | Convert a JSON array of objects to CSV. Configurable delimiter, columns, optional flattening of nested objects (`meta.city`, `meta.zip`). |
| `xml_validate` | Validate XML well-formedness + optional XSD schema. Errors with line/column. XXE-safe. |
| `sitemap_extract` | Fetch + parse XML sitemaps. SSRF-protected (refuses private/loopback/link-local/cloud-metadata IPs). Optional recursive expansion of sub-sitemaps. |
| `stats` | Descriptive statistics for a list of numbers: mean / median / mode / stddev / variance / percentiles / IQR / geometric / harmonic. |
| `number_base` | Convert integers between bases 2..36 + Roman numerals. Big-int safe via GMP. |
| `finance_calc` | Multi-mode financial calculations: loan, compound interest, simple interest, discount, tip, sales tax, ROI, percentage, markup. |
| `aspect_ratio` | Compute reduced aspect ratio (16:9, 4:3, 21:9, ...) from width × height, or scale a dimension to a target ratio. |
| `color_convert` | Convert any color into hex / rgb / rgba / hsl / hsv / cmyk + closest named color + WCAG luminance and contrast (AA / AAA flags). |
| `url_metadata` | Fetch a URL and extract title / description / OpenGraph / Twitter Card / canonical / language / hreflang / JSON-LD / favicon / response headers / element counts. SSRF-protected, 2 MB cap. |
| `meta_tags_generate` | Generate a full HTML head block (meta + OpenGraph + Twitter Card + JSON-LD) from title/description/url/image. Returns ready-to-paste HTML + SEO score 0-100 with concrete warnings. |
| `dns_lookup` | Resolve DNS records (A, AAAA, MX, TXT, NS, CNAME, SOA, CAA, PTR, SRV) via the system resolver. Includes reverse PTR for A records. |
| `ssl_check` | Inspect a domain's TLS certificate: subject, issuer, validity, fingerprint, alt names, full chain, days remaining, negotiated protocol/cipher. SSRF-protected. |

### Date & time (3)

| Tool | What it does |
| --- | --- |
| `timestamp` | Bidirectional epoch ↔ ISO 8601 ↔ RFC 3339 ↔ human. Auto-detects epoch resolution. Timezone-aware. Accepts natural language (`"next monday"`, `"+2 weeks"`). |
| `date_math` | Add/subtract a duration from a date, or compute the diff between two dates. Optional business-day count (Mon–Fri). |
| `age_calc` | Calculate age in years/months/days from DOB. Returns next birthday, days until, Western zodiac sign, generation label. |

### Generators & social (2)

| Tool | What it does |
| --- | --- |
| `random_gen` | CSPRNG-backed generator: number, string (alpha/alphanumeric/numeric/hex/base58/base64url), word, picker (with/without replacement), team balancer, dice (`NdM`), coin, country, UUID v4 / v7. |
| `hashtag_tools` | Hashtag operations on text: extract (with offsets), remove, generate (stop-word-filtered word frequency), format (camel/snake/lower/preserve). Unicode-aware. |

The catalog grows over time. `npx -y` always fetches the latest published version — your client just needs a restart to pick up new tools.

## Install snippets for every major client

### Claude Desktop

Open the Claude Desktop config:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

Add the `mcpServers` entry from the Quick install above and restart.

### Claude Code

```bash
claude mcp add mate-tools npx -- -y @mate-tools/mcp-server
```

### Cursor

Add to `~/.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "mate-tools": {
      "command": "npx",
      "args": ["-y", "@mate-tools/mcp-server"]
    }
  }
}
```

### Windsurf and other MCP clients

The server speaks MCP over stdio with the standard JSON-RPC 2.0 framing. Any MCP-compatible client can launch it as a subprocess with the same configuration shape.

### Manual install (no npx)

```bash
npm install -g @mate-tools/mcp-server
mate-tools-mcp   # speaks JSON-RPC over stdio; plug into a client
```

## How to verify it's working

Once installed, ask your AI agent any of these to confirm the tools are wired:

> "Use mate-tools to count the lines and reading time of this paragraph."
>
> "Hash the string `secret` with SHA-256."
>
> "Generate 10 strong passwords, 20 chars, no ambiguous characters."
>
> "Score this password: `correct horse battery staple`."
>
> "Convert `#ff5733` to all color spaces and tell me the WCAG contrast vs white."
>
> "What's the aspect ratio of 3840 × 2160?"
>
> "Diff these two paragraphs for me."
>
> "What's the monthly payment on a $300k loan at 6.5% APR over 30 years?"
>
> "How old is someone born on 1990-04-15? What's their zodiac sign?"
>
> "Extract all URLs from `https://example.com/sitemap.xml` recursively."
>
> "Fetch the metadata and OpenGraph tags from `https://example.com` for me."
>
> "Generate SEO meta tags for an article titled `…` and score the result."
>
> "Roll 4d6 drop lowest, six times, for me."
>
> "Suggest hashtags for this caption."
>
> "Look up the MX and TXT records for example.com."
>
> "Is the SSL certificate on github.com valid? When does it expire?"
>
> "Decode this JWT and tell me if it's expired."

The agent will pick the right tool automatically.

## How it works

The server is a single ~600-line zero-dependency Node script. Every tool call:

1. Receives a JSON-RPC `tools/call` request from the MCP client.
2. Forwards the arguments to the public mate.tools API at `https://mate.tools/api/v1/{tool}.php`.
3. Returns a human-readable summary plus the full JSON response back to the client.

Nothing runs locally besides the JSON-RPC plumbing. Computation runs on mate.tools' servers behind Cloudflare. Every endpoint is rate-limited at 60 req/min and 600 req/hour per IP.

## Configuration

Override the API endpoint (e.g. for testing against a staging deployment):

```bash
MATE_TOOLS_API_BASE=https://staging.mate.tools/api/v1 npx -y @mate-tools/mcp-server
```

## Privacy

Each tool call:
- ✅ Sends only the arguments you provide to the MCP tool.
- ✅ Hits HTTPS in transit.
- ✅ Is processed in memory and not logged with content.
- ❌ Does not collect telemetry.
- ❌ Does not require an account, API key or sign-in.

The mate.tools server logs only request method, hashed-IP (rotating daily salt), endpoint name and duration — never request content.

`credit_card_validate` and `password_strength` are explicitly engineered so the sensitive input never leaves request-handler memory. Only the validation outcome and metrics are returned.

`sitemap_extract`, `url_metadata`, and `ssl_check` refuse to fetch / connect to any host whose name resolves to a private (RFC 1918), loopback, link-local, or cloud-metadata IP. For HTTP-based tools, each redirect destination is re-validated, so SSRF tricks via 302 don't work. `url_metadata` additionally caps the response body at 2 MB. `ssl_check` uses a 5-second connect timeout.

`jwt_decode` never logs the token. Decoding runs entirely in request-handler memory; only the algorithm name, signature verification outcome, and request duration are written to the per-day access log. Use it confidently with production tokens.

`regex_test` enforces a hard PCRE backtrack ceiling (100,000 steps) per request — catastrophic regex patterns return a clean 422 rather than hanging the server.

`random_gen` is backed by PHP's `random_int` / `random_bytes` (CSPRNG) — never the Mersenne Twister. UUIDs are RFC 4122 v4 with proper version/variant bits, or v7 with millisecond-precision timestamp.

## Source and documentation

- **npm:** <https://www.npmjs.com/package/@mate-tools/mcp-server>
- **Source code (single file):** <https://mate.tools/api/mcp/server.js>
- **Install guide with screenshots:** <https://mate.tools/api/mcp>
- **JSON API reference:** <https://mate.tools/api>
- **OpenAPI 3.1 spec:** <https://mate.tools/api/openapi.json>
- **llms.txt:** <https://mate.tools/llms.txt>

## Issues / feedback

Open an issue at the [mate.tools contact form](https://mate.tools/contact) — please mention "@mate-tools/mcp-server" in the subject line. New tools land roughly every 1–2 weeks; if there's a specific utility you want exposed, just ask.

## License

MIT — free for personal and commercial use. See [LICENSE](LICENSE).