@avocadostudio-ai/mcp-server 0.3.3 → 0.5.0

package/README.md

@@ -14,7 +14,7 @@ Each install is scoped to **one site**: `(session, siteId)` are bound at launch
 | Sites | `avocado-register-site`, `avocado-list-sites`, `avocado-get-site-config`, `avocado-update-site-config` |
 | Media | `avocado-upload-image`, `avocado-generate-image`, `avocado-search-unsplash`, `avocado-transcribe-audio`, `avocado-interpret-image` |
 | Publishing | `avocado-compute-publish-diff`, `avocado-publish-content`, `avocado-get-publish-status`, `avocado-list-snapshots`, `avocado-restore-snapshot` |
-| History | `avocado-undo-edit`, `avocado-redo-edit`, `avocado-restore-version` |
+| History | `avocado-undo-edit`, `avocado-redo-edit`, `avocado-restore-version`, `avocado-discard-changes` |
 | Planner | `avocado-chat-plan`, `avocado-preview-plan`, `avocado-approve-pending-plan`, `avocado-discard-pending-plan` |
 | Preview | `avocado-screenshot-page` — returns a full-page JPEG inline (visual feedback channel for chat-only hosts like Claude Desktop) |
 

package/dist/tools/history.js

@@ -34,4 +34,23 @@ export function registerHistoryTools(server, client) {
             return errorResult(err);
         }
     });
+    server.tool("avocado-discard-changes", [
+        "Throw away changes from the history log. Each affected page is rolled back to the state it held immediately before the earliest version selected on it.",
+        "A page has one timeline, so discarding a change also discards the later changes to that same page — the response lists them under `discarded[].alsoDiscarded`. Pages you did not select keep their edits.",
+        "Versions with nothing recorded before them come back under `skipped` rather than being guessed at. The discard itself is undoable.",
+    ].join("\n"), {
+        versions: z
+            .array(z.number().int().positive())
+            .min(1)
+            .describe("Version numbers from the history log to discard."),
+    }, async ({ versions }) => {
+        try {
+            return jsonResult(await client.request("POST", "/history/discard", {
+                body: client.scopedBody({ versions }),
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
 }

package/dist/tools/index.js

@@ -8,6 +8,7 @@ import { registerHistoryTools } from "./history.js";
 import { registerChatTools } from "./chat.js";
 import { registerPreviewTools } from "./preview.js";
 import { registerSessionTools } from "./sessions.js";
+import { registerQaTools } from "./qa.js";
 /**
  * `gate` is optional so a caller that has no capability answer yet — every
  * caller, at startup — still registers the full tool set. The gate hides and
@@ -25,4 +26,5 @@ export function registerAllTools(server, client, gate) {
     registerHistoryTools(server, client);
     registerChatTools(server, client);
     registerPreviewTools(server, client);
+    registerQaTools(server, client);
 }

package/dist/tools/publishing.js

@@ -13,15 +13,24 @@ export function registerPublishingTools(server, client) {
             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.", {
+    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.",
+        "Pass `slugs` to publish only those pages — every other page keeps exactly what it has live. Omit it to publish the whole draft.",
+    ].join("\n"), {
         siteOrigin: z.string().url().optional(),
-    }, async ({ siteOrigin }) => {
+        slugs: z.array(z.string()).optional().describe("Publish only these page slugs, leaving every other page as it is on the live site. Omit for a full publish."),
+        includeSiteConfig: z.boolean().optional().describe("Whether the site header/nav ships with this publish. Defaults to true."),
+    }, async ({ siteOrigin, slugs, includeSiteConfig }) => {
         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 }),
+                body: client.scopedBody({
+                    siteOrigin,
+                    ...(slugs && slugs.length > 0 ? { slugs } : {}),
+                    ...(includeSiteConfig === false ? { includeSiteConfig: false } : {}),
+                }),
                 bearer: client.config.publishToken,
             }));
         }

package/dist/tools/qa.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 registerQaTools(server: McpServer, client: OrchestratorClient): void;

package/dist/tools/qa.js

@@ -0,0 +1,115 @@
+import { z } from "zod";
+import { getAllBlockMeta, panelCoverage, formatPanelCoverage } from "@avocadostudio-ai/shared";
+/*
+ * The step that asks whether the editing surface an integration just produced is
+ * any good.
+ *
+ * An agent can finish wiring a site — routes mounted, manifest served, markers
+ * emitted, build clean — and hand back a property panel whose list rows read
+ * `Item 4`, whose labels come from somebody else's block, and whose polymorphic
+ * branches never narrow. Every one of those was visible in the data the whole
+ * time; nothing was asking. The build cannot see it, the type checker cannot see
+ * it, and `editableCoverage` is about the preview.
+ *
+ * So this is the QA move: after integrating, before claiming success, ask the
+ * site what it will actually look like to edit, and either fix what comes back
+ * or report it verbatim.
+ *
+ * It reads the manifest from the ORCHESTRATOR for the same reason discovery
+ * does — that is the process which runs the site's `registerBlocks()` — and
+ * compares it against the site's real pages. No browser, no screenshot, no model
+ * call.
+ */
+/** The editor's own registry, which is what a colliding type name collides with. */
+function editorBuiltins() {
+    return getAllBlockMeta();
+}
+export function registerQaTools(server, client) {
+    server.tool("avocado-check-editing-surface", "QA the property panel this site produces: which list rows a person can tell apart, which polymorphic branches actually narrow, which props are in the content but described by nothing, and where block type names collide with Avocado's built-ins. Call this after integrating a site or changing its block schemas, and before reporting the integration as done — a site can build cleanly, serve a valid manifest and still be unintelligible to edit.", {
+        slugs: z
+            .array(z.string())
+            .optional()
+            .describe("Pages to examine. Defaults to every slug the site has."),
+        includeBuiltinCollisions: z
+            .boolean()
+            .optional()
+            .describe("Report block type names that also exist in the editor's built-in registry with a different shape. Default true; this is usually the root cause of several other findings.")
+    }, async ({ slugs, includeBuiltinCollisions = true }) => {
+        let manifest;
+        try {
+            manifest = await client.request("GET", "/blocks/manifest");
+            if (!manifest || !Array.isArray(manifest.blocks))
+                throw new Error("no blocks array");
+        }
+        catch (err) {
+            /*
+             * Deliberately an error rather than a fallback to this process's
+             * registry. Discovery can hedge — a labelled guess still helps an agent
+             * plan. A QA check that silently measured the wrong site's blocks would
+             * report an all-clear on a panel nobody has looked at, which is worse
+             * than not running.
+             */
+            return {
+                content: [{
+                        type: "text",
+                        text: `Cannot QA the editing surface: the site's block manifest is unreadable at ` +
+                            `${client.config.orchestratorUrl}/blocks/manifest (${err instanceof Error ? err.message : String(err)}). ` +
+                            `This check has to read the manifest from the process that renders the site, not from this one.`
+                    }],
+                isError: true
+            };
+        }
+        let targetSlugs = slugs;
+        if (!targetSlugs || targetSlugs.length === 0) {
+            try {
+                const index = await client.request("GET", "/draft/slugs", {
+                    query: { session: client.config.session, siteId: client.config.siteId }
+                });
+                targetSlugs = index.slugs ?? [];
+            }
+            catch {
+                targetSlugs = [];
+            }
+        }
+        const pages = [];
+        const unreadable = [];
+        for (const slug of targetSlugs) {
+            try {
+                pages.push(await client.getPage(slug));
+            }
+            catch {
+                unreadable.push(slug);
+            }
+        }
+        const report = panelCoverage(manifest, pages, {
+            ...(includeBuiltinCollisions ? { builtinTypes: editorBuiltins() } : {})
+        });
+        /*
+         * Both shapes on purpose. The formatted report is what a person reads when
+         * the agent quotes it; the structured findings are what the agent filters,
+         * counts and decides on. Handing back only prose makes an agent re-parse
+         * its own tool output, and only JSON makes its final message unreadable.
+         */
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({
+                        pagesExamined: pages.length,
+                        ...(unreadable.length > 0 ? { unreadableSlugs: unreadable } : {}),
+                        rowsExamined: report.rowsExamined,
+                        rowsLabelled: report.rowsLabelled,
+                        findingCount: report.findings.length,
+                        findings: report.findings,
+                        unknownBlockTypes: report.unknownBlockTypes,
+                        report: formatPanelCoverage(report),
+                        guidance: report.findings.length === 0
+                            ? "No editing-surface findings. The panel can label every list row it was shown."
+                            : "Fix these before reporting the integration as done, or list the ones you are leaving and why. " +
+                                "`colliding_type` first: where a site re-registers a built-in name with its own shape, anything " +
+                                "the manifest does not declare explicitly is taken from the built-in, which usually explains " +
+                                "several of the findings under it."
+                    }, null, 2)
+                }]
+        };
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avocadostudio-ai/mcp-server",
-  "version": "0.3.3",
+  "version": "0.5.0",
   "description": "Avocado Studio MCP server — exposes page/block/discovery tools over the Model Context Protocol.",
   "license": "Apache-2.0",
   "type": "module",
@@ -41,7 +41,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^4.3.6",
-    "@avocadostudio-ai/shared": "^0.3.3"
+    "@avocadostudio-ai/shared": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",