@cloudhal/mcp-server 0.0.0-stage → 0.1.1

package/dist/src/common.js

@@ -0,0 +1,488 @@
+/**
+ * What every tool module shares: the SDK-independent tool shape, the call context, `ToolError` and
+ * the mapping of store errors to it (stable codes, actionable text), and small schema/prompt helpers.
+ */
+import {
+                     
+                
+                 
+  checkEntryLimit,
+                
+                         
+                
+  OwnLimitError,
+                    
+                 
+             
+                       
+} from "@cloudhal/agent-runtime";
+                                                                    
+import { CommentsError } from "@cloudhal/comments";
+                                                                                          
+                                                                       
+import {
+  ConflictError,
+  FilterError,
+  InvariantError,
+  NotFoundError,
+  UniqueConstraintError,
+} from "@cloudhal/core-ts";
+                                                              
+                                                              
+import { ScheduleConflictError, ScheduleError } from "@cloudhal/schedules";
+                                                  
+                                                               
+import {                  ScheduleRequestError,                    } from "./schedules.js";
+
+                                                 
+
+                                 
+               
+                
+                      
+                          
+                           
+                               
+                  
+     
+                                                                           
+                                                                               
+     
+                                                                                            
+                             
+                                                            
+                                                                                        
+     
+                                                                                                    
+                                                                                                     
+                                                                                  
+     
+                                                                                
+     
+                                                                                              
+                                                                                              
+                                       
+     
+                                                      
+     
+                                                                                             
+                                                              
+     
+                                                                      
+                                                                          
+                          
+     
+                                                                                                 
+                                                                                              
+     
+                                                                                          
+     
+                                                                                                 
+                                                                                         
+     
+                                                                                   
+     
+                                                                                        
+                                                  
+     
+                               
+     
+                                                                                                 
+                                                                                                  
+                                                                                             
+                                                                                                   
+     
+                            
+     
+                                                                                                
+                                                       
+     
+                                           
+     
+                                                                                              
+                                                                                            
+     
+                                        
+                           
+                                        
+    
+                                                                                 
+     
+                                                                                                
+                                                                                            
+     
+                                                                         
+ 
+
+/** A content block of a tool result (the MCP shapes Cloudhal uses). */
+                         
+                                  
+                                                      
+
+/** Media settings of a deployment for the asset tools (RFC-0004 §5.6–§5.7). */
+                                   
+     
+                                                                                                     
+                                                                                                      
+     
+                                              
+                                                                                                     
+                                             
+                                                                                     
+                                               
+                                                                                                  
+                                        
+                                       
+ 
+
+/** What `render_page` renders with (RFC-0021 §4). */
+                             
+                                  
+                                                                                     
+                                               
+                                 
+                                          
+ 
+
+/**
+ * Watches drafts being built (RFC-0020 §6): Studio's Build view follows a page while agents
+ * change it. Called after a write succeeds, and when a build's operations are refused, so a
+ * person sees the agent correct itself. Awaited through `notifyBuild`, which bounds and swallows
+ * failures: watching never fails or slows a write noticeably.
+ */
+                                
+                       
+                            
+                        
+                          
+                          
+                                                                               
+                                                  
+                                                     
+                           
+                            
+                            
+                            
+                          
+                          
+                                        
+                           
+ 
+
+/** Tells the Build view, waiting at most 2 s; a failure is logged, never thrown (RFC-0020 §6). */
+export async function notifyBuild(report                            )                {
+  try {
+    const pending = report();
+    if (!pending) return;
+    let timer                                           ;
+    await Promise.race([
+      pending,
+      new Promise      ((resolve) => {
+        timer = setTimeout(resolve, 2_000);
+      }),
+    ]).finally(() => clearTimeout(timer));
+  } catch (e) {
+    console.warn(`cloudhal: build view not told: ${e instanceof Error ? e.message : String(e)}`);
+  }
+}
+
+                              
+                        
+                                                                   
+                                    
+                       
+                                                                                   
+                                        
+                                                    
+                                 
+                                                                                 
+                                      
+                                                                                                    
+                                     
+     
+                                                                                                
+                                                                                       
+     
+                                                                   
+                                                                 
+                                            
+                                                                                    
+                               
+                                                                    
+                                       
+                                                                                               
+                                           
+                                                                                               
+                                      
+     
+                                                                                                
+                                                             
+     
+                                  
+     
+                                                                                                   
+                                                
+     
+                                                                              
+                                                                                           
+                                        
+                                                                                                     
+                                  
+                                                                                       
+                               
+     
+                                                                                                 
+                                                                  
+     
+                                                                         
+                                                                                               
+                                    
+                                                                        
+                               
+ 
+
+/**
+ * Without a membership source an agent owns what it wrote itself (local stdio with own-limited
+ * scopes); people are themselves; the system owns nothing.
+ */
+export const ACTOR_OWNERSHIP                    = {
+  async personOf(actor) {
+    return actor.kind === "system" ? undefined : actor.id;
+  },
+};
+
+/** The person a call is measured against for "own" (RFC-0005 §4). */
+export function callerPerson(ctx             )         {
+  return ctx.principal.person?.id ?? ctx.principal.actor.id;
+}
+
+/** Checks an entry write against the call's own limit (I9); refusals are `denied`. */
+export async function entryLimitCheck(
+  ctx             ,
+  op                                ,
+  stored                          ,
+  next                                                                                 ,
+)                {
+  try {
+    await checkEntryLimit({
+      limit: ctx.limit,
+      op,
+      person: callerPerson(ctx),
+      owner: ctx.ownership ?? ACTOR_OWNERSHIP,
+      stored,
+      next,
+    });
+  } catch (e) {
+    if (e instanceof OwnLimitError) throw new ToolError("denied", e.message, { code: e.code });
+    throw e;
+  }
+}
+
+/** Stable error codes agents can branch on; the text says what to do next. */
+                           
+               
+              
+             
+            
+                       
+                 
+                      
+                  
+                    
+                    
+                        
+                           
+                       
+                                            
+                        
+                 
+             
+                       
+                     
+         
+                             
+                        
+                    
+                    
+
+/** What an approval request would change (RFC-0014 §5): a body, block by block. */
+                                  
+               
+                                                                                 
+                 
+                     
+                
+                 
+ 
+
+export class ToolError extends Error {
+                    name = "ToolError";
+           code               ;
+  /** Machine-readable context (suggestions, counts, ids). */
+           details                                   ;
+  constructor(code               , message        , details                          = {}) {
+    super(message);
+    this.code = code;
+    this.details = details;
+  }
+}
+
+export const id = { type: "string", pattern: "^[a-z]+_[A-Za-z0-9]{6,32}$" };
+export const SLUG_PATTERN = "^[a-z0-9]+(?:-[a-z0-9]+)*$";
+export const str = (desc        , extra             = {}) => ({
+  type: "string",
+  description: desc,
+  ...extra,
+});
+export const obj = (
+  properties            ,
+  required           = [],
+  extra             = {},
+)             => ({ type: "object", additionalProperties: false, properties, required, ...extra });
+export const strip = (schema         )             => {
+  const { $schema: _s, $id: _i, ...rest } = schema              ;
+  return rest;
+};
+
+/** Agent-controlled text in approval prompts is shortened and quoted so it cannot pose as UI. */
+export function quote(text        , max = 60)         {
+  const flat = text.replace(/\s+/g, " ").trim();
+  return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+
+export 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;
+}
+
+export async function autoSnapshot(
+  ctx             ,
+  siteId        ,
+  tool        ,
+  metadata                         ,
+)                    {
+  return ctx.store.createSnapshot(siteId, {
+    actor: ctx.principal.actor,
+    reason: "agentMutation",
+    label: `${tool} by ${ctx.principal.actor.name ?? ctx.principal.actor.id}`,
+    ...(metadata ? { metadata } : {}),
+  });
+}
+
+/** What to do next, per invariant (RFC-0002 §3). */
+function invariantHint(e                )                     {
+  const key = typeof e.details.taxonomy === "string" ? e.details.taxonomy : undefined;
+  switch (e.code) {
+    case "required_term":
+      return key
+        ? `this site requires a ${key} on review and published articles; call list_terms(taxonomy: "${key}") and set terms.${key}.primary`
+        : "merge the term into another one (merge_terms) or reassign those articles first";
+    case "primary_not_assigned":
+      return "the primary term must be one of the assigned terms; set it with terms.<taxonomy>.primary (it is added for you)";
+    case "invalid_assignment":
+      return "call list_taxonomies for the keys and collections, and list_terms or resolve_terms for the terms";
+    case "term_not_assignable":
+      return "the term was retired or merged; call resolve_terms with its name to find the term that replaced it";
+    case "too_many_terms":
+      return "list_taxonomies shows each taxonomy's maxPerEntry; drop some with terms.<taxonomy>.remove";
+    case "not_allowed":
+      return "ask a person to add or review it in Cloudhal Studio, or reuse an existing term (list_terms)";
+    case "slug_taken":
+      return "reuse that term (resolve_terms) or choose another slug";
+    case "invalid_labels":
+      return "names and synonyms must not repeat another term's name, synonym or slug; reuse that term or pick another name";
+    case "too_large":
+      return typeof e.details.limit === "number"
+        ? "use a smaller file; larger files are uploaded by a person in Studio"
+        : "split the operation, or ask a person for the staged job";
+    case "unknown_asset":
+      return "call list_assets for this site's files, or add one with upload_asset or fetch_asset_url";
+    case "retired_asset":
+      return "pick another file (list_assets), or ask a person to restore this one";
+    case "in_use":
+      return "remove those uses first (update_entry, update_page), or retire the file instead";
+    case "fetch_blocked":
+      return "use a public https address of the file itself; internal hosts, IP addresses and redirects into them are refused";
+    case "reserved_path":
+      return "paths under /media/<16 hex digits>/ belong to media files";
+    case "retry":
+      return "call the tool again in a few seconds";
+    case "locale_not_enabled":
+      return "use one of the site's locales (get_site), or ask a person to add the language";
+    case "translation_exists":
+      return "that language already has a version in the group; update it instead";
+    case "review_required":
+      return "save it as a draft; a person reviews machine translations of this collection before they publish";
+    case "host_taken":
+      return "pick another hostname; this one already serves another site of the installation";
+    case "invalid_surface":
+      return "fix the parts named by the JSON Pointers in details.issues; get_catalog lists every component, its props and the binding rules";
+    default:
+      return undefined;
+  }
+}
+
+/** Store errors as `ToolError`s with stable codes; anything else is returned unchanged. */
+export function toToolError(e         )          {
+  if (e instanceof ToolError) return e;
+  // Schedule errors (RFC-0008): a refused input keeps its code in the text and the details.
+  if (e instanceof ScheduleError)
+    return new ToolError(
+      e.code === "not_found" ? "not_found" : "invalid",
+      `${e.code}: ${e.message}`,
+      {
+        code: e.code,
+      },
+    );
+  if (e instanceof ScheduleConflictError)
+    return new ToolError(
+      "conflict",
+      `${e.message}; read it again (get_release) and pass the current rev`,
+      { kind: e.kind, id: e.id },
+    );
+  if (e instanceof ScheduleRequestError) return new ToolError("invalid", e.message);
+  // Comment store errors (RFC-0007): stable codes, the store's message says what to fix.
+  if (e instanceof CommentsError)
+    return new ToolError(
+      e.code === "not_found"
+        ? "not_found"
+        : e.code === "conflict"
+          ? "conflict"
+          : e.code === "forbidden"
+            ? "denied"
+            : "invalid",
+      e.message,
+    );
+  if (e instanceof ConflictError) return new ToolError("conflict", e.message);
+  if (e instanceof NotFoundError) return new ToolError("not_found", e.message);
+  if (e instanceof UniqueConstraintError)
+    return new ToolError(
+      "conflict",
+      e.kind === "contentEntry"
+        ? `an article with this collection, locale and slug already exists (${e.key}); choose another slug`
+        : `${e.kind} "${e.key}" already exists`,
+    );
+  if (e instanceof InvariantError) {
+    const hint = invariantHint(e);
+    return new ToolError(e.code, hint ? `${e.message}. ${hint}` : e.message, { ...e.details });
+  }
+  if (e instanceof FilterError) {
+    if (e.code === "unknown_term")
+      return new ToolError(
+        "unknown_term",
+        `${e.message}; call list_terms for the vocabulary (old slugs still match)`,
+        { unknown: e.unknown },
+      );
+    if (e.code === "unknown_taxonomy") return new ToolError("unknown_taxonomy", e.message);
+    return new ToolError(
+      "invalid_filter",
+      `${e.message} (grammar: clauses joined by "+", e.g. "category:news+tag:[ai,llm]+-tag:sponsored"; "primary:category:x"; "category:x>*" for sub-categories)`,
+    );
+  }
+  return e;
+}
+
+export function mapError(e         )        {
+  throw toToolError(e);
+}

package/dist/src/content-shared.d.ts

@@ -0,0 +1,50 @@
+/** Schemas and helpers shared by the site, page, surface, entry and publish tool families. */
+import type { Actor, Asset, ContentEntry, Page, Site } from "@cloudhal/core-contracts";
+import type { BlockWriter } from "@cloudhal/core-ts";
+import { unknownBlockTypes } from "@cloudhal/core-ts";
+import type { BlockRegistry } from "@cloudhal/core-ts/blocks";
+import { type Catalog } from "@cloudhal/core-ts/surfaces";
+import { type JsonSchema, type ToolContext } from "./common.js";
+/** The catalog surfaces on this site are written against: the theme's name and its block types. */
+export declare function siteCatalog(site: Site, ctx: {
+    store: {
+        blocks: BlockRegistry;
+    };
+}): Catalog;
+/** Body blocks an agent changes carry it and the MCP channel (RFC-0014 §3). */
+export declare function mcpWriter(ctx: {
+    principal: {
+        actor: Actor;
+    };
+}): BlockWriter;
+export declare const SITE: JsonSchema;
+export declare const PAGE: JsonSchema;
+export declare const ENTRY: JsonSchema;
+export declare const SNAPSHOT: JsonSchema;
+export declare const SECTION: JsonSchema;
+export type Seo = NonNullable<Page["seo"]>;
+/** An article's cover image by asset (RFC-0004): `{ assetId, alt? }`; the store fills in the rest. */
+export declare const COVER_INPUT: JsonSchema;
+/** The tool input for a page's sections. */
+export declare const sectionInput: {
+    type: string;
+    items: JsonSchema;
+    description: string;
+};
+/** The media-library assets a page or article refers to, by id, so previews render them (RFC-0004). */
+export declare function assetsOf(ctx: ToolContext, kind: "page" | "contentEntry", node: Page | ContentEntry): Promise<Map<string, Asset>>;
+export declare function coverImage(input: unknown): NonNullable<ContentEntry["coverImage"]>;
+/** Reported when a write keeps blocks of types this deployment does not know (RFC-0015 §7). */
+export declare const unknownBlocks: {
+    type: string;
+    items: {
+        type: string;
+    };
+    description: string;
+};
+export declare function unknownBlocksOf(ctx: ToolContext, content: Parameters<typeof unknownBlockTypes>[1]): {
+    unknownBlocks?: string[];
+};
+export declare const entryMarkdown: (entry: ContentEntry) => string | undefined;
+/** Agents write markdown only; raw HTML sections are for people in Studio (security review H3). */
+export declare function assertNoHtmlSections(sections: unknown): void;

package/dist/src/content-shared.js

@@ -0,0 +1,102 @@
+/** Schemas and helpers shared by the site, page, surface, entry and publish tool families. */
+
+                                                                                       
+import {
+  ContentEntrySchema,
+  PageSchema,
+  SectionSchema,
+  SiteSchema,
+  SnapshotSchema,
+} from "@cloudhal/core-contracts";
+                                                     
+import { unknownBlockTypes } from "@cloudhal/core-ts";
+                                                              
+import { assetRefsOf } from "@cloudhal/core-ts/media";
+import {               createCatalog } from "@cloudhal/core-ts/surfaces";
+import { id,                  str, strip,                   ToolError } from "./common.js";
+
+/** The catalog surfaces on this site are written against: the theme's name and its block types. */
+export function siteCatalog(site      , ctx                                      )          {
+  return createCatalog({ name: site.theme.name, blocks: ctx.store.blocks });
+}
+
+/** Body blocks an agent changes carry it and the MCP channel (RFC-0014 §3). */
+export function mcpWriter(ctx                                 )              {
+  return { actor: ctx.principal.actor, via: "mcp" };
+}
+
+export const SITE = strip(SiteSchema);
+export const PAGE = strip(PageSchema);
+export const ENTRY = strip(ContentEntrySchema);
+export const SNAPSHOT = strip(SnapshotSchema);
+export const SECTION = strip(SectionSchema);
+                                           
+
+/** An article's cover image by asset (RFC-0004): `{ assetId, alt? }`; the store fills in the rest. */
+export const COVER_INPUT             = {
+  type: "object",
+  additionalProperties: false,
+  required: ["assetId"],
+  description:
+    "Cover image from the media library (list_assets, upload_asset). alt overrides the file's own alt text for this article.",
+  properties: { assetId: id, alt: str("Alt text for this use", { maxLength: 500 }) },
+};
+
+/** The tool input for a page's sections. */
+export const sectionInput = {
+  type: "array",
+  items: SECTION,
+  description:
+    'Ordered sections; keep existing ids when editing. Typed blocks (a callout, a button, an FAQ, the theme\'s own) are sections with kind "component", a type and its props: list_block_types.',
+};
+
+/** The media-library assets a page or article refers to, by id, so previews render them (RFC-0004). */
+export async function assetsOf(
+  ctx             ,
+  kind                         ,
+  node                     ,
+)                              {
+  const ids = [...new Set(assetRefsOf(kind, node).map((r) => r.assetId))];
+  const found = await Promise.all(ids.map((id) => ctx.store.getAsset(id)));
+  return new Map(
+    found
+      .filter((a)             => a !== undefined && a.siteId === node.siteId)
+      .map((a) => [a.id, a]),
+  );
+}
+
+export function coverImage(input         )                                          {
+  const c = input                                     ;
+  // `src` is written by the store from the asset (invariant 8).
+  return { assetId: c.assetId, alt: c.alt ?? "", src: `asset:${c.assetId}` };
+}
+
+/** Reported when a write keeps blocks of types this deployment does not know (RFC-0015 §7). */
+export const unknownBlocks = {
+  type: "array",
+  items: { type: "string" },
+  description:
+    "Block types used here that this site does not know (another theme's?): kept as written, not shown on the site. list_block_types shows the known ones.",
+};
+
+export function unknownBlocksOf(
+  ctx             ,
+  content                                         ,
+)                               {
+  const names = unknownBlockTypes(ctx.store.blocks, content);
+  return names.length ? { unknownBlocks: names } : {};
+}
+
+export const entryMarkdown = (entry              ) =>
+  entry.body.format === "markdown" ? entry.body.value : undefined;
+
+/** Agents write markdown only; raw HTML sections are for people in Studio (security review H3). */
+export function assertNoHtmlSections(sections         )       {
+  if (!Array.isArray(sections)) return;
+  for (const s of sections                                                     )
+    if (s?.kind === "richText" && s.format !== "markdown")
+      throw new ToolError(
+        "invalid",
+        `section ${s.id ?? ""} uses format "${s.format}"; agents may only write markdown sections`,
+      );
+}

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

@@ -0,0 +1,9 @@
+/**
+ * DESIGN.md over MCP (RFC-0021 §2): `get_design` gives an agent everything it needs before it
+ * designs (the theme's and the site's design rules, the design settings, the catalog's names and
+ * Cloudhal's guidance) in one call; `set_design` changes the site's rules and always waits for a
+ * person. The site's rules are owner-written data, delimited in the text result: they shape design
+ * choices and never grant permissions.
+ */
+import { type ToolDefinition } from "./common.js";
+export declare function designTools(): ToolDefinition[];