@cloudhal/mcp-server 0.0.0-stage → 0.1.1

package/dist/src/server.js

@@ -0,0 +1,135 @@
+/**
+ * The Cloudhal MCP server (ADR-0004, ADR-0011): one `McpServer` per principal, built from the
+ * SDK-independent tool definitions in `tools.ts`. It adds what the protocol needs on top of the
+ * policy engine:
+ *
+ * - **Approval gate** — when policy answers `approval-required`, the call returns MCP's
+ *   multi-round-trip `input_required` with an elicitation ("Publish X to production?"). The human
+ *   answers in their client; the client retries with `inputResponses` and the HMAC-signed
+ *   `requestState`, and only then does the handler run. Clients without elicitation get a
+ *   `confirmToken` to pass on a second call (ADR-0004 fallback; can be disabled).
+ * - **Skills as resources** — `skill://<name>/SKILL.md` and `skill://<name>/references/<file>`.
+ * - **Skill-scoped calls** — a client declares the skill it is following via
+ *   `_meta["cloudhal.skill"]`; the policy engine then limits the call to that skill's scopes.
+ * - **Audit** — every decision and call is recorded (see `runTool`).
+ */
+import {
+                     
+                
+                   
+                         
+  PolicyEngine,
+                 
+} from "@cloudhal/agent-runtime";
+                                                                    
+                                                        
+import { createRequestStateCodec, McpServer } from "@modelcontextprotocol/server";
+                                                  
+                                                                               
+                                                    
+                                                           
+import {                   handleToolCall } from "./server-call.js";
+import { serverInstructions } from "./server-instructions.js";
+import { registerResources } from "./server-resources.js";
+import { compiledSchema, defaultToolList, registeredInputSchema } from "./server-schema.js";
+import {                      toolPolicies } from "./tools.js";
+
+export { SKILL_META_KEY } from "./server-call.js";
+
+                                     
+                        
+                                                                                      
+                                    
+                                                                                               
+                       
+                               
+                                     
+                                                                           
+                                      
+                                                                                                
+                                     
+                                                                                                  
+                                       
+                                                                          
+                                           
+                                                              
+                                      
+                                                                             
+                                        
+                                                   
+                                  
+     
+                                                                                                  
+                                                                                             
+     
+                                
+     
+                                                                                                   
+                                                                                                  
+                                                                                          
+     
+                                        
+     
+                                                                                                    
+                          
+     
+                                            
+     
+                                                                                              
+                                                                                          
+     
+                                             
+                                                                     
+                                 
+                                                                           
+                                          
+                                       
+                                    
+                                                               
+ 
+
+/** Builds a Cloudhal MCP server for one principal. */
+export function createCloudhalMcpServer(options                    )            {
+  const tools = options.tools ?? defaultToolList();
+  const policy = options.policy ?? new PolicyEngine(toolPolicies(tools));
+  const skills = new Map((options.skills ?? []).map((s) => [s.manifest.name, s]));
+  const fallback = options.confirmTokenFallback ?? false;
+  const codec = createRequestStateCodec               ({
+    key: options.stateKey,
+    ttlSeconds: options.approvalTtlSeconds ?? 600,
+    bind: () => `cloudhal.approval\0${options.principal.actor.id}`,
+  });
+
+  const server = new McpServer(
+    {
+      name: options.serverInfo?.name ?? "cloudhal",
+      version: options.serverInfo?.version ?? "0.0.1",
+      title: "Cloudhal",
+      websiteUrl: "https://github.com/cloudhal-dev/cloudhal",
+    },
+    {
+      capabilities: { tools: {}, resources: {} },
+      instructions: serverInstructions(options.principal),
+      requestState: { verify: codec.verify },
+    },
+  );
+
+  const rt              = { options, policy, skills, codec, fallback, server };
+  for (const def of tools)
+    server.registerTool(
+      def.name,
+      {
+        title: def.title,
+        description: def.description,
+        inputSchema: registeredInputSchema(def, { approvals: !!options.approvals, fallback }),
+        outputSchema: compiledSchema(def.outputSchema, "", () => def.outputSchema),
+        annotations: { ...def.annotations, title: def.title },
+        // MCP Apps: hosts that render UI show the tool's results in Cloudhal's View; others ignore it.
+        ...(def.ui ? { _meta: { ui: { ...def.ui } } } : {}),
+      },
+      (rawArgs, ctx) => handleToolCall(rt, def, rawArgs, ctx),
+    );
+
+  registerResources(server, skills);
+  return server;
+}

package/dist/src/stdio.d.ts

@@ -0,0 +1,9 @@
+import { type CloudhalMcpOptions } from "./server.js";
+export interface StdioOptions extends Omit<CloudhalMcpOptions, "stateKey"> {
+    stateKey?: Uint8Array | string | undefined;
+    onerror?: ((error: Error) => void) | undefined;
+}
+/** Serves one Cloudhal MCP server over the process's stdin/stdout. Resolves `close()` to stop. */
+export declare function serveCloudhalStdio(options: StdioOptions): {
+    close(): Promise<void>;
+};

package/dist/src/stdio.js

@@ -0,0 +1,18 @@
+/** stdio transport: `cloudhal mcp` runs this for local MCP clients (Claude Code, Cursor, …). */
+import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import {                          createCloudhalMcpServer } from "./server.js";
+
+                                                                            
+                                             
+                                                 
+ 
+
+/** Serves one Cloudhal MCP server over the process's stdin/stdout. Resolves `close()` to stop. */
+export function serveCloudhalStdio(options              )                             {
+  // One process serves every round of an approval, so a per-process random key is enough.
+  const stateKey = options.stateKey ?? crypto.getRandomValues(new Uint8Array(32));
+  const { onerror, ...rest } = options;
+  return serveStdio(() => createCloudhalMcpServer({ ...rest, stateKey }), {
+    ...(onerror ? { onerror } : {}),
+  });
+}

package/dist/src/surface-tools.d.ts

@@ -0,0 +1,4 @@
+/** RFC-0020 surface tools: the catalog, JSON Patch drafts, A2UI / json-render import and export. */
+import { type ToolDefinition } from "./common.js";
+/** get_catalog … export_surface, in `tools/list` order. */
+export declare function surfaceTools(): ToolDefinition[];

package/dist/src/surface-tools.js

@@ -0,0 +1,357 @@
+/** RFC-0020 surface tools: the catalog, JSON Patch drafts, A2UI / json-render import and export. */
+
+                                                     
+import { ID_PREFIX, newId } from "@cloudhal/core-ts";
+import {
+  fromA2ui,
+  fromJsonRender,
+  InteropError,
+                     
+  toA2ui,
+  toJsonRender,
+} from "@cloudhal/core-ts/interop";
+import { mediaPath } from "@cloudhal/core-ts/media";
+import {
+  catalogPrompt,
+               
+  patchPage,
+  SURFACE_LIMITS,
+  SurfacePatchError,
+} from "@cloudhal/core-ts/surfaces";
+import {
+  autoSnapshot,
+  id,
+  mapError,
+  notifyBuild,
+  obj,
+  requireSite,
+  str,
+                   
+                      
+  ToolError,
+} from "./common.js";
+import {
+  assertNoHtmlSections,
+  mcpWriter,
+  PAGE,
+  SNAPSHOT,
+  siteCatalog,
+  unknownBlocks,
+  unknownBlocksOf,
+} from "./content-shared.js";
+import { PREVIEW_UI_URI } from "./preview-view.js";
+
+const getCatalogTool                 = {
+  name: "get_catalog",
+  title: "Get the UI catalog",
+  description:
+    "The components a page surface may use on this site (RFC-0020): Cloudhal's layout, content and interactive primitives plus the theme's block types, with their props, child rules, bindings ({path}), named functions, visibility conditions and limits, as instructions to follow. Read it before building or changing surfaces with patch_draft.",
+  inputSchema: obj({ siteId: id }, ["siteId"]),
+  outputSchema: obj(
+    {
+      catalog: { type: "string" },
+      components: { type: "array", items: { type: "string" } },
+      instructions: { type: "string" },
+    },
+    ["catalog", "components", "instructions"],
+  ),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  scopes: ["content:read"],
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    const catalog = siteCatalog(site, ctx);
+    return {
+      catalog: catalog.id,
+      components: catalog.names(),
+      instructions: catalogPrompt(catalog, site.defaultLocale),
+    };
+  },
+};
+
+const patchDraftTool                 = {
+  name: "patch_draft",
+  ui: { resourceUri: PREVIEW_UI_URI },
+  title: "Patch a page draft",
+  description:
+    'Build or change a page step by step with RFC 6902 JSON Patch operations on /title, /sections and /seo, e.g. {"op":"add","path":"/sections/-","value":{…a surface…}}. Every call is checked as a whole: misspelt component names are snapped to the catalog, unknown props dropped and missing required ones filled from the example (all listed in `repairs`), then every surface is validated. Failures come back as `invalid_surface` with VALIDATION_FAILED issues carrying JSON Pointers: fix those parts and send again. Requires the page\'s current `rev`; writes the draft and snapshots afterwards. Never publishes. Read get_catalog first.',
+  inputSchema: obj(
+    {
+      siteId: id,
+      pageId: id,
+      rev: { type: "integer", minimum: 0 },
+      ops: {
+        type: "array",
+        minItems: 1,
+        maxItems: SURFACE_LIMITS.opsPerCall,
+        items: obj(
+          {
+            op: { type: "string", enum: ["add", "remove", "replace", "move", "copy", "test"] },
+            path: str("JSON Pointer into the page, under /title, /sections or /seo"),
+            from: str("For move and copy: JSON Pointer of the source"),
+            value: {},
+          },
+          ["op", "path"],
+        ),
+      },
+    },
+    ["siteId", "pageId", "rev", "ops"],
+  ),
+  outputSchema: obj(
+    {
+      page: PAGE,
+      snapshot: SNAPSHOT,
+      repairs: { type: "array", items: { type: "string" } },
+      unknownBlocks,
+    },
+    ["page", "snapshot", "repairs"],
+  ),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
+  scopes: ["content:write"],
+  handler: (a, ctx) =>
+    applyDraftOps(ctx, "patch_draft", {
+      siteId: a.siteId          ,
+      pageId: a.pageId          ,
+      rev: a.rev          ,
+      ops: () => a.ops             ,
+    }),
+};
+
+const importSurfaceTool                 = {
+  name: "import_surface",
+  ui: { resourceUri: PREVIEW_UI_URI },
+  title: "Import a surface",
+  description:
+    "Add (or replace) a page surface from another generative-UI format: `a2ui` takes A2UI v0.9 messages (createSurface, updateComponents, updateDataModel; basic catalog), `json-render` takes a spec ({root, elements, state?}) written against Cloudhal's catalog. What has no Cloudhal equivalent (server events, text fields, image URLs, unknown functions) is left out and listed in `notes`; the result then goes through the same repairs and validation as patch_draft. Requires the page's current `rev`; writes the draft and snapshots afterwards. Never publishes.",
+  inputSchema: obj(
+    {
+      siteId: id,
+      pageId: id,
+      rev: { type: "integer", minimum: 0 },
+      format: { type: "string", enum: ["a2ui", "json-render"] },
+      document: {
+        description:
+          "a2ui: the array of messages (or JSON Lines text); json-render: the spec object (or its JSON text)",
+      },
+      surfaceId: str("a2ui: which surface of the messages, when they hold several"),
+      replaceSectionId: {
+        ...id,
+        description: "Replace this surface section instead of adding a new one at the end",
+      },
+    },
+    ["siteId", "pageId", "rev", "format", "document"],
+  ),
+  outputSchema: obj(
+    {
+      page: PAGE,
+      snapshot: SNAPSHOT,
+      sectionId: id,
+      notes: { type: "array", items: { type: "string" } },
+      repairs: { type: "array", items: { type: "string" } },
+      unknownBlocks,
+    },
+    ["page", "snapshot", "sectionId", "notes", "repairs"],
+  ),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
+  scopes: ["content:write"],
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    const page = await ctx.store.getPage(a.pageId          );
+    if (!page || page.siteId !== site.id)
+      throw new ToolError("not_found", `page ${a.pageId} not found`);
+    const replace = a.replaceSectionId                      ;
+    const at = replace ? page.sections.findIndex((s) => s.id === replace) : -1;
+    if (replace && (at < 0 || page.sections[at]?.kind !== "surface"))
+      throw new ToolError("not_found", `page ${page.id} has no surface section ${replace}`);
+    const sectionId = replace ?? newId(ID_PREFIX.section);
+    const converted = convertSurface(a, sectionId, siteCatalog(site, ctx).id);
+    const result = await applyDraftOps(ctx, "import_surface", {
+      siteId: site.id,
+      pageId: page.id,
+      rev: a.rev          ,
+      ops: () => [
+        replace
+          ? { op: "replace", path: `/sections/${at}`, value: converted.surface }
+          : { op: "add", path: "/sections/-", value: converted.surface },
+      ],
+    });
+    return { ...result, sectionId, notes: converted.notes };
+  },
+};
+
+const exportSurfaceTool                 = {
+  name: "export_surface",
+  title: "Export a surface",
+  description:
+    "A page's surface section in another generative-UI format: `a2ui` (A2UI v0.9 messages for the basic catalog, images as absolute URLs when the site has a primary domain) or `json-render` (a spec with the data as state). What the format cannot express is listed in `notes`. Read-only.",
+  inputSchema: obj(
+    {
+      siteId: id,
+      pageId: id,
+      sectionId: id,
+      format: { type: "string", enum: ["a2ui", "json-render"] },
+    },
+    ["siteId", "pageId", "sectionId", "format"],
+  ),
+  outputSchema: obj(
+    {
+      format: { type: "string" },
+      document: {},
+      notes: { type: "array", items: { type: "string" } },
+    },
+    ["format", "document", "notes"],
+  ),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  scopes: ["content:read"],
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    const page = await ctx.store.getPage(a.pageId          );
+    if (!page || page.siteId !== site.id)
+      throw new ToolError("not_found", `page ${a.pageId} not found`);
+    const section = page.sections.find((s) => s.id === a.sectionId);
+    if (section?.kind !== "surface")
+      throw new ToolError("not_found", `page ${page.id} has no surface section ${a.sectionId}`);
+    if (a.format === "json-render") {
+      const { spec, notes } = toJsonRender(section);
+      return { format: "json-render", document: spec, notes };
+    }
+    const host = site.domains.find((d) => d.primary)?.hostname;
+    const urls = new Map                ();
+    if (host)
+      for (const c of section.components) {
+        const ref = c.component === "Image" ? c.props?.asset : undefined;
+        if (typeof ref !== "string" || !ref.startsWith("asset:")) continue;
+        const asset = await ctx.store.getAsset(ref.slice("asset:".length));
+        if (asset && asset.siteId === site.id) urls.set(ref, `https://${host}${mediaPath(asset)}`);
+      }
+    const { messages, notes } = toA2ui(section, { assetUrl: (ref) => urls.get(ref) });
+    return { format: "a2ui", document: messages, notes };
+  },
+};
+
+/** get_catalog … export_surface, in `tools/list` order. */
+export function surfaceTools()                   {
+  return [getCatalogTool, patchDraftTool, importSurfaceTool, exportSurfaceTool];
+}
+
+/**
+ * `patch_draft`'s write path, shared with `import_surface`: CAS on the page's `rev`, repairs and
+ * validation (`patchPage`), the store write, one snapshot and the build events.
+ */
+async function applyDraftOps(
+  ctx             ,
+  tool        ,
+  input                                                                       ,
+) {
+  const site = await requireSite(ctx, input.siteId);
+  const page = await ctx.store.getPage(input.pageId);
+  if (!page || page.siteId !== site.id)
+    throw new ToolError("not_found", `page ${input.pageId} not found`);
+  if (page.rev !== input.rev)
+    throw new ToolError(
+      "conflict",
+      `page ${page.id} is at rev ${page.rev}, you sent ${input.rev}; reload with get_page and retry`,
+    );
+  const ops = input.ops();
+  let patched                                  ;
+  try {
+    patched = patchPage(page, ops, siteCatalog(site, ctx));
+  } catch (e) {
+    if (e instanceof SurfacePatchError) {
+      await notifyBuild(() =>
+        ctx.build?.patchRejected({
+          siteId: site.id,
+          pageId: page.id,
+          tool,
+          actor: ctx.principal.actor,
+          issues: e.issues,
+        }),
+      );
+      throw new ToolError(
+        "invalid_surface",
+        `${e.message}. Fix the parts at these JSON Pointers and send the operations again; get_catalog lists every component and its props`,
+        { issues: e.issues },
+      );
+    }
+    throw e;
+  }
+  assertNoHtmlSections(patched.value.sections);
+  try {
+    const saved = await ctx.store.updatePage(patched.value, { writer: mcpWriter(ctx) });
+    const snapshot = await autoSnapshot(ctx, page.siteId, tool);
+    await notifyBuild(() =>
+      ctx.build?.pageChanged({
+        siteId: site.id,
+        page: saved,
+        tool,
+        actor: ctx.principal.actor,
+        ops: ops             ,
+        repairs: patched.notes,
+      }),
+    );
+    return {
+      page: saved,
+      snapshot,
+      repairs: patched.notes,
+      ...unknownBlocksOf(ctx, { sections: saved.sections }),
+    };
+  } catch (e) {
+    mapError(e);
+  }
+}
+
+/** `import_surface`'s document as a Cloudhal surface (A2UI messages or a json-render spec). */
+function convertSurface(
+  a                         ,
+  sectionId        ,
+  catalog        ,
+)                {
+  const parse = (raw         , lines         )          => {
+    if (typeof raw !== "string") return raw;
+    try {
+      return lines
+        ? raw
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean)
+            .map((l) => JSON.parse(l))
+        : JSON.parse(raw);
+    } catch {
+      throw new ToolError("invalid", "document is not valid JSON (or JSON Lines for a2ui)");
+    }
+  };
+  try {
+    if (a.format === "a2ui") {
+      const doc = parse(a.document, true);
+      const messages = Array.isArray(doc) ? doc : [doc];
+      return fromA2ui(messages, {
+        sectionId,
+        catalog,
+        ...(typeof a.surfaceId === "string" ? { surfaceId: a.surfaceId } : {}),
+      });
+    }
+    return fromJsonRender(parse(a.document, false), { sectionId, catalog });
+  } catch (e) {
+    if (e instanceof InteropError) throw new ToolError("invalid", e.message);
+    throw e;
+  }
+}

package/dist/src/taxonomy-tools.d.ts

@@ -0,0 +1,16 @@
+import { type ToolDefinition } from "./common.js";
+/**
+ * Thresholds of `taxonomy_report` (returned with it): the core report's own, plus how many findings
+ * of one kind are listed.
+ */
+export declare const REPORT_THRESHOLDS: {
+    readonly maxEditDistance: 2;
+    readonly maxEditShare: 0.5;
+    readonly minSimilarLength: 4;
+    readonly oversizedShare: 0.5;
+    readonly oversizedMinEntries: 20;
+    readonly maxPairTerms: 2000;
+    /** Findings listed per kind (counts are complete). */
+    readonly maxPerKind: 50;
+};
+export declare function taxonomyTools(): ToolDefinition[];