@pixlcore/xyext-mcp 0.0.0-stage → 1.0.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 PixlCore LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+<p align="center"><img src="https://raw.githubusercontent.com/pixlcore/xyext-mcp/refs/heads/main/logo.png" height="160" alt="MCP Server for xyOps"/></p>
+<h1 align="center">MCP Server for xyOps</h1>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect your AI assistant directly to xyOps. This extension adds a Model Context Protocol (MCP) server at `/mcp` on your conductor's existing URL, with tools for events, jobs, tickets, alert invocations, monitoring snapshots, and servers.
+
+The extension includes [xyCLI](https://github.com/pixlcore/xycli) as a dependency and runs its MCP HTTP server locally. It works with Docker and manual xyOps installations. You do not need a global CLI installation, a separate container, or an additional published port.
+
+## Installation
+
+Requires **xyOps 1.1.11 or later**.
+
+Install **MCP Server** from the xyOps Marketplace. Installing the extension enables it automatically after the conductor restarts. No configuration is required for the default setup.
+
+For unpublished development versions, use the [local extension development instructions](https://github.com/pixlcore/xyops/blob/main/docs/ext.md#local-development). The package name is `@pixlcore/xyext-mcp` and its runtime ID is `pixlcore-xyext-mcp`.
+
+## Connect Your AI Assistant
+
+Choose **Streamable HTTP** in your MCP client and use your conductor's URL with `/mcp` appended:
+
+```text
+https://xyops.example.com/mcp
+```
+
+Configure this request header in your client:
+
+```text
+Authorization: Bearer YOUR_XYOPS_API_KEY
+```
+
+Each client supplies its own xyOps API key. The extension forwards it to xyCLI, and xyOps validates the key and enforces its permissions and resource restrictions when tools call the API. There is no shared server API key to configure. Choose the permissions you want to grant the assistant when creating its key in xyOps.
+
+To explore the tool list and make calls manually, launch [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```sh
+npx @modelcontextprotocol/inspector
+```
+
+Select Streamable HTTP, enter your conductor's `/mcp` URL, and configure the Bearer authorization header. See the [xyCLI MCP guide](https://github.com/pixlcore/xycli/blob/main/docs/mcp.md) for tool descriptions and more client examples.
+
+## Configuration
+
+The only setting is `port`, which defaults to `5524`. This is the private port used by the internal service on `127.0.0.1`. Clients always connect through the xyOps conductor's `/mcp` endpoint.
+
+To choose another port, merge this into your xyOps configuration, preserving any existing extension settings:
+
+```json
+{
+	"extensions": {
+		"pixlcore-xyext-mcp": {
+			"port": 5525
+		}
+	}
+}
+```
+
+Restart the conductor to apply the change. Choose an unused port between `1` and `65535`, different from `WebServer.port`. In Docker, the equivalent environment option is:
+
+```sh
+-e XYOPS_extensions__pixlcore-xyext-mcp__port=5525
+```
+
+Remove the extension through the Marketplace when you no longer want the MCP endpoint.
+
+## Deployment Notes
+
+- The child connects back to xyOps at `http://127.0.0.1:PORT`. The conductor's HTTP listener must be accessible on loopback.
+- External clients use the conductor's existing HTTPS listener or reverse proxy. Do not publish the internal MCP child port.
+- Browser requests with an `Origin` header must match the origin of xyOps's `base_app_url`. Desktop agents that omit this header can connect normally.
+- Extensions run on the primary conductor. In a multi-conductor cluster with a load balancer, route `/mcp` to the current primary.
+- If you use an authentication gateway, allow `/mcp` to use Bearer API-key authentication. Browser login redirects cannot authenticate an MCP client.
+
+The extension launches its dependency using the conductor's Node.js executable. Node's module resolution handles both ordinary NPM dependency layouts and development symlinks. Child diagnostics are written to `logs/Extension.log` with the category column set to `pixlcore-xyext-mcp`.
+
+The endpoint returns `503` while the child is unavailable. An unexpected child exit is logged and requires a conductor restart; requests are not automatically replayed. During shutdown, the extension removes its URI handler, closes its proxy connections, and sends SIGTERM to the child without waiting for it.
+
+## Development Tests
+
+Install the package dependencies and run the tests against a development xyOps checkout:
+
+```sh
+XYOPS_ROOT=/path/to/xyops npm test
+```
+
+Without `XYOPS_ROOT`, the tests look for a sibling `xyops` checkout beside the parent `xyplugs` directory. They use that checkout's web-server dependencies, the extension's actual xyCLI dependency, and an isolated API fixture. They do not require a running conductor or real API keys.
+
+The tests cover startup and shutdown, custom ports, port conflicts, concurrent client credentials, JSON and SSE forwarding, missing or invalid credentials, rejected origins, and disconnect cleanup.
+
+## Privacy
+
+This extension does not collect telemetry or send data to an external service. Tool requests and results travel between your MCP client and xyOps through a local child process. Your AI application may send results to its model provider according to that application's configuration and policies.
+
+## License
+
+MIT. See [LICENSE.md](LICENSE.md). xyCLI and its dependencies retain their own licenses.

package/index.js

@@ -0,0 +1,200 @@
+// MCP Extension for xyOps
+// Copyright (c) 2026 PixlCore LLC
+// MIT License
+
+const cp = require('child_process');
+const http = require('http');
+
+module.exports = {
+	
+	init() {
+		// Extensions are loaded on the primary. Installing this package enables
+		// MCP without any additional service or global CLI installation.
+		this.shut = false;
+		this.xy.web.addURIHandler('/mcp', '@pixlcore/xyext-mcp', this.handleMCP.bind(this));
+		this.startLocalMCP();
+	},
+	
+	startLocalMCP() {
+		// One long-lived HTTP server, with credentials scoped to each request.
+		if (this.mcpChild || this.shut) return;
+		const webPort = Number(this.server.config.getPath('WebServer.port'));
+		
+		const port = Number(this.config.port ?? 5524);
+		if (!Number.isInteger(port) || port < 1 || port > 65535 || port === webPort) {
+			return this.logDebug(1, 'Cannot launch local MCP: Invalid MCP port (must differ from WebServer.port).');
+		}
+		
+		// Strip conductor settings BEFORE adding CLI settings. Do not supply a
+		// service API key: every HTTP caller must provide its own Bearer token.
+		const env = this.xy.cleanEnv();
+		env.XYOPS_BASE_URL = 'http://127.0.0.1:' + webPort;
+		env.XYOPS_API_KEY = '';
+		
+		// The SDK must reach the conductor directly, even on hosts configured
+		// with a corporate outbound proxy. Set both spellings for compatibility.
+		env.NO_PROXY = env.no_proxy = '127.0.0.1,localhost,::1';
+		env.XYOPS_MCP_TLS_CERT = '';
+		env.XYOPS_MCP_TLS_KEY = '';
+		
+		let origin;
+		try { origin = new URL(this.server.config.get('base_app_url')).origin; }
+		catch (err) { return this.logDebug(1, 'Cannot launch local MCP: Invalid base_app_url.'); }
+		env.XYOPS_MCP = JSON.stringify({ allowed_hosts: ['127.0.0.1'], allowed_origins: [origin] });
+		
+		this.mcpPort = port;
+		this.mcpReady = false;
+		this.mcpRequests = new Set();
+		let child;
+		
+		try {
+			// Resolve from this package so NPM hoisting and development symlinks
+			// both work. Use the conductor's Node executable, never a global xy.
+			const entry = require.resolve('@pixlcore/xycli');
+			child = cp.spawn(process.execPath, [entry, 'mcp', 'serve', '--host', '127.0.0.1', '--port', String(port)], {
+				env, stdio: ['ignore', 'pipe', 'pipe']
+			});
+		}
+		catch (err) {
+			this.logDebug(1, 'Cannot launch local MCP: ' + err.message);
+			return;
+		}
+		
+		this.mcpChild = child;
+		this.logDebug(2, 'Starting local MCP HTTP server on loopback port ' + port);
+		
+		// Only mark ready after this child announces its successful bind. A
+		// service already occupying the port must never receive client keys.
+		const readyLine = 'xy mcp: Listening at http://127.0.0.1:' + port + '/mcp';
+		
+		for (const stream of [child.stdout, child.stderr]) {
+			stream.setEncoding('utf8');
+			let pending = '';
+			
+			stream.on('data', chunk => {
+				pending += chunk;
+				let index;
+				
+				while ((index = pending.indexOf('\n')) >= 0) {
+					const line = pending.slice(0, index).trim();
+					pending = pending.slice(index + 1);
+					
+					if (line === readyLine && !this.shut && child.exitCode === null && child.signalCode === null) this.mcpReady = true;
+					if (line) this.logDebug(5, 'MCP: ' + line);
+				}
+				
+				// Bound buffering even if a diagnostic never includes a newline.
+				if (pending.length > 8192) { this.logDebug(5, 'MCP: ' + pending.slice(0, 8192)); pending = ''; }
+			});
+			stream.on('end', () => { if (pending) this.logDebug(5, 'MCP: ' + pending); });
+		}
+		
+		child.on('error', err => {
+			this.mcpReady = false;
+			this.logDebug(1, 'Local MCP process error: ' + err.message);
+		});
+		
+		child.on('exit', (code, signal) => {
+			this.mcpReady = false;
+			for (const request of this.mcpRequests) request.destroy();
+			this.logDebug(this.shut ? 3 : 1, 'Local MCP process exited', { code, signal });
+		});
+		
+		child.on('close', () => { if (this.mcpChild === child) this.mcpChild = null; });
+	},
+	
+	handleMCP(args, callback) {
+		// The web server has already consumed the request body. Reuse its bytes
+		// and calculate a fresh Content-Length instead of piping an empty input.
+		const { request, response } = args;
+		const fail = (status, message) => callback(status, { 'Content-Type': 'text/plain', 'Cache-Control': 'no-store' }, message);
+		
+		if (!this.xy.master || this.xy.shut || this.shut || !this.mcpReady) return fail('503 Service Unavailable', 'Local MCP server is unavailable.');
+		
+		if (!['POST', 'GET', 'DELETE'].includes(request.method)) {
+			return callback('405 Method Not Allowed', { Allow: 'POST, GET, DELETE' }, 'Method not allowed.');
+		}
+		
+		if (request.method === 'POST' && !/^application\/json(?:\s*;|$)/i.test(request.headers['content-type'] || '')) {
+			return fail('415 Unsupported Media Type', 'MCP requests must use application/json.');
+		}
+		
+		// Preserve MCP and authentication headers only. Cookies, forwarded
+		// identity headers, and hop-by-hop headers do not belong on this hop.
+		const headers = {};
+		for (const name of ['authorization', 'accept', 'content-type', 'content-encoding', 'origin', 'mcp-protocol-version', 'mcp-session-id', 'last-event-id']) {
+			if (request.headers[name] !== undefined) headers[name] = request.headers[name];
+		}
+		
+		const body = request.method === 'POST' ? (request.body || Buffer.from(JSON.stringify(args.params))) : null;
+		if (body) headers['content-length'] = body.length;
+		
+		let completed = false;
+		let upstream;
+		
+		const finish = () => {
+			if (completed) return;
+			completed = true;
+			this.mcpRequests.delete(upstream);
+			response.removeListener('finish', finish);
+			response.removeListener('close', disconnect);
+			args.perf.end('process');
+			callback(true);
+		};
+		
+		const disconnect = () => { upstream.destroy(); finish(); };
+		
+		upstream = http.request({
+			hostname: '127.0.0.1', port: this.mcpPort, path: '/mcp',
+			method: request.method, headers, agent: false
+		}, incoming => {
+			// Stream JSON or SSE verbatim. Strip connection-specific headers,
+			// including any additional names nominated by Connection itself.
+			const excluded = new Set(['connection', 'keep-alive', 'proxy-authenticate', 'proxy-authorization', 'te', 'trailer', 'transfer-encoding', 'upgrade']);
+			for (const name of String(incoming.headers.connection || '').split(',')) excluded.add(name.trim().toLowerCase());
+			
+			const output = {};
+			for (const name in incoming.headers) { if (!excluded.has(name)) output[name] = incoming.headers[name]; }
+			
+			response.writeHead(incoming.statusCode, output);
+			response.flushHeaders();
+			
+			incoming.on('data', chunk => args.perf.count('bytes_out', chunk.length));
+			incoming.on('error', () => response.destroy());
+			incoming.pipe(response);
+		});
+		
+		this.mcpRequests.add(upstream);
+		
+		response.once('finish', finish);
+		response.once('close', disconnect);
+		
+		upstream.setTimeout(120000, () => upstream.destroy(new Error('MCP upstream timeout')));
+		
+		upstream.on('error', err => {
+			if (completed) return;
+			this.logDebug(3, 'MCP upstream request failed: ' + err.message);
+			if (response.headersSent) response.destroy();
+			else {
+				response.writeHead(502, { 'Content-Type': 'text/plain', 'Cache-Control': 'no-store' });
+				response.end('Local MCP server request failed.');
+			}
+		});
+		
+		upstream.end(body);
+	},
+	
+	shutdown() {
+		// Extension shutdown is fire-and-forget. Stop admitting requests, remove
+		// our route and signal the attached child without blocking the conductor.
+		this.shut = true;
+		this.mcpReady = false;
+		this.xy.web.removeURIHandler('@pixlcore/xyext-mcp');
+		
+		for (const request of this.mcpRequests || []) request.destroy();
+		
+		const child = this.mcpChild;
+		if (child && child.exitCode === null && child.signalCode === null) child.kill('SIGTERM');
+	}
+	
+};

package/package.json

@@ -1,6 +1,37 @@
 {
-  "name": "@pixlcore/xyext-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+	"name": "@pixlcore/xyext-mcp",
+	"version": "1.0.0",
+	"description": "Connect AI assistants to xyOps with an HTTP MCP server.",
+	"author": "Joseph Huckaby <jhuckaby@pixlcore.com>",
+	"homepage": "https://github.com/pixlcore/xyext-mcp",
+	"license": "MIT",
+	"main": "index.js",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/pixlcore/xyext-mcp"
+	},
+	"bugs": {
+		"url": "https://github.com/pixlcore/xyext-mcp/issues"
+	},
+	"keywords": [
+		"xyops",
+		"extension",
+		"mcp"
+	],
+	"overrides": {
+		"basic-ftp": "6.2.1"
+	},
+	"dependencies": {
+		"@pixlcore/xycli": "^1.2.1"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"files": [
+		"index.js",
+		"xyops.json"
+	],
+	"scripts": {
+		"test": "node --test test/mcp-proxy.test.js"
+	}
+}

package/xyops.json

@@ -0,0 +1,15 @@
+{
+	"type": "xypdf",
+	"description": "xyOps Portable Data Object",
+	"version": "1.0",
+	"xyops": "1.1.11",
+	"items": [
+		{
+			"type": "extension",
+			"data": {
+				"id": "pixlcore/xyext-mcp",
+				"version": "v1.0.0"
+			}
+		}
+	]
+}