@pixlcore/xycli 1.1.0 → 1.2.0

package/.dockerignore

@@ -0,0 +1,13 @@
+# Include only the files needed to run xyCLI and display its documentation.
+# In particular, never copy host node_modules, credentials, or test fixtures.
+*
+!package.json
+!package-lock.json
+!index.js
+!lib/
+!lib/**
+!docs/
+!docs/**
+!README.md
+!CHANGELOG.md
+!logo.webp

package/.github/workflows/docker.yml

@@ -0,0 +1,64 @@
+name: Publish Docker Image
+
+on:
+  push:
+    tags: [ '*' ]
+
+permissions:
+  contents: read
+  packages: write
+  # Required for GitHub's keyless Sigstore artifact attestation.
+  id-token: write
+  attestations: write
+  # Required to register the attested image in GitHub's linked artifact inventory.
+  artifact-metadata: write
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v4
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v4
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v4
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract image metadata
+        id: meta
+        uses: docker/metadata-action@v6
+        with:
+          images: ghcr.io/${{ github.repository }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=ref,event=tag
+            type=sha
+
+      - name: Build and push (multi-arch)
+        id: push
+        uses: docker/build-push-action@v7
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+
+      # Sign the exact multi-platform image digest that Buildx pushed to GHCR.
+      - name: Generate build provenance attestation
+        uses: actions/attest@v4
+        with:
+          subject-name: ghcr.io/${{ github.repository }}
+          subject-digest: ${{ steps.push.outputs.digest }}
+          push-to-registry: true

package/.github/workflows/offline-tests.yml

@@ -19,7 +19,7 @@ jobs:
           - ubuntu-latest
           - windows-latest
         node:
-          - 20.19.0
+          - 22
           - 24
 
     steps:

package/Dockerfile

@@ -0,0 +1,45 @@
+FROM node:24-bookworm-slim
+
+LABEL org.opencontainers.image.source="https://github.com/pixlcore/xycli"
+LABEL org.opencontainers.image.description="The xyOps command-line interface and MCP server."
+LABEL org.opencontainers.image.licenses="MIT"
+
+ENV DEBIAN_FRONTEND=noninteractive
+
+# Keep the runtime small: no worker tools, compilers, or Docker CLI are needed.
+# Remove apt caches in the same layer that installs the certificate bundle.
+RUN set -eu; \
+	apt-get update; \
+	apt-get install -y --no-install-recommends ca-certificates; \
+	apt-get clean; \
+	rm -rf /var/lib/apt/lists/*
+
+WORKDIR /opt/xycli
+
+ENV NODE_ENV=production
+
+# Install the tagged checkout's locked dependencies, rather than fetching an
+# unrelated CLI release from npm. Source edits can reuse the dependency layer.
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev \
+	&& npm cache clean --force
+
+# .dockerignore includes only runtime source and documentation, so local
+# node_modules links, test fixtures, and private configuration stay outside.
+COPY . .
+
+# Keep the application read-only for the runtime user, with a writable working
+# directory for commands that export or sync files.
+RUN ln -s /opt/xycli/index.js /usr/local/bin/xy \
+	&& mkdir -p /workspace \
+	&& chown node:node /workspace
+
+USER node
+WORKDIR /workspace
+
+EXPOSE 8080/tcp
+
+# Arguments after the image name replace CMD, allowing any xyCLI command.
+# HTTP needs an explicit allowed_hosts list supplied in XYOPS_MCP or cli.json.
+ENTRYPOINT ["xy"]
+CMD ["mcp", "serve", "--host", "0.0.0.0", "--port", "8080"]

package/README.md

@@ -23,6 +23,7 @@ Browse the [screenshot gallery](docs/screenshots.md) for more views, or jump to
 ## Contents
 
 - [Getting started](#getting-started)
+- [Docker](#docker)
 - [Configuration](#configuration)
 - [Global CLI switches](#global-cli-switches)
 - [Tutorial: your first Event, job, and Web Hook](docs/tutorial.md)
@@ -33,6 +34,7 @@ Browse the [screenshot gallery](docs/screenshots.md) for more views, or jump to
 - [Sync your automation with local files](#sync-your-automation-with-local-files)
 - [System operations and logs](#system-operations-and-logs)
 - [Documentation and API access](#documentation-and-api-access)
+- [MCP server for AI applications](docs/mcp.md)
 
 ## Getting started
 
@@ -67,6 +69,25 @@ xy
 
 You should see the dashboard. If you need to set up xyOps itself, start with its [Getting Started guide](https://docs.xyops.io/start). See [API Keys](https://docs.xyops.io/api#api-keys) for authentication details and [Privileges](https://docs.xyops.io/privileges) for permissions.
 
+## Docker
+
+The `ghcr.io/pixlcore/xycli` image includes Node.js and xyCLI, so you only need Docker installed on your machine. It supports Linux AMD64 and ARM64. Images are built from the source checkout on Git tag pushes and published with the Git tag, `latest`, and a `sha-` tag.
+
+The image's entrypoint is `xy`. Pass a CLI command after the image name, for example:
+
+```sh
+docker run --rm -it \
+	-e XYOPS_BASE_URL="https://xyops.example.com" \
+	-e XYOPS_API_KEY="YOUR_API_KEY" \
+	ghcr.io/pixlcore/xycli:latest events
+```
+
+Without a command override, the container starts the MCP HTTP server. See [Running MCP with Docker](docs/mcp.md#running-with-docker) for a complete startup command and STDIO usage.
+
+The container runs as the `node` user (UID 1000), with `/workspace` as its working directory. For file exports, imports, or sync, mount your working files there with `-v "$PWD:/workspace"` and ensure that user can access them. You can also mount an existing CLI configuration file read-only at `/home/node/.config/xyops/cli.json`. Custom sync completion commands need any external programs they invoke; Git and worker tools are not bundled in this image.
+
+To upgrade, pull the new image and recreate the container. Use a specific Git tag instead of `latest` when you want to pin a release. For a local build from this repository, run `docker build -t xycli:local .` and substitute `xycli:local` in the examples.
+
 ## Configuration
 
 xyCLI loads optional JSON configuration files on every invocation, then applies environment variables. Settings are merged in this order:

package/docs/help.md

@@ -25,6 +25,8 @@ xy tickets
 xy hooks
 xy marketplace
 xy upgrade
+xy mcp stdio
+xy mcp serve --port 8080
 xy event EVENT_ID --export event.json
 xy import event.json
 xy sync ./ --up events,plugins --dry
@@ -394,6 +396,8 @@ Updates load the user file separately and apply only the settings specified on t
 
 Configuration loads the machine file first, then the user file, then `XYOPS_`-prefixed environment variables. The machine and user files are `/etc/xyops/cli.json` and `~/.config/xyops/cli.json` on Unix and macOS, or `%PROGRAMDATA%\xyops\cli.json` and `%USERPROFILE%\.config\xyops\cli.json` on Windows. Later sources override matching top-level settings. Environment overrides still take precedence over saved user settings. Common keys include `api_key`, `base_url`, `temp_dir`, `color`, `suggest`, `items_per_page`, `cache_ttl`, `raw`, and `invisible`.
 
+Environment values that look like JSON objects or arrays are parsed automatically for any setting. For example, `XYOPS_SYNC='{"up":["events"],"down":false}'` supplies a structured `sync` setting. Boolean and numeric values keep their usual conversions. Malformed JSON-looking values report the environment variable name. Objects and arrays are serialized as JSON when the CLI exports its effective configuration back into the environment.
+
 ## doc
 
 Fetch and display xyOps documentation in the terminal. Run the command without a document name to browse the documentation index. Specify a document to read it in full, or add a chapter slug to focus on one section and all of its sub-sections.
@@ -2635,3 +2639,22 @@ Default output shows complete bracket-delimited log lines using the server's con
 The search selects the last N matches before applying the display order, so `--sort date_asc` does not select the earliest N matches. There is no numbered pagination; use `--rows` rather than `--limit`, `--offset`, or `--page`. The summary's total row count includes non-matching lines.
 
 Missing logs or archives return an empty result. `--dry` previews the search. To view a particular Job's output instead, use `xy job log JOB_ID`.
+
+# mcp
+
+Connect AI applications to xyOps using xyOps API keys. Requires Node.js 20 or newer.
+
+```sh
+xy mcp stdio
+xy mcp serve --port 8080
+xy mcp stdio --read-only
+xy mcp serve --port 8443 --tls-cert /path/to/server.crt --tls-key /path/to/server.key
+```
+
+STDIO is for applications that launch a local process. HTTP exposes `/mcp` on `127.0.0.1` by default. The `mcp` prefix is required; pass the port with `--port`. Use `--host` to choose another bind address. Every HTTP request requires the client's xyOps API key as a bearer token, including loopback connections. Non-loopback binds additionally require explicit `mcp.allowed_hosts`; there is no separate MCP authentication token.
+
+Both modes expose event discovery, creation, updates, deletion, execution and job inspection/search. `--read-only` omits and blocks mutation/execution tools. Every API call still uses your key's existing privileges and resource restrictions.
+
+STDIO uses your configured `XYOPS_API_KEY`. HTTP clients send their own xyOps API key as `Authorization: Bearer YOUR_XYOPS_API_KEY`; each request forwards that key to xyOps, with no fallback to the server's configured key. MCP owns stdin/stdout and does not support interactive CLI options such as `--dry` or `--format`. Diagnostics go to stderr.
+
+See [MCP Server](mcp.md) for configuration, tools, deployment and tool-authoring details.

package/docs/mcp.md

@@ -0,0 +1,224 @@
+# MCP Server
+
+xyCLI connects AI applications to xyOps through the Model Context Protocol (MCP). Both transports use your normal CLI connection settings. STDIO uses your configured API key; HTTP uses the key supplied by each client. xyOps enforces that key's privileges and resource restrictions on every API operation.
+
+## Quick start
+
+First, if you haven't already done so, follow [Getting started](../README.md#getting-started) to install Node.js and xyCLI, then configure your xyOps connection and API key. Alternatively, use the [Docker image](#running-with-docker), which includes Node.js and xyCLI.
+
+For an application that launches a local MCP process, configure its executable as `xy` and its arguments as `mcp`, `stdio`:
+
+```sh
+xy mcp stdio
+```
+
+The STDIO server uses your existing xyCLI authentication: the `XYOPS_API_KEY` environment variable or the `api_key` setting in your `cli.json` configuration file. The environment variable takes precedence.
+
+The application launches this command and communicates through its standard streams. stdout contains only MCP messages; diagnostics go to stderr. If the application cannot find `xy`, use the absolute path reported by `which xy` on macOS/Linux or `where xy` on Windows.
+
+For a client that connects over HTTP, start a foreground server like so:
+
+```sh
+xy mcp serve --port 8080
+```
+
+Connect the client to `http://127.0.0.1:8080/mcp` and configure its `Authorization` header as `Bearer YOUR_XYOPS_API_KEY`. The `mcp` prefix is required, and the port is a named option. Stop the server with Ctrl-C.
+
+MCP requires Node.js 20 or newer. This server supports the [2026-07-28 protocol](https://blog.modelcontextprotocol.io/posts/2026-07-28/) and compatible 2025-era clients over STDIO and stateless Streamable HTTP. Legacy HTTP+SSE endpoints and persistent HTTP sessions are not provided.
+
+## Running with Docker
+
+The general-purpose `ghcr.io/pixlcore/xycli` image starts the MCP HTTP server by default. With Docker installed, this single command supplies all required server settings:
+
+```sh
+docker run --rm --init --name xycli-mcp \
+	-p 127.0.0.1:8080:8080 \
+	-e XYOPS_BASE_URL="https://xyops.example.com" \
+	-e XYOPS_MCP='{"allowed_hosts":["localhost","127.0.0.1","[::1]"]}' \
+	ghcr.io/pixlcore/xycli:latest
+```
+
+Replace `XYOPS_BASE_URL` with your xyOps URL. Connect your MCP client to `http://127.0.0.1:8080/mcp` and configure its `Authorization` header as `Bearer YOUR_XYOPS_API_KEY`. HTTP mode does not need `XYOPS_API_KEY` in the container; each client supplies its own key.
+
+The server listens on `0.0.0.0:8080` inside the container, while the example publishes it only on your host's loopback interface. For network access, configure `allowed_hosts` for the hostname your clients use, publish the appropriate interface, and provide HTTPS through a reverse proxy or the server's TLS options. `allowed_hosts` contains hostnames without port numbers, not the container's bind address.
+
+If xyOps runs on your Docker host, use `http://host.docker.internal:5522` as the base URL. On Linux, also add `--add-host=host.docker.internal:host-gateway`. `localhost` inside the container refers to the container itself.
+
+For **STDIO**, configure your MCP client to launch this command instead:
+
+```sh
+docker run --rm --init -i \
+	-e XYOPS_BASE_URL="https://xyops.example.com" \
+	-e XYOPS_API_KEY="YOUR_XYOPS_API_KEY" \
+	ghcr.io/pixlcore/xycli:latest mcp stdio
+```
+
+Keep `-i` so the client can write protocol messages to stdin, and omit `-t` so no terminal is allocated. STDIO uses the supplied API key and needs no published port or HTTP Host allowlist.
+
+Arguments after the image name replace the default `mcp serve --host 0.0.0.0 --port 8080` command. For example, append `mcp serve --host 0.0.0.0 --port 8080 --read-only` to the HTTP example for read-only access. The same image runs other CLI commands; see [Docker](../README.md#docker) for file mounts, configuration, and upgrades.
+
+## Testing with MCP Inspector
+
+[MCP Inspector](https://github.com/modelcontextprotocol/inspector) provides a browser interface for browsing tools, inspecting their inputs, and making tool calls.
+
+For **STDIO**, launch Inspector with xyCLI as its server command:
+
+```sh
+npx @modelcontextprotocol/inspector xy mcp stdio
+```
+
+Inspector launches xyCLI using your existing connection settings and API key. Open the browser URL printed in the terminal (if it doesn't automatically open it for you) and connect to the server.
+
+For **HTTP**, start xyCLI in one terminal:
+
+```sh
+xy mcp serve --port 8080
+```
+
+Then launch Inspector in another terminal:
+
+```sh
+npx @modelcontextprotocol/inspector
+```
+
+Open its browser interface and configure the connection:
+
+| Setting | Value |
+| --- | --- |
+| Transport | Streamable HTTP |
+| URL | `http://127.0.0.1:8080/mcp` |
+| Custom header name | `Authorization` |
+| Custom header value | `Bearer YOUR_XYOPS_API_KEY` |
+
+After connecting with either transport, open the Tools view and try `list_events` or `get_event_options`. Select a tool to inspect its inputs, submit a call, and view the result.
+
+## Authentication and permissions
+
+Configure the upstream URL through your normal CLI JSON file or `XYOPS_BASE_URL`. For STDIO, supply the API key through `api_key` in that file or `XYOPS_API_KEY`, just like the normal CLI. Keep keys in private configuration or environment variables, rather than prompts or command-line arguments.
+
+Each process connects to one configured xyOps installation. HTTP clients supply their own xyOps API keys using `Authorization: Bearer YOUR_XYOPS_API_KEY` on every request. Each tool forwards that client's key to xyOps as `X-API-Key`, including when a tool makes multiple API calls. Concurrent clients keep their credentials and permissions separate.
+
+HTTP mode does not require a server-side API key and never falls back to one. Missing or malformed bearer headers receive HTTP 401. xyOps rejects invalid keys and unauthorized API operations; these failures are returned as MCP tool errors. Tool discovery is local and does not validate the key upstream or filter tools by its privileges.
+
+A key can permit reading and running existing events without granting `create_events`, `edit_events`, or `delete_events`. This is read-and-execute access. For strict read-only access, also omit `run_jobs` and other write privileges. You can additionally restrict MCP itself:
+
+```sh
+xy mcp stdio --read-only
+xy mcp serve --port 8080 --read-only
+```
+
+Read-only mode omits all mutation/execution tools and rejects direct attempts to call them. Tool annotations describe behavior; actual xyOps privileges remain authoritative.
+
+There is no separate MCP authentication token. HTTP clients must support configured authorization headers. OAuth discovery and interactive login are not provided in this version.
+
+## HTTP configuration
+
+Add an `mcp` object to your existing CLI configuration:
+
+```json
+{
+	"mcp": {
+		"host": "127.0.0.1",
+		"port": 8080,
+		"read_only": false,
+		"max_page_size": 100,
+		"max_request_bytes": 1048576,
+		"max_result_bytes": 1048576
+	}
+}
+```
+
+| Setting | Default | Purpose |
+| --- | --- | --- |
+| `host` | `127.0.0.1` | Listener address. Override with `--host`. |
+| `port` | `8080` | Listener port. Override with `--port`. |
+| `allowed_hosts` | `localhost`, `127.0.0.1`, `[::1]` | Accepted Host header hostnames, without port numbers. Enclose IPv6 addresses in brackets. |
+| `allowed_origins` | Empty array | Exact allowed browser origins, including scheme and port. Requests without an Origin header are accepted. |
+| `read_only` | `false` | Advertise and accept only read tools. |
+| `max_page_size` | `100` | Maximum rows per page, from 1 to 100. |
+| `max_request_bytes` | `1048576` | Maximum protocol input size. |
+| `max_result_bytes` | `1048576` | Maximum serialized tool data size. Oversized results return an explicit error. |
+| `tls_cert`, `tls_key` | Unset | PEM certificate and key files for HTTPS. Supply both together. |
+
+Configuration environment values that look like JSON objects or arrays are parsed as JSON, including `XYOPS_MCP`. Scalar settings accept flat environment overrides such as `XYOPS_MCP_PORT`, `XYOPS_MCP_READ_ONLY`, and `XYOPS_MCP_MAX_RESULT_BYTES`. Configure host/origin arrays in the JSON file. Command-line options override environment variables, which override the `mcp` object.
+
+A non-loopback bind requires an explicit `mcp.allowed_hosts` list. Bearer API keys are required on every HTTP request, including loopback connections. Use HTTPS or a trusted reverse proxy providing TLS for network access. A non-loopback HTTP bind does not automatically encrypt traffic. No permissive browser CORS policy is enabled.
+
+For IPv6 loopback, use `xy mcp serve --host ::1 --port 8080` and connect to `http://[::1]:8080/mcp`. The bind address uses no brackets; URLs and `allowed_hosts` entries use brackets.
+
+For direct HTTPS:
+
+```sh
+xy mcp serve --port 8443 --tls-cert /path/to/server.crt --tls-key /path/to/server.key
+```
+
+This opens only the HTTPS listener. Restart after replacing certificate files. Unknown routes return 404; local files are never served.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `list_events` | Find events/workflows by title, category, type or enabled state. Returns summaries and revisions. |
+| `get_event` | Fetch a definition and revision. Optional `fields` limits returned properties. |
+| `get_event_options` | Discover categories, target groups and event plugins. Optional `plugin_id` adds parameter definitions. |
+| `create_event` | Create an ordinary event or workflow from an explicit definition. |
+| `update_event` | Apply changes using an exact ID and the revision returned by `get_event`. |
+| `delete_event` | Delete an event while retaining historical jobs. Active jobs prevent deletion. |
+| `run_event` | Launch an enabled event with a manual trigger, optionally supplying parameters and input data. |
+| `get_job` | Inspect job state, completion and output. Optional `fields` selects other job properties. |
+| `search_jobs` | Search completed jobs with query, pagination and sorting. |
+| `create_ticket` | Create a ticket with a subject, Markdown body and optional classification/assignment. |
+| `update_ticket` | Apply only supplied fields to a ticket by exact ID. |
+| `delete_ticket` | Permanently delete a ticket by exact ID. |
+| `comment_ticket` | Append a Markdown comment with the authenticated key as its author. |
+| `search_alerts` | Search active and historical alert invocations, rather than alert definitions. |
+| `search_snapshots` | Search server/group snapshots, optionally including verbose monitoring details. |
+| `take_snapshot` | Capture the latest monitoring data for exactly one server or group. |
+| `list_servers` | List connected workers, optionally filtering by hostname, group or enabled state. |
+
+Pages default to 25 rows, capped by `max_page_size`. Events, servers and lookup collections are paginated locally after fetching the authorized collection; job, alert and snapshot searches are paginated on the server. Each lookup collection has its own total and uses the requested offset/limit.
+
+Updates, deletions and executions require exact IDs. Event creation requires an explicit `enabled` value. Ordinary events require category, plugin, targets and a server-selection algorithm. Workflows require a workflow object with nodes and connections. xyOps validates the full definition and permissions.
+
+Event updates preserve omitted top-level fields. Supplied objects and arrays replace their saved values, including `params`, `triggers` and `workflow`. Read the definition first and include the values you want to retain. Stale revisions are rejected instead of silently overwriting newer changes.
+
+`run_event` returns immediately with a job ID. Use `get_job` until `final` is true, or search with `event:EVENT_ID` or `tags:_error`. Launches accept parameter overrides and `input.data`, but not arbitrary event overrides, test-mode bypasses or local-file uploads.
+
+### Tickets
+
+Create a ticket with `{"ticket":{"subject":"Backup failed","body":"Investigating the logs.","type":"issue"}}`. xyOps generates its ID, number and initial history. Ticket types and statuses follow your xyOps configuration, including custom values. This initial tool set supports text and metadata; file attachments, automatic job/alert templates and attached event definitions are not exposed.
+
+Use `update_ticket` with `{"id":"TICKET_ID","changes":{"status":"closed"}}`. Omitted fields remain unchanged, while arrays such as `assignees`, `cc`, `notify` and `tags` replace their entire lists. Empty arrays clear those lists; an empty `category` or `server` clears that link. `due` is an absolute Unix timestamp in seconds (1980 or later), or `0` to clear it. Unlike events, tickets have no revision precondition, so concurrent edits to the same field can overwrite each other.
+
+Use `comment_ticket` with `{"id":"TICKET_ID","body":"The backup is working again."}`. xyOps assigns the comment author and timestamp. Create/update return ticket summaries; comment also returns the new comment. Creating, updating and commenting may send notifications according to xyOps settings. These operations require `create_tickets`, `edit_tickets` and `delete_tickets` as appropriate; comments require `edit_tickets`.
+
+### Monitoring
+
+`search_alerts` accepts queries such as `active:true`, `server:SERVER_ID` or `start:>=today`. `search_snapshots` accepts queries such as `type:group`, `groups:GROUP_ID` or `source:alert`. Both support `query`, `offset`, `limit`, `sort_by` and `sort_dir` (`1` ascending, `-1` descending), defaulting to newest IDs first. xyOps applies the API key's resource restrictions. Snapshot search omits heavy nested details unless `verbose` is `true`; use small pages with verbose results to stay within the response size limit.
+
+`list_servers` returns connected worker summaries and IDs, excluding offline servers and conductor peers. `hostname` matches a case-insensitive substring, `group` matches an exact group ID, and `enabled` filters the enabled flag.
+
+Use `take_snapshot` with either `{"server":"SERVER_ID"}` or `{"group":"GROUP_ID"}`, never both. This requires `create_snapshots` and stores the most recent monitoring sample; it does not start a watch or force a new sample. The result includes the snapshot ID and target. Group IDs can be found in server summaries or `get_event_options`.
+
+API requests are not automatically retried. A lost connection after a mutation may leave its outcome uncertain; inspect xyOps before repeating it. Cancellation or shutdown does not undo accepted mutations or abort jobs already launched.
+
+## Adding a tool
+
+Every bundled `.js` file in `lib/mcp/tools/` exports:
+
+| Function | Contract |
+| --- | --- |
+| `describe()` | Synchronously returns `name`, `description`, a plain JSON `inputSchema`, and behavioral `annotations`. No API calls or other side effects. |
+| `async run(args, context)` | Returns a JSON-serializable object or throws. Never writes stdout, reads stdin, or exits the process. |
+
+The registry sorts and loads files once, checks exports/names, and compiles schemas. Helpers belong outside the tools directory. Duplicate names or malformed definitions stop startup.
+
+The context supplies `callAPI(name, params)`, `signal`, `log`, and `limits`. HTTP scopes this context to the incoming key. Tool modules must use `context.callAPI()` so every upstream call uses the correct credentials. Add newly required methods to the shared boundary's read/write API allowlists. Calls use the existing SDK. Cancellation prevents subsequent API calls but cannot undo requests already sent.
+
+Both transports invoke the same modules. A tool can combine API calls, simplify inputs and select useful outputs. The runtime validates arguments and returns structured data plus JSON text. Provide pagination or field selection for large results. Keep credentials and raw transport envelopes out of outputs and diagnostics.
+
+## Tests
+
+`npm run test:offline` includes schema, permission-boundary and wire-level STDIO/HTTP/HTTPS checks using fixtures. The TLS key in `test/fixtures/mcp/` is a public test fixture, never a deployment credential.
+
+`node test.js mcp` runs the live suite against `http://localhost:5522`. It requires administrator test credentials, an enabled category, the stock Shell Plugin and a connected worker. It creates disposable events/API keys and a draft ticket, runs a harmless echo job, takes server/group snapshots, verifies restricted-key behavior over STDIO and concurrent HTTP requests, and cleans up its records. Monitoring tests require a worker in a group with a saved monitoring sample. The ticket remains a draft to suppress notifications; the suite deletes only snapshots it created and verifies their removal.

package/docs/two-way-delete-tutorial.md

@@ -2,7 +2,7 @@
 
 This tutorial keeps Events, workflows, and Plugins in both xyOps and Git. Existing definitions can be edited on either side, and deletions can start on either side. New definitions are created in the xyOps UI and exported to Git. Every sync runs because Git accepted a push or xyOps recorded an activity. There are no cron jobs or recurring sync schedules.
 
-Use xyCLI version **v1.1.0+** (with down-sync delete support) and xyOps version **v1.1.3+** (with System Activity triggers). Both features must be available before you enable this workflow.
+Use xyCLI version **v1.1.1+** (with down-sync delete support) and xyOps version **v1.1.4+** (with System Activity triggers and exclusions). Both features must be available before you enable this workflow.
 
 > [!IMPORTANT]
 > **Two-way deletion requires authoritative triggers in both directions.** Run `--up --delete` only in response to an accepted Git change, and run `--down --delete` only in response to xyOps activity. Each invocation has exactly one authoritative side. A single command with both `--up` and `--down` cannot use `--delete`.
@@ -24,7 +24,7 @@ Use one persistent Git checkout on a machine running xySat. Target all three xyO
 
 You will need:
 
-- A xyOps API Key that can see the **complete** Event and Plugin inventories, update and delete those types, and update global sync state. A restricted or partial inventory is unsafe for up-only deletion.
+- A dedicated xyOps API Key for xyCLI that can see the **complete** Event and Plugin inventories, update and delete those types, and update global sync state. A restricted or partial inventory is unsafe for up-only deletion. You will select this same key in the System Activity trigger exclusions below.
 - A dedicated repository and a persistent checkout, such as `/srv/xyops-automation`, with noninteractive Git pull and push access.
 - A Git author identity for commits generated by xyOps.
 - Shared xyOps job capacity and queue limits on all three Events.
@@ -171,6 +171,8 @@ Create three Shell Plugin Events in xyOps, initially disabled. Target only the s
 | **Export creations from xyOps** | System Activity | `event_create`, `plugin_create` | `/usr/local/sbin/xyops-git-sync create` |
 | **Apply accepted Git pushes** | Manual | No activity selection | `/usr/local/sbin/xyops-git-sync up` |
 
+On **each of the two System Activity triggers**, open **Exclude Users / Keys** and select the dedicated xyCLI sync API Key configured on the worker in step 1. xyOps records the key's ID as the activity initiator and skips that trigger when the ID is excluded. This prevents an upsync API update or deletion from launching a redundant downsync job. Leave ordinary users out of the exclusion list so their UI changes still launch the appropriate job. If more than one API Key can make sync writes, exclude each of those keys on both triggers.
+
 The update activities make xyOps UI edits flow back to Git too. The separate creation Event runs `sync setup --new`, because ordinary downsync updates existing local sources but does not create files for new xyOps definitions. The setup command's `--down_cmd` runs only when it writes files; the down-delete command's `--down_cmd` runs only after local changes. Neither creates an empty Git commit on a no-op run.
 
 The Git Event has an enabled **Manual** trigger so a Git hook or verified webhook receiver can launch it with `xy run` or the [`run_event` API](https://docs.xyops.io/api#run_event). It has no schedule. The Git push is still the authoritative reason for that run.
@@ -237,6 +239,7 @@ Run these tests with disposable Events and Plugins, not production definitions:
 3. Delete it in xyOps. Confirm that the **down** Event removes the XYPDF and owned neighbor files and pushes the deletion.
 4. Edit an existing definition in Git and push. Confirm that the accepted-push trigger runs **up** and updates xyOps.
 5. Delete a different existing definition in Git and push. Confirm that **up** deletes only that definition in xyOps.
+6. For both Git-initiated tests, confirm that the sync API Key's activity did not launch either System Activity Event. A second downsync job means the key is missing from a trigger's exclusion list.
 
 Before the first live delete, preview each direction against the complete checkout and inspect every proposed deletion:
 

package/index.js

@@ -14,6 +14,16 @@ const Uncatch = require('uncatch');
 const cli = require('pixl-cli');
 const pkg = require('./package.json');
 
+// MCP owns its streams and lifecycle. Enter before pixl-cli installs terminal
+// output, signal handlers, or argument expansion that could consume stdin.
+if (process.argv[2] === 'mcp') {
+	require('./lib/mcp.js').main(process.argv.slice(3)).catch(function(err) {
+		process.stderr.write('xy mcp: ' + err.message + '\n');
+		process.exitCode = 1;
+	});
+	return;
+}
+
 if (!process.env.XYOPS_USER_AGENT) {
 	process.env.XYOPS_USER_AGENT = `xyOps CLI v${pkg.version} (Node.js); ${os.hostname()} (${os.platform()}/${os.arch()})`;
 }
@@ -79,7 +89,7 @@ const TOP_LEVEL_COMMANDS = [
 	'plugins', 'plugin', 'servers', 'server', 'secrets', 'secret',
 	'snapshots', 'snapshot', 'tags', 'tag', 'tickets', 'ticket',
 	'hooks', 'hook', 'marketplace',
-	'import', 'api', 'repl'
+	'import', 'api', 'repl', 'mcp'
 ];
 
 // coerce true/false into booleans

package/lib/config.js

@@ -42,7 +42,12 @@ var config_layer = module.exports = {
 			if (ekey.match(/^XYOPS_(\w+)$/)) {
 				var key = RegExp.$1.toLowerCase();
 				var value = process.env[ekey];
-				if (value === "true") value = true;
+				// Parse object and array values just like JSON-looking CLI arguments.
+				if (value.trim().match(/^\{[\s\S]*\}$/) || value.trim().match(/^\[[\s\S]*\]$/)) {
+					try { value = JSON.parse(value); }
+					catch (err) { throw new Error('Failed to parse JSON from environment variable: ' + ekey); }
+				}
+				else if (value === "true") value = true;
 				else if (value === "false") value = false;
 				else if (String(value).match(/^\-?\d+(\.\d+)?$/)) value = parseFloat(value);
 				else if (String(value).match(/^\-?\d+$/)) value = parseInt(value);
@@ -51,7 +56,7 @@ var config_layer = module.exports = {
 		}
 		
 		for (var key in config) {
-			process.env['XYOPS_' + key.toUpperCase()] = '' + config[key];
+			process.env['XYOPS_' + key.toUpperCase()] = (config[key] !== null && typeof config[key] === 'object') ? JSON.stringify(config[key]) : '' + config[key];
 		}
 		
 		this.config = config;

package/lib/mcp/context.js

@@ -0,0 +1,52 @@
+// Shared SDK boundary. No terminal formatting, cached records, or global args.
+const READ_APIS = new Set(['get_events', 'get_event', 'get_categories', 'get_groups', 'get_plugins', 'get_plugin', 'get_job', 'search_jobs', 'search_alerts', 'search_snapshots', 'get_active_servers']);
+const WRITE_APIS = new Set(['create_event', 'update_event', 'delete_event', 'run_event', 'create_ticket', 'update_ticket', 'delete_ticket', 'add_ticket_change', 'create_snapshot', 'create_group_snapshot']);
+
+function checkKeys(value) {
+	// Prevent prototype-bearing keys from reaching downstream merge helpers.
+	if (!value || typeof value !== 'object') return;
+	for (const key of Object.keys(value)) {
+		if (['__proto__', 'prototype', 'constructor'].includes(key)) throw new Error('Unsupported property: ' + key);
+		checkKeys(value[key]);
+	}
+}
+
+function createContext(api, options = {}) {
+	const limits = Object.freeze({ max_page_size: options.max_page_size || 100, max_result_bytes: options.max_result_bytes || 1048576 });
+	const redact = text => String(text).split(options.api_key || '\0').join('[redacted]');
+	const log = message => process.stderr.write('xy mcp: ' + redact(message) + '\n');
+	
+	return {
+		limits, log, redact, readOnly: !!options.read_only,
+		withApiKey(api_key) {
+			// HTTP requests get their own immutable credential scope, including
+			// error redaction. Never change environment variables or SDK defaults.
+			if (typeof api_key !== 'string' || !api_key) throw new Error('Missing xyOps API key.');
+			return createContext(api, { ...options, api_key });
+		},
+		async callAPI(name, params = {}, signal) {
+			if (!READ_APIS.has(name) && !WRITE_APIS.has(name)) throw new Error('Unsupported API: ' + name);
+			if (options.read_only && !READ_APIS.has(name)) throw new Error('MCP is configured read-only.');
+			if (signal?.aborted) throw new Error('Request cancelled before contacting xyOps.');
+			checkKeys(params);
+			
+			// Retry policy belongs to this boundary, not the AI client. Retrying a
+			// timed-out launch could create a second job. The SDK also starts with
+			// retries disabled in the MCP entry point.
+			let response;
+			const requestOptions = { retries: 0 };
+			if (options.api_key) requestOptions.headers = { 'X-API-Key': options.api_key };
+			try { response = await api[name](params, requestOptions); }
+			catch (err) { response = { err }; }
+			if (response?.err || !response?.data || response.data.code) {
+				const definitive = response?.data && response.data.code;
+				const message = definitive ? response.data.description : (response?.err?.message || response?.err || 'Invalid xyOps response');
+				const uncertain = WRITE_APIS.has(name) && !definitive;
+				throw new Error(redact(message) + (uncertain ? ' Outcome is uncertain; inspect xyOps before retrying this operation.' : ''));
+			}
+			return response.data;
+		}
+	};
+}
+
+module.exports = { createContext, checkKeys };

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 };