@avocadostudio-ai/mcp-server 0.2.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing the Work or
+      Derivative Works thereof, You may choose to offer, and charge a
+      fee for, acceptance of support, warranty, indemnity, or other
+      liability obligations and/or rights consistent with this License.
+      However, in accepting such obligations, You may act only on Your
+      own behalf and on Your sole responsibility, not on behalf of any
+      other Contributor, and only if You agree to indemnify, defend,
+      and hold each Contributor harmless for any liability incurred by,
+      or claims asserted against, such Contributor by reason of your
+      accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Avocado Studio Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,128 @@
+# Avocado Studio MCP Server
+
+Exposes Avocado Studio's page, block, and discovery tools over the [Model Context Protocol](https://modelcontextprotocol.io/) so MCP hosts (Claude Desktop, Claude Code, etc.) can drive a site the same way a human does in the editor.
+
+Each install is scoped to **one site**: `(session, siteId)` are bound at launch via env vars. The server is a thin wrapper over the orchestrator HTTP API — the orchestrator remains the source of truth for validation, persistence, undo history, and demo-mode gating.
+
+## Tool catalog (47 tools)
+
+| Group | Tools |
+|------|-------|
+| Discovery | `avocado-list-block-types`, `avocado-get-block-schema` |
+| Pages | `avocado-get-page`, `avocado-list-pages`, `avocado-create-page`, `avocado-rename-page`, `avocado-duplicate-page`, `avocado-remove-page`, `avocado-update-page-meta` |
+| Blocks | `avocado-add-block`, `avocado-update-block-props`, `avocado-remove-block`, `avocado-move-block`, `avocado-duplicate-block`, `avocado-add-list-item`, `avocado-update-list-item`, `avocado-remove-list-item`, `avocado-move-list-item` |
+| 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` |
+| 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) |
+
+Two transports, same tool registry:
+- **stdio** — `src/index.ts`. MCP host spawns the server as a subprocess. Best for local dev / Claude Code.
+- **HTTP (streamable)** — `src/http.ts`. Runs on a port; MCP hosts connect via URL + bearer token. Required for Claude Desktop's "Add custom connector" flow and remote deployments.
+
+## Install — Claude Code
+
+```bash
+claude mcp add avocado \
+  --env ORCHESTRATOR_URL=http://localhost:4200 \
+  --env AVOCADO_SESSION=dev \
+  --env AVOCADO_SITE_ID=avocado-stories \
+  -- npx -y @avocadostudio-ai/mcp-server
+```
+
+## Install — Claude Desktop
+
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "avocado-studio": {
+      "command": "npx",
+      "args": ["-y", "@avocadostudio-ai/mcp-server"],
+      "env": {
+        "ORCHESTRATOR_URL": "http://localhost:4200",
+        "AVOCADO_SESSION": "dev",
+        "AVOCADO_SITE_ID": "avocado-stories"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. Tools appear under `avocado-studio` and can be individually set to **Always allow / Ask / Never allow**.
+
+## Install — HTTP / custom connector
+
+Start the HTTP server:
+
+```bash
+AVOCADO_SITE_ID=avocado-stories \
+AVOCADO_MCP_BEARER_TOKEN=$(openssl rand -hex 32) \
+npx -y -p @avocadostudio-ai/mcp-server avocado-mcp-http
+# → avocado-studio MCP server listening on http://localhost:4300/mcp
+```
+
+Health probe (no auth): `curl http://localhost:4300/healthz`
+
+In Claude Desktop → **Settings → Connectors → Add custom connector**:
+
+- **URL:** `http://localhost:4300/mcp` (or a public HTTPS URL once deployed)
+- **Auth:** Bearer — paste the token you generated above
+
+Raw JSON-RPC example:
+
+```bash
+curl -X POST http://localhost:4300/mcp \
+  -H "Authorization: Bearer $TOKEN" \
+  -H "content-type: application/json" \
+  -H "accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+The HTTP transport runs in **stateless mode** — each request is independent, no session state on the server. POST only (GET/DELETE return 405).
+
+## Env vars
+
+| Var | Required | Default | Notes |
+|-----|----------|---------|-------|
+| `AVOCADO_SITE_ID` | **yes** | — | Which site this install edits (e.g. `avocado-stories`). |
+| `ORCHESTRATOR_URL` | no | `http://localhost:4200` | Points at the Avocado Studio orchestrator. |
+| `AVOCADO_SESSION` | no | `dev` | Session key that scopes draft state. |
+| `AVOCADO_PUBLISH_TOKEN` | no | — | Required only for `avocado-publish-content`. Must match the orchestrator's `DRAFT_MODE_SECRET`. Omit to disable publish through MCP. |
+| `AVOCADO_MCP_BEARER_TOKEN` | **yes (HTTP mode)** | — | Shared secret clients must send as `Authorization: Bearer <token>`. Generate with `openssl rand -hex 32`. Only read by `src/http.ts`. |
+| `AVOCADO_MCP_PORT` | no | `4300` | Port for HTTP mode. |
+
+## Design notes
+
+- **Thin wrapper, single source of truth.** Every mutation goes through `POST /ops`, which runs the existing Zod validation, ops-engine, undo stack, version log, and demo-mode gate. The MCP server never mutates state directly.
+- **Discovery before mutation.** `avocado-list-block-types` + `avocado-get-block-schema` are the intended entry points for agents. Calling `avocado-add-block` without first fetching the schema risks invalid prop shapes → 400 from the orchestrator.
+- **Read-only vs. destructive.** Discovery and `avocado-get-page` / `avocado-list-pages` are safe to mark **Always allow**. Mutations should stay on **Ask**.
+- **Block registration.** Importing the `@avocadostudio-ai/shared` package root is enough to trigger every block's `registerBlock()` side effect — its barrel re-exports `./blocks/index.ts`. Do **not** deep-import `@avocadostudio-ai/shared/src/...`: the published tarball ships `dist/` only, and the package now declares an `exports` map that closes that path off.
+
+## Tests
+
+```bash
+pnpm --filter @avocadostudio-ai/mcp-server test
+pnpm --filter @avocadostudio-ai/mcp-server typecheck
+```
+
+Tests stub `fetch` to assert HTTP call shape. They don't start a real orchestrator.
+
+## Forward plan
+
+### Phase 3a — HTTP transport ✅ shipped
+`StreamableHTTPServerTransport` mounted in `src/http.ts` with bearer auth (`AVOCADO_MCP_BEARER_TOKEN`). Stateless mode, POST-only, `/healthz` probe. Testable locally; ready to deploy.
+
+### Phase 3b — hosted deployment + OAuth
+1. **Deploy** the `avocado-mcp-http` process to Render alongside the orchestrator. Public HTTPS URL required by Claude Desktop's connector flow.
+2. **OAuth gateway** — AEM uses "Complete the Adobe login flow". Add OAuth 2.1 with PKCE in front of `/mcp` so bearer tokens are minted via an auth code exchange rather than shared-secret copy/paste. Token claims encode `siteId` (keeps per-site scoping).
+3. **Claude connector directory submission** — public HTTPS URL, OAuth endpoints, logo, description, per-tool permission matrix screenshot. Lands "Avocado Studio Content MCP Service" in Claude Desktop's built-in connector list.
+4. **Safety** — per-tool `readOnlyHint` annotations so Claude auto-allows reads; audit log piggybacking on existing orchestrator telemetry; rate limit on `/mcp` (reuse demo-mode's per-IP limiter).
+
+### Phase 4 — nice-to-haves
+- MCP resources (not just tools) for page + site-config, so hosts can pin them as context without a tool call.
+- MCP prompts (slash-command templates) for common flows: "draft a pricing page", "refresh hero copy site-wide".
+- Typed client SDK generated from the orchestrator's OpenAPI so the wrapper stays auto-synced.

package/dist/capabilities.d.ts

@@ -0,0 +1,63 @@
+/**
+ * What the site behind this install will actually honour.
+ *
+ * All ~47 tools register unconditionally, whatever the adapter behind them
+ * supports. On a CMS-routed site `avocado-create-page` applies cleanly,
+ * previews correctly and reports success — then produces a page that can never
+ * be published, and that fails the entire publish transaction when tried. An
+ * agent told "this site cannot create pages" is strictly more useful than one
+ * that can create a broken one.
+ *
+ * Three properties this has to have, and they are what the design is for:
+ *
+ * 1. **Registration must never wait on the network.** In stdio, tools are
+ *    registered before the transport is even connected; making that block on
+ *    an HTTP call means the MCP server fails to start whenever the site is
+ *    down. So everything registers, and gated tools are disabled afterwards,
+ *    asynchronously, once the site has answered.
+ *
+ * 2. **Silence is permission.** An orchestrator that is unreachable, in demo
+ *    mode, or simply older than this field all produce the same answer as an
+ *    adapter that declared nothing: unknown, and unknown permits. A
+ *    restrictive default would withdraw working tools from every existing
+ *    install the moment the network hiccuped.
+ *
+ * 3. **Hiding is not enough.** Some hosts cache the tool list and ignore
+ *    `notifications/tools/list_changed`, and the SDK's own refusal for a
+ *    disabled tool ("Tool X disabled") carries no reason. Gated handlers
+ *    therefore also refuse at call time, with text that says why.
+ */
+import type { OrchestratorClient } from "./orchestrator-client.ts";
+export type CapabilityKey = "createPages" | "deletePages" | "structuralEdits";
+export type CapabilitySnapshot = {
+    createPages: boolean;
+    deletePages: boolean;
+    structuralEdits: boolean;
+    /** Where the answer came from. `unknown` is the permissive default. */
+    source: "orchestrator" | "unknown";
+    /** Present when `source` is "unknown" and we tried — why we could not tell. */
+    reason?: string;
+};
+/** A tool handle, narrowed to the two methods we use. Avoids importing the SDK's internals. */
+type ToolHandle = {
+    enable(): void;
+    disable(): void;
+};
+export interface CapabilityGate {
+    /** Refusal text when the site has explicitly said no, else null. */
+    refuse(key: CapabilityKey): string | null;
+    /** Hand the gate a registered tool so it can hide it once the site answers. */
+    track(key: CapabilityKey, tool: ToolHandle): void;
+    /** Ask the orchestrator and apply the answer to every tracked tool. */
+    refresh(): Promise<CapabilitySnapshot>;
+    /** The current answer, without asking. */
+    snapshot(): CapabilitySnapshot;
+}
+export type CapabilityGateOptions = {
+    /** How long an answer stays good. Default 60s. */
+    ttlMs?: number;
+    /** How long to wait for the probe. Default 2s — this must never delay a tool call much. */
+    timeoutMs?: number;
+};
+export declare function createCapabilityGate(client: OrchestratorClient, options?: CapabilityGateOptions): CapabilityGate;
+export {};

package/dist/capabilities.js

@@ -0,0 +1,116 @@
+/**
+ * What the site behind this install will actually honour.
+ *
+ * All ~47 tools register unconditionally, whatever the adapter behind them
+ * supports. On a CMS-routed site `avocado-create-page` applies cleanly,
+ * previews correctly and reports success — then produces a page that can never
+ * be published, and that fails the entire publish transaction when tried. An
+ * agent told "this site cannot create pages" is strictly more useful than one
+ * that can create a broken one.
+ *
+ * Three properties this has to have, and they are what the design is for:
+ *
+ * 1. **Registration must never wait on the network.** In stdio, tools are
+ *    registered before the transport is even connected; making that block on
+ *    an HTTP call means the MCP server fails to start whenever the site is
+ *    down. So everything registers, and gated tools are disabled afterwards,
+ *    asynchronously, once the site has answered.
+ *
+ * 2. **Silence is permission.** An orchestrator that is unreachable, in demo
+ *    mode, or simply older than this field all produce the same answer as an
+ *    adapter that declared nothing: unknown, and unknown permits. A
+ *    restrictive default would withdraw working tools from every existing
+ *    install the moment the network hiccuped.
+ *
+ * 3. **Hiding is not enough.** Some hosts cache the tool list and ignore
+ *    `notifications/tools/list_changed`, and the SDK's own refusal for a
+ *    disabled tool ("Tool X disabled") carries no reason. Gated handlers
+ *    therefore also refuse at call time, with text that says why.
+ */
+const PERMISSIVE = {
+    createPages: true,
+    deletePages: true,
+    structuralEdits: true,
+    source: "unknown"
+};
+/** Human-readable name for each capability, used in refusal text. */
+const WHAT = {
+    createPages: "create pages",
+    deletePages: "delete pages",
+    structuralEdits: "add, remove, move or duplicate blocks"
+};
+export function createCapabilityGate(client, options = {}) {
+    const ttlMs = options.ttlMs ?? 60_000;
+    const timeoutMs = options.timeoutMs ?? 2_000;
+    let current = PERMISSIVE;
+    let fetchedAt = 0;
+    let inFlight = null;
+    const tracked = [];
+    function apply(next) {
+        current = next;
+        for (const { key, tool } of tracked) {
+            // enable()/disable() are idempotent, so this needs no diffing.
+            if (next[key])
+                tool.enable();
+            else
+                tool.disable();
+        }
+    }
+    async function probe() {
+        /*
+         * `/status/planner`, not `/whoami`: whoami awaits the adapter bootstrap —
+         * the cold CMS read that can take minutes on a large site — and asking
+         * "what may I do?" must not be made to wait on "what is in the draft?".
+         * It is also not blocked in demo mode, where /whoami is.
+         */
+        try {
+            const status = await client.request("GET", "/status/planner", {
+                signal: AbortSignal.timeout(timeoutMs)
+            });
+            const caps = status?.capabilities;
+            if (!caps) {
+                // An orchestrator older than this field. Not an error, and not a "no".
+                return { ...PERMISSIVE, reason: "this orchestrator does not report capabilities" };
+            }
+            return {
+                createPages: caps.createPages !== false,
+                deletePages: caps.deletePages !== false,
+                structuralEdits: caps.structuralEdits !== false,
+                source: "orchestrator"
+            };
+        }
+        catch (err) {
+            return { ...PERMISSIVE, reason: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    return {
+        snapshot: () => current,
+        refuse(key) {
+            if (current[key])
+                return null;
+            return (`This site cannot ${WHAT[key]}. Its content adapter has declared the capability ` +
+                `unavailable, so the change would apply to the draft and then fail to publish. ` +
+                `Call avocado-whoami to see what this site does support.`);
+        },
+        track(key, tool) {
+            tracked.push({ key, tool });
+            if (!current[key])
+                tool.disable();
+        },
+        async refresh() {
+            const now = Date.now();
+            if (inFlight)
+                return inFlight;
+            if (current.source === "orchestrator" && now - fetchedAt < ttlMs)
+                return current;
+            inFlight = probe()
+                .then((next) => {
+                fetchedAt = Date.now();
+                apply(next);
+                return next;
+            })
+                .finally(() => { inFlight = null; });
+            return inFlight;
+        }
+    };
+}

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Install-time configuration bound via environment variables.
+ *
+ * Each MCP install is scoped to exactly one (session, siteId) pair. The client
+ * (Claude Desktop / Claude Code) passes these through when it spawns the stdio
+ * server, so tool calls don't need to accept session/siteId as arguments.
+ */
+export type McpConfig = {
+    orchestratorUrl: string;
+    session: string;
+    siteId: string;
+    /** Optional bearer token for /publish. Falls back to env DRAFT_MODE_SECRET if not set. */
+    publishToken?: string;
+};
+export declare function loadConfig(env?: NodeJS.ProcessEnv): McpConfig;

package/dist/config.js

@@ -0,0 +1,17 @@
+/**
+ * Install-time configuration bound via environment variables.
+ *
+ * Each MCP install is scoped to exactly one (session, siteId) pair. The client
+ * (Claude Desktop / Claude Code) passes these through when it spawns the stdio
+ * server, so tool calls don't need to accept session/siteId as arguments.
+ */
+export function loadConfig(env = process.env) {
+    const orchestratorUrl = (env.ORCHESTRATOR_URL ?? "http://localhost:4200").replace(/\/+$/, "");
+    const session = env.AVOCADO_SESSION?.trim() || "dev";
+    const siteId = env.AVOCADO_SITE_ID?.trim() || "";
+    if (!siteId) {
+        throw new Error("AVOCADO_SITE_ID is required. Set it to the site this MCP install should edit (e.g. 'avocado-stories').");
+    }
+    const publishToken = env.AVOCADO_PUBLISH_TOKEN?.trim() || undefined;
+    return { orchestratorUrl, session, siteId, publishToken };
+}

package/dist/http-auth.d.ts

@@ -0,0 +1,14 @@
+import type { IncomingMessage } from "node:http";
+export type AuthResult = {
+    ok: true;
+} | {
+    ok: false;
+    status: 401 | 403;
+    message: string;
+};
+/**
+ * Validate a bearer token on an incoming HTTP request. Returns a result object
+ * instead of throwing so the caller can still reply with a clean JSON-RPC error.
+ * Uses a constant-time compare to resist timing attacks.
+ */
+export declare function checkBearer(req: IncomingMessage, expected: string): AuthResult;

package/dist/http-auth.js

@@ -0,0 +1,26 @@
+/**
+ * Validate a bearer token on an incoming HTTP request. Returns a result object
+ * instead of throwing so the caller can still reply with a clean JSON-RPC error.
+ * Uses a constant-time compare to resist timing attacks.
+ */
+export function checkBearer(req, expected) {
+    const header = req.headers.authorization;
+    if (!header || typeof header !== "string") {
+        return { ok: false, status: 401, message: "missing Authorization header" };
+    }
+    const match = /^Bearer\s+(.+)$/i.exec(header.trim());
+    if (!match) {
+        return { ok: false, status: 401, message: "Authorization header must be 'Bearer <token>'" };
+    }
+    const presented = match[1];
+    if (presented.length !== expected.length) {
+        return { ok: false, status: 403, message: "invalid token" };
+    }
+    let mismatch = 0;
+    for (let i = 0; i < presented.length; i++) {
+        mismatch |= presented.charCodeAt(i) ^ expected.charCodeAt(i);
+    }
+    if (mismatch !== 0)
+        return { ok: false, status: 403, message: "invalid token" };
+    return { ok: true };
+}

package/dist/http.d.ts

@@ -0,0 +1,13 @@
+#!/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
+ */
+export {};