@impetik/xeer-mcp 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Impetik
+
+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

@@ -0,0 +1,93 @@
+# @impetik/xeer-mcp
+
+Model Context Protocol server for [Xeer](https://github.com/impetik/xeer). It exposes the
+scaffold → check → dev → build → deploy loop as MCP tools, each returning the
+`xeer.command.v0` JSON envelope the `xeer` CLI already prints.
+
+See [docs/AGENTS.md](https://github.com/impetik/xeer/blob/main/docs/AGENTS.md) for the loop
+this server is built for, and the `xeer` skill in
+[`.claude/skills/xeer/`](https://github.com/impetik/xeer/tree/main/.claude/skills/xeer) for
+the same protocol written as agent instructions.
+
+## Run it
+
+```jsonc
+// .mcp.json, or your harness's MCP configuration
+{
+  "mcpServers": {
+    "xeer": {
+      "command": "npx",
+      "args": ["--package=@impetik/xeer-mcp", "--", "xeer-mcp"],
+      "env": { "XEER_MCP_ROOT": "." }
+    }
+  }
+}
+```
+
+From this repository, after `pnpm -r build`:
+
+```sh
+node packages/mcp/dist/main.js    # stdio; or `pnpm mcp` from the workspace root
+```
+
+## Tools
+
+| Tool | CLI it runs | Returns |
+| --- | --- | --- |
+| `xeer_check` | `xeer check <dir> --json` | Manifest + analysis diagnostics; `result.manifest` when clean |
+| `xeer_test` | `xeer test <dir> --json` | `{ ok, total, passed, failed, cases, diagnostics, events }` |
+| `xeer_build` | `xeer build <dir> --json` | `result.artifactId`, modules, assets, operations |
+| `xeer_new` | `xeer new <dir> --json` | `result.files` |
+| `xeer_doctor` | `xeer doctor <dir> --json` | `result.checks`, `result.summary` |
+| `xeer_deploy` | `xeer deploy <dir> --json` | `result.url` |
+| `xeer_auth_status` | `xeer auth status --json` | Builder identity and credential expiry |
+| `xeer_inspect` | `xeer inspect`/`state`/`logs` | Inspector response for a running preview |
+| `xeer_dev_start` | `xeer dev <dir> --json --port 0` | Session handle, cursor, and the events up to `preview.ready` |
+| `xeer_dev_status` | — | `xeer.dev.v0` events after a cursor, plus `openDiagnostics` |
+| `xeer_dev_stop` | — | Final events; shuts down over `xeer.dev.control.v0` IPC |
+| `xeer_diagnostics` | — | What an `XE####` code means and the edit that closes it |
+
+Every command tool returns the envelope both as `structuredContent` and as a JSON text
+block, so a client that ignores structured output still sees all of it. A tool result is
+always an envelope: when the CLI crashes without printing one, the server synthesizes
+`XE0000` rather than failing the call in a different shape.
+
+`xeer_test` is the exception, because `xeer test --json` streams `xeer.dev.v0` events rather
+than printing an envelope. It collects the run and returns the summary plus the unabridged
+event stream, with each failed case carrying a `Diagnostic`-shaped `failure` (`XE1904`
+assertion, `XE1905` throw or unexpectedly refused call, `XE1906` timeout) that includes the
+matcher, expected and actual values, and the project-relative test location. It needs no
+session handle: unlike `dev`, a test run is short-lived and terminal.
+
+`xeer link` and `xeer env` are deliberately absent. Which hosted app a checkout deploys to
+is the human owner's decision, so on `XE5111`/`XE5120`/`XE5121` the surface reports the
+diagnostic and its documented repair instead of performing it. `xeer env` reads and writes
+secrets — `xeer env pull` returns plaintext — so it is not reachable through a tool call.
+
+## Why dev is three tools
+
+An MCP tool call is request/response; `xeer dev` is a long-lived JSONL stream. The session
+is therefore owned by the server and addressed by a `sessionId`, with the protocol's own
+`seq` as a resumable cursor:
+
+```text
+xeer_dev_start  → { sessionId, cursor, status: 'ready', preview: { url, inspectorUrl, ... }, events }
+   edit a file
+xeer_dev_status → { events: [compile.start, compile.diagnostic?, compile.ready?], openDiagnostics, generation }
+xeer_dev_stop   → { status: 'stopped' }
+```
+
+No event is summarized away, so the agent reads the same stream a terminal would show.
+Repairing diagnostics needs none of this — `xeer_check` runs the same compiler — so the
+session exists for when the preview, the inspector, or rebuild/rollback behaviour matters.
+
+## Configuration
+
+| Variable | Effect |
+| --- | --- |
+| `XEER_MCP_ROOT` | Confinement root for every `directory` argument. Defaults to the server's working directory; paths that escape it are refused. |
+| `XEER_CLI` | Absolute path to `dist/cli.js`, overriding resolution through this package's dependencies. |
+
+Always stop dev sessions you start: local state is leased per project and mode, so a leaked
+session makes the next run fail with `XE1812`. The stdio entrypoint stops every session on
+`SIGINT`/`SIGTERM`.

package/dist/dev-session.d.ts

@@ -0,0 +1,92 @@
+import type { Diagnostic, DevEvent } from '@impetik/xeer-spec';
+/**
+ * `xeer dev` is a long-running process that streams `xeer.dev.v0` JSONL events;
+ * an MCP tool call is a single request/response. This module reconciles the two
+ * without weakening either.
+ *
+ * The process is owned by the server and addressed by a session id. Events are
+ * buffered with their protocol `seq` as the cursor, so `xeer_dev_status` is a
+ * resumable read of the same stream a terminal would have shown — no event is
+ * summarized away, and nothing is lost between polls. Shutdown uses the
+ * documented `xeer.dev.control.v0` IPC message rather than a signal, which is
+ * why the child is forked with an IPC channel.
+ *
+ * The alternative — re-running `xeer check` after every edit — is a complete
+ * repair loop on its own and is what the skill recommends for pure diagnostics
+ * work. A dev session is for when the agent also needs the preview, the
+ * inspector, and the rebuild/rollback behaviour that only `dev` has.
+ */
+export type DevSessionStatus = 'starting' | 'ready' | 'compile_failed' | 'stopped' | 'crashed';
+export interface PreviewUrls {
+    url: string;
+    healthUrl: string;
+    inspectorUrl: string;
+    debugUrl: string;
+    logsUrl: string;
+}
+export interface DevSessionSummary {
+    sessionId: string;
+    directory: string;
+    status: DevSessionStatus;
+    running: boolean;
+    /** Highest `seq` observed. Pass it back as `cursor` to read only what is new. */
+    cursor: number;
+    generation?: number;
+    artifactId?: string;
+    preview?: PreviewUrls;
+    /** Diagnostics from the most recent compile attempt. Empty once a rebuild is accepted. */
+    openDiagnostics: Diagnostic[];
+    exit?: {
+        code?: number;
+        reason?: string;
+    };
+    /** Number of buffered events discarded because the buffer is bounded. */
+    droppedEvents: number;
+    stderr?: string;
+}
+export interface DevSessionRead extends DevSessionSummary {
+    events: DevEvent[];
+}
+export interface DevSessionOptions {
+    directory: string;
+    host?: string;
+    port?: number;
+}
+export declare class DevSession {
+    #private;
+    readonly sessionId: string;
+    readonly directory: string;
+    constructor(sessionId: string, options: DevSessionOptions);
+    get running(): boolean;
+    get status(): DevSessionStatus;
+    /**
+     * Resolves once the session is serving or the process is gone. A failed first
+     * compile emits `process.exit` and then exits, so waiting for the process
+     * rather than for the event keeps `running` truthful in the returned summary.
+     */
+    waitForStart(timeoutMilliseconds?: number): Promise<void>;
+    /**
+     * Waits for the burst of events after `cursor` to settle.
+     *
+     * Two conditions, because a rebuild has two shapes. A compile that is in
+     * flight must be waited *out* — `compile.start` is followed by seconds of
+     * silence while the compiler works, so returning on a quiet window there would
+     * report "no diagnostics" for a build that had not finished. A compile that
+     * failed emits its diagnostics and then simply stops, with no terminal event,
+     * so once diagnostics have arrived a quiet window is the only signal there is.
+     */
+    waitForActivity(cursor: number, timeoutMilliseconds: number, quietMilliseconds?: number): Promise<void>;
+    summary(): DevSessionSummary;
+    read(cursor?: number, limit?: number): DevSessionRead;
+    /** Uses the documented IPC shutdown, then escalates only if the child ignores it. */
+    stop(): Promise<DevSessionSummary>;
+}
+export declare class DevSessionRegistry {
+    #private;
+    start(options: DevSessionOptions): DevSession;
+    find(directory: string): DevSession | undefined;
+    get(sessionId?: string): DevSession;
+    list(): string[];
+    summaries(): DevSessionSummary[];
+    stopAll(): Promise<void>;
+}

package/dist/dev-session.js

@@ -0,0 +1,285 @@
+import { fork } from 'node:child_process';
+import { resolveXeerCli } from './xeer-cli.js';
+const MAX_BUFFERED_EVENTS = 2_000;
+const MAX_STDERR_CHARACTERS = 4_096;
+const DEFAULT_START_TIMEOUT_MILLISECONDS = 180_000;
+const DEFAULT_QUIET_MILLISECONDS = 600;
+const STOP_TIMEOUT_MILLISECONDS = 20_000;
+export class DevSession {
+    sessionId;
+    directory;
+    #child;
+    #events = [];
+    #dropped = 0;
+    #cursor = 0;
+    #status = 'starting';
+    #preview;
+    #generation;
+    #artifactId;
+    #openDiagnostics = [];
+    #exit;
+    /** A compile is in flight: an agent polling for the outcome must keep waiting. */
+    #compiling = false;
+    #restarting = false;
+    #diagnosticsThisCompile = 0;
+    #stderr = '';
+    #stdoutRemainder = '';
+    #waiters = new Set();
+    constructor(sessionId, options) {
+        this.sessionId = sessionId;
+        this.directory = options.directory;
+        // Port 0 is the documented automation mode: the OS picks a free port and the
+        // preview.ready event reports it, so parallel sessions cannot collide.
+        const args = ['dev', options.directory, '--json',
+            '--host', options.host ?? '127.0.0.1', '--port', String(options.port ?? 0)];
+        this.#child = fork(resolveXeerCli(), args, {
+            cwd: options.directory,
+            stdio: ['ignore', 'pipe', 'pipe', 'ipc'],
+            env: { ...process.env, NO_UPDATE_NOTIFIER: '1' },
+        });
+        this.#child.stdout?.setEncoding('utf8');
+        this.#child.stderr?.setEncoding('utf8');
+        this.#child.stdout?.on('data', (chunk) => this.#ingest(chunk));
+        this.#child.stderr?.on('data', (chunk) => {
+            this.#stderr = (this.#stderr + chunk).slice(-MAX_STDERR_CHARACTERS);
+            this.#wake();
+        });
+        this.#child.on('error', (error) => {
+            this.#stderr = (this.#stderr + `\n${error.message}`).slice(-MAX_STDERR_CHARACTERS);
+            if (this.running)
+                this.#status = 'crashed';
+            this.#wake();
+        });
+        this.#child.on('close', (code) => {
+            // `process.exit` already recorded the intent; a close without it is a crash.
+            if (this.#status === 'starting' || this.#status === 'ready') {
+                this.#status = code === 0 ? 'stopped' : 'crashed';
+            }
+            this.#exit = { ...(typeof code === 'number' ? { code } : {}), ...(this.#exit?.reason ? { reason: this.#exit.reason } : {}) };
+            this.#wake();
+        });
+    }
+    get running() {
+        return this.#child.exitCode === null && this.#child.signalCode === null;
+    }
+    get status() {
+        return this.#status;
+    }
+    #ingest(chunk) {
+        const text = this.#stdoutRemainder + chunk;
+        const lines = text.split('\n');
+        this.#stdoutRemainder = lines.pop() ?? '';
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let event;
+            try {
+                const parsed = JSON.parse(trimmed);
+                if (parsed?.protocol !== 'xeer.dev.v0' || typeof parsed.type !== 'string')
+                    continue;
+                event = parsed;
+            }
+            catch {
+                continue;
+            }
+            this.#record(event);
+        }
+        this.#wake();
+    }
+    #record(event) {
+        this.#events.push(event);
+        if (this.#events.length > MAX_BUFFERED_EVENTS) {
+            this.#dropped += this.#events.length - MAX_BUFFERED_EVENTS;
+            this.#events = this.#events.slice(-MAX_BUFFERED_EVENTS);
+        }
+        this.#cursor = Math.max(this.#cursor, event.seq);
+        // Unknown event types are ignored by contract; only the lifecycle types below
+        // change what an agent should do next.
+        switch (event.type) {
+            case 'compile.start':
+                this.#openDiagnostics = [];
+                this.#compiling = true;
+                this.#restarting = false;
+                this.#diagnosticsThisCompile = 0;
+                break;
+            case 'compile.diagnostic':
+                this.#openDiagnostics.push(event.data);
+                this.#diagnosticsThisCompile += 1;
+                break;
+            case 'compile.ready': {
+                const data = event.data;
+                this.#generation = data.generation;
+                this.#artifactId = data.artifactId;
+                this.#openDiagnostics = [];
+                // A guarded restart emits compile.ready before server.restarted, so the
+                // promotion is not finished yet.
+                if (!this.#restarting)
+                    this.#compiling = false;
+                break;
+            }
+            case 'server.restarting':
+                this.#restarting = true;
+                this.#compiling = true;
+                break;
+            case 'server.restarted':
+                this.#restarting = false;
+                this.#compiling = false;
+                break;
+            case 'preview.ready':
+                this.#preview = event.data;
+                this.#status = 'ready';
+                this.#compiling = false;
+                break;
+            case 'process.exit': {
+                const data = event.data;
+                this.#exit = { ...(typeof data.code === 'number' ? { code: data.code } : {}), ...(data.reason ? { reason: data.reason } : {}) };
+                this.#status = data.reason === 'compile_failed' ? 'compile_failed'
+                    : data.reason === 'runtime_failed' ? 'crashed' : 'stopped';
+                this.#compiling = false;
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    #wake() {
+        for (const waiter of [...this.#waiters])
+            waiter();
+    }
+    #wait(predicate, timeoutMilliseconds) {
+        if (predicate())
+            return Promise.resolve();
+        return new Promise((done) => {
+            const finish = () => {
+                clearTimeout(timer);
+                this.#waiters.delete(waiter);
+                done();
+            };
+            const waiter = () => { if (predicate())
+                finish(); };
+            const timer = setTimeout(finish, timeoutMilliseconds);
+            this.#waiters.add(waiter);
+        });
+    }
+    /**
+     * Resolves once the session is serving or the process is gone. A failed first
+     * compile emits `process.exit` and then exits, so waiting for the process
+     * rather than for the event keeps `running` truthful in the returned summary.
+     */
+    async waitForStart(timeoutMilliseconds = DEFAULT_START_TIMEOUT_MILLISECONDS) {
+        await this.#wait(() => this.#status === 'ready' || !this.running, timeoutMilliseconds);
+    }
+    /**
+     * Waits for the burst of events after `cursor` to settle.
+     *
+     * Two conditions, because a rebuild has two shapes. A compile that is in
+     * flight must be waited *out* — `compile.start` is followed by seconds of
+     * silence while the compiler works, so returning on a quiet window there would
+     * report "no diagnostics" for a build that had not finished. A compile that
+     * failed emits its diagnostics and then simply stops, with no terminal event,
+     * so once diagnostics have arrived a quiet window is the only signal there is.
+     */
+    async waitForActivity(cursor, timeoutMilliseconds, quietMilliseconds = DEFAULT_QUIET_MILLISECONDS) {
+        if (timeoutMilliseconds <= 0)
+            return;
+        const deadline = Date.now() + timeoutMilliseconds;
+        const remaining = () => Math.max(0, deadline - Date.now());
+        await this.#wait(() => this.#cursor > cursor || !this.running, timeoutMilliseconds);
+        while (this.running && this.#cursor > cursor && remaining() > 0) {
+            if (this.#compiling && this.#diagnosticsThisCompile === 0) {
+                await this.#wait(() => !this.#compiling || this.#diagnosticsThisCompile > 0, remaining());
+                continue;
+            }
+            const before = this.#cursor;
+            await this.#wait(() => this.#cursor > before, Math.min(quietMilliseconds, remaining()));
+            if (this.#cursor === before)
+                return;
+        }
+    }
+    summary() {
+        return {
+            sessionId: this.sessionId,
+            directory: this.directory,
+            status: this.#status,
+            running: this.running,
+            cursor: this.#cursor,
+            ...(this.#generation === undefined ? {} : { generation: this.#generation }),
+            ...(this.#artifactId === undefined ? {} : { artifactId: this.#artifactId }),
+            ...(this.#preview ? { preview: this.#preview } : {}),
+            openDiagnostics: [...this.#openDiagnostics],
+            ...(this.#exit ? { exit: this.#exit } : {}),
+            droppedEvents: this.#dropped,
+            ...(this.#stderr.trim() ? { stderr: this.#stderr.trim() } : {}),
+        };
+    }
+    read(cursor = 0, limit = 200) {
+        const events = this.#events.filter((event) => event.seq > cursor);
+        return {
+            ...this.summary(),
+            events: events.length > limit ? events.slice(-limit) : events,
+        };
+    }
+    /** Uses the documented IPC shutdown, then escalates only if the child ignores it. */
+    async stop() {
+        if (!this.running)
+            return this.summary();
+        if (this.#child.connected)
+            this.#child.send({ protocol: 'xeer.dev.control.v0', type: 'shutdown' });
+        else
+            this.#child.kill('SIGTERM');
+        await this.#wait(() => !this.running, STOP_TIMEOUT_MILLISECONDS);
+        if (this.running) {
+            this.#child.kill('SIGKILL');
+            await this.#wait(() => !this.running, 5_000);
+        }
+        return this.summary();
+    }
+}
+export class DevSessionRegistry {
+    #sessions = new Map();
+    #counter = 0;
+    start(options) {
+        const existing = this.find(options.directory);
+        if (existing?.running) {
+            throw new Error(`A dev session is already running for ${options.directory} (${existing.sessionId}). `
+                + 'Local state is leased per project, so stop it before starting another.');
+        }
+        if (existing)
+            this.#sessions.delete(existing.sessionId);
+        this.#counter += 1;
+        const session = new DevSession(`dev-${this.#counter}`, options);
+        this.#sessions.set(session.sessionId, session);
+        return session;
+    }
+    find(directory) {
+        for (const session of this.#sessions.values())
+            if (session.directory === directory)
+                return session;
+        return undefined;
+    }
+    get(sessionId) {
+        if (sessionId) {
+            const session = this.#sessions.get(sessionId);
+            if (!session)
+                throw new Error(`Unknown dev session: ${sessionId}. Known: ${this.list().join(', ') || 'none'}`);
+            return session;
+        }
+        const running = [...this.#sessions.values()].filter((session) => session.running);
+        const candidates = running.length ? running : [...this.#sessions.values()];
+        if (candidates.length === 1)
+            return candidates[0];
+        if (!candidates.length)
+            throw new Error('No dev session has been started. Call xeer_dev_start first.');
+        throw new Error(`Several dev sessions exist; pass sessionId. Known: ${this.list().join(', ')}`);
+    }
+    list() {
+        return [...this.#sessions.keys()];
+    }
+    summaries() {
+        return [...this.#sessions.values()].map((session) => session.summary());
+    }
+    async stopAll() {
+        await Promise.all([...this.#sessions.values()].map((session) => session.stop()));
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createXeerMcpServer, type XeerMcpServer } from './server.js';
+export { DevSession, DevSessionRegistry, type DevSessionOptions, type DevSessionRead, type DevSessionStatus, type DevSessionSummary, type PreviewUrls, } from './dev-session.js';
+export { runXeerTests, type RunTestsOptions, type TestCaseResult, type TestFailure, type TestRunResult, } from './test-run.js';
+export { projectRoot, resolveDirectory, resolveXeerCli, runXeerCommand, XeerCliError, type CommandEnvelope, type CommandRun, type RunOptions, } from './xeer-cli.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createXeerMcpServer } from './server.js';
+export { DevSession, DevSessionRegistry, } from './dev-session.js';
+export { runXeerTests, } from './test-run.js';
+export { projectRoot, resolveDirectory, resolveXeerCli, runXeerCommand, XeerCliError, } from './xeer-cli.js';

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createXeerMcpServer } from './server.js';
+/**
+ * stdio entrypoint. Nothing may be written to stdout except JSON-RPC frames, so
+ * every diagnostic message from this process goes to stderr.
+ */
+const { server, devSessions } = createXeerMcpServer();
+let closing = false;
+async function shutdown(code) {
+    if (closing)
+        return;
+    closing = true;
+    // Dev sessions hold a local state lease; a leaked child would block the next run.
+    await devSessions.stopAll().catch(() => undefined);
+    await server.close().catch(() => undefined);
+    process.exit(code);
+}
+process.on('SIGINT', () => void shutdown(0));
+process.on('SIGTERM', () => void shutdown(0));
+try {
+    await server.connect(new StdioServerTransport());
+}
+catch (error) {
+    process.stderr.write(`xeer-mcp failed to start: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+    process.exit(1);
+}

package/dist/server.d.ts

@@ -0,0 +1,7 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { DevSessionRegistry } from './dev-session.js';
+export interface XeerMcpServer {
+    server: McpServer;
+    devSessions: DevSessionRegistry;
+}
+export declare function createXeerMcpServer(): XeerMcpServer;

package/dist/server.js

@@ -0,0 +1,376 @@
+import { createRequire } from 'node:module';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+import { DIAGNOSTICS, DIAGNOSTIC_CODES, DIAGNOSTIC_FAMILIES, diagnosticDefinition, renderDiagnosticsReference, } from '@impetik/xeer-spec/diagnostics';
+import { DevSessionRegistry } from './dev-session.js';
+import { runXeerTests } from './test-run.js';
+import { projectRoot, resolveDirectory, runXeerCommand, XeerCliError } from './xeer-cli.js';
+/**
+ * The Xeer MCP server.
+ *
+ * Tools are a thin, honest projection of the CLI: one tool per command, each
+ * returning the `xeer.command.v0` envelope the CLI printed. The only tools that
+ * are not a single command are the dev-session trio, because a long-running
+ * event stream has to be addressed by a handle and a cursor, and
+ * `xeer_diagnostics`, which serves the generated catalogue so an agent can look
+ * up a code without a second round trip through the filesystem.
+ */
+const version = createRequire(import.meta.url)('../package.json').version;
+const directoryArgument = z.string().optional()
+    .describe('Project directory. Relative paths resolve against the server root; defaults to it.');
+/** Mirrors the Diagnostic interface in @impetik/xeer-spec, loosely so new fields pass through. */
+const diagnosticSchema = z.object({
+    code: z.string(),
+    severity: z.string(),
+    message: z.string(),
+    file: z.string().optional(),
+    span: z.object({
+        line: z.number(),
+        column: z.number(),
+        length: z.number().optional(),
+    }).loose().optional(),
+    hint: z.string().optional(),
+}).loose();
+const envelopeOutput = {
+    argv: z.array(z.string()).describe('The exact xeer argv that produced this envelope.'),
+    exitCode: z.number().nullable(),
+    protocol: z.literal('xeer.command.v0'),
+    command: z.string(),
+    ok: z.boolean(),
+    diagnostics: z.array(diagnosticSchema),
+    result: z.unknown().optional(),
+    stderr: z.string().optional(),
+};
+function structured(payload) {
+    return {
+        // The text block is the same JSON, because a client that ignores
+        // structuredContent must still see the whole envelope.
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        structuredContent: payload,
+        ...(payload['ok'] === false ? { isError: false } : {}),
+    };
+}
+function failure(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+/** Runs a CLI command and shapes the result identically for every tool. */
+async function commandTool(args, directory) {
+    const run = await runXeerCommand(args, { cwd: directory });
+    return structured({
+        argv: run.argv,
+        exitCode: run.exitCode,
+        ...run.envelope,
+        ...(run.stderr ? { stderr: run.stderr } : {}),
+    });
+}
+async function withDirectory(directory, body) {
+    try {
+        return await body(await resolveDirectory(directory));
+    }
+    catch (error) {
+        if (error instanceof XeerCliError)
+            return failure(error.message);
+        throw error;
+    }
+}
+const CHECK_DESCRIPTION = [
+    'Validate a Xeer project and return its diagnostics as JSON. This is the repair loop:',
+    'read diagnostics, apply the smallest edit each one names, run it again, converge on ok: true.',
+    'Runs the manifest stage and, if that passes, the module-graph/zone/operations/type analysis.',
+    'Envelope: { protocol: "xeer.command.v0", command: "check", ok, diagnostics: Diagnostic[],',
+    'result?: { manifest } }. Diagnostic codes are stable — look one up with xeer_diagnostics.',
+].join(' ');
+const BUILD_DESCRIPTION = [
+    'Build the content-addressed artifact. Runs check first, so build diagnostics are a superset',
+    'of check diagnostics plus bundling, budget, and asset codes (XE14xx, XE15xx).',
+    'On success result is { artifactId, outputDirectory, modules, assets, operations }.',
+    'Run xeer_test before this to prove the application behaves, not just that it compiles.',
+].join(' ');
+export function createXeerMcpServer() {
+    const server = new McpServer({ name: 'xeer', version }, {
+        instructions: [
+            'Xeer is a constrained full-stack platform whose diagnostics are its agent surface.',
+            `Project root for this server: ${projectRoot()}.`,
+            'Loop: xeer_new to scaffold, xeer_check after every edit, xeer_test to prove behaviour,',
+            'xeer_build before deploy. A green check means it compiles; only a green test means it works.',
+            'Command tools return the CLI\'s xeer.command.v0 envelope verbatim; dispatch on diagnostics[].code',
+            'and use xeer_diagnostics to learn what a code means and which edit closes it.',
+            'Use xeer_dev_start/status/stop only when you need a running preview and inspector;',
+            'a check-edit-check loop plus xeer_test is enough to build and repair a project.',
+        ].join(' '),
+    });
+    const devSessions = new DevSessionRegistry();
+    server.registerTool('xeer_check', {
+        title: 'Check a Xeer project',
+        description: CHECK_DESCRIPTION,
+        inputSchema: { directory: directoryArgument },
+        outputSchema: envelopeOutput,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ directory }) => withDirectory(directory, (resolved) => commandTool(['check', resolved], resolved)));
+    server.registerTool('xeer_build', {
+        title: 'Build a Xeer project',
+        description: BUILD_DESCRIPTION,
+        inputSchema: { directory: directoryArgument },
+        outputSchema: envelopeOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async ({ directory }) => withDirectory(directory, (resolved) => commandTool(['build', resolved], resolved)));
+    server.registerTool('xeer_test', {
+        title: 'Run a Xeer project\'s tests',
+        description: [
+            'Run the application\'s own tests: build, type-check tests/**/*.test.ts against the generated',
+            'contract, boot the verified artifact in workerd with fresh isolated state, run every test, tear',
+            'down. This is the convergence check — a green check proves the project compiles, a green test',
+            'proves it behaves. Returns { ok, total, passed, failed, cases, diagnostics, events }.',
+            'Each failed case carries a Diagnostic-shaped failure with matcher, expected, actual, and the',
+            'project-relative test location: XE1904 assertion, XE1905 threw or unexpectedly refused call,',
+            'XE1906 timeout. Compiler diagnostics abort the run before any test boots.',
+            'Tests call as(\'alice\'|\'bob\'|\'guest\'), so ownership and authorization are directly testable.',
+        ].join(' '),
+        inputSchema: {
+            directory: directoryArgument,
+            timeoutMilliseconds: z.number().int().min(1_000).max(1_800_000).optional(),
+        },
+        outputSchema: {
+            argv: z.array(z.string()),
+            exitCode: z.number().nullable(),
+            ok: z.boolean(),
+            reason: z.string().optional(),
+            total: z.number(),
+            passed: z.number(),
+            failed: z.number(),
+            durationMs: z.number().optional(),
+            files: z.array(z.string()),
+            cases: z.array(z.object({
+                file: z.string(),
+                name: z.string(),
+                status: z.enum(['passed', 'failed']),
+                durationMs: z.number().optional(),
+                failure: diagnosticSchema.optional(),
+            }).loose()),
+            diagnostics: z.array(diagnosticSchema),
+            events: z.array(z.object({
+                protocol: z.literal('xeer.dev.v0'),
+                seq: z.number(),
+                time: z.string(),
+                type: z.string(),
+                data: z.unknown(),
+            }).loose()),
+            stderr: z.string().optional(),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    }, async ({ directory, timeoutMilliseconds }) => withDirectory(directory, async (resolved) => {
+        const run = await runXeerTests({
+            directory: resolved,
+            ...(timeoutMilliseconds === undefined ? {} : { timeoutMilliseconds }),
+        });
+        return structured(run);
+    }));
+    server.registerTool('xeer_new', {
+        title: 'Scaffold a Xeer project',
+        description: 'Create a new Xeer project in an empty or non-existent directory. '
+            + 'The scaffold checks and builds clean, so use it as the starting point rather than writing '
+            + 'a manifest by hand. result is { directory, name, files }.',
+        inputSchema: {
+            directory: z.string().describe('Target directory, relative to the server root. Must be empty or absent.'),
+        },
+        outputSchema: envelopeOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ directory }) => withDirectory(directory, (resolved) => commandTool(['new', resolved], projectRoot())));
+    server.registerTool('xeer_doctor', {
+        title: 'Diagnose the Xeer toolchain',
+        description: 'Check the local toolchain and generated-file state. Use it when a command fails for '
+            + 'a reason no project edit explains. result is { checks, summary }; failures also appear as XE4001 '
+            + 'diagnostics.',
+        inputSchema: { directory: directoryArgument },
+        outputSchema: envelopeOutput,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ directory }) => withDirectory(directory, (resolved) => commandTool(['doctor', resolved], resolved)));
+    server.registerTool('xeer_deploy', {
+        title: 'Deploy a Xeer project',
+        description: 'Build, verify, and upload the artifact to the control plane. Requires a builder '
+            + 'credential: XE5002 means a human must run `xeer auth login` first. result is '
+            + '{ application, url, ... }.',
+        inputSchema: {
+            directory: directoryArgument,
+            controlUrl: z.string().optional().describe('Control-plane origin override, e.g. https://control.example.com.'),
+        },
+        outputSchema: envelopeOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, async ({ directory, controlUrl }) => withDirectory(directory, (resolved) => commandTool(['deploy', resolved, ...(controlUrl ? ['--control-url', controlUrl] : [])], resolved)));
+    server.registerTool('xeer_auth_status', {
+        title: 'Report builder sign-in status',
+        description: 'Report whether a builder credential is available for deployment. Sign-in itself is '
+            + 'interactive and cannot be completed by an agent; XE5002 means ask the human to run '
+            + '`xeer auth login`.',
+        inputSchema: {
+            controlUrl: z.string().optional().describe('Control-plane origin override.'),
+        },
+        outputSchema: envelopeOutput,
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ controlUrl }) => commandTool(['auth', 'status', ...(controlUrl ? ['--control-url', controlUrl] : [])], projectRoot()));
+    server.registerTool('xeer_inspect', {
+        title: 'Inspect a running preview',
+        description: 'Read the inspector API of a running dev or preview server: normalized manifest '
+            + '(manifest), per-table record counts (state), the bounded structured log ring (logs), or '
+            + 'every stored record with the schema that describes it (export). Use the URLs from '
+            + 'xeer_dev_status.preview.',
+        inputSchema: {
+            previewUrl: z.string().describe('Preview URL from preview.ready, e.g. http://127.0.0.1:43127/.'),
+            view: z.enum(['manifest', 'state', 'logs', 'export']).default('manifest'),
+            after: z.string().optional().describe('Log cursor, for view: "logs".'),
+        },
+        outputSchema: envelopeOutput,
+        annotations: { readOnlyHint: true, openWorldHint: true },
+    }, async ({ previewUrl, view, after }) => {
+        const command = view === 'manifest' ? 'inspect' : view;
+        return commandTool([command, previewUrl, ...(view === 'logs' && after ? ['--after', after] : [])], projectRoot());
+    });
+    const sessionOutput = {
+        sessionId: z.string(),
+        directory: z.string(),
+        status: z.enum(['starting', 'ready', 'compile_failed', 'stopped', 'crashed']),
+        running: z.boolean(),
+        cursor: z.number(),
+        generation: z.number().optional(),
+        artifactId: z.string().optional(),
+        preview: z.object({
+            url: z.string(),
+            healthUrl: z.string(),
+            inspectorUrl: z.string(),
+            debugUrl: z.string(),
+            logsUrl: z.string(),
+        }).loose().optional(),
+        openDiagnostics: z.array(diagnosticSchema),
+        exit: z.object({ code: z.number().optional(), reason: z.string().optional() }).loose().optional(),
+        droppedEvents: z.number(),
+        stderr: z.string().optional(),
+        events: z.array(z.object({
+            protocol: z.literal('xeer.dev.v0'),
+            seq: z.number(),
+            time: z.string(),
+            type: z.string(),
+            data: z.unknown(),
+        }).loose()),
+    };
+    server.registerTool('xeer_dev_start', {
+        title: 'Start a dev session',
+        description: [
+            'Start `xeer dev --json` and return the xeer.dev.v0 events it emitted up to the point it settled.',
+            'Returns when preview.ready arrives (status "ready"), or when the first compile fails',
+            '(status "compile_failed", openDiagnostics populated). Port 0 by default, so the real URL is in',
+            'preview.ready. Keep the returned cursor and pass it to xeer_dev_status after each edit.',
+            'You do not need a dev session to repair diagnostics: xeer_check is the same compiler.',
+        ].join(' '),
+        inputSchema: {
+            directory: directoryArgument,
+            host: z.string().optional().describe('Defaults to 127.0.0.1.'),
+            port: z.number().int().min(0).max(65535).optional().describe('Defaults to 0 (OS-assigned).'),
+            timeoutMilliseconds: z.number().int().min(1_000).max(600_000).optional(),
+        },
+        outputSchema: sessionOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
+    }, async ({ directory, host, port, timeoutMilliseconds }) => withDirectory(directory, async (resolved) => {
+        let session;
+        try {
+            session = devSessions.start({
+                directory: resolved,
+                ...(host ? { host } : {}),
+                ...(port === undefined ? {} : { port }),
+            });
+        }
+        catch (error) {
+            return failure(error instanceof Error ? error.message : String(error));
+        }
+        await session.waitForStart(timeoutMilliseconds ?? 180_000);
+        return structured(session.read(0));
+    }));
+    server.registerTool('xeer_dev_status', {
+        title: 'Read new dev-session events',
+        description: [
+            'Read the xeer.dev.v0 events emitted since `cursor`, then return the session summary.',
+            'After editing a file, call this with waitMilliseconds set: the CLI coalesces changes behind a',
+            '75 ms quiet window, rebuilds, and emits compile.start, any compile.diagnostic, and compile.ready',
+            'when the rebuild is accepted. openDiagnostics is the outcome of the latest attempt, so an empty',
+            'openDiagnostics with a higher generation means the edit was accepted.',
+        ].join(' '),
+        inputSchema: {
+            sessionId: z.string().optional().describe('Optional when only one session exists.'),
+            cursor: z.number().int().min(0).default(0).describe('Last seq you have already read.'),
+            waitMilliseconds: z.number().int().min(0).max(600_000).default(0)
+                .describe('Wait up to this long for new events to arrive and settle.'),
+            limit: z.number().int().min(1).max(1_000).default(200),
+        },
+        outputSchema: sessionOutput,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ sessionId, cursor, waitMilliseconds, limit }) => {
+        let session;
+        try {
+            session = devSessions.get(sessionId);
+        }
+        catch (error) {
+            return failure(error instanceof Error ? error.message : String(error));
+        }
+        await session.waitForActivity(cursor, waitMilliseconds);
+        return structured(session.read(cursor, limit));
+    });
+    server.registerTool('xeer_dev_stop', {
+        title: 'Stop a dev session',
+        description: 'Stop a dev session over the documented xeer.dev.control.v0 IPC shutdown, releasing '
+            + 'the local state lease. Always stop sessions you started: the lease is per project and mode, '
+            + 'so a leaked session blocks the next dev run with XE1812.',
+        inputSchema: {
+            sessionId: z.string().optional().describe('Optional when only one session exists.'),
+            cursor: z.number().int().min(0).default(0),
+        },
+        outputSchema: sessionOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+    }, async ({ sessionId, cursor }) => {
+        let session;
+        try {
+            session = devSessions.get(sessionId);
+        }
+        catch (error) {
+            return failure(error instanceof Error ? error.message : String(error));
+        }
+        await session.stop();
+        return structured(session.read(cursor));
+    });
+    server.registerTool('xeer_diagnostics', {
+        title: 'Look up Xeer diagnostic codes',
+        description: 'Explain a diagnostic code: what the platform observed and which edit closes it. '
+            + 'Omit `code` for the whole generated reference. This is the same catalogue the compiler emits '
+            + 'from, so it cannot drift from the codes you receive.',
+        inputSchema: {
+            code: z.string().optional().describe('An XE#### code, e.g. XE1202.'),
+        },
+        outputSchema: {
+            code: z.string().optional(),
+            family: z.string().optional(),
+            means: z.string().optional(),
+            repair: z.string().optional(),
+            surfaces: z.array(z.string()).optional(),
+            codes: z.array(z.string()).optional(),
+            reference: z.string().optional(),
+        },
+        annotations: { readOnlyHint: true, openWorldHint: false },
+    }, async ({ code }) => {
+        if (!code) {
+            return structured({ codes: [...DIAGNOSTIC_CODES], reference: renderDiagnosticsReference() });
+        }
+        const normalized = code.trim().toUpperCase();
+        const definition = diagnosticDefinition(normalized);
+        if (!definition) {
+            const known = Object.keys(DIAGNOSTICS).sort().join(', ');
+            return failure(`Unknown diagnostic code: ${normalized}. Known codes: ${known}`);
+        }
+        const family = DIAGNOSTIC_FAMILIES.find((candidate) => candidate.prefix === definition.prefix);
+        return structured({
+            code: definition.code,
+            family: family ? `${family.title}: ${family.summary}` : definition.prefix,
+            means: definition.means,
+            repair: definition.repair,
+            surfaces: [...definition.surfaces],
+        });
+    });
+    return { server, devSessions };
+}

package/dist/test-run.d.ts

@@ -0,0 +1,57 @@
+import type { DevEvent, Diagnostic } from '@impetik/xeer-spec';
+/**
+ * `xeer test --json` is the one command that streams instead of printing an
+ * envelope: it reuses the `xeer.dev.v0` JSONL protocol so a consumer sees the
+ * build, then each case as it runs (docs/specs/test-protocol-v0.md).
+ *
+ * It is also short-lived and terminal, unlike `xeer dev`, so it needs no session
+ * handle. This collects the stream, folds it into the summary an agent acts on —
+ * which cases failed, and the Diagnostic-shaped failure for each — and returns
+ * the raw events alongside it so nothing is lost to the summary.
+ */
+/** A test failure is a Diagnostic plus the assertion detail. */
+export interface TestFailure extends Diagnostic {
+    kind?: 'assertion' | 'error' | 'timeout' | string;
+    matcher?: string;
+    negated?: boolean;
+    expected?: string;
+    actual?: string;
+    operation?: {
+        persona?: string;
+        kind?: string;
+        name?: string;
+        status?: number;
+        errorCode?: string;
+        errorId?: string;
+    };
+}
+export interface TestCaseResult {
+    file: string;
+    name: string;
+    status: 'passed' | 'failed';
+    durationMs?: number;
+    failure?: TestFailure;
+}
+export interface TestRunResult {
+    argv: string[];
+    exitCode: number | null;
+    /** 0 every test passed, 1 a diagnostic or failed test, 2 the runtime could not start. */
+    ok: boolean;
+    /** `complete`, `tests_failed`, `build_failed`, `no_tests`, `test_type_errors`, `test_compile_failed`, `runtime_failed`. */
+    reason?: string;
+    total: number;
+    passed: number;
+    failed: number;
+    durationMs?: number;
+    files: string[];
+    cases: TestCaseResult[];
+    /** Compiler diagnostics, which abort the run before any test boots. */
+    diagnostics: Diagnostic[];
+    events: DevEvent[];
+    stderr?: string;
+}
+export interface RunTestsOptions {
+    directory: string;
+    timeoutMilliseconds?: number;
+}
+export declare function runXeerTests(options: RunTestsOptions): Promise<TestRunResult>;

package/dist/test-run.js

@@ -0,0 +1,118 @@
+import { spawn } from 'node:child_process';
+import { resolveXeerCli } from './xeer-cli.js';
+const DEFAULT_TIMEOUT_MILLISECONDS = 600_000;
+const MAX_EVENTS = 2_000;
+export async function runXeerTests(options) {
+    const cliPath = resolveXeerCli();
+    const argv = ['test', options.directory, '--json'];
+    const timeout = options.timeoutMilliseconds ?? DEFAULT_TIMEOUT_MILLISECONDS;
+    return new Promise((done) => {
+        const child = spawn(process.execPath, [cliPath, ...argv], {
+            cwd: options.directory,
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, NO_UPDATE_NOTIFIER: '1' },
+        });
+        const events = [];
+        const diagnostics = [];
+        const cases = [];
+        let files = [];
+        let summary = null;
+        let reason;
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeout);
+        const ingest = (line) => {
+            let event;
+            try {
+                const parsed = JSON.parse(line);
+                if (parsed?.protocol !== 'xeer.dev.v0' || typeof parsed.type !== 'string')
+                    return;
+                event = parsed;
+            }
+            catch {
+                return;
+            }
+            if (events.length < MAX_EVENTS)
+                events.push(event);
+            switch (event.type) {
+                case 'compile.diagnostic':
+                    diagnostics.push(event.data);
+                    break;
+                case 'test.run.start':
+                    files = event.data.files ?? [];
+                    break;
+                case 'test.case.pass': {
+                    const data = event.data;
+                    cases.push({ file: data.file, name: data.name, status: 'passed',
+                        ...(data.durationMs === undefined ? {} : { durationMs: data.durationMs }) });
+                    break;
+                }
+                case 'test.case.fail': {
+                    const data = event.data;
+                    cases.push({ file: data.file, name: data.name, status: 'failed',
+                        ...(data.durationMs === undefined ? {} : { durationMs: data.durationMs }),
+                        ...(data.failure ? { failure: data.failure } : {}) });
+                    break;
+                }
+                case 'test.run.complete':
+                    summary = event.data;
+                    break;
+                case 'process.exit':
+                    reason = event.data.reason;
+                    break;
+                default:
+                    break;
+            }
+        };
+        child.stdout?.setEncoding('utf8');
+        child.stderr?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => {
+            stdout += chunk;
+            const lines = stdout.split('\n');
+            stdout = lines.pop() ?? '';
+            for (const line of lines)
+                if (line.trim())
+                    ingest(line.trim());
+        });
+        child.stderr?.on('data', (chunk) => { stderr += chunk; });
+        const settle = (exitCode, failure) => {
+            clearTimeout(timer);
+            if (stdout.trim())
+                ingest(stdout.trim());
+            const failed = summary?.failed ?? cases.filter((entry) => entry.status === 'failed').length;
+            const passed = summary?.passed ?? cases.filter((entry) => entry.status === 'passed').length;
+            // A run that failed without emitting either a diagnostic or a summary never
+            // reached the runner. Report it as XE0000 rather than as zero tests passing:
+            // "no failures" and "nothing ran" must never look alike to an agent.
+            if (failure || (exitCode !== 0 && !summary && !diagnostics.length)) {
+                diagnostics.push({
+                    code: 'XE0000',
+                    severity: 'error',
+                    message: failure
+                        ?? (stderr.trim() || `xeer ${argv.join(' ')} exited with ${exitCode} and emitted no events.`),
+                });
+            }
+            done({
+                argv,
+                exitCode,
+                ok: exitCode === 0 && !failure,
+                ...(reason ? { reason } : {}),
+                total: summary?.total ?? cases.length,
+                passed,
+                failed,
+                ...(summary?.durationMs === undefined ? {} : { durationMs: summary.durationMs }),
+                files,
+                cases,
+                diagnostics,
+                events,
+                ...(stderr.trim() ? { stderr: stderr.trim() } : {}),
+            });
+        };
+        child.on('error', (error) => settle(null, `Could not run the xeer CLI: ${error.message}`));
+        child.on('close', (code) => settle(code, timedOut ? `xeer ${argv.join(' ')} exceeded ${timeout} ms and was killed.` : undefined));
+    });
+}

package/dist/xeer-cli.d.ts

@@ -0,0 +1,51 @@
+import type { Diagnostic } from '@impetik/xeer-spec';
+/**
+ * Every tool in this server shells out to the `xeer` CLI with `--json` and
+ * forwards the envelope it printed, unchanged.
+ *
+ * That is deliberate. The CLI's `xeer.command.v0` envelope and its diagnostics
+ * are the versioned contract (docs/specs/dev-protocol-v0.md); re-implementing
+ * the commands against the compiler API would create a second surface that can
+ * drift from the one humans see in a terminal. An agent driving this server and
+ * a human running the CLI observe the same bytes.
+ */
+/** The envelope `xeer <command> --json` writes to stdout. */
+export interface CommandEnvelope {
+    protocol: 'xeer.command.v0';
+    command: string;
+    ok: boolean;
+    diagnostics: Diagnostic[];
+    result?: unknown;
+}
+export interface CommandRun {
+    /** Argv after the CLI path, so a human can reproduce the call. */
+    argv: string[];
+    exitCode: number | null;
+    envelope: CommandEnvelope;
+    /** Present only when the CLI wrote to stderr, which JSON mode reserves for fatal failures. */
+    stderr?: string;
+}
+export declare class XeerCliError extends Error {
+}
+/**
+ * The CLI is resolved through this package's own dependency graph, so the server
+ * cannot silently drive a different xeer than the one it was installed with.
+ * XEER_CLI overrides it for a workspace checkout or a pinned build.
+ */
+export declare function resolveXeerCli(): string;
+/**
+ * Directory arguments are confined to a root, which defaults to the directory
+ * the server was started in. An MCP server is reachable by anything that can
+ * talk to the harness, so "which project" is an authorization question, not a
+ * convenience one. Set XEER_MCP_ROOT to widen it deliberately.
+ */
+export declare function projectRoot(): string;
+/** Resolves a tool's `directory` argument against the confinement root. */
+export declare function resolveDirectory(directory: string | undefined): Promise<string>;
+export interface RunOptions {
+    /** Working directory for the child. Defaults to the resolved project directory. */
+    cwd?: string;
+    timeoutMilliseconds?: number;
+}
+/** Runs `xeer <args> --json` and returns the envelope it printed. */
+export declare function runXeerCommand(args: string[], options?: RunOptions): Promise<CommandRun>;

package/dist/xeer-cli.js

@@ -0,0 +1,123 @@
+import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
+import { realpath } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+export class XeerCliError extends Error {
+}
+const COMMAND_PROTOCOL = 'xeer.command.v0';
+const DEFAULT_TIMEOUT_MILLISECONDS = 300_000;
+/**
+ * The CLI is resolved through this package's own dependency graph, so the server
+ * cannot silently drive a different xeer than the one it was installed with.
+ * XEER_CLI overrides it for a workspace checkout or a pinned build.
+ */
+export function resolveXeerCli() {
+    const override = process.env.XEER_CLI;
+    if (override)
+        return resolve(override);
+    const require = createRequire(import.meta.url);
+    try {
+        return resolve(dirname(require.resolve('@impetik/xeer')), 'cli.js');
+    }
+    catch (error) {
+        throw new XeerCliError('Could not resolve the xeer CLI. Install @impetik/xeer alongside this server, '
+            + `or set XEER_CLI to its dist/cli.js: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/**
+ * Directory arguments are confined to a root, which defaults to the directory
+ * the server was started in. An MCP server is reachable by anything that can
+ * talk to the harness, so "which project" is an authorization question, not a
+ * convenience one. Set XEER_MCP_ROOT to widen it deliberately.
+ */
+export function projectRoot() {
+    return resolve(process.env.XEER_MCP_ROOT ?? process.cwd());
+}
+function contains(root, candidate) {
+    const rel = relative(root, candidate);
+    return rel === '' || (!rel.startsWith(`..${sep}`) && rel !== '..' && !isAbsolute(rel));
+}
+/** Resolves a tool's `directory` argument against the confinement root. */
+export async function resolveDirectory(directory) {
+    const root = projectRoot();
+    const requested = resolve(root, directory ?? '.');
+    const rootReal = await realpath(root).catch(() => root);
+    const requestedReal = await realpath(requested).catch(() => requested);
+    if (!contains(root, requested) || !contains(rootReal, requestedReal)) {
+        throw new XeerCliError(`directory must stay inside ${root}. Received ${requested}. `
+            + 'Set XEER_MCP_ROOT when the server must reach another tree.');
+    }
+    return requested;
+}
+function isEnvelope(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return candidate.protocol === COMMAND_PROTOCOL
+        && typeof candidate.command === 'string'
+        && typeof candidate.ok === 'boolean'
+        && Array.isArray(candidate.diagnostics);
+}
+/**
+ * A CLI crash has no envelope to forward, so one is synthesized with XE0000 —
+ * the same code the CLI itself writes to stderr for an internal failure. A tool
+ * result is therefore always an envelope, and an agent never has to branch on
+ * "did the transport work".
+ */
+function crashEnvelope(command, message) {
+    return {
+        protocol: COMMAND_PROTOCOL,
+        command,
+        ok: false,
+        diagnostics: [{ code: 'XE0000', severity: 'error', message }],
+    };
+}
+/** Runs `xeer <args> --json` and returns the envelope it printed. */
+export async function runXeerCommand(args, options = {}) {
+    const cliPath = resolveXeerCli();
+    const argv = args.includes('--json') ? [...args] : [...args, '--json'];
+    const command = args[0] ?? 'unknown';
+    const timeout = options.timeoutMilliseconds ?? DEFAULT_TIMEOUT_MILLISECONDS;
+    return new Promise((done) => {
+        const child = spawn(process.execPath, [cliPath, ...argv], {
+            ...(options.cwd ? { cwd: options.cwd } : {}),
+            stdio: ['ignore', 'pipe', 'pipe'],
+            env: { ...process.env, NO_UPDATE_NOTIFIER: '1' },
+        });
+        let stdout = '';
+        let stderr = '';
+        let timedOut = false;
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill('SIGKILL');
+        }, timeout);
+        child.stdout?.setEncoding('utf8');
+        child.stderr?.setEncoding('utf8');
+        child.stdout?.on('data', (chunk) => { stdout += chunk; });
+        child.stderr?.on('data', (chunk) => { stderr += chunk; });
+        const settle = (exitCode, failure) => {
+            clearTimeout(timer);
+            // JSON mode prints exactly one envelope; take the last complete line so a
+            // stray warning ahead of it cannot break parsing.
+            const line = stdout.split('\n').map((entry) => entry.trim()).filter(Boolean).at(-1);
+            let envelope = null;
+            if (line) {
+                try {
+                    const parsed = JSON.parse(line);
+                    if (isEnvelope(parsed))
+                        envelope = parsed;
+                }
+                catch { /* Fall through to the synthesized envelope. */ }
+            }
+            done({
+                argv,
+                exitCode,
+                envelope: envelope ?? crashEnvelope(command, failure
+                    ?? (stderr.trim() || `xeer ${argv.join(' ')} exited with ${exitCode} and printed no envelope.`)),
+                ...(stderr.trim() ? { stderr: stderr.trim() } : {}),
+            });
+        };
+        child.on('error', (error) => settle(null, `Could not run the xeer CLI: ${error.message}`));
+        child.on('close', (code) => settle(code, timedOut ? `xeer ${argv.join(' ')} exceeded ${timeout} ms and was killed.` : undefined));
+    });
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@impetik/xeer-mcp",
+  "version": "0.2.1",
+  "type": "module",
+  "description": "Model Context Protocol server for Xeer: the scaffold, check, dev, build, and deploy loop as agent tools.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/impetik/xeer.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/impetik/xeer#readme",
+  "bugs": "https://github.com/impetik/xeer/issues",
+  "keywords": [
+    "xeer",
+    "mcp",
+    "model-context-protocol",
+    "agent",
+    "diagnostics"
+  ],
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "!dist/**/*.map",
+    "!dist/**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "xeer-mcp": "./dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.0.10",
+    "@impetik/xeer": "0.2.1",
+    "@impetik/xeer-spec": "0.2.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.1.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --testTimeout 120000",
+    "test:smoke": "vitest run --config vitest.smoke.config.ts",
+    "start": "node dist/main.js"
+  }
+}