@caelo-cms/mcp-server 0.10.55 → 0.10.57

package/dist/tool-definitions.js

@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * The MCP tool definitions, input schemas and `instructions` of Caelo's two
+ * MCP surfaces — ONE copy, used by the stdio shims in this package and by
+ * the admin's remote Streamable HTTP endpoints (issue #806). A connecting
+ * agent must see the same names, schemas and instructions whichever way it
+ * reaches the site; editing them here changes both.
+ *
+ * Pure module (zod only): no transport, no filesystem, no network.
+ */
+import { z } from "zod";
+// ─── instructions (#552) ────────────────────────────────────────────────
+/**
+ * MCP `instructions` for the chat-scope server (#552), injected into the
+ * connecting agent's context so it uses caelo_chat as a conversation with
+ * the site's own agent rather than a one-shot command.
+ */
+export const CHAT_MCP_INSTRUCTIONS = [
+    "This server talks to a Caelo CMS site's own AI agent through caelo_chat; describe the outcome you want and the agent decides how to build it.",
+    "Pass the chatSessionId from a reply to continue the same conversation; omit it only to start a new one.",
+    "Changes land on that chat's preview branch; nothing reaches the live site until the operator publishes in the Caelo admin. Some actions wait for the operator's approval click there.",
+    "When a reply says the turn is waiting for the operator's approval, call caelo_await_approval with the chatSessionId: it waits for the decision and returns your turn's continuation. Never re-send the request; you cannot approve anything yourself.",
+].join("\n");
+/**
+ * MCP `instructions` for the admin server (#552). Clients such as Claude
+ * Code put this into the agent's context on connect, so a freshly
+ * connected agent knows the session protocol without the operator
+ * pasting anything: without a session every write fails, without the
+ * context it works without the site's rules and brand voice.
+ */
+export const ADMIN_MCP_INSTRUCTIONS = [
+    "This server edits a Caelo CMS site. Before any other caelo tool:",
+    "1. Call caelo_open_session once. It resumes the operator's most recent open session (pass newSession: true only when the operator asks for a fresh one; chatSessionId resumes a specific one). Every write lands in the site's shared draft (or the session's own experiment branch); you may stage finished work with stage_changes, but nothing reaches the live site until the operator clicks Publish live in the Caelo admin.",
+    "2. Call caelo_get_context once and follow it: it carries the site model, tool playbook, staging rules, site memory (brand voice, glossary) and the skills index.",
+    "3. Load every skill the context marks ALWAYS APPLIES with load_skill before the work it covers (e.g. before writing any visitor-facing copy).",
+    "Every tool in this list works over MCP, including approval-gated ones (marked APPROVAL-GATED — deploys, users/roles, languages/locales, plugin settings, bulk deletes …). Call them yourself: Caelo shows the operator an approval card in the Caelo admin (their Live Edit chat and the pending-approvals page), the call waits for Approve/Reject and returns the decision; if the wait times out, call caelo_await_approval with the proposalId. Tell the operator what you requested and that they approve the card in Caelo. Never ask the operator to paste a prompt into the Caelo admin chat or to do a step there that a tool here can do, and never re-propose a pending proposal.",
+    "After every stage_changes, call get_quality_audit (it waits for the result) and fix every open problem it names, then Stage and re-read until it passes: the target is 100 in every category and zero findings, and a score that dropped since the page's previous audit points at a recent change — check those changes first. Do not report open scores or findings to the operator as a result — only what you proved cannot be fixed in the site.",
+    "Tool errors name the next step to take; follow them instead of retrying unchanged.",
+].join("\n");
+// ─── caelo_upload_images (both surfaces) ────────────────────────────────
+/** Per-image size cap (matches the admin's chat-attachment cap). */
+export const MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+/** Uploaded media references accepted by caelo_chat; never accept object-store keys. */
+export const uploadedImageSchema = z
+    .object({
+    assetId: z.string().uuid(),
+    mime: z.enum(["image/png", "image/jpeg", "image/webp", "image/gif"]),
+    alt: z.string().max(2048).optional(),
+})
+    .strict();
+const imageInput = z
+    .object({
+    filePath: z.string().min(1).max(4096).optional(),
+    base64: z
+        .string()
+        .min(4)
+        .max(Math.ceil(MAX_IMAGE_BYTES / 3) * 4)
+        .regex(/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/)
+        .optional(),
+    filename: z.string().min(1).max(512).optional(),
+    alt: z.string().max(2048).optional(),
+    reference: z.boolean().optional(),
+})
+    .strict()
+    .refine((i) => (i.filePath === undefined) !== (i.base64 === undefined), "Supply exactly one of filePath or base64");
+/** A bounded batch; each file has its own success/error result for safe retries. */
+export const uploadImagesInput = z.object({ images: z.array(imageInput).min(1).max(4) }).strict();
+const UPLOAD_IMAGES_INPUT_SCHEMA = {
+    type: "object",
+    required: ["images"],
+    additionalProperties: false,
+    properties: {
+        images: {
+            type: "array",
+            minItems: 1,
+            maxItems: 4,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    filePath: {
+                        type: "string",
+                        description: "Path on the MCP server machine. Mutually exclusive with base64.",
+                    },
+                    base64: {
+                        type: "string",
+                        description: "Raw image bytes as base64. Mutually exclusive with filePath.",
+                    },
+                    filename: { type: "string", description: "Optional media filename." },
+                    alt: { type: "string", description: "Optional description of the image." },
+                    reference: {
+                        type: "boolean",
+                        description: "True for an image that only guides generation/editing; it is never placed on a page.",
+                    },
+                },
+                oneOf: [{ required: ["filePath"] }, { required: ["base64"] }],
+            },
+        },
+    },
+};
+const UPLOAD_IMAGES_COMMON = "Files become shared CMS media assets. Set reference: true for images that only guide image generation or editing " +
+    "(character sheets, style samples): they stay out of the page-image library and are never published. " +
+    "Returns attachments for caelo_chat " +
+    "or asset IDs for page tools. Uploading does not send a chat message or publish a page. " +
+    "Results are per file: retry only failures.";
+/** Exposed in both stdio catalogues, including chat-scoped connections. */
+export const UPLOAD_IMAGES_TOOL = {
+    name: "caelo_upload_images",
+    description: "Upload 1–4 PNG, JPEG, WebP or GIF images (5 MiB each) to the Caelo media library. " +
+        "Prefer filePath for files on the machine running this MCP server; otherwise supply raw base64 (no data URL). " +
+        `${UPLOAD_IMAGES_COMMON} Requires the token owner's current content.write permission.`,
+    inputSchema: UPLOAD_IMAGES_INPUT_SCHEMA,
+};
+/**
+ * The same tool over a remote connection (#806): identical name and schema;
+ * the description says what differs — the server runs in the Caelo admin,
+ * so it cannot read files on the agent's machine and only base64 works.
+ */
+export const REMOTE_UPLOAD_IMAGES_TOOL = {
+    name: UPLOAD_IMAGES_TOOL.name,
+    description: "Upload 1–4 PNG, JPEG, WebP or GIF images (5 MiB each) to the Caelo media library. " +
+        "Supply raw base64 (no data URL): this is a remote connection, so the server cannot read files on your machine and filePath is refused. " +
+        `${UPLOAD_IMAGES_COMMON} Requires your current content.write permission.`,
+    inputSchema: UPLOAD_IMAGES_INPUT_SCHEMA,
+};
+// ─── chat surface ───────────────────────────────────────────────────────
+export const caeloChatInputSchema = z
+    .object({
+    attachments: z.array(uploadedImageSchema).max(4).optional(),
+    message: z.string().min(1).max(50_000),
+    chatSessionId: z.string().uuid().optional(),
+    pageId: z.string().uuid().optional(),
+})
+    .strict();
+export const CAELO_CHAT_TOOL = {
+    name: "caelo_chat",
+    description: "Talk to your Caelo CMS install's AI agent. Same agent that powers the live-edit chat overlay — it can read pages, propose edits, queue Owner-approval proposals, summarise plugin data. Continues an existing chat session (when chatSessionId is supplied) or starts a fresh one. Returns the agent's reply text plus structured tool-call summaries.",
+    inputSchema: {
+        type: "object",
+        required: ["message"],
+        properties: {
+            attachments: {
+                type: "array",
+                maxItems: 4,
+                description: "Attachments returned by caelo_upload_images.",
+                items: z.toJSONSchema(uploadedImageSchema),
+            },
+            message: {
+                type: "string",
+                description: "What you want to say to the Caelo agent.",
+            },
+            chatSessionId: {
+                type: "string",
+                description: "Optional. Chat session UUID to continue. Omit to start a fresh page-unbound chat.",
+            },
+            pageId: {
+                type: "string",
+                description: "Optional. Bind a NEW chat to one page so the agent's page-context block is populated. Same shape as /edit?page=<id>.",
+            },
+        },
+    },
+};
+export const chatAwaitApprovalInput = z.object({ chatSessionId: z.string().uuid() }).strict();
+/** Issue #658 — keep waiting on the approval cards a caelo_chat turn paused on. */
+export const CHAT_AWAIT_APPROVAL_TOOL = {
+    name: "caelo_await_approval",
+    description: "Wait for the operator's Approve/Reject on the approval cards your caelo_chat turn paused on, then " +
+        "continue that turn and return its reply (the change applied, or the agent's reaction to a rejection). " +
+        "Use it when a caelo_chat reply says it is still waiting for approval. You cannot approve anything " +
+        "yourself — only the operator can, in the Caelo admin.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            chatSessionId: {
+                type: "string",
+                description: "The chatSessionId from the caelo_chat reply that is waiting.",
+            },
+        },
+        required: ["chatSessionId"],
+    },
+};
+// ─── admin (Power-MCP) surface ──────────────────────────────────────────
+export const openSessionInput = z
+    .object({
+    title: z.string().min(1).max(200).optional(),
+    pageId: z.string().uuid().optional(),
+    chatSessionId: z.string().uuid().optional(),
+    newSession: z.boolean().optional(),
+})
+    .strict();
+export const OPEN_SESSION_TOOL = {
+    name: "caelo_open_session",
+    description: "Open the Caelo work session your subsequent tool calls run in. Every write lands in the site's shared " +
+        "draft — invisible to the live site until it is staged and the operator clicks Publish live in the Caelo admin. " +
+        "Call this ONCE before any other caelo tool. By default it RESUMES the operator's own most recent open " +
+        "session (so earlier unstaged work continues in the same chat); pass newSession: true only when the " +
+        "operator wants a separate fresh session, or chatSessionId to resume a specific one. Optional pageId " +
+        "resumes (or opens) that page's session.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            title: { type: "string", description: "Session title shown in the Caelo admin chat list." },
+            pageId: { type: "string", description: "Optional page UUID to bind the session to." },
+            chatSessionId: {
+                type: "string",
+                description: "Resume this specific session instead of the most recent one.",
+            },
+            newSession: {
+                type: "boolean",
+                description: "Open a fresh session instead of resuming the most recent open one.",
+            },
+        },
+    },
+};
+export const adminAwaitApprovalInput = z.object({ proposalId: z.string().uuid() }).strict();
+/** Issue #658 — keep waiting for a decision after a gated call's wait timed out. */
+export const ADMIN_AWAIT_APPROVAL_TOOL = {
+    name: "caelo_await_approval",
+    description: "Wait for the operator's Approve/Reject on a proposal you queued with an approval-gated tool, and return " +
+        "the decision (applied / rejected with reason / …). Use it when a gated tool's result says it is still " +
+        "waiting. You cannot approve anything yourself — only the operator can, in the Caelo admin.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            proposalId: {
+                type: "string",
+                description: "The id from the gated tool's 'Queued proposal <id>' result.",
+            },
+        },
+        required: ["proposalId"],
+    },
+};
+export const GET_CONTEXT_TOOL = {
+    name: "caelo_get_context",
+    description: "Fetch the Caelo install's composed site context: how pages/modules/content instances fit together, " +
+        "the tool playbook, staging rules, site memory (brand voice, glossary) and the active skills index. " +
+        "Load this once before working; load individual skills on demand via the load_skill tool.",
+    inputSchema: { type: "object", properties: {} },
+};
+/**
+ * The chat server's whole tool list (stdio flavour). Static, so it also
+ * serves the credential-less listing MCP directories inspect (#841); the
+ * remote surface swaps in its own upload tool.
+ */
+export const CHAT_TOOLS = [UPLOAD_IMAGES_TOOL, CHAT_AWAIT_APPROVAL_TOOL, CAELO_CHAT_TOOL];
+/**
+ * The tools Power-MCP adds in front of the admin's catalogue (stdio
+ * flavour) — also the head of the credential-less listing (#841).
+ */
+export const ADMIN_LOCAL_TOOLS = [
+    UPLOAD_IMAGES_TOOL,
+    OPEN_SESSION_TOOL,
+    GET_CONTEXT_TOOL,
+    ADMIN_AWAIT_APPROVAL_TOOL,
+];
+//# sourceMappingURL=tool-definitions.js.map

package/dist/tool-definitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-definitions.js","sourceRoot":"","sources":["../src/tool-definitions.ts"],"names":[],"mappings":"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"}

package/dist/unconfigured.d.ts

@@ -0,0 +1,26 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+/**
+ * The Power-MCP tools shipped with this release. Throws when the
+ * snapshot is missing or malformed — a package without it is a broken
+ * release, not something to list around.
+ */
+export declare function loadPowerCatalogue(): Array<{
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}>;
+/** The two variables every mode needs to reach an admin install. */
+export type CredentialVar = "CAELO_ADMIN_URL" | "CAELO_MCP_TOKEN";
+/** Which credential variables are unset or empty in `env`. */
+export declare function missingCredentials(env: NodeJS.ProcessEnv): CredentialVar[];
+/** The error every tool call returns while credentials are missing. */
+export declare function describeMissingCredentials(mode: "chat" | "admin", missing: readonly CredentialVar[]): string;
+export interface StartUnconfiguredOpts {
+    readonly mode: "chat" | "admin";
+    readonly missing: readonly CredentialVar[];
+    /** Defaults to stdio; tests pass an in-memory transport. */
+    readonly transport?: Transport;
+}
+/** Serves the mode's tool list (see the file header) and fails every call. */
+export declare function startUnconfiguredServer(opts: StartUnconfiguredOpts): Promise<void>;
+//# sourceMappingURL=unconfigured.d.ts.map

package/dist/unconfigured.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"unconfigured.d.ts","sourceRoot":"","sources":["../src/unconfigured.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAwB/E;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,KAAK,CAAC;IAC1C,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACtC,CAAC,CAKD;AAED,oEAAoE;AACpE,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,iBAAiB,CAAC;AAElE,8DAA8D;AAC9D,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,aAAa,EAAE,CAE1E;AAED,uEAAuE;AACvE,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,GAAG,OAAO,EACtB,OAAO,EAAE,SAAS,aAAa,EAAE,GAChC,MAAM,CAQR;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,4DAA4D;IAC5D,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;CAChC;AAED,8EAA8E;AAC9E,wBAAsB,uBAAuB,CAAC,IAAI,EAAE,qBAAqB,GAAG,OAAO,CAAC,IAAI,CAAC,CAwBxF"}

package/dist/unconfigured.js

@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: MPL-2.0
+/**
+ * Issue #841 — the server answers `initialize` + `tools/list` without
+ * credentials, so MCP directories (Glama, the official registry's
+ * scanners, awesome-mcp-servers via Glama) can inspect it. They start
+ * the bin with no env and ask for the tool list; exiting there kept
+ * Caelo unlisted.
+ *
+ * This is not a fallback in the CLAUDE.md §2 sense: nothing degrades
+ * silently. The process says on stderr that it is unconfigured, and
+ * every tool call fails with the variables to set. The version
+ * handshake is skipped because there is no admin to ask — and it cannot
+ * move to the first call instead: it re-execs the whole process as the
+ * admin's release, which is only possible before the client's
+ * `initialize` has been answered.
+ *
+ * Power-MCP's real catalogue comes from the admin, so unconfigured it
+ * lists the snapshot shipped with this release (`power-catalogue.json`,
+ * written by scripts/power-catalogue.ts at release cut) — directories
+ * then show the tools an operator actually gets.
+ */
+import { readFileSync } from "node:fs";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { ADMIN_LOCAL_TOOLS, ADMIN_MCP_INSTRUCTIONS, CHAT_MCP_INSTRUCTIONS, CHAT_TOOLS, } from "./tool-definitions.js";
+import { ownVersion } from "./version-handshake.js";
+const powerCatalogueSchema = z.object({
+    version: z.string(),
+    tools: z
+        .array(z.object({
+        name: z.string(),
+        description: z.string(),
+        inputSchema: z.record(z.string(), z.unknown()),
+    }))
+        .min(1),
+});
+/**
+ * The Power-MCP tools shipped with this release. Throws when the
+ * snapshot is missing or malformed — a package without it is a broken
+ * release, not something to list around.
+ */
+export function loadPowerCatalogue() {
+    const raw = readFileSync(new URL("../power-catalogue.json", import.meta.url), "utf8");
+    return powerCatalogueSchema
+        .parse(JSON.parse(raw))
+        .tools.map(({ name, description, inputSchema }) => ({ name, description, inputSchema }));
+}
+/** Which credential variables are unset or empty in `env`. */
+export function missingCredentials(env) {
+    return ["CAELO_ADMIN_URL", "CAELO_MCP_TOKEN"].filter((name) => !env[name]);
+}
+/** The error every tool call returns while credentials are missing. */
+export function describeMissingCredentials(mode, missing) {
+    const scope = mode === "admin" ? "an ADMIN-scoped" : "a";
+    return (`This Caelo MCP server is not connected to a Caelo install: ${missing.join(" and ")} ` +
+        `${missing.length === 1 ? "is" : "are"} not set. Set CAELO_ADMIN_URL to your admin's https:// address ` +
+        `and CAELO_MCP_TOKEN to ${scope} token minted at /settings/mcp on that install, then restart the ` +
+        "MCP server. The operator has to do this in the MCP client's config; retrying the call will not help.");
+}
+/** Serves the mode's tool list (see the file header) and fails every call. */
+export async function startUnconfiguredServer(opts) {
+    const server = new Server({
+        name: opts.mode === "admin" ? "caelo-admin-mcp" : "caelo-mcp-server",
+        version: ownVersion(),
+    }, {
+        capabilities: { tools: {} },
+        instructions: opts.mode === "admin" ? ADMIN_MCP_INSTRUCTIONS : CHAT_MCP_INSTRUCTIONS,
+    });
+    const error = describeMissingCredentials(opts.mode, opts.missing);
+    const tools = opts.mode === "admin" ? [...ADMIN_LOCAL_TOOLS, ...loadPowerCatalogue()] : [...CHAT_TOOLS];
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+    server.setRequestHandler(CallToolRequestSchema, async () => ({
+        isError: true,
+        content: [{ type: "text", text: error }],
+    }));
+    // stderr: stdout is the stdio transport.
+    console.error(`caelo mcp: ${error}`);
+    await server.connect(opts.transport ?? new StdioServerTransport());
+}
+//# sourceMappingURL=unconfigured.js.map

package/dist/unconfigured.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"unconfigured.js","sourceRoot":"","sources":["../src/unconfigured.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@caelo-cms/mcp-server",
-  "version": "0.10.55",
+  "mcpName": "io.github.caelo-cms/caelo",
+  "version": "0.10.57",
   "private": false,
   "license": "MPL-2.0",
   "description": "MCP servers for Caelo CMS: `caelo_chat` (talk to Caelo's own AI) and the admin-scoped Power-MCP (the full chat-runner tool catalogue, driven by your own agent). Lets Claude Code (or any MCP-aware client) drive a Caelo install from outside the browser.",
@@ -23,10 +24,18 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./surfaces": {
+      "types": "./dist/surfaces/index.d.ts",
+      "bun": "./src/surfaces/index.ts",
+      "development": "./src/surfaces/index.ts",
+      "import": "./dist/surfaces/index.js",
+      "default": "./dist/surfaces/index.js"
     }
   },
   "files": [
     "dist/",
+    "power-catalogue.json",
     "README.md",
     "package.json"
   ],