@caelo-cms/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# `@caelo-cms/mcp-server`
+
+MCP server exposing your Caelo CMS install's chat-runner as a single
+`caelo_chat` tool. Lets Claude Code (or any MCP-aware client) drive
+your install — read pages, propose edits, queue Owner-approval
+proposals, summarise plugin data — without opening the browser.
+
+This package is a thin shim. Every `caelo_chat` invocation becomes one
+HTTPS POST against your admin install's `/api/mcp/chat` endpoint, which
+dispatches into the same chat-runner that powers the live-edit overlay.
+
+## Install
+
+In your Caelo install:
+
+1. Visit `/security/mcp` as an Owner.
+2. Click **New token**, give it a name (`claude-code`, `laptop`, `ci`,
+   etc.), optionally set an AI-spend cap (microcents), and copy the
+   bearer that's shown ONCE.
+3. The page renders the exact `claude mcp add` snippet — copy + run it.
+
+Manual setup if your client isn't Claude Code:
+
+```bash
+# stdio server invoked by your MCP-aware client
+bunx @caelo-cms/mcp-server
+```
+
+with these env vars set:
+
+| Variable | Required | Notes |
+|---|---|---|
+| `CAELO_ADMIN_URL` | yes | `https://admin.example.com` — point at your install. |
+| `CAELO_MCP_TOKEN` | yes | Bearer minted at `/security/mcp`. |
+
+## The `caelo_chat` tool
+
+| Field | Type | Notes |
+|---|---|---|
+| `message` | string, required | What you want to say to the Caelo agent. |
+| `chatSessionId` | uuid, optional | Continue an existing chat session. |
+| `pageId` | uuid, optional | Bind a NEW chat to one page so the agent's page-context block populates. |
+
+Output: assistant reply text + a JSON block with `chatSessionId` (for
+the next call), `requestId` (click through to
+`/security/audit/<requestId>` for the full audit trail), the structured
+tool-call summaries the agent dispatched, the per-turn cost in
+microcents, and a `pendingProposals` count so the agent can surface
+"you have N things waiting for Owner approval".
+
+## Why a single tool?
+
+Browse / publish / propose actions happen *through* the chat — "which
+pages exist?" → the Caelo agent calls `pages.list` internally → answers
+in text. Same auth surface, same RLS scoping, same audit trail, same
+propose-execute Owner gate as the browser. The remote agent talks to a
+human-equivalent agent, not to a programmatic API.
+
+## License
+
+MPL-2.0.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@caelo-cms/mcp-server",
+  "version": "0.1.0",
+  "private": false,
+  "license": "MPL-2.0",
+  "description": "MCP server exposing the Caelo CMS chat-runner as a `caelo_chat` tool. Lets Claude Code (or any MCP-aware client) drive a Caelo install from outside the browser.",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "caelo-mcp-server": "./src/index.ts"
+  },
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc -b"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "zod": "4.3.6"
+  }
+}

package/src/chat-bridge.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * HTTP bridge — translates a `caelo_chat` MCP call into a single POST
+ * against the admin install's `/api/mcp/chat` endpoint. The endpoint
+ * dispatches `mcp.send_chat` (system-only op) which resolves the
+ * bearer to a Caelo actor and drives `runChatTurn`.
+ *
+ * 30-second client-side timeout — chat-runner turns longer than that
+ * are likely stuck (the runner has its own provider-call timeouts).
+ * MCP clients see a clean error instead of a hung connection.
+ */
+
+export interface SendChatOpts {
+  readonly adminUrl: string;
+  readonly token: string;
+  readonly message: string;
+  readonly chatSessionId?: string;
+  readonly pageId?: string;
+}
+
+export interface SendChatResult {
+  readonly chatSessionId: string;
+  readonly requestId: string;
+  readonly assistant: string;
+  readonly toolCalls: ReadonlyArray<{ name: string; summary: string; succeeded: boolean }>;
+  readonly pendingProposals: number;
+  readonly costMicrocents: number;
+}
+
+const TIMEOUT_MS = 30_000;
+
+export async function sendChat(opts: SendChatOpts): Promise<SendChatResult> {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+  try {
+    const url = `${opts.adminUrl.replace(/\/+$/, "")}/api/mcp/chat`;
+    const res = await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "x-caelo-mcp-token": opts.token,
+      },
+      body: JSON.stringify({
+        message: opts.message,
+        chatSessionId: opts.chatSessionId,
+        pageId: opts.pageId,
+      }),
+      signal: controller.signal,
+    });
+    if (!res.ok) {
+      const body = await safeText(res);
+      throw new Error(`HTTP ${res.status}: ${body || res.statusText}`);
+    }
+    const json = (await res.json()) as SendChatResult;
+    return json;
+  } catch (e) {
+    if (e instanceof Error && e.name === "AbortError") {
+      throw new Error(`timeout after ${TIMEOUT_MS / 1000}s`);
+    }
+    throw e;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function safeText(res: Response): Promise<string> {
+  try {
+    return (await res.text()).slice(0, 500);
+  } catch {
+    return "";
+  }
+}

package/src/index.ts

@@ -0,0 +1,33 @@
+#!/usr/bin/env bun
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * @caelo-cms/mcp-server — entrypoint.
+ *
+ * Reads `CAELO_ADMIN_URL` + `CAELO_MCP_TOKEN` from env, builds an MCP
+ * server exposing exactly one tool (`caelo_chat`), and listens over
+ * stdio (Claude Code's default invocation pattern).
+ *
+ * Bridge model: this process is a thin shim. Every `caelo_chat` call
+ * becomes a single HTTP POST against the admin install's
+ * `/api/mcp/chat` endpoint, which dispatches into the chat-runner with
+ * the resolved actor identity. The MCP server NEVER touches the
+ * database directly — it just translates between MCP semantics and
+ * the admin's HTTP surface.
+ */
+
+import { startMcpServer } from "./server.js";
+
+const adminUrl = process.env["CAELO_ADMIN_URL"];
+const token = process.env["CAELO_MCP_TOKEN"];
+
+if (!adminUrl) {
+  console.error("CAELO_ADMIN_URL not set — point me at your admin install (e.g. https://admin.example.com)");
+  process.exit(2);
+}
+if (!token) {
+  console.error("CAELO_MCP_TOKEN not set — mint one at /security/mcp on your admin install");
+  process.exit(2);
+}
+
+await startMcpServer({ adminUrl, token });

package/src/server.ts

@@ -0,0 +1,135 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * MCP server construction. Registers exactly one tool — `caelo_chat` —
+ * and binds it to a stdio transport. The single-tool design is
+ * deliberate: the remote agent talks to Caelo's chat-runner the same
+ * way a human in the browser does. Browse / publish / propose actions
+ * happen through the chat ("which pages exist?" → agent calls
+ * pages.list internally → text response). Same auth surface, same
+ * actor scope, same audit trail.
+ */
+
+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 { sendChat } from "./chat-bridge.js";
+
+export interface StartOpts {
+  readonly adminUrl: string;
+  readonly token: string;
+}
+
+const caeloChatInputSchema = z
+  .object({
+    message: z.string().min(1).max(50_000),
+    chatSessionId: z.string().uuid().optional(),
+    pageId: z.string().uuid().optional(),
+  })
+  .strict();
+
+export async function startMcpServer(opts: StartOpts): Promise<void> {
+  const server = new Server(
+    {
+      name: "caelo-mcp-server",
+      version: "0.1.0",
+    },
+    {
+      capabilities: { tools: {} },
+    },
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        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: {
+            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>.",
+            },
+          },
+        },
+      },
+    ],
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (req) => {
+    if (req.params.name !== "caelo_chat") {
+      return {
+        isError: true,
+        content: [
+          { type: "text", text: `unknown tool: ${req.params.name}` },
+        ],
+      };
+    }
+    const parsed = caeloChatInputSchema.safeParse(req.params.arguments ?? {});
+    if (!parsed.success) {
+      return {
+        isError: true,
+        content: [
+          { type: "text", text: `invalid arguments: ${parsed.error.message}` },
+        ],
+      };
+    }
+    try {
+      const result = await sendChat({
+        adminUrl: opts.adminUrl,
+        token: opts.token,
+        message: parsed.data.message,
+        ...(parsed.data.chatSessionId ? { chatSessionId: parsed.data.chatSessionId } : {}),
+        ...(parsed.data.pageId ? { pageId: parsed.data.pageId } : {}),
+      });
+      // Two content blocks: human-readable assistant text + a JSON
+      // structured block the calling agent can parse for the
+      // requestId, tool calls, cost, pending proposals.
+      return {
+        content: [
+          { type: "text", text: result.assistant },
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                chatSessionId: result.chatSessionId,
+                requestId: result.requestId,
+                toolCalls: result.toolCalls,
+                pendingProposals: result.pendingProposals,
+                costMicrocents: result.costMicrocents,
+              },
+              null,
+              2,
+            ),
+          },
+        ],
+      };
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return {
+        isError: true,
+        content: [{ type: "text", text: `caelo_chat failed: ${msg}` }],
+      };
+    }
+  });
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "./src",
+    "outDir": "./dist",
+    "noEmit": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["**/*.test.ts", "**/dist", "**/node_modules"]
+}