@cloudhal/mcp-server 0.0.0-stage → 0.1.1

package/dist/src/schema-transforms.d.ts

@@ -0,0 +1,14 @@
+/** Schema rewrites applied to every tool's input and output schema. */
+import type { JsonSchema } from "./common.js";
+/**
+ * Contract schemas reference `#/$defs/...` relative to their own root. Once embedded inside a tool
+ * schema those pointers must resolve from the tool schema's root instead, so nested `$defs` are
+ * hoisted there (names are shared and identical across contracts).
+ */
+export declare function hoistDefs(schema: JsonSchema): JsonSchema;
+/**
+ * Inputs may name an image by asset alone (`{ assetId, alt? }`, RFC-0004 §2.2): the store writes
+ * `src`, `width` and `height`. So an input ImageRef needs `src` or `assetId`, and `alt` may be left
+ * out; stored documents keep the contract's strict shape.
+ */
+export declare function relaxImageRefs(schema: JsonSchema): JsonSchema;

package/dist/src/schema-transforms.js

@@ -0,0 +1,50 @@
+/** Schema rewrites applied to every tool's input and output schema. */
+
+                                              
+
+/**
+ * Contract schemas reference `#/$defs/...` relative to their own root. Once embedded inside a tool
+ * schema those pointers must resolve from the tool schema's root instead, so nested `$defs` are
+ * hoisted there (names are shared and identical across contracts).
+ */
+export function hoistDefs(schema            )             {
+  const defs                          = {};
+  const walk = (node         , isRoot         )          => {
+    if (Array.isArray(node)) return node.map((n) => walk(n, false));
+    if (!node || typeof node !== "object") return node;
+    const out                          = {};
+    for (const [k, v] of Object.entries(node                           )) {
+      if (k === "$defs" && !isRoot) {
+        for (const [name, def] of Object.entries(v                           ))
+          defs[name] = walk(def, false);
+        continue;
+      }
+      out[k] = walk(v, false);
+    }
+    return out;
+  };
+  const root = walk(schema, true)              ;
+  const own = (root.$defs                                       ) ?? {};
+  return Object.keys(defs).length || Object.keys(own).length
+    ? { ...root, $defs: { ...defs, ...own } }
+    : root;
+}
+
+/**
+ * Inputs may name an image by asset alone (`{ assetId, alt? }`, RFC-0004 §2.2): the store writes
+ * `src`, `width` and `height`. So an input ImageRef needs `src` or `assetId`, and `alt` may be left
+ * out; stored documents keep the contract's strict shape.
+ */
+export function relaxImageRefs(schema            )             {
+  const defs = schema.$defs                                          ;
+  const ref = defs?.ImageRef;
+  if (!ref) return schema;
+  const { required: _r, ...rest } = ref;
+  return {
+    ...schema,
+    $defs: {
+      ...defs,
+      ImageRef: { ...rest, anyOf: [{ required: ["src"] }, { required: ["assetId"] }] },
+    },
+  };
+}

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

@@ -0,0 +1,2 @@
+import { type ToolDefinition } from "./common.js";
+export declare function searchTools(): ToolDefinition[];

package/dist/src/search-tools.js

@@ -0,0 +1,112 @@
+/**
+ * `search_site` (RFC-0029 §8): find a site's articles, pages, terms, media, menu items and redirects
+ * by words, drafts included, the way Studio's palette does; or, with `published`, what readers
+ * find on `/search` (the site's search provider: published, inside time gates).
+ */
+import {
+  MARK_CLOSE,
+  MARK_OPEN,
+  SEARCH_KINDS,
+                  
+  SITE_SEARCH_KINDS,
+  SITE_SEARCH_LIMIT_MAX,
+                      
+  searchSiteNodes,
+} from "@cloudhal/core-ts";
+import { id, mapError, obj, requireSite, str,                     } from "./common.js";
+
+const HIT = obj(
+  {
+    kind: { type: "string" },
+    id: { type: "string" },
+    title: { type: "string" },
+    detail: { type: "string" },
+    context: { type: "string" },
+    status: { type: "string" },
+    locale: { type: "string" },
+    ref: { type: "string" },
+    href: { type: "string" },
+    snippet: { type: "string" },
+  },
+  ["kind", "title"],
+);
+
+const plain = (snippet        ) => snippet.replaceAll(MARK_OPEN, "").replaceAll(MARK_CLOSE, "");
+
+const searchSiteTool                 = {
+  name: "search_site",
+  title: "Search the site",
+  description:
+    "Find nodes by words instead of listing everything. By default searches what you edit, drafts included: articles (kind entry), pages, terms, media (asset), menu items (menu: `id` is the menu, `ref` the item) and redirects; every word must start a word of the title, slug, path, labels or alt text; up to `limit` hits per kind. With `published: true`, returns what readers find on /search instead (published articles, pages, terms and authors, with snippets), in the site's default locale.",
+  inputSchema: obj(
+    {
+      siteId: id,
+      query: str("Words to find", { minLength: 1, maxLength: 200 }),
+      kinds: {
+        type: "array",
+        description:
+          "Only these kinds. Editing view: entry, page, term, asset, menu, redirect. Published view: article, page, term, author.",
+        items: { type: "string", enum: [...new Set([...SITE_SEARCH_KINDS, ...SEARCH_KINDS])] },
+        minItems: 1,
+        uniqueItems: true,
+      },
+      published: { type: "boolean", description: "Search what readers see (default false)" },
+      limit: {
+        type: "integer",
+        description: "Hits per kind (editing view) or in all (published view)",
+        minimum: 1,
+        maximum: SITE_SEARCH_LIMIT_MAX,
+      },
+    },
+    ["siteId", "query"],
+  ),
+  outputSchema: obj({ query: { type: "string" }, hits: { type: "array", items: HIT } }, [
+    "query",
+    "hits",
+  ]),
+  annotations: {
+    readOnlyHint: true,
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  scopes: ["content:read"],
+  handler: async (a, ctx) => {
+    const site = await requireSite(ctx, a.siteId          );
+    const query = a.query          ;
+    const kinds = a.kinds                        ;
+    const limit = a.limit                      ;
+    try {
+      if (a.published === true) {
+        const r = await ctx.store.search(site.id, query, {
+          locale: site.defaultLocale,
+          now: (ctx.now?.() ?? new Date()).getTime(),
+          perPage: limit ?? SITE_SEARCH_LIMIT_MAX,
+          ...(kinds ? { kinds: kinds                 } : {}),
+          ...(site.publishedSnapshotId ? { snapshotId: site.publishedSnapshotId } : {}),
+        });
+        return {
+          query: r.query,
+          hits: r.hits.map((h) => ({
+            kind: h.kind ?? "article",
+            id: h.nodeId,
+            title: h.title,
+            href: h.href,
+            ...(h.context ? { context: h.context } : {}),
+            ...(h.snippet ? { snippet: plain(h.snippet) } : {}),
+          })),
+        };
+      }
+      return await searchSiteNodes(ctx.store, site.id, query, {
+        ...(kinds ? { kinds: kinds                     } : {}),
+        ...(limit !== undefined ? { limit } : {}),
+      });
+    } catch (e) {
+      mapError(e);
+    }
+  },
+};
+
+export function searchTools()                   {
+  return [searchSiteTool];
+}

package/dist/src/server-approvals.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The approval half of a tool call: the answer a call carries (elicitation round 2, a redeemed
+ * `approvalId`, a `confirmToken`) checked against its binding, and the request when policy wants a
+ * person (Studio for agents and role limits, otherwise the client's elicitation).
+ */
+import { type Principal } from "@cloudhal/agent-runtime";
+import { type CallToolResult, type InputRequiredResult, type ServerContext } from "@modelcontextprotocol/server";
+import type { RunContext } from "./schedules.js";
+import type { CallRuntime } from "./server-call.js";
+import type { runTool, ToolDefinition } from "./tools.js";
+export interface ApprovalState {
+    tool: string;
+    /** sha256 of the canonical arguments, so an approval cannot be replayed for other arguments. */
+    args: string;
+    /** The site's content digest when the person was asked; a later change voids the approval. */
+    state: string;
+}
+export declare function errorResult(text: string): CallToolResult;
+/** What an approval is tied to: the tool, the arguments and the state of what the call acts on. */
+export interface Binding {
+    argsHash: string;
+    /** The current state, or `null` when it cannot be read (nothing may be filed or matched then). */
+    stateHash: () => Promise<string | null>;
+    matches: (state: ApprovalState | undefined) => Promise<boolean>;
+    unbound: () => CallToolResult;
+}
+/** One call in flight. */
+export interface Call {
+    rt: CallRuntime;
+    def: ToolDefinition;
+    args: Record<string, unknown>;
+    ctx: ServerContext;
+    principal: Principal;
+    run: RunContext | undefined;
+    siteId: string | undefined;
+    binding: Binding;
+}
+/** `confirmed`: a person said yes to this call; `approved`: someone who could make it decided it. */
+export interface Clearance {
+    confirmed: boolean;
+    approved: boolean;
+}
+/** The approval the call carries, checked against its binding. */
+export declare function clearance(call: Call, approvalId: unknown, confirmToken: unknown): Promise<Clearance | CallToolResult> | Clearance;
+export type Outcome = Awaited<ReturnType<typeof runTool>>;
+type ApprovalDecision = Extract<Outcome["decision"], {
+    kind: "approval-required";
+}>;
+/** Policy wants a person: file the request in Studio, or ask in the client. */
+export declare function approvalRequired(call: Call, outcome: Outcome, decision: ApprovalDecision): Promise<CallToolResult | InputRequiredResult> | CallToolResult;
+export {};

package/dist/src/server-approvals.js

@@ -0,0 +1,273 @@
+/**
+ * The approval half of a tool call: the answer a call carries (elicitation round 2, a redeemed
+ * `approvalId`, a `confirmToken`) checked against its binding, and the request when policy wants a
+ * person (Studio for agents and role limits, otherwise the client's elicitation).
+ */
+import {                     effectiveMode,                } from "@cloudhal/agent-runtime";
+import {
+  acceptedContent,
+                      
+  CLIENT_CAPABILITIES_META_KEY,
+                          
+                               
+                           
+  inputRequired,
+  inputResponse,
+                     
+} from "@modelcontextprotocol/server";
+                                                 
+                                                    
+                                                          
+
+                                
+               
+                                                                                                  
+               
+                                                                                                
+                
+ 
+
+const REDEEM_MESSAGES                         = {
+  "not-found": "unknown approvalId",
+  pending: "still waiting for a person to approve it in Studio — try again later",
+  denied: "a person denied this request; nothing changed",
+  consumed: "this approval was already used; ask again",
+  expired: "this approval expired; ask again",
+  mismatch: "this approval was for a different call",
+  "state-changed":
+    "the site changed after the approval was requested; ask again so the person sees the current changes",
+};
+
+/** Where an agent sees what a carried-out request did. */
+function outcomeTools(tool        )         {
+  return tool.includes("comment")
+    ? "list_comments or get_comment_thread"
+    : "get_release or list_schedule";
+}
+
+const APPROVAL_SCHEMA                                             = {
+  type: "object",
+  properties: {
+    confirm: {
+      type: "boolean",
+      title: "Approve",
+      description: "true to let the action run, false to stop here",
+    },
+  },
+  required: ["confirm"],
+};
+
+export function errorResult(text        )                 {
+  return { content: [{ type: "text", text }], isError: true };
+}
+
+/** What an approval is tied to: the tool, the arguments and the state of what the call acts on. */
+                          
+                   
+                                                                                                    
+                                          
+                                                                  
+                                
+ 
+
+/** One call in flight. */
+                       
+                  
+                      
+                                
+                     
+                       
+                              
+                             
+                   
+ 
+
+/** `confirmed`: a person said yes to this call; `approved`: someone who could make it decided it. */
+                            
+                     
+                    
+ 
+
+/** The approval the call carries, checked against its binding. */
+export function clearance(
+  call      ,
+  approvalId         ,
+  confirmToken         ,
+)                                                  {
+  const answer = inputResponse(call.ctx.mcpReq.inputResponses, "approval");
+  if (answer.kind !== "missing") return elicitedClearance(call, answer);
+  if (approvalId !== undefined) return redeemedClearance(call, approvalId);
+  if (confirmToken !== undefined) return tokenClearance(call, confirmToken);
+  return { confirmed: false, approved: false };
+}
+
+/** Round 2 of an approval: the client echoed our elicitation answer + signed state. */
+async function elicitedClearance(
+  call      ,
+  answer                                  ,
+)                                      {
+  const { def, args, ctx, principal } = call;
+  if (answer.kind !== "elicit") return errorResult("unexpected input response kind");
+  if (!(await call.binding.matches(ctx.mcpReq.requestState               ())))
+    return errorResult(
+      "approval state does not match this call (different arguments, or the site changed meanwhile); start over",
+    );
+  const content = acceptedContent                       (ctx.mcpReq.inputResponses, "approval");
+  if (answer.action !== "accept" || content?.confirm !== true) {
+    await call.rt.options.audit?.record({
+      at: new Date().toISOString(),
+      actor: principal.actor,
+      siteId: call.siteId,
+      tool: def.name,
+      decision: "deny",
+      reason: answer.action === "accept" ? "approval refused" : `approval ${answer.action}d`,
+      skill: principal.skill?.name,
+      input: def.auditArgs ? def.auditArgs(args) : args,
+      outcome: "error",
+    });
+    return errorResult(`${def.name} was not approved; nothing changed.`);
+  }
+  return { confirmed: true, approved: false };
+}
+
+/** A redeemed out-of-band approval (ADR-0014): someone who could make the full call decided it. */
+async function redeemedClearance(
+  call      ,
+  approvalId         ,
+)                                      {
+  const { def } = call;
+  const approvals = call.rt.options.approvals;
+  if (!approvals) return errorResult("approvalId is not accepted on this server");
+  if (typeof approvalId !== "string") return errorResult("approvalId must be a string");
+  // Comment and release tools are carried out by the person who approves them
+  // (RFC-0007 §10.3, RFC-0008 §10.4).
+  if (def.carryOutOnApproval) {
+    const request = await approvals.get(approvalId);
+    return errorResult(
+      request?.status === "consumed" && request.tool === def.name
+        ? `approval ${approvalId}: already carried out — the person who approved it ran ${def.name} at once. Check the result with ${outcomeTools(def.name)}.`
+        : `approval ${approvalId}: ${request?.status === "denied" ? REDEEM_MESSAGES.denied : `${def.name} is carried out in Cloudhal Studio when a person approves it; there is nothing to redeem`}`,
+    );
+  }
+  const current = await call.binding.stateHash();
+  if (current === null) return call.binding.unbound();
+  const redeemed = await approvals.redeem(approvalId, {
+    tool: def.name,
+    argsHash: call.binding.argsHash,
+    actorId: call.principal.actor.id,
+    stateHash: current,
+  });
+  if (!redeemed.ok)
+    return errorResult(`approval ${approvalId}: ${REDEEM_MESSAGES[redeemed.reason]}`);
+  return { confirmed: true, approved: true };
+}
+
+/** The local fallback: a signed token the server handed out with the approval question. */
+async function tokenClearance(
+  call      ,
+  confirmToken         ,
+)                                      {
+  if (!call.rt.fallback) return errorResult("confirmToken is not accepted on this server");
+  if (typeof confirmToken !== "string") return errorResult("confirmToken must be a string");
+  let state                           ;
+  try {
+    state = await call.rt.codec.verify(confirmToken, call.ctx);
+  } catch {
+    state = undefined;
+  }
+  if (!(await call.binding.matches(state)))
+    return errorResult("invalid, expired or mismatched confirmToken; ask for approval again");
+  return { confirmed: true, approved: false };
+}
+
+                                                          
+                                                                                    
+
+/** Policy wants a person: file the request in Studio, or ask in the client. */
+export function approvalRequired(
+  call      ,
+  outcome         ,
+  decision                  ,
+)                                                                 {
+  const approvals = call.rt.options.approvals;
+  const prompt = outcome.approvalPrompt ?? decision.reason;
+  // A call beyond the caller's role (cause `role`) is decided by someone else, never in the
+  // caller's own client (RFC-0005 §10.2).
+  const role = decision.cause === "role";
+  if (role && !approvals)
+    return errorResult(`denied: ${decision.reason}. Ask someone whose role allows it (an Editor).`);
+  // Agents with their own credentials never answer for a person: the request waits in Studio.
+  if (approvals && (call.principal.actor.kind === "agent" || role))
+    return requestInStudio(call, { approvals, outcome, decision, prompt });
+  return askInClient(call, prompt);
+}
+
+async function requestInStudio(
+  call      ,
+  input                                                                                            ,
+)                          {
+  const { def, args, principal, run } = call;
+  const { approvals, outcome, decision, prompt } = input;
+  const current = await call.binding.stateHash();
+  if (current === null) return call.binding.unbound();
+  const pending = await approvals.request({
+    siteId: call.siteId,
+    tool: def.name,
+    argsHash: call.binding.argsHash,
+    input: args,
+    actor: principal.actor,
+    prompt,
+    stateHash: current,
+    mode: effectiveMode(principal),
+    cause: decision.cause,
+    ...(outcome.autoCheck ? { autoCheck: outcome.autoCheck } : {}),
+    ...(run ? { runId: run.run.id } : {}),
+  });
+  if (def.carryOutOnApproval)
+    return errorResult(
+      `approval pending: ${prompt}\nA person must approve request ${pending.id} in Cloudhal Studio (site → Activity → Approvals); approving it carries the call out at once, as long as what it acts on has not changed meanwhile. Do not call ${def.name} again for it; check the outcome later with ${outcomeTools(def.name)}. It expires ${pending.expiresAt}.\napprovalId: ${pending.id}`,
+    );
+  // A person's own request is carried out when someone approves it (RFC-0005 §6).
+  if (principal.actor.kind !== "agent")
+    return errorResult(
+      `approval pending: ${decision.reason}\nRequest ${pending.id} waits in Cloudhal Studio (site → Activity → Approvals) for someone whose role allows it; approving it runs ${def.name} for you. It expires ${pending.expiresAt}.\napprovalId: ${pending.id}`,
+    );
+  return errorResult(
+    `approval pending: ${prompt}\nA person must approve request ${pending.id} in Cloudhal Studio (site → Activity → Approvals). After it is approved, call ${def.name} again with the same arguments plus approvalId "${pending.id}". It expires ${pending.expiresAt}.\napprovalId: ${pending.id}`,
+  );
+}
+
+/** Ask the person in their MCP client (elicitation), or hand out a confirmToken (local fallback). */
+async function askInClient(
+  call      ,
+  prompt        ,
+)                                                {
+  const { rt, def, ctx } = call;
+  const current = await call.binding.stateHash();
+  if (current === null) return call.binding.unbound();
+  const state = await rt.codec.mint(
+    { tool: def.name, args: call.binding.argsHash, state: current },
+    ctx,
+  );
+  // 2026-07-28 requests carry the client's capabilities in their _meta envelope (stateless
+  // HTTP); 2025-era connections declared them at initialize.
+  const envelope = ctx.mcpReq.envelope                                       ;
+  const caps =
+    (envelope?.[CLIENT_CAPABILITIES_META_KEY]                                  ) ??
+    rt.server.server.getClientCapabilities();
+  if (caps?.elicitation) {
+    return inputRequired({
+      inputRequests: {
+        approval: inputRequired.elicit({ message: prompt, requestedSchema: APPROVAL_SCHEMA }),
+      },
+      requestState: state,
+    });
+  }
+  if (!rt.fallback)
+    return errorResult(
+      `approval required: ${prompt}\nThis client cannot collect approval (no elicitation support).`,
+    );
+  return errorResult(
+    `approval required: ${prompt}\nAsk the person. If (and only if) they approve, call ${def.name} again with the same arguments plus confirmToken: "${state}" (valid ${Math.round((rt.options.approvalTtlSeconds ?? 600) / 60)} minutes).`,
+  );
+}

package/dist/src/server-call.d.ts

@@ -0,0 +1,28 @@
+/**
+ * One tool call through the MCP layer, in order: the declared skill, the automation run, the
+ * approval answer the call carries (elicitation round 2, a redeemed `approvalId` or a
+ * `confirmToken`), `runTool`, and when policy wants a person, the approval request (Studio, or
+ * the client's elicitation).
+ *
+ * Approvals are bound to the tool, the canonical arguments and the state of what the call acts on
+ * (`Binding`); a state that cannot be computed is `null` and fails closed.
+ */
+import { type LoadedSkill, type PolicyEngine } from "@cloudhal/agent-runtime";
+import type { CallToolResult, createRequestStateCodec, InputRequiredResult, McpServer, ServerContext } from "@modelcontextprotocol/server";
+import type { CloudhalMcpOptions } from "./server.js";
+import { type ApprovalState } from "./server-approvals.js";
+import { type ToolDefinition } from "./tools.js";
+export declare const SKILL_META_KEY = "cloudhal.skill";
+export type ApprovalCodec = ReturnType<typeof createRequestStateCodec<ApprovalState>>;
+/** What every call of one server instance shares. */
+export interface CallRuntime {
+    options: CloudhalMcpOptions;
+    policy: PolicyEngine;
+    skills: Map<string, LoadedSkill>;
+    codec: ApprovalCodec;
+    /** Hand out `confirmToken`s to clients that cannot elicit (local only). */
+    fallback: boolean;
+    server: McpServer;
+}
+/** The `registerTool` callback for `def`. */
+export declare function handleToolCall(rt: CallRuntime, def: ToolDefinition, rawArgs: unknown, ctx: ServerContext): Promise<CallToolResult | InputRequiredResult>;