knitto-mcp-server-channel

Aplikasi Node.js (TypeScript) untuk menjalankan stack @knittotextile/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)

Related MCP server: Figma MCP Server

Menjalankan (Docker)

1. Salin environment (wajib isi GITHUB_TOKEN):

cp .env.example .env

2. Build & jalankan:

docker compose up -d --build

3. Cek status:

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:

FIGMA_WS_PORT=4000

Lalu restart:

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:

FIGMA_WS_PORT=4000
FIGMA_WS_PUBLISH_PORT=8080

Build manual tanpa Compose:

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:

docker compose down

Troubleshooting bridge

Setelah mengubah kode, wajib rebuild image:

docker compose up -d --build

Cek bridge sudah terdaftar di log:

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)

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:

{
  "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

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