Sketchdex

sketchdex

エージェントにホワイトボードを。 sketchdex.dev

Sketchdex は、Claude、Codex、Cursor、その他あらゆる MCP クライアントが、何かを説明しながら手描き風の Excalidraw 図を描けるようにする MCP サーバーです。シーンは、お使いのマシン上のフォルダーに保存される実際の .excalidraw ファイルです。エージェントは描画したり、描画内容を確認したり、修正したりできます。完成したものは、同梱のライブラリアプリまたは excalidraw.com で開いて、引き続き編集できます。

公式の @excalidraw/excalidraw パッケージを基盤としているため、本物のキャンバスを使用します。MIT ライセンスです。

インストール

Node 20 以降が必要です。レンダリング（render_scene）には、マシン上に Chrome、Chromium、Edge、Brave などの Chromium ベースのブラウザーが必要です。それ以外の機能は、ブラウザーなしで動作します。

最も手早い方法は、すでにお使いのエージェントにインストールを任せることです。コマンドを実行できるエージェントに、次の内容を貼り付けてください。

sketchdex mcp serverをインストールしてください。手順を確認するために npx -y sketchdex docs install を実行してください。

または、手動でインストールします。

Claude Code

claude mcp add --scope user sketchdex -- npx -y sketchdex

Codex

codex mcp add sketchdex -- npx -y sketchdex

Cursor

Cursor に追加、または ~/.cursor/mcp.json に次の内容を追加します。

{
  "mcpServers": {
    "sketchdex": {
      "command": "npx",
      "args": ["-y", "sketchdex"]
    }
  }
}

VS Code

code --add-mcp '{"name":"sketchdex","command":"npx","args":["-y","sketchdex"]}'

Claude Desktop、Windsurf、Gemini CLI、その他の環境では、Cursor と同じ mcpServers ブロックを使用するか、stdio サーバーとしてコマンド npx -y sketchdex を指定します。各環境に対応する正確なファイルは、npx -y sketchdex docs install で確認できます。

その後、セッションで「sketchdex を使ってイベントループの仕組みを描いて」と頼んでみてください。

シーンは ~/Documents/sketchdex に保存されます。保存先を変更するには、パッケージ名の後に --vault /path/to/folder を指定するか、サーバーの環境変数に SKETCHDEX_VAULT を設定します。iCloud または Dropbox のフォルダーも使えます。

エージェント向けドキュメント

マニュアルはパッケージ内に含まれているため、エージェントは誰かがページを読むことなく、セットアップに関する質問に答えたり、問題を解決したりできます。

• npx -y sketchdex docs [topic] で内容を出力します（トピック：install、vault、 app、rendering、tools、drawing、troubleshooting、または all）。
• サーバーに接続すると、sketchdex_docs ツールから同じテキストを取得できます。サーバーの指示では、セットアップやエラーに関する質問にはこのツールを使うよう、エージェントに伝えます。
• 同じトピックは、sketchdex://docs/<topic> の MCP リソースとしても利用できます。

アプリ

npx sketchdex app

ブラウザーでライブラリが開きます。ライブプレビュー、検索、ピン留め、名前の変更、複製、インポートができるシーンのグリッドに加え、シーンごとの完全な Excalidraw エディター、⌥K スイッチャー、エージェントが書き込むたびにその内容を表示する 履歴 サイドバーを備えています。エージェントが付けたラベルを確認しながら、各変更をプレビュー、保持、または元に戻せます。アプリはエージェントの書き込みをリアルタイムで検知します。

同じプロセスが、HTTP の POST /mcp と、ローカルホスト限定のプレーン REST POST /api/agent/:op の両方でツールを提供します。

エージェントが利用できる機能

stdio 経由で 19 個のツールを利用できます。主なツールは次のとおりです。

ツール	機能
describe_scene	ピクセルではなく構造を確認します。境界、数、要素ごとの簡潔な概要を取得できます。まずはこちらを使います。
add_elements	ボックス、矢印、テキスト、生成図形（polygon、star、arc、capsule、path）を追加します。図形に label を指定すると、その図形にバインドされたテキストを追加できます。矢印に start／end を指定すると、それぞれの端点をバインドできます。
update_elements	1 つの ID と、変更するフィールドを指定します。読み取り・変更・書き込みはサーバー側で行われるため、2 行の編集には 2 行分のコストがかかります。
import_svg	SVG を書き込み、手描き風の編集可能な要素を 1 つのまとまりとして取得します。何かに見えるように描く必要がある場合に使います。
render_scene	シーン全体または指定範囲を PNG として実際にキャンバスに描画し、エージェントが自分の作業を確認できます。
check_scene	ジオメトリから、隠れたテキスト、重なったラベル、宙に浮いた矢印、孤立した要素などのレイアウト上の問題を検出します。
snapshot_scene、list_history、restore_snapshot	いざというときのための安全策です。書き込みのたびに、直前の状態がスナップショットとして保存されます。
sketchdex_docs	トピック別のマニュアルです。エージェントはこれを使ってセットアップに関する質問に答え、エラーを自力で修正できます。

エージェントが読むマニュアル全文は BRIEF.md にあります。要素の形式、手描きの仕様（ラフさ、アンカーの少なさ、フラットな色、クリップアートを使わないこと）、紙とインクのルール、注意すべき点が記載されています。

安定性

• ファイルが正です。 すべてのシーンは通常の .excalidraw ファイルです。書き込みはアトミックに行われ（一時ファイルを作成してからリネーム）、削除したファイルは trash/ に移動します。index.json はキャッシュであり、失われた場合はサーバーがファイルから再構築します。
• エージェントによる書き込みはすべて取り消せます。 スナップショットは gzip 圧縮され、シーンごとに最大 20 個まで保存されます。画像は対象外で、スナップショットが自動的に期限切れになることはありません。
• 全体を書き換えるのではなく、差分を適用します。 エージェントの作業中にエディターで加えた編集は保持されます。書き込みにはリビジョントークンが付与され、競合する保存はマージされます。
• ローカルのみです。 アカウント、アップロード、テレメトリーはありません。サーバーは 127.0.0.1 にバインドします。

~/Documents/sketchdex/
├── index.json              names, timestamps, pins (a cache, not the truth)
├── scenes/<id>.excalidraw  the scene itself, real Excalidraw format
├── thumbs/<id>.svg         library previews
├── history/<id>/           snapshots taken before agent writes, gzipped
└── trash/<stamp>-<id>.excalidraw

Node API

import { createAgentApi } from "sketchdex";
const api = createAgentApi(); // or createAgentApi("/path/to/vault")
await api.describeScene("Brain Dump");

MCP および REST のインターフェースと同じ実装です。アプリを閉じた状態でも動作します。

開発

git clone https://github.com/lucasr1b/sketchdex
cd sketchdex
npm install          # also retunes Excalidraw's colour picker for dark paper
npm run dev          # app + API + HTTP MCP on http://localhost:5173
npm run build        # dist/, which the CLI and the render page need
node bin/sketchdex.js app

チェックアウトを参照する MCP クライアントを使うには、コマンドとして node /path/to/sketchdex/mcp/server.js を指定します。チェックアウト内では、server/ または mcp/ 以下のファイルが変更されると、サーバーがワーカーをホットリロードします。そのため、クライアントを再起動しなくても、次のツール呼び出しから変更が反映されます。

コミット前に npm run lint、npx tsc -p tsconfig.app.json --noEmit、npm test を実行してください。このテストではパッケージを作成してクリーンなプロジェクトにインストールし、実際の MCP クライアントを通じてレンダリングも含めて動作を確認します。CI では macOS、Linux、Windows で実行します。 AGENTS.md には、コードベースの構成と編集後も守るべきルールが記載されています。macOS 用デスクトップシェルもあります。npm run electron:dev を実行してください。

注意事項

• 新しいシーンは暗い紙（#121212）で始まり、色が反転されることはありません。キャンバス、サムネイル、レンダリングには、記述されたとおりの 16 進数カラーが表示されます。紙の色はシーンごとに設定します（viewBackgroundColor）。
• 初回インストール時の最初のレンダリングでは、ブラウザーの起動に数秒かかります。その後は約 1.5 秒です。
• ブラウザーが通常と異なる場所にある場合は、SKETCHDEX_BROWSER=/path/to/browser を設定してください。
• サーバーは Host が localhost のリクエストにのみ応答し、クロスサイトからの書き込みを拒否するため、ブラウザーで開いた Web ページからボルトにアクセスすることはできません。ただし、通常のローカルポートにバインドするため、同じマシンであなたのユーザー権限で実行されているものならアクセスできます。それが意図した動作です。
• アプリでは ⌘K でシーン切り替えメニューが開きます。このショートカットは Excalidraw の「リンクを追加」と競合するため、リンクにはコンテキストメニューを使ってください。
• アプリは（アプリとしてインストールするために）小さなサービスワーカーを登録します。キャッシュは行いませんが、後で同じポートで別のプロジェクトを実行すると、登録解除するまでそのプロジェクトの開発者ツールにも表示されます。