# knitto-mcp-server-channel

Aplikasi Node.js (TypeScript) untuk menjalankan stack **[@knittotextile/knitto-mcp-figma](https://github.com/knittotextile/knitto-mcp/pkgs/npm/knitto-mcp-figma)** di server:

1. **WebSocket relay** (`knitto-mcp-figma-socket`)
2. **AI bridge Cursor** (`knitto-mcp-figma-bridge-cursor`)
3. **AI bridge OpenRouter** (`knitto-mcp-figma-bridge-openrouter`)

## Prasyarat

- Docker & Docker Compose
- GitHub Personal Access Token dengan scope `read:packages` (`GITHUB_TOKEN`)

| Variabel | Default | Fungsi |
|----------|---------|--------|
| `FIGMA_WS_HOST` | `0.0.0.0` | Host bind WebSocket |
| `FIGMA_WS_PORT` | `3055` | Port WebSocket di dalam container |
| `FIGMA_WS_PUBLISH_PORT` | `FIGMA_WS_PORT` | Port yang di-publish ke host |
| `FIGMA_WS_SERVER` | `localhost` | Host socket untuk bridge (dalam container) |
| `CURSOR_API_KEY` | — | API key Cursor (opsional, bisa dari plugin) |
| `OPENROUTER_API_KEY` | — | API key OpenRouter (opsional, bisa dari plugin) |
| `KNITTO_BRIDGE_CWD` | `/app/bridge-workspace` | Working directory agent bridge |
| `KNITTO_BRIDGE_MAX_CONCURRENT` | `1` | Job paralel per channel |
| `KNITTO_BRIDGE_JOB_TIMEOUT_MS` | `600000` | Timeout per job (ms) |
| `KNITTO_BRIDGE_MODEL` | `auto` | Model Cursor agent |
| `GITHUB_TOKEN` | — | Auth GitHub Packages saat Docker build |

## Menjalankan (Docker)

1. Salin environment (wajib isi `GITHUB_TOKEN`):

```bash
cp .env.example .env
```

2. Build & jalankan:

```bash
docker compose up -d --build
```

3. Cek status:

```bash
docker compose ps
docker compose logs -f knitto-mcp-channel
curl http://localhost:${FIGMA_WS_PUBLISH_PORT:-3055}/
```

Health check HTTP: `GET http://<server-host>:<port>/` → `Knitto Figma WebSocket server running`

### Mengganti port

Ubah di `.env`:

```env
FIGMA_WS_PORT=4000
```

Lalu restart:

```bash
docker compose up -d
```

Client (plugin Figma / Cursor MCP) harus mengarah ke port yang sama, contoh `FIGMA_WS_PORT=4000`.

Jika port host berbeda dari port container:

```env
FIGMA_WS_PORT=4000
FIGMA_WS_PUBLISH_PORT=8080
```

Build manual tanpa Compose:

```bash
DOCKER_BUILDKIT=1 docker build \
  --secret id=github_token,env=GITHUB_TOKEN \
  -t knitto-mcp-server-channel:latest .
docker run -d \
  --name knitto-mcp-channel \
  -p "${FIGMA_WS_PORT:-3055}:${FIGMA_WS_PORT:-3055}" \
  -e FIGMA_WS_PORT="${FIGMA_WS_PORT:-3055}" \
  --env-file .env \
  knitto-mcp-server-channel:latest
```

> `GITHUB_TOKEN` hanya dipakai saat build (via Docker secret) dan tidak dicetak di log build.

Stop container:

```bash
docker compose down
```

### Troubleshooting bridge

Setelah mengubah kode, **wajib rebuild** image:

```bash
docker compose up -d --build
```

Cek bridge sudah terdaftar di log:

```bash
docker compose logs knitto-mcp-channel | grep "Bridge registered"
```

Harus muncul:

```
Bridge registered: cursor-... (Cursor)
Bridge registered: openrouter-... (OpenRouter)
```

Jika job Agent gagal:

1. Isi `CURSOR_API_KEY` / `OPENROUTER_API_KEY` di `.env`, atau simpan di plugin tab **Agent → Bridge credentials**
2. Plugin **Connection** harus connect ke host server yang sama (bukan `localhost` dari mesin lain)
3. **Channel** di plugin harus sama dengan yang dipakai saat submit job

## Development lokal (opsional)

```bash
cp .npmrc.example .npmrc   # isi GITHUB_TOKEN
pnpm install
pnpm rebuild sqlite3       # wajib untuk bridge-cursor (@cursor/sdk)
pnpm dev
```

## Konfigurasi client

### Plugin Figma

1. Install plugin dari `node_modules/@knittotextile/knitto-mcp-figma/dist/knitto-figma-mcp-plugin.zip`
2. Tab **Connection** → isi **Channel** (contoh: `knitto`)
3. Isi **WebSocket host** = hostname/IP server ini
4. Klik **Connect**
5. Tab **Agent** → pilih bridge **Cursor** atau **OpenRouter** → Submit

API key bridge bisa diisi di `.env` atau disimpan lewat panel **Bridge credentials** di plugin.

### Cursor IDE (`mcp.json`) — opsional

Jika tidak memakai tab Agent di plugin, MCP bisa dihubungkan langsung dari Cursor:

```json
{
  "mcpServers": {
    "figma": {
      "command": "npx",
      "args": ["-y", "@knittotextile/knitto-mcp-figma@latest"],
      "env": {
        "CHANNEL_ID": "knitto",
        "FIGMA_WS_SERVER": "your-server-host",
        "FIGMA_WS_PORT": "3055"
      }
    }
  }
}
```

**Catatan:** Matikan MCP figma di Cursor saat memakai bridge dari plugin (atau gunakan channel terpisah) agar tidak bentrok.

## Arsitektur

```mermaid
flowchart LR
  PluginUI --> Socket
  Socket --> BridgeCursor[Bridge Cursor]
  Socket --> BridgeOR[Bridge OpenRouter]
  BridgeCursor --> MCP["knitto-mcp-figma MCP"]
  BridgeOR --> MCP
  MCP --> Socket
  CursorMCP[Cursor IDE MCP] --> Socket
```