> ## Documentation Index
> Fetch the complete documentation index at: https://docs.avocadostudio.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# MCP Server
> Drive Avocado Studio from Claude Desktop, Claude Code, or any Model Context Protocol host.
The **Avocado Studio MCP Server** exposes pages, blocks, and block discovery as Model Context Protocol tools. Plug it into Claude Desktop (or any MCP host) and Claude can read and edit your site with the same operations the web editor uses.
Current status: **Phases 1, 2, 3a shipped** — 40 tools, both **stdio** and **streamable HTTP** transports. One site per install. Claude connector directory listing + OAuth land in Phase 3b.
## What you get
```mermaid theme={null}
flowchart LR
claude[Claude Desktop / Code]
mcp[Avocado MCP Server
stdio]
orch[Avocado Orchestrator
HTTP :4200]
db[(SQLite session state)]
claude <--> |stdio JSON-RPC| mcp
mcp --> |REST| orch
orch --> db
```
The MCP server is a thin wrapper: every mutation goes through `POST /ops` on the orchestrator, so Zod validation, undo history, version log, and demo-mode gating all still apply.
## Tool catalog
### Discovery
| Tool | What it does |
| -------------------------- | -------------------------------------------------------------------------------------- |
| `avocado-list-block-types` | Lists every block type the site can render (Hero, CTA, FAQAccordion, …). |
| `avocado-get-block-schema` | Returns the JSON schema + field metadata for a block type — call before writing props. |
### Pages
| Tool | What it does |
| -------------------------- | ---------------------------------------------------------------- |
| `avocado-get-page` | Fetches a page's full draft document. |
| `avocado-list-pages` | Lists every page slug in the draft. |
| `avocado-create-page` | Creates a new page with an initial blocks array. |
| `avocado-rename-page` | Changes slug and/or title. Internal links rewrite automatically. |
| `avocado-duplicate-page` | Clones a page, optionally under a new slug. |
| `avocado-remove-page` | Deletes a page. Undo-able. |
| `avocado-update-page-meta` | Patches SEO fields (title, description, ogImage). |
### Blocks
| Tool | What it does |
| ---------------------------- | --------------------------------------------------------------------------- |
| `avocado-add-block` | Inserts a new block into a page. |
| `avocado-update-block-props` | Patches one or more props on an existing block. |
| `avocado-remove-block` | Deletes a block. |
| `avocado-move-block` | Reorders a block within a page. |
| `avocado-duplicate-block` | Clones a block, optionally to another page. |
| `avocado-add-list-item` | Appends/inserts an item into a block's list field (features, cards, faqs…). |
| `avocado-update-list-item` | Patches fields on a single list item by index. |
| `avocado-remove-list-item` | Removes a list item by index. |
| `avocado-move-list-item` | Reorders a list item. |
### Sites
| Tool | What it does |
| ---------------------------- | -------------------------------------------------------------------------- |
| `avocado-register-site` | Register/update the site entry (preview URL, name, port, purpose, secret). |
| `avocado-list-sites` | List every site registered under the current session. |
| `avocado-get-site-config` | Fetch the site's config (name, logo, tone, purpose, nav labels/groups). |
| `avocado-update-site-config` | Patch the site config (name, logo, navLabels, navGroups). Undo-able. |
### Media
| Tool | What it does |
| -------------------------- | -------------------------------------------------------------------------------------------- |
| `avocado-upload-image` | Upload an image (base64) to the orchestrator; returns a URL usable as a block prop. |
| `avocado-generate-image` | Generate an image from a prompt via OpenAI or Gemini. |
| `avocado-search-unsplash` | Search Unsplash for stock photos. |
| `avocado-transcribe-audio` | Transcribe a base64 audio clip via OpenAI Whisper. |
| `avocado-interpret-image` | Vision analysis: image → one-sentence summary (useful for alt text or screenshot-to-intent). |
### Publishing
| Tool | What it does |
| ------------------------------ | --------------------------------------------------------------------- |
| `avocado-compute-publish-diff` | Diff between the current draft and the last published snapshot. |
| `avocado-publish-content` | Publish the draft to the live site. Requires `AVOCADO_PUBLISH_TOKEN`. |
| `avocado-get-publish-status` | Publish tracker: target type, state, last deployment, URLs. |
| `avocado-list-snapshots` | List published snapshots (commits) available for restore. |
| `avocado-restore-snapshot` | Rewind the draft to a published snapshot by commit sha. |
### History
| Tool | What it does |
| ------------------------- | ---------------------------------------------------------------------------- |
| `avocado-undo-edit` | Undo the last change on a page. |
| `avocado-redo-edit` | Redo the last undone change. |
| `avocado-restore-version` | Jump to a specific version from the history log (doesn't consume undo/redo). |
### Planner
| Tool | What it does |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `avocado-chat-plan` | Send a natural-language instruction to the planner; orchestrator figures out which ops to apply and runs them. May return a `pendingPlanId` if the plan needs approval. |
| `avocado-preview-plan` | Run the planner in plan-only mode — returns the would-apply ops without mutating state. Ideal for review-before-approve flows. |
| `avocado-approve-pending-plan` | Apply the pending plan waiting for approval. Pass `pendingPlanId` from the prior chat response to protect against race conditions. |
| `avocado-discard-pending-plan` | Reject/discard the pending plan. |
### Preview
| Tool | What it does |
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `avocado-screenshot-page` | Captures a full-page screenshot of the draft (via Playwright) and returns it as an inline JPEG. Required for visual feedback in chat-only hosts like Claude Desktop that can't render the live preview iframe. Site must have a `previewUrl` registered. |
## Install
### Claude Desktop
Open `~/Library/Application Support/Claude/claude_desktop_config.json` and add:
```json theme={null}
{
"mcpServers": {
"avocado-studio": {
"command": "npx",
"args": ["tsx", "/absolute/path/to/apps/mcp-server/src/index.ts"],
"env": {
"ORCHESTRATOR_URL": "http://localhost:4200",
"AVOCADO_SESSION": "dev",
"AVOCADO_SITE_ID": "avocado-stories"
}
}
}
}
```
Restart Claude Desktop. Open **Settings → Connectors → avocado-studio** to set per-tool permissions (**Always allow / Ask / Never allow**). The discovery and `get` tools are safe to auto-allow; keep mutations on **Ask**.
### Claude Code
```bash theme={null}
claude mcp add avocado \
--env ORCHESTRATOR_URL=http://localhost:4200 \
--env AVOCADO_SESSION=dev \
--env AVOCADO_SITE_ID=avocado-stories \
-- npx tsx /absolute/path/to/apps/mcp-server/src/index.ts
```
### HTTP transport (remote / custom connector)
Start the HTTP server:
```bash theme={null}
AVOCADO_SITE_ID=avocado-stories \
AVOCADO_MCP_BEARER_TOKEN=$(openssl rand -hex 32) \
pnpm --filter @ai-site-editor/mcp-server start:http
```
Output: `avocado-studio MCP server listening on http://localhost:4300/mcp`
In Claude Desktop → **Settings → Connectors → Add custom connector**:
* **URL:** `http://localhost:4300/mcp`
* **Auth:** Bearer token — the value you passed as `AVOCADO_MCP_BEARER_TOKEN`
Stateless mode — each POST is a self-contained JSON-RPC call. Health probe at `GET /healthz` (no auth) for load balancers.
### Environment variables
| Var | Required | Default | Notes |
| -------------------------- | --------------- | ----------------------- | --------------------------------------------------------------------------------------------------- |
| `AVOCADO_SITE_ID` | yes | — | Which site this install edits. |
| `ORCHESTRATOR_URL` | no | `http://localhost:4200` | Points at the orchestrator. |
| `AVOCADO_SESSION` | no | `dev` | Session key that scopes draft state. |
| `AVOCADO_PUBLISH_TOKEN` | no | — | Only needed to enable `avocado-publish-content`. Must match the orchestrator's `DRAFT_MODE_SECRET`. |
| `AVOCADO_MCP_BEARER_TOKEN` | yes (HTTP mode) | — | Bearer token clients must present. Only read by `src/http.ts`. |
| `AVOCADO_MCP_PORT` | no | `4300` | Port for HTTP mode. |
## How agents should use it
1. **Discover first.** Call `avocado-list-block-types` once, then `avocado-get-block-schema` for any type you're about to add or edit. The schema tells you which props are required and which enum values are valid.
2. **Read before mutate.** Call `avocado-get-page` to get block ids before `avocado-update-block-props` — block ids are stable and opaque.
3. **Prefer structural ops over full rewrites.** `avocado-update-list-item` with an index + patch is cheaper and safer than replacing the whole list via `avocado-update-block-props`.
## Roadmap
* **Phase 1 + 2 + 3a — shipped.** 40 tools across 8 groups. Stdio transport (local install) and streamable HTTP transport (custom connectors, remote deploy) both work with the same tool registry. Approve/reject plan loop supported.
* **Phase 3b** — Hosted deployment (Render) + OAuth in front of `/mcp` (replaces shared-secret bearer with proper login flow, same UX as "AEM Content MCP Service"). Submit to Claude's connector directory. Add per-tool read-only annotations and audit logging.
* **Phase 4** — MCP resources (pin a page as context), MCP prompts (slash-command templates), typed client generated from the orchestrator OpenAPI.