noddle draw

noddle draw MCP サーバー

AI エージェント（Claude Code、Claude Desktop、または任意の MCP クライアント）が、あなたと一緒にボード上で作業できるようにします。ボードの読み取り、作成、編集、バージョン履歴の閲覧、他の共同作業者と同じようなコメントができます。

noddle draw は匿名です。アカウントもトークンもありません。ボード ID（12 桁の 16 進数文字列）またはボード URL がアクセス手段です。エージェントは渡された任意のボードを開くことができ、エージェントが作成したボードのリンクを持つ人は誰でも、そのボードを開けます。エージェントは NODDLE_AGENT_NAME を使ってコメントとバージョンスナップショットに署名します。

• Python ≥ 3.9 の標準ライブラリのみを使用します（urllib + json）。インストールは不要です。
• stdio トランスポート：1 行につき JSON-RPC 2.0 メッセージを 1 つ送信します。stdout にはプロトコルメッセージのみが出力され、ログは stderr に出力されます。
• MCP プロトコルの 2 世代対応：
  • 2026-07-28（モダン、ステートレス）：すべてのリクエストに _meta["io.modelcontextprotocol/protocolVersion"] と clientCapabilities が含まれます。サーバーは server/discover を実装し、すべての結果に resultType と _meta["io.modelcontextprotocol/serverInfo"] を設定します。また、リスト／読み取り結果には ttlMs／cacheScope を設定します。未対応のバージョンの場合は -32022 UnsupportedProtocolVersion を返します。
  • レガシーの initialize ハンドシェイク：2025-11-25、2025-06-18、2025-03-26、2024-11-05 に対応しています。サーバーは、クライアントのバージョンに対応している場合はそのバージョンで応答し、対応していない場合は 2025-11-25 で応答します。このモードでは ping が動作します。JSON-RPC バッチは、バッチを許可していた唯一のリビジョンである 2025-03-26 の場合にのみ受け付けられます。

1. 登録

Claude Code（リポジトリのルートから実行。スクリプトの絶対パスを使うとより確実です）：

claude mcp add noddle -- python3 mcp/noddle_mcp.py
# a self-hosted instance instead of draw.noddle.dev:
claude mcp add noddle --env NODDLE_BASE_URL=http://127.0.0.1:8000 -- python3 mcp/noddle_mcp.py

Claude Desktop（~/Library/Application Support/Claude/claude_desktop_config.json）またはプロジェクトの .mcp.json では、同じ形式を使用します：

{
  "mcpServers": {
    "noddle": {
      "command": "python3",
      "args": ["/absolute/path/to/noddle-draw/mcp/noddle_mcp.py"],
      "env": { "NODDLE_BASE_URL": "https://draw.noddle.dev" }
    }
  }
}

MCP Bundle（Claude Desktop やその他の MCPB クライアントにワンクリックでインストール）：最新の mcpb-v* リリースから noddle-draw.mcpb をダウンロードして開きます。必要なのは Python 3.10+ のみです（標準ライブラリを使用するため、インストール手順はありません）。

チェックアウトから実行する場合（ここにある pyproject.toml）：

uvx --from ./mcp noddle-draw-mcp       # or: pipx install ./mcp && noddle-draw-mcp

このサーバーは、公式 MCP レジストリに dev.noddle/draw として登録されています（リリースを参照）。

環境変数	デフォルト値
NODDLE_BASE_URL	https://draw.noddle.dev	noddle draw インスタンスの http(s) オリジン。http(s) 以外の値を指定すると、コード 2 で終了します
NODDLE_AGENT_NAME	MCP agent	コメントとバージョン履歴に表示される名前（最大 40 文字）
NODDLE_TIMEOUT	30	ボード API 呼び出し 1 回あたりの秒数
NODDLE_AI_TIMEOUT	180	generate_diagram の実行時間（秒）
NODDLE_AI_PROVIDER	—	generate_diagram 用の任意の BYOK：claude、openai、gemini、openrouter、custom
NODDLE_AI_KEY	—	AI プロバイダーのキーです。NODDLE_BASE_URL にのみ送信され、ウェブアプリと同じ X-AI-* ヘッダーとして使用されます。保存されることはありません。未設定の場合、インスタンスに共有プールがあればそれを使用します
NODDLE_AI_MODEL	—	任意のモデルの上書き設定
NODDLE_AI_BASE	—	OpenAI 互換のベース URL（プロバイダーが custom の場合のみ）

CLI：--help、--version、--list-tools（ツール定義を JSON として出力します）。 終了コード：stdin が閉じられた場合（正常終了）は 0、設定が不正な場合は 2。

2. ツール

すべてのツールは、outputSchema に準拠する structuredContent と、同じ内容の JSON をテキストブロックとして返します。ボードツールは resource_link として noddle://board/{id} も返します（リビジョン ≥ 2025-06-18）。doc_id を受け取る ツールには、12 桁の 16 進数 ID またはボード URL（{base}/d/{id} または /embed/{id}）を渡せます。NODDLE_BASE_URL とオリジンが異なる URL は拒否されます。

ツール	readOnly	destructive	idempotent	openWorld	内容
get_board	✓			✗	名前、URL、my_role（editor／viewer）、updated_at、ページの概要、図の JSON。page_id と include_svg は省略可能
create_board	✗	✗	✗	✗	新しいボードを作成します。図の JSON は省略可能です。URL を知っている人は誰でも編集できます
update_board	✗	✓	✓	✗	図全体を置き換えます（取得 → 編集 → 送信）。バージョンのスナップショットが保存されます。expected_updated_at を指定すると、同時編集時に上書きする代わりに競合エラーが返されます
rename_board	✗	✗	✓	✗	名前を変更します
list_versions	✓			✗	バージョン履歴のスナップショットを新しい順に一覧表示します
get_version	✓			✗	1 つのスナップショットの図を取得します。復元するには、その内容を update_board に渡します
list_comments	✓			✗	コメントスレッド
add_comment	✗	✗	✗	✗	node_id／edge_id／parent_id（返信）のいずれか 1 つ、または座標 x,y（＋ page_id）にピン留めします。閲覧専用リンクでも利用できます
generate_diagram	✓			✓	インスタンスの AI（独自の BYOK キーまたは共有プール）を使って、文章または Mermaid から図の JSON を生成します。何も保存しないため、結果を create_board／update_board に渡してください

意図的に list_boards と削除機能はありません。API にその機能がないためです。リンクからアクセスできてもボードを検索できるわけではなく、匿名ボードには削除を委ねられる信頼できる所有者がいません。リンクが閲覧専用のボードへの書き込みは、403 のツールエラーになります。

図のペイロードはそのまま中継されます。サーバーが検証するのはエンベロープ （{pages:[{id,nodes,edges}]} またはレガシー形式の {nodes,edges}。ID は文字列）のみです。ノードとエッジのフィールドは変更せずに転送されるため、freedraw 種類の points や curved ルーティングなど、新しいエディターのフィールドもサーバーの更新なしで利用できます。contracts/openapi.yaml の DiagramNode／ DiagramEdge を参照してください。

エラー：

• 不正な引数、API エラー（400／403／404／413／422／429／503）、競合は、モデルが対処できる isError: true のツール結果として返されます。
• プロトコルエラーでは標準の JSON-RPC コードが使われます。不明なツールまたは無効なパラメーターは -32602、不明なメソッドは -32601、不正な JSON は -32700、無効なリクエストは -32600 です。

3. リソースとプロンプト

• リソース：resources/list は、このセッションで作成、読み取り、または 編集したボードを noddle://board/{id}（application/json、lastModified）として一覧表示します。API に一覧表示機能がないため、最初は空です。resources/templates/list は noddle://board/{doc_id} を公開するため、クライアントは任意のボードを ID で読み取れます。resources/read は get_board と同じ JSON を返します。不明なボードには -32602 が返されます。
• プロンプト：
  • design_board(topic, notes?)：生成 → 妥当性を確認 → create_board → URL を返信します。
  • review_board(doc_id)：ボードをリソースとして埋め込み、アンカー付きコメントとして投稿する批評を求めます。

4. 例（Claude Code）

> Create a board "Payment flow" with Client → API Gateway → Payment Service → Database,
  then comment on the Database node reminding the team to review indexes.

Claude: generate_diagram(text="Client -> API Gateway -> Payment Service -> Database")
        → create_board(name="Payment flow", diagram=…)
        → add_comment(doc_id, body="Please review indexes for the payments table", node_id="db")
        → returns https://draw.noddle.dev/d/{id}

コメントは、公開中のボードにリアルタイムで届きます。update_board で書き込んだ図は、ボードを再読み込みすると表示されます。

5. テスト

python3 -m pytest mcp -q        # or: python3 -m unittest discover mcp

test_noddle_mcp.py は、実際のサーバーを stdio 経由で、プロセス内の偽 REST バックエンドに対して実行します。バージョンネゴシエーション（モダン形式とレガシー形式）、スキーマの妥当性、読み取り・書き込みツール、ボード URL の ID、閲覧専用リンク、リソース、プロンプト、BYOK ヘッダーの転送、エラーパスを検証します。また、stdout に JSON-RPC 以外が出力されないこと、リクエストに Authorization ヘッダーが含まれないこと、BYOK キーが出力やログに漏れないことも確認します。

リリース

mcp/server.json はレジストリーの掲載情報（dev.noddle/draw）で、GitHub リリースに添付された MCP Bundle を参照しています。dev.noddle/* 名前空間は HTTP 経由で検証されます。noddle.dev は /.well-known/mcp-registry-auth で公開者の ed25519 公開鍵を提供しています。

1. すべてのバージョンを同じ値に更新します。対象は noddle_mcp.py の __version__、mcpb/manifest.json の version、pyproject.toml の version、および server.json の version です。 レジストリーのバージョンは変更できません。メタデータのみを修正する場合は、1.0.0-1 のようなサフィックスを使用します。
2. バンドルをビルドします。mcp/build_mcpb.sh → mcp/dist/noddle-draw.mcpb（SHA-256 が出力されます）。
3. そのファイルを指定してリリースを作成します。 gh release create mcpb-v<version> mcp/dist/noddle-draw.mcpb --title "MCP server <version>"。
4. server.json で、パッケージの identifier にリリースのダウンロード URL を設定し、fileSha256 に出力されたハッシュを設定します。その後、名前空間の鍵を保持するユーザーが mcp-publisher login http --domain noddle.dev --private-key … を実行してログインし、mcp-publisher publish mcp/server.json を実行して公開します。

メモ

• update_board は保存済みの SVG プレビューを維持します。プレビューは、エディターで次回保存したときに更新されます。
• クロスオリジンの HTTP リダイレクトは拒否されるため、BYOK キーが別のホストに転送されることはありません。ループバック以外のホストへの平文 http 接続で BYOK キーを使用すると、警告がログに記録されます。
• generate_diagram は AI プロバイダーにテキストを送信します。顧客の PII、認証情報、またはアカウント番号は絶対に渡さないでください。