Slate

Una whiteboard sull'iPad che gli agenti AI possono leggere e scrivere via MCP.

Disegni e scrivi a mano con la Pencil, aggiungi note e riquadri. Dall'altra parte un agente (Claude Code o qualsiasi client MCP) legge la board come struttura — elementi, testo, posizioni, frecce — e come immagine, così capisce anche quello che è stato scritto a mano. E può rispondere scrivendo sulla board.

Tutto gira sul tuo Mac. Nessun servizio esterno, nessun dato che esce dalla rete.

Prima di adottarlo: il codice di Slate è MIT, ma il canvas è l'SDK di tldraw, che non è open source e limita l'uso gratuito agli ambienti di sviluppo. Per un deployment di produzione serve una licenza tldraw. Dettagli nella sezione Licenza — leggila prima di costruirci sopra.

Come è fatto

iPad Safari (PWA tldraw)  ─┐
                           ├─ WebSocket sync ─►  board-server (Node 22+)
Mac browser (stessa PWA)  ─┘                     • @tldraw/sync-core
                                                  • SQLite (un file per board)
                                                  • render PNG headless + OCR
                                                          ▲
Claude Code / altri agent ── stdio MCP ──►  slate-mcp ────┘

Lo stato vive sul server, non sull'iPad: la board resta leggibile anche a tablet spento.

Related MCP server: @kamiazya/whiteboard-mcp

Prerequisiti

• Node ≥ 22.12 — richiesto da tldraw 5. Il .node-version punta a 26. Se la tua shell è su Node 20 (default per altri progetti), usa /opt/homebrew/bin/node o fnm use 26.

• Google Chrome — usato in headless per il render. Nessun browser da scaricare.

• Xcode command line tools — solo per compilare il binario OCR.

Setup

npm install
npm run build

# OCR della scrittura a mano (opzionale ma consigliato)
cd tools/ocr && swiftc -O -o slate-ocr main.swift && cd -

Avvio

npm run dev:server     # in sviluppo

Oppure come servizio, così parte da solo al login:

./scripts/install-service.sh

All'avvio il server stampa i link di pairing:

[slate] pair a device:  http://192.168.1.x:4501/?token=…      ← LAN
[slate] pair a device:  http://100.x.x.x:4501/?token=…        ← Tailscale

Collegare l'iPad

1. Apri uno dei link di pairing su Safari. Il token viene salvato e tolto dall'URL.

2. Condividi → Aggiungi a Home. Si apre a schermo intero, senza barre.

3. Fuori casa serve Tailscale sull'iPad (usa il link 100.x). In LAN non serve.

Il firewall di macOS blocca tutto

Se l'iPad non si collega ma da Mac funziona, è quasi certamente il firewall: autorizza il binario node reale (non il symlink).

NODE_REAL=$(readlink -f /opt/homebrew/bin/node)
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add "$NODE_REAL"
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp "$NODE_REAL"

Va rifatto dopo ogni aggiornamento di Node: Homebrew installa in un path versionato (/opt/homebrew/Cellar/node/26.4.0/bin/node) e l'autorizzazione è legata a quel path esatto.

Collegare l'agente

claude mcp add slate -- /opt/homebrew/bin/node ~/GitHub/mcp/slate/apps/slate-mcp/dist/index.js

L'MCP parla al server via loopback, che è sempre autorizzato: nessun token da configurare finché server e agente stanno sulla stessa macchina. Se li separi, passa SLATE_SERVER e SLATE_TOKEN.

Tool disponibili

Eliminare una board non è esposto come tool: si fa via DELETE /api/boards/:id. Un agente può cancellare elementi, non board intere.

Quanto è affidabile l'OCR

Poco, ed è per questo che render_board esiste. Su scrittura a mano reale Apple Vision prende circa 3 parole su 4: abbastanza per cercare ("in che board avevo scritto FLUSSO?"), non abbastanza per fidarsi del testo riconosciuto.

Per capire davvero cosa c'è su una board disegnata, l'agente deve guardare l'immagine. read_board lo dice esplicitamente nel proprio output.

Misurato su una board di prova (scripts/ocr-scale-test.mjs confronta le varianti):

Due cose controintuitive emerse dai dati:

• Alzare la risoluzione non migliora linearmente. A scale 3 la scrittura viene letta peggio che a 2 in alcuni punti: i tratti spessi iniziano a fondersi. Regola con SLATE_OCR_SCALE, non dare per scontato che più alto sia meglio.

• La correzione linguistica conviene tenerla accesa, anche se spinge verso parole di dizionario (è lei a trasformare FLUSSO2 in Autor). Disattivarla con --raw peggiora tutto il resto. Se la tua board è fatta solo di sigle, riprova la misura: il compromesso può ribaltarsi.

Sicurezza

Un solo modello di accesso per tutte le superfici remote — API, sync e upload. Loopback è sempre autorizzato (è così che entra l'MCP); tutto il resto richiede il token, che viene generato al primo avvio e salvato in ~/.slate/token (0600).

Non esiste una modalità "senza token": lasciare aperto il sync proteggendo solo l'API sarebbe inutile, perché chi raggiunge il socket di sync ha già accesso completo in lettura e scrittura a ogni board.

Le immagini sotto /media/ si leggono senza token: tldraw le carica con <img src>, che non può portare un header, e mettere il token nell'URL lo farebbe finire dentro i documenti esportati. I nomi contengono un UUID, quindi non sono indovinabili.

Per restringere l'ascolto alla sola tailnet:

SLATE_HOST=100.x.x.x npm run dev:server   # il tuo indirizzo Tailscale

Variabili d'ambiente

Trappole già incontrate

Cose che costano un pomeriggio se le scopri da solo.

• fontSizeAdjustment: 0 rende il testo invisibile. La nota si salva, si rilegge correttamente dai dati, e sull'iPad appare vuota. Il valore giusto è null ("ricalcola"). Se scrivi record a mano, non copiare uno 0 da un esempio vecchio.

• /assets è di Vite. Le immagini delle board stanno sotto /media perché la build della PWA emette i suoi bundle in /assets: una rotta sovrapposta se li mangia e l'app resta senza JavaScript, fallendo in modo silenzioso.

• Il testo è ProseMirror, non stringa. props.richText vuole un documento; una stringa viene rifiutata dallo schema.

• I tratti sono path base64. tldraw 5 non espone un encoder, quindi non si può fabbricare un tratto a mano libera da script — solo disegnandolo. Per lo stesso motivo la dimensione di un tratto non è calcolabile dal record: la sanno solo il renderer e l'endpoint OCR, che la misurano in un editor vivo.

• Non elencare i tratti uno per uno. Una pagina scritta a mano sono decine o centinaia di draw: elencarli produce un muro di righe identiche che seppellisce tutto il resto. read_board li conta e mostra il testo riconosciuto.

• Le note non crescono da sole. Una sticky è un riquadro fisso 200×200 e il testo che eccede viene tagliato nel render, pur restando integro nei dati: l'API lo rilegge intero mentre sull'iPad la nota appare mozzata. add_note stima growY dalla lunghezza del testo; il client ricalcola l'altezza esatta alla prima modifica.

• Il posizionamento automatico ha bisogno delle misure vere. Siccome i tratti dichiarano dimensione zero, su una board disegnata il calcolo del bordo destro cade dove inizia il primo tratto e la nota finisce sopra il disegno. Per questo add_note interroga /api/boards/:id/bounds quando trova inchiostro.

• I record scritti vengono validati. Il server rifiuta con 400 quello che non passa lo schema tldraw, invece di far crashare il canvas sull'iPad più tardi.

• La licenza tldraw non è open source. Vedi la sezione qui sotto: incide su cosa puoi farci, non solo sul watermark.

Licenza

Il codice di Slate è MIT (vedi LICENSE): usalo, modificalo, ridistribuiscilo come vuoi.

Ma il canvas no. Slate è costruito sull'SDK di tldraw, che non è open source e ha una licenza propria. Vale la pena leggerla prima di adottare Slate, perché è più restrittiva di quanto il watermark lasci intuire:

• L'uso gratuito è limitato ai Development Environment. La licenza definisce Production come «any production deployment of the Software that operates on servers, cloud platforms, web applications, or where the software is used to provide functionality to end users».

• Per un deployment di produzione serve una licenza commerciale o un trial.

• La redistribuzione è ammessa solo come componente di un'altra applicazione, mai standalone, e con copia verbatim della licenza tldraw.

In pratica: un'istanza personale self-hosted sul proprio Mac sta in una zona grigia che solo tldraw può chiarire; qualsiasi cosa somigli a un servizio per altri utenti quasi certamente richiede una licenza. Se il vincolo non ti va bene, la strada è sostituire il canvas con un'alternativa realmente libera — Excalidraw è MIT — tenendo il resto di Slate, che dal canvas dipende solo attraverso il layer di sync e il renderer.

Questa è lettura del testo della licenza, non consulenza legale. Per un uso serio chiedi a tldraw (sales@tldraw.com) o a un avvocato. Il quadro completo delle dipendenze e delle loro licenze è in NOTICE.md.

Sviluppo

npm run dev:server                    # server con reload
npm run dev:web                       # PWA su :4500, proxy verso il server
node scripts/seed-demo.mjs demo       # riempie una board di prova
node scripts/test-mcp.mjs demo        # esercita l'MCP su stdio
node scripts/make-icons.mjs           # rigenera le icone della PWA