@gera-services/mcp-geratools 1.0.0

package/README.md

@@ -0,0 +1,104 @@
+# GeraTools MCP Server
+
+[![A Gera Systems product](https://img.shields.io/badge/Gera-Systems-0a7?style=flat)](https://geratools.com)
+
+An [MCP](https://modelcontextprotocol.io) server that gives AI agents — Claude
+Desktop, Claude Code, ChatGPT with tools, Cursor, Windsurf, or any MCP client —
+a set of everyday **developer utilities** from
+[GeraTools](https://geratools.com): Base64, cryptographic hashing, regex
+testing, word count, JWT decoding and CSS unit conversion.
+
+Every tool is a pure, deterministic function ported straight from the published
+GeraTools browser tools (or Node's `crypto`). **No backend, no network, no
+auth** — everything runs locally, so an agent can compute these without leaving
+the machine.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `base64` | Encode text/hex to Base64, or decode Base64 / Base64url to text. UTF-8 safe (emoji round-trip), standard + URL-safe variants, hex fallback for non-text bytes. |
+| `hash` | Cryptographic digest: `md5`, `sha1`, `sha256`, `sha384`, `sha512`. Input as utf8/hex/base64; output as hex/base64. |
+| `regex_test` | Run a JS regex against a string — returns every match with index, capture groups, named groups, count, and a plain-English explanation of the pattern. |
+| `word_count` | Words, characters (with/without spaces), sentences, paragraphs, lines, and 200-wpm reading time. |
+| `jwt_decode` | Base64url-decode a JWT into header + payload, list `iat`/`nbf`/`exp` as ISO timestamps, and report expiry. (Does **not** verify the signature.) |
+| `css_unit_convert` | Convert a CSS length between `px`, `rem`, `em`, `pt`, `pc`, `in`, `cm`, `mm`, `Q` (1in = 96px; rem/em respect configurable font sizes). |
+
+## Install & run
+
+```bash
+# Run directly (no global install) once published to npm:
+npx -y @gera-services/mcp-geratools
+
+# Or from this repo:
+cd packages/mcp-geratools
+npm run build      # tsc --noCheck  -> dist/
+node bin/cli.js    # starts on stdio
+```
+
+## Client configuration
+
+### Claude Desktop / Claude Code (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "geratools": {
+      "command": "npx",
+      "args": ["-y", "@gera-services/mcp-geratools"]
+    }
+  }
+}
+```
+
+Local (unpublished) variant — point at the built CLI:
+
+```json
+{
+  "mcpServers": {
+    "geratools": {
+      "command": "node",
+      "args": ["/Users/armen/Gera/packages/mcp-geratools/bin/cli.js"]
+    }
+  }
+}
+```
+
+### Cursor / Windsurf (`.cursor/mcp.json` etc.)
+
+```json
+{
+  "mcpServers": {
+    "geratools": {
+      "command": "npx",
+      "args": ["-y", "@gera-services/mcp-geratools"]
+    }
+  }
+}
+```
+
+## Verify it works
+
+```bash
+npm run build
+node scripts/smoke.mjs
+```
+
+The smoke test speaks raw MCP JSON-RPC over stdio (`initialize` → `tools/list`
+→ a real `tools/call` for every tool) and asserts the results — including a
+Base64 emoji round-trip, the known SHA-256 of `"abc"`, and `16px == 1rem`.
+Expected output ends with `ALL SMOKE CHECKS PASSED`.
+
+## Examples
+
+Ask your agent:
+
+- *"Base64-encode this string for me"* → `base64` (mode `encode`)
+- *"What's the SHA-256 of this file's contents?"* → `hash` (`sha256`)
+- *"Does `\b\w+@\w+\.\w+\b` match these two emails, and what does it mean?"* → `regex_test`
+- *"Decode this JWT and tell me when it expires"* → `jwt_decode`
+- *"How many rem is 24px at a 18px root?"* → `css_unit_convert`
+
+## License
+
+MIT © Gera Systems Ltd

package/bin/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for the GeraTools MCP server.
+ * Starts the server on stdio. Intended to be launched by an MCP client
+ * (Claude Desktop, ChatGPT-with-tools, Cursor, etc.) — not run interactively.
+ */
+import { main } from '../dist/server.js';
+
+main().catch((err) => {
+  console.error('Fatal:', err);
+  process.exit(1);
+});

package/dist/engine.d.ts

@@ -0,0 +1,107 @@
+/**
+ * GeraTools computational engine.
+ *
+ * Pure, offline functions ported directly from the real GeraTools browser
+ * islands (utility-tools/src/islands/*). No network, no DOM, no side effects —
+ * the same logic the published tools run, made callable from Node so an MCP
+ * client can use them headlessly.
+ *
+ * Sources:
+ *  - base64        ← Base64EncoderDecoder.tsx
+ *  - regex         ← RegexTester.tsx
+ *  - word count    ← WordCounter.tsx
+ *  - jwt decode    ← JwtDecode.tsx
+ *  - css units     ← CssUnitConverter.tsx
+ *  - hashing       ← uses Node's crypto (the browser tools use SubtleCrypto;
+ *                    same algorithms, same digests)
+ */
+export declare function bytesToBase64(bytes: Uint8Array, url: boolean): string;
+export declare function base64ToBytes(input: string): Uint8Array;
+export type Base64Mode = 'encode' | 'decode';
+export type Base64Variant = 'std' | 'url';
+export type Base64InputKind = 'text' | 'hex';
+export interface Base64Result {
+    mode: Base64Mode;
+    variant: Base64Variant | null;
+    output: string;
+    output_kind: 'base64' | 'text' | 'hex';
+    note: string | null;
+}
+/** Binary-safe Base64 encode/decode, ported from the GeraTools browser tool. */
+export declare function base64(input: string, mode: Base64Mode, opts?: {
+    variant?: Base64Variant;
+    inputKind?: Base64InputKind;
+}): Base64Result;
+export declare const SUPPORTED_HASHES: readonly ["md5", "sha1", "sha256", "sha384", "sha512"];
+export type HashAlgo = (typeof SUPPORTED_HASHES)[number];
+export interface HashResult {
+    algorithm: HashAlgo;
+    input_encoding: 'utf8' | 'hex' | 'base64';
+    output_encoding: 'hex' | 'base64';
+    digest: string;
+    digest_bits: number;
+}
+/** Cryptographic digest of arbitrary input. Real Node crypto, deterministic. */
+export declare function hashText(input: string, algorithm: HashAlgo, opts?: {
+    inputEncoding?: 'utf8' | 'hex' | 'base64';
+    outputEncoding?: 'hex' | 'base64';
+}): HashResult;
+export declare function explainRegex(pattern: string): string[];
+export interface RegexMatch {
+    match: string;
+    index: number;
+    groups: string[];
+    namedGroups: Record<string, string> | null;
+}
+export interface RegexResult {
+    pattern: string;
+    flags: string;
+    valid: boolean;
+    error: string | null;
+    count: number;
+    matches: RegexMatch[];
+    explanation: string[];
+}
+/** Run a JS regex against a test string and explain it, ported from the tool. */
+export declare function regexTest(pattern: string, test: string, flags?: string): RegexResult;
+export interface WordCountResult {
+    words: number;
+    charsWithSpaces: number;
+    charsNoSpaces: number;
+    sentences: number;
+    paragraphs: number;
+    lines: number;
+    readingTimeSeconds: number;
+    readingTimeHuman: string;
+}
+/** Word / character / sentence / paragraph stats, ported from the tool. */
+export declare function wordCount(text: string): WordCountResult;
+export interface JwtDecodeResult {
+    header: Record<string, unknown>;
+    payload: Record<string, unknown>;
+    signature: string;
+    timeClaims: {
+        claim: string;
+        epoch: number;
+        iso: string;
+    }[];
+    expired: boolean | null;
+    note: string;
+}
+/** Decode (NOT verify) a JWT into header/payload + time claims. */
+export declare function jwtDecode(token: string): JwtDecodeResult;
+export declare const CSS_UNITS: readonly ["px", "rem", "em", "pt", "pc", "in", "cm", "mm", "Q"];
+export type CssUnit = (typeof CSS_UNITS)[number];
+export interface CssUnitResult {
+    value: number;
+    from: CssUnit;
+    rootFontPx: number;
+    parentFontPx: number;
+    px: number;
+    conversions: Record<string, number>;
+}
+/** Convert a CSS length to every other unit, ported from the tool. */
+export declare function cssUnitConvert(value: number, from: CssUnit, opts?: {
+    rootFontPx?: number;
+    parentFontPx?: number;
+}): CssUnitResult;

package/dist/engine.js

@@ -0,0 +1,386 @@
+/**
+ * GeraTools computational engine.
+ *
+ * Pure, offline functions ported directly from the real GeraTools browser
+ * islands (utility-tools/src/islands/*). No network, no DOM, no side effects —
+ * the same logic the published tools run, made callable from Node so an MCP
+ * client can use them headlessly.
+ *
+ * Sources:
+ *  - base64        ← Base64EncoderDecoder.tsx
+ *  - regex         ← RegexTester.tsx
+ *  - word count    ← WordCounter.tsx
+ *  - jwt decode    ← JwtDecode.tsx
+ *  - css units     ← CssUnitConverter.tsx
+ *  - hashing       ← uses Node's crypto (the browser tools use SubtleCrypto;
+ *                    same algorithms, same digests)
+ */
+import { createHash, getHashes } from 'node:crypto';
+// ── Base64 (ported from Base64EncoderDecoder.tsx) ────────────────────────────
+const STD = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/';
+export function bytesToBase64(bytes, url) {
+    let out = '';
+    for (let i = 0; i < bytes.length; i += 3) {
+        const b0 = bytes[i];
+        const b1 = i + 1 < bytes.length ? bytes[i + 1] : 0;
+        const b2 = i + 2 < bytes.length ? bytes[i + 2] : 0;
+        const triple = (b0 << 16) | (b1 << 8) | b2;
+        out += STD[(triple >> 18) & 0x3f];
+        out += STD[(triple >> 12) & 0x3f];
+        out += i + 1 < bytes.length ? STD[(triple >> 6) & 0x3f] : '=';
+        out += i + 2 < bytes.length ? STD[triple & 0x3f] : '=';
+    }
+    if (url) {
+        return out.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+    }
+    return out;
+}
+export function base64ToBytes(input) {
+    // Accept both standard and url-safe, restore padding.
+    let s = input.trim().replace(/\s+/g, '').replace(/-/g, '+').replace(/_/g, '/');
+    while (s.length % 4 !== 0)
+        s += '=';
+    const lookup = new Int16Array(256).fill(-1);
+    for (let i = 0; i < STD.length; i++)
+        lookup[STD.charCodeAt(i)] = i;
+    const clean = s.replace(/=+$/, '');
+    const outLen = Math.floor((clean.length * 6) / 8);
+    const out = new Uint8Array(outLen);
+    let bits = 0;
+    let acc = 0;
+    let o = 0;
+    for (let i = 0; i < clean.length; i++) {
+        const v = lookup[clean.charCodeAt(i)];
+        if (v < 0)
+            throw new Error(`Invalid Base64 character at position ${i + 1}.`);
+        acc = (acc << 6) | v;
+        bits += 6;
+        if (bits >= 8) {
+            bits -= 8;
+            out[o++] = (acc >> bits) & 0xff;
+        }
+    }
+    return out;
+}
+function hexToBytes(hex) {
+    const clean = hex.replace(/0x/gi, '').replace(/[\s,]+/g, '');
+    if (clean.length % 2 !== 0)
+        throw new Error('Hex must have an even number of digits.');
+    if (!/^[0-9a-fA-F]*$/.test(clean))
+        throw new Error('Hex contains non-hexadecimal characters.');
+    const out = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(clean.substr(i * 2, 2), 16);
+    }
+    return out;
+}
+function detectPayload(s) {
+    const t = s.trim();
+    if (/^data:/i.test(t))
+        return 'Looks like a data: URI — decode the part after the comma.';
+    if (/^-----BEGIN /.test(t))
+        return 'Looks like a PEM block — the Base64 body sits between the BEGIN/END armor lines.';
+    if (/^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]*$/.test(t))
+        return 'Looks like a JWT (three Base64url segments). Use the jwt_decode tool to read the header and payload.';
+    return null;
+}
+/** Binary-safe Base64 encode/decode, ported from the GeraTools browser tool. */
+export function base64(input, mode, opts = {}) {
+    const variant = opts.variant ?? 'std';
+    const inputKind = opts.inputKind ?? 'text';
+    if (mode === 'encode') {
+        const bytes = inputKind === 'hex' ? hexToBytes(input) : new TextEncoder().encode(input);
+        return {
+            mode,
+            variant,
+            output: bytesToBase64(bytes, variant === 'url'),
+            output_kind: 'base64',
+            note: null,
+        };
+    }
+    // decode
+    const bytes = base64ToBytes(input);
+    let text;
+    try {
+        text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch {
+        const hex = Array.from(bytes)
+            .map((b) => b.toString(16).padStart(2, '0'))
+            .join(' ');
+        return {
+            mode,
+            variant: null,
+            output: hex,
+            output_kind: 'hex',
+            note: 'Decoded bytes are not valid UTF-8 text — returning raw hex instead.',
+        };
+    }
+    return { mode, variant: null, output: text, output_kind: 'text', note: detectPayload(input) };
+}
+// ── Hashing (Node crypto — same algorithms the browser SubtleCrypto uses) ─────
+export const SUPPORTED_HASHES = ['md5', 'sha1', 'sha256', 'sha384', 'sha512'];
+/** Cryptographic digest of arbitrary input. Real Node crypto, deterministic. */
+export function hashText(input, algorithm, opts = {}) {
+    const inputEncoding = opts.inputEncoding ?? 'utf8';
+    const outputEncoding = opts.outputEncoding ?? 'hex';
+    if (!getHashes().includes(algorithm) && algorithm !== 'md5') {
+        throw new Error(`Algorithm "${algorithm}" is not available on this platform.`);
+    }
+    const buf = Buffer.from(input, inputEncoding);
+    const digest = createHash(algorithm).update(buf).digest(outputEncoding);
+    // digest length in bits = hex chars * 4
+    const hexLen = createHash(algorithm).update(buf).digest('hex').length;
+    return {
+        algorithm,
+        input_encoding: inputEncoding,
+        output_encoding: outputEncoding,
+        digest,
+        digest_bits: hexLen * 4,
+    };
+}
+// ── Regex tester (ported from RegexTester.tsx) ───────────────────────────────
+// A lightweight token-by-token plain-English explainer.
+export function explainRegex(pattern) {
+    const out = [];
+    let i = 0;
+    const classNames = {
+        '\\d': 'any digit (0-9)',
+        '\\D': 'any non-digit',
+        '\\w': 'any word character (letter, digit or underscore)',
+        '\\W': 'any non-word character',
+        '\\s': 'any whitespace',
+        '\\S': 'any non-whitespace',
+        '\\b': 'a word boundary',
+        '\\B': 'a non-word-boundary',
+    };
+    while (i < pattern.length) {
+        const c = pattern[i];
+        const two = pattern.slice(i, i + 2);
+        if (classNames[two]) {
+            out.push(`Match ${classNames[two]}.`);
+            i += 2;
+            continue;
+        }
+        if (c === '\\') {
+            out.push(`Match the literal character "${pattern[i + 1] ?? ''}".`);
+            i += 2;
+            continue;
+        }
+        switch (c) {
+            case '^':
+                out.push('Anchor to the start of the line/string.');
+                break;
+            case '$':
+                out.push('Anchor to the end of the line/string.');
+                break;
+            case '.':
+                out.push('Match any single character (except newline).');
+                break;
+            case '*':
+                out.push('Repeat the previous item zero or more times.');
+                break;
+            case '+':
+                out.push('Repeat the previous item one or more times.');
+                break;
+            case '?':
+                out.push('Make the previous item optional (zero or one).');
+                break;
+            case '|':
+                out.push('OR — match the expression before or after this.');
+                break;
+            case '(': {
+                if (pattern.slice(i, i + 3) === '(?:') {
+                    out.push('Start a non-capturing group.');
+                    i += 2;
+                }
+                else {
+                    out.push('Start a capturing group.');
+                }
+                break;
+            }
+            case ')':
+                out.push('End the group.');
+                break;
+            case '[': {
+                const end = pattern.indexOf(']', i);
+                const body = end > -1 ? pattern.slice(i + 1, end) : pattern.slice(i + 1);
+                const neg = body.startsWith('^');
+                out.push(`Match ${neg ? 'any character NOT' : 'any one character'} in the set [${neg ? body.slice(1) : body}].`);
+                i = end > -1 ? end : pattern.length;
+                break;
+            }
+            case '{': {
+                const end = pattern.indexOf('}', i);
+                const body = end > -1 ? pattern.slice(i + 1, end) : '';
+                out.push(`Repeat the previous item ${body} times.`);
+                i = end > -1 ? end : pattern.length;
+                break;
+            }
+            default:
+                out.push(`Match the literal character "${c}".`);
+        }
+        i++;
+    }
+    return out;
+}
+/** Run a JS regex against a test string and explain it, ported from the tool. */
+export function regexTest(pattern, test, flags = 'g') {
+    let re;
+    try {
+        re = new RegExp(pattern, flags);
+    }
+    catch (e) {
+        return {
+            pattern,
+            flags,
+            valid: false,
+            error: e instanceof Error ? e.message : 'Invalid pattern',
+            count: 0,
+            matches: [],
+            explanation: pattern ? explainRegex(pattern) : [],
+        };
+    }
+    // Force global to enumerate every match (matchAll requires the g flag).
+    const g = new RegExp(pattern, flags.includes('g') ? flags : flags + 'g');
+    const matches = [];
+    for (const m of test.matchAll(g)) {
+        matches.push({
+            match: m[0],
+            index: m.index ?? -1,
+            groups: m.slice(1).map((x) => x ?? ''),
+            namedGroups: m.groups ? { ...m.groups } : null,
+        });
+        if (m[0] === '')
+            break; // guard against zero-width infinite loop
+    }
+    return {
+        pattern,
+        flags,
+        valid: true,
+        error: null,
+        count: matches.length,
+        matches,
+        explanation: pattern ? explainRegex(pattern) : [],
+    };
+}
+// ── Word counter (ported from WordCounter.tsx) ───────────────────────────────
+const WORDS_PER_MINUTE = 200;
+function fmtTime(secs) {
+    if (secs < 60)
+        return `${secs}s`;
+    const m = Math.floor(secs / 60);
+    const s = secs % 60;
+    return s === 0 ? `${m} min` : `${m} min ${s}s`;
+}
+/** Word / character / sentence / paragraph stats, ported from the tool. */
+export function wordCount(text) {
+    const trimmed = text.trim();
+    const words = trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
+    const charsWithSpaces = text.length;
+    const charsNoSpaces = text.replace(/\s/g, '').length;
+    const sentences = trimmed.length === 0
+        ? 0
+        : trimmed.split(/[.!?]+/).filter((s) => s.trim().length > 0).length;
+    const paragraphs = trimmed.length === 0
+        ? 0
+        : trimmed.split(/\n\s*\n/).filter((p) => p.trim().length > 0).length;
+    const lines = text.length === 0 ? 0 : text.split(/\n/).length;
+    const readingTimeSeconds = Math.ceil((words / WORDS_PER_MINUTE) * 60);
+    return {
+        words,
+        charsWithSpaces,
+        charsNoSpaces,
+        sentences,
+        paragraphs,
+        lines,
+        readingTimeSeconds,
+        readingTimeHuman: words === 0 ? '0s' : fmtTime(readingTimeSeconds),
+    };
+}
+// ── JWT decode (ported from JwtDecode.tsx) ───────────────────────────────────
+const TIME_CLAIMS = ['iat', 'nbf', 'exp'];
+function base64UrlDecodeToString(seg) {
+    const bytes = base64ToBytes(seg);
+    return new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+}
+/** Decode (NOT verify) a JWT into header/payload + time claims. */
+export function jwtDecode(token) {
+    const raw = token.trim();
+    const parts = raw.split('.');
+    if (parts.length < 2) {
+        throw new Error('Not a JWT: expected at least header.payload separated by dots.');
+    }
+    let header;
+    try {
+        header = JSON.parse(base64UrlDecodeToString(parts[0]));
+    }
+    catch {
+        throw new Error('Could not Base64url-decode the header as JSON.');
+    }
+    let payload;
+    try {
+        payload = JSON.parse(base64UrlDecodeToString(parts[1]));
+    }
+    catch {
+        throw new Error('Could not Base64url-decode the payload as JSON.');
+    }
+    const timeClaims = [];
+    let expired = null;
+    for (const claim of TIME_CLAIMS) {
+        const v = payload[claim];
+        if (typeof v === 'number' && Number.isFinite(v)) {
+            timeClaims.push({ claim, epoch: v, iso: new Date(v * 1000).toISOString() });
+            if (claim === 'exp')
+                expired = Date.now() > v * 1000;
+        }
+    }
+    return {
+        header,
+        payload,
+        signature: parts[2] ?? '',
+        timeClaims,
+        expired,
+        note: 'Signature is NOT verified. Never trust an unverified payload for authorization — verify server-side with the signing key.',
+    };
+}
+// ── CSS unit converter (ported from CssUnitConverter.tsx) ─────────────────────
+const PX_PER_IN = 96;
+const ABSOLUTE = [
+    { unit: 'px', pxPer: 1 },
+    { unit: 'in', pxPer: PX_PER_IN },
+    { unit: 'cm', pxPer: PX_PER_IN / 2.54 },
+    { unit: 'mm', pxPer: PX_PER_IN / 25.4 },
+    { unit: 'Q', pxPer: PX_PER_IN / 25.4 / 4 },
+    { unit: 'pt', pxPer: PX_PER_IN / 72 },
+    { unit: 'pc', pxPer: PX_PER_IN / 6 },
+];
+export const CSS_UNITS = ['px', 'rem', 'em', 'pt', 'pc', 'in', 'cm', 'mm', 'Q'];
+const round = (n) => Math.round(n * 1e6) / 1e6;
+/** Convert a CSS length to every other unit, ported from the tool. */
+export function cssUnitConvert(value, from, opts = {}) {
+    const root = opts.rootFontPx && Number.isFinite(opts.rootFontPx) ? opts.rootFontPx : 16;
+    const parent = opts.parentFontPx && Number.isFinite(opts.parentFontPx) ? opts.parentFontPx : 16;
+    // To px baseline first.
+    let px;
+    if (from === 'rem')
+        px = value * root;
+    else if (from === 'em')
+        px = value * parent;
+    else {
+        const abs = ABSOLUTE.find((a) => a.unit === from);
+        px = abs ? value * abs.pxPer : value;
+    }
+    const toUnit = (unit) => {
+        if (unit === 'rem')
+            return px / root;
+        if (unit === 'em')
+            return px / parent;
+        const abs = ABSOLUTE.find((a) => a.unit === unit);
+        return abs ? px / abs.pxPer : px;
+    };
+    const conversions = {};
+    for (const u of CSS_UNITS)
+        conversions[u] = round(toUnit(u));
+    return { value, from, rootFontPx: root, parentFontPx: parent, px: round(px), conversions };
+}

package/dist/server.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GeraTools MCP Server (stdio)
+ *
+ * Exposes a handful of the real GeraTools developer utilities to AI agents over
+ * the Model Context Protocol. Every tool is a pure, deterministic function
+ * ported straight from the published GeraTools browser tools (or Node's
+ * crypto) — no backend, no network, no auth — so an agent (Claude, ChatGPT
+ * with tools, any MCP client) can base64-encode, hash, test a regex, count
+ * words, decode a JWT, or convert CSS units entirely offline.
+ *
+ * Product: GeraTools — https://geratools.com (a Gera Systems product)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const server: McpServer;
+export declare function main(): Promise<void>;

package/dist/server.js

@@ -0,0 +1,162 @@
+/**
+ * GeraTools MCP Server (stdio)
+ *
+ * Exposes a handful of the real GeraTools developer utilities to AI agents over
+ * the Model Context Protocol. Every tool is a pure, deterministic function
+ * ported straight from the published GeraTools browser tools (or Node's
+ * crypto) — no backend, no network, no auth — so an agent (Claude, ChatGPT
+ * with tools, any MCP client) can base64-encode, hash, test a regex, count
+ * words, decode a JWT, or convert CSS units entirely offline.
+ *
+ * Product: GeraTools — https://geratools.com (a Gera Systems product)
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { base64, hashText, SUPPORTED_HASHES, regexTest, wordCount, jwtDecode, cssUnitConvert, CSS_UNITS, } from './engine.js';
+export const server = new McpServer({
+    name: 'geratools',
+    version: '1.0.0',
+});
+function asText(payload) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+    };
+}
+function asError(message) {
+    return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: message }, null, 2) }],
+    };
+}
+// ── Tool 1: base64 ────────────────────────────────────────────────────────────
+server.registerTool('base64', {
+    title: 'Base64 encode / decode (UTF-8 safe)',
+    description: 'Encode text or hex bytes to Base64, or decode Base64 / Base64url back to text. Binary-safe via UTF-8 so emoji and non-ASCII round-trip correctly. Supports standard (+ / with = padding) and URL-safe (- _ no padding) variants. Decoding auto-restores padding and falls back to raw hex if the bytes are not valid UTF-8. Runs entirely offline — same logic as the GeraTools Base64 tool.',
+    inputSchema: {
+        input: z.string().describe('The text/hex to encode, or the Base64 string to decode.'),
+        mode: z.enum(['encode', 'decode']).describe('"encode" text→Base64, or "decode" Base64→text.'),
+        variant: z
+            .enum(['std', 'url'])
+            .optional()
+            .describe('Encode output: "std" (default) or "url" (URL-safe Base64url). Ignored when decoding.'),
+        input_kind: z
+            .enum(['text', 'hex'])
+            .optional()
+            .describe('When encoding, treat input as UTF-8 "text" (default) or "hex" bytes.'),
+    },
+}, async ({ input, mode, variant, input_kind }) => {
+    try {
+        return asText(base64(input, mode, {
+            variant: variant,
+            inputKind: input_kind,
+        }));
+    }
+    catch (e) {
+        return asError(e instanceof Error ? e.message : 'Base64 operation failed.');
+    }
+});
+// ── Tool 2: hash ──────────────────────────────────────────────────────────────
+server.registerTool('hash', {
+    title: 'Cryptographic hash (MD5 / SHA-1 / SHA-256 / SHA-384 / SHA-512)',
+    description: 'Compute a cryptographic digest of the input using Node crypto — the same algorithms a browser SubtleCrypto produces. Input can be utf8 (default), hex, or base64; output as hex (default) or base64. Deterministic and offline. Note: MD5 and SHA-1 are provided for checksums/legacy interop only, not for security.',
+    inputSchema: {
+        input: z.string().describe('The data to hash.'),
+        algorithm: z
+            .enum(SUPPORTED_HASHES)
+            .describe('Hash algorithm: md5, sha1, sha256, sha384, or sha512.'),
+        input_encoding: z
+            .enum(['utf8', 'hex', 'base64'])
+            .optional()
+            .describe('How to interpret the input bytes. Default utf8.'),
+        output_encoding: z
+            .enum(['hex', 'base64'])
+            .optional()
+            .describe('Digest output encoding. Default hex.'),
+    },
+}, async ({ input, algorithm, input_encoding, output_encoding }) => {
+    try {
+        return asText(hashText(input, algorithm, {
+            inputEncoding: input_encoding,
+            outputEncoding: output_encoding,
+        }));
+    }
+    catch (e) {
+        return asError(e instanceof Error ? e.message : 'Hashing failed.');
+    }
+});
+// ── Tool 3: regex_test ────────────────────────────────────────────────────────
+server.registerTool('regex_test', {
+    title: 'Test a regular expression against a string',
+    description: 'Run a JavaScript regular expression against a test string and return every match (with index, capture groups and named groups), the match count, and a plain-English, token-by-token explanation of the pattern. Invalid patterns return the engine error rather than throwing. Offline — same logic as the GeraTools Regex Tester.',
+    inputSchema: {
+        pattern: z.string().describe('The regular expression source (no surrounding slashes).'),
+        test_string: z.string().describe('The string to run the regex against.'),
+        flags: z
+            .string()
+            .optional()
+            .describe('Regex flags, e.g. "gi". Default "g". (g is forced internally for enumeration.)'),
+    },
+}, async ({ pattern, test_string, flags }) => {
+    return asText(regexTest(pattern, test_string, flags ?? 'g'));
+});
+// ── Tool 4: word_count ────────────────────────────────────────────────────────
+server.registerTool('word_count', {
+    title: 'Count words, characters, sentences and reading time',
+    description: 'Analyse a block of text: word count, characters (with and without spaces), sentence count, paragraph count, line count, and estimated reading time (200 wpm). Offline — same logic as the GeraTools Word Counter.',
+    inputSchema: {
+        text: z.string().describe('The text to analyse.'),
+    },
+}, async ({ text }) => asText(wordCount(text)));
+// ── Tool 5: jwt_decode ────────────────────────────────────────────────────────
+server.registerTool('jwt_decode', {
+    title: 'Decode a JSON Web Token (no signature verification)',
+    description: 'Base64url-decode a JWT into its header and payload JSON, list the iat/nbf/exp time claims as ISO timestamps, and report whether the token is expired. Does NOT verify the signature — never trust an unverified payload for authorization. Offline — same logic as the GeraTools JWT Decoder.',
+    inputSchema: {
+        token: z.string().describe('The JWT, e.g. "header.payload.signature".'),
+    },
+}, async ({ token }) => {
+    try {
+        return asText(jwtDecode(token));
+    }
+    catch (e) {
+        return asError(e instanceof Error ? e.message : 'Could not decode the token.');
+    }
+});
+// ── Tool 6: css_unit_convert ──────────────────────────────────────────────────
+server.registerTool('css_unit_convert', {
+    title: 'Convert a CSS length between units',
+    description: 'Convert a CSS length value from one unit to every other CSS unit (px, rem, em, pt, pc, in, cm, mm, Q). Absolute units use 1in = 96px; rem depends on root font size and em on parent font size (both default 16px). Offline — same logic as the GeraTools CSS Unit Converter.',
+    inputSchema: {
+        value: z.number().describe('The numeric length value.'),
+        from: z.enum(CSS_UNITS).describe('The unit of the input value.'),
+        root_font_px: z
+            .number()
+            .optional()
+            .describe('Root font size in px, used for rem. Default 16.'),
+        parent_font_px: z
+            .number()
+            .optional()
+            .describe('Parent font size in px, used for em. Default 16.'),
+    },
+}, async ({ value, from, root_font_px, parent_font_px }) => asText(cssUnitConvert(value, from, {
+    rootFontPx: root_font_px,
+    parentFontPx: parent_font_px,
+})));
+// ── Start ─────────────────────────────────────────────────────────────────────
+export async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // stderr only — stdout is the MCP transport.
+    console.error('GeraTools MCP server running on stdio (geratools v1.0.0)');
+}
+// Run when invoked directly as the built server (node dist/server.js).
+// The bin/cli.js entry imports and calls main() itself, so we only auto-run
+// for direct server.js invocation to avoid a double start.
+const isMain = typeof process !== 'undefined' && process.argv[1] && /server\.js$/.test(process.argv[1]);
+if (isMain) {
+    main().catch((err) => {
+        console.error('Fatal:', err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@gera-services/mcp-geratools",
+  "version": "1.0.0",
+  "description": "GeraTools MCP server — base64, cryptographic hashing, regex testing, word count, JWT decode and CSS unit conversion. Deterministic, offline, no auth. A Gera Systems product.",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/server.js",
+  "types": "dist/server.d.ts",
+  "mcpName": "io.github.geraservicesuk/mcp-geratools",
+  "bin": {
+    "mcp-geratools": "bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "server.json",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --noCheck",
+    "type-check": "tsc --noEmit",
+    "start": "node bin/cli.js",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "base64",
+    "hash",
+    "sha256",
+    "regex",
+    "jwt",
+    "word-count",
+    "gera",
+    "geratools",
+    "developer-tools"
+  ],
+  "author": "Gera Systems Ltd",
+  "homepage": "https://geratools.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/geraservicesuk/globetura.git",
+    "directory": "packages/mcp-geratools"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.12.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/server.json

@@ -0,0 +1,22 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.geraservicesuk/mcp-geratools",
+  "description": "base64, hashing, regex, word count, JWT decode and CSS unit conversion. Deterministic, offline.",
+  "version": "1.0.0",
+  "repository": {
+    "url": "https://github.com/geraservicesuk/globetura",
+    "source": "github",
+    "subfolder": "packages/mcp-geratools"
+  },
+  "websiteUrl": "https://geratools.com",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@gera-services/mcp-geratools",
+      "version": "1.0.0",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}