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)

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):

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