@three-ws/mcp-server 1.1.0

package/src/lib/resilient-fetch.js

@@ -0,0 +1,194 @@
+// Resilient HTTP layer shared by every MCP tool.
+//
+// The tools previously each called bare `fetch()` — most with no timeout and
+// none with a retry. A single transient blip (a 429 burst, a 502 from a CDN, a
+// dropped socket) failed the whole tool call. This module gives every outbound
+// request three guarantees:
+//
+//   1. It ALWAYS times out. No request can hang forever and block a paid tool
+//      (which, on a hang, could settle a payment with no result).
+//   2. Transient failures are retried with exponential backoff + full jitter,
+//      honoring the server's `Retry-After` on 429/503.
+//   3. Retries are SAFE: only idempotent methods (GET/HEAD) are retried by
+//      default, so a non-idempotent POST (start a job, send an agent message)
+//      is never silently duplicated. A caller that knows its POST is safe to
+//      replay can opt in with `retryNonIdempotent: true`.
+//
+// `resilientFetch` returns a `Response` (drop-in for `fetch`); `fetchJson`
+// layers JSON parsing + non-2xx → throw on top of it.
+
+const DEFAULT_RETRY_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+const IDEMPOTENT_METHODS = new Set(['GET', 'HEAD', 'OPTIONS']);
+
+/**
+ * Sleep that rejects promptly if an AbortSignal fires, so a caller-supplied
+ * deadline can cut a backoff wait short instead of waiting it out.
+ */
+function abortableDelay(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener?.('abort', onAbort);
+			resolve();
+		}, ms);
+		function onAbort() {
+			clearTimeout(timer);
+			reject(signal.reason instanceof Error ? signal.reason : new Error('aborted'));
+		}
+		signal?.addEventListener?.('abort', onAbort, { once: true });
+	});
+}
+
+/**
+ * Parse a `Retry-After` header into milliseconds. Supports both the
+ * delta-seconds form (`120`) and the HTTP-date form. Returns null when absent
+ * or unparseable so the caller falls back to computed backoff.
+ */
+function parseRetryAfterMs(res) {
+	const raw = res?.headers?.get?.('retry-after');
+	if (!raw) return null;
+	const secs = Number(raw);
+	if (Number.isFinite(secs)) return Math.max(0, secs * 1000);
+	const when = Date.parse(raw);
+	if (Number.isFinite(when)) return Math.max(0, when - Date.now());
+	return null;
+}
+
+/**
+ * Full-jitter exponential backoff: a random wait in [0, cap] where the cap
+ * doubles each attempt. Full jitter (vs. fixed backoff) spreads a thundering
+ * herd of simultaneous retries so they don't re-collide on the next attempt.
+ */
+function backoffMs(attempt, baseDelayMs, maxDelayMs) {
+	const cap = Math.min(maxDelayMs, baseDelayMs * 2 ** attempt);
+	return Math.floor(Math.random() * cap);
+}
+
+/**
+ * fetch() with a hard timeout and safe, jittered retries.
+ *
+ * @param {string} url
+ * @param {RequestInit} [init]
+ * @param {object} [opts]
+ * @param {number} [opts.timeoutMs=10000]   per-attempt timeout
+ * @param {number} [opts.retries=2]          retry count (total attempts = retries + 1)
+ * @param {number} [opts.baseDelayMs=250]    backoff base
+ * @param {number} [opts.maxDelayMs=4000]    backoff cap
+ * @param {Set<number>|number[]} [opts.retryStatuses]  HTTP statuses worth retrying
+ * @param {boolean} [opts.retryNonIdempotent=false]    allow retrying non-GET/HEAD
+ * @param {AbortSignal} [opts.signal]        external deadline/cancel
+ * @param {string} [opts.label]              short name used in thrown error messages
+ * @returns {Promise<Response>}
+ */
+export async function resilientFetch(url, init = {}, opts = {}) {
+	const {
+		timeoutMs = 10_000,
+		retries = 2,
+		baseDelayMs = 250,
+		maxDelayMs = 4_000,
+		retryStatuses,
+		retryNonIdempotent = false,
+		signal: externalSignal,
+		label,
+	} = opts;
+
+	const statuses = retryStatuses
+		? retryStatuses instanceof Set
+			? retryStatuses
+			: new Set(retryStatuses)
+		: DEFAULT_RETRY_STATUSES;
+	const method = (init.method || 'GET').toUpperCase();
+	const mayRetry = retryNonIdempotent || IDEMPOTENT_METHODS.has(method);
+	const name = label || `${method} ${url}`;
+
+	let lastErr = null;
+	for (let attempt = 0; attempt <= retries; attempt += 1) {
+		if (externalSignal?.aborted) {
+			throw externalSignal.reason instanceof Error
+				? externalSignal.reason
+				: new Error(`${name}: aborted`);
+		}
+
+		// Fresh controller per attempt (abort is one-shot). Abort on either the
+		// per-attempt timeout OR the caller's external signal.
+		const controller = new AbortController();
+		let timedOut = false;
+		const timer = setTimeout(() => {
+			timedOut = true;
+			controller.abort();
+		}, timeoutMs);
+		const onExternalAbort = () => controller.abort();
+		externalSignal?.addEventListener?.('abort', onExternalAbort, { once: true });
+
+		try {
+			const res = await fetch(url, { ...init, signal: controller.signal });
+
+			// Retry on transient status codes if attempts remain and the method
+			// is replay-safe. Drain the body so the socket can be reused.
+			if (statuses.has(res.status) && attempt < retries && mayRetry) {
+				const retryAfter = parseRetryAfterMs(res);
+				try {
+					await res.arrayBuffer();
+				} catch {
+					/* ignore drain failure */
+				}
+				lastErr = new Error(`${name} → HTTP ${res.status}`);
+				const wait = retryAfter ?? backoffMs(attempt, baseDelayMs, maxDelayMs);
+				await abortableDelay(wait, externalSignal);
+				continue;
+			}
+			return res;
+		} catch (err) {
+			// Distinguish a timeout from an external cancel: an external abort is
+			// the caller's deadline and must not be retried.
+			if (externalSignal?.aborted && !timedOut) {
+				throw externalSignal.reason instanceof Error
+					? externalSignal.reason
+					: new Error(`${name}: aborted`);
+			}
+			const normalized = timedOut
+				? Object.assign(new Error(`${name}: timed out after ${timeoutMs}ms`), {
+						name: 'TimeoutError',
+					})
+				: err;
+			lastErr = normalized;
+
+			// A thrown fetch() error is always a network drop or timeout (HTTP
+			// error statuses resolve, they don't throw), so it is retryable for
+			// any replay-safe method while attempts remain.
+			if (attempt < retries && mayRetry) {
+				await abortableDelay(backoffMs(attempt, baseDelayMs, maxDelayMs), externalSignal);
+				continue;
+			}
+			throw normalized;
+		} finally {
+			clearTimeout(timer);
+			externalSignal?.removeEventListener?.('abort', onExternalAbort);
+		}
+	}
+	throw lastErr || new Error(`${name}: exhausted retries`);
+}
+
+/**
+ * resilientFetch + JSON. Throws on a non-2xx final response (after retries) and
+ * on a body that isn't valid JSON, matching the `fetchJson` contract the tools
+ * already expect. Use for read endpoints that return JSON.
+ *
+ * @param {string} url
+ * @param {RequestInit} [init]
+ * @param {object} [opts]  same options as resilientFetch
+ * @returns {Promise<any>}
+ */
+export async function fetchJson(url, init = {}, opts = {}) {
+	const label = opts.label || `${(init.method || 'GET').toUpperCase()} ${url}`;
+	const res = await resilientFetch(url, init, opts);
+	if (!res.ok) {
+		throw new Error(`${label} → HTTP ${res.status}`);
+	}
+	return res.json();
+}
+
+export { DEFAULT_RETRY_STATUSES, parseRetryAfterMs, backoffMs };

package/src/lib/solana-rpc.js

@@ -0,0 +1,130 @@
+// Multi-endpoint Solana RPC with automatic failover.
+//
+// Tools previously hit a SINGLE Solana RPC (defaulting to the public, heavily
+// rate-limited api.mainnet-beta.solana.com). When that endpoint throttled or
+// blipped, the tool failed outright. This module gives every Solana read a
+// prioritized list of endpoints and a bounded per-call timeout: the operation
+// is tried against each endpoint in turn until one succeeds, so a single
+// provider outage no longer takes the tool down.
+//
+// Endpoint precedence (highest first):
+//   1. SOLANA_RPC_URLS  — comma-separated list (the explicit failover chain)
+//   2. SOLANA_RPC_URL   — single primary (kept for back-compat)
+//   3. built-in public mainnet endpoints (last-resort redundancy)
+//
+// A Connection is created per (endpoint, commitment) and memoized, and each is
+// wired with a fetch that hard-times-out so a stuck socket can't wedge a paid
+// call. Failover order rotates after a failure so a flaky endpoint moves to the
+// back instead of being retried first on the next call.
+
+import { Connection } from '@solana/web3.js';
+
+import { resilientFetch } from './resilient-fetch.js';
+
+// Last-resort redundancy when the operator configures nothing. These are
+// well-known public mainnet endpoints; an operator who needs guaranteed
+// throughput should set SOLANA_RPC_URLS to dedicated providers.
+const DEFAULT_MAINNET_ENDPOINTS = [
+	'https://api.mainnet-beta.solana.com',
+	'https://solana-rpc.publicnode.com',
+	'https://rpc.ankr.com/solana',
+];
+
+function dedupe(list) {
+	const seen = new Set();
+	const out = [];
+	for (const item of list) {
+		const v = (item || '').trim();
+		if (v && !seen.has(v)) {
+			seen.add(v);
+			out.push(v);
+		}
+	}
+	return out;
+}
+
+/**
+ * Resolve the ordered Solana mainnet endpoint list from env, falling back to
+ * the built-in public set. Always returns at least one endpoint.
+ *
+ * @returns {string[]}
+ */
+export function getSolanaEndpoints() {
+	const fromList = (process.env.SOLANA_RPC_URLS || '')
+		.split(',')
+		.map((s) => s.trim())
+		.filter(Boolean);
+	const primary = (process.env.SOLANA_RPC_URL || '').trim();
+	const ordered = dedupe([...fromList, primary, ...DEFAULT_MAINNET_ENDPOINTS]);
+	return ordered.length ? ordered : [...DEFAULT_MAINNET_ENDPOINTS];
+}
+
+// Cache one Connection per (endpoint|commitment). web3.js Connections are cheap
+// but hold an http agent; reusing them keeps sockets warm across tool calls.
+const connectionCache = new Map();
+
+function connectionFor(endpoint, commitment, timeoutMs) {
+	const key = `${endpoint}|${commitment}`;
+	let conn = connectionCache.get(key);
+	if (!conn) {
+		conn = new Connection(endpoint, {
+			commitment,
+			// Bound every RPC HTTP call. web3.js otherwise inherits Node's
+			// unbounded default, which is the source of indefinite hangs.
+			fetch: (url, init) =>
+				resilientFetch(url, init, {
+					timeoutMs,
+					// web3.js POSTs JSON-RPC; its reads are idempotent queries, so
+					// allow a single transport-level replay on a blip.
+					retries: 1,
+					retryNonIdempotent: true,
+					label: `solana-rpc ${endpoint}`,
+				}),
+			disableRetryOnRateLimit: false,
+		});
+		connectionCache.set(key, conn);
+	}
+	return conn;
+}
+
+// Endpoints that just failed are rotated to the back so the next call starts
+// with the one most likely to be healthy.
+let rotation = 0;
+
+/**
+ * Run a Solana read against the endpoint list with failover.
+ *
+ * `fn` receives a live `Connection` and should perform exactly one logical
+ * read. If it throws, the next endpoint is tried. The error from the last
+ * endpoint is surfaced when every endpoint fails.
+ *
+ * @template T
+ * @param {(conn: import('@solana/web3.js').Connection) => Promise<T>} fn
+ * @param {object} [opts]
+ * @param {string} [opts.commitment='confirmed']
+ * @param {number} [opts.timeoutMs=12000]  per-endpoint HTTP timeout
+ * @returns {Promise<T>}
+ */
+export async function withSolanaConnection(fn, opts = {}) {
+	const { commitment = 'confirmed', timeoutMs = 12_000 } = opts;
+	const endpoints = getSolanaEndpoints();
+	const start = rotation % endpoints.length;
+	rotation += 1;
+
+	let lastErr = null;
+	for (let i = 0; i < endpoints.length; i += 1) {
+		const endpoint = endpoints[(start + i) % endpoints.length];
+		try {
+			return await fn(connectionFor(endpoint, commitment, timeoutMs));
+		} catch (err) {
+			lastErr = err;
+		}
+	}
+	throw lastErr || new Error('solana-rpc: all endpoints failed');
+}
+
+// Test-only: drop cached Connections so a test can swap env between cases.
+export function _resetSolanaCache() {
+	connectionCache.clear();
+	rotation = 0;
+}

package/src/payments.js

@@ -0,0 +1,319 @@
+// Shared x402 payment wiring for paid MCP tools — Solana mainnet only.
+//
+// Every tool in mcp-server/src/tools/*.js wraps its handler in
+// `paid(cfg, fn)`. This file builds the single shared x402ResourceServer
+// (one per process) that verifies + settles USDC payments on Solana via
+// PayAI's Solana facilitator, and exposes `paid()` that produces the
+// McpServer.tool() callback per the @x402/mcp transport spec
+// (PaymentRequired in structuredContent + content[0].text, settlement
+// response under _meta["x402/payment-response"]).
+//
+// Network: Solana mainnet (solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp).
+//   Receiver: MCP_SVM_PAYMENT_ADDRESS (falls back to X402_PAY_TO_SOLANA /
+//   X402_PAY_TO). Asset: USDC (EPjFW…), 6 decimals. Fee payer:
+//   X402_FEE_PAYER_SOLANA.
+//
+// Only the `exact` scheme is supported: @x402/svm ships no `upto` scheme, so
+// metered/`upto` billing is not available on Solana. Tools that previously
+// metered (the vanity grinder) charge a flat exact price instead.
+//
+// `createPaymentWrapper` from @x402/mcp returns a function that wraps your
+// async tool handler into an MCP-compatible callback. It handles the entire
+// 402 dance: returns a 402 PaymentRequired result with both structuredContent
+// + content[0].text when the client calls without _meta["x402/payment"];
+// verifies the payment, runs the handler, settles, and attaches the
+// SettleResponse to _meta["x402/payment-response"].
+
+import { HTTPFacilitatorClient, x402ResourceServer } from '@x402/core/server';
+import { registerExactSvmScheme } from '@x402/svm/exact/server';
+import { createPaymentWrapper, createToolResourceUrl } from '@x402/mcp';
+import { declareDiscoveryExtension } from '@x402/extensions/bazaar';
+
+// CAIP-2 id for Solana mainnet (mirrors api/_lib/x402-spec.js).
+const NETWORK_SOLANA_MAINNET = 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp';
+
+const DEFAULT_SOLANA_USDC = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+
+const env = (key, fallback) => {
+	const v = process.env[key];
+	return v && v.trim() ? v.trim() : fallback;
+};
+
+function requireSvmPayTo() {
+	const addr = env('MCP_SVM_PAYMENT_ADDRESS') || env('X402_PAY_TO_SOLANA') || env('X402_PAY_TO');
+	if (!addr) {
+		throw new Error(
+			'mcp-server: set MCP_SVM_PAYMENT_ADDRESS to receive Solana USDC payments (or X402_PAY_TO_SOLANA / X402_PAY_TO)',
+		);
+	}
+	return addr;
+}
+
+/**
+ * Assert the receiving Solana payment address is configured. Called once by the
+ * stdio entry point so a running server fails fast with a single clean line
+ * instead of only erroring on the first paid call. Does NOT run during
+ * `buildServer()`/tests — tool registration stays secret-free.
+ *
+ * @throws {Error} with a single actionable message when no pay-to is set
+ */
+export function assertPaymentEnv() {
+	requireSvmPayTo();
+}
+
+function svmFeePayer() {
+	return env('X402_FEE_PAYER_SOLANA', '2wKupLR9q6wXYppw8Gr2NvWxKBUqm4PPJKkQfoxHDBg4');
+}
+
+// Resolve the ordered facilitator URL list. A comma-separated
+// X402_FACILITATOR_URLS_SOLANA configures redundancy; the single-URL env vars
+// are kept for back-compat, and PayAI is the last-resort default. Earlier URLs
+// get precedence at init — if the primary's /supported fetch is unreachable, a
+// later facilitator that responded takes over the Solana `exact` kind, so a
+// facilitator outage no longer leaves the server unable to settle.
+function solanaFacilitatorUrls() {
+	const list = env('X402_FACILITATOR_URLS_SOLANA', '')
+		.split(',')
+		.map((s) => s.trim())
+		.filter(Boolean);
+	const single = env('X402_FACILITATOR_URL_SOLANA') || env('X402_FACILITATOR_URL');
+	const ordered = [];
+	const seen = new Set();
+	for (const url of [...list, single, 'https://facilitator.payai.network']) {
+		if (url && !seen.has(url)) {
+			seen.add(url);
+			ordered.push(url);
+		}
+	}
+	return ordered;
+}
+
+function buildSolanaFacilitators() {
+	const token = env('X402_FACILITATOR_TOKEN_SOLANA') || env('X402_FACILITATOR_TOKEN');
+	const createAuthHeaders = token
+		? async () => ({ headers: { Authorization: `Bearer ${token}` } })
+		: undefined;
+	return solanaFacilitatorUrls().map(
+		(url) => new HTTPFacilitatorClient({ url, createAuthHeaders }),
+	);
+}
+
+let resourceServerPromise = null;
+let lastInitError = null;
+
+// Build a single shared x402ResourceServer, register the Solana `exact`
+// scheme, and call .initialize() to fetch the facilitator's /supported (caches
+// kinds + extensions for the verify/settle path).
+//
+// `initialize()` MUST run before any verify/settle — without it the server has
+// no notion of which facilitator handles Solana and will throw on the first
+// paid call. We memoize the promise so concurrent tool calls don't race during
+// startup.
+export function getResourceServer() {
+	if (resourceServerPromise) return resourceServerPromise;
+	resourceServerPromise = (async () => {
+		const server = new x402ResourceServer(buildSolanaFacilitators());
+		registerExactSvmScheme(server, {});
+		try {
+			await server.initialize();
+		} catch (err) {
+			lastInitError = err;
+			// Don't fatally throw — the server can still emit 402 challenges and
+			// /supported may have been partially populated. Operators will see
+			// the real failure when a tool tries to verify a payment.
+			console.error(`[mcp-server] facilitator initialize() failed: ${err.message}`);
+		}
+		return server;
+	})();
+	return resourceServerPromise;
+}
+
+export function getLastFacilitatorInitError() {
+	return lastInitError;
+}
+
+// Build the per-tool `accepts` list. Every paid tool settles in USDC on Solana
+// mainnet via the `exact` scheme.
+async function buildAcceptsForTool({
+	resourceServer,
+	scheme,
+	priceUsd,
+	networks,
+	resourceUrl,
+	extra,
+}) {
+	const opts = [];
+	for (const net of networks) {
+		if (net !== NETWORK_SOLANA_MAINNET) {
+			throw new Error(`mcp-server: unsupported network ${net} (Solana mainnet only)`);
+		}
+		opts.push({
+			scheme,
+			network: NETWORK_SOLANA_MAINNET,
+			payTo: requireSvmPayTo(),
+			price: priceUsd,
+			maxTimeoutSeconds: 60,
+			extra: {
+				name: 'USDC',
+				decimals: 6,
+				asset: env('X402_ASSET_MINT_SOLANA', DEFAULT_SOLANA_USDC),
+				feePayer: svmFeePayer(),
+				...(extra?.svm || {}),
+			},
+		});
+	}
+	if (opts.length === 0) {
+		throw new Error(`mcp-server: no networks resolved for scheme=${scheme}`);
+	}
+	return resourceServer.buildPaymentRequirementsFromOptions(opts, { resourceUrl });
+}
+
+/**
+ * Wrap a tool handler with x402 payment (USDC on Solana, `exact` scheme).
+ *
+ * The x402 wiring (resource server init, `accepts` requirements, payment
+ * wrapper) is built LAZILY on the first invocation — NOT when the tool is
+ * registered. This keeps tool registration (names/descriptions/schemas)
+ * free of any runtime payment env: `buildServer()` can enumerate every tool
+ * without MCP_SVM_PAYMENT_ADDRESS, and only an actual paid call triggers the
+ * env requirement. The wrapper is memoized so the first call pays the init cost
+ * once and every subsequent call reuses it.
+ *
+ * @param {object} cfg
+ * @param {string} cfg.toolName              — e.g. "get_pose_seed"
+ * @param {string} cfg.description           — human-readable description
+ * @param {string} [cfg.scheme='exact']      — only 'exact' is supported on Solana
+ * @param {string|number} cfg.priceUsd       — Price like "$0.001"
+ * @param {string[]} [cfg.networks]          — default ['solana:5eykt4…']
+ * @param {object} cfg.inputSchema           — JSON Schema for the tool's args
+ * @param {object} [cfg.example]             — example invocation for bazaar
+ * @param {object} [cfg.outputExample]       — example output for bazaar
+ * @param {object} [cfg.extra]               — extra fields (extra.svm)
+ * @param {object} [cfg.hooks]               — { onBeforeExecution, onAfterExecution, onAfterSettlement }
+ * @param {Function} handler                 — async (args, { settle? }) → result
+ * @returns {Function} MCP tool callback for McpServer.tool()
+ */
+export function paid(cfg, handler) {
+	const {
+		toolName,
+		description,
+		scheme = 'exact',
+		priceUsd,
+		networks = [NETWORK_SOLANA_MAINNET],
+		inputSchema,
+		example,
+		outputExample,
+		extra,
+		hooks,
+	} = cfg;
+
+	if (!toolName) throw new Error('paid(): toolName is required');
+	if (!description) throw new Error('paid(): description is required');
+	if (!priceUsd) throw new Error('paid(): priceUsd is required (e.g. "$0.001")');
+	if (!inputSchema) throw new Error('paid(): inputSchema is required');
+	if (scheme !== 'exact') {
+		throw new Error(`paid(): only the 'exact' scheme is supported on Solana (got '${scheme}')`);
+	}
+
+	// Lazily build (and memoize) the payment wrapper. This is the ONLY place
+	// that touches payment env (requireSvmPayTo) and the facilitator, so it
+	// runs on first invocation rather than at registration time.
+	let wrapperPromise = null;
+	async function getWrapper() {
+		if (wrapperPromise) return wrapperPromise;
+		wrapperPromise = (async () => {
+			const resourceServer = await getResourceServer();
+			const resourceUrl = createToolResourceUrl(toolName);
+			const accepts = await buildAcceptsForTool({
+				resourceServer,
+				scheme,
+				priceUsd,
+				networks,
+				resourceUrl,
+				extra,
+			});
+
+			const bazaar = declareDiscoveryExtension({
+				toolName,
+				description,
+				transport: 'stdio',
+				inputSchema,
+				example,
+				output: outputExample ? { example: outputExample } : undefined,
+			});
+
+			const wrap = createPaymentWrapper(resourceServer, {
+				accepts,
+				resource: { url: resourceUrl, description, mimeType: 'application/json' },
+				extensions: bazaar,
+				hooks,
+			});
+
+			return wrap(async (args, context) => {
+				const result = await handler(args, context);
+				return buildToolResult(result);
+			});
+		})();
+		return wrapperPromise;
+	}
+
+	// The callback McpServer.registerTool() invokes. Defers all payment wiring
+	// to the first real call.
+	return async function paidToolCallback(args, context) {
+		const wrapped = await getWrapper();
+		return wrapped(args, context);
+	};
+}
+
+/**
+ * Build the MCP `CallToolResult` envelope from a handler's return value.
+ *
+ * This is the single place every paid tool's output is shaped, so all 15 tools
+ * get the same modern MCP contract for free:
+ *
+ *   - `content[0].text` — the JSON (or raw string) blob. Always present, so
+ *     pre-2025-06-18 clients that only read text keep working unchanged.
+ *   - `structuredContent` — the handler's object verbatim, surfaced as MCP
+ *     structured tool output (spec 2025-06-18). Clients that support it get a
+ *     ready-to-use object and skip the `JSON.parse(content[0].text)` dance.
+ *     Only emitted for plain objects (the spec requires an object, not an
+ *     array or scalar); string/array returns fall back to text-only.
+ *   - `isError: true` — set ONLY for the explicit `toolError()` envelope
+ *     (`ok === false`). This flags the failure to the LLM AND, via the x402
+ *     payment wrapper, cancels the payment instead of settling it — so a caller
+ *     is never charged for an invalid-input / provider / timeout error. It is
+ *     deliberately NOT set for partial-data successes (e.g. a snapshot whose
+ *     `price` sub-field carries `{ error }` but whose overall call succeeded),
+ *     which have no top-level `ok: false`.
+ *
+ * @param {unknown} result  — whatever the tool handler returned
+ * @returns {{ content: Array<{type:'text',text:string}>, structuredContent?: object, isError?: true }}
+ */
+export function buildToolResult(result) {
+	const text = typeof result === 'string' ? result : JSON.stringify(result);
+	const envelope = { content: [{ type: 'text', text }] };
+	const isPlainObject = result !== null && typeof result === 'object' && !Array.isArray(result);
+	if (isPlainObject) {
+		envelope.structuredContent = result;
+		if (result.ok === false) {
+			envelope.isError = true;
+		}
+	}
+	return envelope;
+}
+
+/**
+ * Standard tool error envelope. Every tool's error path returns this shape so
+ * MCP clients can branch on a stable `{ ok: false, error: <code>, message }`
+ * contract instead of the per-tool ad-hoc shapes this server used to emit.
+ *
+ * @param {string} code     — machine-readable error code (snake_case)
+ * @param {string} message  — human-readable explanation
+ * @param {object} [extra]  — optional extra fields merged into the envelope
+ * @returns {{ ok: false, error: string, message: string }}
+ */
+export function toolError(code, message, extra) {
+	return { ok: false, error: code, message, ...(extra || {}) };
+}
+
+export { NETWORK_SOLANA_MAINNET };

package/src/tools/_shared.js

@@ -0,0 +1,41 @@
+// Shared helpers for the paid MCP tools.
+//
+// Single-sources the tool input schema: each tool declares its arguments ONCE
+// as a Zod shape (an object of `{ field: ZodType }`), and the JSON Schema the
+// MCP client / x402 bazaar sees is DERIVED from that shape via
+// zod-to-json-schema. This kills the JSON-Schema↔Zod drift class — the two
+// representations can no longer disagree because there is only one source.
+//
+// Re-exports `toolError` so tools can import their error contract + schema
+// helper from a single module.
+
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+
+export { toolError } from '../payments.js';
+
+/**
+ * Derive a MCP-shaped JSON Schema from a Zod shape (the same `{ field: ZodType }`
+ * object passed to `McpServer.registerTool({ inputSchema })`).
+ *
+ * The output matches what the tools previously hand-wrote: a top-level
+ * `{ type: 'object', properties, required, additionalProperties: false }`
+ * with no `$schema`/`$ref` envelope, so the external contract MCP clients and
+ * the x402 bazaar see is unchanged.
+ *
+ * @param {Record<string, import('zod').ZodTypeAny>} shape
+ * @returns {object} JSON Schema (draft-07 object schema)
+ */
+export function jsonSchemaFromZod(shape) {
+	const schema = zodToJsonSchema(z.object(shape).strict(), {
+		// Inline everything — MCP clients expect a self-contained object schema,
+		// not a `$ref`-into-`definitions` document.
+		$refStrategy: 'none',
+		target: 'jsonSchema7',
+	});
+	// zod-to-json-schema wraps the result with a `$schema` meta key; strip it so
+	// the emitted schema is byte-for-byte the lean object schema the tools used
+	// to hand-maintain.
+	delete schema.$schema;
+	return schema;
+}