# Three.js MCP Triangle

A colored Three.js triangle rendered in the browser that you control through an
**MCP (Model Context Protocol) server**. The server exposes tools to change the
triangle's **color** and **transform** (position, rotation, scale). State
changes are pushed live to the browser over a WebSocket.

```
MCP client (Claude / VS Code Copilot)
        │  stdio (MCP protocol)
        ▼
  MCP server (src/index.js)  ── thin proxy
        │  HTTP POST /api/state
        ▼
  Web server (src/web-server.js)  ── owns the state
        │  WebSocket push (state changes)
        ▼
  Browser  →  http://localhost:3000  →  Three.js triangle
```

**Two processes, one shared state.** The web server owns the triangle state and
serves the browser; the MCP server is a thin proxy that POSTs to it. This is why
the MCP tools and the browser stay in sync even though your MCP client spawns
the MCP server in a *separate* process from `npm start`.

> **Where do I type prompts?** In your MCP client's chat (e.g. **VS Code Copilot
> Chat in Agent mode**) — *not* in the terminal. The terminal running
> `npm start` is the web server; the terminal is not a prompt box.

---

## Project structure

| Path                  | Purpose                                                        |
| --------------------- | -------------------------------------------------------------- |
| `src/web-server.js`   | Standalone server: owns state, serves viewer, WS + HTTP API    |
| `src/index.js`        | MCP server — thin proxy that calls the web server's HTTP API   |
| `src/state.js`        | Shared triangle state + change subscriptions                   |
| `public/index.html`   | Three.js scene that renders and live-updates the triangle      |
| `.vscode/mcp.json`    | VS Code MCP server configuration                               |

---

## Requirements

- Node.js **18+**

## Install

```powershell
npm install
```

## Run

**Step 1 — start the web server** (leave it running):

```powershell
npm start
```

Then open <http://localhost:3000> to see the triangle. Change the web port with
the `PORT` environment variable (default `3000`).

**Step 2 — connect an MCP client** (see below). The MCP server is launched by
your client, not by `npm start`. It proxies to the web server via the `WEB_URL`
environment variable (default `http://localhost:3000`).

Type your prompts in the **MCP client's chat**, not in the terminal.

---

## Using it as an MCP server

### VS Code (GitHub Copilot)

The included [`.vscode/mcp.json`](.vscode/mcp.json) registers the server. First
run `npm start` in a terminal, then open the **Copilot Chat** view, switch to
**Agent** mode, and the `threejs-triangle` tools become available. Open
<http://localhost:3000> in a browser to watch changes apply in real time.

### Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "threejs-triangle": {
      "command": "node",
      "args": ["src/index.js"],
      "cwd": "d:/Learning/ThreeJs_MCP",
      "env": { "WEB_URL": "http://localhost:3000" }
    }
  }
}
```

Run `npm start` first, restart Claude Desktop, then open
<http://localhost:3000> in a browser.

---

## Exposed tools (the API)

### `set_color`

Set one solid color for the whole triangle.

| Param   | Type   | Description                    |
| ------- | ------ | ------------------------------ |
| `color` | string | Hex color, e.g. `#ff8800`      |

### `set_vertex_colors`

Set the three vertex colors individually to create a gradient.

| Param    | Type   | Description                 |
| -------- | ------ | --------------------------- |
| `color1` | string | Top vertex color            |
| `color2` | string | Bottom-left vertex color    |
| `color3` | string | Bottom-right vertex color   |

### `set_transform`

Set position, rotation (degrees), and/or scale. Any omitted axis keeps its
current value.

| Param      | Type                         | Description                                  |
| ---------- | ---------------------------- | -------------------------------------------- |
| `position` | `{ x?, y?, z? }`             | World position                               |
| `rotation` | `{ x?, y?, z? }`             | Rotation in **degrees**                      |
| `scale`    | `number` or `{ x?, y?, z? }` | Uniform scale, or per-axis scale             |

### `get_state`

Returns the current triangle state (vertex colors + transform).

### `reset`

Resets to defaults: red/green/blue vertices and identity transform.

---

## Example prompts

Once the server is connected in your MCP client, try:

- "Make the triangle solid orange."
- "Set the vertex colors to red, green and blue."
- "Rotate the triangle 45 degrees on the Z axis and scale it to 1.5."
- "Move the triangle to x: 1, y: -0.5."
- "Reset the triangle."

---

## How it works

1. `state.js` holds a single `TriangleState` object and a set of subscribers.
2. `web-server.js` (run via `npm start`) owns the state, serves
   `public/index.html`, exposes the HTTP API (`GET/POST /api/state`,
   `POST /api/reset`), and broadcasts every change to connected browsers over
   WebSocket. New tabs receive the current state on connect.
3. `index.js` is the MCP server your client spawns. Each tool calls the web
   server's HTTP API — it holds no state itself. This keeps the browser and the
   tools in sync across the two processes.
4. `public/index.html` builds a `BufferGeometry` triangle with per-vertex
   colors and applies incoming state to the mesh's color attribute and
   transform.

> **Note:** MCP uses **stdout** for its protocol, so the MCP server writes all
> logs to **stderr** (`console.error`). The web server is a normal process and
> logs to stdout.

> **Troubleshooting:** If tools report "Could not reach the triangle web
> server", make sure `npm start` is running. If you see `EADDRINUSE` on port
> 3000, another process already holds it — stop it or set a different `PORT`
> (and matching `WEB_URL`).

---

## License

MIT