@impetik/xeer-mcp 0.2.1 → 0.2.3

package/README.md

@@ -1,13 +1,15 @@
-# @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, each
+returning the `xeer.command.v0` JSON envelope the `xeer` CLI already prints.
 
-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) also ships the same protocol as a Claude Code skill
+under `.claude/skills/xeer/`, which you can copy into your own project.
 
 ## Run it
 
@@ -37,9 +39,10 @@ node packages/mcp/dist/main.js    # stdio; or `pnpm mcp` from the workspace root
 | `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_new` | `xeer new <dir> [--template <name>] --json` | `result.template`, `result.files` |
 | `xeer_doctor` | `xeer doctor <dir> --json` | `result.checks`, `result.summary` |
-| `xeer_deploy` | `xeer deploy <dir> --json` | `result.url` |
+| `xeer_deploy` | `xeer deploy <dir> --json` | `result.url` (`environment: "preview"` deploys to the side-by-side preview URL) |
+| `xeer_promote` | `xeer promote <dir> --json` | `result.artifactId`, `result.replaced`, `result.url` |
 | `xeer_auth_status` | `xeer auth status --json` | Builder identity and credential expiry |
 | `xeer_inspect` | `xeer inspect`/`state`/`logs` | Inspector response for a running preview |
 | `xeer_dev_start` | `xeer dev <dir> --json --port 0` | Session handle, cursor, and the events up to `preview.ready` |

package/dist/server.js

@@ -1,6 +1,7 @@
 import { createRequire } from 'node:module';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
+import { DEFAULT_TEMPLATE, TEMPLATES } from '@impetik/xeer';
 import { DIAGNOSTICS, DIAGNOSTIC_CODES, DIAGNOSTIC_FAMILIES, diagnosticDefinition, renderDiagnosticsReference, } from '@impetik/xeer-spec/diagnostics';
 import { DevSessionRegistry } from './dev-session.js';
 import { runXeerTests } from './test-run.js';
@@ -168,14 +169,21 @@ export function createXeerMcpServer() {
     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 }.',
+            + 'Every template checks, tests, and builds clean, so use one as the starting point rather '
+            + 'than writing a manifest by hand. "notes" (the default) and "todo" are per-user apps, "blog" '
+            + 'is public to read and private to write, and "personal-site" has no database at all. None of '
+            + 'them scaffolds sign-in UI. result is { directory, name, template, files }; an unknown '
+            + 'template is XE3002 and writes nothing.',
         inputSchema: {
             directory: z.string().describe('Target directory, relative to the server root. Must be empty or absent.'),
+            // The names come from the CLI itself, so this schema cannot advertise a template the
+            // installed CLI does not have — or omit one it does.
+            template: z.enum(TEMPLATES).optional()
+                .describe(`Which scaffold to write. Defaults to ${DEFAULT_TEMPLATE}.`),
         },
         outputSchema: envelopeOutput,
         annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false },
-    }, async ({ directory }) => withDirectory(directory, (resolved) => commandTool(['new', resolved], projectRoot())));
+    }, async ({ directory, template }) => withDirectory(directory, (resolved) => commandTool(['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 '
@@ -189,14 +197,35 @@ export function createXeerMcpServer() {
         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, ... }.',
+            + '{ application, url, ... }. Defaults to production; pass environment "preview" to deploy to the '
+            + 'app\'s side-by-side preview URL instead, which is what to iterate against — production keeps '
+            + 'serving, and preview has its own disposable state. Make a preview live with xeer_promote.',
         inputSchema: {
             directory: directoryArgument,
+            environment: z.enum(['production', 'preview']).optional()
+                .describe('Deployment target. Omit for production; "preview" leaves production untouched.'),
             controlUrl: z.string().optional().describe('Control-plane origin override, e.g. https://control.example.com.'),
         },
         outputSchema: envelopeOutput,
         annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-    }, async ({ directory, controlUrl }) => withDirectory(directory, (resolved) => commandTool(['deploy', resolved, ...(controlUrl ? ['--control-url', controlUrl] : [])], resolved)));
+    }, async ({ directory, environment, controlUrl }) => withDirectory(directory, (resolved) => commandTool(['deploy', resolved, ...(environment ? ['--environment', environment] : []),
+        ...(controlUrl ? ['--control-url', controlUrl] : [])], resolved)));
+    server.registerTool('xeer_promote', {
+        title: 'Promote a Xeer preview to production',
+        description: 'Make the version currently on the app\'s preview URL live on production — the same '
+            + 'bundle, not a rebuild, with production\'s own environment values. The second half of the '
+            + '"deploy to preview, look at it, then ship it" loop. XE5175 means nothing has been deployed to '
+            + 'preview yet. result is { artifactId, replaced, url, ... }.',
+        inputSchema: {
+            directory: directoryArgument,
+            fromArtifact: z.string().optional()
+                .describe('Promote this artifact id instead of whatever preview is serving, e.g. sha256:….'),
+            controlUrl: z.string().optional().describe('Control-plane origin override.'),
+        },
+        outputSchema: envelopeOutput,
+        annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    }, async ({ directory, fromArtifact, controlUrl }) => withDirectory(directory, (resolved) => commandTool(['promote', resolved, ...(fromArtifact ? ['--from-artifact', fromArtifact] : []),
+        ...(controlUrl ? ['--control-url', controlUrl] : [])], resolved)));
     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 '

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "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.1",
-    "@impetik/xeer-spec": "0.2.1"
+    "@impetik/xeer": "0.2.3",
+    "@impetik/xeer-spec": "0.2.3"
   },
   "devDependencies": {
     "@types/node": "^24.1.0"