@three-ws/mcp-server 1.1.0

package/src/tools/sentiment-pulse.js

@@ -0,0 +1,118 @@
+// `sentiment_pulse` — paid MCP tool that returns a real-time sentiment
+// pulse for a Solana token by pulling recent pump.fun comments and
+// scoring them with the three.ws lexicon scorer. Callers may attach
+// additional texts (e.g. X posts they have collected) to fold into the
+// overall score.
+//
+// Pricing: $0.003 USDC, settled `exact` in USDC on Solana mainnet.
+//
+// Implementation: calls POST /api/social/sentiment-pulse on the three.ws
+// API surface. No keys are required — the endpoint relies on the public
+// pump.fun frontend-api-v3 replies route.
+
+import { z } from 'zod';
+
+import { paid, toolError } from '../payments.js';
+import { jsonSchemaFromZod } from './_shared.js';
+import { resilientFetch } from '../lib/resilient-fetch.js';
+
+const TOOL_NAME = 'sentiment_pulse';
+const TOOL_DESCRIPTION =
+	'Sentiment pulse for a Solana token: fetches the most recent pump.fun comments via frontend-api-v3, optionally folds in caller-supplied snippets (e.g. recent X cashtag posts), and scores the combined stream with the three.ws deterministic lexicon. Returns overall + per-source breakdown with examples. Pairs naturally with pump_snapshot. Paid: $0.003 USDC.';
+
+function env(k, def) {
+	const v = process.env[k];
+	return v && String(v).trim() ? String(v).trim() : def;
+}
+
+const SOLANA_MINT_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+// Single source of truth: Zod shape carries the base58 refinement + bounds +
+// descriptions; JSON Schema derived. (The previous JSON Schema declared a
+// `default: 100` on limit, which Zod cannot express as a JSON-Schema default
+// while keeping the field optional — the handler already treats an absent
+// limit as "use the endpoint default", so dropping the advertised default is
+// the correct, drift-free outcome.)
+const inputZodShape = {
+	token: z
+		.string()
+		.min(32)
+		.max(44)
+		.refine((v) => SOLANA_MINT_RE.test(v), 'token must be a base58 Solana mint pubkey')
+		.describe('Solana SPL or pump.fun mint pubkey (base58).'),
+	limit: z.number().int().min(1).max(200).describe('Max pump.fun comments to score.').optional(),
+	extraTexts: z
+		.array(z.string().max(2000))
+		.max(200)
+		.describe('Extra text snippets to include (e.g. X posts you have already collected).')
+		.optional(),
+};
+
+const inputJsonSchema = jsonSchemaFromZod(inputZodShape);
+
+export async function buildSentimentPulseTool() {
+	const handler = await paid(
+		{
+			toolName: TOOL_NAME,
+			description: TOOL_DESCRIPTION,
+			scheme: 'exact',
+			priceUsd: '$0.003',
+			inputSchema: inputJsonSchema,
+			example: { token: 'HZ1JovNiVvGrGNiiYvEozEVgZ58xaU3RKwX8eACQBCt3', limit: 100 },
+			outputExample: {
+				ok: true,
+				token: 'HZ1JovNiVvGrGNiiYvEozEVgZ58xaU3RKwX8eACQBCt3',
+				overall: { score: 0.42, posPct: 58, negPct: 16, neuPct: 26, count: 100 },
+				breakdown: { pumpfun: { score: 0.4, count: 90 }, extra: { score: 0.5, count: 10 } },
+			},
+		},
+		async ({ token, limit, extraTexts }) => {
+			const endpoint = env(
+				'MCP_SENTIMENT_PULSE_ENDPOINT',
+				'https://three.ws/api/social/sentiment-pulse',
+			);
+			let res;
+			try {
+				// Read-only scoring computation — safe to retry on a transient blip.
+				res = await resilientFetch(
+					endpoint,
+					{
+						method: 'POST',
+						headers: { 'content-type': 'application/json' },
+						body: JSON.stringify({ token, limit, extraTexts }),
+					},
+					{
+						timeoutMs: 15_000,
+						retries: 2,
+						retryNonIdempotent: true,
+						label: 'sentiment-pulse',
+					},
+				);
+			} catch (err) {
+				return toolError('upstream_unreachable', err?.message || 'fetch failed');
+			}
+			const data = await res.json().catch(() => null);
+			if (!res.ok || !data || data.ok === false) {
+				return toolError(
+					data?.code || data?.error || 'sentiment_failed',
+					data?.message || `endpoint returned ${res.status}`,
+				);
+			}
+			return data;
+		},
+	);
+	return {
+		name: TOOL_NAME,
+		title: 'Sentiment pulse ($0.003)',
+		description: TOOL_DESCRIPTION,
+		inputSchema: inputZodShape,
+		// Read-only live market feed — re-calls with the same args return
+		// fresh data, so not idempotent.
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: false,
+			openWorldHint: true,
+		},
+		handler,
+	};
+}

package/src/tools/text-to-avatar.js

@@ -0,0 +1,289 @@
+// `text_to_avatar` — paid MCP tool that generates a textured 3D GLB avatar
+// from either a text prompt or one/more reference image URLs, by driving
+// Replicate's text-to-3D / image-to-3D pipeline (Tencent Hunyuan-3D 3.1 by
+// default, configurable via REPLICATE_TEXT_TO_AVATAR_MODEL).
+//
+// Pricing: $0.15 USDC, settled `exact` in USDC on Solana mainnet.
+//
+// Behavior: synchronously submits a Replicate prediction and polls until the
+// prediction reaches a terminal state or the configured timeout fires. The
+// returned GLB URL is the Replicate-hosted output. To avoid the caller having
+// to chase signed-URL expiration, this tool re-fetches the GLB and rehosts it
+// on the three.ws R2 bucket when MCP_TEXT_TO_AVATAR_REHOST is enabled
+// (default off; opt-in because rehosting writes a public object).
+//
+// Environment:
+//   REPLICATE_API_TOKEN                — required.
+//   REPLICATE_TEXT_TO_AVATAR_MODEL     — required version hash. Pin a
+//                                        commercial-OK image/text-to-3D model
+//                                        (e.g. tencent/hunyuan-3d-3.1 latest).
+//   MCP_TEXT_TO_AVATAR_TIMEOUT_MS      — optional, defaults to 110_000.
+//   MCP_TEXT_TO_AVATAR_POLL_MS         — optional, defaults to 2_000.
+//   MCP_TEXT_TO_AVATAR_REHOST          — "1" to rehost via MCP_REHOST_ENDPOINT.
+//   MCP_REHOST_ENDPOINT                — three.ws URL that ingests external
+//                                        GLB URLs.
+//   MCP_REHOST_KEY                     — bearer for MCP_REHOST_ENDPOINT.
+
+import { z } from 'zod';
+
+import { paid, toolError } from '../payments.js';
+import { jsonSchemaFromZod } from './_shared.js';
+
+const TOOL_NAME = 'text_to_avatar';
+const TOOL_DESCRIPTION =
+	'Generate a textured 3D GLB avatar from a text prompt or one or more reference image URLs. Drives Replicate (Hunyuan-3D 3.1 by default, configurable) and polls the prediction synchronously until a GLB is produced or the timeout fires. Returns the GLB URL, the source prompt/images, the picked model version, the prediction id, and timing metadata. Paid: $0.15 USDC.';
+
+const REPLICATE_BASE = 'https://api.replicate.com/v1';
+
+function env(k, def) {
+	const v = process.env[k];
+	return v && String(v).trim() ? String(v).trim() : def;
+}
+
+function authHeaders() {
+	const token = env('REPLICATE_API_TOKEN');
+	if (!token) {
+		const err = new Error('REPLICATE_API_TOKEN is not configured on the MCP server');
+		err.code = 'not_configured';
+		throw err;
+	}
+	return { authorization: `Bearer ${token}`, 'content-type': 'application/json' };
+}
+
+function extractGlbUrl(output) {
+	if (!output) return null;
+	if (typeof output === 'string') return output;
+	if (Array.isArray(output)) {
+		for (const v of output) {
+			if (typeof v === 'string' && /\.glb(\?|$)/i.test(v)) return v;
+		}
+		for (const v of output) {
+			if (typeof v === 'string' && /^https?:\/\//.test(v)) return v;
+		}
+	}
+	if (typeof output === 'object') {
+		for (const key of ['glb', 'mesh', 'mesh_url', 'output_url', 'url', 'model']) {
+			if (typeof output[key] === 'string') return output[key];
+		}
+	}
+	return null;
+}
+
+async function submitPrediction({ version, input }) {
+	const res = await fetch(`${REPLICATE_BASE}/predictions`, {
+		method: 'POST',
+		headers: authHeaders(),
+		body: JSON.stringify({ version, input }),
+	});
+	const data = await res.json().catch(() => ({}));
+	if (!res.ok) {
+		const err = new Error(data?.detail || data?.title || `replicate returned ${res.status}`);
+		err.code = 'provider_error';
+		err.providerStatus = res.status;
+		throw err;
+	}
+	return data;
+}
+
+async function pollPrediction(predictionId, { timeoutMs, intervalMs }) {
+	const deadline = Date.now() + timeoutMs;
+	let last = null;
+	// Per-fetch ceiling so a single hung HTTP roundtrip can't block the whole
+	// poll loop past `deadline`. Without this, Node's fetch has no default
+	// timeout — a Replicate edge-stall would dangle the request indefinitely
+	// and the outer loop never gets a chance to re-check Date.now() < deadline.
+	const perFetchTimeoutMs = Math.max(intervalMs * 3, 10_000);
+	while (Date.now() < deadline) {
+		let r;
+		try {
+			r = await fetch(`${REPLICATE_BASE}/predictions/${encodeURIComponent(predictionId)}`, {
+				headers: authHeaders(),
+				signal: AbortSignal.timeout(perFetchTimeoutMs),
+			});
+		} catch (err) {
+			// Aborted polls are transient; resume the loop until `deadline`
+			// expires. Other network failures bubble up as provider errors so
+			// the caller sees them instead of an opaque _timedOut.
+			if (err?.name === 'AbortError' || err?.name === 'TimeoutError') {
+				await new Promise((res) => setTimeout(res, intervalMs));
+				continue;
+			}
+			const e = new Error(`replicate poll fetch failed: ${err?.message || err}`);
+			e.code = 'provider_error';
+			throw e;
+		}
+		const data = await r.json().catch(() => ({}));
+		if (!r.ok) {
+			const err = new Error(data?.detail || `replicate poll returned ${r.status}`);
+			err.code = 'provider_error';
+			throw err;
+		}
+		last = data;
+		const s = data.status;
+		if (s === 'succeeded' || s === 'failed' || s === 'canceled') return data;
+		await new Promise((res) => setTimeout(res, intervalMs));
+	}
+	return { ...last, _timedOut: true };
+}
+
+async function rehostIfRequested(glbUrl, { prompt, images }) {
+	if (env('MCP_TEXT_TO_AVATAR_REHOST', '0') !== '1') return null;
+	const endpoint = env('MCP_REHOST_ENDPOINT', 'https://three.ws/api/avatars/ingest-url');
+	const ingestKey = env('MCP_REHOST_KEY');
+	if (!ingestKey) return null;
+	try {
+		const r = await fetch(endpoint, {
+			method: 'POST',
+			headers: {
+				'content-type': 'application/json',
+				authorization: `Bearer ${ingestKey}`,
+			},
+			body: JSON.stringify({
+				source_url: glbUrl,
+				name: (prompt || 'mcp-text-to-avatar').slice(0, 80),
+				source: 'mcp',
+				source_meta: { provider: 'replicate', prompt, images },
+			}),
+		});
+		if (!r.ok) return { error: `rehost failed: ${r.status}` };
+		return await r.json();
+	} catch (err) {
+		return { error: err?.message || 'rehost call failed' };
+	}
+}
+
+// Single source of truth: Zod shape carries descriptions + bounds; JSON Schema
+// derived. (No required fields — the handler enforces "prompt OR images".)
+const inputZodShape = {
+	prompt: z.string().max(1000).describe('Natural-language description of the avatar to generate.').optional(),
+	images: z
+		.array(z.string().url())
+		.max(4)
+		.describe('Optional reference image URLs. When provided, the model performs image-to-3D reconstruction.')
+		.optional(),
+	seed: z.number().int().min(0).max(2147483647).optional(),
+	texture: z.boolean().describe('Request PBR textures when supported (default true).').optional(),
+};
+
+const inputJsonSchema = jsonSchemaFromZod(inputZodShape);
+
+export async function buildTextToAvatarTool() {
+	const handler = await paid(
+		{
+			toolName: TOOL_NAME,
+			description: TOOL_DESCRIPTION,
+			scheme: 'exact',
+			priceUsd: '$0.15',
+			inputSchema: inputJsonSchema,
+			example: { prompt: 'a cheerful cyberpunk fox in a red hoodie' },
+			outputExample: {
+				ok: true,
+				predictionId: 'qb...8',
+				glbUrl: 'https://replicate.delivery/.../mesh.glb',
+				prompt: 'a cheerful cyberpunk fox in a red hoodie',
+				model: 'tencent/hunyuan-3d-3.1@<version-hash>',
+				durationMs: 41000,
+				preview: 'https://three.ws/viewer?src=https%3A%2F%2Freplicate.delivery%2F...',
+			},
+		},
+		async ({ prompt, images, seed, texture }) => {
+			const version = env('REPLICATE_TEXT_TO_AVATAR_MODEL');
+			if (!version) {
+				return toolError(
+					'not_configured',
+					'REPLICATE_TEXT_TO_AVATAR_MODEL is not set on the MCP server. Pin a commercial-OK image/text-to-3D version (e.g. tencent/hunyuan-3d-3.1 latest).',
+				);
+			}
+			if (!prompt && (!images || images.length === 0)) {
+				return toolError('invalid_input', 'Provide either prompt or images[].');
+			}
+			const input = {
+				prompt: prompt || undefined,
+				image: images && images.length ? images[0] : undefined,
+				images: images && images.length ? images : undefined,
+				seed: typeof seed === 'number' ? seed : undefined,
+				texture: typeof texture === 'boolean' ? texture : true,
+			};
+			Object.keys(input).forEach((k) => input[k] === undefined && delete input[k]);
+
+			const started = Date.now();
+			let submitted;
+			try {
+				submitted = await submitPrediction({ version, input });
+			} catch (err) {
+				return toolError(err.code || 'provider_error', err.message);
+			}
+
+			const timeoutMs = Number(env('MCP_TEXT_TO_AVATAR_TIMEOUT_MS', '110000'));
+			const intervalMs = Number(env('MCP_TEXT_TO_AVATAR_POLL_MS', '2000'));
+			let finalState;
+			try {
+				finalState = await pollPrediction(submitted.id, { timeoutMs, intervalMs });
+			} catch (err) {
+				return toolError(err.code || 'provider_error', err.message, {
+					predictionId: submitted.id,
+				});
+			}
+
+			const durationMs = Date.now() - started;
+
+			if (finalState._timedOut) {
+				return toolError('timeout', `prediction did not finish within ${timeoutMs}ms`, {
+					predictionId: submitted.id,
+					status: finalState.status,
+					resumeUrl: `${REPLICATE_BASE}/predictions/${submitted.id}`,
+					durationMs,
+				});
+			}
+
+			if (finalState.status === 'failed' || finalState.status === 'canceled') {
+				return toolError(
+					'prediction_failed',
+					finalState.error || `prediction ended with status ${finalState.status}`,
+					{ predictionId: submitted.id, durationMs },
+				);
+			}
+
+			const glbUrl = extractGlbUrl(finalState.output);
+			if (!glbUrl) {
+				return toolError('no_glb_in_output', 'prediction succeeded but no GLB url was found in output', {
+					rawOutput: finalState.output,
+					predictionId: submitted.id,
+					durationMs,
+				});
+			}
+
+			const rehost = await rehostIfRequested(glbUrl, { prompt, images });
+			const preview = `https://three.ws/viewer?src=${encodeURIComponent(glbUrl)}`;
+
+			return {
+				ok: true,
+				predictionId: submitted.id,
+				glbUrl,
+				rehosted: rehost,
+				prompt: prompt || null,
+				images: images || null,
+				seed: typeof seed === 'number' ? seed : null,
+				model: version,
+				durationMs,
+				preview,
+				fetchedAt: new Date().toISOString(),
+			};
+		},
+	);
+	return {
+		name: TOOL_NAME,
+		title: 'Text → 3D avatar ($0.15)',
+		description: TOOL_DESCRIPTION,
+		inputSchema: inputZodShape,
+		// Creates a hosted GLB artifact via external generation APIs; destroys
+		// nothing, and every call mints a fresh asset.
+		annotations: {
+			readOnlyHint: false,
+			destructiveHint: false,
+			idempotentHint: false,
+			openWorldHint: true,
+		},
+		handler,
+	};
+}

package/src/tools/vanity-grinder.js

@@ -0,0 +1,178 @@
+// `vanity_grinder` — paid MCP tool that brute-forces a Solana keypair whose
+// base58 public key starts with a chosen prefix (and optionally ends with a
+// chosen suffix).
+//
+// Pricing: flat `exact` price in USDC on Solana (default $0.05, override with
+// MCP_VANITY_PRICE_USD). Metered/`upto` billing is not available on Solana —
+// @x402/svm ships no `upto` scheme — so this tool charges a single flat fee
+// regardless of attempt count.
+//
+// Output (over the same MCP channel — clients should treat as secret):
+//   - address (base58)
+//   - privateKey64 (base58, full 64-byte secret key as @solana/web3.js expects)
+//   - iterations + durationMs
+//
+// The grinder is the same async-yielding routine in api/_lib/pump-vanity.js
+// (BASE58_ALPHABET, 6-char max pattern, lowercase ignoreCase support). It
+// runs in-process — there is no external service.
+
+import { z } from 'zod';
+
+import { paid } from '../payments.js';
+import { jsonSchemaFromZod } from './_shared.js';
+import { grindMintKeypair, estimateAttempts, BASE58_ALPHABET } from '../lib/pump-vanity.js';
+import bs58 from 'bs58';
+
+const TOOL_NAME = 'vanity_grinder';
+
+// Flat price charged per successful grind, in USDC on Solana.
+const PRICE_USD = process.env.MCP_VANITY_PRICE_USD?.trim() || '$0.05';
+
+// Hard upper bound on grinder iterations. Each iteration is a synchronous
+// ed25519 keypair generation; the loop yields periodically but still pins the
+// single-threaded event loop while running. Cap it so a single paid call
+// cannot monopolize the process. 1.5M attempts is enough to reliably find a
+// 4-char prefix (~58^4 ≈ 11.3M expected, but most 1-3 char requests land far
+// sooner); anything longer is rejected up front by the difficulty guard below.
+const MAX_ITERATIONS_CAP = 1_500_000;
+const DEFAULT_MAX_ITERATIONS = 1_500_000;
+
+// Reject requests whose expected attempts dwarf the iteration cap rather than
+// grinding to the cap and timing out. We allow a generous multiple of the cap
+// (vanity grinding is probabilistic, so a request with expected ~= cap can
+// still succeed), but a prefix that is, say, 10x harder than the cap will
+// almost always time out and waste the caller's time and payment.
+const DIFFICULTY_REJECT_MULTIPLE = 4;
+
+const TOOL_DESCRIPTION =
+	`Generate a Solana keypair whose base58 address starts with a chosen prefix (and optionally ends with a chosen suffix). ` +
+	`SECURITY: the returned \`privateKey64\` is a REAL, fully-funded-capable private key. It transits the MCP channel in plaintext, ` +
+	`so the MCP host (Claude Desktop, Cursor, any proxy) MAY LOG the entire response. Treat the whole tool result as a secret, ` +
+	`import it into a wallet immediately, and never reuse a key that may have been logged. ` +
+	`Billed via x402 \`exact\` (flat ${PRICE_USD} USDC on Solana).`;
+
+// Single source of truth: Zod shape carries descriptions + bounds; JSON Schema
+// derived. Previously the JSON Schema and Zod both capped prefix/suffix at 6
+// chars and maxIterations at MAX_ITERATIONS_CAP — kept identical here.
+const inputZodShape = {
+	prefix: z
+		.string()
+		.min(1)
+		.max(6)
+		.describe(
+			`Base58 prefix the address must start with. Allowed chars: ${BASE58_ALPHABET}. 1-6 chars (longer prefixes are exponentially harder and are rejected).`,
+		),
+	suffix: z
+		.string()
+		.min(1)
+		.max(6)
+		.describe('Optional base58 suffix the address must end with. 1-6 chars.')
+		.optional(),
+	ignoreCase: z.boolean().describe('Case-insensitive match (folds upper+lower base58 chars).').optional(),
+	maxIterations: z
+		.number()
+		.int()
+		.min(1)
+		.max(MAX_ITERATIONS_CAP)
+		.describe(`Hard cap on grinder iterations. Default ${DEFAULT_MAX_ITERATIONS}, clamped to ${MAX_ITERATIONS_CAP}.`)
+		.optional(),
+};
+
+const inputJsonSchema = jsonSchemaFromZod(inputZodShape);
+
+// Up-front difficulty guard. Returns null if the request is feasible within the
+// iteration cap, or a helpful Error (status 400) if the requested prefix/suffix
+// is so hard it would grind to the cap and time out. Exported for tests.
+export function assertGrindFeasible({ prefix, suffix, ignoreCase = false, maxIterations = DEFAULT_MAX_ITERATIONS } = {}) {
+	const cap = Math.min(Math.max(1, Math.floor(maxIterations)), MAX_ITERATIONS_CAP);
+	const expected = estimateAttempts({ prefix, suffix, ignoreCase });
+	if (expected > cap * DIFFICULTY_REJECT_MULTIPLE) {
+		const pattern = [prefix ? `prefix '${prefix}'` : null, suffix ? `suffix '${suffix}'` : null]
+			.filter(Boolean)
+			.join(' + ');
+		return Object.assign(
+			new Error(
+				`Pattern too hard: ${pattern} needs ~${Math.round(expected).toLocaleString()} expected attempts, ` +
+					`but the grinder caps at ${cap.toLocaleString()} iterations. ` +
+					`Use a shorter prefix/suffix (each extra base58 char is ~${ignoreCase ? 33 : 58}x harder)` +
+					`${ignoreCase ? '' : ', or enable ignoreCase to roughly halve the difficulty per char'}.`,
+			),
+			{ status: 400, code: 'vanity_too_hard' },
+		);
+	}
+	return null;
+}
+
+export async function buildVanityGrinderTool() {
+	const handler = await paid(
+		{
+			toolName: TOOL_NAME,
+			description: TOOL_DESCRIPTION,
+			priceUsd: PRICE_USD,
+			inputSchema: inputJsonSchema,
+			example: { prefix: 'pump' },
+			outputExample: {
+				address: 'pumpXYZ...',
+				privateKey64: '5x...base58...',
+				iterations: 12345,
+				durationMs: 230,
+				priceUsd: PRICE_USD,
+			},
+		},
+		async ({ prefix, suffix, ignoreCase = false, maxIterations = DEFAULT_MAX_ITERATIONS }) => {
+			// Clamp the caller-supplied cap into the safe range so a single paid
+			// call can never schedule millions of synchronous keypair generations.
+			const cap = Math.min(Math.max(1, Math.floor(maxIterations)), MAX_ITERATIONS_CAP);
+
+			// Reject impossible-to-satisfy patterns up front instead of grinding
+			// to the cap and timing out (event-loop DoS / wasted payment).
+			const infeasible = assertGrindFeasible({ prefix, suffix, ignoreCase, maxIterations: cap });
+			if (infeasible) throw infeasible;
+
+			const expected = estimateAttempts({ prefix, suffix, ignoreCase });
+			const grind = await grindMintKeypair({
+				prefix,
+				suffix,
+				ignoreCase,
+				maxIterations: cap,
+			});
+			const address = grind.keypair.publicKey.toBase58();
+			// @solana/web3.js Keypair.secretKey is the full 64-byte ed25519 secret
+			// (32-byte seed || 32-byte pubkey). Wallets like Phantom import this
+			// directly as base58. The client is responsible for storing it.
+			//
+			// NOTE: privateKey64 is intentionally NEVER passed to console.log/error
+			// anywhere in this path — the only sink is the structured tool result.
+			const privateKey64 = bs58.encode(Buffer.from(grind.keypair.secretKey));
+			return {
+				address,
+				privateKey64,
+				iterations: grind.iterations,
+				estimatedIterations: Math.round(expected),
+				durationMs: grind.durationMs,
+				prefix,
+				suffix: suffix || null,
+				ignoreCase,
+				priceUsd: PRICE_USD,
+				_secretWarning:
+					'privateKey64 is a REAL Solana private key. It just transited the MCP channel in plaintext, ' +
+					'so the MCP host (Claude Desktop / Cursor / any proxy) MAY have logged this entire response. ' +
+					'Import it into a wallet now, treat the whole result as a secret, and do not reuse a key you suspect was logged.',
+			};
+		},
+	);
+	return {
+		name: TOOL_NAME,
+		title: `Solana vanity grinder (${PRICE_USD})`,
+		description: TOOL_DESCRIPTION,
+		inputSchema: inputZodShape,
+		// Pure local compute with no external interaction, but output is a
+		// freshly-random keypair every call — never idempotent.
+		annotations: {
+			readOnlyHint: true,
+			idempotentHint: false,
+			openWorldHint: false,
+		},
+		handler,
+	};
+}