@pixlcore/xycli 1.1.1 → 1.2.1

package/lib/mcp/registry.js

@@ -0,0 +1,27 @@
+// Load only the bundled tools. Helpers belong outside the tools directory.
+const fs = require('node:fs');
+const Path = require('node:path');
+const { fromJsonSchema } = require('@modelcontextprotocol/server');
+
+module.exports = function loadTools(directory = Path.join(__dirname, 'tools')) {
+	const tools = new Map();
+	
+	for (const file of fs.readdirSync(directory).filter(file => file.endsWith('.js')).sort()) {
+		const tool = require(Path.join(directory, file));
+		if (typeof tool.describe !== 'function' || typeof tool.run !== 'function') {
+			throw new Error('Invalid MCP tool exports: ' + file);
+		}
+		const description = tool.describe();
+		if (!description || !/^[a-z][a-z0-9_]*$/.test(description.name) || !description.description ||
+			!description.inputSchema || description.inputSchema.type !== 'object' ||
+			typeof description.annotations?.readOnlyHint !== 'boolean') {
+			throw new Error('Invalid MCP tool description: ' + file);
+		}
+		if (tools.has(description.name)) throw new Error('Duplicate MCP tool: ' + description.name);
+		
+		// Compile once, rather than rebuilding validators for each HTTP request.
+		const inputSchema = fromJsonSchema(description.inputSchema);
+		tools.set(description.name, { ...tool, description, inputSchema });
+	}
+	return tools;
+};

package/lib/mcp/results.js

@@ -0,0 +1,14 @@
+// Tools return ordinary objects. Only this layer knows the MCP result envelope.
+function result(data, limit) {
+	const text = JSON.stringify(data);
+	if (Buffer.byteLength(text) > limit) {
+		throw new Error('Result exceeds the MCP output limit. Request fewer rows or selected fields. The operation may already have completed.');
+	}
+	return { structuredContent: data, content: [{ type: 'text', text }] };
+}
+
+function failure(error, redact) {
+	return { isError: true, content: [{ type: 'text', text: redact(error.message || error) }] };
+}
+
+module.exports = { result, failure };

package/lib/mcp/schemas.js

@@ -0,0 +1,67 @@
+// Handwritten public contracts, independent of the underlying API inventory.
+const id = { type: 'string', pattern: '^[a-z0-9_]+$', description: 'Exact xyOps ID; use a list tool to discover IDs.' };
+const text = { type: 'string' };
+const object = { type: 'object', additionalProperties: true };
+const objects = { type: 'array', items: object };
+const strings = { type: 'array', items: text };
+const pagination = {
+	offset: { type: 'integer', minimum: 0, default: 0 },
+	limit: { type: 'integer', minimum: 1, maximum: 100, default: 25 }
+};
+
+// Ticket types and statuses are configurable in xyOps, so do not freeze them
+// into enums here. Empty category/server strings explicitly clear a link.
+const ticketProperties = {
+	subject: { type: 'string', pattern: '\\S' },
+	body: { ...text, description: 'Ticket body in Markdown.' },
+	type: { ...text, minLength: 1, description: 'Configured ticket type, such as issue or question.' },
+	status: { ...text, minLength: 1, description: 'Configured ticket status, such as open, closed or draft.' },
+	category: { type: 'string', pattern: '^[a-z0-9_]*$' },
+	server: { type: 'string', pattern: '^[a-z0-9_]*$' },
+	assignees: { ...strings, description: 'Assignee usernames. Replaces the entire list.' },
+	cc: { ...strings, description: 'Usernames to receive ticket updates. Replaces the entire list.' },
+	notify: { ...strings, description: 'Email addresses to receive ticket updates. Replaces the entire list.' },
+	tags: { ...strings, description: 'Existing tag IDs. Replaces the entire list.' },
+	// xyOps interprets small positive values as relative offsets. Accept only
+	// absolute dates here, plus zero to remove the due date.
+	due: { type: 'integer', anyOf: [{ const: 0 }, { minimum: 315532800 }], description: 'Absolute Unix timestamp in seconds (1980 or later), or 0 to clear.' }
+};
+const ticketSummary = ['id', 'num', 'subject', 'type', 'status', 'category', 'server', 'assignees', 'cc', 'notify', 'tags', 'due', 'created', 'modified'];
+
+const workflow = {
+	type: 'object', required: ['nodes', 'connections'], additionalProperties: false,
+	properties: {
+		nodes: { ...objects, description: 'Workflow nodes, each with id, type and type-specific settings. Inspect an existing workflow for examples.' },
+		connections: { ...objects, description: 'Directed workflow connections between node IDs.' },
+		start: text
+	}
+};
+const eventProperties = {
+	title: { type: 'string', pattern: '\\S' }, enabled: { type: 'boolean' }, category: id,
+	plugin: id, targets: strings, algo: { ...text, description: 'Server selection algorithm, such as random, round_robin or least_cpu.' },
+	params: { ...object, description: 'Plugin parameters. A supplied object replaces the saved parameter object on update.' },
+	fields: objects, triggers: { ...objects, description: 'Trigger definitions. For manual execution use {type: "manual", enabled: true}.' },
+	actions: objects, limits: objects, tags: strings, notes: text, icon: text,
+	expression: text, workflow
+};
+
+function input(properties, required = []) {
+	return { type: 'object', properties, required, additionalProperties: false };
+}
+
+function describe(name, description, properties, required = [], readOnly = true) {
+	return {
+		name, description, inputSchema: input(properties, required),
+		annotations: { readOnlyHint: readOnly, destructiveHint: !readOnly, idempotentHint: readOnly, openWorldHint: true }
+	};
+}
+
+function page(args, context) {
+	return { offset: args.offset ?? 0, limit: Math.min(args.limit ?? 25, context.limits.max_page_size) };
+}
+
+function pick(value, fields) {
+	return Object.fromEntries(fields.filter(key => Object.hasOwn(value, key)).map(key => [key, value[key]]));
+}
+
+module.exports = { id, text, object, objects, strings, pagination, eventProperties, ticketProperties, ticketSummary, input, describe, page, pick };

package/lib/mcp/server.js

@@ -0,0 +1,28 @@
+// Both transports register the same descriptions and invoke the same modules.
+const { McpServer } = require('@modelcontextprotocol/server');
+const { result, failure } = require('./results.js');
+const { checkKeys } = require('./context.js');
+const pkg = require('../../package.json');
+
+module.exports = function serverFactory(tools, context) {
+	return function buildServer({ apiKey } = {}) {
+		// STDIO uses the configured context. HTTP supplies a key for each
+		// exchange, shared by all API calls made by that exchange's tools.
+		const scoped = apiKey === undefined ? context : context.withApiKey(apiKey);
+		const server = new McpServer({ name: 'xyops', version: pkg.version });
+		for (const tool of tools.values()) {
+			const { name, ...description } = tool.description;
+			if (scoped.readOnly && !description.annotations.readOnlyHint) continue;
+			server.registerTool(name, { ...description, inputSchema: tool.inputSchema }, async function(args, request) {
+				try {
+					checkKeys(args);
+					const invocation = { ...scoped, signal: request.mcpReq.signal };
+					invocation.callAPI = (name, params) => scoped.callAPI(name, params, invocation.signal);
+					return result(await tool.run(args, invocation), scoped.limits.max_result_bytes);
+				}
+				catch (err) { return failure(err, scoped.redact); }
+			});
+		}
+		return server;
+	};
+};

package/lib/mcp/tools/comment-ticket.js

@@ -0,0 +1,11 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('comment_ticket', 'Append a Markdown comment to a ticket by exact ID. xyOps assigns the author and timestamp. May send configured ticket notifications. Returns the ticket summary and new comment.', {
+	id: S.id, body: { type: 'string', pattern: '\\S', description: 'Comment body in Markdown.' }
+}, ['id', 'body'], false);
+
+exports.run = async function(args, context) {
+	// Expose comments only, not arbitrary change-history records or authors.
+	const { ticket } = await context.callAPI('add_ticket_change', { id: args.id, change: { type: 'comment', body: args.body } });
+	return { ticket: S.pick(ticket, S.ticketSummary), comment: S.pick(ticket.changes.at(-1), ['id', 'type', 'body', 'username', 'date']) };
+};

package/lib/mcp/tools/create-event.js

@@ -0,0 +1,17 @@
+const S = require('../schemas.js');
+
+exports.describe = function() {
+	const definition = S.input({ ...S.eventProperties, id: S.id, type: { type: 'string', enum: ['event', 'workflow'] } }, ['title', 'enabled', 'category']);
+	// A workflow owns its graph; an ordinary event selects a plugin and worker.
+	definition.allOf = [{
+		if: { properties: { type: { const: 'workflow' } }, required: ['type'] },
+		then: { required: ['workflow'] },
+		else: { required: ['plugin', 'targets', 'algo'], properties: { targets: { ...S.strings, minItems: 1 } } }
+	}];
+	return S.describe('create_event', 'Create an event or workflow. Use get_event_options for valid IDs and plugin parameters. Specify enabled explicitly and supply triggers explicitly when needed. Returns the created ID and revision.', { event: definition }, ['event'], false);
+};
+
+exports.run = async function(args, context) {
+	const { event } = await context.callAPI('create_event', args.event);
+	return { event: S.pick(event, ['id', 'title', 'enabled', 'revision']) };
+};

package/lib/mcp/tools/create-ticket.js

@@ -0,0 +1,11 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('create_ticket', 'Create a ticket with a subject and optional Markdown body, assignment and classification. Status defaults to open in xyOps. May send configured ticket notifications. Returns a summary; file attachments and automatic templates are not supported.', {
+	ticket: S.input(S.ticketProperties, ['subject'])
+}, ['ticket'], false);
+
+exports.run = async function(args, context) {
+	// Let xyOps assign the ID, number, author and initial change history.
+	const { ticket } = await context.callAPI('create_ticket', { ...args.ticket });
+	return { ticket: S.pick(ticket, S.ticketSummary) };
+};

package/lib/mcp/tools/delete-event.js

@@ -0,0 +1,8 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('delete_event', 'Delete an event or workflow by exact ID. Historical jobs are retained. xyOps rejects deletion while jobs for this event are active.', { id: S.id }, ['id'], false);
+
+exports.run = async function(args, context) {
+	await context.callAPI('delete_event', { id: args.id });
+	return { id: args.id, deleted: true, historical_jobs_retained: true };
+};

package/lib/mcp/tools/delete-ticket.js

@@ -0,0 +1,8 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('delete_ticket', 'Permanently delete a ticket by exact ID. References from jobs and alerts are cleaned up by xyOps background maintenance.', { id: S.id }, ['id'], false);
+
+exports.run = async function(args, context) {
+	await context.callAPI('delete_ticket', { id: args.id });
+	return { id: args.id, deleted: true };
+};

package/lib/mcp/tools/get-event-options.js

@@ -0,0 +1,19 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('get_event_options', 'Look up categories, target groups and event plugins for creating events. Each collection is paginated. Supply plugin_id to also inspect its parameter definitions.', { ...S.pagination, plugin_id: S.id });
+
+exports.run = async function(args, context) {
+	const { offset, limit } = S.page(args, context);
+	const output = {};
+	// Each API independently enforces the configured key permissions.
+	for (const name of ['categories', 'groups', 'plugins']) {
+		const data = await context.callAPI('get_' + name);
+		const rows = data.rows.filter(item => name !== 'plugins' || item.type === 'event').sort((a, b) => a.id.localeCompare(b.id));
+		output[name] = { rows: rows.slice(offset, offset + limit).map(item => S.pick(item, ['id', 'title', 'enabled'])), total: rows.length, offset, limit };
+	}
+	if (args.plugin_id) {
+		const { plugin } = await context.callAPI('get_plugin', { id: args.plugin_id });
+		output.plugin = S.pick(plugin, ['id', 'title', 'type', 'params']);
+	}
+	return output;
+};

package/lib/mcp/tools/get-event.js

@@ -0,0 +1,8 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('get_event', 'Read an event or workflow definition before editing it. Pass its revision to update_event. Optional fields limits the returned definition.', { id: S.id, fields: S.strings }, ['id']);
+
+exports.run = async function(args, context) {
+	const { event } = await context.callAPI('get_event', { id: args.id });
+	return { event: args.fields ? S.pick(event, [...new Set(['id', 'revision', ...args.fields])]) : event };
+};

package/lib/mcp/tools/get-job.js

@@ -0,0 +1,8 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('get_job', 'Inspect a running or completed job. Returns status, completion details and output data. Optional fields selects additional job properties. Download tokens are not returned.', { id: S.id, fields: S.strings }, ['id']);
+
+exports.run = async function(args, context) {
+	const { job } = await context.callAPI('get_job', { id: args.id });
+	return { job: S.pick(job, args.fields ? [...new Set(['id', 'state', 'final', ...args.fields])] : ['id', 'event', 'title', 'state', 'final', 'code', 'description', 'started', 'completed', 'elapsed', 'progress', 'data', 'output']) };
+};

package/lib/mcp/tools/list-events.js

@@ -0,0 +1,17 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('list_events', 'Find events and workflows. Returns summaries, not full definitions. Title is a case-insensitive substring. Pagination is applied locally after fetching authorized events.', {
+	...S.pagination, title: S.text, category: S.id, type: { type: 'string', enum: ['event', 'workflow'] }, enabled: { type: 'boolean' }
+});
+
+exports.run = async function(args, context) {
+	const data = await context.callAPI('get_events');
+	const rows = data.rows.filter(event =>
+		(!args.title || event.title.toLowerCase().includes(args.title.toLowerCase())) &&
+		(!args.category || event.category === args.category) &&
+		(!args.type || (event.type || 'event') === args.type) &&
+		(args.enabled === undefined || !!event.enabled === args.enabled)
+	).sort((a, b) => a.id.localeCompare(b.id));
+	const { offset, limit } = S.page(args, context);
+	return { rows: rows.slice(offset, offset + limit).map(event => S.pick(event, ['id', 'title', 'type', 'category', 'plugin', 'enabled', 'revision'])), total: rows.length, offset, limit };
+};

package/lib/mcp/tools/list-servers.js

@@ -0,0 +1,17 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('list_servers', 'List connected worker servers visible to the API key, excluding offline servers and conductor peers. Returns compact summaries. Hostname is a case-insensitive substring; group is an exact group ID. Filtering and pagination are local.', {
+	...S.pagination, hostname: S.text, group: S.id, enabled: { type: 'boolean' }
+});
+
+exports.run = async function(args, context) {
+	// Use the authorized worker collection, avoiding internal conductor data.
+	const data = await context.callAPI('get_active_servers');
+	const rows = data.rows.filter(server =>
+		(!args.hostname || (server.hostname || '').toLowerCase().includes(args.hostname.toLowerCase())) &&
+		(!args.group || (server.groups || []).includes(args.group)) &&
+		(args.enabled === undefined || !!server.enabled === args.enabled)
+	).sort((a, b) => a.id.localeCompare(b.id));
+	const { offset, limit } = S.page(args, context);
+	return { rows: rows.slice(offset, offset + limit).map(server => S.pick(server, ['id', 'hostname', 'title', 'ip', 'enabled', 'groups', 'created', 'modified', 'info'])), total: rows.length, offset, limit };
+};

package/lib/mcp/tools/run-event.js

@@ -0,0 +1,10 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('run_event', 'Launch an enabled event or workflow with a manual trigger. Optional params override declared event parameters; input.data passes input data. Returns immediately with a job ID. Use get_job to follow completion. Repeating this call starts another job.', {
+	id: S.id, params: S.object, input: S.input({ data: {} })
+}, ['id'], false);
+
+exports.run = async function(args, context) {
+	const data = await context.callAPI('run_event', args);
+	return { id: data.id, started: true };
+};

package/lib/mcp/tools/search-alerts.js

@@ -0,0 +1,12 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('search_alerts', 'Search active or historical alert invocations, not alert definitions. Query examples: active:true, alert:ALERT_ID, server:SERVER_ID, groups:GROUP_ID, or start:>=today. Combine terms with spaces. Newest first by default; xyOps applies API-key restrictions.', {
+	...S.pagination, query: S.text, sort_by: S.text, sort_dir: { type: 'integer', enum: [1, -1] }
+});
+
+exports.run = async function(args, context) {
+	// Keep the query intact so xyOps owns parsing and permission filtering.
+	const { offset, limit } = S.page(args, context);
+	const data = await context.callAPI('search_alerts', { query: args.query || '*', offset, limit, sort_by: args.sort_by || '_id', sort_dir: args.sort_dir ?? -1 });
+	return { rows: data.rows, total: data.list.length, offset, limit };
+};

package/lib/mcp/tools/search-jobs.js

@@ -0,0 +1,12 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('search_jobs', 'Search completed jobs, newest first by default. Query examples: tags:_error, event:EVENT_ID, or date:>=2026-01-01 date:<2027-01-01. Combine terms with spaces. Running jobs are available through get_job. Results respect API-key category and group restrictions.', {
+	...S.pagination, query: S.text, sort_by: { type: 'string', enum: ['_id', 'completed', 'elapsed'] }, sort_dir: { type: 'integer', enum: [1, -1] }
+});
+
+exports.run = async function(args, context) {
+	const { offset, limit } = S.page(args, context);
+	const fields = ['id', 'event', 'title', 'category', 'plugin', 'code', 'description', 'completed', 'elapsed'];
+	const data = await context.callAPI('search_jobs', { query: args.query || '*', offset, limit, sort_by: args.sort_by || '_id', sort_dir: args.sort_dir ?? -1, select: fields.join(',') });
+	return { rows: data.rows.map(job => S.pick(job, fields)), total: data.list.length, offset, limit };
+};

package/lib/mcp/tools/search-snapshots.js

@@ -0,0 +1,12 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('search_snapshots', 'Search server or group snapshots. Query examples: type:server, type:group, server:SERVER_ID, groups:GROUP_ID, source:alert, or date:>=today. Newest first by default. Heavy process, connection and group details are omitted unless verbose is true; use small pages for verbose results.', {
+	...S.pagination, query: S.text, sort_by: S.text, sort_dir: { type: 'integer', enum: [1, -1] }, verbose: { type: 'boolean', default: false }
+});
+
+exports.run = async function(args, context) {
+	// The API prunes heavy nested fields by default while retaining metrics.
+	const { offset, limit } = S.page(args, context);
+	const data = await context.callAPI('search_snapshots', { query: args.query || '*', offset, limit, sort_by: args.sort_by || '_id', sort_dir: args.sort_dir ?? -1, verbose: args.verbose ?? false });
+	return { rows: data.rows, total: data.list.length, offset, limit };
+};

package/lib/mcp/tools/take-snapshot.js

@@ -0,0 +1,15 @@
+const S = require('../schemas.js');
+
+exports.describe = function() {
+	const tool = S.describe('take_snapshot', 'Capture the most recent monitoring data for exactly one server or group. This creates a stored snapshot; it does not start a watch or request a fresh sample. Returns the snapshot ID.', {
+		server: S.id, group: S.id
+	}, [], false);
+	tool.inputSchema.oneOf = [{ required: ['server'] }, { required: ['group'] }];
+	return tool;
+};
+
+exports.run = async function(args, context) {
+	// One public operation dispatches to the appropriate backend API.
+	const data = args.server ? await context.callAPI('create_snapshot', { server: args.server }) : await context.callAPI('create_group_snapshot', { group: args.group });
+	return { id: data.id, type: args.server ? 'server' : 'group', ...(args.server ? { server: args.server } : { group: args.group }) };
+};

package/lib/mcp/tools/update-event.js

@@ -0,0 +1,12 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('update_event', 'Update an event using the revision returned by get_event. Omitted fields are preserved. Supplied nested objects and arrays replace existing values, so include all values you want to keep. Event type cannot be changed. A stale revision is rejected.', {
+	id: S.id, revision: { type: 'integer', minimum: 1 }, changes: { ...S.input(S.eventProperties), minProperties: 1 }
+}, ['id', 'revision', 'changes'], false);
+
+exports.run = async function(args, context) {
+	// Submit a partial update with the caller's revision. Do not fetch and merge
+	// the entire record, which could overwrite changes made by another caller.
+	const { event } = await context.callAPI('update_event', { ...args.changes, id: args.id, revision: args.revision });
+	return { event: S.pick(event, ['id', 'title', 'enabled', 'revision']) };
+};

package/lib/mcp/tools/update-ticket.js

@@ -0,0 +1,11 @@
+const S = require('../schemas.js');
+
+exports.describe = () => S.describe('update_ticket', 'Update a ticket by exact ID. Omitted fields are preserved; supplied arrays replace the entire saved list. Tickets have no revision precondition. May send configured ticket notifications. Returns a summary.', {
+	id: S.id, changes: { ...S.input(S.ticketProperties), minProperties: 1 }
+}, ['id', 'changes'], false);
+
+exports.run = async function(args, context) {
+	// Preserve the API partial-update contract without fetching stale fields.
+	const { ticket } = await context.callAPI('update_ticket', { ...args.changes, id: args.id });
+	return { ticket: S.pick(ticket, S.ticketSummary) };
+};

package/lib/mcp/transports/http.js

@@ -0,0 +1,76 @@
+// Thin Node listener: do not read or parse the body before the MCP adapter.
+const http = require('node:http');
+const https = require('node:https');
+const fs = require('node:fs');
+const { createMcpHandler } = require('@modelcontextprotocol/server');
+const { toNodeHandler, hostHeaderValidation } = require('@modelcontextprotocol/node');
+
+module.exports = async function startHTTP(factory, options) {
+	// Check only the header shape here. xyOps validates the key and enforces
+	// privileges when the tool calls its API; there is no separate MCP secret.
+	function bearerKey(authorization) {
+		return /^Bearer +([A-Za-z0-9._~+\/-]+=*)$/i.exec(authorization || '')?.[1];
+	}
+	const handler = createMcpHandler(request => {
+		const apiKey = bearerKey(request.requestInfo.headers.get('authorization'));
+		if (!apiKey) throw new Error('Missing xyOps API key.');
+		return factory({ apiKey });
+	}, {
+		// Auto returns JSON for ordinary calls and preserves streamed messages
+		// if a future tool needs progress notifications during its response.
+		responseMode: 'auto', maxRequestBodySize: options.max_request_bytes,
+		maxSubscriptions: 0, onerror: () => options.log('MCP protocol error on HTTP request.')
+	});
+	const nodeHandler = toNodeHandler(handler, { maxRequestBodySize: options.max_request_bytes, onerror: () => options.log('MCP HTTP adapter error.') });
+	const validateHost = hostHeaderValidation(options.allowed_hosts);
+	
+	function respond(response, status, text) {
+		response.writeHead(status, { 'Content-Type': 'text/plain', 'Cache-Control': 'no-store' });
+		response.end(text);
+	}
+	
+	function request(request, response) {
+		// Route before dispatch. The SDK owns protocol method/status semantics.
+		if (request.url.split('?')[0] !== '/mcp') return respond(response, 404, 'Not found');
+		if (!validateHost(request, response)) return;
+		const origin = request.headers.origin;
+		if (origin && !options.allowed_origins.includes(origin)) return respond(response, 403, 'Origin not allowed');
+		if (!bearerKey(request.headers.authorization)) {
+			response.setHeader('WWW-Authenticate', 'Bearer');
+			return respond(response, 401, 'Supply a xyOps API key as a Bearer token');
+		}
+		response.setHeader('Cache-Control', 'no-store');
+		nodeHandler(request, response).catch(function() {
+			options.log('MCP HTTP request failed.');
+			if (!response.headersSent) respond(response, 500, 'Internal server error');
+			else response.destroy();
+		});
+	}
+	
+	const server = options.tls_cert ? https.createServer({ cert: fs.readFileSync(options.tls_cert), key: fs.readFileSync(options.tls_key) }, request) : http.createServer(request);
+	server.requestTimeout = 30000;
+	server.headersTimeout = 15000;
+	server.maxConnections = 100;
+	await new Promise((resolve, reject) => {
+		server.once('error', reject);
+		server.listen(options.port, options.host, function() {
+			server.removeListener('error', reject);
+			resolve();
+		});
+	});
+	
+	let closing;
+	return {
+		address: server.address(),
+		close() {
+			// Stop new requests first, then cancel MCP exchanges and close sockets.
+			if (!closing) closing = (async function() {
+				const closed = new Promise(resolve => server.close(resolve));
+				await handler.close();
+				server.closeAllConnections();
+				await closed;
+			})();
+			return closing;
+		}
+	};
+};

package/lib/mcp/transports/stdio.js

@@ -0,0 +1,7 @@
+// The SDK exclusively owns stdin/stdout. Diagnostics always use stderr.
+const { serveStdio, StdioServerTransport } = require('@modelcontextprotocol/server/stdio');
+
+module.exports = function startStdio(factory, options) {
+	const transport = new StdioServerTransport(process.stdin, process.stdout, { maxBufferSize: options.max_request_bytes });
+	return serveStdio(factory, { transport, maxSubscriptions: 0, onerror: () => options.log('MCP protocol error on stdin.') });
+};

package/lib/mcp.js

@@ -0,0 +1,120 @@
+// Dedicated MCP startup avoids terminal behavior in the interactive CLI.
+const { parseArgs } = require('node:util');
+const os = require('node:os');
+const pkg = require('../package.json');
+
+const HELP = `Usage:
+  xy mcp stdio [--read-only]
+  xy mcp serve [--port 8080] [--host 127.0.0.1] [--read-only]
+
+Uses the existing CLI configuration and XYOPS_BASE_URL. STDIO uses XYOPS_API_KEY.
+HTTP endpoint: /mcp. Clients supply their xyOps API key as a Bearer token.
+Remote binds also require allowed_hosts in the mcp configuration section.
+TLS options: --tls-cert FILE --tls-key FILE. See xy help mcp for details.
+`;
+
+function configuration(config, args) {
+	if (config.mcp !== undefined && (!config.mcp || typeof config.mcp !== 'object' || Array.isArray(config.mcp))) throw new Error('MCP configuration must be an object.');
+	const values = { ...config.mcp };
+	// Nested config stays readable in cli.json. Environment overrides use flat
+	// names, matching the CLI's existing XYOPS_* loader.
+	for (const key of ['host', 'port', 'read_only', 'max_page_size', 'max_result_bytes', 'max_request_bytes', 'tls_cert', 'tls_key']) {
+		if (config['mcp_' + key] !== undefined) values[key] = config['mcp_' + key];
+	}
+	for (const key of ['host', 'port', 'read-only', 'tls-cert', 'tls-key']) {
+		if (args[key] !== undefined) values[key.replaceAll('-', '_')] = args[key];
+	}
+	const options = {
+		host: '127.0.0.1', port: 8080, read_only: false,
+		max_page_size: 100, max_result_bytes: 1048576, max_request_bytes: 1048576,
+		allowed_hosts: ['localhost', '127.0.0.1', '[::1]'], allowed_origins: [], ...values
+	};
+	for (const key of ['port', 'max_page_size', 'max_result_bytes', 'max_request_bytes']) {
+		options[key] = Number(options[key]);
+		const max = key === 'port' ? 65535 : (key === 'max_page_size' ? 100 : 16 * 1024 * 1024);
+		if (!Number.isInteger(options[key]) || options[key] < 1 || options[key] > max) throw new Error('Invalid MCP ' + key);
+	}
+	if (typeof options.host !== 'string' || !options.host) throw new Error('Invalid MCP host');
+	if (typeof options.read_only !== 'boolean') throw new Error('MCP read_only must be a boolean');
+	for (const key of ['allowed_hosts', 'allowed_origins']) {
+		if (!Array.isArray(options[key]) || options[key].some(value => typeof value !== 'string' || !value)) throw new Error('MCP ' + key + ' must be an array of strings');
+	}
+	if (!!options.tls_cert !== !!options.tls_key) throw new Error('Supply both tls_cert and tls_key');
+	return options;
+}
+
+async function main(argv) {
+	// Give the long-running MCP server a recognizable name in process lists.
+	process.title = 'xyOps MCP Server';
+	
+	const { values, positionals } = parseArgs({ args: argv, allowPositionals: true, options: {
+		port: { type: 'string' }, host: { type: 'string' }, 'read-only': { type: 'boolean' },
+		'tls-cert': { type: 'string' }, 'tls-key': { type: 'string' },
+		help: { type: 'boolean', short: 'h' }, verbose: { type: 'boolean', short: 'v' },
+		debug: { type: 'boolean', short: 'd' }, quiet: { type: 'boolean', short: 'q' }
+	} });
+	if (values.help || positionals[0] === 'help') { process.stdout.write(HELP); return; }
+	const mode = positionals[0];
+	if (!['stdio', 'serve'].includes(mode) || positionals.length !== 1) throw new Error('Use xy mcp stdio or xy mcp serve --port 8080. Run xy mcp --help for details.');
+	if (Number(process.versions.node.split('.')[0]) < 20) throw new Error('MCP requires Node.js 20 or newer.');
+	
+	const app = {};
+	require('./config.js').loadConfig.call(app);
+	const config = app.config;
+	if (!config.base_url) throw new Error('Configure XYOPS_BASE_URL or base_url in cli.json.');
+	if (mode === 'stdio' && !config.api_key) throw new Error('Configure XYOPS_API_KEY or api_key in cli.json for STDIO.');
+	const options = configuration(config, values);
+	if (mode === 'serve' && !['127.0.0.1', '::1', 'localhost'].includes(options.host)) {
+		if (!config.mcp?.allowed_hosts?.length) throw new Error('Remote HTTP binds require explicit mcp.allowed_hosts.');
+	}
+	
+	// Identify MCP traffic in xyOps logs, preserving an explicit override.
+	if (!process.env.XYOPS_USER_AGENT) {
+		process.env.XYOPS_USER_AGENT = `xyOps MCP v${pkg.version} (Node.js); ${os.hostname()} (${os.platform()}/${os.arch()})`;
+	}
+	
+	// Initialize the SDK only after config is loaded so timeout settings apply.
+	// Never inherit a retry policy which could duplicate a create/run request.
+	process.env.XYOPS_RETRIES = '0';
+	const { api } = require('@pixlcore/xyops-sdk');
+	api.request.setRetries(0);
+	const context = require('./mcp/context.js').createContext(api, { ...options, api_key: mode === 'stdio' ? config.api_key : undefined });
+	const tools = require('./mcp/registry.js')();
+	const factory = require('./mcp/server.js')(tools, context);
+	const start = require('./mcp/transports/' + (mode === 'stdio' ? 'stdio' : 'http') + '.js');
+	const service = await start(factory, { ...options, log: context.log });
+	if (mode === 'serve') {
+		// IPv6 bind addresses are unbracketed, but URLs require brackets to
+		// separate the address from the port.
+		const hostname = options.host.includes(':') ? '[' + options.host + ']' : options.host;
+		context.log('Listening at ' + (options.tls_cert ? 'https' : 'http') + '://' + hostname + ':' + service.address.port + '/mcp');
+	}
+	
+	await new Promise(resolve => {
+		let closing = false;
+		const stop = async function() {
+			if (closing) return;
+			closing = true;
+			// A request already accepted upstream may still complete. Shutdown does
+			// not abort xyOps jobs or claim that a cancelled mutation was rolled back.
+			const timer = setTimeout(() => process.exit(1), 5000);
+			timer.unref();
+			try { await service.close(); }
+			catch (err) { context.log(err.message); process.exitCode = 1; }
+			finally {
+				clearTimeout(timer);
+				api.request.setKeepAlive(false);
+				for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.removeListener(signal, stop);
+				process.stdin.removeListener('end', stop);
+				resolve();
+			}
+		};
+		for (const signal of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.once(signal, stop);
+		if (mode === 'stdio') {
+			process.stdin.once('end', stop);
+			if (process.stdin.readableEnded) stop();
+		}
+	});
+}
+
+module.exports = { main, configuration };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@pixlcore/xycli",
-	"version": "1.1.1",
+	"version": "1.2.1",
 	"description": "A complete command-line interface for the xyOps workflow automation system.",
 	"author": "Joseph Huckaby <jhuckaby@pixlcore.com>",
 	"homepage": "https://github.com/pixlcore/xycli",
@@ -21,21 +21,23 @@
 	],
 	"scripts": {
 		"test": "node test.js",
-		"test:offline": "node --test test/config.test.js test/help.test.js test/markdown.test.js test/sync-buckets-unit.test.js test/sync-syshook-unit.test.js test/sync-unit.test.js test/toast.test.js test/upgrade.test.js test/utils-unit.test.js",
+		"test:offline": "node --test test/config.test.js test/help.test.js test/jobs-follow-unit.test.js test/markdown.test.js test/sync-buckets-unit.test.js test/sync-syshook-unit.test.js test/sync-unit.test.js test/toast.test.js test/upgrade.test.js test/utils-unit.test.js test/mcp-tools-unit.test.js test/mcp-stdio-unit.test.js test/mcp-http-unit.test.js",
 		"changelog": "node tools/changelog.js"
 	},
 	"overrides": {
 		"basic-ftp": "6.2.1"
 	},
 	"dependencies": {
-		"@pixlcore/xyops-sdk": "^1.0.7",
+		"@pixlcore/xyops-sdk": "^1.0.8",
 		"cli-highlight": "2.1.11",
 		"diff": "9.0.0",
 		"pixl-cli": "^1.1.6",
 		"html-to-text": "10.0.1",
 		"marked": "15.0.12",
 		"marked-terminal": "7.3.0",
-		"uncatch": "^1.0.4"
+		"uncatch": "^1.0.4",
+		"@modelcontextprotocol/server": "^2.4.0",
+		"@modelcontextprotocol/node": "^2.1.2"
 	},
 	"publishConfig": {
 		"access": "public"