@pixlcore/xycli 1.1.1 → 1.2.1

package/test/mcp-stdio-unit.test.js

@@ -0,0 +1,194 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('node:http');
+const { spawnSync } = require('node:child_process');
+const { httpRPC, stdioClient } = require('./helpers/mcp.js');
+
+test('STDIO uses the real CLI and SDK with protocol-only stdout and clean EOF', async t => {
+	let calls = 0;
+	const backend = http.createServer((request, response) => {
+		calls++;
+		assert.equal(request.headers['x-api-key'], 'fixture-key');
+		assert.ok(request.url.startsWith('/api/app/get_event/v1'));
+		response.setHeader('Content-Type', 'application/json');
+		response.end(JSON.stringify({ code: 0, event: { id: 'fixture', revision: 2 } }));
+	});
+	await new Promise(resolve => backend.listen(0, '127.0.0.1', resolve));
+	t.after(() => new Promise(resolve => { backend.close(resolve); backend.closeAllConnections(); }));
+	const client = stdioClient(t, { XYOPS_BASE_URL: 'http://127.0.0.1:' + backend.address().port, XYOPS_API_KEY: 'fixture-key', XYOPS_RETRIES: '4' }, ['mcp', 'stdio', '--verbose', '--debug', '--read-only']);
+	assert.ok((await client.initialize()).result);
+	const listing = await client.request('tools/list');
+	assert.equal(listing.result.tools.length, 8);
+	assert.equal((await client.call('get_event', { id: 'fixture' })).result.structuredContent.event.revision, 2);
+	assert.equal(calls, 1);
+	const rejected = await client.call('run_event', { id: 'fixture' });
+	assert.ok(rejected.error || rejected.result.isError);
+	assert.equal(calls, 1);
+	client.child.stdin.end();
+	const [code] = await client.exit;
+	assert.equal(code, 0);
+	assert.ok(client.lines.every(line => JSON.parse(line).jsonrpc === '2.0'));
+	assert.ok(!client.stderr().includes('fixture-key'));
+});
+
+test('named HTTP options and local help do not contact xyOps', () => {
+	for (const args of [['mcp', 'serve', '--help'], ['mcp', '--help']]) {
+		const response = spawnSync(process.execPath, ['index.js', ...args], { encoding: 'utf8', env: { ...process.env, XYOPS_API_KEY: '', XYOPS_BASE_URL: '' } });
+		assert.equal(response.status, 0);
+		assert.match(response.stdout, /--port 8080/);
+	}
+	const response = spawnSync(process.execPath, ['index.js', 'mcp', 'serve', '8080'], { encoding: 'utf8' });
+	assert.equal(response.status, 1);
+	assert.equal(response.stdout, '');
+	assert.match(response.stderr, /--port/);
+});
+
+for (const { host, urlHost } of [{ host: '127.0.0.1', urlHost: '127.0.0.1' }, { host: '::1', urlHost: '[::1]' }]) {
+	test('HTTP CLI starts and shuts down on ' + host, { timeout: 15000 }, async t => {
+		// Reserve an available port before launching the actual CLI process. Tool
+		// calls use the real SDK with no process-wide API key configured.
+		const backend = http.createServer((request, response) => {
+			response.setHeader('Content-Type', 'application/json');
+			const id = new URL(request.url, 'http://fixture').searchParams.get('id');
+			assert.equal(request.headers['x-api-key'], id + '-key');
+			response.end(JSON.stringify({ code: 0, event: { id } }));
+		});
+		await new Promise(resolve => backend.listen(0, '127.0.0.1', resolve));
+		t.after(() => new Promise(resolve => { backend.close(resolve); backend.closeAllConnections(); }));
+		const reservation = http.createServer();
+		try {
+			await new Promise((resolve, reject) => {
+				reservation.once('error', reject);
+				reservation.listen(0, host, resolve);
+			});
+		}
+		catch (err) {
+			// Some test hosts have IPv6 disabled. Skip only that explicit case.
+			if (host === '::1' && ['EADDRNOTAVAIL', 'EAFNOSUPPORT'].includes(err.code)) return t.skip('IPv6 loopback unavailable');
+			throw err;
+		}
+		const port = reservation.address().port;
+		await new Promise(resolve => reservation.close(resolve));
+		const client = stdioClient(t, {
+			XYOPS_BASE_URL: 'http://127.0.0.1:' + backend.address().port, XYOPS_API_KEY: '',
+			XYOPS_MCP: JSON.stringify({ host: '127.0.0.1' })
+		}, ['mcp', 'serve', '--host', host, '--port', String(port), '--read-only']);
+		await new Promise((resolve, reject) => {
+			const timer = setTimeout(() => reject(new Error('HTTP startup timeout: ' + client.stderr())), 10000);
+			client.child.stderr.on('data', () => {
+				if (client.stderr().includes('Listening at ')) { clearTimeout(timer); resolve(); }
+			});
+			client.exit.then(() => { clearTimeout(timer); reject(new Error('CLI exited before startup: ' + client.stderr())); });
+		});
+		const url = 'http://' + urlHost + ':' + port + '/mcp';
+		assert.ok(client.stderr().includes('Listening at ' + url));
+		const listing = await httpRPC(url, 'tools/list', {}, {
+			modern: true, headers: { Authorization: 'Bearer fixture-token' }
+		});
+		assert.equal(listing.result.tools.length, 8);
+		assert.equal((await fetch(url)).status, 401);
+		// Binding IPv6 must not weaken the Host allowlist.
+		const rejectedHost = await new Promise((resolve, reject) => {
+			const req = http.get(url, { headers: { Host: 'evil.example', Authorization: 'Bearer fixture-key' } }, response => {
+				response.resume();
+				resolve(response.statusCode);
+			});
+			req.on('error', reject);
+		});
+		assert.equal(rejectedHost, 403);
+		const replies = await Promise.all(['first', 'second'].map((id, index) => httpRPC(url, 'tools/call', {
+			name: 'get_event', arguments: { id }
+		}, { modern: !!index, headers: { Authorization: 'Bearer ' + id + '-key' } })));
+		assert.deepEqual(replies.map(reply => reply.result.structuredContent.event.id), ['first', 'second']);
+		assert.equal(client.child.kill('SIGTERM'), true);
+		const [code, signal] = await client.exit;
+		if (process.platform === 'win32') {
+			// Windows force-terminates a child sent SIGTERM, without running its
+			// signal handler. Node reports signal termination, not exit code 0.
+			assert.equal(code, null);
+			assert.equal(signal, 'SIGTERM');
+		}
+		else {
+			// POSIX delivers SIGTERM to the CLI's graceful shutdown handler.
+			assert.equal(code, 0);
+			assert.equal(signal, null);
+		}
+		assert.deepEqual(client.lines, []);
+	});
+}
+
+test('ticket and monitoring tools use real SDK routes and validated STDIO inputs', async t => {
+	const requests = [];
+	const backend = http.createServer((request, response) => {
+		let body = '';
+		request.on('data', chunk => { body += chunk; });
+		request.on('end', () => {
+			const url = new URL(request.url, 'http://fixture');
+			const name = url.pathname.split('/')[3];
+			const params = body ? JSON.parse(body) : Object.fromEntries(url.searchParams);
+			requests.push({ name, method: request.method, params });
+			assert.equal(request.headers['x-api-key'], 'fixture-key');
+			assert.match(request.headers['user-agent'], /xyOps MCP/);
+			let result = { code: 0 };
+			switch (name) {
+				case 'create_ticket':
+				case 'update_ticket':
+				case 'add_ticket_change':
+					result.ticket = { id: 't1', num: 1, subject: 'Test', status: params.status || 'open', changes: params.change ? [{ ...params.change, id: 'c1', username: 'fixture-key', date: 123 }] : [] };
+					break;
+				case 'delete_ticket': break;
+				case 'create_snapshot':
+				case 'create_group_snapshot': result.id = 'sn1'; break;
+				case 'get_active_servers': result.rows = [{ id: 's1', hostname: 'worker', groups: ['main'], enabled: true }]; result.list = { length: 1 }; break;
+				case 'search_alerts':
+				case 'search_snapshots': result.rows = [{ id: 'record1' }]; result.list = { length: 1 }; break;
+				default: result = { code: 'test', description: 'Unexpected route ' + name };
+			}
+			response.setHeader('Content-Type', 'application/json');
+			response.end(JSON.stringify(result));
+		});
+	});
+	await new Promise(resolve => backend.listen(0, '127.0.0.1', resolve));
+	t.after(() => new Promise(resolve => { backend.close(resolve); backend.closeAllConnections(); }));
+	const client = stdioClient(t, { XYOPS_BASE_URL: 'http://127.0.0.1:' + backend.address().port, XYOPS_API_KEY: 'fixture-key', XYOPS_MCP: '{}' });
+	await client.initialize();
+	const listing = await client.request('tools/list');
+	assert.equal(listing.result.tools.length, 17);
+	const invoke = async (name, args) => {
+		const reply = await client.call(name, args);
+		assert.ok(reply.result && !reply.result.isError, JSON.stringify(reply));
+		return reply.result.structuredContent;
+	};
+	assert.equal((await invoke('create_ticket', { ticket: { subject: 'Test', body: '**Markdown**' } })).ticket.id, 't1');
+	assert.deepEqual(requests.at(-1), { name: 'create_ticket', method: 'POST', params: { subject: 'Test', body: '**Markdown**' } });
+	await invoke('update_ticket', { id: 't1', changes: { status: 'closed', assignees: [] } });
+	assert.deepEqual(requests.at(-1).params, { id: 't1', status: 'closed', assignees: [] });
+	assert.equal((await invoke('comment_ticket', { id: 't1', body: 'Comment' })).comment.username, 'fixture-key');
+	assert.deepEqual(requests.at(-1).params, { id: 't1', change: { type: 'comment', body: 'Comment' } });
+	assert.equal((await invoke('delete_ticket', { id: 't1' })).deleted, true);
+	await invoke('search_alerts', { query: 'active:true server:s1', limit: 2 });
+	assert.deepEqual(requests.at(-1), { name: 'search_alerts', method: 'GET', params: { query: 'active:true server:s1', offset: '0', limit: '2', sort_by: '_id', sort_dir: '-1' } });
+	await invoke('search_snapshots', {});
+	assert.ok(!('verbose' in requests.at(-1).params));
+	await invoke('search_snapshots', { verbose: true, limit: 1 });
+	assert.equal(requests.at(-1).params.verbose, '1');
+	assert.equal((await invoke('list_servers', { group: 'main' })).rows[0].id, 's1');
+	await invoke('take_snapshot', { server: 's1' });
+	assert.deepEqual(requests.at(-1), { name: 'create_snapshot', method: 'POST', params: { server: 's1' } });
+	await invoke('take_snapshot', { group: 'main' });
+	assert.deepEqual(requests.at(-1), { name: 'create_group_snapshot', method: 'POST', params: { group: 'main' } });
+	
+	// Validate through the registered protocol schema as well as the registry.
+	const count = requests.length;
+	for (const [name, args] of [
+		['take_snapshot', {}], ['take_snapshot', { server: 's1', group: 'main' }],
+		['create_ticket', { ticket: { subject: 'Test', username: 'admin' } }],
+		['comment_ticket', { id: 't1', body: ' ' }]
+	]) {
+		const reply = await client.call(name, args);
+		assert.ok(reply.error || reply.result.isError, name);
+	}
+	assert.equal(requests.length, count);
+	client.child.stdin.end();
+	assert.equal((await client.exit)[0], 0);
+});

package/test/mcp-tools-unit.test.js

@@ -0,0 +1,212 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const Path = require('node:path');
+const { createContext } = require('../lib/mcp/context.js');
+const { configuration } = require('../lib/mcp.js');
+const { result } = require('../lib/mcp/results.js');
+const tools = require('../lib/mcp/registry.js')();
+
+test('tool schemas reject unsafe or ambiguous mutation inputs', async () => {
+	const validate = (name, args) => tools.get(name).inputSchema['~standard'].validate(args);
+	assert.equal(tools.size, 17);
+	assert.ok((await validate('create_event', { event: { title: 'Test', category: 'general', enabled: false } })).issues);
+	assert.ok((await validate('update_event', { id: 'test', changes: { title: 'New' } })).issues);
+	assert.ok((await validate('update_event', { id: 'test', revision: 0, changes: {} })).issues);
+	assert.ok((await validate('run_event', { id: 'test', test: true })).issues);
+	assert.ok((await validate('delete_event', { id: 'test', delete_jobs: true })).issues);
+	assert.ok((await validate('search_jobs', { limit: 101 })).issues);
+	assert.ok(!(await validate('create_event', { event: { title: 'Flow', category: 'general', enabled: false, type: 'workflow', workflow: { nodes: [], connections: [] } } })).issues);
+});
+
+test('update submits only supplied changes and the expected revision', async () => {
+	let request;
+	const context = createContext({ update_event: async params => { request = params; return { data: { code: 0, event: { id: params.id, revision: 3 } } }; } });
+	const response = await tools.get('update_event').run({ id: 'event1', revision: 2, changes: { params: { message: 'new' }, triggers: [] } }, context);
+	assert.deepEqual(request, { id: 'event1', revision: 2, params: { message: 'new' }, triggers: [] });
+	assert.equal(response.event.revision, 3);
+});
+
+test('context enforces read-only, cancellation and safe property names before SDK calls', async () => {
+	let calls = 0;
+	const api = { run_event: async () => { calls++; return { data: { code: 0 } }; } };
+	await assert.rejects(createContext(api, { read_only: true }).callAPI('run_event', {}), /read-only/);
+	const context = createContext(api);
+	await assert.rejects(context.callAPI('run_event', {}, AbortSignal.abort()), /cancelled/);
+	await assert.rejects(context.callAPI('run_event', JSON.parse('{"params":{"__proto__":{}}}')), /Unsupported property/);
+	await assert.rejects(context.callAPI('admin_update', {}), /Unsupported API/);
+	assert.equal(calls, 0);
+});
+
+test('transport failure reports uncertain mutations, redacts the key, and never retries', async () => {
+	let calls = 0;
+	const context = createContext({ run_event: async (params, options) => {
+		calls++; assert.equal(options.retries, 0); return { err: 'lost connection secret-key' };
+	} }, { api_key: 'secret-key' });
+	await assert.rejects(context.callAPI('run_event', {}), error => /uncertain/.test(error.message) && !error.message.includes('secret-key'));
+	assert.equal(calls, 1);
+	const denied = createContext({ run_event: async () => ({ err: 'denied', data: { code: 'access', description: 'Denied' } }) });
+	await assert.rejects(denied.callAPI('run_event'), error => error.message === 'Denied');
+});
+
+test('read tools paginate and omit API envelopes and download tokens', async () => {
+	const context = createContext({
+		get_events: async () => ({ data: { code: 0, rows: [{ id: 'b', title: 'Second', enabled: false }, { id: 'a', title: 'First', enabled: true }] } }),
+		get_job: async () => ({ data: { code: 0, token: 'private', job: { id: 'j1', state: 'complete', data: { answer: 42 } } } })
+	});
+	const events = await tools.get('list_events').run({ limit: 1 }, context);
+	assert.equal(events.total, 2);
+	assert.equal(events.rows[0].id, 'a');
+	const job = await tools.get('get_job').run({ id: 'j1' }, context);
+	assert.equal(job.job.data.answer, 42);
+	assert.ok(!JSON.stringify(job).includes('private'));
+	assert.throws(() => result({ long: 'x'.repeat(100) }, 50), /output limit/);
+});
+
+test('configuration validates named options and limits', () => {
+	assert.equal(configuration({}, { port: '9000' }).port, 9000);
+	assert.equal(configuration({ mcp: { read_only: true }, mcp_port: 9001 }, {}).port, 9001);
+	assert.throws(() => configuration({}, { port: 'oops' }), /port/);
+	assert.throws(() => configuration({ mcp: { max_page_size: 1000 } }, {}), /max_page_size/);
+	assert.throws(() => configuration({ mcp: { tls_cert: 'cert' } }, {}), /both/);
+});
+
+test('registry fails on duplicate names, invalid exports and invalid schemas', t => {
+	const directory = fs.mkdtempSync(Path.join(os.tmpdir(), 'xycli-mcp-registry-'));
+	t.after(() => fs.rmSync(directory, { recursive: true, force: true }));
+	const load = require('../lib/mcp/registry.js');
+	fs.writeFileSync(Path.join(directory, 'bad.js'), 'module.exports = {};');
+	assert.throws(() => load(directory), /Invalid MCP tool exports/);
+	fs.unlinkSync(Path.join(directory, 'bad.js'));
+	const moduleText = 'exports.run = async () => ({}); exports.describe = () => (' + JSON.stringify(tools.get('get_event').description) + ');';
+	fs.writeFileSync(Path.join(directory, 'one.js'), moduleText);
+	fs.writeFileSync(Path.join(directory, 'two.js'), moduleText);
+	assert.throws(() => load(directory), /Duplicate/);
+	fs.unlinkSync(Path.join(directory, 'one.js'));
+	fs.unlinkSync(Path.join(directory, 'two.js'));
+	const invalid = structuredClone(tools.get('get_event').description);
+	invalid.inputSchema.properties.id.type = 'not-a-json-type';
+	fs.writeFileSync(Path.join(directory, 'schema.js'), 'exports.run = async () => ({}); exports.describe = () => (' + JSON.stringify(invalid) + ');');
+	assert.throws(() => load(directory));
+});
+
+test('ticket and monitoring schemas reject ambiguous targets and protected metadata', async () => {
+	const validate = (name, args) => tools.get(name).inputSchema['~standard'].validate(args);
+	const invalid = [
+		['create_ticket', { ticket: { subject: '   ' } }],
+		['create_ticket', { ticket: { subject: 'Test', username: 'admin' } }],
+		['create_ticket', { ticket: { subject: 'Test', changes: [] } }],
+		['create_ticket', { ticket: { subject: 'Test', template: 'job', job: 'j1' } }],
+		['update_ticket', { id: 't1', changes: {} }],
+		['update_ticket', { id: 't1', changes: { id: 't2' } }],
+		['update_ticket', { id: 't1', changes: { due: 3600 } }],
+		['update_ticket', { id: 't1', changes: { assignees: 'admin' } }],
+		['comment_ticket', { id: 't1', body: ' ' }],
+		['comment_ticket', { id: 't1', body: 'Hello', username: 'admin' }],
+		['delete_ticket', { id: 'bad/id' }],
+		['take_snapshot', {}],
+		['take_snapshot', { server: 's1', group: 'main' }],
+		['take_snapshot', { server: '' }],
+		['search_alerts', { limit: 101 }],
+		['search_snapshots', { verbose: 'true' }],
+		['list_servers', { offset: -1 }]
+	];
+	for (const [name, args] of invalid) assert.ok((await validate(name, args)).issues, name + ': ' + JSON.stringify(args));
+	for (const [name, args] of [
+		['create_ticket', { ticket: { subject: 'Test', type: 'custom', status: 'custom' } }],
+		['update_ticket', { id: 't1', changes: { due: 0, server: '', category: '', assignees: [], tags: [] } }],
+		['update_ticket', { id: 't1', changes: { due: 1800000000 } }],
+		['take_snapshot', { server: 's1' }], ['take_snapshot', { group: 'main' }]
+	]) assert.ok(!(await validate(name, args)).issues, name + ': ' + JSON.stringify(args));
+});
+
+test('ticket mutations preserve partial updates and keep history out of summaries', async () => {
+	const requests = [];
+	const api = {};
+	for (const name of ['create_ticket', 'update_ticket', 'delete_ticket', 'add_ticket_change']) {
+		api[name] = async params => {
+			requests.push({ name, params });
+			return { data: { code: 0, ticket: { id: 't1', num: 1, subject: 'Test', body: 'Large body', changes: [{ body: 'Old history' }, { id: 'c1', type: 'comment', body: 'New comment', username: 'key1', date: 123 }] } } };
+		};
+	}
+	const context = createContext(api);
+	const created = await tools.get('create_ticket').run({ ticket: { subject: 'Test', body: 'Markdown' } }, context);
+	assert.equal(created.ticket.id, 't1');
+	assert.ok(!('body' in created.ticket) && !('changes' in created.ticket));
+	await tools.get('update_ticket').run({ id: 't1', changes: { tags: [], server: '', due: 0 } }, context);
+	assert.deepEqual(requests[1], { name: 'update_ticket', params: { id: 't1', tags: [], server: '', due: 0 } });
+	const comment = await tools.get('comment_ticket').run({ id: 't1', body: 'New comment' }, context);
+	assert.deepEqual(requests[2].params, { id: 't1', change: { type: 'comment', body: 'New comment' } });
+	assert.equal(comment.comment.id, 'c1');
+	assert.equal(comment.comment.username, 'key1');
+	assert.ok(!JSON.stringify(comment).includes('Old history'));
+	assert.deepEqual(await tools.get('delete_ticket').run({ id: 't1' }, context), { id: 't1', deleted: true });
+});
+
+test('monitoring reads preserve queries, bound pages and filter authorized server summaries', async () => {
+	const requests = [];
+	const api = {
+		get_active_servers: async () => ({ data: { code: 0, rows: [
+			{ id: 's3', hostname: 'WEB-3', groups: ['main'], enabled: false, socket_id: 'internal' },
+			{ id: 's2', hostname: 'web-2', groups: ['other'], enabled: false },
+			{ id: 's1', hostname: 'web-1', groups: ['main'], enabled: false },
+			{ id: 's4', hostname: 'web-4', groups: ['main'], enabled: true }
+		] } })
+	};
+	for (const name of ['search_alerts', 'search_snapshots']) api[name] = async params => {
+		requests.push({ name, params });
+		return { data: { code: 0, rows: [{ id: 'record1', data: { cpu: 42 } }], list: { length: 50 } } };
+	};
+	const context = createContext(api, { max_page_size: 2 });
+	const alerts = await tools.get('search_alerts').run({ query: 'active:true server:s1', offset: 4, limit: 10, sort_by: 'start', sort_dir: 1 }, context);
+	assert.deepEqual(requests[0].params, { query: 'active:true server:s1', offset: 4, limit: 2, sort_by: 'start', sort_dir: 1 });
+	assert.equal(alerts.total, 50);
+	assert.equal(alerts.limit, 2);
+	const snapshots = await tools.get('search_snapshots').run({}, context);
+	assert.deepEqual(requests[1].params, { query: '*', offset: 0, limit: 2, sort_by: '_id', sort_dir: -1, verbose: false });
+	assert.equal(snapshots.rows[0].data.cpu, 42);
+	await tools.get('search_snapshots').run({ verbose: true, limit: 1 }, context);
+	assert.equal(requests[2].params.verbose, true);
+	const servers = await tools.get('list_servers').run({ hostname: 'WeB', group: 'main', enabled: false, offset: 1, limit: 1 }, context);
+	assert.equal(servers.total, 2);
+	assert.equal(servers.rows[0].id, 's3');
+	assert.ok(!('socket_id' in servers.rows[0]));
+});
+
+test('all new write APIs enforce read-only, key scoping and uncertain outcomes', async () => {
+	const mutations = [
+		['create_ticket', { ticket: { subject: 'Test' } }, 'create_ticket'],
+		['update_ticket', { id: 't1', changes: { status: 'closed' } }, 'update_ticket'],
+		['delete_ticket', { id: 't1' }, 'delete_ticket'],
+		['comment_ticket', { id: 't1', body: 'Test' }, 'add_ticket_change'],
+		['take_snapshot', { server: 's1' }, 'create_snapshot'],
+		['take_snapshot', { group: 'main' }, 'create_group_snapshot']
+	];
+	for (const [name, args, method] of mutations) {
+		let calls = 0;
+		const api = { [method]: async (params, options) => {
+			calls++;
+			assert.equal(options.retries, 0);
+			assert.equal(options.headers['X-API-Key'], 'client-key');
+			return { err: 'lost connection client-key' };
+		} };
+		assert.equal(tools.get(name).description.annotations.readOnlyHint, false);
+		await assert.rejects(tools.get(name).run(args, createContext(api, { read_only: true })), /read-only/);
+		assert.equal(calls, 0);
+		const scoped = createContext(api, { api_key: 'server-key' }).withApiKey('client-key');
+		await assert.rejects(tools.get(name).run(args, scoped), error => /uncertain/.test(error.message) && !error.message.includes('client-key'));
+		assert.equal(calls, 1);
+		api[method] = async () => ({ data: { code: 'access', description: 'Permission denied' } });
+		await assert.rejects(tools.get(name).run(args, scoped), error => error.message === 'Permission denied');
+	}
+});
+
+test('take_snapshot dispatches server and group requests without starting watches', async () => {
+	const context = createContext({
+		create_snapshot: async params => { assert.deepEqual(params, { server: 's1' }); return { data: { code: 0, id: 'sn1' } }; },
+		create_group_snapshot: async params => { assert.deepEqual(params, { group: 'main' }); return { data: { code: 0, id: 'sn2' } }; }
+	});
+	assert.deepEqual(await tools.get('take_snapshot').run({ server: 's1' }, context), { id: 'sn1', type: 'server', server: 's1' });
+	assert.deepEqual(await tools.get('take_snapshot').run({ group: 'main' }, context), { id: 'sn2', type: 'group', group: 'main' });
+});

package/test/mcp.test.js

@@ -0,0 +1,212 @@
+// Explicit live suite. Only this test's disposable records may be modified.
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { loadTestConfig, call, cleanupFixtures } = require('./helpers/common.js');
+const { stdioClient, httpRPC } = require('./helpers/mcp.js');
+const { configuration } = require('../lib/mcp.js');
+
+test('MCP live event/job lifecycle and API-key permissions', async t => {
+	const config = loadTestConfig();
+	const stamp = Date.now();
+	const eventID = 'cli_mcp_' + stamp;
+	const keyID = 'cli_mcp_key_' + stamp;
+	const sdk = require('@pixlcore/xyops-sdk');
+	const jobs = new Set();
+	const client = stdioClient(t);
+	await client.initialize();
+	
+	async function invoke(name, args) {
+		const reply = await client.call(name, args);
+		assert.ok(reply.result && !reply.result.isError, reply.result?.content?.[0]?.text || 'Tool failed: ' + name);
+		return reply.result.structuredContent;
+	}
+	
+	async function finished(id) {
+		const deadline = Date.now() + 30000;
+		while (Date.now() < deadline) {
+			const { job } = await invoke('get_job', { id });
+			if (job.final) return job;
+			await new Promise(resolve => setTimeout(resolve, 250));
+		}
+		throw new Error('Disposable MCP job did not finish');
+	}
+	
+	// Check connectivity before creating fixtures, so an unavailable server
+	// reports the original failure rather than a secondary cleanup failure.
+	const data = await call('getMultiple', { lists: 'categories,plugins', servers: 1 });
+	try {
+		const options = await invoke('get_event_options', { plugin_id: 'shellplug' });
+		assert.equal(options.plugin.id, 'shellplug');
+		const category = data.categories.find(item => item.enabled);
+		const target = Object.keys(data.servers)[0];
+		assert.ok(category && target, 'Live test requires an enabled category and connected server');
+		const created = await invoke('create_event', { event: {
+			id: eventID, title: 'Disposable MCP Test ' + stamp, enabled: true,
+			category: category.id, plugin: 'shellplug', targets: [target], algo: 'random',
+			params: { script: 'echo XYCLI_MCP_TEST_' + stamp },
+			triggers: [{ type: 'manual', enabled: true }], actions: [], limits: []
+		} });
+		assert.equal(created.event.id, eventID);
+		const read = await invoke('get_event', { id: eventID });
+		const updated = await invoke('update_event', { id: eventID, revision: read.event.revision, changes: { notes: 'Updated through MCP' } });
+		assert.ok(updated.event.revision > read.event.revision);
+		const stale = await client.call('update_event', { id: eventID, revision: read.event.revision, changes: { notes: 'Must not apply' } });
+		assert.equal(stale.result.isError, true);
+		assert.match(stale.result.content[0].text, /Revision mismatch/);
+		const preserved = await invoke('get_event', { id: eventID });
+		assert.equal(preserved.event.params.script, read.event.params.script);
+		assert.equal(preserved.event.notes, 'Updated through MCP');
+		assert.equal((await invoke('list_events', { title: 'Disposable MCP Test ' + stamp })).total, 1);
+		
+		// A genuinely restricted xyOps key can inspect and run, but cannot edit.
+		const key = await call('createApiKey', { id: keyID, title: keyID, active: true, privileges: { run_jobs: true } });
+		const restricted = stdioClient(t, { XYOPS_API_KEY: key.plain_key });
+		await restricted.initialize();
+		assert.ok(!(await restricted.call('get_event', { id: eventID })).result.isError);
+		const denied = await restricted.call('update_event', { id: eventID, revision: updated.event.revision, changes: { notes: 'Forbidden' } });
+		assert.equal(denied.result.isError, true);
+		const launched = await restricted.call('run_event', { id: eventID });
+		assert.ok(!launched.result.isError, 'Restricted key should be able to run the fixture');
+		const jobID = launched.result.structuredContent.id;
+		jobs.add(jobID);
+		const job = await finished(jobID);
+		assert.equal(job.code, 0);
+		const results = await invoke('search_jobs', { query: 'event:' + eventID });
+		assert.ok(results.rows.some(row => row.id === jobID));
+		
+		// Use the HTTP transport against the same live API and compare results.
+		const context = require('../lib/mcp/context.js').createContext(sdk.api, { api_key: config.api_key });
+		const factory = require('../lib/mcp/server.js')(require('../lib/mcp/registry.js')(), context);
+		const service = await require('../lib/mcp/transports/http.js')(factory, { ...configuration({}, {}), port: 0, log() {} });
+		try {
+			const response = await httpRPC('http://127.0.0.1:' + service.address.port + '/mcp', 'tools/call', { name: 'get_event', arguments: { id: eventID } }, { modern: true, headers: { Authorization: 'Bearer ' + key.plain_key } });
+			assert.deepEqual(response.result.structuredContent.event, preserved.event);
+			const url = 'http://127.0.0.1:' + service.address.port + '/mcp';
+			// The process has admin credentials, but each HTTP caller must use
+			// only its supplied key, even while requests overlap.
+			const updates = await Promise.all([
+				{ key: config.api_key, notes: 'HTTP admin update' },
+				{ key: key.plain_key, notes: 'Forbidden HTTP update' },
+				{ key: 'invalid-fixture-key', notes: 'Invalid key update' }
+			].map(item => httpRPC(url, 'tools/call', { name: 'update_event', arguments: {
+				id: eventID, revision: updated.event.revision, changes: { notes: item.notes }
+			} }, { modern: true, headers: { Authorization: 'Bearer ' + item.key } })));
+			assert.ok(!updates[0].result.isError);
+			assert.equal(updates[1].result.isError, true);
+			assert.equal(updates[2].result.isError, true);
+			// These must be authentication/permission failures, not revision
+			// conflicts caused by the concurrent administrator update.
+			assert.match(updates[1].result.content[0].text, /does not have the .* privilege/);
+			assert.match(updates[2].result.content[0].text, /Invalid API Key/);
+			assert.equal((await fetch(url)).status, 401);
+			assert.equal((await invoke('get_event', { id: eventID })).event.notes, 'HTTP admin update');
+		}
+		finally { await service.close(); }
+		
+		await invoke('delete_event', { id: eventID });
+		assert.equal((await invoke('get_job', { id: jobID })).job.id, jobID, 'Event deletion retains historical jobs');
+		assert.equal((await client.call('get_event', { id: eventID })).result.isError, true);
+	}
+	finally {
+		// Cleanup is allowed to delete only IDs owned by this test invocation.
+		const errors = [];
+		for (const id of jobs) {
+			try {
+				const { job } = await call('getJob', { id });
+				if (!job.final) { await call('abortJob', { id }); await finished(id); }
+				await call('deleteJob', { id });
+			}
+			catch (err) { errors.push(err); }
+		}
+		try { await cleanupFixtures([
+			{ list: 'events', method: 'deleteEvent', match: item => item.id === eventID },
+			{ list: 'api_keys', method: 'deleteApiKey', match: item => item.id === keyID }
+		]); }
+		catch (err) { errors.push(err); }
+		if (errors.length) throw new AggregateError(errors, 'MCP fixture cleanup failed');
+	}
+});
+
+test('MCP live ticket and monitoring lifecycle', async t => {
+	loadTestConfig();
+	const subject = 'Disposable MCP Ticket ' + Date.now();
+	const snapshots = new Set();
+	let ticketID;
+	const client = stdioClient(t);
+	await client.initialize();
+	async function invoke(name, args) {
+		const reply = await client.call(name, args);
+		assert.ok(reply.result && !reply.result.isError, reply.result?.content?.[0]?.text || 'Tool failed: ' + name);
+		return reply.result.structuredContent;
+	}
+	
+	// Exact-ID searches return a not-found API error after deletion, rather
+	// than an empty search page. Keep that distinction in cleanup assertions.
+	async function verifyMissing(collection, id) {
+		const response = await require('@pixlcore/xyops-sdk').api['search_' + collection]({ query: '#id:' + id, limit: 1 });
+		assert.ok(response.err && response.data?.description?.includes(id) && /Not found/i.test(response.data.description), 'Disposable ' + collection + ' record was removed');
+	}
+	
+	// Preflight is read-only. The server needs one saved monitoring sample.
+	const servers = await invoke('list_servers', { limit: 1 });
+	const server = servers.rows[0];
+	assert.ok(server?.groups?.length, 'Live MCP monitoring test requires a connected worker in a group');
+	try {
+		// Keep the ticket in draft for its entire lifetime to suppress email.
+		const created = await invoke('create_ticket', { ticket: { subject, status: 'draft', body: 'Initial body', assignees: [], cc: [], notify: [] } });
+		ticketID = created.ticket.id;
+		assert.ok(ticketID);
+		assert.equal(created.ticket.status, 'draft');
+		await invoke('update_ticket', { id: ticketID, changes: { body: 'Updated body', server: server.id } });
+		const saved = (await call('get_ticket', { id: ticketID })).ticket;
+		assert.equal(saved.subject, subject);
+		assert.equal(saved.status, 'draft');
+		assert.equal(saved.body, 'Updated body');
+		assert.equal(saved.server, server.id);
+		const commented = await invoke('comment_ticket', { id: ticketID, body: 'MCP fixture comment' });
+		assert.equal(commented.comment.body, 'MCP fixture comment');
+		assert.ok(commented.comment.id && commented.comment.username);
+		assert.equal(commented.ticket.status, 'draft');
+		const history = (await call('get_ticket', { id: ticketID })).ticket.changes;
+		assert.equal(history.at(-1).id, commented.comment.id);
+		const removed = await invoke('delete_ticket', { id: ticketID });
+		assert.equal(removed.deleted, true);
+		const deletedID = ticketID;
+		ticketID = null;
+		await verifyMissing('tickets', deletedID);
+		
+		// Search existing alert history without triggering an alert or action.
+		const alerts = await invoke('search_alerts', { query: 'server:' + server.id, limit: 1 });
+		assert.ok(Array.isArray(alerts.rows) && alerts.rows.length <= 1);
+		assert.equal(typeof alerts.total, 'number');
+		for (const target of [{ server: server.id }, { group: server.groups[0] }]) {
+			const snapshot = await invoke('take_snapshot', target);
+			snapshots.add(snapshot.id);
+			assert.ok(snapshot.id);
+			const found = await invoke('search_snapshots', { query: '#id:' + snapshot.id, limit: 1 });
+			assert.equal(found.rows[0].id, snapshot.id);
+			assert.equal(found.rows[0].type, target.server ? 'server' : 'group');
+			assert.ok(!('snapshots' in found.rows[0]));
+			assert.ok(!('processes' in (found.rows[0].data || {})));
+		}
+	}
+	finally {
+		// Delete only returned IDs from this test and verify each removal.
+		const errors = [];
+		if (ticketID) {
+			try {
+				await call('delete_ticket', { id: ticketID });
+				await verifyMissing('tickets', ticketID);
+			}
+			catch (err) { errors.push(err); }
+		}
+		for (const id of snapshots) {
+			try {
+				await call('delete_snapshot', { id });
+				await verifyMissing('snapshots', id);
+			}
+			catch (err) { errors.push(err); }
+		}
+		if (errors.length) throw new AggregateError(errors, 'MCP ticket/snapshot fixture cleanup failed');
+	}
+});