util-beauty-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Undercurrent Labs LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# util-beauty-mcp
+
+Thin [MCP](https://modelcontextprotocol.io) stdio server for [util.beauty](https://util.beauty).
+
+**Three tools only** (low context cost):
+
+| Tool | Purpose |
+|---|---|
+| `list_utilities` | Live catalog from `GET /v1/meta` |
+| `describe_utility` | OpenAPI request schema for one utility |
+| `call_utility` | Paid POST (x402 or API key) |
+
+## Run
+
+```bash
+cd mcp && npm install
+export X402_PRIVATE_KEY=0x...   # USDC on Base
+# optional: export UB_API_KEY=ub_...
+# optional: export UTIL_BEAUTY_BASE_URL=https://util.beauty
+npx util-beauty-mcp
+```
+
+## Claude Code
+
+```bash
+claude mcp add util-beauty \
+  -e X402_PRIVATE_KEY=0x... \
+  -- npx -y util-beauty-mcp
+```
+
+## Design
+
+Schemas are **not** embedded in tool definitions. Agents must list → describe → call, which matches util.beauty’s `/v1/meta` + OpenAPI discovery model and keeps `tools/list` small.
+
+Payment for `call_utility` reuses the same EIP-3009 flow as production x402 (viem), without requiring `@x402/fetch` to understand util.beauty’s 402 envelope.
+
+See https://util.beauty/mcp and https://util.beauty/skill.md.

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "util-beauty-mcp",
+  "version": "1.0.0",
+  "description": "Thin MCP server for util.beauty — list_utilities, describe_utility, call_utility (discover-then-call, low context).",
+  "type": "module",
+  "bin": {
+    "util-beauty-mcp": "./src/index.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "start": "node src/index.mjs"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "viem": "^2.55.0",
+    "zod": "^3.25.0"
+  },
+  "keywords": [
+    "mcp",
+    "x402",
+    "util.beauty",
+    "agents"
+  ],
+  "license": "MIT",
+  "author": "Undercurrent Labs LLC",
+  "homepage": "https://util.beauty/mcp",
+  "bugs": "https://util.beauty/contact"
+}

package/src/index.mjs

@@ -0,0 +1,289 @@
+#!/usr/bin/env node
+/**
+ * util-beauty-mcp — discover-then-call MCP server.
+ *
+ * Tools (intentionally tiny schemas):
+ *   list_utilities   → GET /v1/meta
+ *   describe_utility → OpenAPI request body for one utility
+ *   call_utility     → POST paid endpoint (x402 or API key)
+ *
+ * Env:
+ *   UTIL_BEAUTY_BASE_URL  default https://util.beauty
+ *   X402_PRIVATE_KEY      hex EVM key with USDC on Base
+ *   UB_API_KEY            optional prepaid key
+ */
+import { randomBytes, randomUUID } from "node:crypto";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { privateKeyToAccount } from "viem/accounts";
+
+const BASE = (process.env.UTIL_BEAUTY_BASE_URL ?? "https://util.beauty").replace(/\/$/, "");
+const CHAIN_IDS = { base: 8453, "base-sepolia": 84532 };
+
+/** @type {{ doc: object, fetchedAt: number } | null} */
+let openapiCache = null;
+const OPENAPI_TTL_MS = 10 * 60 * 1000;
+
+function textResult(data, isError = false) {
+  const text = typeof data === "string" ? data : JSON.stringify(data, null, 2);
+  return { content: [{ type: "text", text }], isError };
+}
+
+async function fetchJson(url, init) {
+  const res = await fetch(url, init);
+  const text = await res.text();
+  let body;
+  try {
+    body = text ? JSON.parse(text) : null;
+  } catch {
+    body = { raw: text.slice(0, 2000) };
+  }
+  return { res, body };
+}
+
+async function getOpenApi() {
+  const now = Date.now();
+  if (openapiCache && now - openapiCache.fetchedAt < OPENAPI_TTL_MS) {
+    return openapiCache.doc;
+  }
+  const { res, body } = await fetchJson(`${BASE}/openapi.json`);
+  if (!res.ok) throw new Error(`openapi.json HTTP ${res.status}`);
+  openapiCache = { doc: body, fetchedAt: now };
+  return body;
+}
+
+function pathForUtility(utility) {
+  return `/v1/${utility.replace(".", "/")}`;
+}
+
+function schemaForUtility(openapi, utility) {
+  const path = pathForUtility(utility);
+  const op = openapi.paths?.[path]?.post;
+  if (!op) {
+    return {
+      utility,
+      path,
+      note: "No POST operation in OpenAPI for this utility. Check /v1/meta.",
+    };
+  }
+  const ref = op.requestBody?.content?.["application/json"]?.schema;
+  let schema = ref;
+  if (ref?.$ref) {
+    const name = ref.$ref.split("/").pop();
+    schema = openapi.components?.schemas?.[name] ?? ref;
+  }
+  return {
+    utility,
+    path: `${BASE}${path}`,
+    method: "POST",
+    summary: op.summary ?? op.description ?? null,
+    requestBodySchema: schema ?? null,
+    notes: [
+      "Browser utilities: provide exactly one of url or html.",
+      "Crypto utilities: binary fields are base64-encoded.",
+      "Always send Idempotency-Key on paid calls.",
+      "Billing is per-attempt after validation (VALIDATION_ERROR is free).",
+    ],
+  };
+}
+
+async function signX402Payment(accepts0) {
+  const key = process.env.X402_PRIVATE_KEY;
+  if (!key) throw new Error("X402_PRIVATE_KEY is not set");
+  const raw = key.startsWith("0x") ? key : `0x${key}`;
+  const account = privateKeyToAccount(/** @type {`0x${string}`} */ (raw));
+  const chainId = CHAIN_IDS[accepts0.network];
+  if (!chainId) throw new Error(`Unsupported x402 network: ${accepts0.network}`);
+
+  const now = Math.floor(Date.now() / 1000);
+  const authorization = {
+    from: account.address,
+    to: accepts0.payTo,
+    value: BigInt(accepts0.maxAmountRequired),
+    validAfter: BigInt(now - 60),
+    validBefore: BigInt(now + (accepts0.maxTimeoutSeconds ?? 300)),
+    nonce: `0x${randomBytes(32).toString("hex")}`,
+  };
+  const signature = await account.signTypedData({
+    domain: {
+      name: accepts0.extra?.name ?? "USD Coin",
+      version: accepts0.extra?.version ?? "2",
+      chainId,
+      verifyingContract: accepts0.asset,
+    },
+    types: {
+      TransferWithAuthorization: [
+        { name: "from", type: "address" },
+        { name: "to", type: "address" },
+        { name: "value", type: "uint256" },
+        { name: "validAfter", type: "uint256" },
+        { name: "validBefore", type: "uint256" },
+        { name: "nonce", type: "bytes32" },
+      ],
+    },
+    primaryType: "TransferWithAuthorization",
+    message: authorization,
+  });
+
+  const payload = {
+    x402Version: 1,
+    scheme: accepts0.scheme,
+    network: accepts0.network,
+    payload: {
+      signature,
+      authorization: {
+        from: authorization.from,
+        to: authorization.to,
+        value: authorization.value.toString(),
+        validAfter: authorization.validAfter.toString(),
+        validBefore: authorization.validBefore.toString(),
+        nonce: authorization.nonce,
+      },
+    },
+  };
+  return Buffer.from(JSON.stringify(payload)).toString("base64");
+}
+
+async function callUtility(utility, body, idempotencyKey) {
+  const url = `${BASE}${pathForUtility(utility)}`;
+  const headers = {
+    "Content-Type": "application/json",
+    "Idempotency-Key": idempotencyKey || randomUUID(),
+  };
+  const jsonBody = JSON.stringify(body ?? {});
+
+  if (process.env.UB_API_KEY) {
+    headers.Authorization = `Bearer ${process.env.UB_API_KEY}`;
+    const { res, body: resp } = await fetchJson(url, {
+      method: "POST",
+      headers,
+      body: jsonBody,
+    });
+    return {
+      status: res.status,
+      paymentMode: "api_key",
+      paymentResponse: res.headers.get("x-payment-response"),
+      body: resp,
+    };
+  }
+
+  if (!process.env.X402_PRIVATE_KEY) {
+    throw new Error(
+      "Set X402_PRIVATE_KEY (USDC on Base) or UB_API_KEY before call_utility.",
+    );
+  }
+
+  // Unpaid probe → 402 with accepts
+  const unpaid = await fetchJson(url, { method: "POST", headers, body: jsonBody });
+  if (unpaid.res.status !== 402) {
+    // Already succeeded (unlikely) or validation error free
+    return {
+      status: unpaid.res.status,
+      paymentMode: "none",
+      body: unpaid.body,
+    };
+  }
+
+  const accepts0 = unpaid.body?.error?.details?.accepts?.[0];
+  if (!accepts0) {
+    return {
+      status: 402,
+      paymentMode: "x402",
+      error: "PAYMENT_REQUIRED without accepts[0]",
+      body: unpaid.body,
+    };
+  }
+
+  const xPayment = await signX402Payment(accepts0);
+  const paid = await fetchJson(url, {
+    method: "POST",
+    headers: { ...headers, "X-PAYMENT": xPayment },
+    body: jsonBody,
+  });
+  return {
+    status: paid.res.status,
+    paymentMode: "x402",
+    paymentResponse: paid.res.headers.get("x-payment-response"),
+    quote: unpaid.body?.error?.details?.quote,
+    body: paid.body,
+  };
+}
+
+const server = new McpServer({
+  name: "util-beauty",
+  version: "1.0.0",
+});
+
+server.tool(
+  "list_utilities",
+  "List util.beauty utilities, prices, payment modes, and limits from live GET /v1/meta. Call this before inventing names or prices.",
+  {},
+  async () => {
+    try {
+      const { res, body } = await fetchJson(`${BASE}/v1/meta`);
+      if (!res.ok) return textResult({ status: res.status, body }, true);
+      // Compact payload for agents
+      const compact = {
+        service: body.service,
+        version: body.version,
+        base: BASE,
+        payment: body.payment,
+        utilities: (body.utilities ?? []).map((u) => ({
+          name: u.name,
+          endpoint: u.endpoint,
+          credits: u.credits,
+          usdMicros: u.usdMicros,
+          description: u.description,
+        })),
+        limits: body.limits,
+        openapiUrl: body.openapiUrl,
+      };
+      return textResult(compact);
+    } catch (err) {
+      return textResult({ error: String(err?.message ?? err) }, true);
+    }
+  },
+);
+
+server.tool(
+  "describe_utility",
+  "Return the OpenAPI request body schema and notes for one util.beauty utility (e.g. browser.screenshot, crypto.hash). Use after list_utilities.",
+  { utility: z.string().describe("Utility name from list_utilities, e.g. crypto.hash") },
+  async ({ utility }) => {
+    try {
+      const openapi = await getOpenApi();
+      return textResult(schemaForUtility(openapi, utility));
+    } catch (err) {
+      return textResult({ error: String(err?.message ?? err) }, true);
+    }
+  },
+);
+
+server.tool(
+  "call_utility",
+  "Call a util.beauty utility (POST). Pays with X402_PRIVATE_KEY (x402) or UB_API_KEY. Prefer describe_utility first for body shape. Billing is per-attempt after validation.",
+  {
+    utility: z.string().describe("e.g. browser.extract or crypto.hash"),
+    body: z
+      .record(z.unknown())
+      .describe("JSON request body for the utility")
+      .optional(),
+    idempotencyKey: z
+      .string()
+      .describe("Optional Idempotency-Key; generated if omitted")
+      .optional(),
+  },
+  async ({ utility, body, idempotencyKey }) => {
+    try {
+      const result = await callUtility(utility, body ?? {}, idempotencyKey);
+      const isError = result.status >= 400;
+      return textResult(result, isError);
+    } catch (err) {
+      return textResult({ error: String(err?.message ?? err) }, true);
+    }
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);