@cloudhal/mcp-server 0.0.0-stage → 0.1.1

package/dist/src/changes.d.ts

@@ -0,0 +1,10 @@
+/** Human-readable change lines for approval prompts (publish). */
+import type { Site } from "@cloudhal/core-contracts";
+import type { SnapshotDiff } from "@cloudhal/core-ts";
+import { type ToolContext } from "./common.js";
+export declare const KIND_LABEL: Record<string, string>;
+/**
+ * One line per changed node for approval prompts, at most 8. Articles also show their assignment
+ * deltas (RFC-0002 §6.4): `~ article "…" (+tag ai, −tag llms, primary category → News)`.
+ */
+export declare function describeChanges(ctx: ToolContext, diff: SnapshotDiff, site?: Site): Promise<string[]>;

package/dist/src/changes.js

@@ -0,0 +1,112 @@
+/** Human-readable change lines for approval prompts (publish). */
+
+                                                                   
+                                                      
+import { termName } from "@cloudhal/core-ts";
+import { describeAsset } from "./asset-tools.js";
+import { quote,                  } from "./common.js";
+import { menuChangeSummary } from "./menu-tools.js";
+import { assignmentDeltas, describeDeltas, termLookup } from "./terms.js";
+
+export const KIND_LABEL                         = {
+  site: "site",
+  page: "page",
+  contentEntry: "article",
+  taxonomy: "taxonomy",
+  term: "term",
+  redirect: "redirect",
+  menu: "menu",
+  asset: "media",
+};
+
+/**
+ * One line per changed node for approval prompts, at most 8. Articles also show their assignment
+ * deltas (RFC-0002 §6.4): `~ article "…" (+tag ai, −tag llms, primary category → News)`.
+ */
+export async function describeChanges(
+  ctx             ,
+  diff              ,
+  site       ,
+)                    {
+  const locale = site?.defaultLocale;
+  const lookup = termLookup(ctx);
+  const title = async (ref                              ) => {
+    switch (ref.kind) {
+      case "page":
+        return (await ctx.store.getPage(ref.id))?.title;
+      case "contentEntry":
+        return (await ctx.store.getContentEntry(ref.id))?.title;
+      case "site":
+        return "site settings";
+      case "taxonomy": {
+        const t = await ctx.store.getTaxonomy(ref.id);
+        return t ? ((locale ? t.labels[locale]?.plural : undefined) ?? t.key) : undefined;
+      }
+      case "term": {
+        const t = await ctx.store.getTerm(ref.id);
+        return t ? termName(t, locale) : undefined;
+      }
+      case "redirect": {
+        const r = await ctx.store.getRedirect(ref.id);
+        return r ? `${r.from} → ${r.to}` : undefined;
+      }
+      case "menu":
+        return (await ctx.store.getMenu(ref.id))?.key;
+      default:
+        return undefined;
+    }
+  };
+  /** Media lines name the file, its type, size and the articles or pages using it (§6.2). */
+  const assetLine = async (sign        , ref                              ) => {
+    const asset = await ctx.store.getAsset(ref.id);
+    if (!asset) return undefined;
+    const usage = (await ctx.store.assetUsage(asset.siteId, [asset.id])).get(asset.id);
+    const first = usage?.refs[0];
+    let user                    ;
+    if (first?.nodeKind === "contentEntry")
+      user = (await ctx.store.getContentEntry(first.nodeId))?.title;
+    else if (first?.nodeKind === "page") user = (await ctx.store.getPage(first.nodeId))?.title;
+    const more = usage && usage.total > 1 ? ` and ${usage.total - 1} more` : "";
+    return `${sign} ${describeAsset(asset, locale)}${user ? `, used by "${quote(user)}"${more}` : ""}${asset.status === "retired" ? " (retired)" : ""}`;
+  };
+  const deltas = async (
+    ref                              ,
+    before                                ,
+  ) => {
+    if (ref.kind === "menu") return menuChangeSummary(ctx, ref, before);
+    if (ref.kind !== "contentEntry") return "";
+    const now = await ctx.store.getContentEntry(ref.id);
+    if (!now) return "";
+    const was = before ? await ctx.store.readSnapshotNode              (before) : undefined;
+    const text = await describeDeltas(assignmentDeltas(was?.terms, now.terms), lookup, locale);
+    return text ? ` (${text})` : "";
+  };
+  const label = (kind        ) => KIND_LABEL[kind] ?? kind;
+  const out           = [];
+  const groups   
+           
+                                                                                     
+      = [
+    ["+", diff.added.map((ref) => ({ ref }))],
+    ["~", diff.changed.map((c) => ({ ref: c.after, before: c.before }))],
+    ["−", diff.removed.map((ref) => ({ ref }))],
+  ];
+  for (const [sign, refs] of groups)
+    for (const { ref, before } of refs) {
+      if (out.length >= 8) {
+        out.push(`… and ${diff.added.length + diff.changed.length + diff.removed.length - 8} more`);
+        return out;
+      }
+      if (ref.kind === "asset" && sign !== "−") {
+        const line = await assetLine(sign, ref);
+        if (line) {
+          out.push(line);
+          continue;
+        }
+      }
+      const t = sign === "−" ? undefined : await title(ref);
+      const d = sign === "−" ? "" : await deltas(ref, before);
+      out.push(`${sign} ${label(ref.kind)} ${t ? `"${quote(t)}"` : ref.id}${d}`);
+    }
+  return out;
+}

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

@@ -0,0 +1,8 @@
+/**
+ * Site chrome over MCP (RFC-0025 §5): `get_chrome` reads the header, footer and brand with the
+ * form schemas and the menu keys they may name; `set_chrome` and `set_brand` change them and
+ * always wait for a person (the chrome is on every page). Both are checked against the contract
+ * and `checkChrome` before they are saved, and show on the site after a publish.
+ */
+import { type ToolDefinition } from "./common.js";
+export declare function chromeTools(): ToolDefinition[];

package/dist/src/chrome-tools.js

@@ -0,0 +1,207 @@
+/**
+ * Site chrome over MCP (RFC-0025 §5): `get_chrome` reads the header, footer and brand with the
+ * form schemas and the menu keys they may name; `set_chrome` and `set_brand` change them and
+ * always wait for a person (the chrome is on every page). Both are checked against the contract
+ * and `checkChrome` before they are saved, and show on the site after a publish.
+ */
+
+                                                     
+import {
+  brandFromForm,
+  brandToForm,
+  checkChrome,
+  chromeMenuKeys,
+  chromeSchemas,
+  logoAsset,
+  resolveChrome,
+                  
+} from "@cloudhal/core-ts/chrome";
+import { id, mapError, obj,                                        ToolError } from "./common.js";
+
+async function requireSite(ctx             , siteId        )                {
+  const site = await ctx.store.getSite(siteId);
+  if (!site) throw new ToolError("not_found", `site ${siteId} not found`);
+  return site;
+}
+
+/** `patch` onto `current`: a value replaces the part, null removes it. */
+function merge                  (current               , patch                         )    {
+  const out                          = { ...(current ?? {}) };
+  for (const [k, v] of Object.entries(patch))
+    if (v === null) delete out[k];
+    else out[k] = v;
+  return out     ;
+}
+
+const PART = {
+  anyOf: [{ type: "object" }, { type: "null" }],
+  description: "Fields to change (see get_chrome's schemas); null removes a field or the part",
+};
+
+export function chromeTools()                   {
+  return [
+    {
+      name: "get_chrome",
+      title: "Read the header and footer",
+      description:
+        "The site's header, footer and brand (RFC-0025): what is set, what pages show (the defaults filled in), the form schemas with every allowed value, and the menu keys the header and footer may name (primary is derived from pages when the site has no menu). Change them with set_chrome and set_brand; a page can hide its header or footer, or make the header transparent over its first band, with its own chrome field (update_page). A transparent header (overHero, or a page's chrome) only applies where the page opens with a Band painted inverse, brand, accent or gradient: it takes that surface's text color; elsewhere it stays solid. Below collapseAt the menus move behind a Menu button (mobileStyle: dropdown, drawer-start, drawer-end, fullscreen); render_page checks skip-link, landmarks, header-contrast and focus-obscured.",
+      inputSchema: obj({ siteId: id }, ["siteId"]),
+      outputSchema: obj(
+        {
+          chrome: { type: "object" },
+          brand: { type: "object" },
+          resolved: { type: "object" },
+          schemas: { type: "object" },
+          menus: { type: "array", items: { type: "string" } },
+          rev: { type: "integer" },
+        },
+        ["chrome", "brand", "resolved", "schemas", "menus", "rev"],
+      ),
+      annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      scopes: ["site:read"],
+      handler: async (a, ctx) => {
+        const site = await requireSite(ctx, a.siteId          );
+        const { header, footer, announcement, consent } = resolveChrome(site);
+        return {
+          chrome: site.chrome ?? {},
+          brand: brandToForm(site.brand),
+          resolved: { header, footer, announcement: announcement ?? null, consent },
+          schemas: chromeSchemas,
+          menus: chromeMenuKeys(await ctx.store.listMenus(site.id)),
+          rev: site.rev,
+        };
+      },
+    },
+    {
+      name: "set_chrome",
+      title: "Change the header and footer",
+      description:
+        "Change the site's header and footer (get_chrome lists the fields and allowed values). Each part's fields are merged onto the current ones; null removes a field, or the whole part (back to the default). Menus are named by key and must exist; a button action needs a label and a link; the copyright line knows {year} and {site}. Shows on every page after a publish. Always waits for a person.",
+      inputSchema: obj(
+        {
+          siteId: id,
+          rev: { type: "integer", minimum: 0, description: "The site's rev from get_chrome" },
+          header: PART,
+          footer: {
+            ...PART,
+            description:
+              "Fields to change; null removes a field or the part. footer.region is one surface section (kind surface, checked like a page's) above the columns, shown on every page (start its headings at level 2); null removes it",
+          },
+          announcement: {
+            ...PART,
+            description:
+              "The bar above the header: id (change it to show a new bar to readers who closed the old one), text, label + href, tone info|brand|warning, dismissible",
+          },
+          consent: {
+            ...PART,
+            description:
+              "The privacy bar: mode none|notice|choices, policy (the privacy page). Cloudhal sites are cookieless and embeds load on click, so most sites need none; a person decides",
+          },
+        },
+        ["siteId", "rev"],
+      ),
+      outputSchema: obj({ chrome: { type: "object" }, rev: { type: "integer" } }, [
+        "chrome",
+        "rev",
+      ]),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      scopes: ["site:write"],
+      requiresApproval: true,
+      approvalPrompt: async (a) => {
+        const parts = (["header", "footer", "announcement", "consent"]         ).filter(
+          (k) => a[k] !== undefined,
+        );
+        return `Change the site's ${parts.join(" and ") || "chrome"} (shown on every page)?`;
+      },
+      handler: async (a, ctx) => {
+        const site = await requireSite(ctx, a.siteId          );
+        const chrome             = { ...(site.chrome ?? {}) };
+        for (const part of ["header", "footer", "announcement", "consent"]         ) {
+          const v = a[part];
+          if (v === undefined) continue;
+          if (v === null) delete chrome[part];
+          else if (typeof v === "object" && !Array.isArray(v))
+            (chrome                           )[part] = merge(
+              chrome[part],
+              v                           ,
+            );
+          else throw new ToolError("invalid", `${part} must be an object or null`);
+        }
+        const issues = checkChrome(chrome, chromeMenuKeys(await ctx.store.listMenus(site.id)));
+        if (issues.length > 0)
+          throw new ToolError("invalid", issues.map((i) => `${i.path}: ${i.message}`).join("; "));
+        const { chrome: _old, ...rest } = site;
+        try {
+          const saved = await ctx.store.updateSite({
+            ...rest,
+            rev: a.rev          ,
+            ...(Object.keys(chrome).length > 0 ? { chrome } : {}),
+          });
+          return { chrome: saved.chrome ?? {}, rev: saved.rev };
+        } catch (e) {
+          mapError(e);
+        }
+      },
+    },
+    {
+      name: "set_brand",
+      title: "Change the logo and social links",
+      description:
+        "Change the site's brand (get_chrome lists the fields): logo and logoDark as an image asset of the site (asset:<id>, from list_assets or upload_asset; the site's name shows without one), logoHeight s|m|l, and social links (network and href, up to 8, shown in footers that ask for them). Fields are merged onto the current ones; null removes one. Always waits for a person.",
+      inputSchema: obj(
+        {
+          siteId: id,
+          rev: { type: "integer", minimum: 0, description: "The site's rev from get_chrome" },
+          brand: { type: "object", description: "Fields to change; null removes one" },
+        },
+        ["siteId", "rev", "brand"],
+      ),
+      outputSchema: obj({ brand: { type: "object" }, rev: { type: "integer" } }, ["brand", "rev"]),
+      annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+      },
+      scopes: ["site:write"],
+      requiresApproval: true,
+      approvalPrompt: async (a) => {
+        const keys = Object.keys((a.brand ?? {})                           );
+        return `Change the site's brand (${keys.join(", ") || "none"}, shown on every page)?`;
+      },
+      handler: async (a, ctx) => {
+        const site = await requireSite(ctx, a.siteId          );
+        const values = merge                         (
+          brandToForm(site.brand),
+          (a.brand ?? {})                           ,
+        );
+        const { brand, issues } = await brandFromForm(values, async (assetId) =>
+          logoAsset(await ctx.store.getAsset(assetId), site),
+        );
+        if (issues.length > 0)
+          throw new ToolError("invalid", issues.map((i) => `${i.path}: ${i.message}`).join("; "));
+        const { brand: _old, ...rest } = site;
+        try {
+          const saved = await ctx.store.updateSite({
+            ...rest,
+            rev: a.rev          ,
+            ...(brand ? { brand } : {}),
+          });
+          return { brand: brandToForm(saved.brand), rev: saved.rev };
+        } catch (e) {
+          mapError(e);
+        }
+      },
+    },
+  ];
+}

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

@@ -0,0 +1,9 @@
+import type { Actor } from "@cloudhal/core-contracts";
+import { type ToolDefinition } from "./common.js";
+/**
+ * Who a call that makes something public runs as (RFC-0007 §10.3): the person, never an agent.
+ * Studio's carry-out passes the approving person as the principal; a local agent's call runs as
+ * the developer who said yes in their own client.
+ */
+export declare const LOCAL_DEVELOPER: Actor;
+export declare function commentTools(): ToolDefinition[];