agent402-mcp 0.13.11 → 0.13.13

package/README.md

@@ -2,7 +2,7 @@
 
 MCP server for [Agent402](https://agent402.tools), the applied layer of [Agentic Finance](https://agent402.tools/agentic-finance) - a catalog of **500+ pay-per-call web tools and curated multi-tool skill packs** for AI agents, paid per call in USDC via the [x402 protocol](https://www.x402.org), **with compute (proof-of-work)** when no wallet is configured, or through a prepaid credits key already issued. (The hosted API is dual-stack: it also accepts [MPP](https://agent402.tools/what-is-mpp) clients on the same 402, settling on Base/Celo or natively on Tempo; this package pays via x402 or credits.) Built by [Havok Holdings LLC](https://github.com/MikeyPetrillo/Agent402).
 
-Your agent gets browser rendering, screenshots, PDF text extraction, URL→markdown, live web search **+ web answers with citations**, live **financial/crypto/macro data** (US equity quotes and daily bars from Databento, CoinGecko, FRED, ECB FX, World Bank, yield curve), **SEC EDGAR filings** (10-K/10-Q text, XBRL, insider, 13F, IPO calendar), **deterministic stats & forecasting** (Pearson correlation, OLS, Holt-Winters), **compression** (gzip/brotli), DNS/TLS/WHOIS + email-deliverability checks, wallet-keyed shared memory, and the pure-CPU utilities - plus **skill packs** like `security-audit`, `trend-analysis`, `structured-scrape`, `decode-blob`, and `forecasting-bake-off` callable as MCP prompts, and the **report products** (deep research, company dossier, 13F fund report, domain audit, token risk, FDA recall, insider flow, market brief) as ordinary catalog slugs. Payment handled invisibly underneath the MCP calls. No signup, no API key.
+Your agent gets browser rendering, screenshots, PDF text extraction, URL→markdown, live web search **+ web answers with citations**, live **financial/crypto/macro data** (US equity quotes and daily bars from a licensed feed, CoinGecko, FRED, ECB FX, World Bank, yield curve), **SEC EDGAR filings** (10-K/10-Q text, XBRL, insider, 13F, IPO calendar), **deterministic stats & forecasting** (Pearson correlation, OLS, Holt-Winters), **compression** (gzip/brotli), DNS/TLS/WHOIS + email-deliverability checks, wallet-keyed shared memory, and the pure-CPU utilities - plus **skill packs** like `security-audit`, `trend-analysis`, `structured-scrape`, `decode-blob`, and `forecasting-bake-off` callable as MCP prompts, and the **report products** (deep research, company dossier, 13F fund report, domain audit, token risk, FDA recall, insider flow, market brief) as ordinary catalog slugs. Payment handled invisibly underneath the MCP calls. No signup, no API key.
 
 ## Quick start
 

package/discovery.js

@@ -0,0 +1,62 @@
+// Discovery reads (the catalog, /api/find, skill packs, leaderboards, a
+// proof-of-work challenge) settle nothing, so a 503 the server sheds under
+// load is safe to repeat. It is retried only when it names its own delay
+// (a Retry-After header or a retryAfterSeconds body field), at most
+// DISCOVERY_ATTEMPTS tries in all, each wait capped at DISCOVERY_MAX_WAIT_MS.
+// A paid or priced call never goes through here: a repeat of one could settle
+// twice.
+export const DISCOVERY_ATTEMPTS = 3;
+export const DISCOVERY_MAX_WAIT_MS = 5000;
+
+const sleepMs = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** The wait (ms) a shed 503 asks for, or null when `r` is not one. */
+export async function shedRetryWaitMs(r, maxWaitMs = DISCOVERY_MAX_WAIT_MS) {
+  if (!r || r.status !== 503) return null;
+  const header = r.headers && typeof r.headers.get === "function" ? r.headers.get("retry-after") : null;
+  let seconds = header != null && String(header).trim() !== "" ? Number(header) : NaN;
+  if (!Number.isFinite(seconds)) {
+    try {
+      const body = await (typeof r.clone === "function" ? r.clone() : r).json();
+      seconds = Number(body && body.retryAfterSeconds);
+    } catch { seconds = NaN; }
+  }
+  if (!Number.isFinite(seconds) || seconds < 0) return null;
+  return Math.min(seconds * 1000, maxWaitMs);
+}
+
+/**
+ * Fetch a discovery surface, retrying a shed 503. Resolves with the last
+ * response (2xx or not) and how many attempts it took; the caller decides how
+ * to report a failure, naming the surface and `res.status`.
+ */
+export async function fetchDiscovery(url, init, { fetchImpl = globalThis.fetch, sleep = sleepMs, attempts: max = DISCOVERY_ATTEMPTS } = {}) {
+  let res;
+  let attempts = 0;
+  for (;;) {
+    attempts++;
+    res = await fetchImpl(url, init);
+    if (res.ok || attempts >= max) return { res, attempts };
+    const wait = await shedRetryWaitMs(res);
+    if (wait == null) return { res, attempts };
+    await sleep(wait);
+  }
+}
+
+/** "HTTP 503 from /api/find after 3 attempts": the tail of a discovery failure. */
+export function discoveryFailure(url, res, attempts) {
+  const path = (() => { try { return new URL(String(url)).pathname; } catch { return String(url).split("?")[0]; } })();
+  return `HTTP ${res.status} from ${path}${attempts > 1 ? ` after ${attempts} attempts` : ""}`;
+}
+
+/** GET JSON from a discovery surface; throws `${label} failed: HTTP <status> from <path>[ after N attempts]`. */
+export async function getDiscoveryJson(label, url, init, opts) {
+  const { res, attempts } = await fetchDiscovery(url, init, opts);
+  if (!res.ok) {
+    const err = new Error(`${label} failed: ${discoveryFailure(url, res, attempts)}`);
+    err.status = res.status;
+    err.attempts = attempts;
+    throw err;
+  }
+  return res.json();
+}

package/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// Agent402 MCP server — exposes the agent402.tools catalog (1000+ pay-per-call
+// Agent402 MCP server, exposes the agent402.tools catalog (1000+ pay-per-call
 // web tools) to any MCP client (Claude, ChatGPT, custom agents) and settles
 // payment underneath, so the model never sees the 402 dance:
 //
@@ -13,18 +13,19 @@
 //
 // Config (env):
 //   AGENT402_URL          target service (default https://agent402.tools)
-//   AGENT_KEY             hex private key of a funded EVM wallet (USDC on Base/Polygon/Arbitrum) — optional
-//   SOLANA_AGENT_KEY      base58 (or JSON byte-array) secret key of a funded Solana wallet (USDC on Solana) — optional
+//   AGENT_KEY             hex private key of a funded EVM wallet (USDC on Base/Polygon/Arbitrum), optional
+//   SOLANA_AGENT_KEY      base58 (or JSON byte-array) secret key of a funded Solana wallet (USDC on Solana), optional
 //   AGENT402_TOOLS        comma-separated slugs to expose first-class (overrides default)
 //   AGENT402_MAX_PER_CALL refuse any single call priced above this many USD (e.g. 0.01)
 //   AGENT402_CREDITS_KEY  a prepaid credits key (a402_...) already issued (new credits are not on
 //                         sale); pays per successful call with no wallet
 //   AGENT402_BUDGET       hard cap on total USDC spent this session (e.g. 1.00)
 //   AGENT402_NETWORKS     restrict + order the chains to pay on (e.g. "robinhood" for USDG on
-//                         Robinhood Chain, "base,solana", or a raw CAIP-2 like eip155:4663) — optional
+//                         Robinhood Chain, "base,solana", or a raw CAIP-2 like eip155:4663), optional
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { parseNetworkPrefs, withNetworkPreference } from "./networks.js";
+import { fetchDiscovery, discoveryFailure, getDiscoveryJson } from "./discovery.js";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
@@ -32,6 +33,8 @@ import {
   ListToolsRequestSchema,
   ListPromptsRequestSchema,
   GetPromptRequestSchema,
+  McpError,
+  ErrorCode,
 } from "@modelcontextprotocol/sdk/types.js";
 import {
   FLAGSHIP_MCP_NAMES,
@@ -44,6 +47,7 @@ import {
   mcpJsonResult,
   outputSchemaFromExample,
   mcpInitializeInstructions,
+  toolInputBoundRefusal,
 } from "./output-schemas.js";
 
 const BASE = (process.env.AGENT402_URL || "https://agent402.tools").replace(/\/$/, "");
@@ -58,12 +62,12 @@ const HAS_WALLET = Boolean(AGENT_KEY || SOLANA_AGENT_KEY);
 // list price only on a successful (200) call and returns X-Credits-Balance.
 const CREDITS_KEY = (process.env.AGENT402_CREDITS_KEY || "").trim();
 const HAS_CREDITS = /^a402_[A-Za-z0-9_-]{32,64}$/.test(CREDITS_KEY);
-// Version comes from package.json — the serverInfo self-report drifted from
+// Version comes from package.json, the serverInfo self-report drifted from
 // the published version once (0.11.5 vs 0.12.1) because this was a hardcoded
 // string bumped by hand. Reading the manifest makes drift impossible.
 const VERSION = JSON.parse(readFileSync(new URL("./package.json", import.meta.url), "utf8")).version;
 
-// Spend controls — enforced BEFORE a payment is ever signed, so a confused or
+// Spend controls, enforced BEFORE a payment is ever signed, so a confused or
 // runaway model cannot drain the wallet. Unset = unlimited (back-compat).
 const num = (v) => (v !== undefined && v !== "" && Number.isFinite(Number(v)) ? Number(v) : undefined);
 const MAX_PER_CALL = num(process.env.AGENT402_MAX_PER_CALL) ?? Infinity;
@@ -71,7 +75,7 @@ const BUDGET = num(process.env.AGENT402_BUDGET) ?? Infinity;
 let spentUsd = 0;
 
 const DEFAULT_CURATED = [
-  // Flagship demand set — keep aligned with src/mcp-flagship.js FLAGSHIP_SLUGS.
+  // Flagship demand set, keep aligned with src/mcp-flagship.js FLAGSHIP_SLUGS.
   // Search/answer is the front door; long tail stays behind catalog.search/catalog.call.
   "search", "answer", "search-news", "render",
   "stock-quote", "transcribe", "memory-read", "memory-write",
@@ -79,24 +83,28 @@ const DEFAULT_CURATED = [
   "decide", "decide-execute",
 ];
 
-// stdout is the MCP protocol channel — all logging goes to stderr.
+// stdout is the MCP protocol channel, all logging goes to stderr.
 const log = (...a) => console.error("[agent402-mcp]", ...a);
 
 // ---------------------------------------------------------------------------
 // Catalog: built from the service's own machine-readable surfaces.
 const catalog = new Map(); // slug -> { slug, method, path, price, description, category, computePayable, inputSchema }
-// Skill packs — curated multi-tool workflows, fetched at startup from the
+// Skill packs, curated multi-tool workflows, fetched at startup from the
 // hosted service so the npm package picks up new packs without a republish.
 // Empty if the discovery fetch fails (older services or transient errors);
 // prompts/list will just return an empty array in that case.
 let skillPacks = [];
 
+// Each surface retries a shed 503 (./discovery.js). A failed pricing or
+// openapi read throws, so the catalog is never built from an error body; the
+// skill packs are optional and read as empty.
 async function loadCatalog() {
   const [pricing, openapi, packs] = await Promise.all([
-    fetch(`${BASE}/api/pricing`).then((r) => r.json()),
-    fetch(`${BASE}/openapi.json`).then((r) => r.json()),
-    fetch(`${BASE}/api/skill-packs.json`).then((r) => (r.ok ? r.json() : { packs: [] })).catch(() => ({ packs: [] })),
+    getDiscoveryJson("catalog load", `${BASE}/api/pricing`),
+    getDiscoveryJson("catalog load", `${BASE}/openapi.json`),
+    getDiscoveryJson("skill packs", `${BASE}/api/skill-packs.json`).catch(() => ({ packs: [] })),
   ]);
+  if (!Array.isArray(pricing?.endpoints)) throw new Error(`catalog load failed: ${BASE}/api/pricing carried no endpoints list`);
   skillPacks = Array.isArray(packs?.packs) ? packs.packs : [];
   for (const e of pricing.endpoints) {
     const slug = e.slug ?? e.docs?.split("/tools/").pop();
@@ -162,7 +170,7 @@ function getPayFetch() {
   return payFetchPromise;
 }
 
-// @solana/kit KeyPairSigner from SOLANA_AGENT_KEY — base58 64-byte secret key
+// @solana/kit KeyPairSigner from SOLANA_AGENT_KEY, base58 64-byte secret key
 // (Phantom / solana-keygen export) or a JSON byte array ([12,34,…]).
 let solanaSignerPromise;
 function solanaSigner() {
@@ -197,7 +205,7 @@ function walletRequiredText(tool) {
     `"${tool.slug}" costs ${tool.price}/call and requires a USDC wallet (it is not eligible for the proof-of-work tier).`,
     `To enable it: set AGENT_KEY on this MCP server to the hex private key of an EVM wallet funded with USDC`,
     `on Base (or Polygon/Arbitrum), and/or SOLANA_AGENT_KEY to the base58 secret key of a Solana wallet funded`,
-    `with USDC on Solana. Payment is per call via the x402 protocol — no signup or API key.`,
+    `with USDC on Solana. Payment is per call via the x402 protocol: no signup or API key.`,
     `Already hold a prepaid credits key? Set AGENT402_CREDITS_KEY to the a402_ key and it pays per successful call (new credits are not on sale).`,
     `Pricing and details: ${BASE}/tools/${tool.slug}`,
   ].join(" ");
@@ -340,12 +348,12 @@ async function callEndpoint(tool, args = {}) {
     const payFetch = await getPayFetch();
     res = await payFetch(url, init);
     // Count spend when the server confirms settlement (payment receipt header),
-    // falling back to any 2xx — conservative in the buyer's favor.
+    // falling back to any 2xx, conservative in the buyer's favor.
     if (res.headers.get("payment-response") || res.headers.get("x-payment-response") || res.ok) spentUsd += price;
   } else if (tool.computePayable) {
-    // No wallet: pay with compute up front — solving before the call skips the
+    // No wallet: pay with compute up front, solving before the call skips the
     // 402 round-trip entirely (challenges are single-use and tool-scoped).
-    const challenge = await (await fetch(`${BASE}/api/pow/challenge?slug=${encodeURIComponent(tool.slug)}`)).json();
+    const challenge = await getDiscoveryJson(`proof-of-work challenge for "${tool.slug}"`, `${BASE}/api/pow/challenge?slug=${encodeURIComponent(tool.slug)}`);
     const nonce = solvePow(challenge);
     res = await fetch(url, { ...init, headers: { ...init.headers, "X-Pow-Solution": `${challenge.token}:${nonce}` } });
   } else {
@@ -382,7 +390,7 @@ function applyFrontDoorTerms(terms, q) {
   if (!terms.includes("websearch") && (
     /\b(search\s+the\s+web|web\s+search|search\s+online|google\s+|bing\s+|look\s+up\s+online|find\s+on\s+the\s+web)\b/.test(ql)
   )) {
-    // pricing descriptions carry "web search" / "Live web search" — boost those.
+    // pricing descriptions carry "web search" / "Live web search", boost those.
     terms.push("web", "search");
   }
   if (!terms.includes("answer") && (
@@ -427,8 +435,8 @@ function searchTools(query, limit = 10) {
 
 // Rank the curated multi-tool skill packs against the same query, so a single
 // search_tools call also tells the agent "this looks like a `security-audit`
-// or `email-deliverability` job — fetch the whole template via prompts/get".
-// Weighted slug/title/tagline/useCase/toolSlugs match — same shape as the
+// or `email-deliverability` job, fetch the whole template via prompts/get".
+// Weighted slug/title/tagline/useCase/toolSlugs match, same shape as the
 // hosted /api/find ranking, kept inline here so the stdio package stays
 // dependency-free. Returns [] when no pack scores above the noise floor.
 function rankWorkflows(query, k = 2) {
@@ -482,7 +490,7 @@ const server = new Server(
   { capabilities: { tools: {}, prompts: {} }, instructions: INIT_INSTRUCTIONS },
 );
 
-// Skill packs are exposed as MCP prompts — discoverable in slash menus on any
+// Skill packs are exposed as MCP prompts, discoverable in slash menus on any
 // MCP-aware client. The list is fetched once at boot in loadCatalog(); the
 // per-prompt rendering is delegated to the hosted service so the npm package
 // stays thin and prompt text stays canonical with the website at /skills.
@@ -506,15 +514,34 @@ server.setRequestHandler(GetPromptRequestSchema, async (req) => {
   for (const [k, v] of Object.entries(args || {})) {
     if (v !== undefined && v !== null && v !== "") url.searchParams.set(k, String(v));
   }
-  const res = await fetch(url);
-  if (!res.ok) throw new Error(`Failed to render prompt "${name}" from ${BASE}: HTTP ${res.status}`);
+  const { res, attempts } = await fetchDiscovery(url);
+  if (!res.ok) throw new Error(`Failed to render prompt "${name}" from ${BASE}: ${discoveryFailure(url, res, attempts)}`);
   return await res.json();
 });
 
 let curated = [];
 let pricingInfo = null;
 
-server.setRequestHandler(ListToolsRequestSchema, async () => {
+// A catalog that could not load at boot (a shed or unreachable service) is
+// read again on the next tools/list or tools/call, at most once per
+// CATALOG_RETRY_MS, so a session that started during a busy minute recovers
+// without a restart.
+const CATALOG_RETRY_MS = 30_000;
+let catalogRetryAt = 0;
+async function ensureCatalog() {
+  if (catalog.size > 0 || Date.now() < catalogRetryAt) return;
+  catalogRetryAt = Date.now() + CATALOG_RETRY_MS;
+  try {
+    pricingInfo = await loadCatalog();
+    curated = requested.map((slug) => catalog.get(slug)).filter(Boolean);
+    log(`catalog: ${catalog.size} tools from ${BASE} on a later read; ${curated.length} first-class`);
+  } catch (err) {
+    log(`Could not load the catalog from ${BASE}: ${err.message}: next read in ${CATALOG_RETRY_MS / 1000}s`);
+  }
+}
+const withCatalog = (handler) => async (req) => { await ensureCatalog(); return handler(req); };
+
+server.setRequestHandler(ListToolsRequestSchema, withCatalog(async () => {
   const SAFE = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
   const OPEN = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
   const WRITE = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false };
@@ -633,7 +660,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
         properties: {
           task: { type: "string", description: "Plain-language task, e.g. 'crypto news headlines' or 'sentiment of a tweet'. Resolved to a proven external seller." },
           params: { type: "object", description: "Input parameters for the resolved external tool (optional; the seller decides its own schema)." },
-          maxUsd: { type: "number", description: "Max underlying seller price in USD. Default 0.005 (the $0.01 fee tier); a value above 0.005 uses the $0.55 tier (seller up to $0.50)." },
+          maxUsd: { type: "number", description: "Max underlying seller price in USD. Default 0.005 (the $0.01 fee tier); above 0.005 and up to 0.04 uses the $0.05 tier; above 0.04 the $0.55 tier (seller up to $0.50)." },
         },
         required: ["task"],
       },
@@ -641,20 +668,26 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
     }
   );
   return { tools };
-});
+}));
 
-server.setRequestHandler(CallToolRequestSchema, async (req) => {
+server.setRequestHandler(CallToolRequestSchema, withCatalog(async (req) => {
   const { name: rawName, arguments: args = {} } = req.params;
   const name = resolveListedName(rawName);
+  const overBound = toolInputBoundRefusal(rawName, args);
+  if (overBound) throw new McpError(ErrorCode.InvalidParams, overBound);
   try {
     if (name === "catalog.search") {
-      const q = args.query ?? "";
+      const q = String(args.query ?? "").trim();
       const results = searchTools(q, args.limit ?? 10);
       const workflows = rankWorkflows(q, 2);
       if (!results.length && !workflows.length) {
+        // A caller that passed no query is told which argument to pass, not
+        // shown an empty string in quotes.
         return mcpJsonResult({
           results: [],
-          message: `No tools matched "${q}". Browse the catalog at ${BASE}/tools or ${BASE}/api/pricing.`,
+          message: q
+            ? `No tools matched "${q}". Browse the catalog at ${BASE}/tools or ${BASE}/api/pricing.`
+            : `catalog.search needs a "query" argument: what the tool should do (for example "convert miles to kilometers"). Browse the catalog at ${BASE}/tools or ${BASE}/api/pricing.`,
         });
       }
       return mcpJsonResult({
@@ -672,9 +705,9 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       const url = new URL(`${BASE}/api/find`);
       url.searchParams.set("q", task);
       url.searchParams.set("k", String(limit));
-      const res = await fetch(url);
+      const { res, attempts } = await fetchDiscovery(url);
       if (!res.ok) {
-        return { content: [{ type: "text", text: `catalog.find failed against ${BASE}/api/find: HTTP ${res.status}` }], isError: true };
+        return { content: [{ type: "text", text: `catalog.find failed against ${BASE}/api/find: ${discoveryFailure(url, res, attempts)}` }], isError: true };
       }
       const body = await res.json();
       const matches = (body.results || []).map((t) => ({
@@ -770,9 +803,9 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       const limit = Math.min(Math.max(parseInt(args.limit, 10) || 10, 1), 50);
       const sort = args.sort === "usd" ? "usd" : "calls";
       const include = args.include === "all" ? "all" : "external";
-      const res = await fetch(`${BASE}/api/mpp-leaderboard`);
+      const { res, attempts } = await fetchDiscovery(`${BASE}/api/mpp-leaderboard`);
       if (!res.ok) {
-        return { content: [{ type: "text", text: `Failed to fetch the MPP leaderboard from ${BASE}: HTTP ${res.status}` }], isError: true };
+        return { content: [{ type: "text", text: `Failed to fetch the MPP leaderboard from ${BASE}: ${discoveryFailure(`${BASE}/api/mpp-leaderboard`, res, attempts)}` }], isError: true };
       }
       const lb = await res.json();
       let board = (Array.isArray(lb.rows) ? lb.rows : []).filter((r) => r.transfers > 0 || (r.d30?.transfers || 0) > 0);
@@ -816,17 +849,17 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
       const include = args.include === "all" ? "all" : "external";
       // /api/leaderboard is free + unpaywalled, so this stays free regardless
       // of payment mode. Honor its query params verbatim so the surface is a
-      // thin pass-through — single source of truth for ranking + filtering.
+      // thin pass-through, single source of truth for ranking + filtering.
       const url = new URL(`${BASE}/api/leaderboard`);
       url.searchParams.set("top", String(limit));
       url.searchParams.set("sort", sort);
       url.searchParams.set("include", include);
-      const res = await fetch(url);
+      const { res, attempts } = await fetchDiscovery(url);
       if (!res.ok) {
-        return { content: [{ type: "text", text: `Failed to fetch leaderboard from ${BASE}: HTTP ${res.status}` }], isError: true };
+        return { content: [{ type: "text", text: `Failed to fetch leaderboard from ${BASE}: ${discoveryFailure(url, res, attempts)}` }], isError: true };
       }
       const snap = await res.json();
-      // Trim to the same compact row shape the hosted MCP connector returns —
+      // Trim to the same compact row shape the hosted MCP connector returns,
       // cross-surface agents see one mental model. Full row (origins,
       // endpoints, scan metadata) stays accessible at /api/leaderboard.
       // Same untrusted-content marking as the hosted connector: a seller's
@@ -851,7 +884,7 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         include: snap.include || include,
         totalSellers: snap.totalSellers ?? (snap.leaderboard || []).length,
         results: rows,
-        ...(snap.warming || snap.scanSkipped ? { note: "Cache is warming — results may be partial. Retry in ~60s." } : {}),
+        ...(snap.warming || snap.scanSkipped ? { note: "Cache is warming: results may be partial. Retry in ~60s." } : {}),
         source: `${BASE}/api/leaderboard`,
       });
     }
@@ -867,13 +900,13 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
         : maxUsd > 0.005 ? "route-execute-plus"
         : "route-execute";
       const tool = catalog.get(slug);
-      if (!tool) return { content: [{ type: "text", text: `External routing (${slug}) is not in the catalog from ${BASE} yet — it may be rolling out. Retry shortly.` }], isError: true };
+      if (!tool) return { content: [{ type: "text", text: `External routing (${slug}) is not in the catalog from ${BASE} yet. It may be rolling out; retry shortly.` }], isError: true };
       // Body matches the route-execute input schema; include:"external" is what
       // pays an OUTSIDE seller (vs this host's catalog). Paid via callEndpoint.
       return await callEndpoint(tool, { task, include: "external", maxUsd, ...(args.params && typeof args.params === "object" ? { params: args.params } : {}) });
     }
     // Curated tools are exposed verb_noun for tools/list consistency, but the
-    // real slug is kebab — accept exposed name, plain snake, or raw slug.
+    // real slug is kebab, accept exposed name, plain snake, or raw slug.
     const mcpToSlug = new Map(Object.entries(FLAGSHIP_MCP_NAMES).map(([slug, mcp]) => [mcp, slug]));
     const wanted = name === "catalog.call"
       ? String(args.slug ?? "")
@@ -896,18 +929,19 @@ server.setRequestHandler(CallToolRequestSchema, async (req) => {
   } catch (err) {
     return { content: [{ type: "text", text: `Agent402 call failed: ${err.message}` }], isError: true };
   }
-});
+}));
 
 // ---------------------------------------------------------------------------
 try {
   pricingInfo = await loadCatalog();
 } catch (err) {
   // Don't hard-exit: starting with an empty catalog still lets the server
-  // connect and answer introspection (tools/list) — required to pass directory
+  // connect and answer introspection (tools/list), required to pass directory
   // health checks (e.g. Glama) and more resilient if the catalog endpoint is
-  // briefly unreachable. catalog.search/catalog.call just return nothing until the
-  // catalog is reachable again.
-  log(`Could not load the catalog from ${BASE}: ${err.message} — starting with an empty catalog`);
+  // briefly unreachable. The next tools/list or tools/call reads it again
+  // (ensureCatalog).
+  log(`Could not load the catalog from ${BASE}: ${err.message}: starting with an empty catalog`);
+  catalogRetryAt = Date.now() + CATALOG_RETRY_MS;
 }
 const requested = (process.env.AGENT402_TOOLS || DEFAULT_CURATED.join(","))
   .split(",").map((s) => s.trim()).filter(Boolean);

package/networks.js

@@ -1,9 +1,9 @@
-// Network preference for the x402 buyer — pure helpers, no side effects.
+// Network preference for the x402 buyer, pure helpers, no side effects.
 //
 // AGENT402_NETWORKS (comma-separated, e.g. "robinhood" or "base,solana" or a
 // raw CAIP-2 like "eip155:4663") restricts AND orders which payment options
 // the buyer will consider from a seller's 402 `accepts`. Without it the
-// underlying @x402 client picks whichever registered scheme matches first —
+// underlying @x402 client picks whichever registered scheme matches first,
 // which on a multi-chain seller is effectively always Base, making rails like
 // USDG on Robinhood Chain unreachable no matter what the wallet holds.
 
@@ -30,7 +30,7 @@ export function parseNetworkPrefs(raw) {
 
 /** Filter a 402's accepts to the preferred networks, ordered by preference
  *  (all accepts for the 1st preferred chain, then the 2nd, …). Throws with an
- *  actionable message when nothing matches — better than silently paying on a
+ *  actionable message when nothing matches, better than silently paying on a
  *  chain the operator excluded. No prefs → accepts unchanged. */
 export function filterAcceptsByNetworks(accepts, prefs) {
   if (!prefs?.length) return accepts;
@@ -39,14 +39,14 @@ export function filterAcceptsByNetworks(accepts, prefs) {
   if (!picked.length) {
     const offered = [...new Set(list.map((a) => a?.network).filter(Boolean))];
     throw new Error(
-      `AGENT402_NETWORKS matched none of the seller's payment options — wanted [${prefs.join(", ")}], offered [${offered.join(", ")}]. ` +
+      `AGENT402_NETWORKS matched none of the seller's payment options: wanted [${prefs.join(", ")}], offered [${offered.join(", ")}]. ` +
         "Remove the restriction or add one of the offered networks."
     );
   }
   return picked;
 }
 
-/** Apply the preference to an @x402 client (duck-typed — any version with
+/** Apply the preference to an @x402 client (duck-typed, any version with
  *  createPaymentPayload works): the client only ever sees the filtered,
  *  preference-ordered accepts. Returns the same client for chaining. */
 export function withNetworkPreference(client, prefs) {

package/output-schemas.js

@@ -2,7 +2,7 @@
 // (stdio package cannot import src/ when published). Keep in sync manually
 // when flagship names or output schemas change.
 
-// Flagship MCP surface — the small default tools/list agents see first.
+// Flagship MCP surface, the small default tools/list agents see first.
 //
 // Product intent: Agent402 is a tools and models layer for agents -
 // deterministic utilities, a metered model gateway, finished reports. Default
@@ -26,7 +26,7 @@ export const FLAGSHIP_SLUGS = [
   "memory-write",
 ];
 
-// Smithery Naming grades DOT notation (domain.action tree), not snake_case —
+// Smithery Naming grades DOT notation (domain.action tree), not snake_case,
 // stuck-at-98 lesson: "Tool names should form a navigable tree using
 // dot-notation (e.g. admin.tools.list)". CallTool still accepts prior snake /
 // digit names via MCP_CALL_ALIASES.
@@ -43,7 +43,7 @@ export const FLAGSHIP_MCP_NAMES = {
   "decide-execute": "decide.execute",
 };
 
-/** Meta tools listed alongside flagships — dotted canonical names. */
+/** Meta tools listed alongside flagships, dotted canonical names. */
 export const META_MCP_NAMES = {
   search_tools: "catalog.search",
   find_tool: "catalog.find",
@@ -85,14 +85,31 @@ export const MCP_CALL_ALIASES = {
   route_and_execute: "router.execute",
 };
 
-/** Resolve any CallTool name to the canonical listed dotted name. */
+/** Every listed dotted name (flagships, meta tools, the router). */
+const LISTED_DOTTED = new Set([
+  ...Object.values(FLAGSHIP_MCP_NAMES),
+  ...Object.values(META_MCP_NAMES),
+  ...Object.values(MCP_CALL_ALIASES),
+]);
+
+/**
+ * Resolve any CallTool name to the canonical listed dotted name: a prior
+ * public alias (MCP_CALL_ALIASES), or the snake form of a listed dotted name
+ * (catalog_search, catalog_find, payment_info, web_search), which a client
+ * that cannot send a dot in a tool name produces. Anything else is returned as
+ * given, so a raw catalog slug still reaches the slug lookup.
+ */
 export function resolveListedName(name) {
   if (!name) return name;
   if (MCP_CALL_ALIASES[name]) return MCP_CALL_ALIASES[name];
+  if (typeof name === "string" && name.includes("_") && !name.includes(".")) {
+    const dotted = name.replace(/_/g, ".");
+    if (LISTED_DOTTED.has(dotted)) return dotted;
+  }
   return name;
 }
 
-/** Open-world / egress tools — honest annotations for directory clients. */
+/** Open-world / egress tools, honest annotations for directory clients. */
 export const FLAGSHIP_OPEN_WORLD = new Set([
   "search", "answer", "search-news", "render", "stock-quote", "transcribe", "decide",
 ]);
@@ -108,7 +125,7 @@ export const MCP_SERVER_DESCRIPTION =
 export const MCP_SERVER_WEBSITE = "https://agent402.tools";
 
 // ---------------------------------------------------------------------------
-// outputSchema (JSON Schema) for every listed tool — Smithery Capability
+// outputSchema (JSON Schema) for every listed tool, Smithery Capability
 // Quality grades presence of named-field schemas; bare {type:"object"} does
 // not count. Keep in sync with CallTool structuredContent shapes in mcp-http.js
 // and the duplicated copy in mcp/output-schemas.js (stdio package).
@@ -225,7 +242,7 @@ export const META_OUTPUT_SCHEMAS = {
     },
     additionalProperties: true,
   },
-  // Smithery Naming wants pure [a-z_]+ verb_noun — no digits / brand tokens
+  // Smithery Naming wants pure [a-z_]+ verb_noun, no digits / brand tokens
   // (describe_agent402 / list_x402_sellers failed the scan). Old names stay
   // CallTool aliases.
   "server.describe": {
@@ -496,17 +513,17 @@ export function mcpInstallHints(baseUrl) {
       },
     },
     npm: "npx -y agent402-mcp",
-    smithery: "Paste the hosted URL at https://smithery.ai/new (or: smithery mcp publish \"https://agent402.tools/mcp\" -n @MikeyPetrillo/agent402). Submission is external; Agent402 does not auto-publish.",
+    smithery: `Paste ${hosted} into the add-server form at https://smithery.ai/new. Submission is external; Agent402 does not auto-publish.`,
     maintainer: "Havok Holdings LLC",
   };
 }
 
 /**
- * MCP initialize.instructions — orientation for clients that never call
+ * MCP initialize.instructions, orientation for clients that never call
  * server.describe. Keep tool names listed-only (dotted Smithery form) (self-consistency) and lead
  * with search/answer as the front door.
  */
-export function mcpInitializeInstructions(baseUrl, { decide = false } = {}) {
+export function mcpInitializeInstructions(baseUrl, { decide = false, mpp = false } = {}) {
   const install = mcpInstallHints(baseUrl);
   const hosted = install.hostedUrl;
   return [
@@ -520,9 +537,58 @@ export function mcpInitializeInstructions(baseUrl, { decide = false } = {}) {
     "Orientation: call server.describe. Payment rails / wallet setup: call payment.info.",
     "Missing a tool: call demand.request. Ecosystem sellers: call sellers.list.",
     `Install (npm + wallet, pays for web.search, web.answer and the rest): ${install.claudeCodeNpm}`,
-    `No wallet yet (hosted, proof-of-work tools only): ${install.claudeCodeHosted}`,
+    // The hosted line says what that connector takes: with MPP on it, a wallet
+    // can pay the other tools there too.
+    `${mpp ? "Hosted (proof-of-work tools free; the rest payable there over MPP from a wallet)" : "No wallet yet (hosted, proof-of-work tools only)"}: ${install.claudeCodeHosted}`,
     `Cursor mcp.json: { "mcpServers": { "agent402": { "url": "${hosted}" } } }`,
-    `Why pay here (usage priced under a quoted ceiling, a failed call is not charged and the receipt proves it, keyed retries never pay twice, one key for tools + models + reports, no wallet needed for the proof-of-work tools or a report by card, proof at /status and /revenue): ${baseUrl}/why`,
+    `Why pay here (usage priced under a quoted ceiling, a failed call is not charged and the receipt proves it, keyed retries never pay twice, one key for tools + models + reports, no wallet needed for the proof-of-work tools or a report by card, proof at /status and /revenue): ${baseUrl}/#why`,
     `Docs: ${baseUrl}/llms.txt · ${baseUrl}/api/find?q=… · status ${baseUrl}/status`,
   ].join("\n");
 }
+
+// Tool input element bound. The SDK's maxToolInputElements option lives on
+// McpServer and is checked inside McpServer's own tools/call handler; both
+// connectors use the low-level Server with their own CallTool handler, where
+// that option is never read. So the same check runs here, with the SDK's
+// counting rule (every array element and every own object member, at any
+// depth) and its InvalidParams message.
+//
+// The bound: a JSON element costs at least two bytes ("0,"), so the hosted
+// connector's 100kb body parser admits at most 51,200 of them. A bound at that
+// figure never refuses a body the parser accepts, and the largest
+// handler-capped input (three 10,000-value series) sits well under it. On the
+// stdio package, which reads lines with no byte cap, an argument tree past it
+// is refused before it is serialized and sent to a server that would 413 it.
+export const MCP_MAX_TOOL_INPUT_ELEMENTS = 51_200;
+
+// Counts array elements and object members in `value`, stopping once the
+// count passes `max` (so a huge tree costs at most max + 1 steps).
+export function toolInputElementCount(value, max = MCP_MAX_TOOL_INPUT_ELEMENTS) {
+  let count = 0;
+  const stack = [value];
+  while (stack.length > 0) {
+    const node = stack.pop();
+    if (node === null || typeof node !== "object") continue;
+    if (Array.isArray(node)) {
+      for (const child of node) {
+        if (++count > max) return count;
+        if (child !== null && typeof child === "object") stack.push(child);
+      }
+    } else {
+      for (const key in node) {
+        if (!Object.prototype.hasOwnProperty.call(node, key)) continue;
+        if (++count > max) return count;
+        const child = node[key];
+        if (child !== null && typeof child === "object") stack.push(child);
+      }
+    }
+  }
+  return count;
+}
+
+// The refusal text for an over-bound call, or null when the input is within
+// the bound. Same wording as the SDK's McpServer refusal.
+export function toolInputBoundRefusal(toolName, args, max = MCP_MAX_TOOL_INPUT_ELEMENTS) {
+  if (toolInputElementCount(args, max) <= max) return null;
+  return `Invalid arguments for tool ${toolName}: arguments contain more than the maximum of ${max} elements`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent402-mcp",
-  "version": "0.13.11",
+  "version": "0.13.13",
   "mcpName": "io.github.MikeyPetrillo/agent402",
   "author": "Havok Holdings LLC <mike@agent402.tools> (https://agent402.tools)",
   "homepage": "https://agent402.tools",
@@ -17,6 +17,7 @@
   "files": [
     "index.js",
     "networks.js",
+    "discovery.js",
     "output-schemas.js",
     "README.md"
   ],