@avocadostudio-ai/mcp-server 0.2.0

package/dist/tools/blocks.js

@@ -0,0 +1,256 @@
+import { z } from "zod";
+import { jsonResult, errorResult } from "./_helpers.js";
+const pageSlug = z.string().min(1).describe("Page slug the block lives on.");
+const blockId = z.string().min(1).describe("Block instance id (from avocado-get-page).");
+const listKey = z.string().min(1).describe("List-field name on the block (e.g. 'features', 'items', 'cards').");
+const itemId = z.string().min(1).optional().describe("Stable id of the target list item (from avocado-get-page). Preferred over index — survives sibling inserts/removals.");
+const afterItemId = z.string().min(1).optional().describe("Place after the item with this id (preferred over afterIndex). Omit to append/move to top.");
+export function registerBlockTools(server, client, gate) {
+    server.tool("avocado-batch-apply", [
+        "Apply an array of ops in a single atomic transaction. All ops commit together or none do, and `previewVersion` only bumps once for the whole batch. Use for multi-op flows (e.g. translating every field on a page, bulk list-item edits) instead of chaining single-op tools — avoids N round-trips and N version bumps.",
+        "",
+        "IMPORTANT: batch ops use the wire-format Operation schema, NOT the single-op MCP tool parameter names. Field names differ: single-op tools like `avocado-rename-page` take `slug`/`newSlug` and `avocado-update-page-meta` takes flat `title`/`description`/`ogImage`, but their batch equivalents take `pageSlug`/`newPageSlug` and `patch: { title?, description?, ogImage? }` respectively. Tip: if you're unsure about an op's exact shape, probe with a minimal 1–2 op batch before constructing a large payload.",
+        "",
+        "Required fields per op type:",
+        "- { op: 'create_page', page: { id, slug, title, updatedAt, blocks: [{id,type,props}], meta? } }",
+        "- { op: 'add_block', pageSlug, block: { id, type, props }, afterBlockId? }",
+        "- { op: 'update_props', pageSlug, blockId, patch }",
+        "- { op: 'remove_block', pageSlug, blockId }",
+        "- { op: 'move_block', pageSlug, blockId, afterBlockId? }",
+        "- { op: 'duplicate_block', pageSlug, blockId, toPageSlug?, newBlockId?, afterBlockId? }",
+        "- { op: 'add_item', pageSlug, blockId, listKey, item, afterItemId? | afterIndex? } — the new item gets a stable id automatically; omit the anchor to append.",
+        "- { op: 'update_item', pageSlug, blockId, listKey, patch, itemId? | index? } — target by itemId (preferred, robust across the batch) or index.",
+        "- { op: 'remove_item', pageSlug, blockId, listKey, itemId? | index? }",
+        "- { op: 'move_item', pageSlug, blockId, listKey, itemId? | index?, afterItemId? | afterIndex? } — omit the anchor to move to front.",
+        "- { op: 'reorder_items', pageSlug, blockId, listKey, order } — order is the FINAL sequence covering every item exactly once (item ids, or 0-based indexes for id-less lists like Table rows). Prefer over chained move_item when several items change position.",
+        "- { op: 'reorder_blocks', pageSlug, order } — order is the FINAL sequence of every non-chrome block id on the page (omit pinned SiteHeader/Footer). Prefer over chained move_block.",
+        "- { op: 'rename_page', pageSlug, newPageSlug?, newTitle? } — provide at least one of newPageSlug (different from current) or newTitle (different from current). Omit newPageSlug for title-only rename.",
+        "- { op: 'remove_page', pageSlug }",
+        "- { op: 'move_page', pageSlug, afterPageSlug? }",
+        "- { op: 'duplicate_page', pageSlug, newPageSlug?, newTitle?, afterPageSlug? }",
+        "- { op: 'update_page_meta', pageSlug, patch: { title?, description?, ogImage? } } — patch must contain at least one field whose value differs from the current meta.",
+        "- { op: 'update_site_config', patch: { name?, logo?, navLabels?, navGroups? } }",
+        "- { op: 'update_theme', patch: { brandColor?, accentColor?, backgroundColor?, surfaceColor?, headingColor?, textColor?, mutedTextColor?, headingFont?, bodyFont?, radius? }, cssVars? } — site-wide colors/fonts/radius. patch uses semantic tokens (CSS color/font/length strings); set a token to \"\" to clear it. cssVars is a raw --var→value escape hatch (merged last).",
+        "",
+        "The whole call rejects atomically if any op fails validation. For a multi-step edit where one op is finicky, consider running the reliable bulk as a batch and the finicky one as a follow-up single-op call so a rejection on the hard op doesn't roll back the good work.",
+    ].join("\n"), {
+        ops: z
+            .array(z.record(z.string(), z.unknown()))
+            .min(1)
+            .describe("Array of ops to apply atomically. Each must include an `op` discriminator and the wire-format fields required for that op type (see tool description for the per-op shape list)."),
+    }, async ({ ops }) => {
+        if (!Array.isArray(ops) || ops.length === 0) {
+            return errorResult(new Error("ops must be a non-empty array."));
+        }
+        try {
+            return jsonResult(await client.applyOps(ops));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-dry-run-ops", [
+        "Validate a hand-built ops array WITHOUT mutating draft state. Returns per-op results (`opResults`: applied | skipped | failed, with a reason on each) and a structured before→after `preview` diff (changed pages/blocks/fields). Unlike avocado-batch-apply, a failing op does not abort the others — it's reported as `failed`, so you get a full 'what would happen' map in one call.",
+        "Use this to check a finicky plan before committing, or to discover which op in a batch is the problem. Ops use the same wire format as avocado-batch-apply (see that tool's description for per-op shapes).",
+    ].join("\n"), {
+        ops: z
+            .array(z.record(z.string(), z.unknown()))
+            .min(1)
+            .describe("Array of ops to validate. Same wire format as avocado-batch-apply."),
+    }, async ({ ops }) => {
+        if (!Array.isArray(ops) || ops.length === 0) {
+            return errorResult(new Error("ops must be a non-empty array."));
+        }
+        try {
+            return jsonResult(await client.request("POST", "/ops", {
+                body: client.scopedBody({ ops, dryRun: true }),
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    const _gated_0 = server.tool("avocado-add-block", "Insert a new block into a page. Call avocado-get-block-schema first to learn the required prop shape for the block type.", {
+        pageSlug,
+        block: z.object({
+            id: z.string().min(1),
+            type: z.string().min(1),
+            props: z.record(z.string(), z.unknown()),
+        }),
+        afterBlockId: z.string().min(1).optional().describe("Insert after this block id. Omit to append at the end."),
+    }, async ({ pageSlug, block, afterBlockId }) => {
+        const refusal = gate?.refuse("structuralEdits");
+        if (refusal)
+            return errorResult(refusal);
+        try {
+            return jsonResult(await client.applyOps([{ op: "add_block", pageSlug, block, afterBlockId }]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    gate?.track("structuralEdits", _gated_0);
+    server.tool("avocado-update-block-props", "Patch one or more props on an existing block. Only the keys in `patch` are updated; other props remain untouched.", {
+        pageSlug,
+        blockId,
+        patch: z.record(z.string(), z.unknown()).describe("Partial props object. Keys must be valid for the block type."),
+    }, async ({ pageSlug, blockId, patch }) => {
+        try {
+            return jsonResult(await client.applyOps([{ op: "update_props", pageSlug, blockId, patch }]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    const _gated_1 = server.tool("avocado-remove-block", "Delete a block from a page. Undo-able from the editor history.", { pageSlug, blockId }, async ({ pageSlug, blockId }) => {
+        const refusal = gate?.refuse("structuralEdits");
+        if (refusal)
+            return errorResult(refusal);
+        try {
+            return jsonResult(await client.applyOps([{ op: "remove_block", pageSlug, blockId }]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    gate?.track("structuralEdits", _gated_1);
+    const _gated_2 = server.tool("avocado-move-block", "Reorder a block within its page. Pass afterBlockId to place it after another block, or omit to move to the top.", {
+        pageSlug,
+        blockId,
+        afterBlockId: z.string().min(1).optional(),
+    }, async ({ pageSlug, blockId, afterBlockId }) => {
+        const refusal = gate?.refuse("structuralEdits");
+        if (refusal)
+            return errorResult(refusal);
+        try {
+            return jsonResult(await client.applyOps([{ op: "move_block", pageSlug, blockId, afterBlockId }]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    gate?.track("structuralEdits", _gated_2);
+    const _gated_3 = server.tool("avocado-duplicate-block", "Duplicate a block, optionally onto a different page and/or with an explicit new id.", {
+        pageSlug,
+        blockId,
+        toPageSlug: z.string().min(1).optional().describe("Target page slug (defaults to the source page)."),
+        newBlockId: z.string().min(1).optional(),
+        afterBlockId: z.string().min(1).optional(),
+    }, async ({ pageSlug, blockId, toPageSlug, newBlockId, afterBlockId }) => {
+        const refusal = gate?.refuse("structuralEdits");
+        if (refusal)
+            return errorResult(refusal);
+        try {
+            return jsonResult(await client.applyOps([
+                { op: "duplicate_block", pageSlug, blockId, toPageSlug, newBlockId, afterBlockId },
+            ]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    gate?.track("structuralEdits", _gated_3);
+    // ── List-field item ops ──
+    server.tool("avocado-add-list-item", "Append or insert an item into a block's list field (e.g. add a feature to FeatureGrid, an item to FAQAccordion). The new item gets a stable id automatically.", {
+        pageSlug,
+        blockId,
+        listKey,
+        item: z.record(z.string(), z.unknown()),
+        afterItemId,
+        afterIndex: z.number().int().min(0).optional().describe("Insert after this index. Omit to append."),
+    }, async ({ pageSlug, blockId, listKey, item, afterItemId, afterIndex }) => {
+        try {
+            return jsonResult(await client.applyOps([
+                { op: "add_item", pageSlug, blockId, listKey, item, afterItemId, afterIndex },
+            ]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-update-list-item", "Patch fields on one item inside a block's list field. Identify it by itemId (preferred) or zero-based index.", {
+        pageSlug,
+        blockId,
+        listKey,
+        itemId,
+        index: z.number().int().min(0).optional().describe("Item index (0-based). Used only when itemId is omitted."),
+        patch: z.record(z.string(), z.unknown()),
+    }, async ({ pageSlug, blockId, listKey, itemId, index, patch }) => {
+        try {
+            return jsonResult(await client.applyOps([
+                { op: "update_item", pageSlug, blockId, listKey, itemId, index, patch },
+            ]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-remove-list-item", "Remove an item from a block's list field. Identify it by itemId (preferred) or zero-based index.", {
+        pageSlug,
+        blockId,
+        listKey,
+        itemId,
+        index: z.number().int().min(0).optional().describe("Item index to remove (0-based). Used only when itemId is omitted."),
+    }, async ({ pageSlug, blockId, listKey, itemId, index }) => {
+        try {
+            return jsonResult(await client.applyOps([
+                { op: "remove_item", pageSlug, blockId, listKey, itemId, index },
+            ]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-move-list-item", "Reorder an item inside a block's list field. Identify the item by itemId (preferred) or index; pass afterItemId/afterIndex to place it after another item, or omit to move to the top.", {
+        pageSlug,
+        blockId,
+        listKey,
+        itemId,
+        index: z.number().int().min(0).optional().describe("Current item index (0-based). Used only when itemId is omitted."),
+        afterItemId,
+        afterIndex: z.number().int().min(0).optional(),
+    }, async ({ pageSlug, blockId, listKey, itemId, index, afterItemId, afterIndex }) => {
+        try {
+            return jsonResult(await client.applyOps([
+                { op: "move_item", pageSlug, blockId, listKey, itemId, index, afterItemId, afterIndex },
+            ]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-reorder-list-items", "Reorder ALL items of a block's list field in one atomic call by stating the final order. Prefer this over repeated avocado-move-list-item calls whenever more than one item changes position (sort, reverse, rearrange) — sequential moves use stale positions.", {
+        pageSlug,
+        blockId,
+        listKey,
+        order: z.array(z.union([z.string().min(1), z.number().int().min(0)])).min(1)
+            .describe("The FINAL order, covering every item exactly once. Entries are stable item ids (from avocado-get-page; preferred) or current 0-based indexes (for id-less lists like Table rows)."),
+    }, async ({ pageSlug, blockId, listKey, order }) => {
+        try {
+            return jsonResult(await client.applyOps([
+                { op: "reorder_items", pageSlug, blockId, listKey, order },
+            ]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    const _gated_4 = server.tool("avocado-reorder-blocks", "Reorder a page's sections in one atomic call by stating the final block order. Prefer this over repeated avocado-move-block calls whenever more than one block changes position. Omit chrome blocks (SiteHeader/Footer) — they are pinned.", {
+        pageSlug,
+        order: z.array(z.string().min(1)).min(1)
+            .describe("The FINAL order: every non-chrome block id on the page (from avocado-get-page), each exactly once."),
+    }, async ({ pageSlug, order }) => {
+        const refusal = gate?.refuse("structuralEdits");
+        if (refusal)
+            return errorResult(refusal);
+        try {
+            return jsonResult(await client.applyOps([
+                { op: "reorder_blocks", pageSlug, order },
+            ]));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    gate?.track("structuralEdits", _gated_4);
+}

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

package/dist/tools/chat.js

@@ -0,0 +1,52 @@
+import { z } from "zod";
+import { jsonResult, errorResult, chatResult } from "./_helpers.js";
+const message = z.string().min(1).describe("Natural-language edit instruction.");
+const slug = z.string().optional().describe("Focus the planner on a specific page (defaults to the home page).");
+const locale = z.enum(["en", "de"]).optional().describe("Language for the planner's summary/change-log response.");
+const activeBlockId = z.string().optional().describe("Hint: which block the user is currently focused on.");
+const screenshot = z.boolean().optional().describe("Auto-attach a draft screenshot of the mutated page when ops applied. Defaults to true; pass false to skip.");
+export function registerChatTools(server, client) {
+    server.tool("avocado-chat-plan", "High-level shortcut: send a natural-language instruction to the planner. The orchestrator decides whether to apply directly or surface a pending plan for approval. When ops apply, a draft screenshot of the touched page auto-attaches (disable with screenshot:false). Response may contain a `pendingPlanId` — if so, call avocado-approve-pending-plan or avocado-discard-pending-plan next.", { message, slug, locale, activeBlockId, screenshot }, async ({ screenshot: wantShot, ...args }) => {
+        try {
+            const res = await client.request("POST", "/chat", { body: client.scopedBody(args) });
+            return await chatResult(client, res, { screenshot: wantShot });
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-preview-plan", "Run the planner in plan-only mode: the orchestrator returns the would-apply ops without mutating draft state. The response includes a `pendingPlanId` (pass to avocado-approve-pending-plan) and a `planPreview` — per-op results (applied/skipped/failed) plus a structured before→after diff (changed pages/blocks/fields) — so you can review exactly what the plan would change before approving. To dry-run a hand-built ops array instead of an instruction, use avocado-dry-run-ops.", { message, slug, locale, activeBlockId }, async (args) => {
+        try {
+            return jsonResult(await client.request("POST", "/chat", {
+                body: client.scopedBody({ ...args, executionMode: "plan_only" }),
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-approve-pending-plan", "Apply the pending plan that's waiting for approval on the current session. Pass `pendingPlanId` from the prior chat response to protect against race conditions (the orchestrator rejects stale approvals). On successful apply, a draft screenshot of the touched page auto-attaches (disable with screenshot:false).", {
+        pendingPlanId: z.string().optional().describe("Id from the prior chat response's pendingPlanId field. Omit to apply whatever is pending (risky)."),
+        screenshot,
+    }, async ({ pendingPlanId, screenshot: wantShot }) => {
+        try {
+            const res = await client.request("POST", "/chat", {
+                body: client.scopedBody({ message: "approve", executionMode: "apply_pending_plan", pendingPlanId }),
+            });
+            return await chatResult(client, res, { screenshot: wantShot });
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-discard-pending-plan", "Discard the pending plan waiting for approval on the current session (user rejected the proposal). Clears orchestrator-side state.", {}, async () => {
+        try {
+            return jsonResult(await client.request("POST", "/chat", {
+                body: client.scopedBody({ message: "discard", executionMode: "discard_pending_plan" }),
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}

package/dist/tools/discovery.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OrchestratorClient } from "../orchestrator-client.ts";
+/** Read-only tools that help agents discover what they can edit. */
+export declare function registerDiscoveryTools(server: McpServer, client: OrchestratorClient): void;

package/dist/tools/discovery.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { getAllBlockMeta, getBlockJsonSchema } from "@avocadostudio-ai/shared";
+/**
+ * Fetch the target site's manifest, falling back to this process's registry.
+ *
+ * The fallback is *labelled* rather than silent. Quietly substituting the local
+ * built-ins is what the original bug did, and a confident wrong answer is worse
+ * than a hedged one: an agent that is told the list may not be the site's can
+ * check, while an agent that is told nothing cannot.
+ */
+async function loadManifest(client) {
+    try {
+        const manifest = await client.request("GET", "/blocks/manifest");
+        if (manifest && Array.isArray(manifest.blocks))
+            return { manifest, source: "orchestrator" };
+        throw new Error("manifest response had no blocks array");
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+            manifest: localRegistryManifest(),
+            source: "fallback:local-registry",
+            note: `Could not read the site's block manifest from ${client.config.orchestratorUrl}/blocks/manifest ` +
+                `(${reason}). What follows is the MCP server's own built-in registry, which is NOT ` +
+                `necessarily what this site can render — a site with custom blocks will have types not ` +
+                `listed here, and types listed here it cannot use. Verify before planning add_block ops.`
+        };
+    }
+}
+/** This process's registry, shaped like a manifest so both paths return one type. */
+function localRegistryManifest() {
+    const meta = getAllBlockMeta();
+    return {
+        version: 1,
+        blocks: Object.entries(meta).flatMap(([type, m]) => {
+            const propsSchema = getBlockJsonSchema(type);
+            if (!propsSchema)
+                return [];
+            return [{
+                    type,
+                    displayName: m.displayName,
+                    propsSchema,
+                    ...(m.category ? { category: m.category } : {}),
+                    ...(m.description ? { description: m.description } : {}),
+                    ...(m.chrome === true ? { chrome: true } : {}),
+                    ...(m.fields ? { fields: m.fields } : {}),
+                    ...(m.listFields ? { listFields: m.listFields } : {})
+                }];
+        })
+    };
+}
+/** Read-only tools that help agents discover what they can edit. */
+export function registerDiscoveryTools(server, client) {
+    server.tool("avocado-list-block-types", "List every block type THIS SITE can render (name, category, description, whether it is structural chrome). Read from the orchestrator, so it includes the site's own custom blocks. Call this before constructing add-block ops so you know which types exist.", {}, async () => {
+        const { manifest, source, note } = await loadManifest(client);
+        const entries = manifest.blocks.map((b) => ({
+            type: b.type,
+            displayName: b.displayName ?? b.type,
+            category: b.category ?? null,
+            description: b.description ?? null,
+            chrome: b.chrome === true,
+        }));
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ source, ...(note ? { warning: note } : {}), blockTypes: entries }, null, 2)
+                }]
+        };
+    });
+    server.tool("avocado-get-block-schema", "Return the JSON schema + field metadata for a block type on THIS SITE. Call this before add-block or update-block-props so you know the exact prop shape (required keys, enum options, list item fields, image aspect ratios).", {
+        type: z.string().describe("Block type name (e.g. 'Hero', 'CTA', 'FeatureGrid')."),
+    }, async ({ type }) => {
+        const { manifest, source, note } = await loadManifest(client);
+        const definition = manifest.blocks.find((b) => b.type === type);
+        if (!definition) {
+            const known = manifest.blocks.map((b) => b.type).join(", ");
+            return {
+                content: [{
+                        type: "text",
+                        text: `Unknown block type: ${type}.${note ? ` ${note}` : ""} Types available (${source}): ${known}`
+                    }],
+                isError: true,
+            };
+        }
+        /*
+         * `meta` is kept as its own key rather than flattened into the definition:
+         * the tool's documented response shape is { type, meta, jsonSchema }, and
+         * agents (and the phase2 tests) address it that way.
+         */
+        const meta = {
+            displayName: definition.displayName ?? definition.type,
+            category: definition.category ?? null,
+            description: definition.description ?? null,
+            chrome: definition.chrome === true,
+            ...(definition.fields ? { fields: definition.fields } : {}),
+            ...(definition.listFields ? { listFields: definition.listFields } : {}),
+        };
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify({ type, source, ...(note ? { warning: note } : {}), meta, jsonSchema: definition.propsSchema, defaultProps: definition.defaultProps ?? null }, null, 2),
+                }],
+        };
+    });
+}

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

package/dist/tools/history.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { jsonResult, errorResult } from "./_helpers.js";
+const slug = z.string().min(1).describe("Page slug to undo/redo (history is per-page).");
+export function registerHistoryTools(server, client) {
+    server.tool("avocado-undo-edit", "Undo the last change on a page. Returns the new preview version and whether further undo/redo is available.", { slug }, async ({ slug }) => {
+        try {
+            return jsonResult(await client.request("POST", "/history/undo", {
+                body: client.scopedBody({ slug }),
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-redo-edit", "Redo the most recently-undone change on a page.", { slug }, async ({ slug }) => {
+        try {
+            return jsonResult(await client.request("POST", "/history/redo", {
+                body: client.scopedBody({ slug }),
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-restore-version", "Jump to a specific version number from the history log (does not consume undo/redo stacks). Current state is pushed to undo first.", {
+        targetVersion: z.number().int().positive().describe("Version number from the history log."),
+    }, async ({ targetVersion }) => {
+        try {
+            return jsonResult(await client.request("POST", "/history/restore", {
+                body: client.scopedBody({ targetVersion }),
+            }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { OrchestratorClient } from "../orchestrator-client.ts";
+import type { CapabilityGate } from "../capabilities.ts";
+/**
+ * `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
+ * refuses afterwards, once the site has said something. See ../capabilities.ts
+ * for why registration must never wait on that.
+ */
+export declare function registerAllTools(server: McpServer, client: OrchestratorClient, gate?: CapabilityGate): void;

package/dist/tools/index.js

@@ -0,0 +1,28 @@
+import { registerDiscoveryTools } from "./discovery.js";
+import { registerPageTools } from "./pages.js";
+import { registerBlockTools } from "./blocks.js";
+import { registerSiteTools } from "./sites.js";
+import { registerMediaTools } from "./media.js";
+import { registerPublishingTools } from "./publishing.js";
+import { registerHistoryTools } from "./history.js";
+import { registerChatTools } from "./chat.js";
+import { registerPreviewTools } from "./preview.js";
+import { registerSessionTools } from "./sessions.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
+ * refuses afterwards, once the site has said something. See ../capabilities.ts
+ * for why registration must never wait on that.
+ */
+export function registerAllTools(server, client, gate) {
+    registerDiscoveryTools(server, client);
+    registerSessionTools(server, client, gate);
+    registerPageTools(server, client, gate);
+    registerBlockTools(server, client, gate);
+    registerSiteTools(server, client);
+    registerMediaTools(server, client);
+    registerPublishingTools(server, client);
+    registerHistoryTools(server, client);
+    registerChatTools(server, client);
+    registerPreviewTools(server, client);
+}

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

package/dist/tools/media.js

@@ -0,0 +1,84 @@
+import { z } from "zod";
+import { jsonResult, errorResult } from "./_helpers.js";
+/**
+ * Helper: orchestrator endpoints for upload/transcribe/interpret accept multipart only.
+ * MCP tool args are JSON, so we accept base64Data + mimeType and build a FormData in-process.
+ */
+function base64ToBlob(base64, mimeType) {
+    // Strip optional data URL prefix.
+    const data = base64.replace(/^data:[^;]+;base64,/, "");
+    const bytes = Buffer.from(data, "base64");
+    return new Blob([bytes], { type: mimeType });
+}
+export function registerMediaTools(server, client) {
+    server.tool("avocado-upload-image", "Upload an image to the orchestrator. Returns a URL usable as a block prop (Hero imageUrl, Card image, etc.). Accepts base64-encoded bytes + mime type.", {
+        base64Data: z.string().min(1).describe("Base64-encoded image bytes. Data URL prefix (data:image/...;base64,) is tolerated."),
+        mimeType: z.enum(["image/png", "image/jpeg", "image/webp", "image/gif"]),
+        filename: z.string().optional().describe("Optional filename hint; defaults to 'upload.<ext>'."),
+    }, async ({ base64Data, mimeType, filename }) => {
+        try {
+            const form = new FormData();
+            const ext = mimeType.split("/")[1];
+            form.append("image", base64ToBlob(base64Data, mimeType), filename ?? `upload.${ext}`);
+            return jsonResult(await client.request("POST", "/image/upload", { formData: form }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-generate-image", "Generate an image from a text prompt using the configured provider (OpenAI or Gemini). Returns a URL + alt text.", {
+        prompt: z.string().min(1).describe("Description of the image to generate."),
+        aspectRatio: z.enum(["landscape", "square", "portrait"]).optional(),
+        provider: z.enum(["openai", "gemini"]).optional().describe("Override the default image provider."),
+        model: z.string().optional().describe("Override the default model name."),
+    }, async (args) => {
+        try {
+            return jsonResult(await client.request("POST", "/image/generate", { body: args }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-search-unsplash", "Search Unsplash for stock photos matching a query. Returns an array of { imageUrl, thumbUrl, alt, author }.", {
+        q: z.string().min(1),
+        limit: z.number().int().min(1).max(20).optional(),
+        page: z.number().int().min(1).optional(),
+    }, async (args) => {
+        try {
+            return jsonResult(await client.request("GET", "/unsplash/search", { query: args }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-transcribe-audio", "Transcribe an audio clip to text via OpenAI Whisper. Accepts base64-encoded audio bytes.", {
+        base64Data: z.string().min(1),
+        mimeType: z.enum(["audio/mp3", "audio/mpeg", "audio/mp4", "audio/mpga", "audio/m4a", "audio/wav", "audio/webm"]),
+        filename: z.string().optional(),
+    }, async ({ base64Data, mimeType, filename }) => {
+        try {
+            const form = new FormData();
+            const ext = mimeType.split("/")[1];
+            form.append("audio", base64ToBlob(base64Data, mimeType), filename ?? `clip.${ext}`);
+            return jsonResult(await client.request("POST", "/audio/transcribe", { formData: form }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+    server.tool("avocado-interpret-image", "Run vision analysis on an image and return a one-sentence description (useful for alt text or screenshot-to-intent).", {
+        base64Data: z.string().min(1),
+        mimeType: z.enum(["image/png", "image/jpeg", "image/webp", "image/gif"]),
+        filename: z.string().optional(),
+    }, async ({ base64Data, mimeType, filename }) => {
+        try {
+            const form = new FormData();
+            const ext = mimeType.split("/")[1];
+            form.append("image", base64ToBlob(base64Data, mimeType), filename ?? `image.${ext}`);
+            return jsonResult(await client.request("POST", "/image/interpret", { formData: form }));
+        }
+        catch (err) {
+            return errorResult(err);
+        }
+    });
+}

package/dist/tools/pages.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 registerPageTools(server: McpServer, client: OrchestratorClient, gate?: CapabilityGate): void;