npm - @impetik/xeer-mcp - Versions diffs - 0.2.2 → 0.2.4 - Mend

@impetik/xeer-mcp 0.2.2 → 0.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/README.md CHANGED Viewed

@@ -1,13 +1,22 @@
-# @impetik/xeer-mcp
+# `@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.
+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 with a
+stable `xeer.mcp-result.v0` result protocol.
-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.
+📖 **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) 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
@@ -17,40 +26,99 @@ the same protocol written as agent instructions.
   "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> --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.
+## 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
@@ -59,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
@@ -71,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.
@@ -85,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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,23 +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 { 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(),
@@ -31,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(),
@@ -155,75 +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. '
-            + '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())));
+        ...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, ... }.',
-        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)));
+        ...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(),
@@ -243,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(),
@@ -252,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({
@@ -279,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));
         }
-        await session.waitForStart(timeoutMilliseconds ?? 180_000);
-        return structured(session.read(0));
+        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.`,
+                },
+            });
+        }
+        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));
+        }
+        try {
+            await session.waitForActivity(cursor, waitMilliseconds);
+        }
+        catch {
+            return failure('dev.status', 'session_read_failed', 'The dev session could not be read.');
         }
-        await session.waitForActivity(cursor, waitMilliseconds);
-        return structured(session.read(cursor, limit));
+        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(),
@@ -351,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,
@@ -372,5 +563,5 @@ export function createXeerMcpServer() {
             surfaces: [...definition.surfaces],
         });
     });
-    return { server, devSessions };
+    return { server, devSessions, profile };
 }

package/dist/test-run.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "type": "module",
   "description": "Model Context Protocol server for Xeer: the scaffold, check, dev, build, and deploy loop as agent tools.",
   "license": "MIT",
@@ -9,7 +9,7 @@
     "url": "git+https://github.com/impetik/xeer.git",
     "directory": "packages/mcp"
   },
-  "homepage": "https://github.com/impetik/xeer#readme",
+  "homepage": "https://xeer.run",
   "bugs": "https://github.com/impetik/xeer/issues",
   "keywords": [
     "xeer",
@@ -43,8 +43,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.10",
-    "@impetik/xeer": "0.2.2",
-    "@impetik/xeer-spec": "0.2.2"
+    "@impetik/xeer": "0.2.4",
+    "@impetik/xeer-spec": "0.2.4"
   },
   "devDependencies": {
     "@types/node": "^24.1.0"