@impetik/xeer-mcp 0.2.3 → 0.2.5

package/README.md

@@ -1,15 +1,22 @@
 # `@impetik/xeer-mcp`
 
 Model Context Protocol server for [Xeer](https://docs.xeer.run), the framework for building and shipping
-full-stack apps. It exposes the scaffold → check → test → build → deploy loop as MCP tools, each
-returning the `xeer.command.v0` JSON envelope the `xeer` CLI already prints.
+full-stack apps. It exposes the scaffold → check → test → build → deploy loop as MCP tools with a
+stable `xeer.mcp-result.v0` result protocol.
 
 📖 **Documentation: [docs.xeer.run](https://docs.xeer.run)** · **Building with AI agents:
 [docs.xeer.run/guides/agents](https://docs.xeer.run/guides/agents)** · **Diagnostics:
 [docs.xeer.run/reference/diagnostics](https://docs.xeer.run/reference/diagnostics)**
 
-The [repository](https://github.com/impetik/xeer) also ships the same protocol as a Claude Code skill
-under `.claude/skills/xeer/`, which you can copy into your own project.
+The [repository](https://github.com/impetik/xeer) keeps the canonical portable skill under
+`.agents/skills/xeer/` and generates provider projections from it. `xeer new` installs those files;
+for an existing project run `xeer agent setup`.
+
+Start with `xeer://project/context` when the client supports MCP resources. Separate normalized project
+resources live at `xeer://project/manifest`, `xeer://project/operations`, and `xeer://project/tests`;
+`xeer://docs/index` lists installed-version Markdown pages exposed by `xeer://docs/{path}`, and
+`xeer://diagnostics/{code}` resolves a stable diagnostic definition. Clients without resource support
+can call `xeer_agent_context` and `xeer_docs_search` instead.
 
 ## Run it
 
@@ -19,41 +26,99 @@ under `.claude/skills/xeer/`, which you can copy into your own project.
   "mcpServers": {
     "xeer": {
       "command": "npx",
-      "args": ["--package=@impetik/xeer-mcp", "--", "xeer-mcp"],
+      "args": ["--package=@impetik/xeer-mcp@<XEER_VERSION>", "--", "xeer-mcp"],
       "env": { "XEER_MCP_ROOT": "." }
     }
   }
 }
 ```
 
+Prefer `xeer agent setup --target mcp`: it replaces `<XEER_VERSION>` and writes this configuration with the exact MCP package
+version compatible with the installed CLI, records a generated-file hash, and refuses to overwrite an
+unowned `.mcp.json`. `XEER_MCP_ROOT: "."` keeps all project paths confined to the checkout.
+
+This starts the default `author` profile: `xeer_deploy_preview` always targets preview, and no
+production-changing tool is registered. An operator who deliberately wants to expose reviewed
+promotion must add `"XEER_MCP_PROFILE": "operator"` to the server environment. A tool argument cannot
+change profiles, and operator promotion requires the exact `receiptId` returned by preview deploy. MCP
+has no artifact-id or current-slot bypass.
+
 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> [--template <name>] --json` | `result.template`, `result.files` |
-| `xeer_doctor` | `xeer doctor <dir> --json` | `result.checks`, `result.summary` |
-| `xeer_deploy` | `xeer deploy <dir> --json` | `result.url` (`environment: "preview"` deploys to the side-by-side preview URL) |
-| `xeer_promote` | `xeer promote <dir> --json` | `result.artifactId`, `result.replaced`, `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.
+## Registered action policy
+
+The generated registry is the complete MCP tool and exclusion surface:
+
+<!-- xeer-action-reference:start -->
+<!-- Generated from packages/spec/src/actions.ts by `pnpm generate:agent-reference`. Do not edit. -->
+
+**MCP tools (15 total; 14 author, 15 operator).** Inputs ending in `?` are optional.
+
+| Tool | Action | Profiles | Summary | Inputs | Effects | Safety | Path policy | Output | Human prerequisite |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| `xeer_check` | `check` | `author` / `operator` | Validate a project and report structured diagnostics. | `directory?`: `string` | `read-source`<br>`write-generated` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | none |
+| `xeer_build` | `build` | `author` / `operator` | Build and verify a content-addressed application artifact. | `directory?`: `string` | `read-source`<br>`write-generated`<br>`run-local` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | none |
+| `xeer_test` | `test` | `author` / `operator` | Run application tests against fresh isolated local state. | `directory?`: `string`<br>`timeoutMilliseconds?`: `integer` [1000..1800000] | `read-source`<br>`write-generated`<br>`run-local`<br>`write-state` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.dev.v0` | none |
+| `xeer_new` | `new` | `author` / `operator` | Create a new project from a supported scaffold. | `directory`: `string`<br>`template?`: `notes` / `todo` / `blog` / `personal-site` | `write-source` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | none |
+| `xeer_agent_context` | `agent.context` | `author` / `operator` | Read normalized project facts, operations, diagnostics, tests, and safe next actions. | `directory?`: `string` | `read-source` | read-only; idempotent; reversible; non-destructive | `project-relative` | `xeer.agent-context.v0` | none |
+| `xeer_docs_search` | `docs.search` | `author` / `operator` | Search the installed-version Xeer documentation index. | `query`: `string`<br>`limit?`: `integer` [1..20]; default `5` | none | read-only; idempotent; reversible; non-destructive | `none` | `xeer.docs-search.v0` | none |
+| `xeer_doctor` | `doctor` | `author` / `operator` | Diagnose the toolchain and generated project state. | `directory?`: `string` | `read-source`<br>`write-generated` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | none |
+| `xeer_deploy_preview` | `deploy.preview` | `author` / `operator` | Build and deploy an artifact to preview only. | `directory?`: `string`<br>`controlUrl?`: `string` | `read-source`<br>`write-generated`<br>`run-local`<br>`network-read`<br>`network-write` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | A human must establish the builder credential with xeer auth login. |
+| `xeer_promote` | `promote.operator` | `operator` | Promote an exact review receipt in operator mode. | `directory?`: `string`<br>`receiptId`: `string`<br>`controlUrl?`: `string` | `network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | A human must review the exact artifact and start xeer-mcp with XEER_MCP_PROFILE=operator. |
+| `xeer_auth_status` | `auth.status` | `author` / `operator` | Report builder credential metadata. | `controlUrl?`: `string` | `network-read`<br>`secret-metadata` | read-only; idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | none |
+| `xeer_inspect` | `inspect` | `author` / `operator` | Read a running application manifest. | `previewUrl`: `string`<br>`view?`: `manifest` / `state` / `logs` / `export`; default `manifest`<br>`after?`: `string` | `network-read`<br>`read-state` | read-only; idempotent; reversible; non-destructive | `app-or-url` | `xeer.command.v0` | none |
+| `xeer_dev_start` | `dev.start` | `author` / `operator` | Start a local development session. | `directory?`: `string`<br>`host?`: `string`<br>`port?`: `integer` [0..65535]<br>`timeoutMilliseconds?`: `integer` [1000..600000] | `read-source`<br>`write-generated`<br>`run-local`<br>`write-state` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.dev.v0` | none |
+| `xeer_dev_status` | `dev.status` | `author` / `operator` | Read new events from a local development session. | `sessionId?`: `string`<br>`cursor?`: `integer` [0..9007199254740991]; default `0`<br>`waitMilliseconds?`: `integer` [0..600000]; default `0`<br>`limit?`: `integer` [1..1000]; default `200` | none | read-only; idempotent; reversible; non-destructive | `none` | `xeer.dev.v0` | none |
+| `xeer_dev_stop` | `dev.stop` | `author` / `operator` | Stop a local development session and release its lease. | `sessionId?`: `string`<br>`cursor?`: `integer` [0..9007199254740991]; default `0` | `run-local` | writes; idempotent; reversible; non-destructive | `none` | `xeer.dev.v0` | none |
+| `xeer_diagnostics` | `diagnostics` | `author` / `operator` | Read the generated diagnostic catalogue. | `code?`: `string` | none | read-only; idempotent; reversible; non-destructive | `none` | `unversioned` | none |
+
+**CLI actions intentionally excluded from MCP (31).**
+
+| CLI action | Action | Summary | Effects | Safety | Path policy | Output | Why no MCP tool |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| `xeer agent setup` | `agent.setup` | Install or verify project-confined agent adapters. | `read-source`<br>`write-source` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer deploy` | `deploy` | Build and deploy an application artifact. | `read-source`<br>`write-generated`<br>`run-local`<br>`network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | MCP exposes a separate preview-only deploy action; direct production deploy stays CLI-only. |
+| `xeer promote` | `promote` | Promote a preview artifact to production. | `network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | MCP promotion is a separate action available only when the server starts in operator profile. |
+| `xeer link` | `link` | Link a checkout to an application the builder owns. | `read-source`<br>`write-source`<br>`network-read`<br>`network-write` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Human identity and project ownership decisions are not delegated through MCP. |
+| `xeer deployments` | `deployments` | List deployment history for an application. | `network-read`<br>`read-state`<br>`secret-metadata` | read-only; idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer rollback` | `rollback` | Redeploy a previously deployed artifact. | `network-read`<br>`network-write`<br>`production-change` | writes; non-idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer disable` | `disable` | Take an application offline without deleting its data. | `network-read`<br>`network-write`<br>`production-change` | writes; idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer enable` | `enable` | Restore a disabled application to service. | `network-read`<br>`network-write`<br>`production-change` | writes; idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer delete` | `delete` | Permanently delete an application and all of its data. | `network-read`<br>`network-write`<br>`write-state`<br>`production-change` | writes; non-idempotent; irreversible; destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer domains add` | `domains.add` | Attach a customer-owned hostname to an application. | `network-read`<br>`network-write`<br>`production-change` | writes; idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer domains ls` | `domains.ls` | List an application's platform and custom domains. | `network-read` | read-only; idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer domains status` | `domains.status` | Refresh hostname and certificate validation. | `network-read`<br>`network-write`<br>`production-change` | writes; idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer domains remove` | `domains.remove` | Detach a custom hostname and delete its provider certificate. | `network-read`<br>`network-write`<br>`production-change` | writes; idempotent; reversible; destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer preview` | `preview` | Run a verified artifact in a local preview server. | `read-source`<br>`write-generated`<br>`run-local`<br>`write-state` | writes; non-idempotent; reversible; non-destructive | `project-relative` | `xeer.dev.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer state` | `state.read` | Read record counts from a running application. | `network-read`<br>`read-state` | read-only; idempotent; reversible; non-destructive | `app-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer state reset` | `state.reset` | Permanently reset local environment state. | `read-source`<br>`write-state` | writes; non-idempotent; irreversible; destructive | `project-relative` | `xeer.command.v0` | Destructive state replacement requires an explicit CLI invocation. |
+| `xeer logs` | `logs` | Read the bounded log ring of a running application. | `network-read`<br>`read-state` | read-only; idempotent; reversible; non-destructive | `app-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer export` | `export` | Export application state to a document. | `network-read`<br>`read-state`<br>`write-file` | writes; idempotent; reversible; non-destructive | `project-or-url` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer import` | `import` | Replace local or preview state from an export document. | `read-source`<br>`network-write`<br>`write-state` | writes; non-idempotent; irreversible; destructive | `project-or-url` | `xeer.command.v0` | Destructive state replacement requires an explicit CLI invocation. |
+| `xeer auth login` | `auth.login` | Establish a human builder credential. | `network-read`<br>`network-write`<br>`secret-write` | writes; non-idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | Human identity and project ownership decisions are not delegated through MCP. |
+| `xeer auth logout` | `auth.logout` | Remove the local builder credential. | `network-write`<br>`secret-write` | writes; idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | Human identity and project ownership decisions are not delegated through MCP. |
+| `xeer auth as` | `auth.as` | Select a deterministic local development persona. | `write-state` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer auth clear` | `auth.clear` | Reset the local development persona. | `write-state` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+| `xeer env set` | `env.set` | Set an environment value or secret. | `network-write`<br>`write-state`<br>`secret-write` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Secret values are intentionally unreachable through MCP; env pull returns plaintext. |
+| `xeer env ls` | `env.ls` | List environment variable names and metadata. | `network-read`<br>`secret-metadata` | read-only; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Secret values are intentionally unreachable through MCP; env pull returns plaintext. |
+| `xeer env rm` | `env.rm` | Remove an environment value or secret. | `network-write`<br>`write-state`<br>`secret-write` | writes; idempotent; irreversible; destructive | `project-relative` | `xeer.command.v0` | Secret values are intentionally unreachable through MCP; env pull returns plaintext. |
+| `xeer env pull` | `env.pull` | Write development secrets to a local file. | `network-read`<br>`write-file`<br>`secret-read` | writes; idempotent; reversible; non-destructive | `project-relative` | `xeer.command.v0` | Secret values are intentionally unreachable through MCP; env pull returns plaintext. |
+| `xeer token create` | `token.create` | Issue a service builder token. | `network-write`<br>`secret-write` | writes; non-idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | Service credential issuance and revocation are intentionally CLI-only. |
+| `xeer token ls` | `token.ls` | List service token metadata. | `network-read`<br>`secret-metadata` | read-only; idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | Service credential issuance and revocation are intentionally CLI-only. |
+| `xeer token revoke` | `token.revoke` | Revoke a service builder token. | `network-write`<br>`secret-write` | writes; idempotent; irreversible; destructive | `none` | `xeer.command.v0` | Service credential issuance and revocation are intentionally CLI-only. |
+| `xeer actions` | `actions` | Print the machine-readable action and safety catalogue. | none | read-only; idempotent; reversible; non-destructive | `none` | `xeer.command.v0` | Not exposed through MCP v0; use the CLI deliberately. |
+<!-- xeer-action-reference:end -->
+
+Every tool returns `{ protocol: "xeer.mcp-result.v0", action, ok, result?, error? }` both as
+`structuredContent` and as a JSON text block. Command tools preserve the CLI's
+`xeer.command.v0` envelope at `result.envelope`, alongside `result.exitCode`. Host argv,
+raw stderr, and absolute directories are omitted. A CLI crash still produces an `XE0000`
+command envelope; an application-level refusal produces a stable `error.code` without
+turning the response into an MCP transport error.
 
 `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
@@ -62,11 +127,6 @@ assertion, `XE1905` throw or unexpectedly refused call, `XE1906` timeout) that i
 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
@@ -74,10 +134,10 @@ is therefore owned by the server and addressed by a `sessionId`, with the protoc
 `seq` as a resumable cursor:
 
 ```text
-xeer_dev_start  → { sessionId, cursor, status: 'ready', preview: { url, inspectorUrl, ... }, events }
+xeer_dev_start  → { result: { 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' }
+xeer_dev_status → { result: { events: [compile.start, compile.diagnostic?, compile.ready?], openDiagnostics, generation } }
+xeer_dev_stop   → { result: { status: 'stopped' } }
 ```
 
 No event is summarized away, so the agent reads the same stream a terminal would show.
@@ -88,8 +148,18 @@ session exists for when the preview, the inspector, or rebuild/rollback behaviou
 
 | Variable | Effect |
 | --- | --- |
+| `XEER_MCP_PROFILE` | `author` (default) exposes no production-changing action. `operator` additionally exposes exact-artifact `xeer_promote`; any other value refuses server startup. |
 | `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. |
+| `XEER_MCP_CONTROL_ORIGINS` | Comma-separated additional exact HTTPS or loopback development control-plane origins that MCP may send builder credentials to. Only hosted `https://control.xeer.run` is allowed by default; plaintext non-loopback origins are always refused. |
+| `XEER_MCP_INSPECTOR_ORIGINS` | Comma-separated exact loopback HTTP origins for preview servers started outside this MCP server. A preview started with `xeer_dev_start` is allowed automatically only while that session remains active. |
+
+URL-shaped inspector targets are confined separately: MCP accepts the loopback HTTP origin of an active
+`xeer_dev_start` session (or an exact operator-configured origin) and exact hosted
+`https://<app>.xeer.run` origins. Bare application names and appIds are safe because the authenticated
+control plane resolves them; arbitrary, private-network,
+link-local, custom-domain, and credential-bearing URLs are refused before the CLI runs. Use an app
+name or appId to inspect an application that serves a custom domain.
 
 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

package/dist/dev-session.js

@@ -1,5 +1,12 @@
 import { fork } from 'node:child_process';
 import { resolveXeerCli } from './xeer-cli.js';
+function hasPreviewUrls(value) {
+    if (typeof value !== 'object' || value === null)
+        return false;
+    const candidate = value;
+    return ['url', 'healthUrl', 'inspectorUrl', 'debugUrl', 'logsUrl']
+        .every((key) => typeof candidate[key] === 'string');
+}
 const MAX_BUFFERED_EVENTS = 2_000;
 const MAX_STDERR_CHARACTERS = 4_096;
 const DEFAULT_START_TIMEOUT_MILLISECONDS = 180_000;
@@ -123,6 +130,11 @@ export class DevSession {
                 this.#compiling = true;
                 break;
             case 'server.restarted':
+                // A Vite restart may bind a different port when automation requested port 0. The URLs on
+                // a current event replace preview.ready immediately. Keep the last valid discovery values
+                // when supervising an older CLI whose pre-v0 payload did not yet carry URLs.
+                if (hasPreviewUrls(event.data))
+                    this.#preview = event.data;
                 this.#restarting = false;
                 this.#compiling = false;
                 break;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-export { createXeerMcpServer, type XeerMcpServer } from './server.js';
+export { createXeerMcpServer, mcpProfile, type XeerMcpServer, type XeerMcpServerOptions, } 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

@@ -1,4 +1,4 @@
-export { createXeerMcpServer } from './server.js';
+export { createXeerMcpServer, mcpProfile, } 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.js

@@ -1,11 +1,19 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createXeerMcpServer } from './server.js';
+import { createXeerMcpServer, mcpProfile } 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 instance;
+try {
+    instance = createXeerMcpServer({ profile: mcpProfile(process.env.XEER_MCP_PROFILE) });
+}
+catch (error) {
+    process.stderr.write(`xeer-mcp failed to start: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+}
+const { server, devSessions } = instance;
 let closing = false;
 async function shutdown(code) {
     if (closing)

package/dist/network-policy.d.ts

@@ -0,0 +1,4 @@
+/** Undefined means the explicit control origin is safe to receive the builder credential. */
+export declare function controlOriginRefusal(value: string | undefined, configured?: string | undefined): string | undefined;
+/** Undefined means the target cannot make MCP perform an arbitrary direct network read. */
+export declare function inspectorTargetRefusal(value: string, activeLocalOrigins?: readonly string[], configured?: string | undefined): string | undefined;

package/dist/network-policy.js

@@ -0,0 +1,65 @@
+import { DEFAULT_XEER_CONTROL_ORIGIN, exactHttpOrigin, isHostedXeerApplicationTarget, isLocalInspectorTarget, isLoopbackHostname, } from '@impetik/xeer-spec/network-policy';
+const APP_ID = /^app_[A-Za-z0-9_-]{8,96}$/u;
+const APPLICATION_NAME = /^[a-z][a-z0-9-]{1,62}$/u;
+function configuredControlOrigins(value) {
+    const result = new Set();
+    for (const entry of value?.split(',') ?? []) {
+        const origin = exactHttpOrigin(entry);
+        if (!origin)
+            continue;
+        const url = new URL(origin);
+        // Configuration can add an HTTPS control plane or a loopback development one; it can never opt
+        // a plaintext non-loopback endpoint into receiving a credential.
+        if (url.protocol === 'https:' || isLoopbackHostname(url.hostname))
+            result.add(origin);
+    }
+    return result;
+}
+function configuredInspectorOrigins(value) {
+    const result = new Set();
+    for (const entry of value?.split(',') ?? []) {
+        const origin = exactHttpOrigin(entry);
+        if (!origin)
+            continue;
+        const url = new URL(origin);
+        if (url.protocol === 'http:' && isLoopbackHostname(url.hostname))
+            result.add(origin);
+    }
+    return result;
+}
+/** Undefined means the explicit control origin is safe to receive the builder credential. */
+export function controlOriginRefusal(value, configured = process.env.XEER_MCP_CONTROL_ORIGINS) {
+    if (value === undefined)
+        return undefined;
+    const origin = exactHttpOrigin(value);
+    if (!origin) {
+        return 'The MCP controlUrl must be an exact HTTP(S) origin with no credentials, path, query, or fragment.';
+    }
+    if (origin === DEFAULT_XEER_CONTROL_ORIGIN || configuredControlOrigins(configured).has(origin))
+        return undefined;
+    return 'The MCP controlUrl is not allowed to receive builder credentials. Use https://control.xeer.run, '
+        + 'or preconfigure the exact HTTPS or loopback development origin in XEER_MCP_CONTROL_ORIGINS.';
+}
+/** Undefined means the target cannot make MCP perform an arbitrary direct network read. */
+export function inspectorTargetRefusal(value, activeLocalOrigins = [], configured = process.env.XEER_MCP_INSPECTOR_ORIGINS) {
+    const target = value.trim();
+    if (!target)
+        return 'The inspector target must not be empty.';
+    if (isLocalInspectorTarget(target)) {
+        const origin = new URL(target).origin;
+        const allowed = new Set([
+            ...activeLocalOrigins.map((entry) => exactHttpOrigin(entry)).filter((entry) => entry !== undefined),
+            ...configuredInspectorOrigins(configured),
+        ]);
+        if (allowed.has(origin))
+            return undefined;
+        return 'The loopback inspector origin is not an active MCP dev session. Start it with xeer_dev_start '
+            + 'or preconfigure the exact origin in XEER_MCP_INSPECTOR_ORIGINS.';
+    }
+    // Hosted URLs are not fetched directly: the CLI encodes them into the authenticated control-plane
+    // lookup path, which owner-resolves the application before proxying its inspector.
+    if (isHostedXeerApplicationTarget(target) || APP_ID.test(target) || APPLICATION_NAME.test(target))
+        return undefined;
+    return 'MCP inspector URLs must be loopback HTTP URLs from xeer dev/preview or exact hosted '
+        + 'https://<app>.xeer.run origins. Use the application name or appId for a custom hosted domain.';
+}

package/dist/server.d.ts

@@ -1,7 +1,13 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type XeerMcpProfile } from '@impetik/xeer-spec/actions';
 import { DevSessionRegistry } from './dev-session.js';
 export interface XeerMcpServer {
     server: McpServer;
     devSessions: DevSessionRegistry;
+    profile: XeerMcpProfile;
 }
-export declare function createXeerMcpServer(): XeerMcpServer;
+export interface XeerMcpServerOptions {
+    readonly profile?: XeerMcpProfile;
+}
+export declare function mcpProfile(value: string | undefined): XeerMcpProfile;
+export declare function createXeerMcpServer(options?: XeerMcpServerOptions): XeerMcpServer;

package/dist/server.js

@@ -1,24 +1,86 @@
 import { createRequire } from 'node:module';
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { isAbsolute, relative, sep } from 'node:path';
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
-import { DEFAULT_TEMPLATE, TEMPLATES } from '@impetik/xeer';
+import { createAgentContext, readDocsIndex, readDocsPage, searchDocs } from '@impetik/xeer/agent-context';
 import { DIAGNOSTICS, DIAGNOSTIC_CODES, DIAGNOSTIC_FAMILIES, diagnosticDefinition, renderDiagnosticsReference, } from '@impetik/xeer-spec/diagnostics';
+import { actionDefinition, mcpAnnotations, } from '@impetik/xeer-spec/actions';
+import { isReviewReceiptId } from '@impetik/xeer-spec/review';
 import { DevSessionRegistry } from './dev-session.js';
+import { controlOriginRefusal, inspectorTargetRefusal } from './network-policy.js';
 import { runXeerTests } from './test-run.js';
-import { projectRoot, resolveDirectory, runXeerCommand, XeerCliError } from './xeer-cli.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
+ * preserving the `xeer.command.v0` envelope inside `xeer.mcp-result.v0`. The 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.');
+function inputPropertySchema(property) {
+    let schema;
+    if (property.type === 'string') {
+        if (property.enum?.length === 0)
+            throw new Error('MCP input enum must contain at least one value.');
+        if (property.enum) {
+            if (property.minLength !== undefined || property.maxLength !== undefined || property.pattern !== undefined) {
+                throw new Error('MCP string enum inputs cannot also declare length or pattern constraints.');
+            }
+            schema = z.enum(property.enum);
+        }
+        else {
+            let string = z.string();
+            if (property.minLength !== undefined)
+                string = string.min(property.minLength);
+            if (property.maxLength !== undefined)
+                string = string.max(property.maxLength);
+            if (property.pattern !== undefined)
+                string = string.regex(new RegExp(property.pattern, 'u'));
+            schema = string;
+        }
+    }
+    else if (property.type === 'boolean') {
+        schema = z.boolean();
+    }
+    else {
+        let number = z.number();
+        if (property.type === 'integer')
+            number = number.int();
+        if (property.minimum !== undefined)
+            number = number.min(property.minimum);
+        if (property.maximum !== undefined)
+            number = number.max(property.maximum);
+        schema = number;
+    }
+    if (property.description !== undefined)
+        schema = schema.describe(property.description);
+    return schema;
+}
+/** Runtime MCP presentation and validation come from the registry projected by listTools and the docs. */
+function toolPolicy(id) {
+    const definition = actionDefinition(id);
+    const registered = definition?.surfaces.mcpInputSchema;
+    if (!registered)
+        throw new Error(`Action ${id} has no registered MCP input schema.`);
+    const title = definition.surfaces.mcpTitle;
+    const description = definition.surfaces.mcpDescription;
+    if (!title || !description)
+        throw new Error(`Action ${id} has no registered MCP presentation.`);
+    const required = new Set(registered.required ?? []);
+    const inputSchema = Object.fromEntries(Object.entries(registered.properties).map(([name, property]) => {
+        let schema = inputPropertySchema(property);
+        if (property.default !== undefined)
+            schema = schema.default(property.default);
+        else if (!required.has(name))
+            schema = schema.optional();
+        return [name, schema];
+    }));
+    return { title, description, inputSchema, annotations: mcpAnnotations(definition) };
+}
 /** Mirrors the Diagnostic interface in @impetik/xeer-spec, loosely so new fields pass through. */
 const diagnosticSchema = z.object({
     code: z.string(),
@@ -32,107 +94,232 @@ const diagnosticSchema = z.object({
     }).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(),
+const commandEnvelopeOutput = {
     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) {
+const mcpErrorSchema = z.object({ code: z.string(), message: z.string() });
+const wrappedOutput = (result) => ({
+    protocol: z.literal('xeer.mcp-result.v0'),
+    action: z.string(),
+    ok: z.boolean(),
+    result: result.optional(),
+    error: mcpErrorSchema.optional(),
+});
+const commandOutput = wrappedOutput(z.object({
+    exitCode: z.number().nullable(),
+    envelope: z.object(commandEnvelopeOutput).loose(),
+}));
+function structured(action, result, options = {}) {
+    const reusableResult = reusableValue(result);
+    const payload = {
+        protocol: 'xeer.mcp-result.v0',
+        action,
+        ok: options.ok ?? true,
+        ...(reusableResult === undefined ? {} : { result: reusableResult }),
+        ...(options.error ? { error: reusableValue(options.error) } : {}),
+    };
     return {
         // The text block is the same JSON, because a client that ignores
-        // structuredContent must still see the whole envelope.
+        // structuredContent must still see the whole wrapper.
         content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
         structuredContent: payload,
-        ...(payload['ok'] === false ? { isError: false } : {}),
+        ...(payload.ok === false ? { isError: false } : {}),
     };
 }
-function failure(message) {
-    return { content: [{ type: 'text', text: message }], isError: true };
+function failure(action, code, message) {
+    return structured(action, undefined, { ok: false, error: { code, message } });
+}
+function escapeRegularExpression(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/** Removes the configured host root from every public string, including nested diagnostics/events. */
+function reusableString(value) {
+    const root = projectRoot();
+    const roots = new Set([root, root.split('\\').join('/'), root.split('/').join('\\')]);
+    let output = value;
+    for (const candidate of roots) {
+        output = output.replace(new RegExp(escapeRegularExpression(candidate), 'gi'), '.');
+    }
+    return output;
+}
+function reusableValue(value) {
+    if (typeof value === 'string')
+        return reusableString(value);
+    if (Array.isArray(value))
+        return value.map(reusableValue);
+    if (typeof value !== 'object' || value === null)
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, reusableValue(entry)]));
+}
+function projectPath(path) {
+    const output = relative(projectRoot(), path).split(sep).join('/');
+    return output || '.';
+}
+function reusableEnvelope(envelope) {
+    if (envelope.command !== 'new' || typeof envelope.result !== 'object' || envelope.result === null)
+        return envelope;
+    const result = envelope.result;
+    return {
+        ...envelope,
+        result: {
+            ...result,
+            ...(typeof result['directory'] === 'string'
+                ? { directory: isAbsolute(result['directory']) ? projectPath(result['directory']) : result['directory'] }
+                : {}),
+        },
+    };
 }
-/** 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,
+/** Runs a CLI command and wraps its envelope without exposing host argv or stderr. */
+async function commandTool(action, args, directory) {
+    let run;
+    try {
+        run = await runXeerCommand(args, { cwd: directory });
+    }
+    catch (error) {
+        if (error instanceof XeerCliError)
+            return failure(action, 'adapter_unavailable', error.message);
+        return failure(action, 'adapter_failure', 'The xeer CLI adapter failed before producing a result.');
+    }
+    const envelope = reusableEnvelope(run.envelope);
+    const adapterDiagnostic = envelope.diagnostics.find((diagnostic) => diagnostic.code === 'XE0000');
+    return structured(action, {
         exitCode: run.exitCode,
-        ...run.envelope,
-        ...(run.stderr ? { stderr: run.stderr } : {}),
+        envelope,
+    }, {
+        ok: envelope.ok,
+        ...(adapterDiagnostic ? {
+            error: { code: 'adapter_failure', message: adapterDiagnostic.message },
+        } : {}),
     });
 }
-async function withDirectory(directory, body) {
+async function withDirectory(directory, action, body) {
+    let resolved;
     try {
-        return await body(await resolveDirectory(directory));
+        resolved = await resolveDirectory(directory);
     }
     catch (error) {
         if (error instanceof XeerCliError)
-            return failure(error.message);
+            return failure(action, 'path_refused', error.message);
         throw error;
     }
+    return body(resolved);
+}
+export function mcpProfile(value) {
+    if (value === undefined || value.trim() === '')
+        return 'author';
+    if (value === 'author' || value === 'operator')
+        return value;
+    throw new Error(`Invalid XEER_MCP_PROFILE ${JSON.stringify(value)}; expected "author" or "operator".`);
 }
-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() {
+export function createXeerMcpServer(options = {}) {
+    const profile = options.profile ?? 'author';
     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()}.`,
+            'This server is confined to its configured project root.',
             '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',
+            'xeer_build, then xeer_deploy_preview. A green check means it compiles; only a green test means it works.',
+            'The author profile cannot change production. Promotion is available only when a human starts',
+            'the server with XEER_MCP_PROFILE=operator, and then requires an exact artifact id.',
+            'Tools return xeer.mcp-result.v0; command results preserve the CLI xeer.command.v0 envelope',
+            'under result.envelope. Dispatch on that envelope\'s 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();
+    const jsonResource = (uri, value) => ({
+        contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(reusableValue(value), null, 2) }],
+    });
+    const contextResource = async (uri, select) => jsonResource(uri, select(await createAgentContext(projectRoot())));
+    server.registerResource('project-context', 'xeer://project/context', {
+        title: 'Normalized Xeer project context', description: 'Bounded, deterministic, read-only AgentContextV0.',
+        mimeType: 'application/json',
+    }, async (uri) => contextResource(uri, (context) => context));
+    server.registerResource('project-manifest', 'xeer://project/manifest', {
+        title: 'Normalized application manifest', mimeType: 'application/json',
+    }, async (uri) => contextResource(uri, (context) => ({
+        ...context.application,
+        capabilities: context.capabilities,
+        storage: context.storage,
+        budgets: context.budgets,
+        database: context.schema,
+    })));
+    server.registerResource('project-operations', 'xeer://project/operations', {
+        title: 'Discovered application operations', mimeType: 'application/json',
+    }, async (uri) => contextResource(uri, (context) => context.operations));
+    server.registerResource('project-tests', 'xeer://project/tests', {
+        title: 'Application test inventory', mimeType: 'application/json',
+    }, async (uri) => contextResource(uri, (context) => context.tests));
+    server.registerResource('docs-index', 'xeer://docs/index', {
+        title: 'Installed Xeer documentation index', description: 'Compact version-matched page and content-hash index.',
+        mimeType: 'application/json',
+    }, async (uri) => {
+        const docs = await readDocsIndex();
+        return jsonResource(uri, {
+            ...docs.index,
+            ...(docs.compatibilityWarning ? { compatibilityWarning: docs.compatibilityWarning } : {}),
+        });
+    });
+    const docsTemplate = new ResourceTemplate('xeer://docs/{+path}', {
+        list: async () => {
+            const { index } = await readDocsIndex();
+            return { resources: index.pages.map((page) => ({
+                    uri: `xeer://docs${page.path === '/' ? '/' : page.path}`,
+                    name: page.title,
+                    title: page.title,
+                    description: page.description,
+                    mimeType: 'text/markdown',
+                })) };
+        },
+    });
+    server.registerResource('docs-page', docsTemplate, {
+        title: 'Installed Xeer documentation page', description: 'A version-matched Markdown page loaded on demand.',
+        mimeType: 'text/markdown',
+    }, async (uri, variables) => {
+        const raw = variables.path;
+        const path = Array.isArray(raw) ? raw.join('/') : String(raw ?? '');
+        const page = await readDocsPage(path);
+        return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text: page.markdown }] };
+    });
+    const diagnosticsTemplate = new ResourceTemplate('xeer://diagnostics/{code}', { list: undefined });
+    server.registerResource('diagnostic', diagnosticsTemplate, {
+        title: 'Xeer diagnostic definition', mimeType: 'application/json',
+    }, async (uri, variables) => {
+        const code = String(variables.code ?? '').toUpperCase();
+        const definition = diagnosticDefinition(code);
+        if (!definition)
+            throw new Error(`Unknown Xeer diagnostic code: ${code}`);
+        return jsonResource(uri, definition);
+    });
+    server.registerTool('xeer_agent_context', {
+        ...toolPolicy('agent.context'),
+        outputSchema: wrappedOutput(z.object({ protocol: z.literal('xeer.agent-context.v0') }).loose()),
+    }, async ({ directory }) => withDirectory(directory, 'agent.context', async (resolved) => structured('agent.context', await createAgentContext(resolved))));
+    server.registerTool('xeer_docs_search', {
+        ...toolPolicy('docs.search'),
+        outputSchema: wrappedOutput(z.object({
+            protocol: z.literal('xeer.docs-search.v0'), query: z.string(), results: z.array(z.object({
+                path: z.string(), uri: z.string(), title: z.string(), canonicalUrl: z.string(), contentHash: z.string(), score: z.number(),
+            }).loose()),
+        }).loose()),
+    }, async ({ query, limit }) => structured('docs.search', await searchDocs(query, limit)));
     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)));
+        ...toolPolicy('check'),
+        outputSchema: commandOutput,
+    }, async ({ directory }) => withDirectory(directory, 'check', (resolved) => commandTool('check', ['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)));
+        ...toolPolicy('build'),
+        outputSchema: commandOutput,
+    }, async ({ directory }) => withDirectory(directory, 'build', (resolved) => commandTool('build', ['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()),
+        ...toolPolicy('test'),
+        outputSchema: wrappedOutput(z.object({
             exitCode: z.number().nullable(),
             ok: z.boolean(),
             reason: z.string().optional(),
@@ -156,103 +343,80 @@ export function createXeerMcpServer() {
                 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 }),
+        }).loose()),
+    }, async ({ directory, timeoutMilliseconds }) => withDirectory(directory, 'test', async (resolved) => {
+        let run;
+        try {
+            run = await runXeerTests({
+                directory: resolved,
+                ...(timeoutMilliseconds === undefined ? {} : { timeoutMilliseconds }),
+            });
+        }
+        catch (error) {
+            if (error instanceof XeerCliError)
+                return failure('test', 'adapter_unavailable', error.message);
+            return failure('test', 'adapter_failure', 'The xeer test adapter failed before producing a result.');
+        }
+        const { argv: _argv, stderr: _stderr, ...reusable } = run;
+        const adapterDiagnostic = run.diagnostics.find((diagnostic) => diagnostic.code === 'XE0000');
+        return structured('test', reusable, {
+            ok: run.ok,
+            ...(adapterDiagnostic ? {
+                error: { code: 'adapter_failure', message: adapterDiagnostic.message },
+            } : {}),
         });
-        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. '
-            + 'Every template checks, tests, and builds clean, so use one as the starting point rather '
-            + 'than writing a manifest by hand. "notes" (the default) and "todo" are per-user apps, "blog" '
-            + 'is public to read and private to write, and "personal-site" has no database at all. None of '
-            + 'them scaffolds sign-in UI. result is { directory, name, template, files }; an unknown '
-            + 'template is XE3002 and writes nothing.',
-        inputSchema: {
-            directory: z.string().describe('Target directory, relative to the server root. Must be empty or absent.'),
-            // The names come from the CLI itself, so this schema cannot advertise a template the
-            // installed CLI does not have — or omit one it does.
-            template: z.enum(TEMPLATES).optional()
-                .describe(`Which scaffold to write. Defaults to ${DEFAULT_TEMPLATE}.`),
-        },
-        outputSchema: envelopeOutput,
-        annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    }, async ({ directory, template }) => withDirectory(directory, (resolved) => commandTool(['new', resolved, ...(template === undefined ? [] : ['--template', template])], projectRoot())));
+        ...toolPolicy('new'),
+        outputSchema: commandOutput,
+    }, async ({ directory, template }) => withDirectory(directory, 'new', (resolved) => commandTool('new', ['new', resolved, ...(template === undefined ? [] : ['--template', template])], 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, ... }. Defaults to production; pass environment "preview" to deploy to the '
-            + 'app\'s side-by-side preview URL instead, which is what to iterate against — production keeps '
-            + 'serving, and preview has its own disposable state. Make a preview live with xeer_promote.',
-        inputSchema: {
-            directory: directoryArgument,
-            environment: z.enum(['production', 'preview']).optional()
-                .describe('Deployment target. Omit for production; "preview" leaves production untouched.'),
-            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, environment, controlUrl }) => withDirectory(directory, (resolved) => commandTool(['deploy', resolved, ...(environment ? ['--environment', environment] : []),
-        ...(controlUrl ? ['--control-url', controlUrl] : [])], resolved)));
-    server.registerTool('xeer_promote', {
-        title: 'Promote a Xeer preview to production',
-        description: 'Make the version currently on the app\'s preview URL live on production — the same '
-            + 'bundle, not a rebuild, with production\'s own environment values. The second half of the '
-            + '"deploy to preview, look at it, then ship it" loop. XE5175 means nothing has been deployed to '
-            + 'preview yet. result is { artifactId, replaced, url, ... }.',
-        inputSchema: {
-            directory: directoryArgument,
-            fromArtifact: z.string().optional()
-                .describe('Promote this artifact id instead of whatever preview is serving, e.g. sha256:….'),
-            controlUrl: z.string().optional().describe('Control-plane origin override.'),
-        },
-        outputSchema: envelopeOutput,
-        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    }, async ({ directory, fromArtifact, controlUrl }) => withDirectory(directory, (resolved) => commandTool(['promote', resolved, ...(fromArtifact ? ['--from-artifact', fromArtifact] : []),
-        ...(controlUrl ? ['--control-url', controlUrl] : [])], resolved)));
+        ...toolPolicy('doctor'),
+        outputSchema: commandOutput,
+    }, async ({ directory }) => withDirectory(directory, 'doctor', (resolved) => commandTool('doctor', ['doctor', resolved], resolved)));
+    server.registerTool('xeer_deploy_preview', {
+        ...toolPolicy('deploy.preview'),
+        outputSchema: commandOutput,
+    }, async ({ directory, controlUrl }) => {
+        const refusal = controlOriginRefusal(controlUrl);
+        if (refusal)
+            return failure('deploy.preview', 'url_refused', refusal);
+        return withDirectory(directory, 'deploy.preview', (resolved) => commandTool('deploy.preview', ['deploy', resolved, '--environment', 'preview', ...(controlUrl ? ['--control-url', controlUrl] : [])], resolved));
+    });
+    if (profile === 'operator') {
+        server.registerTool('xeer_promote', {
+            ...toolPolicy('promote.operator'),
+            outputSchema: commandOutput,
+        }, async ({ directory, receiptId, controlUrl }) => {
+            if (!isReviewReceiptId(receiptId)) {
+                return failure('promote.operator', 'invalid_review_receipt_id', 'receiptId must be the complete review_… id returned by a preview deployment.');
+            }
+            const refusal = controlOriginRefusal(controlUrl);
+            if (refusal)
+                return failure('promote.operator', 'url_refused', refusal);
+            return withDirectory(directory, 'promote.operator', (resolved) => commandTool('promote.operator', ['promote', resolved, '--receipt', receiptId,
+                ...(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()));
+        ...toolPolicy('auth.status'),
+        outputSchema: commandOutput,
+    }, async ({ controlUrl }) => {
+        const refusal = controlOriginRefusal(controlUrl);
+        if (refusal)
+            return failure('auth.status', 'url_refused', refusal);
+        return commandTool('auth.status', ['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 },
+        ...toolPolicy('inspect'),
+        outputSchema: commandOutput,
     }, async ({ previewUrl, view, after }) => {
+        const activeLocalOrigins = devSessions.summaries().flatMap((session) => session.running && session.preview ? [session.preview.url] : []);
+        const refusal = inspectorTargetRefusal(previewUrl, activeLocalOrigins);
+        if (refusal)
+            return failure('inspect', 'url_refused', refusal);
         const command = view === 'manifest' ? 'inspect' : view;
-        return commandTool([command, previewUrl, ...(view === 'logs' && after ? ['--after', after] : [])], projectRoot());
+        return commandTool('inspect', [command, previewUrl, ...(view === 'logs' && after ? ['--after', after] : [])], projectRoot());
     });
     const sessionOutput = {
         sessionId: z.string(),
@@ -272,7 +436,6 @@ export function createXeerMcpServer() {
         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(),
@@ -281,24 +444,17 @@ export function createXeerMcpServer() {
             data: z.unknown(),
         }).loose()),
     };
+    const reusableSession = (value) => {
+        const { stderr: _stderr, directory, ...rest } = value;
+        return {
+            ...rest,
+            ...(typeof directory === 'string' ? { directory: projectPath(directory) } : {}),
+        };
+    };
     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) => {
+        ...toolPolicy('dev.start'),
+        outputSchema: wrappedOutput(z.object(sessionOutput).loose()),
+    }, async ({ directory, host, port, timeoutMilliseconds }) => withDirectory(directory, 'dev.start', async (resolved) => {
         let session;
         try {
             session = devSessions.start({
@@ -308,71 +464,78 @@ export function createXeerMcpServer() {
             });
         }
         catch (error) {
-            return failure(error instanceof Error ? error.message : String(error));
+            if (error instanceof XeerCliError)
+                return failure('dev.start', 'adapter_unavailable', error.message);
+            return failure('dev.start', 'session_refused', error instanceof Error ? error.message : String(error));
+        }
+        try {
+            await session.waitForStart(timeoutMilliseconds ?? 180_000);
+        }
+        catch {
+            return failure('dev.start', 'session_start_failed', 'The dev session failed while starting.');
+        }
+        if (session.status === 'starting') {
+            try {
+                await session.stop();
+            }
+            catch {
+                return failure('dev.start', 'session_stop_failed', 'The timed-out dev session could not be stopped.');
+            }
+            return structured('dev.start', reusableSession(session.read(0)), {
+                ok: false,
+                error: {
+                    code: 'session_start_timeout',
+                    message: `xeer dev did not become ready within ${timeoutMilliseconds ?? 180_000} ms.`,
+                },
+            });
         }
-        await session.waitForStart(timeoutMilliseconds ?? 180_000);
-        return structured(session.read(0));
+        const result = reusableSession(session.read(0));
+        return structured('dev.start', result, session.status === 'ready' ? {} : {
+            ok: false,
+            error: { code: 'session_start_failed', message: `xeer dev stopped with status ${session.status}.` },
+        });
     }));
     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 },
+        ...toolPolicy('dev.status'),
+        outputSchema: wrappedOutput(z.object(sessionOutput).loose()),
     }, async ({ sessionId, cursor, waitMilliseconds, limit }) => {
         let session;
         try {
             session = devSessions.get(sessionId);
         }
         catch (error) {
-            return failure(error instanceof Error ? error.message : String(error));
+            return failure('dev.status', 'session_refused', error instanceof Error ? error.message : String(error));
         }
-        await session.waitForActivity(cursor, waitMilliseconds);
-        return structured(session.read(cursor, limit));
+        try {
+            await session.waitForActivity(cursor, waitMilliseconds);
+        }
+        catch {
+            return failure('dev.status', 'session_read_failed', 'The dev session could not be read.');
+        }
+        return structured('dev.status', reusableSession(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 },
+        ...toolPolicy('dev.stop'),
+        outputSchema: wrappedOutput(z.object(sessionOutput).loose()),
     }, async ({ sessionId, cursor }) => {
         let session;
         try {
             session = devSessions.get(sessionId);
         }
         catch (error) {
-            return failure(error instanceof Error ? error.message : String(error));
+            return failure('dev.stop', 'session_refused', error instanceof Error ? error.message : String(error));
+        }
+        try {
+            await session.stop();
         }
-        await session.stop();
-        return structured(session.read(cursor));
+        catch {
+            return failure('dev.stop', 'session_stop_failed', 'The dev session could not be stopped.');
+        }
+        return structured('dev.stop', reusableSession(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: {
+        ...toolPolicy('diagnostics'),
+        outputSchema: wrappedOutput(z.object({
             code: z.string().optional(),
             family: z.string().optional(),
             means: z.string().optional(),
@@ -380,20 +543,19 @@ export function createXeerMcpServer() {
             surfaces: z.array(z.string()).optional(),
             codes: z.array(z.string()).optional(),
             reference: z.string().optional(),
-        },
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        }).loose()),
     }, async ({ code }) => {
         if (!code) {
-            return structured({ codes: [...DIAGNOSTIC_CODES], reference: renderDiagnosticsReference() });
+            return structured('diagnostics', { 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}`);
+            return failure('diagnostics', 'unknown_diagnostic', `Unknown diagnostic code: ${normalized}. Known codes: ${known}`);
         }
         const family = DIAGNOSTIC_FAMILIES.find((candidate) => candidate.prefix === definition.prefix);
-        return structured({
+        return structured('diagnostics', {
             code: definition.code,
             family: family ? `${family.title}: ${family.summary}` : definition.prefix,
             means: definition.means,
@@ -401,5 +563,5 @@ export function createXeerMcpServer() {
             surfaces: [...definition.surfaces],
         });
     });
-    return { server, devSessions };
+    return { server, devSessions, profile };
 }

package/dist/test-run.js

@@ -93,7 +93,7 @@ export async function runXeerTests(options) {
                     code: 'XE0000',
                     severity: 'error',
                     message: failure
-                        ?? (stderr.trim() || `xeer ${argv.join(' ')} exited with ${exitCode} and emitted no events.`),
+                        ?? `xeer test --json exited with ${exitCode} and emitted no events.`,
                 });
             }
             done({
@@ -112,7 +112,7 @@ export async function runXeerTests(options) {
                 ...(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));
+        child.on('error', () => settle(null, 'Could not run the xeer CLI.'));
+        child.on('close', (code) => settle(code, timedOut ? `xeer test --json exceeded ${timeout} ms and was killed.` : undefined));
     });
 }

package/dist/xeer-cli.d.ts

@@ -1,7 +1,7 @@
 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.
+ * preserves the envelope it printed inside a versioned MCP result.
  *
  * 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
@@ -18,7 +18,7 @@ export interface CommandEnvelope {
     result?: unknown;
 }
 export interface CommandRun {
-    /** Argv after the CLI path, so a human can reproduce the call. */
+    /** Internal argv after the CLI path. Never include it in an MCP result: it may contain host paths. */
     argv: string[];
     exitCode: number | null;
     envelope: CommandEnvelope;

package/dist/xeer-cli.js

@@ -19,9 +19,9 @@ export function resolveXeerCli() {
     try {
         return resolve(dirname(require.resolve('@impetik/xeer')), 'cli.js');
     }
-    catch (error) {
+    catch {
         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)}`);
+            + 'or set XEER_CLI to its dist/cli.js.');
     }
 }
 /**
@@ -44,7 +44,7 @@ export async function resolveDirectory(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}. `
+        throw new XeerCliError('directory must stay inside the configured XEER_MCP_ROOT. '
             + 'Set XEER_MCP_ROOT when the server must reach another tree.');
     }
     return requested;
@@ -113,11 +113,11 @@ export async function runXeerCommand(args, options = {}) {
                 argv,
                 exitCode,
                 envelope: envelope ?? crashEnvelope(command, failure
-                    ?? (stderr.trim() || `xeer ${argv.join(' ')} exited with ${exitCode} and printed no envelope.`)),
+                    ?? `xeer ${command} --json 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));
+        child.on('error', () => settle(null, 'Could not run the xeer CLI.'));
+        child.on('close', (code) => settle(code, timedOut ? `xeer ${command} --json exceeded ${timeout} ms and was killed.` : undefined));
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "type": "module",
   "description": "Model Context Protocol server for Xeer: the scaffold, check, dev, build, and deploy loop as agent tools.",
   "license": "MIT",
@@ -43,8 +43,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.10",
-    "@impetik/xeer": "0.2.3",
-    "@impetik/xeer-spec": "0.2.3"
+    "@impetik/xeer": "0.2.5",
+    "@impetik/xeer-spec": "0.2.5"
   },
   "devDependencies": {
     "@types/node": "^24.1.0"