@cloudhal/mcp-server 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,5 @@
+import { type ToolDefinition } from "./common.js";
+/** list_sites … update_page, in `tools/list` order. */
+export declare function siteAndPageTools(): ToolDefinition[];
+/** delete_page, listed after the surface tools. */
+export declare function pageRemovalTools(): ToolDefinition[];

package/dist/src/page-tools.js

@@ -0,0 +1,311 @@
+import { visibleSites } from "@cloudhal/agent-runtime";
+/** Site and page tools: list, read, create, update and delete pages. */
+
+                                                              
+import {
+  autoSnapshot,
+  id,
+                  
+  mapError,
+  notifyBuild,
+  obj,
+  requireSite,
+  str,
+                      
+  ToolError,
+} from "./common.js";
+import {
+  assertNoHtmlSections,
+  mcpWriter,
+  PAGE,
+           
+  SITE,
+  SNAPSHOT,
+  sectionInput,
+  unknownBlocks,
+  unknownBlocksOf,
+} from "./content-shared.js";
+import { menuHint, menuItemsHiddenBy } from "./menu-tools.js";
+
+const listSitesTool                 = {
+  name: "list_sites",
+  title: "List sites",
+  description: "Sites this principal can operate.",
+  inputSchema: obj({}),
+  outputSchema: obj({ sites: { type: "array", items: SITE } }, ["sites"]),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  scopes: ["site:read"],
+  // RFC-0034 A2: only the sites the principal's person may open.
+  handler: async (_a, ctx) => {
+    const all = await ctx.store.listSites();
+    const ids = visibleSites(
+      ctx.principal,
+      all.map((s) => s.id),
+    );
+    return { sites: all.filter((s) => ids.includes(s.id)) };
+  },
+};
+
+const getSiteTool                 = {
+  name: "get_site",
+  title: "Get site",
+  description: "A site with its page order, locales, theme and published snapshot.",
+  inputSchema: obj({ siteId: id }, ["siteId"]),
+  outputSchema: obj({ site: SITE }, ["site"]),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  scopes: ["site:read"],
+  handler: async (a, ctx) => ({ site: await requireSite(ctx, a.siteId          ) }),
+};
+
+const listPagesTool                 = {
+  name: "list_pages",
+  title: "List pages",
+  description: "Pages of a site in navigation order (all statuses).",
+  inputSchema: obj({ siteId: id }, ["siteId"]),
+  outputSchema: obj({ pages: { type: "array", items: PAGE } }, ["pages"]),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  scopes: ["content:read"],
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    const order = new Map(site.pageIds.map((pid, i) => [pid, i]));
+    const pages = (await ctx.store.listPages(site.id)).sort(
+      (x, y) => (order.get(x.id) ?? 1e9) - (order.get(y.id) ?? 1e9),
+    );
+    return { pages };
+  },
+};
+
+const getPageTool                 = {
+  name: "get_page",
+  title: "Get page",
+  description: "One page with its sections and current revision (send `rev` back when updating).",
+  inputSchema: obj({ siteId: id, pageId: id }, ["siteId", "pageId"]),
+  outputSchema: obj({ page: PAGE }, ["page"]),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  scopes: ["content:read"],
+  handler: async (a, ctx) => {
+    const page = await ctx.store.getPage(a.pageId          );
+    if (!page || page.siteId !== a.siteId)
+      throw new ToolError("not_found", `page ${a.pageId} not found`);
+    return { page };
+  },
+};
+
+const createPageTool                 = {
+  name: "create_page",
+  title: "Create page",
+  description:
+    "Create a draft page and append it to the site's navigation. Snapshots the site afterwards.",
+  inputSchema: obj(
+    {
+      siteId: id,
+      path: str("Absolute lower-case path, e.g. /about", {
+        pattern: "^/(?:[a-z0-9]+(?:-[a-z0-9]+)*(?:/[a-z0-9]+(?:-[a-z0-9]+)*)*)?$",
+      }),
+      title: str("Page title"),
+      locale: str("BCP 47 locale; defaults to the site's default locale"),
+      sections: sectionInput,
+      seo: PAGE.$defs ? ((PAGE.$defs              ).Seo              ) : { type: "object" },
+    },
+    ["siteId", "path", "title"],
+  ),
+  outputSchema: obj(
+    { page: PAGE, site: SITE, snapshot: SNAPSHOT, hint: { type: "string" }, unknownBlocks },
+    ["page", "site", "snapshot"],
+  ),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
+  scopes: ["content:write"],
+  handler: async (a, ctx) => {
+    assertNoHtmlSections(a.sections);
+    const site = await requireSite(ctx, a.siteId          );
+    try {
+      const result = await ctx.store.createPage(
+        site,
+        {
+          siteId: site.id,
+          path: a.path          ,
+          title: a.title          ,
+          locale: (a.locale                      ) ?? site.defaultLocale,
+          status: "draft",
+          sections: (a.sections                         ) ?? [],
+          ...(a.seo ? { seo: a.seo        } : {}),
+        },
+        { writer: mcpWriter(ctx) },
+      );
+      const snapshot = await autoSnapshot(ctx, site.id, "create_page");
+      const hint = await menuHint(ctx, site.id, { kind: "page", id: result.page.id });
+      return {
+        ...result,
+        snapshot,
+        ...(hint ? { hint } : {}),
+        ...unknownBlocksOf(ctx, { sections: result.page.sections }),
+      };
+    } catch (e) {
+      mapError(e);
+    }
+  },
+};
+
+const updatePageTool                 = {
+  name: "update_page",
+  title: "Update page",
+  description:
+    "Replace a page's title, path, sections or seo, or set its own motion level and chrome (RFC-0025: header default|transparent|hidden, footer default|minimal|hidden; null goes back to the site's). Requires the current `rev` (optimistic locking). Status changes are not allowed here. Snapshots afterwards.",
+  inputSchema: obj(
+    {
+      siteId: id,
+      pageId: id,
+      rev: { type: "integer", minimum: 0 },
+      title: str("New title"),
+      path: str("New path"),
+      sections: sectionInput,
+      seo: { type: "object" },
+      motion: {
+        type: ["string", "null"],
+        enum: ["none", "subtle", "standard", "expressive", null],
+        description: "This page's motion level over the site's (RFC-0024); null removes it",
+      },
+      chrome: {
+        type: ["object", "null"],
+        properties: {
+          header: { type: "string", enum: ["default", "transparent", "hidden"] },
+          footer: { type: "string", enum: ["default", "minimal", "hidden"] },
+        },
+        additionalProperties: false,
+        description: "This page's header and footer (RFC-0025); null removes it",
+      },
+    },
+    ["siteId", "pageId", "rev"],
+  ),
+  outputSchema: obj({ page: PAGE, snapshot: SNAPSHOT, unknownBlocks }, ["page", "snapshot"]),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
+  scopes: ["content:write"],
+  handler: async (a, ctx) => {
+    assertNoHtmlSections(a.sections);
+    const page = await ctx.store.getPage(a.pageId          );
+    if (!page || page.siteId !== a.siteId)
+      throw new ToolError("not_found", `page ${a.pageId} not found`);
+    if (page.rev !== a.rev)
+      throw new ToolError(
+        "conflict",
+        `page ${page.id} is at rev ${page.rev}, you sent ${a.rev}; reload and retry`,
+      );
+    const { motion: _motion, chrome: _chrome, ...kept } = page;
+    const next       = {
+      ...kept,
+      ...(a.motion === undefined
+        ? page.motion
+          ? { motion: page.motion }
+          : {}
+        : a.motion
+          ? { motion: a.motion                                }
+          : {}),
+      ...(a.chrome === undefined
+        ? page.chrome
+          ? { chrome: page.chrome }
+          : {}
+        : a.chrome
+          ? { chrome: a.chrome                                }
+          : {}),
+      ...(a.title ? { title: a.title           } : {}),
+      ...(a.path ? { path: a.path           } : {}),
+      ...(a.sections ? { sections: a.sections              } : {}),
+      ...(a.seo ? { seo: a.seo        } : {}),
+    };
+    try {
+      const saved = await ctx.store.updatePage(next, { writer: mcpWriter(ctx) });
+      const snapshot = await autoSnapshot(ctx, page.siteId, "update_page");
+      await notifyBuild(() =>
+        ctx.build?.pageChanged({
+          siteId: page.siteId,
+          page: saved,
+          tool: "update_page",
+          actor: ctx.principal.actor,
+        }),
+      );
+      return { page: saved, snapshot, ...unknownBlocksOf(ctx, { sections: saved.sections }) };
+    } catch (e) {
+      mapError(e);
+    }
+  },
+};
+
+const deletePageTool                 = {
+  name: "delete_page",
+  title: "Delete page",
+  description:
+    "Delete a page and remove it from navigation. Destructive: requires approval. Snapshots afterwards.",
+  inputSchema: obj({ siteId: id, pageId: id, rev: { type: "integer", minimum: 0 } }, [
+    "siteId",
+    "pageId",
+    "rev",
+  ]),
+  outputSchema: obj({ site: SITE, snapshot: SNAPSHOT }, ["site", "snapshot"]),
+  annotations: {
+    readOnlyHint: false,
+    destructiveHint: true,
+    idempotentHint: false,
+    openWorldHint: false,
+  },
+  scopes: ["content:write"],
+  approvalPrompt: async (a, ctx) => {
+    const page = await ctx.store.getPage(a.pageId          );
+    const menus = page
+      ? await menuItemsHiddenBy(ctx, page.siteId, { kind: "page", id: page.id })
+      : "";
+    return `Delete page "${page?.title ?? a.pageId}" (${page?.path ?? ""})? This removes it from navigation; earlier snapshots keep a copy.${menus}`;
+  },
+  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`);
+    try {
+      const updated = await ctx.store.deletePage(site, { ...page, rev: a.rev           });
+      const snapshot = await autoSnapshot(ctx, site.id, "delete_page");
+      return { site: updated, snapshot };
+    } catch (e) {
+      mapError(e);
+    }
+  },
+};
+
+/** list_sites … update_page, in `tools/list` order. */
+export function siteAndPageTools()                   {
+  return [listSitesTool, getSiteTool, listPagesTool, getPageTool, createPageTool, updatePageTool];
+}
+
+/** delete_page, listed after the surface tools. */
+export function pageRemovalTools()                   {
+  return [deletePageTool];
+}

package/dist/src/preview-doc.d.ts

@@ -0,0 +1,9 @@
+/** `previewDoc`: a page or article rendered as the site would show it (preview_page, render tools). */
+import { type ToolContext } from "./common.js";
+/** A page or article rendered as the site would show it, with its preview link (when there is one). */
+export declare function previewDoc(a: Record<string, unknown>, ctx: ToolContext): Promise<{
+    title: string;
+    path: string;
+    html: string;
+    url: string | null;
+}>;

package/dist/src/preview-doc.js

@@ -0,0 +1,56 @@
+/** `previewDoc`: a page or article rendered as the site would show it (preview_page, render tools). */
+
+import {
+  previewCollections,
+  renderEntryPreview,
+  renderPagePreview,
+} from "@cloudhal/astro-renderer/preview";
+import { mintPreviewToken, previewUrl, primaryOrigin } from "@cloudhal/core-ts";
+import { requireSite,                   ToolError } from "./common.js";
+import { assetsOf } from "./content-shared.js";
+
+/** A page or article rendered as the site would show it, with its preview link (when there is one). */
+export async function previewDoc(
+  a                         ,
+  ctx             ,
+)                                                                             {
+  const site = await requireSite(ctx, a.siteId          );
+  let doc                                               ;
+  if (a.entryId) {
+    const entry = await ctx.store.getContentEntry(a.entryId          );
+    if (!entry || entry.siteId !== site.id)
+      throw new ToolError("not_found", `entry ${a.entryId} not found`);
+    doc = renderEntryPreview(site, entry, {
+      assets: await assetsOf(ctx, "contentEntry", entry),
+      blocks: ctx.store.blocks,
+    });
+  } else if (a.pageId) {
+    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 collections = previewCollections(page.sections);
+    const entries = Object.fromEntries(
+      await Promise.all(
+        collections.map(async (c) => [c, await ctx.store.listContentEntries(site.id, c)]),
+      ),
+    );
+    doc = renderPagePreview(site, page, entries, {
+      assets: await assetsOf(ctx, "page", page),
+      blocks: ctx.store.blocks,
+    });
+  } else {
+    throw new ToolError("invalid", "pass pageId or entryId");
+  }
+  // Prefer a signed link to the deployed site (drafts visible); fall back to `cloudhal dev`.
+  if (ctx.previewSecret && primaryOrigin(site)) {
+    const token = await mintPreviewToken(ctx.previewSecret, {
+      site: site.id,
+      target: "live",
+    });
+    return { ...doc, url: previewUrl(site, doc.path, token) ?? null };
+  }
+  return {
+    ...doc,
+    url: ctx.previewBaseUrl ? new URL(doc.path, ctx.previewBaseUrl).toString() : null,
+  };
+}

package/dist/src/preview-view.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Cloudhal's MCP Apps View (RFC-0020 §6, phase 20f; the MCP Apps extension, 2026-01-26): hosts
+ * that render UI resources (Claude, ChatGPT, VS Code, …) show the page an agent is building right
+ * inside the conversation. `preview_page` and `patch_draft` point at it with
+ * `_meta.ui.resourceUri`; after `patch_draft` the View asks `preview_page` for the new version.
+ *
+ * Outward only: the View is our own constant HTML, never model output, and nothing from MCP Apps
+ * reaches the public site. The preview is Cloudhal's escaped preview document, shown in a shadow
+ * root (its styles stay inside; no script in it can run). It contacts no server of its own: tool
+ * calls go through the host, so the default MCP Apps CSP (no connections) is enough.
+ */
+/** The View's resource (MCP Apps: a `ui://` URI). */
+export declare const PREVIEW_UI_URI = "ui://cloudhal/preview";
+/** The MCP Apps HTML profile. */
+export declare const MCP_APP_MIME = "text/html;profile=mcp-app";
+/** The MCP Apps extension a host advertises in its capabilities. */
+export declare const MCP_APPS_EXTENSION = "io.modelcontextprotocol/ui";
+/** The View: one HTML document, its script inline (MCP Apps hosts serve the resource as is). */
+export declare const PREVIEW_VIEW_HTML: string;

package/dist/src/preview-view.js

@@ -0,0 +1,71 @@
+/**
+ * Cloudhal's MCP Apps View (RFC-0020 §6, phase 20f; the MCP Apps extension, 2026-01-26): hosts
+ * that render UI resources (Claude, ChatGPT, VS Code, …) show the page an agent is building right
+ * inside the conversation. `preview_page` and `patch_draft` point at it with
+ * `_meta.ui.resourceUri`; after `patch_draft` the View asks `preview_page` for the new version.
+ *
+ * Outward only: the View is our own constant HTML, never model output, and nothing from MCP Apps
+ * reaches the public site. The preview is Cloudhal's escaped preview document, shown in a shadow
+ * root (its styles stay inside; no script in it can run). It contacts no server of its own: tool
+ * calls go through the host, so the default MCP Apps CSP (no connections) is enough.
+ */
+
+/** The View's resource (MCP Apps: a `ui://` URI). */
+export const PREVIEW_UI_URI = "ui://cloudhal/preview";
+/** The MCP Apps HTML profile. */
+export const MCP_APP_MIME = "text/html;profile=mcp-app";
+/** The MCP Apps extension a host advertises in its capabilities. */
+export const MCP_APPS_EXTENSION = "io.modelcontextprotocol/ui";
+
+const script = String.raw`const out=document.getElementById("preview");const status=document.getElementById("status");
+const root=out.attachShadow({mode:"open"});
+let seq=0;const pending=new Map();
+const post=(m)=>window.parent.postMessage(Object.assign({jsonrpc:"2.0"},m),"*");
+const request=(method,params)=>new Promise((resolve,reject)=>{const id=++seq;pending.set(id,{resolve,reject});post({id,method,params});});
+const say=(t)=>{status.textContent=t;status.hidden=!t;};
+const size=()=>post({method:"ui/notifications/size-changed",params:{width:document.documentElement.scrollWidth,height:document.documentElement.scrollHeight}});
+new ResizeObserver(size).observe(document.body);
+const show=(html)=>{if(typeof html!=="string"||!html){say("No preview yet.");return;}
+const doc=new DOMParser().parseFromString(html,"text/html");
+const css=[...doc.querySelectorAll("style")].map((s)=>s.textContent||"").join("\n").replace(/:root/g,":host");
+for(const el of doc.querySelectorAll("script,iframe,object,embed,link,meta,base,form"))el.remove();
+const style=document.createElement("style");style.textContent=css+"\n:host{display:block}";
+const body=document.createElement("div");body.className="page";body.append(...doc.body.childNodes);
+root.replaceChildren(style,body);say("");size();};
+const fromResult=async(r)=>{if(!r)return;const sc=r.structuredContent||{};
+if(r.isError){const t=(r.content||[]).map((c)=>c&&c.text||"").join(" ");say(t.slice(0,300)||"The step was refused.");return;}
+if(typeof sc.html==="string"){show(sc.html);return;}
+const page=sc.page;if(page&&typeof page.id==="string"&&typeof page.siteId==="string"){say("Updating preview…");
+try{const p=await request("tools/call",{name:"preview_page",arguments:{siteId:page.siteId,pageId:page.id}});show(p&&p.structuredContent&&p.structuredContent.html);}catch(e){say("Preview unavailable.");}}};
+window.addEventListener("message",(e)=>{if(e.source!==window.parent)return;const m=e.data;if(!m||m.jsonrpc!=="2.0")return;
+if(m.id!==undefined&&!m.method){const p=pending.get(m.id);if(p){pending.delete(m.id);m.error?p.reject(m.error):p.resolve(m.result);}return;}
+switch(m.method){case"ui/notifications/tool-input":say("Working…");break;
+case"ui/notifications/tool-result":fromResult(m.params);break;
+case"ui/notifications/tool-cancelled":say("Cancelled.");break;
+case"ui/notifications/host-context-changed":{const t=m.params&&m.params.theme;if(t==="dark"||t==="light")document.documentElement.style.colorScheme=t;break;}
+case"ui/resource-teardown":post({id:m.id,result:{}});break;
+default:if(m.id!==undefined)post({id:m.id,error:{code:-32601,message:"method not found"}});}});
+request("ui/initialize",{protocolVersion:"2026-01-26",appCapabilities:{},clientInfo:{name:"cloudhal-preview",version:"1"}}).then(()=>post({method:"ui/notifications/initialized"})).catch(()=>say("This host does not run MCP Apps."));
+`;
+
+/** The View: one HTML document, its script inline (MCP Apps hosts serve the resource as is). */
+export const PREVIEW_VIEW_HTML = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Cloudhal preview</title>
+<style>
+:root{color-scheme:light dark;font:14px/1.5 system-ui,-apple-system,"Segoe UI",sans-serif}
+body{margin:0}
+#status{margin:0;padding:8px 12px;color:#59636e;font-size:13px}
+#preview{display:block;background:#fff;color-scheme:light}
+</style>
+</head>
+<body>
+<p id="status">Waiting for the agent…</p>
+<div id="preview"></div>
+<script>${script}</script>
+</body>
+</html>
+`;

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

@@ -0,0 +1,10 @@
+/** Snapshot, diff, preview, publish and rollback tools (approval-gated publishing). */
+import type { OwnOnlyResult } from "@cloudhal/agent-runtime";
+import { type ToolContext, type ToolDefinition } from "./common.js";
+/** create_snapshot … rollback, in `tools/list` order. */
+export declare function publishTools(): ToolDefinition[];
+/**
+ * Is publishing the current state own-only for the caller (RFC-0005 §4, I10)? Every publicly
+ * visible pending change must be an entry the caller's person owns.
+ */
+export declare function ownOnlyPublish(ctx: ToolContext, siteId: string): Promise<OwnOnlyResult>;