@impetik/xeer-mcp

Model Context Protocol server for Xeer, 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.

📖 Documentation: docs.xeer.run · Building with AI agents: docs.xeer.run/guides/agents · Diagnostics: docs.xeer.run/reference/diagnostics

The repository 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

// .mcp.json, or your harness's MCP configuration
{
  "mcpServers": {
    "xeer": {
      "command": "npx",
      "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:

node packages/mcp/dist/main.js    # stdio; or `pnpm mcp` from the workspace root

Registered action policy

The generated registry is the complete MCP tool and exclusion surface:

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-sourcewrite-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-sourcewrite-generatedrun-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?: stringtimeoutMilliseconds?: integer [1000..1800000] | read-sourcewrite-generatedrun-localwrite-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: stringtemplate?: 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: stringlimit?: 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-sourcewrite-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?: stringcontrolUrl?: string | read-sourcewrite-generatedrun-localnetwork-readnetwork-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?: stringreceiptId: stringcontrolUrl?: string | network-readnetwork-writeproduction-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-readsecret-metadata | read-only; idempotent; reversible; non-destructive | none | xeer.command.v0 | none | | xeer_inspect | inspect | author / operator | Read a running application manifest. | previewUrl: stringview?: manifest / state / logs / export; default manifestafter?: string | network-readread-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?: stringhost?: stringport?: integer [0..65535]share?: booleantimeoutMilliseconds?: integer [1000..600000] | read-sourcewrite-generatedrun-localwrite-statenetwork-readnetwork-write | 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?: stringcursor?: integer [0..9007199254740991]; default 0waitMilliseconds?: integer [0..600000]; default 0limit?: 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?: stringcursor?: integer [0..9007199254740991]; default 0 | run-local | writes; idempotent; reversible; non-destructive | none | xeer.dev.v0 | none | | xeer_diagnostics | diagnostics | author / operator | Explain one emitted diagnostic code. | code: string | none | read-only; idempotent; reversible; non-destructive | none | xeer.command.v0 | none |

CLI actions intentionally excluded from MCP (35).

| 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-sourcewrite-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-sourcewrite-generatedrun-localnetwork-readnetwork-writeproduction-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-readnetwork-writeproduction-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 tunnel | tunnel.start | Expose a loopback HTTP server through an authenticated tunnel. | run-localnetwork-readnetwork-write | writes; non-idempotent; reversible; non-destructive | none | xeer.tunnel.cli.v0 | Not exposed through MCP v0; use the CLI deliberately. | | xeer link | link | Link a checkout to an application the builder owns. | read-sourcewrite-sourcenetwork-readnetwork-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-readread-statesecret-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-readnetwork-writeproduction-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-readnetwork-writeproduction-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-readnetwork-writeproduction-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-readnetwork-writewrite-stateproduction-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-readnetwork-writeproduction-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-readnetwork-writeproduction-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-readnetwork-writeproduction-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-sourcewrite-generatedrun-localwrite-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-readread-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-sourcewrite-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-readread-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-readread-statewrite-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-sourcenetwork-writewrite-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-readnetwork-writesecret-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-writesecret-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-writewrite-statesecret-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-readsecret-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-writewrite-statesecret-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-readwrite-filesecret-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-writesecret-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-readsecret-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-writesecret-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 db tables | db.tables | List the tables of a running application database. | read-state | read-only; idempotent; reversible; non-destructive | project-relative | xeer.command.v0 | Not exposed through MCP v0; use the CLI deliberately. | | xeer db schema | db.schema | Print the declared schema of a running application database. | read-state | read-only; idempotent; reversible; non-destructive | project-relative | xeer.command.v0 | Not exposed through MCP v0; use the CLI deliberately. | | xeer db exec | db.exec | Run one SQL statement against a running application database. | read-statewrite-state | writes; non-idempotent; irreversible; non-destructive | project-relative | xeer.command.v0 | Destructive state replacement requires an explicit CLI invocation. |

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 event stream, with each failed case carrying a Diagnostic-shaped failure (XE1904 assertion, XE1905 throw or unexpectedly refused call, XE1906 timeout) that includes the matcher, expected and actual values, and the project-relative test location. It needs no session handle: unlike dev, a test run is short-lived and terminal.

Why dev is three tools

An MCP tool call is request/response; xeer dev is a long-lived JSONL stream. The session is therefore owned by the server and addressed by a sessionId, with the protocol's own seq as a resumable cursor:

xeer_dev_start  → { result: { sessionId, cursor, status: 'ready', preview: { url, inspectorUrl, ... }, events } }
   edit a file
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. Repairing diagnostics needs none of this — xeer_check runs the same compiler — so the session exists for when the preview, the inspector, or rebuild/rollback behaviour matters.

Configuration

| Variable | Effect | | --- | --- | | XEER_MCP_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 SIGINT/SIGTERM.