@three-ws/mcp-server 1.1.0

package/src/index.js

@@ -0,0 +1,201 @@
+#!/usr/bin/env node
+// @three-ws/mcp-server entry point.
+//
+// Boots an MCP server over stdio that exposes paid tools for pose generation,
+// pump.fun snapshots, ERC-8004 reputation lookups, and Solana vanity mining.
+// Tool calls without payment return the v2 MCP-transport `PaymentRequired`
+// envelope (per @x402/mcp + transports-v2/mcp.md). Successful settlements are
+// reported back to the client under `_meta["x402/payment-response"]`.
+//
+// Run standalone:
+//   node mcp-server/src/index.js
+//
+// Or wire into Claude Desktop / Cursor as documented in README.md.
+//
+// Testability: `buildServer()` constructs and returns the fully-registered
+// McpServer WITHOUT connecting the stdio transport and WITHOUT requiring any
+// runtime payment env — tool registration (names/descriptions/schemas) is
+// secret-free. Only an actual paid tool *invocation* requires
+// MCP_SVM_PAYMENT_ADDRESS (enforced lazily inside `paid()`). The stdio boot in
+// `main()` runs only when this file is the process entry point.
+
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { realpathSync } from 'node:fs';
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+
+import { assertPaymentEnv, getLastFacilitatorInitError, getResourceServer } from './payments.js';
+import { buildPoseSeedTool } from './tools/pose-seed.js';
+import { buildPumpSnapshotTool } from './tools/pump-snapshot.js';
+import { buildAgentReputationTool } from './tools/agent-reputation.js';
+import { buildVanityGrinderTool } from './tools/vanity-grinder.js';
+import { buildTextToAvatarTool } from './tools/text-to-avatar.js';
+import { buildMeshForgeTool } from './tools/mesh-forge.js';
+import { buildRigMeshTool } from './tools/rig-mesh.js';
+import { buildSentimentPulseTool } from './tools/sentiment-pulse.js';
+import { buildEnsSnsResolveTool } from './tools/ens-sns-resolve.js';
+import { buildAgentDelegateActionTool } from './tools/agent-delegate-action.js';
+import { buildAgenCListTasksTool } from './tools/agenc-list-tasks.js';
+import { buildAgenCGetTaskTool } from './tools/agenc-get-task.js';
+import { buildAgenCGetAgentTool } from './tools/agenc-get-agent.js';
+import { buildAixbtIntelTool } from './tools/aixbt-intel.js';
+import { buildAixbtProjectsTool } from './tools/aixbt-projects.js';
+
+const SERVER_INSTRUCTIONS =
+	'Paid x402 MCP tools from three.ws. Each tool quotes its USDC price in its description. ' +
+	'Tool calls without an x402 payment payload in _meta return a PaymentRequired structuredContent ' +
+	'(v2 MCP transport spec). Tools cover: 3D avatar generation (text_to_avatar), ' +
+	'text/image-to-3D mesh generation via a Granite-directed model chain (mesh_forge), ' +
+	'auto-rigging a GLB into an animation-ready model (rig_mesh), ' +
+	'ENS + SNS name resolution ' +
+	'(ens_sns_resolve), agent-to-agent delegation (agent_delegate_action), token sentiment pulse ' +
+	'(sentiment_pulse), pose generation (get_pose_seed), Solana token snapshots (pump_snapshot), ' +
+	'ERC-8004 agent reputation (agent_reputation), Solana vanity address mining ' +
+	'(vanity_grinder), and AgenC coordination protocol reads — ' +
+	'task discovery, task status + lifecycle, and agent registry lookup ' +
+	'(agenc_list_tasks, agenc_get_task, agenc_get_agent), and aixbt market ' +
+	'intelligence — narrative intel feed and momentum-ranked project scans ' +
+	'(aixbt_intel, aixbt_projects).';
+
+// The advertised MCP server version comes straight from package.json so it
+// can never drift from the published npm version.
+const { version: PKG_VERSION } = createRequire(import.meta.url)('../package.json');
+
+// Every tool builder. Each returns a descriptor
+// { name, title, description, inputSchema (Zod shape), annotations, handler }.
+// None of these require payment env — the env requirement is deferred to the
+// first paid call.
+const TOOL_BUILDERS = [
+	buildTextToAvatarTool,
+	buildMeshForgeTool,
+	buildRigMeshTool,
+	buildEnsSnsResolveTool,
+	buildAgentDelegateActionTool,
+	buildSentimentPulseTool,
+	buildPoseSeedTool,
+	buildPumpSnapshotTool,
+	buildAgentReputationTool,
+	buildVanityGrinderTool,
+	buildAgenCListTasksTool,
+	buildAgenCGetTaskTool,
+	buildAgenCGetAgentTool,
+	buildAixbtIntelTool,
+	buildAixbtProjectsTool,
+];
+
+/**
+ * Build every tool descriptor. Side-effect-free w.r.t. payment env and the
+ * stdio transport — safe to call from tests to enumerate the tool surface.
+ *
+ * @returns {Promise<Array<{name:string,title:string,description:string,inputSchema:object,annotations:object,handler:Function}>>}
+ */
+export async function buildTools() {
+	return Promise.all(TOOL_BUILDERS.map((build) => build()));
+}
+
+/**
+ * Construct and return a fully-registered McpServer WITHOUT connecting any
+ * transport and WITHOUT requiring runtime payment env. Tool registration
+ * (names/descriptions/schemas) works with no secrets; only an actual paid tool
+ * invocation requires MCP_SVM_PAYMENT_ADDRESS.
+ *
+ * @returns {Promise<McpServer>}
+ */
+export async function buildServer() {
+	const server = new McpServer(
+		{
+			// Stable MCP identity — matches the bin name and the registry
+			// mcpName suffix (io.github.nirholas/3d-agent-mcp). Deliberately
+			// NOT derived from the scoped npm package name.
+			name: '3d-agent-mcp',
+			version: PKG_VERSION,
+		},
+		{
+			// Declare full tools capability so clients on the strict MCP 2025-06-18
+			// spec know we don't push tools/list_changed notifications (our tool
+			// surface is fixed per-process). `resources` + `logging` left
+			// undeclared because we don't ship resource or logging APIs over this
+			// transport; declaring them empty would mislead clients into calling
+			// resources/list and getting a method-not-found.
+			capabilities: { tools: { listChanged: false } },
+			instructions: SERVER_INSTRUCTIONS,
+		},
+	);
+
+	const tools = await buildTools();
+	for (const t of tools) {
+		server.registerTool(
+			t.name,
+			{
+				title: t.title,
+				description: t.description,
+				inputSchema: t.inputSchema,
+				// MCP ToolAnnotations (readOnlyHint / destructiveHint /
+				// idempotentHint / openWorldHint) — lets clients gate
+				// confirmation prompts per tool instead of treating every call
+				// as a destructive write.
+				annotations: t.annotations,
+			},
+			t.handler,
+		);
+	}
+
+	return server;
+}
+
+/**
+ * Connect the server to stdio. Runs only as the process entry point. Eagerly
+ * warms the shared x402 resource server so the first paid call doesn't pay the
+ * /supported fetch cost, then connects the StdioServerTransport.
+ */
+async function main() {
+	// Fail fast: a running server that can't receive payments is useless. This
+	// is the ONLY startup env gate — it does not run during buildServer()/tests.
+	assertPaymentEnv();
+
+	// Force the shared x402 resource server to initialize before any tool is
+	// invoked — this fetches /supported from each facilitator so verify + settle
+	// don't pay that cost on the first paid call.
+	await getResourceServer();
+	const initErr = getLastFacilitatorInitError();
+	if (initErr) {
+		console.error(`[mcp-server] facilitator init returned warnings: ${initErr.message}`);
+	}
+
+	const server = await buildServer();
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	// Log to stderr so the stdout channel stays clean for MCP JSON-RPC frames.
+	console.error('[mcp-server] ready — paid tools registered over stdio');
+}
+
+// Run the stdio boot ONLY when this file is the process entry point. Importing
+// the module for tests (or to reuse buildServer/buildTools) must NOT connect a
+// transport or require payment env.
+//
+// The entry path is compared both directly and via its realpath: when launched
+// through the npm bin (`node_modules/.bin/3d-agent-mcp`, a symlink to this file),
+// process.argv[1] is the symlink while import.meta.url is the resolved target —
+// so a direct compare alone would wrongly treat the bin launch as "imported" and
+// never start the server.
+function isProcessEntryPoint() {
+	const argvPath = process.argv[1];
+	if (!argvPath) return false;
+	if (import.meta.url === pathToFileURL(argvPath).href) return true;
+	try {
+		return import.meta.url === pathToFileURL(realpathSync(argvPath)).href;
+	} catch {
+		return false;
+	}
+}
+const isEntryPoint = isProcessEntryPoint();
+
+if (isEntryPoint) {
+	main().catch((err) => {
+		// One clean, actionable line to stderr — never a raw multi-line stack.
+		console.error(`mcp-server: ${err?.message || err}`);
+		process.exit(1);
+	});
+}

package/src/lib/evm-rpc.js

@@ -0,0 +1,130 @@
+// Multi-endpoint EVM RPC with automatic failover + bounded timeouts.
+//
+// `agent_reputation` and `ens_sns_resolve` previously talked to a SINGLE,
+// hard-coded public RPC per chain with NO timeout and NO backup — a public
+// endpoint rate-limiting or stalling took the whole tool down (and, with no
+// timeout, could hang a paid call indefinitely).
+//
+// This module returns an ethers provider backed by a prioritized list of
+// endpoints. With more than one endpoint it builds a `FallbackProvider` with
+// `quorum: 1`, so the highest-priority healthy endpoint answers and a failure
+// transparently falls over to the next. Every endpoint carries a request
+// timeout, so no RPC call can hang without bound.
+//
+// Endpoint precedence (highest first):
+//   1. caller-supplied override URLs (e.g. MCP_AGENT_REP_RPC_<id> / MCP_ENS_RPC_URL)
+//   2. MCP_EVM_RPC_<chainId>  — comma-separated env list
+//   3. built-in public endpoints for that chain
+
+import { FallbackProvider, FetchRequest, JsonRpcProvider, Network } from 'ethers';
+
+// Built-in redundancy: at least two public endpoints per supported chain so a
+// single provider outage is survivable out of the box. Operators who need
+// guaranteed throughput should pin dedicated endpoints via MCP_EVM_RPC_<id>.
+const BUILTIN_RPCS = {
+	1: [
+		'https://eth.llamarpc.com',
+		'https://ethereum-rpc.publicnode.com',
+		'https://cloudflare-eth.com',
+	],
+	8453: [
+		'https://mainnet.base.org',
+		'https://base-rpc.publicnode.com',
+		'https://base.llamarpc.com',
+	],
+	42161: ['https://arb1.arbitrum.io/rpc', 'https://arbitrum-one-rpc.publicnode.com'],
+	10: ['https://mainnet.optimism.io', 'https://optimism-rpc.publicnode.com'],
+	137: ['https://polygon-rpc.com', 'https://polygon-bor-rpc.publicnode.com'],
+	56: ['https://bsc-dataseed1.binance.org', 'https://bsc-rpc.publicnode.com'],
+	43114: [
+		'https://api.avax.network/ext/bc/C/rpc',
+		'https://avalanche-c-chain-rpc.publicnode.com',
+	],
+	42220: ['https://forno.celo.org'],
+	59144: ['https://rpc.linea.build'],
+	534352: ['https://rpc.scroll.io'],
+};
+
+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 RPC endpoint list for a chain. Caller overrides come
+ * first, then the MCP_EVM_RPC_<chainId> env list, then the built-in set.
+ *
+ * @param {number} chainId
+ * @param {string[]} [overrides]  caller-supplied URLs to try first
+ * @returns {string[]}
+ */
+export function getEvmRpcUrls(chainId, overrides = []) {
+	const fromEnv = (process.env[`MCP_EVM_RPC_${chainId}`] || '')
+		.split(',')
+		.map((s) => s.trim())
+		.filter(Boolean);
+	const builtin = BUILTIN_RPCS[chainId] || [];
+	const ordered = dedupe([...(overrides || []), ...fromEnv, ...builtin]);
+	if (!ordered.length) {
+		throw new Error(`evm-rpc: no endpoints known for chainId ${chainId}`);
+	}
+	return ordered;
+}
+
+function timedRequest(url, timeoutMs) {
+	const req = new FetchRequest(url);
+	req.timeout = timeoutMs;
+	return req;
+}
+
+/**
+ * Build an ethers provider for a chain with endpoint failover.
+ *
+ * With a single endpoint, returns a plain timed `JsonRpcProvider`. With more
+ * than one, returns a `FallbackProvider` (quorum 1) that answers from the
+ * first healthy endpoint and fails over on error — so the multi-read callers
+ * (resolveAgentId + identity + reputation + events) keep using one provider
+ * object while every underlying call is redundant and bounded.
+ *
+ * @param {number} chainId
+ * @param {object} [opts]
+ * @param {string[]} [opts.overrides]   caller-supplied URLs to try first
+ * @param {number} [opts.timeoutMs=12000]
+ * @returns {import('ethers').AbstractProvider}
+ */
+export function makeEvmProvider(chainId, opts = {}) {
+	const { overrides = [], timeoutMs = 12_000 } = opts;
+	const urls = getEvmRpcUrls(chainId, overrides);
+	const network = Network.from(chainId);
+
+	if (urls.length === 1) {
+		return new JsonRpcProvider(timedRequest(urls[0], timeoutMs), network, {
+			staticNetwork: network,
+		});
+	}
+
+	const configs = urls.map((url, i) => ({
+		provider: new JsonRpcProvider(timedRequest(url, timeoutMs), network, {
+			staticNetwork: network,
+		}),
+		priority: i + 1, // lower number = tried first
+		// Move on to the next endpoint if this one stalls, well before the hard
+		// per-request timeout, so failover is responsive.
+		stallTimeout: Math.min(timeoutMs, 3_000),
+		weight: 1,
+	}));
+
+	// quorum 1: a single endpoint's answer is authoritative; the rest are pure
+	// failover, not a consensus requirement.
+	return new FallbackProvider(configs, network, { quorum: 1 });
+}
+
+export { BUILTIN_RPCS };