@avocadostudio-ai/mcp-server 0.4.0 → 0.5.0

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/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.4.0",
+  "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.4.0"
+    "@avocadostudio-ai/shared": "^0.5.0"
   },
   "devDependencies": {
     "@types/node": "^22.13.10",