@impetik/xeer-mcp 0.2.13 → 0.2.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@impetik/xeer-mcp",
-  "version": "0.2.13",
+  "version": "0.2.15",
   "type": "module",
   "description": "Model Context Protocol server for Xeer: the scaffold, check, dev, build, and deploy loop as agent tools.",
   "license": "MIT",
@@ -47,7 +47,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.0.10",
-    "@impetik/xeer": "0.2.13"
+    "@impetik/xeer": "0.2.15"
   },
   "devDependencies": {
     "@types/node": "^24.1.0"

package/vendor/spec/actions.d.ts

@@ -47,6 +47,8 @@ export interface XeerActionDefinition {
     readonly command: readonly string[];
     readonly aliases?: readonly (readonly string[])[];
     readonly summary: string;
+    /** Optional command-specific detail rendered only by focused `xeer <command> --help`. */
+    readonly description?: string;
     /** Help syntax without the `xeer ` prefix. May contain `{{templates}}`. */
     readonly usage: readonly string[];
     /** Optional abbreviated syntax for the global command list. Full usage remains authoritative. */
@@ -73,6 +75,15 @@ export interface XeerActionDefinition {
         readonly mcpExclusion?: string;
     };
 }
+export interface XeerCliCommandGroupDefinition {
+    readonly command: string;
+    readonly summary: string;
+}
+/**
+ * Human-facing summaries for command families. Membership and ordering still come from the action
+ * registry; this only supplies the sentence that no individual subcommand can describe honestly.
+ */
+export declare const XEER_CLI_COMMAND_GROUPS: readonly XeerCliCommandGroupDefinition[];
 export interface XeerCliOptionDefinition {
     readonly name: string;
     readonly takesValue: boolean;
@@ -182,6 +193,7 @@ declare const actions: readonly [{
     readonly id: "new";
     readonly command: readonly ["new"];
     readonly summary: "Create a new project from a supported scaffold.";
+    readonly description: string;
     readonly usage: readonly ["new <directory> [--template {{templates}}] [--json]"];
     readonly helpOrder: 30;
     readonly outputProtocol: "xeer.command.v0";
@@ -331,6 +343,7 @@ declare const actions: readonly [{
     readonly id: "deploy";
     readonly command: readonly ["deploy"];
     readonly summary: "Build and deploy an application artifact.";
+    readonly description: string;
     readonly usage: readonly ["deploy [directory] [--environment prod|preview] [--control-url <url>] [--json]"];
     readonly helpOrder: 50;
     readonly outputProtocol: "xeer.command.v0";
@@ -348,6 +361,7 @@ declare const actions: readonly [{
     readonly id: "promote";
     readonly command: readonly ["promote"];
     readonly summary: "Promote a preview artifact to production.";
+    readonly description: string;
     readonly usage: readonly [string];
     readonly helpOrder: 80;
     readonly outputProtocol: "xeer.command.v0";
@@ -466,6 +480,7 @@ declare const actions: readonly [{
     readonly id: "inspect";
     readonly command: readonly ["inspect"];
     readonly summary: "Read a running application manifest.";
+    readonly description: string;
     readonly usage: readonly ["inspect <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]"];
     readonly helpOrder: 230;
     readonly outputProtocol: "xeer.command.v0";
@@ -700,6 +715,7 @@ declare const actions: readonly [{
     readonly id: "deployments";
     readonly command: readonly ["deployments"];
     readonly summary: "List deployment history for an application.";
+    readonly description: string;
     readonly usage: readonly ["deployments [app|directory] [--limit <n>] [--control-url <url>] [--json]"];
     readonly helpOrder: 70;
     readonly outputProtocol: "xeer.command.v0";
@@ -717,6 +733,7 @@ declare const actions: readonly [{
     readonly id: "rollback";
     readonly command: readonly ["rollback"];
     readonly summary: "Redeploy a previously deployed artifact.";
+    readonly description: string;
     readonly usage: readonly ["rollback [app|directory] <artifactId> [--environment prod|preview] [--control-url <url>] [--json]"];
     readonly helpOrder: 90;
     readonly outputProtocol: "xeer.command.v0";
@@ -734,6 +751,7 @@ declare const actions: readonly [{
     readonly id: "disable";
     readonly command: readonly ["disable"];
     readonly summary: "Take an application offline without deleting its data.";
+    readonly description: string;
     readonly usage: readonly ["disable [app|directory] [--control-url <url>] [--json]"];
     readonly helpOrder: 100;
     readonly outputProtocol: "xeer.command.v0";
@@ -768,6 +786,7 @@ declare const actions: readonly [{
     readonly id: "delete";
     readonly command: readonly ["delete"];
     readonly summary: "Permanently delete an application and all of its data.";
+    readonly description: string;
     readonly usage: readonly ["delete [app|directory] --confirm <application> [--control-url <url>] [--json]"];
     readonly helpOrder: 120;
     readonly outputProtocol: "xeer.command.v0";
@@ -872,6 +891,7 @@ declare const actions: readonly [{
     readonly id: "state.read";
     readonly command: readonly ["state"];
     readonly summary: "Read record counts from a running application.";
+    readonly description: string;
     readonly usage: readonly ["state <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]"];
     readonly helpOrder: 260;
     readonly outputProtocol: "xeer.command.v0";
@@ -906,6 +926,7 @@ declare const actions: readonly [{
     readonly id: "logs";
     readonly command: readonly ["logs"];
     readonly summary: "Read the bounded log ring of a running application.";
+    readonly description: string;
     readonly usage: readonly ["logs <local-url|app> [--environment prod|preview] [--after <cursor>] [--control-url <url>] [--json]"];
     readonly helpOrder: 280;
     readonly outputProtocol: "xeer.command.v0";
@@ -923,6 +944,7 @@ declare const actions: readonly [{
     readonly id: "export";
     readonly command: readonly ["export"];
     readonly summary: "Export application state to a document.";
+    readonly description: string;
     readonly usage: readonly ["export <local-url|app> [--environment prod|preview] [--out <file>] [--control-url <url>] [--json]", "export --state <dev|preview> [directory] [--out <file>] [--json]"];
     readonly helpOrder: 290;
     readonly outputProtocol: "xeer.command.v0";
@@ -940,6 +962,7 @@ declare const actions: readonly [{
     readonly id: "import";
     readonly command: readonly ["import"];
     readonly summary: "Replace local or preview state from an export document.";
+    readonly description: string;
     readonly usage: readonly ["import <preview-url> <file> [--json]", "import --state <dev|preview> [directory] <file> [--json]"];
     readonly helpOrder: 300;
     readonly outputProtocol: "xeer.command.v0";

package/vendor/spec/actions.js

@@ -4,6 +4,20 @@ export const ACTION_REGISTRY_PROTOCOL = 'xeer.actions.v0';
 export const XEER_MCP_PROFILES = ['author', 'operator'];
 export const XEER_ARTIFACT_ID_PATTERN = '^sha256:[a-f0-9]{64}$';
 export const MCP_INPUT_SCHEMA_DRAFT = 'http://json-schema.org/draft-07/schema#';
+/**
+ * Human-facing summaries for command families. Membership and ordering still come from the action
+ * registry; this only supplies the sentence that no individual subcommand can describe honestly.
+ */
+export const XEER_CLI_COMMAND_GROUPS = Object.freeze([
+    { command: 'agent', summary: 'Set up agent integrations and inspect normalized project context.' },
+    { command: 'docs', summary: 'Search the documentation bundled with this Xeer version.' },
+    { command: 'auth', summary: 'Manage builder credentials and local development personas.' },
+    { command: 'domains', summary: 'Manage an application\'s platform and custom domains.' },
+    { command: 'state', summary: 'Inspect running application state or reset local state.' },
+    { command: 'env', summary: 'Manage application environment values and secrets.' },
+    { command: 'token', summary: 'Manage service builder tokens.' },
+    { command: 'db', summary: 'Inspect and query a running application database.' },
+]);
 const NOT_EXPOSED_V0 = 'Not exposed through MCP v0; use the CLI deliberately.';
 const HUMAN_IDENTITY = 'Human identity and project ownership decisions are not delegated through MCP.';
 const SECRET_VALUES = 'Secret values are intentionally unreachable through MCP; env pull returns plaintext.';
@@ -179,6 +193,9 @@ const actions = [
     },
     {
         id: 'new', command: ['new'], summary: 'Create a new project from a supported scaffold.',
+        description: 'Creates a complete project that checks, tests, and builds clean. Templates do not '
+            + 'scaffold sign-in UI: every visitor already has a verified identity, and the generated README '
+            + 'explains how to opt in to a persistent account.',
         usage: ['new <directory> [--template {{templates}}] [--json]'], helpOrder: 30,
         outputProtocol: 'xeer.command.v0', effects: ['write-source'], idempotent: false,
         reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'project-relative',
@@ -250,6 +267,8 @@ const actions = [
     },
     {
         id: 'deploy', command: ['deploy'], summary: 'Build and deploy an application 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,
         outputProtocol: 'xeer.command.v0',
         effects: ['read-source', 'write-generated', 'run-local', 'network-read', 'network-write', 'production-change'],
@@ -259,6 +278,9 @@ const actions = [
     },
     {
         id: 'promote', command: ['promote'], summary: 'Promote a preview artifact to production.',
+        description: 'Makes the exact artifact serving in preview live in production without rebuilding it. '
+            + '--receipt uses the immutable review record from a preview deploy; --from-artifact is the direct '
+            + 'human override for a retained artifact.',
         usage: ['promote [app|directory] [--receipt <receiptId> | --from-artifact <artifactId>] '
                 + '[--control-url <url>] [--json]'], helpOrder: 80,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'production-change'],
@@ -315,6 +337,9 @@ const actions = [
     },
     {
         id: 'inspect', command: ['inspect'], summary: 'Read a running application manifest.',
+        description: 'Reads a local dev or preview URL directly. For a deployed application, Xeer uses the '
+            + 'signed-in builder credential and defaults names and app IDs to production; pass an exact URL or '
+            + '--environment preview to select preview.',
         usage: ['inspect <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]'], helpOrder: 230,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'], idempotent: true,
         reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
@@ -423,6 +448,8 @@ const actions = [
     },
     {
         id: 'deployments', command: ['deployments'], summary: 'List deployment history for an application.',
+        description: 'Lists the newest deployments first and marks the version serving each environment. '
+            + 'With no target, it uses the application linked to the current directory.',
         usage: ['deployments [app|directory] [--limit <n>] [--control-url <url>] [--json]'], helpOrder: 70,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state', 'secret-metadata'],
         idempotent: true, reversible: true, destructive: false,
@@ -431,6 +458,8 @@ const actions = [
     },
     {
         id: 'rollback', command: ['rollback'], summary: 'Redeploy a previously deployed artifact.',
+        description: 'Creates a new deployment from a retained artifact instead of rewriting history. Use the '
+            + 'artifact ID from xeer deployments; current environment values are injected at deployment time.',
         usage: ['rollback [app|directory] <artifactId> [--environment prod|preview] [--control-url <url>] [--json]'],
         helpOrder: 90, outputProtocol: 'xeer.command.v0',
         effects: ['network-read', 'network-write', 'production-change'], idempotent: false,
@@ -440,6 +469,8 @@ const actions = [
     },
     {
         id: 'disable', command: ['disable'], summary: 'Take an application offline without deleting its data.',
+        description: 'Returns 410 Gone for application requests while preserving the Worker, stored data, and '
+            + 'environment values. Run xeer enable to restore service.',
         usage: ['disable [app|directory] [--control-url <url>] [--json]'], helpOrder: 100,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'production-change'],
         idempotent: true, reversible: true, destructive: false,
@@ -456,6 +487,8 @@ const actions = [
     },
     {
         id: 'delete', command: ['delete'], summary: 'Permanently delete an application and all of its data.',
+        description: 'Destroys the deployed Worker and stored data, stops the origin resolving, and permanently '
+            + 'retires the app ID. The exact application name is required with --confirm.',
         usage: ['delete [app|directory] --confirm <application> [--control-url <url>] [--json]'], helpOrder: 120,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'network-write', 'write-state', 'production-change'],
         idempotent: false, reversible: false, destructive: true,
@@ -505,6 +538,9 @@ const actions = [
     },
     {
         id: 'state.read', command: ['state'], summary: 'Read record counts from a running application.',
+        description: 'Reads a local dev or preview URL directly. For a deployed application, Xeer uses the '
+            + 'signed-in builder credential and defaults names and app IDs to production; pass an exact URL or '
+            + '--environment preview to select preview.',
         usage: ['state <local-url|app> [--environment prod|preview] [--control-url <url>] [--json]'], helpOrder: 260,
         outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'], idempotent: true,
         reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
@@ -520,6 +556,9 @@ const actions = [
     },
     {
         id: 'logs', command: ['logs'], summary: 'Read the bounded log ring of a running application.',
+        description: 'Reads a local dev or preview URL directly. For a deployed application, Xeer uses the '
+            + 'signed-in builder credential and defaults names and app IDs to production; pass an exact URL or '
+            + '--environment preview to select preview.',
         usage: ['logs <local-url|app> [--environment prod|preview] [--after <cursor>] [--control-url <url>] [--json]'],
         helpOrder: 280, outputProtocol: 'xeer.command.v0', effects: ['network-read', 'read-state'],
         idempotent: true, reversible: true, destructive: false, humanPrerequisites: [], pathPolicy: 'app-or-url',
@@ -527,6 +566,8 @@ const actions = [
     },
     {
         id: 'export', command: ['export'], summary: 'Export application state to a document.',
+        description: 'Reads a local URL directly or a deployed application through the signed-in builder. '
+            + 'Use --state to export from the xeer dev or xeer preview server running for a project directory.',
         usage: [
             'export <local-url|app> [--environment prod|preview] [--out <file>] [--control-url <url>] [--json]',
             'export --state <dev|preview> [directory] [--out <file>] [--json]',
@@ -537,6 +578,8 @@ const actions = [
     },
     {
         id: 'import', command: ['import'], summary: 'Replace local or preview state from an export document.',
+        description: 'Replaces the selected state wholesale. Direct URLs must point to preview; --state imports '
+            + 'into the xeer dev or xeer preview server running for a project directory. Production import is refused.',
         usage: [
             'import <preview-url> <file> [--json]',
             'import --state <dev|preview> [directory] <file> [--json]',