@impetik/xeer-mcp 0.2.9 → 0.2.12

package/README.md

@@ -74,7 +74,7 @@ The generated registry is the complete MCP tool and exclusion surface:
 | `xeer_dev_start` | `dev.start` | `author` / `operator` | Start a local development session. | `directory?`: `string`<br>`host?`: `string`<br>`port?`: `integer` [0..65535]<br>`timeoutMilliseconds?`: `integer` [1000..600000] | `read-source`<br>`write-generated`<br>`run-local`<br>`write-state` | 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?`: `string`<br>`cursor?`: `integer` [0..9007199254740991]; default `0`<br>`waitMilliseconds?`: `integer` [0..600000]; default `0`<br>`limit?`: `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?`: `string`<br>`cursor?`: `integer` [0..9007199254740991]; default `0` | `run-local` | writes; idempotent; reversible; non-destructive | `none` | `xeer.dev.v0` | none |
-| `xeer_diagnostics` | `diagnostics` | `author` / `operator` | Read the generated diagnostic catalogue. | `code?`: `string` | none | read-only; idempotent; reversible; non-destructive | `none` | `unversioned` | 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 (34).**
 

package/dist/server.js

@@ -3,7 +3,7 @@ import { isAbsolute, relative, sep } from 'node:path';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
 import { createAgentContext, readDocsIndex, readDocsPage, searchDocs } from '@impetik/xeer/agent-context';
-import { DIAGNOSTICS, DIAGNOSTIC_CODES, DIAGNOSTIC_FAMILIES, diagnosticDefinition, renderDiagnosticsReference, } from '../vendor/spec/diagnostics.js';
+import { DIAGNOSTIC_FAMILIES, diagnosticDefinition, } from '../vendor/spec/diagnostics.js';
 import { actionDefinition, mcpAnnotations, } from '../vendor/spec/actions.js';
 import { isReviewReceiptId } from '../vendor/spec/review.js';
 import { DevSessionRegistry } from './dev-session.js';
@@ -541,18 +541,12 @@ export function createXeerMcpServer(options = {}) {
             means: z.string().optional(),
             repair: z.string().optional(),
             surfaces: z.array(z.string()).optional(),
-            codes: z.array(z.string()).optional(),
-            reference: z.string().optional(),
         }).loose()),
     }, async ({ code }) => {
-        if (!code) {
-            return structured('diagnostics', { codes: [...DIAGNOSTIC_CODES], reference: renderDiagnosticsReference() });
-        }
         const normalized = code.trim().toUpperCase();
         const definition = diagnosticDefinition(normalized);
         if (!definition) {
-            const known = Object.keys(DIAGNOSTICS).sort().join(', ');
-            return failure('diagnostics', 'unknown_diagnostic', `Unknown diagnostic code: ${normalized}. Known codes: ${known}`);
+            return failure('diagnostics', 'unknown_diagnostic', `Unknown diagnostic code: ${normalized}. Pass the exact XE#### emitted by Xeer.`);
         }
         const family = DIAGNOSTIC_FAMILIES.find((candidate) => candidate.prefix === definition.prefix);
         return structured('diagnostics', {

package/package.json

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

package/vendor/spec/actions.d.ts

@@ -627,10 +627,11 @@ declare const actions: readonly [{
     };
 }, {
     readonly id: "diagnostics";
-    readonly command: readonly [];
-    readonly summary: "Read the generated diagnostic catalogue.";
-    readonly usage: readonly [];
-    readonly outputProtocol: "unversioned";
+    readonly command: readonly ["diagnostics"];
+    readonly summary: "Explain one emitted diagnostic code.";
+    readonly usage: readonly ["diagnostics <XE####> [--json]"];
+    readonly helpOrder: 37;
+    readonly outputProtocol: "xeer.command.v0";
     readonly effects: readonly [];
     readonly idempotent: true;
     readonly reversible: true;
@@ -646,10 +647,11 @@ declare const actions: readonly [{
                     readonly type: "string";
                 };
             };
+            readonly required: readonly ["code"];
         };
         readonly mcpTitle: "Look up Xeer diagnostic codes";
         readonly mcpDescription: string;
-        readonly cli: false;
+        readonly cli: true;
         readonly mcpTool: "xeer_diagnostics";
         readonly mcpProfiles: readonly ["author", "operator"];
     };
@@ -1244,7 +1246,7 @@ export declare function mcpAnnotations(action: XeerActionDefinition): McpActionA
 export declare function mcpInputJsonSchema(action: XeerActionDefinition): McpInputJsonSchema | undefined;
 export declare const ACTION_REFERENCE_START = "<!-- xeer-action-reference:start -->";
 export declare const ACTION_REFERENCE_END = "<!-- xeer-action-reference:end -->";
-export declare const ACTION_REFERENCE_TARGETS: readonly ["docs/AGENTS.md", "packages/website/content/guides/agents.md", ".agents/skills/xeer/SKILL.md", "packages/mcp/README.md", "packages/website/content/reference/cli.md"];
+export declare const ACTION_REFERENCE_TARGETS: readonly ["docs/AGENTS.md", "packages/website/content/guides/agents.md", ".agents/skills/xeer/references/mcp-actions.md", "packages/mcp/README.md", "packages/website/content/reference/cli.md"];
 /** One generated block is embedded in every agent-facing action-policy surface. */
 export declare function renderActionReference(): string;
 export {};

package/vendor/spec/actions.js

@@ -136,9 +136,8 @@ const MCP_PRESENTATION = {
     },
     diagnostics: {
         mcpTitle: 'Look up Xeer diagnostic codes',
-        mcpDescription: 'Explain a diagnostic code: what the platform observed and which edit closes it. '
-            + 'Omit `code` for the whole generated reference. This is the same catalogue the compiler emits '
-            + 'from, so it cannot drift from the codes you receive.',
+        mcpDescription: 'Explain one diagnostic code: what the platform observed and which edit closes it. '
+            + 'Pass the exact XE#### emitted by the command; this lookup intentionally never returns the whole catalogue.',
     },
 };
 const actions = [
@@ -387,15 +386,16 @@ const actions = [
         },
     },
     {
-        id: 'diagnostics', command: [], summary: 'Read the generated diagnostic catalogue.',
-        usage: [], outputProtocol: 'unversioned', effects: [], idempotent: true, reversible: true,
+        id: 'diagnostics', command: ['diagnostics'], summary: 'Explain one emitted diagnostic code.',
+        usage: ['diagnostics <XE####> [--json]'], helpOrder: 37,
+        outputProtocol: 'xeer.command.v0', effects: [], idempotent: true, reversible: true,
         destructive: false, humanPrerequisites: [], pathPolicy: 'none',
         surfaces: {
-            cli: false, mcpTool: 'xeer_diagnostics', mcpProfiles: XEER_MCP_PROFILES,
+            cli: true, mcpTool: 'xeer_diagnostics', mcpProfiles: XEER_MCP_PROFILES,
             ...MCP_PRESENTATION.diagnostics,
             mcpInputSchema: { type: 'object', properties: {
                     code: { description: 'An XE#### code, e.g. XE1202.', type: 'string' },
-                } },
+                }, required: ['code'] },
         },
     },
     {
@@ -732,7 +732,7 @@ export const ACTION_REFERENCE_END = '<!-- xeer-action-reference:end -->';
 export const ACTION_REFERENCE_TARGETS = [
     'docs/AGENTS.md',
     'packages/website/content/guides/agents.md',
-    '.agents/skills/xeer/SKILL.md',
+    '.agents/skills/xeer/references/mcp-actions.md',
     'packages/mcp/README.md',
     'packages/website/content/reference/cli.md',
 ];

package/vendor/spec/index.d.ts

@@ -18,3 +18,4 @@ export * from './admin.js';
 export * from './admin-sql.js';
 export * from './network-policy.js';
 export * from './review.js';
+export * from './template.js';

package/vendor/spec/index.js

@@ -18,3 +18,4 @@ export * from './admin.js';
 export * from './admin-sql.js';
 export * from './network-policy.js';
 export * from './review.js';
+export * from './template.js';

package/vendor/spec/template.d.ts

@@ -0,0 +1,32 @@
+import { z } from 'zod';
+export declare const TEMPLATE_FORMAT: "xeer.template.v0";
+export declare const TEMPLATE_MANIFEST_SCHEMA_URL: "https://docs.xeer.run/template-v0.schema.json";
+export declare const templateManifestSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    format: z.ZodLiteral<"xeer.template.v0">;
+    title: z.ZodString;
+    description: z.ZodString;
+    category: z.ZodString;
+    tags: z.ZodArray<z.ZodString>;
+    keyHighlights: z.ZodArray<z.ZodString>;
+    screenshots: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        alt: z.ZodString;
+    }, z.core.$strict>>;
+    author: z.ZodObject<{
+        name: z.ZodString;
+        url: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    capabilities: z.ZodArray<z.ZodEnum<{
+        database: "database";
+        storage: "storage";
+    }>>;
+    requiredSecrets: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        description: z.ZodString;
+    }, z.core.$strict>>;
+    previewAppId: z.ZodString;
+}, z.core.$strict>;
+export type TemplateManifestV0 = z.infer<typeof templateManifestSchema>;
+export declare const templateManifestJsonSchema: Readonly<Record<string, unknown>>;
+export declare function parseTemplateManifest(value: unknown): TemplateManifestV0;

package/vendor/spec/template.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+import { CAPABILITIES } from './types.js';
+export const TEMPLATE_FORMAT = 'xeer.template.v0';
+export const TEMPLATE_MANIFEST_SCHEMA_URL = 'https://docs.xeer.run/template-v0.schema.json';
+const trimmed = (maximum) => z.string().min(1).max(maximum)
+    .refine((value) => value === value.trim(), 'must not have leading or trailing whitespace')
+    .refine((value) => !/[\u0000-\u001f\u007f]/u.test(value), 'must not contain control characters');
+const slug = z.string().regex(/^[a-z][a-z0-9-]{1,62}$/u, 'must be a lowercase slug between 2 and 63 characters');
+const environmentName = z.string().regex(/^[A-Z][A-Z0-9_]{0,63}$/u, 'must be an uppercase environment variable name');
+const appId = z.string().regex(/^app_[A-Za-z0-9_-]{8,96}$/u, 'must be a valid Xeer appId');
+const screenshotPath = z.string().regex(/^screenshots\/(?:[A-Za-z0-9][A-Za-z0-9._-]*\/)*[A-Za-z0-9][A-Za-z0-9._-]*\.(?:avif|jpe?g|png|webp)$/u, 'must be a repository-local AVIF, JPEG, PNG, or WebP path under screenshots/');
+const authorSchema = z.strictObject({
+    name: trimmed(80),
+    url: z.string().url().optional(),
+});
+const requiredSecretSchema = z.strictObject({
+    name: environmentName,
+    description: trimmed(200),
+});
+const screenshotSchema = z.strictObject({
+    path: screenshotPath,
+    alt: trimmed(200),
+});
+export const templateManifestSchema = z.strictObject({
+    $schema: z.string().url().optional(),
+    format: z.literal(TEMPLATE_FORMAT),
+    title: trimmed(120),
+    description: trimmed(300),
+    category: slug,
+    tags: z.array(trimmed(40)).min(1).max(16),
+    keyHighlights: z.array(trimmed(120)).min(1).max(8),
+    screenshots: z.array(screenshotSchema).min(1).max(8),
+    author: authorSchema,
+    capabilities: z.array(z.enum(CAPABILITIES)).max(CAPABILITIES.length),
+    requiredSecrets: z.array(requiredSecretSchema).max(16),
+    previewAppId: appId,
+}).superRefine((manifest, ctx) => {
+    const unique = (values, path, label) => {
+        const seen = new Set();
+        for (const [index, value] of values.entries()) {
+            const normalized = value.toLocaleLowerCase('en-US');
+            if (seen.has(normalized)) {
+                ctx.addIssue({ code: 'custom', path: [path, index], message: `${label} is declared twice` });
+            }
+            seen.add(normalized);
+        }
+    };
+    unique(manifest.tags, 'tags', 'tag');
+    unique(manifest.keyHighlights, 'keyHighlights', 'highlight');
+    unique(manifest.screenshots.map((screenshot) => screenshot.path), 'screenshots', 'screenshot');
+    unique(manifest.capabilities, 'capabilities', 'capability');
+    unique(manifest.requiredSecrets.map((secret) => secret.name), 'requiredSecrets', 'secret');
+});
+const generatedTemplateManifestJsonSchema = z.toJSONSchema(templateManifestSchema);
+const generatedProperties = generatedTemplateManifestJsonSchema.properties;
+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.',
+    properties: {
+        ...generatedProperties,
+        $schema: {
+            ...generatedProperties.$schema,
+            description: 'Editor schema hint. Xeer does not fetch this URL during validation.',
+        },
+        format: {
+            ...generatedProperties.format,
+            description: `Template metadata protocol discriminator; exactly ${TEMPLATE_FORMAT}.`,
+        },
+        tags: {
+            ...generatedProperties.tags,
+            uniqueItems: true,
+        },
+        keyHighlights: {
+            ...generatedProperties.keyHighlights,
+            uniqueItems: true,
+        },
+        screenshots: {
+            ...generatedProperties.screenshots,
+            description: 'Repository-local raster images used by template galleries.',
+            uniqueItems: true,
+        },
+        capabilities: {
+            ...generatedProperties.capabilities,
+            description: 'Application capabilities, verified against xeer.app.json when the catalog is generated.',
+            uniqueItems: true,
+        },
+        previewAppId: {
+            ...generatedProperties.previewAppId,
+            description: 'Stable first-party application identity used only for the public live preview.',
+        },
+        requiredSecrets: {
+            ...generatedProperties.requiredSecrets,
+            description: 'Secrets a template copy needs before it is usable.',
+        },
+    },
+});
+export function parseTemplateManifest(value) {
+    return templateManifestSchema.parse(value);
+}