@impetik/xeer-mcp 0.2.23 → 0.2.25

package/README.md

@@ -14,7 +14,7 @@ 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://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.
 
@@ -61,8 +61,8 @@ The generated registry is the complete MCP tool and exclusion surface:
 | 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_build` | `build` | `author` / `operator` | Build and verify a content-addressed project 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 the project test suite and record review evidence. | `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?`: `string`<br>`framework?`: `sveltekit`<br>`ui?`: `preact` / `react` | `write-source`<br>`network-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`: `string`<br>`limit?`: `integer` [1..20]; default `5` | none | read-only; idempotent; reversible; non-destructive | `none` | `xeer.docs-search.v0` | none |
@@ -82,7 +82,7 @@ The generated registry is the complete MCP tool and exclusion surface:
 | --- | --- | --- | --- | --- | --- | --- | --- |
 | `xeer init` | `init` | Initialize Xeer in an existing SvelteKit project. | `read-source`<br>`write-source`<br>`run-local`<br>`network-read` | writes; 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-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 deploy` | `deploy` | Build and deploy a project 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 tunnel` | `tunnel.start` | Expose a loopback HTTP server through an authenticated tunnel. | `run-local`<br>`network-read`<br>`network-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-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. |
@@ -122,16 +122,22 @@ Every tool returns `{ protocol: "xeer.mcp-result.v0", action, ok, result?, error
 `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.
+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 collects the run and returns the summary plus the unabridged
-event stream, with each failed case carrying a `Diagnostic`-shaped `failure` (`XE1904`
+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
@@ -145,15 +151,17 @@ xeer_dev_status → { result: { events: [compile.start, compile.diagnostic?, com
 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
+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-artifact `xeer_promote`; any other value refuses server startup. |
+| `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. |

package/dist/server.js

@@ -224,7 +224,7 @@ export function createXeerMcpServer(options = {}) {
             'Loop: xeer_new to scaffold, xeer_check after every edit, xeer_test to prove behaviour,',
             '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.',
+            'the server with XEER_MCP_PROFILE=operator, and then requires an exact review receipt.',
             '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.',
@@ -551,8 +551,9 @@ export function createXeerMcpServer(options = {}) {
     server.registerTool('xeer_diagnostics', {
         ...toolPolicy('diagnostics'),
         outputSchema: wrappedOutput(z.object({
+            protocol: z.literal('xeer.diagnostic.v0').optional(),
             code: z.string().optional(),
-            family: z.string().optional(),
+            family: z.object({ prefix: z.string(), title: z.string(), summary: z.string() }).optional(),
             means: z.string().optional(),
             repair: z.string().optional(),
             surfaces: z.array(z.string()).optional(),
@@ -565,8 +566,9 @@ export function createXeerMcpServer(options = {}) {
         }
         const family = DIAGNOSTIC_FAMILIES.find((candidate) => candidate.prefix === definition.prefix);
         return structured('diagnostics', {
+            protocol: 'xeer.diagnostic.v0',
             code: definition.code,
-            family: family ? `${family.title}: ${family.summary}` : definition.prefix,
+            ...(family ? { family: { prefix: family.prefix, title: family.title, summary: family.summary } } : {}),
             means: definition.means,
             repair: definition.repair,
             surfaces: [...definition.surfaces],

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.23",
+  "version": "0.2.25",
   "type": "module",
-  "description": "Model Context Protocol server for Xeer: the scaffold, check, dev, build, and deploy loop as agent tools.",
+  "description": "Model Context Protocol server for Xeer project context, diagnostics, scaffold, check, test, dev, build, and preview deployment.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.10",
-    "@impetik/xeer": "0.2.23"
+    "@impetik/xeer": "0.2.25"
   },
   "devDependencies": {
     "@types/node": "^24.1.0"

package/vendor/spec/actions.d.ts

@@ -129,7 +129,7 @@ declare const actions: readonly [{
 }, {
     readonly id: "build";
     readonly command: readonly ["build"];
-    readonly summary: "Build and verify a content-addressed application artifact.";
+    readonly summary: "Build and verify a content-addressed project artifact.";
     readonly usage: readonly ["build [directory] [--json]"];
     readonly helpOrder: 40;
     readonly outputProtocol: "xeer.command.v0";
@@ -158,7 +158,7 @@ declare const actions: readonly [{
 }, {
     readonly id: "test";
     readonly command: readonly ["test"];
-    readonly summary: "Run application tests against fresh isolated local state.";
+    readonly summary: "Run the project test suite and record review evidence.";
     readonly usage: readonly ["test [directory] [--host <host>] [--json]"];
     readonly helpOrder: 250;
     readonly outputProtocol: "xeer.dev.v0";
@@ -369,7 +369,7 @@ declare const actions: readonly [{
 }, {
     readonly id: "deploy";
     readonly command: readonly ["deploy"];
-    readonly summary: "Build and deploy an application artifact.";
+    readonly summary: "Build and deploy a project artifact.";
     readonly description: string;
     readonly usage: readonly ["deploy [directory] [--environment prod|preview] [--control-url <url>] [--json]"];
     readonly helpOrder: 50;
@@ -468,7 +468,7 @@ declare const actions: readonly [{
             };
             readonly required: readonly ["receiptId"];
         };
-        readonly mcpTitle: "Promote an exact preview artifact (operator)";
+        readonly mcpTitle: "Promote an exact review receipt (operator)";
         readonly mcpDescription: string;
         readonly cli: false;
         readonly mcpTool: "xeer_promote";

package/vendor/spec/actions.js

@@ -57,9 +57,9 @@ const MCP_PRESENTATION = {
         mcpDescription: [
             '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.',
+            'A Xeer application runs manifest, module graph, zone, operation, and type analysis. Its result',
+            'is { manifest }. A framework project delegates its check script and returns',
+            '{ framework, config, check }. Diagnostic codes are stable. Look one up with xeer_diagnostics.',
         ].join(' '),
     },
     build: {
@@ -67,17 +67,19 @@ const MCP_PRESENTATION = {
         mcpDescription: [
             '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.',
+            'A Xeer application returns { artifactId, outputDirectory, modules, assets, operations }.',
+            'A framework project returns { framework, artifactId, outputDirectory, modules, assets }.',
+            'Framework results omit operations because the framework owns its routes and build contract.',
+            'Run xeer_test before this to prove behavior as well as compilation.',
         ].join(' '),
     },
     test: {
         mcpTitle: 'Run a Xeer project\'s tests',
         mcpDescription: [
-            '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 }.',
+            'Run the project\'s own tests. A Xeer application builds, type-checks every tests/**/*.ts module',
+            'against the generated contract, boots the artifact in workerd with fresh state, runs every',
+            'registered test, and tears down. A framework project delegates its package test script.',
+            'Returns { exitCode, ok, reason?, total, passed, failed, durationMs?, files, 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.',
@@ -92,13 +94,15 @@ const MCP_PRESENTATION = {
             + 'Every template checks, tests, and builds clean, so use one as the starting point rather '
             + 'than writing a manifest by hand. "notes" (the default) and "todo" are per-user apps, "blog" '
             + 'is public to read and private to write, and "personal-site" has no database at all. None of '
-            + 'them scaffolds sign-in UI. "ui" selects the UI provider independently of the template — '
-            + '"preact" (the default) or "react" — and changes the manifest rather than any source file. '
+            + 'them scaffolds sign-in UI. "ui" selects "preact" or "react" for a bundled starter only. '
+            + 'Catalog templates own their renderer and reject "ui" with XE3013. '
             + '"framework" is the other axis and is exclusive with "template": "sveltekit" writes a '
             + 'SvelteKit project with xeer.config.json instead of xeer.app.json, so it has no UI provider '
-            + 'and no declared database, and its commands delegate to the package scripts after an '
-            + 'install. result is { directory, name, files } plus "template" and "ui" for an application '
-            + 'scaffold or "framework" for a framework one; an unknown template is XE3002, an unknown ui '
+            + 'and no declared database. Its check, dev, test, and build commands delegate to package '
+            + 'scripts after an install. A bundled result is { directory, name, files, template, ui }. '
+            + 'A direct framework result replaces template and ui with framework. A catalog result adds '
+            + 'projectKind, platformVersion, and artifactVersion, plus framework when projectKind is '
+            + '"framework". Catalog results never contain "ui". An unknown template is XE3002, an unknown ui '
             + 'is XE3003, "ui" with "framework" is XE3004, "template" with "framework" is XE3005, an '
             + 'unknown framework is XE3006, and none of them writes anything.',
     },
@@ -111,24 +115,24 @@ const MCP_PRESENTATION = {
     deploy: {
         mcpTitle: 'Deploy a Xeer preview',
         mcpDescription: 'Build, verify, and upload the artifact to the preview environment. This tool never '
-            + 'changes production. Requires a builder '
-            + 'credential: XE5002 means a human must run `xeer auth login` first. result is '
+            + 'changes production. It accepts a credential established by `xeer auth login` or a service '
+            + 'token supplied in XEER_SERVICE_TOKEN. result is '
             + '{ application, url, ... } for the app\'s side-by-side preview URL; production keeps serving, '
             + 'and preview has its own disposable state.',
     },
     promote: {
-        mcpTitle: 'Promote an exact preview artifact (operator)',
-        mcpDescription: 'Make the version currently on the app\'s preview URL live on production — the same '
-            + 'bundle, not a rebuild, with production\'s own environment values. The second half of the '
-            + '"deploy to preview, look at it, then ship it" loop. XE5175 means nothing has been deployed to '
-            + 'preview yet. The exact artifact id is required. This tool exists only when the server starts '
+        mcpTitle: 'Promote an exact review receipt (operator)',
+        mcpDescription: 'Make the artifact bound to an exact review receipt live on production. The control '
+            + 'plane verifies that the receipt still names the active preview and its recorded test evidence. '
+            + 'It promotes the same bundle without rebuilding and uses production environment values. '
+            + 'This tool exists only when the server starts '
             + 'with XEER_MCP_PROFILE=operator. result is { artifactId, replaced, url, ... }.',
     },
     'auth.status': {
         mcpTitle: 'Report builder sign-in status',
-        mcpDescription: '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`.',
+        mcpDescription: 'Report whether a builder credential is available for deployment. A person can '
+            + 'establish it with `xeer auth login`, or a service can use XEER_SERVICE_TOKEN. Interactive '
+            + 'sign-in cannot be completed by an agent.',
     },
     inspect: {
         mcpTitle: 'Inspect a running preview',
@@ -182,7 +186,7 @@ const actions = [
         },
     },
     {
-        id: 'build', command: ['build'], summary: 'Build and verify a content-addressed application artifact.',
+        id: 'build', command: ['build'], summary: 'Build and verify a content-addressed project artifact.',
         usage: ['build [directory] [--json]'], helpOrder: 40,
         outputProtocol: 'xeer.command.v0', effects: ['read-source', 'write-generated', 'run-local'],
         idempotent: true, reversible: true, destructive: false, humanPrerequisites: [],
@@ -193,7 +197,7 @@ const actions = [
         },
     },
     {
-        id: 'test', command: ['test'], summary: 'Run application tests against fresh isolated local state.',
+        id: 'test', command: ['test'], summary: 'Run the project test suite and record review evidence.',
         usage: ['test [directory] [--host <host>] [--json]'], helpOrder: 250, outputProtocol: 'xeer.dev.v0',
         effects: ['read-source', 'write-generated', 'run-local', 'write-state'],
         idempotent: true, reversible: true, destructive: false, humanPrerequisites: [],
@@ -238,13 +242,13 @@ const actions = [
                     framework: {
                         description: 'Scaffold a fresh project for this framework instead of a Xeer '
                             + 'application: it declares xeer.config.json, owns its own renderer and routes, and '
-                            + 'delegates every command to its package scripts. Exclusive with template and ui.',
+                            + 'delegates check, dev, test, and build to its package scripts. Exclusive with template and ui.',
                         type: 'string', enum: FRAMEWORK_NAMES,
                     },
                     ui: {
                         description: 'Which UI provider the written manifest selects. Defaults to preact, and '
-                            + 'omitting it writes no client block at all. Orthogonal to template, and refused '
-                            + 'with XE3004 alongside a framework that owns its own renderer.',
+                            + 'omitting it writes no client block at all. Applies only to bundled starters. Catalog '
+                            + 'templates reject it with XE3013, and frameworks reject it with XE3004.',
                         type: 'string', enum: ['preact', 'react'],
                     },
                 },
@@ -312,7 +316,7 @@ const actions = [
         },
     },
     {
-        id: 'deploy', command: ['deploy'], summary: 'Build and deploy an application artifact.',
+        id: 'deploy', command: ['deploy'], summary: 'Build and deploy a project artifact.',
         description: 'Deploys to production by default. Use --environment preview for a separate preview '
             + 'Worker, URL, environment values, and disposable data so you can review a release before it goes live.',
         usage: ['deploy [directory] [--environment prod|preview] [--control-url <url>] [--json]'], helpOrder: 50,

package/vendor/spec/diagnostics.js

@@ -447,7 +447,7 @@ export const DIAGNOSTIC_DEFINITIONS = [
         + 'Never scaffold a new project over an initialized one.', ['preview', 'inspect', 'state', 'agent']),
     define('XE4001', 'A doctor check failed. `hint` carries the check details as JSON, and result.checks '
         + 'lists every check with its id and status.', 'Fix the environment problem the failing check names. Doctor never edits the project.', ['doctor']),
-    define('XE5000', 'An auth subcommand was invoked with wrong arguments.', 'Use `xeer auth <login|status|logout|as|clear>`; `auth as` takes alice or bob.', ['auth']),
+    define('XE5000', 'An auth subcommand was invoked with wrong arguments.', 'Use `xeer auth <login|status|logout|as|clear>`; `auth as` takes alice, bob, or carol.', ['auth']),
     define('XE5001', 'The --control-url value is not an exact HTTP(S) origin, or is plain HTTP off localhost.', 'Pass an origin such as https://control.example.com with no path.', ['auth', 'deploy']),
     define('XE5002', 'No valid builder credential is stored.', 'A human must run `xeer auth login` and approve the shown code. An agent cannot complete sign-in.', ['auth', 'deploy']),
     define('XE5003', 'XEER_SERVICE_TOKEN is set to something that is not a service token, so no command '

package/vendor/spec/template.js

@@ -77,7 +77,7 @@ export const templateManifestJsonSchema = Object.freeze({
     ...generatedTemplateManifestJsonSchema,
     $id: TEMPLATE_MANIFEST_SCHEMA_URL,
     title: 'Xeer template manifest v0',
-    description: 'Authored metadata for one application in the Xeer template catalog.',
+    description: 'Authored metadata for one project in the Xeer template catalog.',
     properties: {
         ...generatedProperties,
         $schema: {
@@ -103,7 +103,7 @@ export const templateManifestJsonSchema = Object.freeze({
         },
         capabilities: {
             ...generatedProperties.capabilities,
-            description: 'Application capabilities, verified against xeer.app.json when the catalog is generated.',
+            description: 'Project capabilities, verified against the template root contract when the catalog is generated.',
             uniqueItems: true,
         },
         previewAppId: {