Skip to content

Open-source platform for 3D AI agents. Turn text or a photo into a rigged, animated GLB avatar, give it an LLM brain, memory and a wallet, and embed it anywhere with one web component. Remote MCP server, x402 payments, Three.js, browser-native.

15.1 KB
Raw Blame
// three:// MCP resources (api/_mcp/resources.js): URI routing, access rules,
// the per-server subsets, the read_resource tool on every server, and the
// subscribe -> poll -> notifications/resources/updated path a wallet transfer
// drives.
//
// The database is an in-memory stand-in that understands exactly the queries
// these cases issue; the Solana RPC is replaced by a connection whose latest
// signature the test moves, which is what a real transfer does.

import { describe, it, expect, vi, beforeEach } from 'vitest';

const OWNER = '11111111-1111-4111-8111-111111111111';
const STRANGER = '22222222-2222-4222-8222-222222222222';
const AGENT = '33333333-3333-4333-8333-333333333333';
// The System Program id: a valid public key that is nobody's wallet.
const ADDRESS = '11111111111111111111111111111111';

const db = { subs: [], nextId: 1, launches: [] };

function agentRow() {
	return {
		id: AGENT,
		user_id: OWNER,
		name: 'Scout',
		description: 'test agent',
		persona_prompt: 'calm',
		skills: ['greet'],
		meta: { solana_address: ADDRESS, spend_limits: { daily_usd: 50 } },
		avatar_id: null,
		is_published: false,
		created_at: '2026-09-01T00:00:00.000Z',
		updated_at: '2026-09-01T00:00:00.000Z',
	};
}

vi.mock('../api/_lib/db.js', () => ({
	sql: vi.fn(async (strings, ...values) => {
		const q = strings.join('?').replace(/\s+/g, ' ').trim();
		if (q.startsWith('SELECT id, user_id, name, description, persona_prompt')) {
			return values[0] === AGENT ? [agentRow()] : [];
		}
		if (q.includes('FROM agent_identities ai LEFT JOIN avatars av')) {
			return values[0] === OWNER
				? [{ id: AGENT, name: 'Scout', description: null, is_published: false, created_at: '2026-09-01', solana_address: ADDRESS, model: null, avatar_id: null }]
				: [];
		}
		if (q.includes('FROM pump_agent_mints pam')) return db.launches;
		if (q.startsWith('SELECT count(*)::int AS n FROM mcp_resource_subscriptions')) {
			const [server, key, uri] = values;
			return [{ n: db.subs.filter((s) => s.server === server && s.subscriber_key === key && s.uri !== uri).length }];
		}
		if (q.startsWith('INSERT INTO mcp_resource_subscriptions')) {
			const [server, key, userId, uri, fingerprint] = values;
			const existing = db.subs.find((s) => s.server === server && s.subscriber_key === key && s.uri === uri);
			if (existing) existing.fingerprint = fingerprint;
			else db.subs.push({ id: db.nextId++, server, subscriber_key: key, user_id: userId, uri, fingerprint });
			return [];
		}
		if (q.startsWith('SELECT id, uri, fingerprint FROM mcp_resource_subscriptions')) {
			const [server, key] = values;
			return db.subs.filter((s) => s.server === server && s.subscriber_key === key);
		}
		if (q.startsWith('UPDATE mcp_resource_subscriptions SET fingerprint')) {
			const [fingerprint, id] = values;
			db.subs.find((s) => s.id === id).fingerprint = fingerprint;
			return [];
		}
		if (q.startsWith('UPDATE mcp_resource_subscriptions SET checked_at')) return [];
		if (q.startsWith('DELETE FROM mcp_resource_subscriptions WHERE id')) {
			db.subs = db.subs.filter((s) => s.id !== values[0]);
			return [];
		}
		if (q.startsWith('DELETE FROM mcp_resource_subscriptions WHERE server')) {
			const [server, key, uri] = values;
			db.subs = db.subs.filter((s) => !(s.server === server && s.subscriber_key === key && (uri === undefined || s.uri === uri)));
			return [];
		}
		if (q.startsWith("SELECT meta->>'solana_address' AS address")) return [{ address: ADDRESS }];
		// No stored override: the free-tier allowance falls back to its defaults.
		if (q.startsWith('SELECT value FROM app_settings WHERE key')) return [];
		throw new Error(`unexpected query in test: ${q.slice(0, 120)}`);
	}),
	isDbUnavailableError: () => false,
	isDbCapacityError: () => false,
}));

const rpc = { signature: 'sig-before' };
vi.mock('../api/_lib/agent-pumpfun.js', () => ({
	solanaConnection: () => ({
		getSignaturesForAddress: vi.fn(async () => [{ signature: rpc.signature }]),
	}),
}));

const invalidated = [];
vi.mock('../api/_lib/balances.js', () => ({
	invalidateBalances: vi.fn(async (x) => invalidated.push(x)),
	getBalances: vi.fn(async () => ({ native: { amount: 1.5, usd: 300 }, tokens: [] })),
	walletUsdTotal: () => 300,
}));

const resources = await import('../api/_mcp/resources.js');
const { TOOL_CATALOG: mainCatalog } = await import('../api/_mcp/catalog.js');
const { TOOL_CATALOG: agentCatalog } = await import('../api/_mcpagent/catalog.js');
const { TOOL_CATALOG: studioCatalog } = await import('../api/_mcp3d/catalog.js');
const { TOOL_CATALOG: bazaarCatalog } = await import('../api/_mcpbazaar/catalog.js');

const CATALOGS = { mcp: mainCatalog, 'mcp-agent': agentCatalog, 'mcp-3d': studioCatalog, 'mcp-bazaar': bazaarCatalog };

const owner = { userId: OWNER, scope: 'agents:read wallet:read', source: 'oauth', clientId: 'client-a' };
const stranger = { userId: STRANGER, scope: 'agents:read wallet:read', source: 'oauth', clientId: 'client-b' };
const anon = { userId: null, scope: '', source: 'free' };
const req = { headers: {} };

beforeEach(() => {
	db.subs = [];
	db.nextId = 1;
	db.launches = [];
	rpc.signature = 'sig-before';
	invalidated.length = 0;
});

describe('resource registry', () => {
	it('every hosted server exposes resources and publishes read_resource', () => {
		for (const server of resources.RESOURCE_SERVERS) {
			expect(resources.resourcesFor(server).length).toBeGreaterThan(0);
			expect(CATALOGS[server].map((t) => t.name)).toContain('read_resource');
		}
	});

	it('covers every resource the spec requires', () => {
		const all = new Set(resources.RESOURCES.map((r) => r.uri || r.uriTemplate));
		for (const uri of [
			'three://me',
			'three://agents',
			'three://agents/{agentId}',
			'three://agents/{agentId}/wallet',
			'three://agents/{agentId}/usage',
			'three://agents/{agentId}/chat',
			'three://agents/{agentId}/runs',
			'three://agents/{agentId}/runs/{runId}',
			'three://agents/{agentId}/orders',
			'three://agents/{agentId}/dca',
			'three://agents/{agentId}/intents',
			'three://agents/{agentId}/earnings',
			'three://marketplace',
			'three://models',
			'three://wallets',
			'three://launches',
			'three://x402/services',
			'three://assets/{id}',
		]) {
			expect(all, uri).toContain(uri);
		}
		expect(resources.resourcesFor('mcp-3d').map((r) => r.key)).toContain('asset');
		expect(resources.resourcesFor('mcp').map((r) => r.key)).not.toContain('asset');
	});

	it('names a tool equivalent in every description, and only tools the server has', () => {
		for (const server of resources.RESOURCE_SERVERS) {
			const names = new Set(CATALOGS[server].map((t) => t.name));
			for (const def of resources.resourcesFor(server)) {
				expect(resources.describeFor(def, server)).toContain('read_resource');
				const dedicated = def.tools?.[server];
				if (dedicated) expect(names, `${server} ${dedicated}`).toContain(dedicated);
			}
		}
	});
});

describe('URI matching', () => {
	it('matches templates, captures params and reads the format flag', () => {
		const m = resources.matchResource('mcp', `three://agents/${AGENT}/wallet?format=markdown`);
		expect(m.def.key).toBe('wallet');
		expect(m.params).toEqual({ agentId: AGENT });
		expect(m.format).toBe('markdown');
		expect(m.path).toBe(`three://agents/${AGENT}/wallet`);
	});

	it('rejects foreign schemes, unknown paths and resources another server owns', () => {
		expect(resources.matchResource('mcp', 'https://three.ws/api/mcp')).toBeNull();
		expect(resources.matchResource('mcp', 'three://nothing/here')).toBeNull();
		expect(resources.matchResource('mcp-bazaar', 'three://agents')).toBeNull();
		expect(resources.matchResource('mcp', `three://assets/${AGENT}`)).toBeNull();
	});
});

describe('resources/read access', () => {
	it('refuses account data to an anonymous caller with a sign-in hint', async () => {
		await expect(
			resources.handleResourceMethod('mcp', 'resources/read', { uri: 'three://me' }, anon, req),
		).rejects.toMatchObject({ code: -32001 });
	});

	it('refuses a caller without an agents scope', async () => {
		const noScope = { ...owner, scope: 'avatars:read' };
		await expect(
			resources.handleResourceMethod('mcp', 'resources/read', { uri: 'three://agents' }, noScope, req),
		).rejects.toMatchObject({ code: -32001, data: { required_scopes: ['agents:read', 'agents:write'] } });
	});

	it("answers someone else's agent exactly like a missing one", async () => {
		await expect(
			resources.handleResourceMethod('mcp', 'resources/read', { uri: `three://agents/${AGENT}/wallet` }, stranger, req),
		).rejects.toMatchObject({ code: -32002 });
	});

	it('reads JSON by default and markdown on request', async () => {
		db.launches = [
			{ mint: 'THREEsynthetic2222', name: 'Test', symbol: 'TST', network: 'mainnet', created_at: '2026-09-02', quote_mint: null, agent_id: AGENT, agent_name: 'Scout' },
		];
		const json = await resources.handleResourceMethod('mcp', 'resources/read', { uri: 'three://launches' }, owner, req);
		expect(json.contents[0].mimeType).toBe('application/json');
		expect(JSON.parse(json.contents[0].text)).toMatchObject({ count: 1, launches: [{ symbol: 'TST' }] });

		const md = await resources.handleResourceMethod('mcp', 'resources/read', { uri: 'three://launches?format=markdown' }, owner, req);
		expect(md.contents[0].mimeType).toBe('text/markdown');
		expect(md.contents[0].text).toMatch(/^# Your token launches/);
		expect(md.contents[0].text).toContain('| mint | name | symbol |');
	});

	it('prices models through the model a key routes to, and free models at zero', async () => {
		const out = await resources.handleResourceMethod('mcp', 'resources/read', { uri: 'three://models' }, anon, req);
		const { agent_models, chat_models, models, free_tier } = JSON.parse(out.contents[0].text);
		// The picker catalog and the free allowance ride along, the same payload GET /api/v1/models carries.
		expect(Array.isArray(models)).toBe(true);
		expect(models.length).toBeGreaterThan(0);
		expect(free_tier.daily_messages).toBeGreaterThan(0);
		const byId = new Map(agent_models.map((m) => [m.id, m]));
		// ibm-granite names no priced model; its OpenRouter route does.
		expect(byId.get('ibm-granite').price_usd_per_mtok).toEqual([0.05, 0.1]);
		expect(byId.get('claude-opus-5').price_usd_per_mtok).toEqual([5, 25]);
		for (const m of [...agent_models, ...chat_models].filter((x) => x.free)) {
			expect(m.price_usd_per_mtok, m.id).toEqual([0, 0]);
		}
	});

	it('hides internal errors behind a generic message with a reference', async () => {
		db.launches = null;
		const err = await resources
			.handleResourceMethod('mcp', 'resources/read', { uri: 'three://launches' }, owner, req)
			.catch((e) => e);
		expect(err.code).toBe(-32603);
		expect(err.message).toMatch(/ref [0-9a-f]{8}/);
	});
});

describe('resources/list', () => {
	it('lists only public resources for an anonymous caller', async () => {
		const out = await resources.handleResourceMethod('mcp', 'resources/list', {}, anon, req);
		expect(out.resources.map((r) => r.uri).sort()).toEqual(['three://marketplace', 'three://models', 'three://x402/services']);
	});

	it("expands per-agent resources for the caller's agents", async () => {
		const out = await resources.handleResourceMethod('mcp', 'resources/list', {}, owner, req);
		const uris = out.resources.map((r) => r.uri);
		expect(uris).toContain(`three://agents/${AGENT}/wallet`);
		expect(uris).toContain(`three://agents/${AGENT}/usage`);
		expect(out.resources.every((r) => r.mimeType === 'application/json')).toBe(true);
	});

	it('serves templates per server', async () => {
		const out = await resources.handleResourceMethod('mcp-3d', 'resources/templates/list', {}, anon, req);
		expect(out.resourceTemplates.map((t) => t.uriTemplate)).toContain('three://assets/{id}');
	});
});

describe('read_resource tool', () => {
	it('returns the resource index with no uri', async () => {
		const out = await resources.readResourceToolResult('mcp-bazaar', {}, anon, req);
		expect(out.structuredContent.resources.map((r) => r.uri)).toContain('three://x402/services');
	});

	it('reports a missing sign-in as a tool error, not a protocol error', async () => {
		const out = await resources.readResourceToolResult('mcp', { uri: 'three://wallets' }, anon, req);
		expect(out.isError).toBe(true);
		expect(out.content[0].text).toMatch(/sign in/);
	});
});

describe('subscriptions', () => {
	const walletUri = `three://agents/${AGENT}/wallet`;

	it('needs a signed-in client', async () => {
		await expect(
			resources.handleResourceMethod('mcp-agent', 'resources/subscribe', { uri: walletUri }, anon, req),
		).rejects.toMatchObject({ code: -32001 });
	});

	it('notifies once after a transfer moves the latest signature, then stays quiet', async () => {
		await resources.handleResourceMethod('mcp-agent', 'resources/subscribe', { uri: walletUri }, owner, req);
		expect(db.subs).toHaveLength(1);
		expect(db.subs[0].subscriber_key).toBe(`user:${OWNER}:client:client-a`);

		const sent = [];
		await resources.pollSubscriptions('mcp-agent', owner, req, (m) => sent.push(m));
		expect(sent).toHaveLength(0);

		rpc.signature = 'sig-after-transfer';
		await resources.pollSubscriptions('mcp-agent', owner, req, (m) => sent.push(m));
		expect(sent).toEqual([{ jsonrpc: '2.0', method: 'notifications/resources/updated', params: { uri: walletUri } }]);
		expect(invalidated).toEqual([{ chain: 'solana', address: ADDRESS }]);

		await resources.pollSubscriptions('mcp-agent', owner, req, (m) => sent.push(m));
		expect(sent).toHaveLength(1);
	});

	it('keys on Mcp-Session-Id when the client sends one', () => {
		expect(resources.subscriberKey(owner, { headers: { 'mcp-session-id': 'abc' } })).toBe('session:abc');
	});

	it('unsubscribe and session teardown remove subscriptions', async () => {
		await resources.handleResourceMethod('mcp-agent', 'resources/subscribe', { uri: walletUri }, owner, req);
		await resources.handleResourceMethod('mcp-agent', 'resources/unsubscribe', { uri: walletUri }, owner, req);
		expect(db.subs).toHaveLength(0);

		await resources.handleResourceMethod('mcp-agent', 'resources/subscribe', { uri: walletUri }, owner, req);
		await resources.dropSubscriptions('mcp-agent', owner, req);
		expect(db.subs).toHaveLength(0);
	});

	it('drops a subscription whose resource is no longer readable', async () => {
		await resources.handleResourceMethod('mcp-agent', 'resources/subscribe', { uri: walletUri }, owner, req);
		db.subs[0].subscriber_key = resources.subscriberKey(stranger, req);
		await resources.pollSubscriptions('mcp-agent', stranger, req, () => {});
		expect(db.subs).toHaveLength(0);
	});
});

describe('dispatcher wiring', () => {
	it('advertises resource subscriptions and prompts on initialize', async () => {
		const { dispatch } = await import('../api/_mcpbazaar/dispatch.js');
		const out = await dispatch({ jsonrpc: '2.0', id: 1, method: 'initialize', params: {} }, anon, req);
		expect(out.result.capabilities.resources).toEqual({ subscribe: true, listChanged: false });
		expect(out.result.capabilities.prompts).toEqual({ listChanged: false });
	});

	it('treats resource and prompt discovery as free discovery, but not subscribe', async () => {
		const { isDiscoveryOnlyBatch } = await import('../api/_lib/mcp-batch-price.js');
		expect(isDiscoveryOnlyBatch([{ method: 'resources/list' }, { method: 'prompts/get' }])).toBe(true);
		expect(isDiscoveryOnlyBatch([{ method: 'resources/subscribe' }])).toBe(false);
	});
});