# BlockbenchMCP

> **:uk: English** · [:ru: Русский](README.ru.md)

Connect **Blockbench** to AI assistants (OpenCode, Claude, and others) via the **Model Context Protocol (MCP)**. The AI can directly control your active Blockbench project: create and delete cubes, inspect the model and its element structure.

## Architecture

```
AI assistant (MCP) ←→ mcp-server (Node.js) ←Socket.IO:9999→ mcp-plugin (Blockbench)
```

- **`apps/mcp-plugin`** — Blockbench plugin. Receives commands over Socket.IO (port `9999`) and executes them in the current project.
- **`apps/mcp-server`** — MCP server. Implements the MCP protocol over stdio and forwards commands to the plugin.
- **`packages/shared`** — shared TypeScript types.

## Tools

| Tool | Description |
|---|---|
| `blockbench.hello` | Checks the connection to Blockbench |
| `blockbench.get_project_info` | Info about the current project (format, texture size, element/texture/animation counts) |
| `blockbench.list_elements` | Lists elements (cubes) in the project with uuid and name |
| `blockbench.add_cube` | Creates a cube (position, size, auto-UV, shade, color, uv_offset) |
| `blockbench.remove_element` | Removes an element by name or uuid |

## Installation

### Prerequisites

- **Blockbench** (current version, tested on 5.x)
- **Node.js** 20+
- **pnpm** (`npm install -g pnpm`)

### 1. Build

```bash
git clone https://github.com/Golub4ik-Official/blockbench-mcp.git
cd blockbench-mcp
pnpm install
pnpm build
```

Artifacts are written to:
- `apps/mcp-plugin/dist/mcp_socketio_plugin.js` — the plugin file
- `apps/mcp-server/dist/index.js` — the MCP server

> **For end users**: a ready-built plugin file (`mcp_socketio_plugin.js`) is attached to every [release](https://github.com/Golub4ik-Official/blockbench-mcp/releases) — no build required.

### 2. Install the Blockbench plugin

1. Open Blockbench.
2. **File → Plugins → Load Plugin from File** → select `apps/mcp-plugin/dist/mcp_socketio_plugin.js`.
3. Enable the plugin (checkbox next to "MCP Plugin").
4. After it loads, the **"MCP Commands"** panel appears (on the right) — it shows the command history and connection status.

### 3. Configure the MCP server in your assistant

Register the MCP server in your assistant's config. OpenCode example (`opencode.json`):

```json
{
  "mcp": {
    "blockbench": {
      "type": "local",
      "command": ["node", "C:/path/to/blockbench-mcp/apps/mcp-server/dist/index.js"],
      "enabled": true
    }
  }
}
```

Claude Desktop example (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "blockbench": {
      "command": "node",
      "args": ["/path/to/blockbench-mcp/apps/mcp-server/dist/index.js"]
    }
  }
}
```

### 4. Usage

1. Open Blockbench and create a project (File → New → Block model).
2. Start or restart your assistant so it picks up the MCP server.
3. Ask the assistant, for example: "Create a generator like in Industrial Craft 2 — case, front panel, and an output slot."
4. Cubes are added to the active Blockbench project.

## Development

```bash
# Watch-build the plugin (rebuilds on changes)
cd apps/mcp-plugin && pnpm dev

# Rebuild the MCP server
cd apps/mcp-server && pnpm build
```

After editing plugin code, rebuild it and reload it in Blockbench: **File → Plugins → Master → Reload**.

## Releases

Releases are created from tags. The GitHub Actions workflow builds the plugin and attaches `mcp_socketio_plugin.js` to the release:

```bash
git tag v0.3.0
git push origin v0.3.0
```

## Troubleshooting

- **"ERROR: Blockbench plugin is not connected"** — the plugin is not loaded or Blockbench is closed. Load the plugin and check the "MCP Commands" panel.
- **Port 9999 is busy** — close the conflicting process or restart the MCP server.
- **Timed out** — Blockbench did not respond within 30 seconds. Make sure a project is open and the plugin is active.
- **The `addElement` method is not found** — use the current plugin version (from a release); old builds used a broken API for older Blockbench versions.

## License

MIT — see [LICENSE](LICENSE).