tensorcad

@tensor-cad/mcp

トレーニングスクリプトを書く前に、アシスタントがトランスフォーマー言語モデルを設計し、コストを調べられるようにする MCP サーバーです。

@tensor-cad/engine をラップしています。これは Go から WebAssembly にコンパイルされた解析エンジンで、型付きブロックグラフ、シンボリックな形状推論、設計ルールチェック、パラメーター数／FLOPs／メモリ／コストのモデル、PyTorch エミッターを備えています。このサーバーはヘッドレスで、.tensorcad.json ファイルと組み込みのリファレンスアーキテクチャを扱うため、エディターを起動する必要はありません。

公式の TypeScript SDK v2（@modelcontextprotocol/server 2.0.0）を基盤とし、stdio 経由で提供されます。

インストール

Claude Code

# from a checkout, during development
claude mcp add --transport stdio tensorcad -- bun packages/mcp/src/stdio.ts

# published
claude mcp add --transport stdio tensorcad -- npx -y @tensor-cad/mcp

--scope project を追加すると、リポジトリを使う全員のために、コミット可能な .mcp.json が書き込まれます。すると、リソースは @tensorcad:tensorcad://... メンションとして、プロンプトは /mcp__tensorcad__design_model として表示されます。

Cursor

プロジェクト内の .cursor/mcp.json、またはすべてのプロジェクトで使う場合は ~/.cursor/mcp.json を設定します。

{
  "mcpServers": {
    "tensorcad": {
      "command": "npx",
      "args": ["-y", "@tensor-cad/mcp"]
    }
  }
}

Cursor では、すべてのサーバーを通じて有効にできるツールの数が限られているため、このサーバーに搭載するツールは40個ではなく18個です。

Claude Desktop、ワンクリックで

リリースから tensorcad.mcpb をダウンロードして開きます。Claude Desktop が拡張機能としてインストールし、設計を保存するフォルダーを一度だけ尋ねます。

バンドルには、Node 向けにビルドされたサーバー（Claude Desktop には同梱されていますが、このリポジトリでは使用していません）と、その隣に WebAssembly エンジンが含まれています。bun run build:mcpb はバンドルをビルドし、完了前に Node で起動します。問題を引き起こした2つの要因は、どちらもサーバー自体ではなく、Bun と Node の違いだったためです。

Claude Desktop、手動で設定

claude_desktop_config.json（Settings、Developer、Edit Config）：

{
  "mcpServers": {
    "tensorcad": {
      "command": "npx",
      "args": ["-y", "@tensor-cad/mcp"],
      "env": { "TENSORCAD_ROOT": "/absolute/path/to/your/designs" }
    }
  }
}

任意のクライアント

mcp.example.json は、リポジトリのルートから実行する bun packages/mcp/src/stdio.ts を使った、リポジトリ相対パスでの開発用設定です。

TENSORCAD_ROOT は、tensorcad_list_designs が .tensorcad.json ファイルを検索するディレクトリと、相対パスの基準となるディレクトリを指定します。デフォルトはプロセスの作業ディレクトリです。

ツール

18個あり、すべて tensorcad_ で名前空間が付けられています。各ツールは inputSchema と outputSchema を宣言し、読みやすいテキストのミラーと併せて structuredContent を返します。読み取りには readOnlyHint と idempotentHint が注釈され、何かを上書きする2つのツールには destructiveHint が注釈されています。

ツール	機能
tensorcad_list_designs	開いている設計、組み込みのリファレンスアーキテクチャ、ディスク上の .tensorcad.json ファイルを一覧表示します
tensorcad_new_design	プリセット、または空の状態から開始し、design_id を返します
tensorcad_open_design	.tensorcad.json を読み込みます。同じパスを2回開くと、同じハンドルを返します
tensorcad_save_design	設計をディスクに書き戻します
tensorcad_get_design	format: "outline"（デフォルト）または "full"
tensorcad_get_block	1つのブロックについて、記述どおりのパラメーターと解決後のパラメーター、ポートの形状、配線、パラメーター数を表示します
tensorcad_search_catalog	パラメータースキーマ、ポートパターン、ドキュメントを含むブロックカタログを検索します
tensorcad_apply_ops	楽観的並行制御による一括編集を実行します
tensorcad_validate	すべての設計ルールを検証し、各指摘に修正のヒントを示します
tensorcad_analyze	パラメーター数、FLOPs、KV キャッシュ、メモリ、スループット、コスト、Chinchilla を分析します
tensorcad_generate_code	PyTorch モジュールと設定を生成し、インラインで返すかディレクトリに書き込みます
tensorcad_checkpoint	名前付きスナップショットを作成します
tensorcad_restore	チェックポイントの状態に戻すか、最後の一括処理を取り消します
tensorcad_explain	1つのブロックについて、何を担うのか、なぜそのサイズなのかを説明します
tensorcad_scale	比率を保ちながら、パラメータ予算に合わせて設計を縮小します
tensorcad_plan	クラスター全体でトレーニングを分割するすべての方法と、そのうち実行可能な方法を示します
tensorcad_diff	2つの設計間で構造上および数値上、何が変わったかを示します
tensorcad_import_hf	Hugging Face の config.json を読み込んで設計に変換します

ほかのツールでは答えられない5つの質問に答える

analyze は設計にかかるコストを示しますが、その理由までは示しません。explain は1つのパスを受け取り、エージェントが文書全体を読んで調べなくても、記述されたとおりのパラメーターと評価後のパラメーター、すべてのポートの形状、モデルの重みと計算量に占める割合を示します。

編集を支えるもう1つの機能が diff です。4つの操作を適用した直後のエージェントは、編集前の設計と比べて、構造上および数値上の変更点を確認できます。plan は、そもそもそれらが重要かどうかを決める問いに答えます。利用可能なマシンで学習できるか、また、どのように分割する必要があるかを示します。

scale と import_hf はどちらもレポートではなく設計を生成し、セッションに保存します。そのため、ほかの設計と同じように分析、差分の確認、生成ができます。これが、ストアに adopt が追加された理由です。create はプリセットから、または何もない状態から設計を作成しますが、これらのツールは完成した設計を受け取ります。

セッションではなくハンドル

tensorcad_new_design と tensorcad_open_design は design_id を生成し、それ以外のすべてのツールはそれを引数として受け取ります。これは2026-07-28の改訂で求められている方法です。呼び出しをまたぐ状態は接続状態ではなく、明示的なハンドルで受け渡されます。そのため、クライアントは会話の途中でサーバーを再起動しても、どの設計について話しているのかを見失いません。

各設計には revision があり、変更のたびに値が増加します。tensorcad_apply_ops に expected_revision を渡すと、同時編集が発生した場合に、現在のリビジョンを示す明確なエラーが返され、気付かないうちに上書きされることはありません。

30個のセッターではなく、1つのパッチツール

tensorcad_apply_ops は操作のリストを受け取り、コピーに対して順番に適用します。最初に拒否された操作でバッチ全体が中止され、設計は変更前の状態のまま保たれるため、操作の一部だけが適用された状態が表に出ることはありません。

操作	フィールド
add_node	parent?、id、type、params?、label?
remove_node	path（そのエッジも一緒に削除されます）
set_param	path、key、value
connect	graph?、from、to
disconnect	graph?、from、to
set_symbol	name、value（数値、式、または削除する場合は null）、doc?、runtime?
rename	path、id（エッジも書き換えられます）
set_label	path、label

path はスラッシュ区切り（layers/block）で、エンドポイントは各自のグラフ内でローカルな blockId:port です。多くの設計はシンボル（L 層、D 幅、H ヘッド、Hkv キー／値ヘッド、dh ヘッド次元、F フィードフォワード幅、V 語彙数）でパラメーター化されているため、個々のブロックを変更するより、通常は set_symbol を使うのが適切です。

リソース

URI	内容
tensorcad://designs/{id}	ドキュメントとその概要
tensorcad://designs/{id}/validation	すべての指摘事項
tensorcad://designs/{id}/analysis	ドキュメント自体のデフォルト値に基づくすべての数値
tensorcad://catalog	パラメータースキーマとポートパターンを含む、すべてのブロックタイプ
tensorcad://catalog/{type}	1つのブロックタイプ
tensorcad://schema/design	.tensorcad.json 形式の JSON Schema

テンプレート形式のリソースは引数補完に対応しており、設計とカタログのテンプレートはそれぞれのインスタンスを列挙します。そのため、クライアントはIDを推測せずにこれらを提示できます。

プロンプト

design_model（目標パラメーター数、コンテキスト長、ファミリー）、review_design、scale_design、explain_costs。

典型的なセッション

tensorcad_new_design { preset: "llama-3-8b" }        -> dsn_1, revision 1
tensorcad_get_design { design_id: "dsn_1" }          -> the outline: symbols, blocks, edge shapes
tensorcad_checkpoint { design_id: "dsn_1" }          -> ckpt_1
tensorcad_apply_ops  { design_id: "dsn_1", expected_revision: 1,
                    ops: [{ op: "set_symbol", name: "D", value: 5120 },
                          { op: "set_symbol", name: "L", value: 40 }] }
                                                  -> revision 2, parameters and a validation summary
tensorcad_validate   { design_id: "dsn_1" }          -> findings with fix hints
tensorcad_analyze    { design_id: "dsn_1", T: 8192, hardware: "h100-sxm", gpus: 8, zero: 3 }
tensorcad_generate_code { design_id: "dsn_1", out_dir: "out/my-model" }
tensorcad_restore    { design_id: "dsn_1", checkpoint_id: "ckpt_1" }   # if it did not work out

ライブエディターブリッジ

TENSORCAD_BRIDGE=1 を指定してサーバーを起動すると、実行中の TensorCAD エディターが接続します。エージェントの編集は行われるそばからキャンバスに表示され、人間の編集も逆方向に反映されます。

TENSORCAD_BRIDGE=1 bun run packages/mcp/src/stdio.ts

次にエディターを開きます（bun run --cwd packages/ui dev、またはデスクトップビルド）。ステータスバーの右端のセルに agent と表示され、押すと接続が解除されます。

処理の流れは次のとおりです。エディターがブリッジを見つけ、画面上のデザインを公開します。これにより、エージェントはそれに似たファイルではなく、そのデザインを編集できます。そして、エージェントは tensorcad_list_designs でデザインを確認できます。それ以降、tensorcad_apply_ops による変更はキャンバスに反映され、人間が行った変更はエージェントのストアに反映されます。その時点で、デザインのリソースが変更されたことが notifications/resources/updated を通じてクライアントに通知されます。エージェントから届いた編集はエディターの取り消しスタックに追加されるため、見ている人が元に戻せます。

ドキュメントは2つありません。以前の設計では、LiveStore を FileStore の隣に置き、両方を DocumentStore の背後に配置していました。この設計では、デザインの保存先が2つになり、内容が異なる場合にどちらを正とするかのルールもありません。ブリッジは、ツールがすでに書き込んでいる1つのストアを監視し、エディターの編集もツール呼び出しと同じ apply を通じて行われます。リビジョンチェックも取り消しログも同じです。

明示的に要求されない限り無効です。 環境変数を設定しなければ、サーバーはポートを開かず、これまでどおり完全にヘッドレスです。そのため、CI でも利用できます。

接続できる相手。 127.0.0.1 にバインドするため、マシンの外部からは接続できません。Origin が localhost のものではないアップグレード要求は拒否します。同一オリジンポリシーでは、インターネット上のページからループバックアドレスへの WebSocket 接続を開くことを防げないためです。また、トークンも必要です。このトークンは所有者のみがアクセスできる権限で ~/.tensorcad/session.json に書き込まれ、GET /session を呼び出したループバックのクライアントに提供されます。ブラウザーはこのファイルを読み取れません。このエンドポイントが存在する理由はそれだけです。このマシンであなたのユーザーとしてすでに実行されているものなら、いずれにせよファイルを読み取れます。このトークンはそれを防ぐものではなく、そのためのものでもありません。

TENSORCAD_BRIDGE_PORT を設定すると、ポートを 7357 以外にできます。エディターはそのポートと、その上の3つのポートを順に確認します。ポートが使用中の場合にブリッジが順に試す範囲も同じです。

意図的に含めていないものもあります。tensorcad_render_preview（キャンバスの画像にはエディターが必要です）と、tensorcad_run_script（スクリプト実行のための抜け道であり、リリースに値するものにするにはサンドボックスとオプトインの環境変数が必要です）です。どちらも今後のツールとして調査メモに記載されています。これらを含めないことで、クライアントにとって扱いやすいツール数を保っています。

公開

この README と同じディレクトリにある server.json は、MCP レジストリのマニフェストです。名前空間（io.github.Filip-Pajalic/tensorcad。package.json の mcpName と一致します）、参照先の npm パッケージ、サーバーが読み取る唯一の環境変数が記載されています。書き込む際にはレジストリ独自のスキーマに照らして検証し、テスト実行のたびに package.json と照合します。ずれが生じるのはスキーマではなく、2つのファイルに記載されたバージョンだからです。

名前空間は、大文字・小文字も含め、GitHub でのアカウント名の表記に合わせています。レジストリは GitHub ログインに対して、所有者自身の大文字・小文字の表記を使った io.github.<owner>/* を許可し、大文字・小文字を区別して比較します。そのため、GitHub 自体は大文字・小文字を区別しなくても、小文字の名前空間は 403 で拒否されます （registry#689）。 リポジトリの URL と名前空間が一致することをテストで確認しています。

リリースワークフローが公開処理を行います。参照先のパッケージを npm ジョブがアップロードした後、registry ジョブがワークフロー独自の GitHub OIDC トークンで認証します。シークレットは不要です。その後、mcp-publisher publish を実行します。このディレクトリから手動で実行する場合：

mcp-publisher login github
mcp-publisher publish

開発

bun run packages/mcp/src/stdio.ts     # serve on stdio
bun test packages/mcp/test            # contract tests: spin the server up and call every tool

コントラクトテストでは、実際の stdio パイプ経由で SDK 自身のクライアントに接続し、各ツールの structuredContent を、そのツールが提示した outputSchema に照らして検証します。これにより、宣言されたコントラクトと実際の応答に食い違いが生じることはありません。