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.

7.6 KB
Raw Blame
// MCP client analytics against the REAL migration, in an in-process Postgres
// (PGlite): an initialize issues a session id and records the client, a
// tools/call that echoes the id is counted against that client, a call with
// no issued id lands on "unknown", and the report folds the daily rows the
// way the /mcp-clients board reads them.

import { readFileSync } from 'node:fs';
import { describe, it, expect, beforeEach, vi } from 'vitest';
import { PGlite } from '@electric-sql/pglite';

const dbState = { pg: null };

vi.mock('../api/_lib/db.js', () => {
	const sql = async (strings, ...values) => {
		const text = strings.reduce((acc, part, i) => acc + part + (i < values.length ? `$${i + 1}` : ''), '');
		const out = await dbState.pg.query(text, values);
		return out.rows;
	};
	return { sql, isDbUnavailableError: () => false, isDbCapacityError: () => false };
});

const analytics = await import('../api/_lib/mcp-client-analytics.js');

const MIGRATION = readFileSync(
	new URL('../api/_lib/migrations/20261008200000_mcp_client_analytics.sql', import.meta.url),
	'utf8',
);

function makeRes() {
	const h = {};
	return {
		setHeader(k, v) { h[k.toLowerCase()] = v; },
		getHeader(k) { return h[k.toLowerCase()]; },
		headers: h,
	};
}

const init = (name, version = '1.0.0') => ({
	jsonrpc: '2.0',
	id: 1,
	method: 'initialize',
	params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name, version } },
});
const call = (tool, id = 2) => ({ jsonrpc: '2.0', id, method: 'tools/call', params: { name: tool, arguments: { q: 'secret prompt text' } } });

beforeEach(async () => {
	dbState.pg = new PGlite();
	await dbState.pg.exec(MIGRATION);
	// Drain what an earlier test queued without flushing, then start clean.
	await analytics.flushMcpClientEvents();
	await dbState.pg.exec('truncate mcp_client_sessions, mcp_client_daily');
});

describe('client name normalization', () => {
	it('trims, lowercases, strips control characters and caps the length', () => {
		expect(analytics.normalizeClientName('  Claude-AI \n')).toBe('claude-ai');
		expect(analytics.normalizeClientName('x'.repeat(200))).toHaveLength(64);
		expect(analytics.normalizeClientName('')).toBe('unknown');
		expect(analytics.normalizeClientName(42)).toBe('unknown');
		expect(analytics.normalizeClientVersion(' 1.2.3\u0007 ')).toBe('1.2.3');
	});

	it('maps known clientInfo names to one family per client', () => {
		const fam = (n) => analytics.clientFamily(analytics.normalizeClientName(n));
		expect(fam('three-ws-connector-probe')).toBe('probe');
		expect(fam('claude-ai')).toBe('claude');
		expect(fam('claude-code')).toBe('claude-code');
		expect(fam('openai-mcp')).toBe('chatgpt');
		expect(fam('cursor-vscode')).toBe('cursor');
		expect(fam('Visual Studio Code')).toBe('vscode');
		expect(fam('Grok Bot')).toBe('grok');
		expect(fam('my-own-agent')).toBe('my-own-agent');
	});

	it('names the auth kind from the resolved principal and from headers', () => {
		expect(analytics.authKindOf({ source: 'oauth' })).toBe('oauth');
		expect(analytics.authKindOf({ source: 'apikey' })).toBe('key');
		expect(analytics.authKindOf({ source: 'x402' })).toBe('x402');
		expect(analytics.authKindOf({ source: 'free' })).toBe('anonymous');
		expect(analytics.authKindFromHeaders({ headers: { authorization: 'Bearer sk_live_abc' } })).toBe('key');
		expect(analytics.authKindFromHeaders({ headers: { authorization: 'Bearer eyJhbGciOi' } })).toBe('oauth');
		expect(analytics.authKindFromHeaders({ headers: { 'x-payment': 'e30=' } })).toBe('x402');
		expect(analytics.authKindFromHeaders({ headers: {} })).toBe('anonymous');
	});
});

describe('trackMcpRequest', () => {
	it('issues an exposed Mcp-Session-Id on initialize and nothing on other methods', () => {
		const res = makeRes();
		const sid = analytics.trackMcpRequest({ body: init('probe'), req: { headers: {} }, res, surface: 'mcp-studio' });
		expect(sid).toMatch(/^mcs_[0-9a-f-]{36}$/);
		expect(res.headers['mcp-session-id']).toBe(sid);
		expect(res.headers['access-control-expose-headers']).toContain('mcp-session-id');
		expect(analytics.isIssuedSessionId(sid)).toBe(true);

		const res2 = makeRes();
		expect(analytics.trackMcpRequest({ body: call('search_catalog'), req: { headers: {} }, res: res2, surface: 'mcp' })).toBeNull();
		expect(res2.headers['mcp-session-id']).toBeUndefined();
	});

	it('keeps the grk_ prefix the grok rate caps key on', () => {
		const res = makeRes();
		const sid = analytics.trackMcpRequest({ body: init('grok'), req: { headers: {} }, res, surface: 'mcp-grok', sessionPrefix: 'grk' });
		expect(sid).toMatch(/^grk_[0-9a-f-]{36}$/);
	});

	it('records the session, then counts echoed calls against its client', async () => {
		const res = makeRes();
		const sid = analytics.trackMcpRequest({
			body: init('  Three-WS-Connector-Probe ', '1.0.0'),
			req: { headers: {} },
			res,
			surface: 'mcp-studio',
			authKind: 'install',
		});
		await analytics.flushMcpClientEvents();
		for (const tool of ['search_catalog', 'search_catalog', 'getting_started']) {
			analytics.trackMcpRequest({ body: call(tool), req: { headers: { 'mcp-session-id': sid } }, res: makeRes(), surface: 'mcp-studio', authKind: 'install' });
		}
		const out = await analytics.flushMcpClientEvents();
		expect(out.failed).toBe(0);

		const { rows: [session] } = await dbState.pg.query('select * from mcp_client_sessions where session_id = $1', [sid]);
		expect(session).toMatchObject({
			surface: 'mcp-studio',
			client: 'probe',
			client_name: 'three-ws-connector-probe',
			client_version: '1.0.0',
			auth_kind: 'install',
			calls: 3,
			tool_calls: { search_catalog: 2, getting_started: 1 },
		});

		const { rows: daily } = await dbState.pg.query('select * from mcp_client_daily');
		expect(daily).toHaveLength(1);
		expect(daily[0]).toMatchObject({ client: 'probe', sessions: 1, calls: 3, tools: { search_catalog: 2, getting_started: 1 } });
	});

	it('never stores a request body or a tool argument', async () => {
		const res = makeRes();
		const sid = analytics.trackMcpRequest({ body: [init('claude-ai'), call('text_to_3d', 3)], req: { headers: {} }, res, surface: 'mcp-3d', auth: { source: 'oauth' } });
		await analytics.flushMcpClientEvents();
		const { rows } = await dbState.pg.query('select row_to_json(s)::text as j from mcp_client_sessions s');
		expect(rows[0].j).not.toContain('secret prompt text');
		const { rows: [s] } = await dbState.pg.query('select calls, auth_kind from mcp_client_sessions where session_id = $1', [sid]);
		// The batch opened the session and called a tool in one request.
		expect(s).toEqual({ calls: 1, auth_kind: 'oauth' });
	});

	it('counts a call with no issued session id under "unknown"', async () => {
		analytics.trackMcpRequest({ body: call('getting_started'), req: { headers: { 'mcp-session-id': 'forged-id' } }, res: makeRes(), surface: 'mcp', auth: { source: 'x402' } });
		await analytics.flushMcpClientEvents();
		const { rows } = await dbState.pg.query('select client, client_name, auth_kind, calls, sessions, tools from mcp_client_daily');
		expect(rows).toEqual([{ client: 'unknown', client_name: 'unknown', auth_kind: 'x402', calls: 1, sessions: 0, tools: { getting_started: 1 } }]);
	});

	it('folds invented tool names past 200 into "(other)"', async () => {
		const many = Object.fromEntries(Array.from({ length: 200 }, (_, i) => [`t${i}`, 1]));
		const { rows: [r] } = await dbState.pg.query('select mcp_tool_count_add($1::jsonb, $2, 1) as j', [JSON.stringify(many), 'brand_new']);
		expect(r.j['(other)']).toBe(1);
		expect(r.j.brand_new).toBeUndefined();
		const { rows: [r2] } = await dbState.pg.query('select mcp_tool_count_add($1::jsonb, $2, 4) as j', [JSON.stringify(many), 't7']);
		expect(r2.j.t7).toBe(5);
	});
});