astroplayground-bridge

Connects an MCP client (Claude Code, Claude Desktop) to an Astro Playground browser tab, so a coding agent can edit the in-browser Astro project while you watch the live preview:

MCP client ──stdio──▶ astroplayground-bridge ◀──WebSocket── playground tab

Browsers can't accept inbound connections, so the tab dials out to this process on ws://127.0.0.1:43210 when you click Agent in the playground toolbar. MCP tool calls are forwarded over that socket and executed inside the page against the in-browser workspace; the agent never needs a server.

Setup

Claude Code:

claude mcp add astro-playground -- npx -y astroplayground-bridge

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "astro-playground": {
      "command": "npx",
      "args": ["-y", "astroplayground-bridge"]
    }
  }
}

Then open the playground, click Agent in the toolbar, and start a conversation. The MCP client launches the bridge automatically on demand.

Tools

| Tool | What it does | | --- | --- | | playground_status | Connection check, preview mode, routes in /src/pages | | list_files | All project file paths | | read_file | Read one file | | write_file | Create/overwrite a file (shows up in the editor immediately) | | delete_file | Delete a file (/package.json, /astro.config.mjs protected) | | build | Build in the browser, refresh the preview, return the build log | | get_page | Built HTML for a route, with data-pg-file/data-pg-loc source annotations |

The intended loop: edit with write_file → build → verify with get_page (the annotations map any rendered element back to its source file and line).

Options

• --port <n> or ASTRO_PLAYGROUND_BRIDGE_PORT — WebSocket port (default 43210). The playground page must be told the same port if you change it.

Notes

• One tab at a time: a newly connected tab replaces the previous one.
• If no tab is connected, every tool returns a clear error telling the user to click Agent in the playground.
• Loopback only — the WebSocket listener binds 127.0.0.1 and has no auth; the browser and the MCP client must be on the same machine.