# Etch Agent Bridge

Local Chrome extension plus MCP server for controlling the Etch builder from MCP-capable agents such as Claude, Codex, opencode, Cursor, or similar tools.

This is not an AI chat product and it does not need model API keys. Your agent client provides the AI model. This project only connects that client to an already-open Etch builder tab through the Etch Public API.

## What You Get

- A Chrome MV3 extension that can see Etch builder tabs only when the URL contains `etch=magic`.
- A local stdio MCP server that exposes Etch tools to your agent.
- A local WebSocket relay on `ws://127.0.0.1:8787` so several MCP clients can share the same browser extension.
- Direct Etch edits for blocks, styles, loops, components, navigation, history, UI color scheme, and document saving.

## Prerequisites

- Git.
- Bun 1.x or newer: <https://bun.sh/docs/installation>
- Chrome, Chromium, Brave, Edge, or another Chromium browser that supports unpacked extensions.
- An authenticated WordPress admin session with Etch installed.
- An Etch builder page where `window.etch` is available.
- One MCP-capable client, for example Claude Code, Claude Desktop, Codex, opencode, Cursor, or Windsurf.

## Install And Build

Clone the repo and build the extension:

```bash
git clone https://github.com/honestlydesign/etch-agent-extension.git
cd etch-agent-extension
bun install
bun run build
```

The browser extension build is created at:

```text
apps/extension/dist
```

## Load The Extension

1. Open `chrome://extensions` in your Chromium browser.
2. Enable `Developer mode`.
3. Click `Load unpacked`.
4. Select the `apps/extension/dist` folder from this repo.
5. Keep the extension installed while you use an MCP agent.

After every `bun run build`, reload the extension on `chrome://extensions` and reload the Etch builder tab.

The extension has a status popup only. It does not contain an editor UI.

## Open An Etch Target

1. Log into WordPress in the same browser.
2. Open the Etch builder for the page or template you want to edit.
3. Add `etch=magic` to the URL.

Examples:

```text
https://example.test/wp-admin/admin.php?page=etch-builder&etch=magic
https://example.test/wp-admin/admin.php?page=etch-builder&post=123&etch=magic
```

If the URL already has query parameters, use `&etch=magic`. If it has no query parameters, use `?etch=magic`.

The extension intentionally ignores pages without `etch=magic`.

## Configure MCP

Each MCP client should launch the same local server:

```bash
cd /ABS/PATH/etch-agent-extension && bun run apps/mcp/src/index.ts --client-name <client-name>
```

Use the absolute path to your cloned repo. If the MCP client cannot find `bun`, run `which bun` and replace `bun` in the command with the absolute Bun path.

The first MCP server process starts the relay host on port `8787`. Later MCP clients connect through that existing relay. This means Claude, Codex, and opencode can all have this MCP configured at the same time. Only one agent should mutate the Etch canvas at a time.

The JSON examples below show only the relevant MCP entry. If your client already has a config file, merge the `etch-agent` entry into it instead of replacing the whole file. Do not commit project MCP config with your private absolute path.

### Claude Code Or Claude Desktop

For Claude Code, use a project `.mcp.json` or your normal Claude MCP config. For Claude Desktop, put the same `mcpServers` block in `claude_desktop_config.json`.

```json
{
  "mcpServers": {
    "etch-agent": {
      "command": "bash",
      "args": [
        "-lc",
        "cd /ABS/PATH/etch-agent-extension && exec bun run apps/mcp/src/index.ts --client-name claude"
      ]
    }
  }
}
```

Restart Claude after changing the config.

### Codex

Add an MCP server entry to `~/.codex/config.toml`:

```toml
[mcp_servers.etch-agent]
command = "bash"
args = ["-lc", "cd /ABS/PATH/etch-agent-extension && exec bun run apps/mcp/src/index.ts --client-name codex"]
```

Restart Codex after changing the config.

### opencode

Add a local MCP entry to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "etch-agent": {
      "type": "local",
      "command": [
        "bash",
        "-lc",
        "cd /ABS/PATH/etch-agent-extension && exec bun run apps/mcp/src/index.ts --client-name opencode"
      ]
    }
  }
}
```

Restart opencode after changing the config.

### Cursor, Windsurf, And Other MCP Clients

Most MCP clients use the same JSON shape as Claude:

```json
{
  "mcpServers": {
    "etch-agent": {
      "command": "bash",
      "args": [
        "-lc",
        "cd /ABS/PATH/etch-agent-extension && exec bun run apps/mcp/src/index.ts --client-name cursor"
      ]
    }
  }
}
```

If your client supports a `cwd` field, you can also set `cwd` to the repo path and use `command: "bun"` with `args: ["run", "apps/mcp/src/index.ts", "--client-name", "your-client"]`.

## Verify The Setup

1. Start or restart your MCP client.
2. Open an Etch builder tab with `etch=magic`.
3. Open the extension popup. It should show relay and target status.
4. Ask your agent to list Etch targets or inspect the selected block.

Useful first prompt:

```text
Use the Etch MCP tools to list available targets, inspect the selected block, and do not save anything.
```

If the agent sees a target, the extension and MCP server are connected.

## Save Behavior

Most mutation tools change the Etch canvas immediately but do not persist to the WordPress database until `etch_save_document` is called.

The agent should call `etch_save_document` only when you explicitly ask it to save. Until then, browser navigation or document switching can discard unsaved edits, depending on Etch behavior.

Component upserts and component deletes are different: Etch persists them immediately through the component API.

## Troubleshooting

No Etch target appears:

- Make sure the builder URL contains `etch=magic`.
- Make sure the WordPress session is authenticated in the same browser.
- Make sure the extension is loaded from `apps/extension/dist`.
- Reload the extension and then reload the Etch builder tab.
- Ask the agent to call `etch_list_targets` again.

The MCP client starts but `bun` is not found:

- Run `which bun`.
- Replace `bun` in the MCP config command with that absolute path.
- Restart the MCP client.

Port `8787` is busy:

- If another Etch Agent Bridge MCP process is running, that is expected. New clients connect to it.
- If a different process owns the port, stop that process and restart the MCP client.
- `--relay-port <port>` exists for tests, but the browser extension expects `8787` by default.

The extension is connected but Etch tools fail:

- Confirm the page is an actual Etch builder page.
- Confirm `window.etch` exists in that builder session.
- Reload the builder after reloading the extension.

Changes are not visible after editing code:

- Run `bun run build`.
- Reload the unpacked extension.
- Reload the Etch builder tab.

## Development Commands

```bash
bun install
bun run build
bun run typecheck
bun run test
bun run dev:mcp
```

`bun run dev:mcp` starts the MCP server directly for local development. In normal use, your MCP client starts the server from its config.

## Architecture

- `apps/extension` is the Chrome MV3 extension with a status popup, background relay connection, isolated content script, and MAIN-world `window.etch` bridge.
- `apps/mcp` is the stdio MCP server. Each running MCP process either hosts the relay on `ws://127.0.0.1:8787` or connects to the existing relay as a client.
- `packages/shared` contains shared schemas, target types, bridge protocol, activation logic, and MCP tool names.
- `skills/etchapi/SKILL.md` describes the agent workflow for agents working inside this repo.

## Tool Coverage

| Area | Tools |
| --- | --- |
| Targets and status | `etch_list_targets`, `etch_get_active_target`, `etch_set_active_target`, `etch_get_status`, `etch_get_last_apply_result` |
| Blocks | `etch_get_selected_block`, `etch_get_document_tree`, `etch_get_block_json`, `etch_find_blocks`, `etch_insert_blocks`, `etch_replace_block`, `etch_update_block`, `etch_mutate_block_attributes`, `etch_duplicate_block`, `etch_move_block`, `etch_delete_block` |
| Styles | `etch_list_styles`, `etch_apply_style_patch`, `etch_delete_style`, `etch_get_style_variable`, `etch_remove_style_variable` |
| Components | `etch_list_components`, `etch_get_component_json`, `etch_upsert_agent_component`, `etch_delete_agent_component` |
| Navigation | `etch_list_posts`, `etch_list_templates`, `etch_open_post`, `etch_open_template`, `etch_get_navigation_context` |
| Loops | `etch_list_loops`, `etch_upsert_loop`, `etch_delete_loop`, `etch_bind_loop_to_block` |
| History and UI | `etch_undo`, `etch_redo`, `etch_get_color_scheme`, `etch_set_color_scheme` |
| Save | `etch_save_document` |

Fields and global stylesheets are not implemented in this bridge.

## Validation Policy

This bridge is a thin pass-through to the Etch Public API. The MCP layer and page-bridge layer validate the structural shape of payloads with Zod, but they do not try to decide which content is safe or valid for Etch.

- Selectors, class names, component keys, loop keys, CSS variable names, text, attribute values, CSS values, and JSON loop data are passed through.
- Block types are forwarded to Etch. Etch is the source of truth for supported block types, tags, attributes, and payload shapes.
- If Etch rejects a payload, the `window.etch` error is returned through the MCP tool result.

Mutations apply directly to the Etch canvas. Use `etch_undo` or `etch_redo` for Etch history operations, and use `etch_save_document` only when the document should be persisted.