ext-apps/examples/threejs-server/README.md

# Example: Three.js App

![Screenshot](screenshot.png)

Interactive 3D scene renderer using Three.js. Demonstrates streaming code preview and full MCP App integration.

## MCP Client Configuration

Add to your MCP client configuration (stdio transport):

```json
{
  "mcpServers": {
    "threejs": {
      "command": "npx",
      "args": [
        "-y",
        "--silent",
        "--registry=https://registry.npmjs.org/",
        "@modelcontextprotocol/server-threejs",
        "--stdio"
      ]
    }
  }
}
```

### Local Development

To test local modifications, use this configuration (replace `~/code/ext-apps` with your clone path):

```json
{
  "mcpServers": {
    "threejs": {
      "command": "bash",
      "args": [
        "-c",
        "cd ~/code/ext-apps/examples/threejs-server && npm run build >&2 && node dist/index.js --stdio"
      ]
    }
  }
}
```

## Features

- **Interactive 3D Rendering**: Execute JavaScript code to create and animate Three.js scenes
- **Streaming Preview**: See the scene build in real-time as code is being written
- **Built-in Helpers**: Pre-configured `OrbitControls`, post-processing effects (bloom), and render passes
- **Documentation Tool**: `learn_threejs` provides API docs and code examples on demand

## Running

1. Install dependencies:

   ```bash
   npm install
   ```

2. Build and start the server:

   ```bash
   npm run start:http  # for Streamable HTTP transport
   # OR
   npm run start:stdio  # for stdio transport
   ```

3. View using the [`basic-host`](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) example or another MCP Apps-compatible host.

### Tool Input

To test the example, copy the contents of [`test-input.json`](test-input.json) into the tool input field in `basic-host`.

The test input creates a simple scene with a rotating cube:

```javascript
const scene = new THREE.Scene();
const camera = new THREE.PerspectiveCamera(60, width / height, 0.1, 100);
camera.position.set(2, 2, 2);

const renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
renderer.setSize(width, height);
renderer.shadowMap.enabled = true;

const cube = new THREE.Mesh(
  new THREE.BoxGeometry(),
  new THREE.MeshStandardMaterial({ color: 0x00ff88 }),
);
cube.castShadow = true;
cube.position.y = 0.5;
scene.add(cube);

const floor = new THREE.Mesh(
  new THREE.PlaneGeometry(5, 5),
  new THREE.MeshStandardMaterial({ color: 0x222233 }),
);
floor.rotation.x = -Math.PI / 2;
floor.receiveShadow = true;
scene.add(floor);

const light = new THREE.DirectionalLight(0xffffff, 2);
light.position.set(3, 5, 3);
light.castShadow = true;
scene.add(light);
scene.add(new THREE.AmbientLight(0x404040));

function animate() {
  requestAnimationFrame(animate);
  cube.rotation.y += 0.01;
  renderer.render(scene, camera);
}
animate();
```

#### Available Three.js Globals

When writing custom code, these globals are available:

```javascript
THREE; // Three.js library
canvas; // Pre-created canvas element
width; // Canvas width
height; // Canvas height
OrbitControls; // Camera controls
EffectComposer; // Post-processing composer
RenderPass; // Render pass
UnrealBloomPass; // Bloom effect
```

## Architecture

### Server (`server.ts`)

Exposes two tools:

- `show_threejs_scene` - Renders a 3D scene from JavaScript code
- `learn_threejs` - Returns documentation and code examples for Three.js APIs

Supports Streamable HTTP and stdio transports.

### App (`src/threejs-app.tsx`)

React component that:

- Receives tool inputs via the MCP App SDK
- Displays streaming preview from `toolInputsPartial.code` as code arrives
- Executes final code from `toolInputs.code` when complete
- Renders to a pre-created canvas with configurable height

## Performance

### Visibility-Based Pause

Animation automatically pauses when the view scrolls out of view:

- Uses `IntersectionObserver` to track visibility (browser-native, no polling)
- Wraps `requestAnimationFrame` to skip frames when not visible
- Animation loop stops completely → zero CPU usage while hidden
- Queued callbacks resume instantly when scrolled back into view

This is transparent to user code - just use `requestAnimationFrame` normally.

### Transparent Background

Supports alpha transparency for seamless host UI integration:

```javascript
const renderer = new THREE.WebGLRenderer({
  canvas,
  antialias: true,
  alpha: true,
});
renderer.setClearColor(0x000000, 0); // Fully transparent
```

This is the default - 3D objects composite directly over the host background.