@forgemeshlabs/utility-grid-mcp 0.1.0

package/.dockerignore

@@ -0,0 +1,9 @@
+.git
+node_modules
+npm-debug.log*
+*.log
+.env
+.env.*
+*.tgz
+coverage
+.DS_Store

package/Dockerfile

@@ -0,0 +1,16 @@
+FROM node:20-slim
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev
+
+COPY index.js README.md LICENSE server.json glama.json GLAMA.md smithery.yaml ./
+RUN chmod +x /app/index.js
+
+ENV NODE_ENV=production \
+  UTILITY_GRID_BASE_URL=https://x402.forgemesh.io
+
+USER node
+
+ENTRYPOINT ["node", "index.js"]

package/GLAMA.md

@@ -0,0 +1,65 @@
+# Glama Build Notes
+
+Durable source for Glama admin fields. Keep this in the public MCP repo so the
+next refresh does not depend on chat history.
+
+## Repository
+
+- GitHub: https://github.com/forgemeshlabs/utility-grid-mcp
+- npm: @forgemeshlabs/utility-grid-mcp
+- Hosted API: https://x402.forgemesh.io
+
+## Build Steps
+
+Plain JavaScript with lockfile:
+
+```json
+["npm ci --omit=dev"]
+```
+
+`package.json` also defines a no-op `"build"` script (`echo "no build step required"`).
+Glama's generic build pipeline runs `npm install && npm run build` regardless of
+the custom steps above — without this no-op script the build fails with
+`npm error Missing script: "build"`. Keep this script in every future MCP package
+even when there is nothing to compile.
+
+## Command Arguments
+
+```json
+["node", "index.js"]
+```
+
+If Glama shows a full proxy wrapper, it may render something like:
+
+```json
+["mcp-proxy", "--", "node", "index.js"]
+```
+
+In the manual command field, enter only the server startup command unless Glama
+explicitly asks for the wrapped command.
+
+## Placeholder Arguments
+
+```json
+{}
+```
+
+## Environment Variables
+
+Canonical env schema belongs in `server.json`, not `glama.json`.
+
+- `WALLET_PRIVATE_KEY` - optional, only required for the 3 paid tools (`call_endpoint`, `daily_402`, `agent_service_directory`). A dedicated low-balance Base wallet.
+- `UTILITY_GRID_BASE_URL` - optional hosted API base URL override.
+
+## Dockerfile
+
+Glama generates its own server runtime from admin fields. The repo Dockerfile is
+a reference and local smoke-test target only.
+
+```bash
+docker build -t utility-grid-mcp .
+docker run --rm -i utility-grid-mcp
+```
+
+Do not bake wallet private keys, API keys, `.env`, runtime databases, or test
+wallet files into the image.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ForgeMesh Labs
+
+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,74 @@
+# ForgeMesh Utility Grid — Agent Utility APIs via x402
+
+*A [ForgeMesh Labs](https://forgemesh.io) product.*
+
+**415+ small agent utility jobs behind 6 tools, not 415.** OCR, vision, audio, embeddings, web extraction, dictionary and slang lookups, chess/legal-move logic, math, conversions, time, geo/space data, and x402 ecosystem intelligence — all paid per call in USDC on Base via [x402](https://x402.org). No API key, no account.
+
+Rather than exposing one MCP tool per route (unmanageable at this scale and growing), this server exposes a handful of **meta-tools**: browse/search the live catalog, fetch a route's exact call spec, then call any route generically. New routes on the upstream service show up automatically — nothing here is hardcoded to today's catalog.
+
+## Quick start (Claude Desktop / Claude Code / any MCP client)
+
+```json
+{
+  "mcpServers": {
+    "utility-grid": {
+      "command": "npx",
+      "args": ["-y", "@forgemeshlabs/utility-grid-mcp"],
+      "env": {
+        "WALLET_PRIVATE_KEY": "0x..."
+      }
+    }
+  }
+}
+```
+
+`WALLET_PRIVATE_KEY` is only needed for the 3 paid tools. Discovery works with **no wallet at all** — skip the `env` block entirely to browse and plan calls for free.
+
+## Tools
+
+| Tool | Cost | What it does |
+|---|---|---|
+| `list_capabilities` | **free** | Category overview with route counts, or every route in one category |
+| `search_capabilities` | **free** | Keyword search across every route's path, id, and description |
+| `get_endpoint_spec` | **free** | A route's exact price, input schema, and worked request/response examples |
+| `call_endpoint` | $0.001-$0.05 | Call any route by path + JSON body — handles the x402 payment flow automatically |
+| `daily_402` | $0.001 | The Daily 402: one featured endpoint from the whole ForgeMesh fleet, rotated by UTC date |
+| `agent_service_directory` | $0.05 | Registry of every ForgeMesh x402 service — category, route count, price range |
+
+## Categories in the catalog (illustrative, not exhaustive)
+
+geo (airports, zip codes, geocoding, weather), lookups (dictionary, Bible, country info, holidays), math (statistics, matrices, equations, geometry), utilities (QR codes, hashing, UUIDs, phone parsing), vision (OCR, image captioning, background removal), audio (TTS, transcription, format conversion), time (timezones, cron, sun/moon), space (NASA APOD, asteroids, solar weather), web (content extraction, robots.txt/Content-Signal checks), registry (fleet catalog, daily spotlight), documents (PDF handling), text (language detection, readability), economy (fx rates, financial calculators), science, developer, domains, ai, and fun (fortunes, chess, trivia).
+
+Call `list_capabilities` with no arguments for the live, current breakdown — the catalog grows over time and this README will drift; the tool won't.
+
+## Typical flow
+
+1. `search_capabilities({ query: "background removal" })` — free, finds `/remove-background`
+2. `get_endpoint_spec({ path: "remove-background" })` — free, shows the exact input schema and price
+3. `call_endpoint({ path: "remove-background", body: { image_url: "https://..." } })` — paid, does the x402 dance and returns the result
+
+Or skip straight to `call_endpoint` if you already know the route and its input shape.
+
+## How payment works
+
+No signup, no API key, no subscription. `call_endpoint`, `daily_402`, and `agent_service_directory` each trigger the same flow: the first request returns an HTTP 402 challenge, this MCP server signs a USDC payment authorization (EIP-3009) on Base and retries, and the result lands in the same response — including settlement details under `_payment` when available.
+
+## Direct API
+
+Prefer raw HTTP? The full agent-readable surface:
+
+- `https://x402.forgemesh.io/llms.txt` — one-page summary for agents
+- `https://x402.forgemesh.io/openapi.json` — OpenAPI 3.1 with x402 payment metadata, full input schemas, and worked examples for every route (this is what `list_capabilities`/`search_capabilities`/`get_endpoint_spec` read from, live, every call)
+- `https://x402.forgemesh.io/.well-known/x402.json` — x402 discovery manifest
+
+## FAQ
+
+**Do I need an account or API key?** No. x402 payments are the only credential, and only for the 3 paid tools.
+
+**What chain and token?** USDC on Base mainnet (`eip155:8453`).
+
+**Will this break when the upstream catalog changes?** No — `list_capabilities`, `search_capabilities`, and `get_endpoint_spec` all read `/openapi.json` live (cached in-memory for 5 minutes). `call_endpoint` never needs a hardcoded schema at all; it just forwards your JSON body.
+
+---
+
+Built by [ForgeMesh Labs](https://forgemesh.io) · Powered by the [x402 protocol](https://x402.org) · MIT License

package/glama.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "name": "@forgemeshlabs/utility-grid-mcp",
+  "description": "415+ agent utility jobs (OCR, vision, audio, math, conversions, geo/space, x402 intelligence) behind 6 meta-tools with free discovery and generic paid calling via x402.",
+  "maintainers": [
+    "clawdbotworker"
+  ],
+  "build": {
+    "steps": [
+      "npm ci --omit=dev"
+    ],
+    "cmd": [
+      "node",
+      "index.js"
+    ]
+  },
+  "placeholderArguments": {},
+  "tags": [
+    "x402",
+    "usdc",
+    "base",
+    "utility-grid",
+    "ocr",
+    "vision",
+    "tts",
+    "geo",
+    "math",
+    "mcp",
+    "autonomous-agents"
+  ]
+}

package/index.js

@@ -0,0 +1,378 @@
+#!/usr/bin/env node
+"use strict";
+
+const { Server } = require("@modelcontextprotocol/sdk/server/index.js");
+const { StdioServerTransport } = require("@modelcontextprotocol/sdk/server/stdio.js");
+const { CallToolRequestSchema, ListToolsRequestSchema } = require("@modelcontextprotocol/sdk/types.js");
+const { x402Client, x402HTTPClient } = require("@x402/core/client");
+const { ExactEvmScheme } = require("@x402/evm/exact/client");
+const { toClientEvmSigner } = require("@x402/evm");
+const { privateKeyToAccount } = require("viem/accounts");
+const { createPublicClient, http } = require("viem");
+const { base } = require("viem/chains");
+
+const VERSION = "0.1.0";
+const BASE_URL = (process.env.UTILITY_GRID_BASE_URL || "https://x402.forgemesh.io").replace(/\/$/, "");
+const BASE_RPC_URL = process.env.BASE_RPC_URL || "https://mainnet.base.org";
+
+// Example upstream capabilities, grouped by category, to orient an agent
+// before it calls list_capabilities/search_capabilities. This is illustrative
+// only — the live catalog (415 routes at build time, and growing) is always
+// fetched fresh from /openapi.json, never hardcoded here.
+const CATEGORY_EXAMPLES =
+  "geo (airports, zip codes, geocoding, weather), lookups (dictionary, bible, country info, holidays), " +
+  "math (statistics, matrices, equations, geometry), utilities (QR codes, hashing, UUIDs, phone parsing), " +
+  "vision (OCR, image captioning, background removal), audio (TTS, transcription, format conversion), " +
+  "time (timezones, cron, sun/moon), space (NASA APOD, asteroids, solar weather), " +
+  "web (content extraction, robots.txt/Content-Signal checks), registry (fleet catalog, daily spotlight), " +
+  "documents (PDF handling), text (language detection, readability), economy (fx rates, financial calculators), " +
+  "science, developer, domains, ai, conversions, and fun (fortunes, chess, trivia)";
+
+// --- discovery (free, no wallet needed) -----------------------------------
+
+let discoveryCache = null; // { at: number, spec: object }
+const DISCOVERY_TTL_MS = 5 * 60 * 1000;
+
+async function fetchOpenApiSpec() {
+  if (discoveryCache && Date.now() - discoveryCache.at < DISCOVERY_TTL_MS) return discoveryCache.spec;
+  const res = await fetch(`${BASE_URL}/openapi.json`);
+  if (!res.ok) throw new Error(`Failed to fetch discovery doc: HTTP ${res.status}`);
+  const spec = await res.json();
+  discoveryCache = { at: Date.now(), spec };
+  return spec;
+}
+
+function normalizePath(input) {
+  let p = String(input || "").trim();
+  if (!p) return "";
+  if (!p.startsWith("/")) p = "/" + p;
+  return p.replace(/\/+$/, "") || "/";
+}
+
+function routeEntries(spec) {
+  const paths = spec.paths || {};
+  return Object.entries(paths).map(([path, methods]) => {
+    const post = methods.post || {};
+    const price = post["x-payment-info"]?.price?.amount;
+    return {
+      path,
+      category: (post.tags || [])[0] || "uncategorized",
+      price: price ? `$${price}` : undefined,
+      description: post.description || post.summary || "",
+      operationId: post.operationId,
+    };
+  });
+}
+
+function truncate(s, n) {
+  if (!s) return s;
+  return s.length > n ? s.slice(0, n - 1).trimEnd() + "…" : s;
+}
+
+async function listCapabilities(args) {
+  const spec = await fetchOpenApiSpec();
+  const entries = routeEntries(spec);
+  const category = args.category ? String(args.category).toLowerCase() : null;
+
+  if (!category) {
+    const counts = {};
+    for (const e of entries) counts[e.category] = (counts[e.category] || 0) + 1;
+    return {
+      total_routes: entries.length,
+      categories: Object.entries(counts)
+        .sort((a, b) => b[1] - a[1])
+        .map(([name, count]) => ({ category: name, route_count: count })),
+      hint: "Pass a category to list its routes, e.g. { \"category\": \"math\" }. Or use search_capabilities with a keyword.",
+      full_catalog: `${BASE_URL}/openapi.json`,
+    };
+  }
+
+  const matches = entries.filter((e) => e.category.toLowerCase() === category);
+  if (matches.length === 0) {
+    const available = [...new Set(entries.map((e) => e.category))].sort();
+    throw new Error(`No routes found in category "${args.category}". Available categories: ${available.join(", ")}`);
+  }
+  return {
+    category,
+    route_count: matches.length,
+    routes: matches.map((e) => ({ path: e.path, price: e.price, description: truncate(e.description, 200) })),
+  };
+}
+
+async function searchCapabilities(args) {
+  const spec = await fetchOpenApiSpec();
+  const entries = routeEntries(spec);
+  const q = String(args.query || "").toLowerCase().trim();
+  if (!q) throw new Error("query is required");
+  const limit = Math.min(Math.max(Number(args.limit) || 20, 1), 50);
+  const matches = entries
+    .filter(
+      (e) =>
+        e.path.toLowerCase().includes(q) ||
+        (e.operationId || "").toLowerCase().includes(q) ||
+        e.description.toLowerCase().includes(q)
+    )
+    .slice(0, limit);
+  return {
+    query: args.query,
+    match_count: matches.length,
+    routes: matches.map((e) => ({
+      path: e.path,
+      category: e.category,
+      price: e.price,
+      description: truncate(e.description, 200),
+    })),
+  };
+}
+
+async function getEndpointSpec(args) {
+  const spec = await fetchOpenApiSpec();
+  const path = normalizePath(args.path);
+  const post = spec.paths?.[path]?.post;
+  if (!post) {
+    // fall back to a loose search so a slightly-off name still resolves
+    const entries = routeEntries(spec);
+    const norm = path.replace(/^\//, "").toLowerCase();
+    const candidates = entries.filter(
+      (e) => e.path.toLowerCase().includes(norm) || (e.operationId || "").toLowerCase().includes(norm.replace(/-/g, "_"))
+    );
+    if (candidates.length === 1) {
+      return getEndpointSpec({ path: candidates[0].path });
+    }
+    throw new Error(
+      candidates.length > 1
+        ? `"${args.path}" is ambiguous. Candidates: ${candidates.map((c) => c.path).join(", ")}`
+        : `No route matching "${args.path}". Use list_capabilities or search_capabilities to find the exact path.`
+    );
+  }
+  const schema = post.requestBody?.content?.["application/json"]?.schema;
+  const requestExample = post.requestBody?.content?.["application/json"]?.example;
+  const responseExample = post.responses?.["200"]?.content?.["application/json"]?.example;
+  return {
+    path,
+    method: "POST",
+    category: (post.tags || [])[0],
+    price: post["x-payment-info"]?.price?.amount ? `$${post["x-payment-info"].price.amount}` : undefined,
+    description: post.description || post.summary,
+    input_schema: schema,
+    request_example: requestExample,
+    response_example: responseExample,
+  };
+}
+
+// --- payment client ---------------------------------------------------------
+
+function buildBaseHttpClient() {
+  const key = process.env.WALLET_PRIVATE_KEY;
+  if (!key) {
+    throw new Error(
+      "WALLET_PRIVATE_KEY is not set. Paid utility-grid calls cost $0.001-$0.05 via x402 — set a dedicated low-balance Base wallet private key (never your primary wallet) with a small amount of USDC on Base mainnet. Discovery tools (list_capabilities, search_capabilities, get_endpoint_spec) work without one."
+    );
+  }
+  const pk = key.startsWith("0x") ? key : "0x" + key;
+  const account = privateKeyToAccount(pk);
+  const coreClient = new x402Client().register("eip155:*", new ExactEvmScheme(toClientEvmSigner(account)));
+  return { httpClient: new x402HTTPClient(coreClient), account };
+}
+
+// x402 derives EIP-3009 validity windows from Date.now; choose a timestamp
+// valid for both Base block time and facilitator wall-clock checks (clock-skew fix).
+async function createChainTimedPaymentPayload(httpClient, paymentRequired) {
+  try {
+    const publicClient = createPublicClient({ chain: base, transport: http(BASE_RPC_URL) });
+    const block = await publicClient.getBlock();
+    const chainNow = Number(block.timestamp);
+    const originalNow = Date.now;
+    const localNow = Math.floor(originalNow() / 1000);
+    const timeout = Number(paymentRequired.accepts?.[0]?.maxTimeoutSeconds || 300);
+    const lowerBound = localNow + 30 - timeout;
+    const upperBound = chainNow + 600;
+    const signingNow = Math.min(Math.max(chainNow, lowerBound), upperBound);
+    Date.now = () => signingNow * 1000;
+    try {
+      return await httpClient.createPaymentPayload(paymentRequired);
+    } finally {
+      Date.now = originalNow;
+    }
+  } catch (_) {
+    return httpClient.createPaymentPayload(paymentRequired);
+  }
+}
+
+async function paidPost(ctx, path, body) {
+  const { httpClient } = ctx;
+  const url = BASE_URL + path;
+  const init = { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body || {}) };
+  const res = await fetch(url, init);
+
+  if (res.status === 402) {
+    let challengeBody;
+    try {
+      challengeBody = await res.clone().json();
+    } catch (_) {}
+    const paymentRequired = httpClient.getPaymentRequiredResponse((name) => res.headers.get(name), challengeBody);
+    const paymentPayload = await createChainTimedPaymentPayload(httpClient, paymentRequired);
+    const paidRes = await fetch(url, {
+      ...init,
+      headers: { ...init.headers, ...httpClient.encodePaymentSignatureHeader(paymentPayload) },
+    });
+    if (!paidRes.ok) {
+      const errBody = await paidRes.text().catch(() => paidRes.statusText);
+      throw new Error(`HTTP ${paidRes.status}: ${errBody.slice(0, 300)}`);
+    }
+    const data = await paidRes.json();
+    try {
+      const settleResponse = httpClient.getPaymentSettleResponse((name) => paidRes.headers.get(name));
+      if (settleResponse && data && typeof data === "object" && !Array.isArray(data)) {
+        return { ...data, _payment: settleResponse };
+      }
+    } catch (_) {}
+    return data;
+  }
+
+  if (!res.ok) {
+    const errBody = await res.text().catch(() => res.statusText);
+    throw new Error(`HTTP ${res.status}: ${errBody.slice(0, 300)}`);
+  }
+  return res.json();
+}
+
+const TOOLS = [
+  {
+    name: "list_capabilities",
+    description:
+      `FREE — no wallet needed. Browse the ForgeMesh Utility Grid catalog (415+ POST routes and growing, covering ${CATEGORY_EXAMPLES}). Call with no arguments for a category overview with route counts, or pass a category to list every route in it with price and description. Always reads the live /openapi.json — never a stale/hardcoded list.`,
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: { type: "string", description: "Optional category to list routes for, e.g. 'math' or 'vision'" },
+      },
+    },
+  },
+  {
+    name: "search_capabilities",
+    description:
+      "FREE — no wallet needed. Keyword search across every route's path, operation id, and description (e.g. 'chess', 'timezone', 'background removal'). Use this when you don't know the exact route name or category.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Keyword to search for" },
+        limit: { type: "integer", description: "Max results (default 20, max 50)" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "get_endpoint_spec",
+    description:
+      "FREE — no wallet needed. Full call spec for one route: price, input JSON schema, a worked request example, and a worked response example, straight from the live OpenAPI discovery doc. Pass the route path (with or without a leading slash, e.g. 'chess-moves' or '/chess-moves'). Use this before call_endpoint to know exactly what body to send.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Route path, e.g. 'chess-moves' or '/geocode-city'" },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "call_endpoint",
+    description:
+      "PAID (price varies by route, $0.001-$0.05) — the generic way to call ANY route in the Utility Grid. Pass the route path and a JSON body matching its input schema (use get_endpoint_spec first if unsure). Handles the full x402 payment flow automatically: fetches the 402 challenge, signs a USDC payment on Base, retries, and returns the result. Requires WALLET_PRIVATE_KEY.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        path: { type: "string", description: "Route path, e.g. 'chess-moves' or '/geocode-city'" },
+        body: { type: "object", description: "JSON body matching the route's input schema (see get_endpoint_spec)" },
+      },
+      required: ["path"],
+    },
+  },
+  {
+    name: "daily_402",
+    description:
+      "PAID ($0.001) — the Daily 402: one featured x402 endpoint per UTC day, rotated deterministically through every paid route in the 12-service ForgeMesh fleet (500+ routes). Returns what it does, its price, input schema, and a worked example. Optional date override to replay a past day's pick. Requires WALLET_PRIVATE_KEY.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        date: { type: "string", description: "Optional ISO date (YYYY-MM-DD) to replay a past day's featured endpoint" },
+      },
+    },
+  },
+  {
+    name: "agent_service_directory",
+    description:
+      "PAID ($0.05) — machine-readable registry of every production x402 service in the ForgeMesh fleet: name, category, live route count, and price range per service. Useful for an agent deciding which paid tool/service to reach for next. Optional category filter (onchain-intel, voice, travel, econ-intel, commerce, infra, media, utility-grid). Requires WALLET_PRIVATE_KEY.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        category: { type: "string", description: "Optional: onchain-intel, voice, travel, econ-intel, commerce, infra, media, utility-grid" },
+      },
+    },
+  },
+];
+
+async function main() {
+  let ctxPromise;
+  async function getPaymentContext() {
+    if (!ctxPromise) ctxPromise = Promise.resolve().then(buildBaseHttpClient);
+    return ctxPromise;
+  }
+
+  const server = new Server({ name: "utility-grid-mcp", version: VERSION }, { capabilities: { tools: {} } });
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    const { name, arguments: args = {} } = req.params;
+    try {
+      let data;
+      switch (name) {
+        case "list_capabilities":
+          data = await listCapabilities(args);
+          break;
+        case "search_capabilities":
+          data = await searchCapabilities(args);
+          break;
+        case "get_endpoint_spec":
+          data = await getEndpointSpec(args);
+          break;
+        case "call_endpoint":
+          data = await paidPost(await getPaymentContext(), normalizePath(args.path), args.body || {});
+          break;
+        case "daily_402":
+          data = await paidPost(await getPaymentContext(), "/daily", { date: args.date });
+          break;
+        case "agent_service_directory":
+          data = await paidPost(await getPaymentContext(), "/agent-service-directory", { category: args.category });
+          break;
+        default:
+          throw new Error(`Unknown tool: ${name}`);
+      }
+      return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+    } catch (e) {
+      return { content: [{ type: "text", text: `Error: ${e.message}` }], isError: true };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(`utility-grid-mcp v${VERSION} ready — ${BASE_URL}`);
+}
+
+if (require.main === module) {
+  main().catch((e) => {
+    console.error("Fatal:", e.message);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  TOOLS,
+  normalizePath,
+  routeEntries,
+  listCapabilities,
+  searchCapabilities,
+  getEndpointSpec,
+  buildBaseHttpClient,
+  fetchOpenApiSpec,
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@forgemeshlabs/utility-grid-mcp",
+  "version": "0.1.0",
+  "description": "ForgeMesh Utility Grid, by ForgeMesh Labs — 415+ small agent utility jobs (OCR, vision, audio, embeddings, web extraction, dictionary/slang, chess, math, conversions, time, geo/space data, and x402 ecosystem intelligence) behind 6 meta-tools instead of one tool per route. Free discovery (browse/search the live catalog, fetch a route's full call spec), paid generic call via x402 USDC micropayments on Base. No API key, no account.",
+  "main": "index.js",
+  "bin": {
+    "utility-grid-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "server.json",
+    "glama.json",
+    "GLAMA.md",
+    "Dockerfile",
+    ".dockerignore",
+    "smithery.yaml",
+    "LICENSE"
+  ],
+  "mcpName": "io.github.forgemeshlabs/utility-grid-mcp",
+  "scripts": {
+    "start": "node index.js",
+    "build": "echo \"no build step required\"",
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "x402",
+    "utility-grid",
+    "ocr",
+    "vision",
+    "tts",
+    "geo",
+    "math",
+    "usdc",
+    "base",
+    "micropayments",
+    "autonomous-agents",
+    "agent-tools"
+  ],
+  "author": "ForgeMesh Labs (https://forgemesh.io)",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forgemeshlabs/utility-grid-mcp.git"
+  },
+  "homepage": "https://x402.forgemesh.io",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.10.1",
+    "@x402/core": "^2.17.0",
+    "@x402/evm": "^2.17.0",
+    "viem": "^2.0.0"
+  }
+}

package/server.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.forgemeshlabs/utility-grid-mcp",
+  "description": "415+ agent utility jobs (OCR, vision, audio, math, conversions, geo/space, x402 intelligence) behind 6 meta-tools with free discovery and generic paid calling via x402.",
+  "repository": {
+    "url": "https://github.com/forgemeshlabs/utility-grid-mcp",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "@forgemeshlabs/utility-grid-mcp",
+      "version": "0.1.0",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "WALLET_PRIVATE_KEY",
+          "description": "Dedicated low-balance Base wallet private key for x402 USDC micropayments. Only required for the 3 paid tools (call_endpoint, daily_402, agent_service_directory) — the 3 discovery tools work without it. Never use your primary wallet.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        },
+        {
+          "name": "UTILITY_GRID_BASE_URL",
+          "description": "Utility Grid API origin override. Defaults to https://x402.forgemesh.io.",
+          "isRequired": false,
+          "isSecret": false,
+          "format": "string"
+        }
+      ]
+    }
+  ],
+  "title": "ForgeMesh Utility Grid MCP",
+  "websiteUrl": "https://x402.forgemesh.io",
+  "icons": [
+    {
+      "src": "https://x402.forgemesh.io/favicon.ico",
+      "mimeType": "image/png"
+    }
+  ]
+}

package/smithery.yaml

@@ -0,0 +1,30 @@
+startCommand:
+  type: stdio
+  configSchema:
+    type: object
+    properties:
+      utilityGridBaseUrl:
+        type: string
+        description: >-
+          Utility Grid API origin override. Defaults to
+          https://x402.forgemesh.io.
+      walletPrivateKey:
+        type: string
+        description: >-
+          Dedicated low-balance Base wallet private key for x402 USDC
+          micropayments. Optional — the 3 discovery tools (list_capabilities,
+          search_capabilities, get_endpoint_spec) work without any wallet.
+          Only the 3 paid tools (call_endpoint, daily_402,
+          agent_service_directory) need it. Never use your primary wallet.
+  commandFunction: |-
+    (config) => ({
+      command: 'npx',
+      args: ['-y', '@forgemeshlabs/utility-grid-mcp'],
+      env: {
+        ...(config.utilityGridBaseUrl ? { UTILITY_GRID_BASE_URL: config.utilityGridBaseUrl } : {}),
+        ...(config.walletPrivateKey ? { WALLET_PRIVATE_KEY: config.walletPrivateKey } : {})
+      }
+    })
+  exampleConfig:
+    utilityGridBaseUrl: 'https://x402.forgemesh.io'
+    walletPrivateKey: '0x...'