@avocadostudio-ai/mcp-server 0.2.0

package/dist/tools/pages.js

@@ -0,0 +1,131 @@
+import { z } from "zod";
+import { jsonResult, errorResult } from "./_helpers.js";
+const pageSlug = z
+    .string()
+    .min(1)
+    .describe("Page slug, starts with '/' (e.g. '/', '/pricing'). This is the page's identity in the draft, " +
+    "NOT necessarily the URL it is served at — see `path` on avocado-list-pages before navigating to one.");
+export function registerPageTools(server, client, gate) {
+    server.tool("avocado-get-page", "Fetch a single page's full draft document (blocks + meta) by slug.", { slug: pageSlug }, async ({ slug }) => {
+        try {
+            return jsonResult(await client.getPage(slug));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-list-pages", "List every page in the current draft (home page first). Returns both `slugs: string[]` and a richer `pages: [{ slug, path?, title, updatedAt, blockCount }]` summary — use `pages` to plan multi-page work without needing a follow-up avocado-get-page per slug. Note: `title` is the page's internal/display title (the one shown in the editor nav and settable via `avocado-rename-page`). It is distinct from the SEO `<title>` tag (`meta.title`) which is set via `avocado-update-page-meta` and only visible through `avocado-get-page`. IMPORTANT: `slug` identifies the page, and is only the site's URL when `path` is absent. A site with locale prefixes, a basePath, or its own routing reports the real URL in `path` — open `path` when it is present, never the slug, or you will land on a 404. ALSO CHECK `source` before trusting the list: `draft`/`adapter` is the site's own content; `demo` means these are Avocado's bundled demo pages and belong to no real site (usually a missing `siteId`); `unknown-site` means no site by that id is known here, so the empty list is not a report that the site has no pages; `empty` means the site is known and genuinely has none. `note` explains the case in words.", {}, async () => {
+        try {
+            return jsonResult(await client.listSlugs());
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    const _gated_0 = server.tool("avocado-create-page", "Create a new page. The page must include a unique slug, title, and an initial blocks array (can be empty).", {
+        slug: pageSlug,
+        title: z.string().min(1),
+        blocks: z.array(z.object({
+            id: z.string().min(1),
+            type: z.string().min(1),
+            props: z.record(z.string(), z.unknown()),
+        })).default([]),
+        meta: z.object({
+            title: z.string().optional(),
+            description: z.string().optional(),
+            ogImage: z.string().optional(),
+        }).optional(),
+    }, async ({ slug, title, blocks, meta }) => {
+        const refusal = gate?.refuse("createPages");
+        if (refusal)
+            return errorResult(refusal);
+        try {
+            return jsonResult(await client.applyOps([
+                {
+                    op: "create_page",
+                    page: {
+                        id: `p_${slug.replace(/[^a-zA-Z0-9]+/g, "_")}_${Date.now()}`,
+                        slug,
+                        title,
+                        updatedAt: new Date().toISOString(),
+                        blocks,
+                        meta,
+                    },
+                },
+            ]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    gate?.track("createPages", _gated_0);
+    server.tool("avocado-rename-page", "Rename a page — change its slug and/or its display/internal title. Provide either `newSlug`, `newTitle`, or both. A pure title change leaves the URL and all internal links untouched; a slug change rewrites internal links to the old slug automatically. Note: this tool changes the page's display title (shown in the editor and in `avocado-list-pages`), which is separate from SEO `meta.title` — use `avocado-update-page-meta` for that.", {
+        slug: pageSlug,
+        newSlug: z.string().min(1).describe("New slug (starts with '/'). Omit for a title-only rename.").optional(),
+        newTitle: z.string().min(1).describe("New display/internal title. Omit for a slug-only rename.").optional(),
+    }, async ({ slug, newSlug, newTitle }) => {
+        if (!newSlug && !newTitle)
+            return errorResult(new Error("Provide newSlug or newTitle."));
+        try {
+            return jsonResult(await client.applyOps([
+                { op: "rename_page", pageSlug: slug, newPageSlug: newSlug, newTitle },
+            ]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    const _gated_1 = server.tool("avocado-duplicate-page", "Duplicate a page, optionally under a new slug/title and inserted after a specific page in the nav order. When `newTitle` is passed, `meta.title` is synced to the new title too (so SEO doesn't show the source page's title). Response includes `duplicatedPages: [{ slug, blockIdMap: { [oldId]: newId } }]` — use the map to target copied blocks directly without a follow-up avocado-get-page.", {
+        slug: pageSlug,
+        newSlug: z.string().min(1).optional(),
+        newTitle: z.string().min(1).optional(),
+        afterSlug: z.string().min(1).optional().describe("Slug of the page the duplicate should appear after in nav order."),
+    }, async ({ slug, newSlug, newTitle, afterSlug }) => {
+        const refusal = gate?.refuse("createPages");
+        if (refusal)
+            return errorResult(refusal);
+        try {
+            return jsonResult(await client.applyOps([
+                { op: "duplicate_page", pageSlug: slug, newPageSlug: newSlug, newTitle, afterPageSlug: afterSlug },
+            ]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    gate?.track("createPages", _gated_1);
+    const _gated_2 = server.tool("avocado-remove-page", "Delete a page from the draft. Undo-able from the editor history.", { slug: pageSlug }, async ({ slug }) => {
+        const refusal = gate?.refuse("deletePages");
+        if (refusal)
+            return errorResult(refusal);
+        try {
+            return jsonResult(await client.applyOps([{ op: "remove_page", pageSlug: slug }]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    gate?.track("deletePages", _gated_2);
+    server.tool("avocado-update-page-meta", "Patch a page's SEO metadata (title, description, ogImage). Only provided keys are updated.", {
+        slug: pageSlug,
+        title: z.string().optional(),
+        description: z.string().optional(),
+        ogImage: z.string().optional(),
+    }, async ({ slug, title, description, ogImage }) => {
+        const patch = {};
+        if (title !== undefined)
+            patch.title = title;
+        if (description !== undefined)
+            patch.description = description;
+        if (ogImage !== undefined)
+            patch.ogImage = ogImage;
+        if (Object.keys(patch).length === 0)
+            return errorResult(new Error("Provide at least one of title, description, ogImage."));
+        try {
+            return jsonResult(await client.applyOps([{ op: "update_page_meta", pageSlug: slug, patch }]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}

package/dist/tools/preview.d.ts

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

package/dist/tools/preview.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { errorResult } from "./_helpers.js";
+export function registerPreviewTools(server, client) {
+    server.tool("avocado-screenshot-page", "Take a full-page screenshot of a page and return it as an inline image. Defaults to the draft (what the editor sees), so in-progress edits are visible before publish. Pass `published: true` to screenshot the live public route instead. Site must have a previewUrl registered (via avocado-register-site).", {
+        slug: z.string().optional().describe("Page slug to screenshot, e.g. '/' or '/pricing'. Defaults to the home page."),
+        published: z.boolean().optional().describe("If true, screenshot the published public route instead of the draft. Defaults to false (draft)."),
+        previewUrl: z.string().url().optional().describe("Override the registered previewUrl (useful for ad-hoc captures)."),
+        draftPath: z.string().optional().describe("Override the site's draft-preview route for this capture. A prefix the slug is appended to ('/avocado') or a template naming where it goes ('/preview/{slug}/draft'). Defaults to the site's registered draftPath, then '/preview-draft'. If a draft screenshot comes back as the site's 404 page, this is why."),
+    }, async ({ slug, published, previewUrl, draftPath }) => {
+        try {
+            const res = await client.request("POST", "/preview/screenshot", {
+                body: client.scopedBody({ slug, published, previewUrl, draftPath }),
+            });
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Screenshot of ${res.url} (${res.mode} mode, ${res.width}×${res.height})`,
+                    },
+                    {
+                        type: "image",
+                        data: res.base64,
+                        mimeType: res.mimeType,
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}

package/dist/tools/publishing.d.ts

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

package/dist/tools/publishing.js

@@ -0,0 +1,67 @@
+import { z } from "zod";
+import { jsonResult, errorResult } from "./_helpers.js";
+export function registerPublishingTools(server, client) {
+    server.tool("avocado-compute-publish-diff", "Compute the diff between the current draft and the last published snapshot. Shows what would change if you publish now.", {
+        siteOrigin: z.string().url().optional().describe("Override the published-content source (defaults to the configured site origin)."),
+    }, async ({ siteOrigin }) => {
+        try {
+            return jsonResult(await client.request("GET", "/publish/diff", {
+                query: client.scoped({ siteOrigin }),
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-publish-content", "Publish the current draft to the live site. Requires AVOCADO_PUBLISH_TOKEN env var (the orchestrator's DRAFT_MODE_SECRET) to be set on the MCP server process.", {
+        siteOrigin: z.string().url().optional(),
+    }, async ({ siteOrigin }) => {
+        if (!client.config.publishToken) {
+            return errorResult(new Error("AVOCADO_PUBLISH_TOKEN is not set on the MCP server. Re-install the connector with --env AVOCADO_PUBLISH_TOKEN=<DRAFT_MODE_SECRET>."));
+        }
+        try {
+            return jsonResult(await client.request("POST", "/publish", {
+                body: client.scopedBody({ siteOrigin }),
+                bearer: client.config.publishToken,
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-get-publish-status", [
+        "Fetch the current publish tracker for this site (target type, state, last deployment, URLs).",
+        "Returns `{ status: 'idle' }` when nothing has been published by the running orchestrator process — that is the normal state before a first publish and after any restart, NOT a sign that publishing is broken. Use avocado-compute-publish-diff to see what a publish would change.",
+    ].join("\n"), {}, async () => {
+        try {
+            return jsonResult(await client.request("GET", "/publish/status", { query: client.scoped() }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-list-snapshots", "List published snapshots (prior publish commits) available to restore from. Defaults to the latest 30.", {
+        limit: z.number().int().min(1).max(100).optional(),
+    }, async ({ limit }) => {
+        try {
+            return jsonResult(await client.request("GET", "/restore/snapshots", {
+                query: { siteId: client.config.siteId, limit },
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-restore-snapshot", "Rewind the draft to a previously-published snapshot, identified by its git commit sha (from avocado-list-snapshots).", {
+        commit: z.string().regex(/^[a-f0-9]{7,40}$/i).describe("Git commit sha (7–40 hex chars) of the published snapshot."),
+    }, async ({ commit }) => {
+        try {
+            return jsonResult(await client.request("POST", "/restore/snapshot", {
+                body: client.scopedBody({ commit }),
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}

package/dist/tools/sessions.d.ts

@@ -0,0 +1,8 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OrchestratorClient } from "../orchestrator-client.ts";
+import type { CapabilityGate } from "../capabilities.ts";
+/**
+ * Session introspection tools — answer "which draft am I editing?" and "what
+ * other sessions exist on this orchestrator?" without dropping to raw SQLite.
+ */
+export declare function registerSessionTools(server: McpServer, client: OrchestratorClient, gate?: CapabilityGate): void;

package/dist/tools/sessions.js

@@ -0,0 +1,39 @@
+import { jsonResult, errorResult } from "./_helpers.js";
+/**
+ * Session introspection tools — answer "which draft am I editing?" and "what
+ * other sessions exist on this orchestrator?" without dropping to raw SQLite.
+ */
+export function registerSessionTools(server, client, gate) {
+    server.tool("avocado-whoami", "Return this MCP install's bound session + a summary of its state (siteId, draft page count, version, last mutation). Call it first: it is how you confirm you are about to edit the draft you think you are. The `source` field says whose content is behind the session — `draft`/`adapter` is the site's own, `demo` is Avocado's bundled demo content (no real site), and `unknown-site` means no site by that id is known here, so everything you do afterwards would apply to a session that matches nothing. `note` explains it in words, and `knownSiteIds` lists what the id could have meant.", {}, async () => {
+        try {
+            const bound = {
+                session: client.config.session,
+                siteId: client.config.siteId,
+                orchestratorUrl: client.config.orchestratorUrl,
+            };
+            const summary = await client.whoami();
+            /*
+             * Refresh capabilities here rather than only at startup: whoami is
+             * what an agent calls first, and a site that came up after this
+             * process did should not be answered from a stale "unknown".
+             * Non-blocking by construction — the gate's probe has its own short
+             * timeout and falls back to permissive.
+             */
+            const capabilities = gate ? await gate.refresh() : undefined;
+            // Prefer the server-reported orchestratorUrl (strips trailing slashes, reflects the actual host),
+            // but surface the locally configured session/siteId so mismatches are debuggable.
+            return jsonResult({ ...summary, bound, ...(capabilities ? { capabilities } : {}) });
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-list-sessions", "List every session this orchestrator has state for, sorted by most recently mutated. Each row: { sessionKey, session, siteId, version, draftPageCount, lastMutatedAt }. Use to discover other drafts (e.g. {siteId}::{session} style keys) without shelling into SQLite.", {}, async () => {
+        try {
+            return jsonResult(await client.listSessions());
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}

package/dist/tools/sites.d.ts

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

package/dist/tools/sites.js

@@ -0,0 +1,90 @@
+import { z } from "zod";
+import { jsonResult, errorResult } from "./_helpers.js";
+export function registerSiteTools(server, client) {
+    server.tool("avocado-register-site", "Register or update the site entry for this install (preview URL, display name, port, purpose, tone). Required once before the editor can find the site.", {
+        name: z.string().min(1).optional().describe("Display name shown in the editor's site switcher."),
+        previewUrl: z.string().url().optional().describe("URL where the Next.js site is running (e.g. http://localhost:3000)."),
+        draftPath: z.string().optional().describe("The route this site renders orchestrator drafts on — a prefix the page slug is appended to ('/avocado') or a template naming where it goes ('/preview/{slug}/draft'). Defaults to '/preview-draft'. Set this for a site that wired Avocado into its own app, or draft screenshots photograph its 404 page."),
+        port: z.number().int().positive().optional(),
+        purpose: z.string().optional().describe("One-liner describing what the site is about. Used as AI context."),
+        secret: z.string().optional().describe("DRAFT_MODE_SECRET value so the orchestrator can fetch draft content."),
+    }, async (args) => {
+        try {
+            return jsonResult(await client.request("POST", "/sites/register", {
+                body: client.scopedBody(args),
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-list-sites", "List every site registered under the current session.", {}, async () => {
+        try {
+            return jsonResult(await client.request("GET", "/sites", { query: { session: client.config.session } }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-get-site-config", "Fetch the current site's config (name, logo, tone, purpose, nav labels/groups, theme overrides).", {}, async () => {
+        try {
+            return jsonResult(await client.getSiteConfig());
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-update-site-config", "Patch the site's config (name, logo, navLabels, navGroups). Only provided keys are updated; others remain untouched. Undo-able via history.", {
+        name: z.string().optional(),
+        logo: z.string().optional().describe("URL or path to the site logo."),
+        navLabels: z.record(z.string(), z.string()).optional().describe("Slug → custom nav label (e.g. { '/pricing': 'Plans & Pricing' })."),
+        navGroups: z.record(z.string(), z.array(z.string())).optional().describe("Parent label → child slugs (e.g. { 'Products': ['/bananas', '/cherries'] })."),
+    }, async ({ name, logo, navLabels, navGroups }) => {
+        const patch = {};
+        if (name !== undefined)
+            patch.name = name;
+        if (logo !== undefined)
+            patch.logo = logo;
+        if (navLabels !== undefined)
+            patch.navLabels = navLabels;
+        if (navGroups !== undefined)
+            patch.navGroups = navGroups;
+        if (Object.keys(patch).length === 0) {
+            return errorResult(new Error("Provide at least one of name, logo, navLabels, navGroups."));
+        }
+        try {
+            return jsonResult(await client.applyOps([{ op: "update_site_config", patch }]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-update-theme", "Change the site-wide visual theme — colors, fonts, and corner radius applied to every page and block. Uses semantic tokens (not raw CSS variables). Merge-patch: only provided tokens change; pass an empty string to reset a token to the theme default. Undo-able via history.", {
+        brandColor: z.string().optional().describe("Primary brand color (CSS color). Sets --brand, --brand-hover, --link."),
+        accentColor: z.string().optional().describe("Secondary accent color. Sets --accent, --accent-hover."),
+        backgroundColor: z.string().optional().describe("Page background color. Sets --bg-0, --bg-000."),
+        surfaceColor: z.string().optional().describe("Card/panel surface color. Sets --surface, --card-bg, --bg-100."),
+        headingColor: z.string().optional().describe("Heading text color. Sets --heading, --text-100."),
+        textColor: z.string().optional().describe("Body text color. Sets --body, --text-200."),
+        mutedTextColor: z.string().optional().describe("Muted/secondary text color. Sets --body-secondary, --text-300, --caption."),
+        headingFont: z.string().optional().describe("Heading font stack (e.g. 'Georgia, serif'). Sets --font-heading."),
+        bodyFont: z.string().optional().describe("Body font stack. Sets --font-body."),
+        radius: z.string().optional().describe("Corner radius across buttons/cards/inputs (e.g. '12px'). Sets --radius and friends."),
+        cssVars: z.record(z.string(), z.string()).optional().describe("Raw --var → value escape hatch, merged after the semantic tokens (raw wins)."),
+    }, async ({ cssVars, ...tokens }) => {
+        const patch = {};
+        for (const [k, v] of Object.entries(tokens)) {
+            if (v !== undefined)
+                patch[k] = v;
+        }
+        if (Object.keys(patch).length === 0 && (!cssVars || Object.keys(cssVars).length === 0)) {
+            return errorResult(new Error("Provide at least one theme token or a cssVars entry."));
+        }
+        try {
+            return jsonResult(await client.applyOps([{ op: "update_theme", patch, ...(cssVars ? { cssVars } : {}) }]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SERVER_VERSION: string;

package/dist/version.js

@@ -0,0 +1,16 @@
+import { createRequire } from "node:module";
+/*
+ * The version the server reports in `initialize`.
+ *
+ * Read from the manifest rather than written here. It was the literal "0.1.0"
+ * in two files, and it stayed "0.1.0" through the package being renamed,
+ * republished and moved — so the first client to ask this server what it was
+ * would have been told the wrong number. A hardcoded version is only ever
+ * correct on the day someone remembers it.
+ *
+ * `../package.json` resolves to the package root from both `src/` in dev and
+ * `dist/` in a published install, and `exports` declares that subpath so the
+ * read works from a registry consumer too.
+ */
+const require = createRequire(import.meta.url);
+export const SERVER_VERSION = require("../package.json").version;

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@avocadostudio-ai/mcp-server",
+  "version": "0.2.0",
+  "description": "Avocado Studio MCP server — exposes page/block/discovery tools over the Model Context Protocol.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "avocado-mcp": "./dist/index.js",
+    "avocado-mcp-http": "./dist/http.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "avocado",
+    "avocado-studio",
+    "mcp",
+    "model-context-protocol",
+    "cms",
+    "ai",
+    "claude"
+  ],
+  "homepage": "https://github.com/avocadostudio-ai/avocado/tree/main/packages/mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/avocadostudio-ai/avocado/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/avocadostudio-ai/avocado.git",
+    "directory": "packages/mcp-server"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.3.6",
+    "@avocadostudio-ai/shared": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsx": "^4.19.3",
+    "typescript": "^5.7.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && chmod +x dist/index.js dist/http.js",
+    "dev": "tsx watch src/index.ts",
+    "dev:http": "tsx watch src/http.ts",
+    "start": "tsx src/index.ts",
+    "start:http": "tsx src/http.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "NODE_ENV=test node ../../scripts/run-tests.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  }
+}