# Local MCP testing (CLI only)

No MCP Inspector UI is required. Use the scripts in `scripts/` to verify tools headlessly.

## Prerequisites

- Node 20+
- Firebase credentials configured for cloud-labs
- A Firebase user id for dev-header auth

## Three-terminal setup

### Terminal 1 — Pinpole app

```bash
cd cloud-labs
ALLOW_DEV_USER_HEADER=1 npm run dev
```

App runs at `http://localhost:3000`.

### Terminal 2 — MCP HTTP server (optional)

```bash
cd pinpole-mcp
npm run build
PINPOLE_BASE_URL=http://localhost:3000 \
PINPOLE_DEV_USER_ID=<your-firebase-uid> \
npm run start:http
```

HTTP MCP at `http://127.0.0.1:3333/mcp`.

### Terminal 3 — Tests

```bash
cd pinpole-mcp
npm run build
npm test
npm run test:tools
PINPOLE_BASE_URL=http://localhost:3000 \
PINPOLE_DEV_USER_ID=<uid> \
npm run test:integration
npm run test:parity
```

## Manual tool calls (stdio)

```bash
node scripts/tool-call.mjs pinpole_list_projects '{}'
node scripts/tool-call.mjs pinpole_build_architecture \
  '{"prompt":"serverless API with DynamoDB","title":"MCP test"}'
```

## Cursor local config

```json
{
  "mcpServers": {
    "pinpole-local": {
      "command": "node",
      "args": ["/absolute/path/to/pinpole-mcp/dist/server.js"],
      "env": {
        "PINPOLE_BASE_URL": "http://localhost:3000",
        "PINPOLE_DEV_USER_ID": "<uid>"
      }
    }
  }
}
```

## Sanity check in browser

After `pinpole_build_architecture`, open the returned `canvasUrl` in Chrome to confirm the diagram rendered. This validates end-to-end flow; it is not an MCP Inspector.

## Open canvas inside Cursor (embedded browser)

Build/draw tools (`pinpole_build_architecture`, `pinpole_draw_on_canvas`) and simulation tools
(`pinpole_open_simulation_canvas`, `pinpole_show_canvas`) return the **real simulation canvas**
inline (`/embed/simulate`) with the Simulate button. `pinpole_open_canvas` is read-only preview only.

1. **Inline simulation canvas** — real Pinpole ReactFlow + Simulate when `PINPOLE_API_TOKEN` is set
2. **Pinpole canvas** — MCP `resource_link` (embed URL when available)
3. **Open interactive canvas in Pinpole** — full app at `app.pinpole.cloud/canvas?...`
4. **Open in Cursor Simple Browser** — `command:simpleBrowser.show`
5. **`structuredContent.embedUrl`** — prefer for `browser_navigate`

### Setup

1. Set `PINPOLE_API_TOKEN` in MCP config (required for inline embed)
2. **Cursor Settings → Tools & MCP → Browser Automation** → enable, set mode to **Browser Tab**
3. Fully restart Cursor after changing MCP config
4. Run a canvas tool — the simulation canvas should appear inline in chat (Cursor 2.6+)

### Simulation canvas smoke test

```bash
npm run test:simulation-canvas
```

### Manual E2E in Cursor

1. Ask: *"Build a CDN → API Gateway → Lambda architecture"*
2. Inline iframe should show real AWS node cards (not flat SVG)
3. Click **Simulate** → sidebar → **Start Simulation**

### Optional: agent opens browser automatically

Ask in Agent chat: *"After building the architecture, open the embed canvas in Cursor's browser tab."*

The agent should use `structuredContent.embedUrl` or `openInCursor.browserNavigateUrl`.