PhysBox: MCP

PhysBox: MCP es un servidor del Protocolo de Contexto de Modelo (MCP) que permite a los LLM y clientes MCP (como Claude Code o Claude Desktop) interactuar programáticamente con las cuatro aplicaciones web de simulación en el navegador:

Toda la comunicación se maneja mediante JSON a través de WebSockets directamente a la aplicación web en tu navegador, sin necesidad de automatización del navegador ni extracción del DOM.

🧠 El Único Modelo del Mundo Físico Nativo para IA

A diferencia de la generación estática de código o las salidas de archivos sin conexión, PhysBox proporciona a los agentes de IA un modelo del mundo interactivo y veraz. Los LLM ejecutan 81 llamadas a herramientas tipadas para observar cinemática espacial, formas de onda en nodos de circuitos y advertencias de seguridad de G-code, lo que les permite autocorregir diseños de forma iterativa.

💬 Ejemplos de Prompts para Agentes en Claude Code y Cursor

Pega cualquiera de estos prompts directamente en tu agente conectado a MCP:

• Volt (Electrónica):

  "Optimiza los valores de los filtros RC en el esquema activo de Volt para lograr una frecuencia de corte de 1 kHz, luego ejecuta circuit_run_sim y grafica la respuesta en magnitud."

• Mesh (Física 3D y CAD):

  "Escribe un soporte de montaje paramétrico en OpenSCAD en Mesh con agujeros para tornillos de 4 mm, ejecuta una verificación de estabilidad de colisiones con MuJoCo usando physics_check_collisions y exporta el STL con el eje Z hacia arriba."

• Etch (CNC y Láser):

  "Importa este logotipo SVG vectorial, aplica pasos de 2 pasadas con descenso de 3 mm para madera contrachapada, verifica las advertencias de seguridad de la fresa y genera el G-code GRBL."

Related MCP server: Tesseron

Cómo Funciona

PhysBox: MCP funciona como un servidor acompañante local que establece un relé WebSocket en el puerto 3142.

Cuando abres cualquiera de las aplicaciones web de simulación, estas se conectan directamente a este relé WebSocket. Cuando un cliente MCP ejecuta una llamada a una herramienta, el comando fluye desde el cliente al servidor acompañante, se reenvía a la pestaña activa del navegador y los resultados regresan.

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

Instalación

Instala el servidor acompañante directamente desde PyPI:

pip install physbox-mcp

Uso y Configuración

1. Abre las Aplicaciones Web

Inicia o accede a las aplicaciones web de simulación en tu navegador web:

• Flux: flux.physbox.io

• Volt: volt.physbox.io

• Mesh: mesh.physbox.io

• Etch: etch.physbox.io

Tan pronto como una página termine de cargarse, se registrará automáticamente con el servidor WebSocket acompañante.

2. Configura tu Cliente MCP

Para Claude Desktop

Agrega el siguiente bloque a tu archivo de configuración de Claude Desktop (ubicado típicamente en AppData/Roaming/Claude/claude_desktop_config.json en Windows o ~/Library/Application Support/Claude/claude_desktop_config.json en macOS):

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

Para Claude Code / Espacio de Trabajo Local (.mcp.json)

Agrega un archivo .mcp.json a la raíz de tu proyecto (o actualiza tu configuración global en ~/.claude/mcp.json):

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

¿Desarrollando desde el código fuente? Si ejecutas directamente desde un repositorio clonado o un entorno virtual, usa tu intérprete de Python:

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

(Reemplaza "python" con la ruta al ejecutable de Python de tu entorno virtual si es necesario, por ejemplo /path/to/venv/bin/python).

Para Google Antigravity IDE

En configuraciones Windows/WSL, Antigravity IDE lee la configuración desde el directorio de configuración global. Dado que el directorio global (~/.gemini/config/) puede tener restricciones de escritura, debes enlazarlo a la carpeta escribible ~/.gemini/antigravity/:

1. En PowerShell, crea un Enlace Fijo desde el destino de configuración global al directorio de usuario escribible:

   # 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. Agrega la configuración de WSL physbox-mcp a tu mcp_config.json (reemplazando <your-wsl-distro> con tu distribución WSL, como Ubuntu-20.04):

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

   (Si desarrollas desde el código fuente en WSL, pasa el binario de Python de tu entorno virtual y -m physbox_mcp.server en args en su lugar).

3. Reinicia el IDE (o cierra y recarga la sesión de chat del agente) para registrar las herramientas MCP de forma nativa.

3. Ejecuta el Servidor Acompañante Manualmente (Opcional)

Si estás ejecutando el servidor en modo HTTP en lugar de Stdio, puedes ejecutar:

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

O configurar parámetros de puerto personalizados:

physbox-mcp --port=4000

Desarrollo y Contribución

Para instrucciones sobre desarrollo local, modificación de esquemas, extensión de definiciones de herramientas y compilaciones manuales, consulta README_DEV.md.