PhysBox: MCP

PhysBox: MCP は、Model Context Protocol (MCP) サーバーであり、LLM や MCP クライアント (Claude Code や Claude Desktop など) が、ブラウザ上の 4 つのシミュレーション Web アプリケーションとプログラム的に連携できるようにします:

すべての通信は、ブラウザ内の Web アプリと直接 WebSocket 経由で JSON を介して行われます。ブラウザの自動化や DOM スクレイピングは必要ありません。

🧠 唯一の AI ネイティブ物理世界モデル

静的なコード生成やオフラインのファイル出力とは異なり、PhysBox は AI エージェントに 対話型のグラウンドトゥルース (ground-truth) 世界モデル を提供します。LLM は 81 の型付けされたツール呼び出しを実行し、空間運動学、回路ノード波形、G コード安全警告などを観察することで、反復的に設計を自己修正できます。

💬 Claude Code および Cursor 向けエージェントプロンプト例

以下のプロンプトを MCP 接続されたエージェントに直接貼り付けてください:

• Volt (エレクトロニクス):

  "アクティブ Volt 回路図内の RC フィルター値を最適化して 1 kHz のカットオフ周波数を実現し、circuit_run_sim を実行してゲイン特性をプロットしてください。"

• Mesh (3D 物理 & CAD):

  "Mesh で 4mm のネジ穴を持つ OpenSCAD パラメトリック取付ブラケットを作成し、physics_check_collisions を使用して MuJoCo 衝突安定性チェックを実行し、Z アップの STL をエクスポートしてください。"

• Etch (CNC & レーザー):

  "このベクター SVG ロゴをインポートし、合板向けの 2 パス 3mm ステップダウンフィードを適用し、エンドミルの安全警告を確認し、GRBL G コードを生成してください。"

Related MCP server: Tesseron

仕組み

PhysBox: MCP は、ポート 3142 で WebSocket リレーを確立するローカルコンパニオンサーバーとして機能します。

いずれかのシミュレーション Web アプリを開くと、そのアプリはこの WebSocket リレーに直接接続されます。MCP クライアントがツール呼び出しを実行すると、コマンドはクライアントからコンパニオンサーバーに送られ、アクティブなブラウザタブに転送され、結果が戻ってきます。

MCP Client (e.g. Claude Desktop)
  └── spawns → physbox-mcp (stdio)
                 └── WebSocket Server (ws://localhost:3142)
                                ├── Flux
                                ├── Volt
                                ├── Mesh
                                └── Etch

インストール

コンパニオンサーバーを PyPI から直接インストールします:

pip install physbox-mcp

使用方法 & セットアップ

1. Web アプリケーションを開く

Web ブラウザでシミュレーション Web アプリケーションを起動またはアクセスします:

• Flux: flux.physbox.io

• Volt: volt.physbox.io

• Mesh: mesh.physbox.io

• Etch: etch.physbox.io

ページの読み込みが完了するとすぐに、自動的にコンパニオン WebSocket サーバーに登録されます。

2. MCP クライアントを設定する

Claude Desktop の場合

Claude Desktop 設定ファイル (通常は Windows では AppData/Roaming/Claude/claude_desktop_config.json、macOS では ~/Library/Application Support/Claude/claude_desktop_config.json にあります) に以下のブロックを追加します:

{
  "mcpServers": {
    "physbox-mcp": {
      "command": "physbox-mcp",
      "args": ["--stdio"]
    }
  }
}

Claude Code / ローカルワークスペース (.mcp.json) の場合

プロジェクトルートに .mcp.json ファイルを追加するか (またはグローバル設定 ~/.claude/mcp.json を更新します):

{
  "mcpServers": {
    "physbox-mcp": {
      "type": "stdio",
      "command": "physbox-mcp",
      "args": ["--stdio"]
    }
  }
}

ソースから開発中ですか？ クローンしたリポジトリや仮想環境から直接実行する場合は、Python インタープリタを使用してください:

{
  "mcpServers": {
    "physbox-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "physbox_mcp.server", "--stdio"]
    }
  }
}

(必要に応じて "python" を仮想環境の Python 実行ファイルのパスに置き換えてください。例: /path/to/venv/bin/python)。

Google Antigravity IDE の場合

Windows/WSL 環境では、Antigravity IDE はグローバル設定ディレクトリから設定を読み取ります。グローバルディレクトリ (~/.gemini/config/) は書き込み制限されている可能性があるため、書き込み可能な ~/.gemini/antigravity/ フォルダーにリンクする必要があります:

1. PowerShell で、グローバル設定ターゲットから書き込み可能なユーザーディレクトリへの ハードリンク を作成します:

   # Delete the empty placeholder file if it exists
   Remove-Item -Path "$env:USERPROFILE\.gemini\config\mcp_config.json" -Force -ErrorAction SilentlyContinue
   
   # Create a Hard Link to the writable copy
   New-Item -ItemType HardLink -Path "$env:USERPROFILE\.gemini\config\mcp_config.json" -Target "$env:USERPROFILE\.gemini\antigravity\mcp_config.json"

2. physbox-mcp WSL 設定を mcp_config.json に追加します (<your-wsl-distro> を WSL ディストリビューション (例: Ubuntu-20.04) に置き換えてください):

   {
     "mcpServers": {
       "physbox-mcp": {
         "command": "C:\\Windows\\system32\\wsl.exe",
         "args": [
           "-d",
           "<your-wsl-distro>",
           "physbox-mcp",
           "--stdio"
         ]
       }
     }
   }

   (WSL でソースから開発する場合は、args 内で仮想環境の Python バイナリと -m physbox_mcp.server を代わりに渡してください)。

3. IDE を再起動 するか (またはエージェントチャットセッションを閉じてリロードし)、MCP ツールをネイティブに登録します。

3. コンパニオンサーバーを手動で実行する (オプション)

Stdio モードではなく HTTP モードでサーバーを実行する場合は、以下のように実行できます:

# Starts HTTP server listening on port 3141 (default)
physbox-mcp

または、カスタムポートパラメータを設定します:

physbox-mcp --port=4000

開発 & コントリビューション

ローカル開発、スキーマの変更、ツール定義の拡張、手動ビルドに関する手順については、README_DEV.md を参照してください。