@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 project artifact. | directory?: string | read-sourcewrite-generatedrun-local | writes; idempotent; reversible; non-destructive | project-relative | xeer.command.v0 | none | | xeer_test | test | author / operator | Run the project test suite and record review evidence. | 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?: stringframework?: sveltekit / astroui?: preact / react | write-sourcenetwork-read | 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, or issue the service token supplied in XEER_SERVICE_TOKEN. | | 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 (39).

| CLI action | Action | Summary | Effects | Safety | Path policy | Output | Why no MCP tool | | --- | --- | --- | --- | --- | --- | --- | --- | | xeer init | init | Initialize Xeer in an existing SvelteKit or Astro project. | read-sourcewrite-sourcerun-localnetwork-read | writes; idempotent; reversible; non-destructive | project-relative | xeer.command.v0 | Not exposed through MCP v0; use the CLI deliberately. | | xeer bootstrap | bootstrap | Open owner-only EmDash setup for a deployed Astro project. | read-sourcenetwork-readnetwork-write | writes; non-idempotent; reversible; non-destructive | project-relative | xeer.command.v0 | Not exposed through MCP v0; use the CLI deliberately. | | 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 a project 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 SQL against a running or deployed application database. | read-statewrite-statenetwork-readnetwork-write | writes; non-idempotent; irreversible; destructive | project-relative | xeer.command.v0 | Destructive state replacement requires an explicit CLI invocation. | | xeer db bookmark | db.bookmark | Print the current Time Travel bookmark of a deployed application database. | network-read | read-only; idempotent; reversible; non-destructive | project-relative | xeer.command.v0 | Not exposed through MCP v0; use the CLI deliberately. | | xeer db restore | db.restore | Restore a deployed application database to a bookmark or a time. | network-writewrite-state | writes; non-idempotent; reversible; 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. A CLI refusal sets the wrapper and nested envelope ok fields to false; its stable code stays in result.envelope.diagnostics. The wrapper error field is for adapter, path, URL, session, and tool-level failures.

xeer_test is the exception, because xeer test --json streams xeer.dev.v0 events rather than printing an envelope. It returns { exitCode, ok, reason?, total, passed, failed, durationMs?, files, cases, diagnostics, events }. The events array retains the first 2,000 events. Each failed case carries a Diagnostic-shaped failure (XE1904 assertion, XE1905 throw or unexpectedly refused call, XE1906 timeout) that includes the matcher, expected and actual values, and the project-relative test location. It needs no session handle: unlike dev, a test run is short-lived and terminal.

xeer_diagnostics also returns a direct result rather than a command envelope: { protocol: "xeer.diagnostic.v0", code, family?, means, repair, surfaces }.

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

The server retains the latest 2,000 dev events and reports earlier loss in droppedEvents. Each status call returns at most limit events, using the newest matching events when more are available. Advance the cursor only to an event you received. Repairing diagnostics needs none of this, because xeer_check runs the same compiler. 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-review-receipt 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.