# Blockbench MCP

Codex-ready local MCP server for controlling Blockbench. This distribution
combines the mature MCP implementation from
[`jasonjgardner/blockbench-mcp-plugin`](https://github.com/jasonjgardner/blockbench-mcp-plugin)
with the local command-history idea from
[`enfp-dev-studio/blockbench-mcp`](https://github.com/enfp-dev-studio/blockbench-mcp),
then modernizes the result for direct use by Codex.

This is an independent community project. It is not affiliated with or
endorsed by Blockbench, OpenAI, Jason J. Gardner, or ENFP Dev Studio.

## What is inside

- A ready-to-load Blockbench desktop plugin with an embedded Streamable HTTP
  MCP server.
- 95 tools for projects, cubes, meshes, armatures, animation, UV editing,
  painting, textures, materials, cameras, import/export, and history.
- 11 resources, 7 resource templates, and 3 prompts.
- Codex-oriented server instructions and MCP tool annotations.
- Loopback-only networking, optional bearer authentication, a 16 MiB request
  limit, and a bounded privacy-aware audit log.
- A reproducible no-dependency build from the preserved upstream bundle.

See [the full tool index](docs/TOOLS.md), [source comparison](docs/ANALYSIS.md),
and [live verification report](docs/LIVE_TEST_REPORT.md).

## Requirements

- Blockbench desktop. The web app cannot host this local server.
- A local Codex client: ChatGPT desktop app, Codex CLI, or Codex IDE extension.
- Node.js 20 or newer only when rebuilding the plugin. It is not required to
  run the bundled plugin.

## Installation

1. Clone or download this repository.

   ```powershell
   git clone https://github.com/illia3/Blockbench-MCP.git
   cd Blockbench-MCP
   ```

2. Open Blockbench and select **File > Plugins > Load Plugin from File**.
   Choose `plugin/blockbench_codex_mcp.js` and allow local network access if
   Blockbench asks.

3. Keep these plugin defaults unless you need a different local setup:

   - port: `3000`
   - MCP endpoint: `/bb-mcp`
   - prompt CDN: disabled
   - bearer token: empty (optional)

4. Connect Codex. In the ChatGPT desktop app or IDE extension, open
   **Settings > MCP servers > Add server**, choose **Streamable HTTP**, enter
   `http://127.0.0.1:3000/bb-mcp`, save, and restart the client.

   For file-based configuration, copy `.codex/config.toml.example` to either
   `~/.codex/config.toml` or a trusted project's `.codex/config.toml`:

   ```toml
   [mcp_servers.blockbench]
   url = "http://127.0.0.1:3000/bb-mcp"
   startup_timeout_sec = 10
   tool_timeout_sec = 120
   enabled = true
   required = false
   default_tools_approval_mode = "writes"
   ```

5. Keep Blockbench open. Check
   `http://127.0.0.1:3000/bb-mcp/ready`, then use `/mcp` in Codex to confirm
   that `blockbench` is connected.

Codex MCP configuration details are documented in the
[official OpenAI MCP guide](https://developers.openai.com/codex/mcp/).

## What to expect

The MCP server runs inside Blockbench, so commands act on the currently open
desktop session. Read-only inspection can run automatically. The supplied
Codex configuration asks for approval before tools that are not marked
read-only. Blockbench undo/redo remains available for supported operations.

Some tools require a compatible project format, an active texture, a selected
element, or an open project. Optional Hytale capabilities appear only when the
corresponding Blockbench environment is available.

## Suggested first prompts

- `Inspect the open Blockbench project and summarize its hierarchy.`
- `Create a 16 x 16 x 16 cube named body and place it at the origin.`
- `List the textures and materials used by the selected elements.`
- `Capture a preview screenshot and identify visible modeling issues.`
- `Show the last 20 Blockbench MCP audit entries.`

## Security

The server binds explicitly to `127.0.0.1`; do not expose it through port
forwarding, a reverse proxy, or a firewall rule. Bearer authentication is
optional and disabled by default so this repository never stores a secret.
See [SECURITY.md](SECURITY.md) for safe token setup and the audit policy.

The `risky_eval` and UI-emulation tools are powerful. Keep the Codex approval
mode set to `writes` or stricter and review their arguments before approval.

## Troubleshooting

- **Codex cannot connect:** keep Blockbench open, verify the plugin is loaded,
  and open the `/ready` URL.
- **The server is missing from `/mcp`:** save the MCP entry and restart the
  desktop app or IDE extension.
- **A tool reports that no project is open:** create or open a Blockbench
  project, then retry.
- **Unauthorized response:** the token configured in Blockbench must match the
  `Authorization` environment header configured for Codex.
- **Port already in use:** stop the conflicting service or change the plugin
  port and the Codex URL together.

## Development and verification

Rebuild and check the committed plugin:

```powershell
npm run build
npm run check
npm test
```

`source/build-custom.mjs` deterministically applies the documented changes to
the preserved upstream 1.6.1 bundle. `npm test` also fails if the generated
plugin differs from the committed artifact.

## Attribution and license

The included plugin is a modified work of Jason J. Gardner's
`blockbench-mcp-plugin` 1.6.1 and is distributed under **GPL-3.0-only**. The
ENFP Dev Studio repository was analyzed, but its source code was not copied.
See [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md),
[MODIFICATIONS.md](MODIFICATIONS.md), and [LICENSE](LICENSE).