@avocadostudio-ai/mcp-server 0.2.0

package/dist/http.js

@@ -0,0 +1,132 @@
+#!/usr/bin/env node
+/**
+ * Avocado Studio MCP server — streamable HTTP transport.
+ *
+ * Run this when you want the MCP server accessible as a URL (Claude Desktop's
+ * "Add custom connector" flow, remote deployments). The stdio entry at
+ * src/index.ts remains the right choice for local Claude Code installs.
+ *
+ * Env vars (in addition to the stdio ones):
+ *   AVOCADO_MCP_BEARER_TOKEN  required — clients must send Authorization: Bearer <token>
+ *   AVOCADO_MCP_PORT          optional — defaults to 4300
+ */
+import { createServer } from "node:http";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { loadConfig } from "./config.js";
+import { OrchestratorClient } from "./orchestrator-client.js";
+import { registerAllTools } from "./tools/index.js";
+import { createCapabilityGate } from "./capabilities.js";
+import { checkBearer } from "./http-auth.js";
+import { SERVER_VERSION } from "./version.js";
+const config = loadConfig();
+const bearerToken = process.env.AVOCADO_MCP_BEARER_TOKEN?.trim();
+if (!bearerToken) {
+    console.error("AVOCADO_MCP_BEARER_TOKEN is required for HTTP mode. Generate one with `openssl rand -hex 32`.");
+    process.exit(1);
+}
+const port = Number(process.env.AVOCADO_MCP_PORT ?? "4300");
+if (!Number.isFinite(port) || port <= 0) {
+    console.error(`AVOCADO_MCP_PORT must be a positive integer, got: ${process.env.AVOCADO_MCP_PORT}`);
+    process.exit(1);
+}
+const orchestratorClient = new OrchestratorClient(config);
+/**
+ * Build a fresh McpServer for each request. Per the SDK's stateless example,
+ * the server+transport pair is disposed when the HTTP response closes. Registering
+ * tools is cheap (pure wiring) — the heavy side effect (block schema registration)
+ * ran once at module load.
+ */
+/*
+ * One gate for the process, not one per request: the capability answer is a
+ * property of the site, and re-probing on every request would put a network
+ * call in front of every tool list.
+ */
+const capabilityGate = createCapabilityGate(orchestratorClient);
+void capabilityGate.refresh();
+function buildServer() {
+    const server = new McpServer({ name: "avocado-studio", version: SERVER_VERSION });
+    registerAllTools(server, orchestratorClient, capabilityGate);
+    return server;
+}
+async function readBody(req) {
+    const chunks = [];
+    for await (const chunk of req)
+        chunks.push(chunk);
+    if (chunks.length === 0)
+        return undefined;
+    const text = Buffer.concat(chunks).toString("utf8");
+    if (!text)
+        return undefined;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function sendJson(res, status, body) {
+    res.statusCode = status;
+    res.setHeader("content-type", "application/json");
+    res.end(JSON.stringify(body));
+}
+const httpServer = createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    // Health probe — no auth, useful for load balancers and Claude Desktop connectivity tests.
+    if (req.method === "GET" && url.pathname === "/healthz") {
+        return sendJson(res, 200, { ok: true, name: "avocado-studio", siteId: config.siteId });
+    }
+    if (url.pathname !== "/mcp") {
+        return sendJson(res, 404, { error: "not found" });
+    }
+    const auth = checkBearer(req, bearerToken);
+    if (!auth.ok) {
+        res.setHeader("www-authenticate", "Bearer");
+        return sendJson(res, auth.status, { error: auth.message });
+    }
+    // Stateless mode only supports POST (initialize + JSON-RPC calls in one shot).
+    // Reject GET/DELETE explicitly so clients fall back to the POST-only path.
+    if (req.method !== "POST") {
+        res.setHeader("allow", "POST");
+        return sendJson(res, 405, {
+            jsonrpc: "2.0",
+            error: { code: -32000, message: "Method not allowed. Stateless MCP transport uses POST only." },
+            id: null,
+        });
+    }
+    const server = buildServer();
+    const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined });
+    res.on("close", () => {
+        transport.close().catch(() => { });
+        server.close().catch(() => { });
+    });
+    try {
+        const body = await readBody(req);
+        await server.connect(transport);
+        await transport.handleRequest(req, res, body);
+    }
+    catch (err) {
+        if (!res.headersSent) {
+            sendJson(res, 500, {
+                jsonrpc: "2.0",
+                error: { code: -32603, message: err instanceof Error ? err.message : String(err) },
+                id: null,
+            });
+        }
+        else {
+            try {
+                res.end();
+            }
+            catch { /* already closed */ }
+        }
+    }
+});
+httpServer.listen(port, () => {
+    console.error(`avocado-studio MCP server listening on http://localhost:${port}/mcp (siteId: ${config.siteId})`);
+});
+const shutdown = () => {
+    httpServer.close(() => process.exit(0));
+    setTimeout(() => process.exit(1), 5000).unref();
+};
+process.on("SIGINT", shutdown);
+process.on("SIGTERM", shutdown);

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Avocado Studio MCP server — stdio transport.
+ *
+ * Spawned by an MCP host (Claude Desktop, Claude Code, etc.) with env vars:
+ *   ORCHESTRATOR_URL   — e.g. http://localhost:4200 or https://orchestrator.example.com
+ *   AVOCADO_SESSION    — session key to scope drafts (defaults to "dev")
+ *   AVOCADO_SITE_ID    — required; which site this install edits
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+/**
+ * Avocado Studio MCP server — stdio transport.
+ *
+ * Spawned by an MCP host (Claude Desktop, Claude Code, etc.) with env vars:
+ *   ORCHESTRATOR_URL   — e.g. http://localhost:4200 or https://orchestrator.example.com
+ *   AVOCADO_SESSION    — session key to scope drafts (defaults to "dev")
+ *   AVOCADO_SITE_ID    — required; which site this install edits
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig } from "./config.js";
+import { OrchestratorClient } from "./orchestrator-client.js";
+import { registerAllTools } from "./tools/index.js";
+import { createCapabilityGate } from "./capabilities.js";
+import { SERVER_VERSION } from "./version.js";
+const config = loadConfig();
+const client = new OrchestratorClient(config);
+const server = new McpServer({ name: "avocado-studio", version: SERVER_VERSION });
+const gate = createCapabilityGate(client);
+registerAllTools(server, client, gate);
+const transport = new StdioServerTransport();
+await server.connect(transport);
+/*
+ * Ask what this site can honour only AFTER the transport is connected, and
+ * never await it here. Registration cannot wait on the network: a probe in
+ * front of `connect` delays the `initialize` handshake by however long the
+ * site takes to answer, and makes the server fail to start when the site is
+ * down. Tools that turn out to be unavailable are disabled once the answer
+ * arrives, and the SDK emits `tools/list_changed`.
+ */
+void gate.refresh();

package/dist/orchestrator-client.d.ts

@@ -0,0 +1,93 @@
+import type { McpConfig } from "./config.ts";
+import type { Operation, PageDoc, SiteConfig } from "@avocadostudio-ai/shared";
+/**
+ * Thin typed wrapper around the orchestrator HTTP API.
+ *
+ * All tools go through this client so:
+ *   - the orchestrator remains the single source of truth for validation,
+ *     persistence, undo stacks, and demo-mode gating;
+ *   - tests can stub a single `fetch` surface instead of reimplementing state.
+ */
+export type Fetcher = typeof fetch;
+export type RequestOptions = {
+    query?: Record<string, string | number | undefined>;
+    body?: unknown;
+    /** FormData body — bypasses JSON serialization, no content-type header set. */
+    formData?: FormData;
+    /** Bearer token for endpoints that require auth (e.g. /publish). */
+    bearer?: string;
+    /** Abort the fetch when this signal fires — lets callers enforce per-request timeouts. */
+    signal?: AbortSignal;
+};
+export declare class OrchestratorClient {
+    readonly config: McpConfig;
+    private readonly fetcher;
+    constructor(config: McpConfig, fetcher?: Fetcher);
+    /** Low-level request. Exposed so tools can hit arbitrary endpoints without growing per-method wrappers for every call. */
+    request<T>(method: "GET" | "POST" | "PUT" | "DELETE", path: string, opts?: RequestOptions): Promise<T>;
+    /** Convenience: session + siteId pre-filled for endpoints that take them as query params. */
+    scoped(extra?: Record<string, string | number | undefined>): Record<string, string | number | undefined>;
+    /** Convenience: session + siteId pre-filled for endpoints that take them in the body. */
+    scopedBody<T extends Record<string, unknown>>(extra: T): T & {
+        session: string;
+        siteId: string;
+    };
+    getPage(slug: string): Promise<PageDoc>;
+    listSlugs(): Promise<PagesIndexResponse>;
+    getSiteConfig(): Promise<SiteConfig>;
+    applyOps(ops: Operation[]): Promise<ApplyOpsResponse>;
+    whoami(): Promise<WhoamiResponse>;
+    listSessions(): Promise<ListSessionsResponse>;
+}
+export type PagesIndexEntry = {
+    slug: string;
+    title: string;
+    updatedAt: string;
+    blockCount: number;
+};
+export type PagesIndexResponse = {
+    slugs: string[];
+    pages: PagesIndexEntry[];
+};
+export type SessionSummary = {
+    sessionKey: string;
+    session: string;
+    siteId: string;
+    version: number;
+    draftPageCount: number;
+    lastMutatedAt: string | null;
+};
+export type WhoamiResponse = SessionSummary & {
+    /** Null unless this is the demo site — the orchestrator does not track what is live elsewhere. */
+    publishedPageCount: number | null;
+    /** Present only when the count is null, explaining where the live side actually lives. */
+    publishedPageCountNote?: string;
+    orchestratorUrl: string;
+};
+export type ListSessionsResponse = {
+    sessions: SessionSummary[];
+    /** Bundled demo pages, not any site's published count. */
+    demoPublishedPageCount: number;
+};
+export type ApplyOpsResponse = {
+    status: string;
+    summary: string;
+    /**
+     * One human-readable line per operation ("Updated Hero heading on /about").
+     * Was `unknown[]` while both transports hardcoded it empty.
+     */
+    changes: string[];
+    mentionedSlugs: string[];
+    previewVersion: number;
+    focusBlockId?: string;
+    updatedSlug?: string;
+    /**
+     * Only present when the batch contained at least one duplicate_page op.
+     * Each entry maps the new page's slug to a { oldBlockId: newBlockId } table
+     * so callers can target the copied blocks without a follow-up get-page.
+     */
+    duplicatedPages?: Array<{
+        slug: string;
+        blockIdMap: Record<string, string>;
+    }>;
+};

package/dist/orchestrator-client.js

@@ -0,0 +1,64 @@
+export class OrchestratorClient {
+    config;
+    fetcher;
+    constructor(config, fetcher = fetch) {
+        this.config = config;
+        this.fetcher = fetcher;
+    }
+    /** Low-level request. Exposed so tools can hit arbitrary endpoints without growing per-method wrappers for every call. */
+    async request(method, path, opts = {}) {
+        const url = new URL(this.config.orchestratorUrl + path);
+        for (const [key, value] of Object.entries(opts.query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        const headers = {};
+        let body;
+        if (opts.formData) {
+            body = opts.formData;
+        }
+        else if (opts.body !== undefined) {
+            headers["content-type"] = "application/json";
+            body = JSON.stringify(opts.body);
+        }
+        if (opts.bearer)
+            headers.authorization = `Bearer ${opts.bearer}`;
+        const res = await this.fetcher(url.toString(), { method, headers, body, signal: opts.signal });
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`orchestrator ${method} ${path} failed: ${res.status} ${text}`);
+        }
+        // Some endpoints return non-JSON (rare) — fall back to text.
+        const contentType = res.headers.get("content-type") ?? "";
+        if (contentType.includes("application/json"))
+            return (await res.json());
+        return (await res.text());
+    }
+    /** Convenience: session + siteId pre-filled for endpoints that take them as query params. */
+    scoped(extra = {}) {
+        return { session: this.config.session, siteId: this.config.siteId, ...extra };
+    }
+    /** Convenience: session + siteId pre-filled for endpoints that take them in the body. */
+    scopedBody(extra) {
+        return { session: this.config.session, siteId: this.config.siteId, ...extra };
+    }
+    // ── Typed helpers for the hottest paths ──
+    getPage(slug) {
+        return this.request("GET", "/draft/pages", { query: this.scoped({ slug }) });
+    }
+    listSlugs() {
+        return this.request("GET", "/draft/slugs", { query: this.scoped() });
+    }
+    getSiteConfig() {
+        return this.request("GET", "/draft/site-config", { query: this.scoped() });
+    }
+    applyOps(ops) {
+        return this.request("POST", "/ops", { body: this.scopedBody({ ops }) });
+    }
+    whoami() {
+        return this.request("GET", "/whoami", { query: this.scoped() });
+    }
+    listSessions() {
+        return this.request("GET", "/sessions");
+    }
+}

package/dist/tools/_helpers.d.ts

@@ -0,0 +1,33 @@
+import type { OrchestratorClient } from "../orchestrator-client.ts";
+export declare function jsonResult(payload: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function errorResult(err: unknown): {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: true;
+};
+type ChatResult = {
+    status?: string;
+    undoSlug?: string;
+    mentionedSlugs?: string[];
+};
+type ToolContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+export declare function chatResult(client: OrchestratorClient, payload: ChatResult, opts?: {
+    screenshot?: boolean;
+}): Promise<{
+    content: ToolContent[];
+}>;
+export {};

package/dist/tools/_helpers.js

@@ -0,0 +1,58 @@
+export function jsonResult(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    };
+}
+export function errorResult(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}
+/**
+ * Build a tool result for a /chat response, optionally chaining a draft-preview
+ * screenshot of the page that was just mutated. We only screenshot when the
+ * chat returned `applied` — pending/clarification states haven't changed state
+ * so there's nothing new to show. Screenshot failures are non-fatal.
+ *
+ * The screenshot is hard-capped at CHAT_SCREENSHOT_TIMEOUT_MS because Claude
+ * Desktop/web clients abandon tool results after ~30s. A slow Playwright load
+ * on top of a long planner run can exceed that window, and the user sees
+ * "Tool result could not be submitted." On timeout we degrade to a note
+ * instead of blocking the whole response.
+ */
+const CHAT_SCREENSHOT_TIMEOUT_MS = 8000;
+export async function chatResult(client, payload, opts = {}) {
+    const content = [
+        { type: "text", text: JSON.stringify(payload, null, 2) },
+    ];
+    const shouldShoot = opts.screenshot !== false && payload.status === "applied";
+    const slug = payload.undoSlug ?? payload.mentionedSlugs?.[0];
+    if (shouldShoot && slug) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), CHAT_SCREENSHOT_TIMEOUT_MS);
+        try {
+            const shot = await client.request("POST", "/preview/screenshot", {
+                body: client.scopedBody({ slug }),
+                signal: controller.signal,
+            });
+            content.push({
+                type: "text",
+                text: `Preview of ${shot.url} (draft, ${shot.width}×${shot.height})`,
+            });
+            content.push({ type: "image", data: shot.base64, mimeType: shot.mimeType });
+        }
+        catch (err) {
+            const aborted = controller.signal.aborted;
+            const reason = aborted
+                ? `timeout after ${CHAT_SCREENSHOT_TIMEOUT_MS}ms`
+                : err instanceof Error ? err.message : String(err);
+            content.push({ type: "text", text: `(screenshot skipped: ${reason})` });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return { content };
+}

package/dist/tools/blocks.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OrchestratorClient } from "../orchestrator-client.ts";
+import type { CapabilityGate } from "../capabilities.ts";
+export declare function registerBlockTools(server: McpServer, client: OrchestratorClient, gate?: CapabilityGate): void;