Perfboard Designer

Perfboard Designer MCP サーバー

AI エージェント（Claude、または任意の MCP クライアント）が Perfboard Designer のためのブレッドボードやストリップボードのレイアウトを設計できる MCP サーバーです。エージェントは部品を調べ、プロジェクトファイルとしてボードを作成し、チェックしたうえで、共有リンクを渡します。リンクをクリックするとエディターでボードが開き、確認したり変更したりできます。

「小さなブレッドボードに555 LED点滅回路を配置して、リンクを送ってください。」

コンピューター上で実行でき（stdio）、アカウントは不要で、ディスクには何も保存しません。または Cloudflare Workers にホストできます（下記）。実行中、エージェントが作業しているプロジェクトをそれぞれ projectId のもとでメモリーに保持するため、エージェントはプロジェクトを一度だけ送信し、その後は小さな変更を加えます。プロジェクトファイルが信頼できる唯一の情報源です。get_project はそのファイルを返し、すべてのツールも ID ではなくファイル全体を受け取ります。

セットアップ

Node.js 22 以降が必要です。npm の perfboard-designer-mcp で公開されており、初回は npx がダウンロードします。

Claude Code:

claude mcp add --scope user perfboard -- npx -y perfboard-designer-mcp

コマンドを指定できる他のクライアントや Claude Desktop（claude_desktop_config.json、Settings → Developer → Edit Config）：

{
  "mcpServers": {
    "perfboard": {
      "command": "npx",
      "args": ["-y", "perfboard-designer-mcp"]
    }
  }
}

このリポジトリから実行するには、ビルドして、コマンドとして node /path/to/perfboard-designer/mcp/dist/server.js を使用します：

cd mcp
npm install
npm run build

リンクは公開エディター https://perfboarddesigner.com/app/ を開きます。別のコピー（たとえばローカルの開発サーバー）を指定するには、サーバーの環境変数に PERFBOARD_EDITOR_URL を設定します：

{
  "mcpServers": {
    "perfboard": {
      "command": "npx",
      "args": ["-y", "perfboard-designer-mcp"],
      "env": {"PERFBOARD_EDITOR_URL": "http://localhost:3000/app/"}
    }
  }
}

このサーバーは、ホストされた Worker がなくても単独で動作します。Worker を参照するのは、2 つの追加機能を使う場合のみです。各機能は PERFBOARD_EDITOR_URL と同様にサーバーの環境変数で設定します。デフォルトでは公開されており、無効にするには off を設定します（その場合、エージェントには提示されません）：

設定	追加機能	デフォルト
PERFBOARD_IMAGE_URL	make_share_link の image。ボードの画像（render_board の PNG はここで描画され、設定は不要です）	https://mcp.perfboarddesigner.com/render.svg
PERFBOARD_PROJECTS_URL	make_share_link の store。保存済みプロジェクトへの短縮リンク。エージェントが要求しない限り、何も送信されません	https://projects.perfboarddesigner.com

ローカルの Worker を指定するには、http://localhost:8787/render.svg と http://localhost:8787 を設定します。

ツール

ツール	説明
list_parts	プロジェクトに配置できるパーツ（現在79個）を一覧表示します。クエリを指定しない場合は、カテゴリごとにすべてのパーツを1行ずつ表示します（ID、名前、ピン数）。"capacitor" や "555" などの単語を指定すると、それらすべてに一致するパーツ、または一致するものがない場合は最も近いパーツを表示します。
get_part	ids で指定した数だけ、パーツの詳細情報を返します。配置先のリスト、ピンとピンラベル、極性、値の単位、本体が覆う穴、コピーして使えるエントリーの例が含まれます。
new_project	メモリー上に保持するプロジェクトを開始し、その projectId を返します。指定したサイズのブレッドボードまたはストリップボードを新規作成するか、サンプルのコピーを作成します（example: "555-led-blinker"）。
edit_project	ops のリストを使って、保持中のプロジェクトを変更します。すべての ops が適用されるか、どれも適用されないかのどちらかです。add_part（パーツ ID を指定し、at、または2端子パーツの場合は from／to を指定します。省略した場合、参照名は番号付きになります。エージェント独自のパーツとして、ピンを任意の位置に配置できる custom、または独自のピン名を持つカタログパーツのパッケージを指定する shape、あるいは後で名前を指定して再配置できる2列ピンのチップまたは開発ボードの chip も指定できます）、update_part（移動、回転、値または参照名の変更）、remove_parts、add_wire（from／to を指定し、曲げる穴を via で指定するか、穴の path を指定して脚ごとに1本のワイヤーを作成します。端点には、そこにある穴を表すピン名（例："U1.7" や "D1.K"）も指定できます）、update_wire（穴またはピンで端点を指定することもでき、via で曲げる位置を置き換えます）、remove_wires、set_board、add_cuts／remove_cuts、set_pad（穴へのメモ）があります。変更内容、新規または移動したパーツのピンの配置先、validate_project と同様に検証したボードを返します。エラーがなければネットも返します。
get_project	保持中のプロジェクトのプロジェクトファイル全体を返します。
get_pin_positions	回転後に、配置した各パーツのピンがボード上のどこに位置するかを返します。たとえば、ワイヤーを正しい穴に配線できるよう、U1 pin 8 (VCC) at [9, 3] のように表示します。
render_board	ボードをテキストで描画します。各穴を1セルとして、列番号と行番号を表示します。パーツキーと番号で示すピン（a1）、本体の下にある穴、ワイヤーの端点、接続せずにワイヤーが通過する穴、ストリップの切断箇所とメモ付きの穴を示し、各キーに対応するパーツと、ネットを含むすべてのワイヤーも表示します。area を指定するとボードの一部だけを描画します（穴が6000個を超える場合に必要です）。format: "png" を指定すると、代わりにエディターと同じようにボードの画像を描画します（穴の間隔は50ピクセルで、1000ピクセルに収まるよう縮小されます。area を指定するとその範囲を切り抜きます）。エージェントが画像を確認できます。
get_nets	ボード上で接続されているピンを返します。各ネットの名前（例：GND）、ピン（チップのピンなら U1.8 VCC、極性のある端子なら D1.K または C1.+、それ以外なら R1.1）、ワイヤーのほか、何にも接続されていないピン、接続点（3つ以上の要素が集まる穴）、交差（ワイヤーが別のワイヤーや穴の上を通過するが、接続しない箇所）を表示します。
validate_project	問題をすべて、その場所とともに一覧表示します。読み取れないエントリー、不明なパーツ、ボードからはみ出したピン、同じ穴にある2つのパーツのピンまたは端子、パーツの重なり、何にも接続されていないワイヤー（端点が浮いている、またはネット上にピンがない）、ピンの上を通過しているがそこで終端していないワイヤー、何にも接続されていない IC ピンと2端子パーツの端子、電源レールの短絡（VCC と 5V は同じレール、VCC と GND は短絡）、逆向きに接続された LED、電解コンデンサー、＋／−ピン、および電源をそのまま横切る向きに導通するダイオード（VCC、GND、5V などの名前が付いたピン、バッテリーホルダーの端子、+9V と記された穴からレールを判定します）、ストリップボード上でストリップにより短絡されたピン、または切断箇所の穴にあるピンを検出します。ワイヤーの交差は問題ではなく、注記として一覧表示されます。expectNets（意図したネットリスト。例：[["U1.8", "U1.4", "R1.1", "J1.1"], ["U1.2", "U1.6", "C1.+"]]）を渡すと、不足している接続や余分な接続はすべてエラーになります。保持中のプロジェクトではこの値が記憶されるため、edit_project と make_share_link でも照合されます（[] を指定すると記憶されている値が消去されます）。ここにプロジェクト全体を送信すると保持され、応答にその projectId が含まれます。
make_share_link	プロジェクトを検証し（指定または記憶されている expectNets を使用）、プロジェクトを開くリンクと、エディターと同じように描画されたボードの SVG 画像のアドレスを image として返します（下記のホストされた Worker から配信されます）。allowErrors を設定しない限り、エラーがあるプロジェクトは拒否されます。editorUrl を指定すると、http://localhost:3000/app/ など別のエディターにリンクします。デフォルト値は PERFBOARD_EDITOR_URL です。store: true（または希望する ID を storeAs: "led-blinker" と指定）を設定すると、プロジェクトも保存し（下記参照）、その ID、短縮リンク、ファイルと画像を stored として返します。いずれの場合も自己完結型のリンクが作成されます。保存に失敗した場合は、その理由が storeError に示されます。
show_board	エディターと同じように描画したボードの画像を、エディターで開くボタンとともにチャット内でユーザーに直接表示します。リンク先の Markdown 画像を読み込まないクライアント（例：Claude、ChatGPT）でも表示できる MCP App です。画像は結果の _meta 内でページに送られ、エージェントには送られません。ページは ui://perfboard/board-view.html リソースです。MCP Apps に対応していないクライアントでは何も表示されません。
read_share_link	エージェントに共有されたリンク（z=、json=、src=、または保存済みプロジェクトの短縮リンク）からプロジェクトを読み込み、projectId を付けて保持します。これにより、エージェントは既存のボードを変更できます。
プロジェクトを読み取るすべてのツールは、projectId またはプロジェクトファイル全体を project として受け取ります。保持された
プロジェクトはサーバープロセスが稼働している間（最近使用された200件）存続します。Cloudflareでは、最後に使用されてから30日間
保持されます。

エージェント向けの指示は短く保たれています（クライアントは約2 KBで切り詰めます）。完全なガイドはリソース perfboard://docs/guide（src/guide.ts）にあります。

また、次の形式もリソースとして提供します。perfboard://docs/project-file（プロジェクトファイルの形式をフィールドごとに解説）、 perfboard://docs/share-links（リンクの形式）、perfboard://parts （部品カタログ全体をJSONで提供）、およびサンプルプロジェクトです。perfboard://examples/555-led-blinker（ジャンパーですべて配線した パーフボード上の555 LED点滅回路）と perfboard://examples/555-led-blinker-stripboard（同じ回路をストリップボード上に構成したもの）。これらは ../examples/から読み込まれます。

Cloudflare Workersでのホスティング

公開版は https://mcp.perfboarddesigner.com/mcp で稼働しています。Claude Code、 claude.ai、ChatGPT、Cursorなどのクライアントへの追加方法は https://perfboarddesigner.com/mcp-server/ （../mcp-server/index.html）に記載されています。

同じサーバーはCloudflare Workerとしても稼働するため、 MCPクライアントは何もインストールせずにウェブ経由で接続できます。/mcpでストリーミング可能なHTTPを利用します （src/worker.ts）。ステートレスで、リクエストごとに新しいサーバーが作成されるため、保持されたプロジェクトをメモリ上に 置いておくことはできません。各プロジェクトは専用のDurable Object（ProjectHolder）に保持され、 projectIdを名前として使用し、未使用の状態が30日続くと破棄されます。プロジェクトIDはランダムなので、推測できません。 サインインは不要です。アドレスを知っている人なら誰でも利用できます。

また、基板の画像も生成します。共有リンクの#以降の部分（name=…&z=… またはjson=…。src=リンクは取得されません）を/render.svg?の後に付けると、その基板をSVG画像として返します。画像は エディター独自の基板レンダラー（../src/board-render/）で描画され、部品アイコンが埋め込まれています。同じパラメーターを指定して /render.png?にアクセスすると、SVGを表示できないチャットアプリやリンクプレビューなどで使えるPNG画像が返されます。アドレスに 画像の内容がすべて含まれるため、キャッシュの有効期限はありません （src/image-requests.ts）。

/render.pngとrender_boardが返すPNGは、同じSVGから resvgを使って描画します。resvgはWebAssemblyにコンパイルされています（@resvg/resvg-wasm、 MPL-2.0）。そのため、Workerとstdioのどちらでも同じ画像が生成されます（src/board-png.ts）。 小さな基板でも描画には約10分の1秒のCPU時間がかかり、Workers Freeプランのリクエストあたり10 msを大幅に超えるため、 ホスト型サーバーで画像を描画するには有料プランが必要です。

リクエストのたびに画像を再描画しないよう、Cloudflareの各データセンターは、配信するすべての画像と保存済みプロジェクトファイルのコピーを 保持します（WorkersのCache API）。保持期間はCache-Controlの指定に従い、 /render.*は1年間、保存済みプロジェクトは1日です。同じデータセンターへの繰り返しのリクエストには、再描画したり保存済みプロジェクトの Durable Objectを起動したりせずに、キャッシュから応答します（src/worker.tsのedgeCached()）。 成功した応答だけが保持されるため、不明なIDは次回も再度検索されます。基板の描画方法を変更した場合、古い画像は期限切れになるか、 Cloudflareダッシュボードでゾーンのキャッシュが消去されるまで残ります。キャッシュはworkers.devのアドレスでは機能せず、 カスタムドメインでのみ機能します。

保存済みプロジェクト

共有リンクにはプロジェクト全体が含まれるため、サーバーなしで動作しますが、長くなります。Worker はプロジェクトを短い ID で保存して配信することもできます。配信先は https://projects.perfboarddesigner.com です（リンクを壊さずにストレージを独立した Worker に移せるよう、同じ Worker の独自のアドレスを使用しています）。これは、エージェント向け（store を指定した make_share_link）とユーザー向け（エディターの共有ダイアログ）の短縮リンクの保存先です。どちらについても docs/share-links.md に説明があります。

リクエスト	応答
POST /projects with {"project": {…}, "id": "led-blinker", "name": "LED blinker"}（id と name は省略可能）	{id, link, file, image, png}：割り当てられた ID、短いエディターリンク、ファイルと画像
GET /projects?q=blinker&limit=20	ID または名前が一致する保存済みプロジェクト。新しいものから順に、リンクとページネーションカーソルを含みます
GET /<id>.json	プロジェクトファイル
GET /<id>.png、GET /<id>.svg	プロジェクトの画像

• ID は小文字、数字、ハイフンで構成され、指定された ID または名前から生成されます（"Mágneses kapcsoló!" → magneses-kapcsolo）。最大 40 文字で、大文字と小文字は区別されません。同じ ID の別のボードがある場合は、ボードの SHA-256 の先頭数文字が追加されます（led-blinker-08196a）。同じボードを同じ ID で再度保存すると、同じ ID が返されます。どちらも指定されていない場合、ID はハッシュになります。3 文字未満の ID、またはサーバー自体のアドレスを示す ID（mcp、render、projects など）には、常にハッシュが追加されます。
• 保存済みプロジェクトは変更されません。再度保存すると、新しい ID が作成されます。1 年間開かれないと削除されます（ファイルまたは画像へのリクエストがあるたびに、この期限は延長されます）。
• エディターで読み込める有効なプロジェクトファイルのみが保存され、サイズ上限は 1 MB です。
• 短縮リンクは p= 共有リンク（…/app/#name=LED%20blinker&p=led-blinker）で、エディターは確認を求めずにこのストレージから開きます。別の場所に保存する場合（PERFBOARD_PROJECTS_URL）、代わりにファイルを指す src= リンクになり、どのエディターでも開けます。リンクを知っている人は誰でもボードを閲覧できます。
• 保存されたプロジェクトはそれぞれ、ID を名前に持つ Durable Object（StoredProjectHolder）です。そのため、2 つのボードを同時に保存しても、同じ ID が割り当てられることはありません（src/stored-projects.ts、src/project-requests.ts）。stdio サーバーは POST /projects 経由で保存します。

まだサインインもレート制限もありません。誰でもプロジェクトを保存できます。

保存済みプロジェクトの検索

一覧は公開されており、トークンは不要です。mcp/ からデプロイします。

npm run worker:deploy

次に検索します。

curl 'https://projects.perfboarddesigner.com/projects?q=blinker&limit=20'

すべてのインデックス済みプロジェクトを一覧表示するには、q を省略します。検索では、ID または名前のリテラルな部分文字列に一致します（ASCII の大文字と小文字は区別しません）。limit のデフォルトは 20 で、1～100 を指定できます。応答は {projects: [{id, name?, storedAt, link, file, image, png}], nextCursor} です。storedAt は Unix ミリ秒単位の元の保存時刻です。次のページを取得するには、同じ q を指定し、nextCursor を URL エンコードした cursor クエリパラメーターとして渡します。null は結果がこれ以上ないことを示します。一覧はキャッシュされず、プロジェクトの有効期間も延長されません。

StoredProjectIndex Durable Object は新しい保存を追跡し、期限切れのプロジェクトを削除します。このインデックスのデプロイ前から存在するプロジェクトは、再度保存されるか、そのストレージオブジェクトから読み取られたときに表示されます（エッジキャッシュのヒットではストレージに到達しません）。これは過去の完全な一覧ではありません。以前は中央インデックスがなかったためです。一時的な MCP 作業用プロジェクトは含まれません。

ローカルで使う場合は、npm run worker:dev を実行し、http://localhost:8787/projects にクエリします。

ローカルで試す場合（http://localhost:8787/mcp）：

npm run worker:dev

Cloudflare アカウントに公開します（最初に一度だけ npx wrangler login を実行します）。

npm run worker:deploy

どちらも最初にビルドします。worker:dev は保存済みプロジェクトを http://localhost:8787 でも提供します。wrangler.toml は Worker の設定ファイルで、名前、ドメイン、Durable Object バインディング、およびリンクを開く場所を指定する [vars] の PERFBOARD_EDITOR_URL と、保存済みプロジェクトを提供する場所を指定する PERFBOARD_PROJECTS_URL が含まれます。次に、そのアドレスを使ってクライアントに追加します。

claude mcp add --transport http perfboard https://perfboard-designer-mcp.<your-subdomain>.workers.dev/mcp

Workers Free プランでは、リクエストの CPU 時間は 10 ms です。大きなボードをチェックすると超過する場合があります。Paid プランでは、はるかに長い時間が許可されます。

リリースの公開

このパッケージは npm で perfboard-designer-mcp として公開されており、サーバーは server.json に記述され、MCP Registry に com.perfboarddesigner/mcp として登録されています。server.json には、ホストされたアドレス（remotes）と npm パッケージ（packages）が記載されています。レジストリは、package.json の mcpName がその名前であること、および公開鍵を保持する DNS TXT レコードがルートドメインにあることで、perfboarddesigner.com の所有者であることを確認します。

1. バージョンを更新します。npm version patch（または minor）を実行し、server.json の先頭と npm パッケージのエントリーの両方で、同じ version を設定します。
2. npm publish を実行します（最初にビルドされます。npm から 2FA を求められます）。npm view perfboard-designer-mcp version に新しいバージョンが表示されるまで待ちます。
3. サーバーに変更があった場合は、Worker をデプロイします。npm run worker:deploy を実行します。
4. mcp-publisher を使ってレジストリに公開します。mcp/ で mcp-publisher validate、続いて mcp-publisher login dns --domain perfboarddesigner.com --private-key "$PRIVATE_KEY" と mcp-publisher publish を実行します。

鍵ペアは OpenSSL 3 で一度だけ作成し、公開鍵を perfboarddesigner.com（Cloudflare DNS）の TXT レコードとして追加します。key.pem はリポジトリの外に保管してください。

openssl genpkey -algorithm Ed25519 -out ~/.config/mcp-registry/key.pem
echo "v=MCPv1; k=ed25519; p=$(openssl pkey -in ~/.config/mcp-registry/key.pem -pubout -outform DER | tail -c 32 | base64)"
PRIVATE_KEY="$(openssl pkey -in ~/.config/mcp-registry/key.pem -noout -text | grep -A3 'priv:' | tail -n +2 | tr -d ' :\n')"

接続の仕組み

ワイヤーは絶縁されたジャンパー線です。ワイヤーは両端の穴だけを接続します。穴の上を通っても接続されず、2 本のワイヤーが交差しても短絡しないため、交差しても問題ありません（エディターでは接合部と誤認されないように表示され、3D ビューでは上側のワイヤーがアーチ状になります）。1 つの穴には部品 1 つのピンまたはリード線を最大 1 つ差し込めます（実際のボードと同様、別の部品をもう 1 つ差し込むとエラーになります）。また、ワイヤーの端は何本でも差し込めます。穴の中にあるものはすべて接続されます。2 つの部品を接続するには、ピンの間にワイヤーを引きます。ジャンパー線ははんだ面に配置することもできます（side: "bottom"、フォーマットバージョン 9）。端の穴同士を同じように接続しますが、上面のワイヤーとは決して交差しません。 ストリップボードでは、ストリップ上のすべての穴が、次に切断された箇所まで接続されています。切断箇所の穴は何にも接続されません。get_nets と validate_project は、エディターの Nets パネルと同じコードで接続状態を判定するため、表示内容と一致します。

構成

src/ がサーバーです。create-server.ts が全体を組み立て、server.ts は stdio 経由で、worker.ts は Cloudflare 上で実行します。tools/ にはグループ別のツール、resources.ts には提供するドキュメント、project-handles.ts には保持するプロジェクト（およびその保存場所）、edit-ops.ts と edit-project.ts には edit_project の操作、validate.ts には検証処理、guide.ts にはその説明とガイドが含まれています。board-view/ は show_board がボードを表示するページです（MCP Appです。view.ts はクライアントのフレーム内で動作し、必要な少数の MCP Apps メッセージを独自に処理するため、ページのサイズを数 KB に抑えられます）。エディター独自の純粋なコードを基盤としており、すべて editor.ts 経由で取り込んでいます。editor.ts は ../src/ からインポートする唯一のファイルです。対象となるのは、../src/project-file/ のプロジェクトファイル読み込み処理、共有リンクのコード、ピンの位置、ネット（nets.ts）、ワイヤーの交差（wire-crossings.ts）、../src/parts/ のパーツ定義とパーツの形状、ボード画像の描画に使う ../src/board-render/ です。これにより、フォーマット、パーツ、接続状態について、常にエディターと同じ認識を保てます。エディターがここから何かをインポートすることはありません。npm run build は、コードと MCP SDK をまとめて実行時依存関係のない単一の dist/server.js（Cloudflare 用には dist/worker.js も）にバンドルし、提供するドキュメントとサンプル、画像に埋め込むパーツアイコン、show_board のページ（view.ts をブラウザー用にバンドルした board-view/view.html）も組み込みます。PNG 画像には resvg の WebAssembly も必要です。ビルド時に dist/resvg.wasm として同じ場所にコピーされます（Worker と一緒にアップロードします）。また、resvg はシステムフォントを使用できないため、フォントも必要です。ボードで使われる文字に絞った Noto Sans と Noto Sans Mono が fonts/ にあります（SIL Open Font License。再生成方法は fonts/README.md を参照してください）。

コマンド	処理内容
npm run build	dist/server.js と dist/worker.js をバンドルします
npm run typecheck	サーバーと、サーバーがインポートするエディターのコードを型チェックします
npm run worker:dev	Cloudflare Worker をローカルの http://localhost:8787/mcp で実行します
npm run worker:deploy	Worker を Cloudflare に公開します
npm version patch、続けて npm publish	npm に新しいバージョンをリリースします（prepublishOnly が最初にビルドします。npm から 2FA を求められます）
npm run inspect	MCP Inspector でサーバーを開き、ツールを手動で試します

要件とコンポーネントの識別情報

共有リーダーは、任意の独立した requirements を含むフォーマット 8 に対応しています。フォーマット 7 では、プロジェクト単位のコンポーネント instanceId フィールドが追加されます。edit_project は、意図されたすべてのネットを維持し、新しいパーツには新しい識別情報を割り当て、接続は割り当てずに要件インベントリに追加します。削除された必須パーツは、別のパーツが同じ参照名を再利用しても、識別情報によって引き続き報告できます。旧エディターの schematic フィールドは無視されます。

requirements.validate が true の場合、チェックでは保存された要件とボードも照合します。不足しているコンポーネントやピン、接続の不足、想定外の接続はエラーになります。網羅が不完全な場合は警告となり、要件を完全に満たしているとは決して説明されません。指定されていないピンはチェックされません。これは既存の完全リスト expectNets 契約とは独立しており、その契約に変更はありません。プロジェクト形式のリソースには要件の種類が含まれています。

ホスト型ストレージ経由でフォーマット 8 のファイルを共有する前に、この共有リーダーをフロントエンドと一緒にデプロイしてください。埋め込みリンクは、ホスト型ストレージがなくても引き続き使用できます。