Pybullet MCP Server

Un servidor mcp para la librería pybullet, soporta 20 herramientas (ej: creación de simulaciones, pasos, carga de robots urdf, etc.)

GitHub

Documentación

Servidor MCP de PyBullet

Un servidor de Protocolo de Contexto de Modelo (MCP) que permite a los asistentes de IA interactuar con simulaciones de física de PyBullet. Crea proyectos basados en física mediante interacciones en lenguaje natural con agentes de IA.

Características

  • 37 Herramientas MCP: API integral para el control de simulaciones de física, incluido el control de articulaciones de robots
  • Gestión de Simulaciones: Crea y gestiona múltiples simulaciones de física independientes con gravedad configurable
  • Manipulación de Objetos: Añade formas primitivas (caja, esfera, cilindro, cápsula) y modelos URDF con control completo de propiedades
  • Control de Robots: Consulta información de articulaciones, controla motores (posición/velocidad/torque) y calcula cinemática inversa
  • Control de Física: Aplica fuerzas, torques y avanza en las simulaciones con pasos de tiempo configurables
  • Persistencia de Estado: Guarda y carga estados completos de simulación desde/hacia archivos JSON
  • Restricciones: Crea articulaciones entre objetos (fijas, prismáticas, esféricas)
  • Detección de Colisiones: Consulta puntos de contacto con información detallada de colisiones
  • Visualización: Modo GUI opcional con visualización de depuración y control de cámara
  • Manejo de Errores: Validación integral con mensajes de error descriptivos

Notas Importantes

  • Requisitos de Coordenadas: Todos los vectores deben proporcionarse como coordenadas 3D completas [x, y, z]
    • Gravedad: [0, 0, -9.81] (no [-9.81])
    • Posiciones: [x, y, z] (no [x, y] ni [x])
    • Fuerzas/Torques: [fx, fy, fz] (no [fx])
    • Orientaciones: [x, y, z, w] cuaternión (no [w])
  • Restricción de Masa: La masa del objeto debe ser positiva (masa > 0). Usa masa grande (ej., 1000) para objetos estáticos
  • Limitación de GUI: Solo una simulación GUI puede estar activa a la vez (limitación de PyBullet)
  • Rutas URDF: Usa rutas absolutas o rutas relativas al directorio de trabajo del servidor
  • Articulaciones Revolutas: create_constraint no admite "revolute" — usa generate_revolute_joint + load_urdf en su lugar. Siempre pasa un output_path explícito dentro del espacio de trabajo a generate_revolute_joint, de lo contrario el URDF generado termina en /tmp/ y load_urdf lo rechazará.

Instalación

Requisitos Previos

  • Python 3.9 o superior
  • Gestor de paquetes pip
  • Entorno virtual (recomendado)

Instalar Dependencias

  1. Crea y activa un entorno virtual:
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Instala FastMCP y PyBullet:
pip install fastmcp pybullet
  1. Para desarrollo (incluye herramientas de prueba):
pip install fastmcp pybullet pytest hypothesis pytest-cov

Verificar Instalación

Comprueba que los paquetes requeridos estén instalados:

python -c "import pybullet; import mcp; print('Installation successful!')"

Inicio Rápido

Ejecutar el Servidor

Consulta QUICKSTART.md para instrucciones detalladas sobre:

  • Iniciar el servidor
  • Configurar Claude Desktop
  • Ejemplos de indicaciones para explorar todas las funciones
  • Flujos de trabajo comunes y casos de uso

Comando rápido:

source venv/bin/activate  # On Windows: venv\Scripts\activate
python -m src.server

El servidor se iniciará y escuchará conexiones de protocolo MCP desde asistentes de IA.

Ejemplo de Uso con Cliente MCP

Una vez conectado a un cliente MCP (como Claude Desktop), puedes interactuar mediante lenguaje natural:

1. Crear una simulación:

Create a new physics simulation with Earth gravity

Esto llama a create_simulation con gravedad [0, 0, -9.81].

Importante: La gravedad debe ser un vector 3D. El servidor acepta notación abreviada como [-9.81] y la expande a [0, 0, -9.81].

2. Añadir objetos:

Add a red box at position (0, 0, 1) with dimensions 0.5x0.5x0.5 and mass 1.0

Esto llama a add_box para crear un objeto de caja. La posición se expande automáticamente a [0, 0, 1].

Add a sphere at (2, 0, 1) with radius 0.3

Esto llama a add_sphere para crear una esfera.

Nota: La masa debe ser positiva. Para objetos estáticos (como planos de suelo), usa valores de masa grandes (ej., 1000).

3. Ejecutar la simulación:

Step the simulation forward 100 times

Esto llama a step_simulation con steps=100.

4. Consultar el estado del objeto:

What is the position and velocity of object 0?

Esto llama a get_object_state para recuperar posición, orientación y velocidades.

5. Aplicar fuerzas:

Apply a force of [10, 0, 0] to object 0

Esto llama a apply_force para empujar el objeto.

6. Guardar la simulación:

Save the current simulation state to simulation.json

Esto llama a save_simulation para persistir el estado.

7. Cargar una simulación:

Load the simulation from simulation.json

Esto llama a load_simulation para restaurar el estado guardado.

Configuración MCP

Para usar este servidor con Cursor o cualquier otro cliente compatible con MCP, añade lo siguiente a tu archivo de configuración MCP:

{
  "mcpServers": {
    "pybullet": {
      "url": "http://localhost:8000/mcp",
      "disabled": false
    }
  }
}

El servidor ejecuta transporte HTTP por defecto. Puedes cambiar el método de transporte editando el punto de entrada en server.py:

if __name__ == "__main__":
    mcp.run(transport="http", port=8000)

Reinicia tu cliente MCP después de actualizar la configuración.

Herramientas Disponibles

El servidor expone 37 herramientas a través del protocolo MCP:

Gestión de Simulaciones (5 herramientas)

  • create_simulation: Inicializa una nueva simulación de física con gravedad configurable y GUI opcional

    • Parámetros: gravity (list[float], predeterminado: [0, 0, -9.81]), gui (bool, predeterminado: false)
    • Devuelve: simulation_id, gravity, gui_enabled

  • list_simulations: Obtiene todos los IDs de simulaciones activas

    • Devuelve: lista de IDs de simulaciones

  • destroy_simulation: Limpia y elimina una simulación

    • Parámetros: sim_id (str)
    • Devuelve: mensaje de confirmación

  • step_simulation: Avanza la simulación uno o más pasos de tiempo

    • Parámetros: sim_id (str), steps (int, predeterminado: 1)
    • Devuelve: simulation_id, steps_taken, current_time

  • set_timestep: Configura la duración del paso de tiempo para una simulación

    • Parámetros: sim_id (str), timestep (float)
    • Devuelve: mensaje de confirmación

Operaciones con Objetos (9 herramientas)

  • add_box: Añade una forma de caja a la simulación

    • Parámetros: sim_id, dimensions (list[float]), position (list[float]), mass (float, predeterminado: 1.0), color (list[float], opcional)
    • Devuelve: object_id, shape, position

  • add_sphere: Añade una forma de esfera a la simulación

    • Parámetros: sim_id, radius (float), position (list[float]), mass (float, predeterminado: 1.0), color (list[float], opcional)
    • Devuelve: object_id, shape, position

  • add_cylinder: Añade una forma de cilindro a la simulación

    • Parámetros: sim_id, radius (float), height (float), position (list[float]), mass (float, predeterminado: 1.0), color (list[float], opcional)
    • Devuelve: object_id, shape, position

  • add_capsule: Añade una forma de cápsula a la simulación

    • Parámetros: sim_id, radius (float), height (float), position (list[float]), mass (float, predeterminado: 1.0), color (list[float], opcional)
    • Devuelve: object_id, shape, position

  • load_urdf: Carga un modelo de robot desde un archivo URDF

    • Parámetros: sim_id, file_path (str), position (list[float]), orientation (list[float], opcional)
    • Devuelve: object_id, file_path, position

  • set_object_pose: Actualiza la posición y orientación del objeto

    • Parámetros: sim_id, object_id (int), position (list[float]), orientation (list[float])
    • Devuelve: mensaje de confirmación

  • get_object_state: Consulta el estado completo del objeto

    • Parámetros: sim_id, object_id (int)
    • Devuelve: position, orientation, linear_velocity, angular_velocity

  • apply_force: Aplica un vector de fuerza a un objeto

    • Parámetros: sim_id, object_id (int), force (list[float]), position (list[float], opcional)
    • Devuelve: mensaje de confirmación

  • apply_torque: Aplica fuerza rotacional a un objeto

    • Parámetros: sim_id, object_id (int), torque (list[float])
    • Devuelve: mensaje de confirmación

  • set_object_velocity: Establece la velocidad lineal y/o angular de un objeto directamente

    • Parámetros: sim_id, object_id (int), linear_velocity (list[float], opcional), angular_velocity (list[float], opcional)
    • Devuelve: mensaje de confirmación

  • change_dynamics: Modifica las propiedades físicas del objeto en tiempo de ejecución

    • Parámetros: sim_id, object_id (int), link_index (int, predeterminado: -1), mass (float, opcional), lateral_friction (float, opcional), spinning_friction (float, opcional), rolling_friction (float, opcional), restitution (float, opcional), linear_damping (float, opcional), angular_damping (float, opcional), contact_stiffness (float, opcional), contact_damping (float, opcional)
    • Devuelve: mensaje de confirmación

  • get_dynamics_info: Consulta las propiedades dinámicas actuales de un objeto

    • Parámetros: sim_id, object_id (int), link_index (int, predeterminado: -1)
    • Devuelve: mass, lateral_friction, local_inertia_diagonal, restitution, rolling_friction, spinning_friction, contact_damping, contact_stiffness, body_type, collision_margin

Lanzamiento de Rayos (2 herramientas)

  • ray_test: Lanza un solo rayo para detectar obstáculos y medir distancias

    • Parámetros: sim_id, ray_from (list[float]), ray_to (list[float])
    • Devuelve: hit (bool), object_id, link_index, hit_fraction, hit_position, hit_normal

  • ray_test_batch: Lanza múltiples rayos eficientemente para simulación de lidar/sensores

    • Parámetros: sim_id, rays_from (list[list[float]]), rays_to (list[list[float]])
    • Devuelve: lista de resultados de impacto (mismos campos que ray_test por rayo)

Renderizado de Cámara (4 herramientas)

  • compute_view_matrix: Calcula la matriz de vista a partir de vectores de ojo/objetivo/arriba de la cámara

    • Parámetros: camera_eye_position (list[float]), camera_target_position (list[float]), camera_up_vector (list[float])
    • Devuelve: matriz de vista como lista de 16 flotantes

  • compute_view_matrix_from_yaw_pitch: Calcula la matriz de vista a partir de coordenadas esféricas (cámara orbital)

    • Parámetros: distance (float), yaw (float), pitch (float), target_position (list[float]), up_axis_index (int, predeterminado: 2)
    • Devuelve: matriz de vista como lista de 16 flotantes

  • compute_projection_matrix: Calcula la matriz de proyección a partir de parámetros de cámara

    • Parámetros: fov (float), aspect (float), near_plane (float), far_plane (float)
    • Devuelve: matriz de proyección como lista de 16 flotantes

  • get_camera_image: Renderiza imágenes RGB, de profundidad y de segmentación desde una cámara virtual

    • Parámetros: sim_id, width (int), height (int), view_matrix (list[float]), projection_matrix (list[float]), renderer (str, predeterminado: "ER_BULLET_HARDWARE_OPENGL")
    • Devuelve: width, height, rgb (PNG en base64), depth (list[float]), segmentation (list[int])

Gestión de Restricciones (2 herramientas)

  • create_constraint: Crea una articulación entre dos objetos

    • Parámetros: sim_id, parent_id (int), child_id (int), joint_type (str), joint_axis (list[float], opcional), parent_frame_position (list[float], opcional), child_frame_position (list[float], opcional)
    • Tipos de articulación: "fixed", "prismatic", "spherical"
    • Devuelve: constraint_id, joint_type
    • Nota: "revolute" NO se admite aquí — usa generate_revolute_joint + load_urdf en su lugar.

  • remove_constraint: Elimina una restricción de la simulación

    • Parámetros: sim_id, constraint_id (int)
    • Devuelve: mensaje de confirmación

Articulaciones Revolutas (Bisagra) — Solución Alternativa

La API de restricciones en tiempo de ejecución de PyBullet no admite articulaciones revolutas. La solución alternativa es un proceso de dos pasos usando estas dos herramientas:

Paso 1 — Generar un URDF con la articulación revoluta:

  • generate_revolute_joint: Genera un archivo URDF que contiene dos formas conectadas por una articulación revoluta
    • Parámetros: parent_shape (str: "box"/"sphere"/"cylinder"), child_shape (str), parent_dimensions (list[float]), child_dimensions (list[float]), parent_mass (float), child_mass (float), joint_axis (list[float]), joint_origin (list[float], opcional), joint_lower_limit (float, predeterminado: -π), joint_upper_limit (float, predeterminado: π), max_effort (float), max_velocity (float), output_path (str)
    • Devuelve: urdf_path, parent_shape, child_shape, joint_type, joint_axis, joint_limits
    • output_path debe establecerse en una ruta dentro del directorio de trabajo del servidor. Si se omite, el archivo se escribe en el directorio temporal del sistema (/tmp/), que está fuera de la ruta permitida y hará que load_urdf falle con un error de acceso denegado.

Paso 2 — Cargar el URDF generado:

  • Llame a load_urdf con el urdf_path devuelto por generate_revolute_joint
  • Luego use set_joint_motor_control para accionar la articulación

Detección de Colisiones (2 herramientas)

  • get_all_collisions: Consulta todos los puntos de contacto en la simulación

    • Parámetros: sim_id
    • Devuelve: lista de puntos de contacto con posiciones, normales, fuerzas

  • get_collisions_for_pair: Consulta puntos de contacto entre objetos específicos

    • Parámetros: sim_id, obj_a (int), obj_b (int)
    • Devuelve: lista de puntos de contacto para el par

Visualización (2 herramientas)

  • enable_debug_visualization: Habilita el renderizado de depuración de puntos de contacto y marcos

    • Parámetros: sim_id, show_contacts (bool, predeterminado: true), show_frames (bool, predeterminado: false)
    • Devuelve: mensaje de confirmación

  • set_camera: Configura la posición de la cámara y el objetivo para el modo GUI

    • Parámetros: sim_id, distance (float), yaw (float), pitch (float), target (list[float])
    • Devuelve: mensaje de confirmación

Persistencia (2 herramientas)

  • save_simulation: Guarda el estado de la simulación en un archivo JSON

    • Parámetros: sim_id, file_path (str)
    • Devuelve: confirmación con la ruta del archivo

  • load_simulation: Carga el estado de la simulación desde un archivo JSON

    • Parámetros: file_path (str), gui (bool, predeterminado: false)
    • Devuelve: nuevo simulation_id, file_path

Control de Robots (5 herramientas)

  • get_num_joints: Consulta el número de articulaciones en un modelo URDF

    • Parámetros: sim_id (str), object_id (int)
    • Devuelve: número de articulaciones (int)

  • get_joint_info: Obtiene propiedades detalladas de la articulación

    • Parámetros: sim_id (str), object_id (int), joint_index (int)
    • Devuelve: joint_name, joint_type, lower_limit, upper_limit, max_force, max_velocity, joint_axis

  • get_joint_state: Obtiene el estado actual de la articulación

    • Parámetros: sim_id (str), object_id (int), joint_index (int)
    • Devuelve: joint_position, joint_velocity, reaction_forces, motor_torque

  • set_joint_motor_control: Controla las articulaciones del robot

    • Parámetros: sim_id (str), object_id (int), joint_index (int), control_mode (str), target_position (float, opcional), target_velocity (float, opcional), force (float, opcional), position_gain (float, opcional), velocity_gain (float, opcional)
    • Modos de control: "POSITION_CONTROL", "VELOCITY_CONTROL", "TORQUE_CONTROL"
    • Devuelve: mensaje de confirmación

  • calculate_inverse_kinematics: Calcula los ángulos de articulación para la pose objetivo del efector final

    • Parámetros: sim_id (str), object_id (int), end_effector_link_index (int), target_position (list[float]), target_orientation (list[float], opcional), lower_limits (list[float], opcional), upper_limits (list[float], opcional), joint_ranges (list[float], opcional), rest_poses (list[float], opcional)
    • Devuelve: lista de posiciones de articulación

Flujos de Trabajo de Ejemplo

Caja Cayendo Básica

Cree una simulación simple con una caja cayendo bajo gravedad:

# Through MCP client (natural language):
"Create a simulation with Earth gravity"
"Add a box at position (0, 0, 5) with dimensions 1x1x1"
"Step the simulation 200 times"
"What is the position of object 0?"

Objetos Apilados

Cree una pila de objetos:

"Create a simulation"
"Add a box at (0, 0, 0.5) with dimensions 10x10x1 and mass 1000"  # Ground
"Add a box at (0, 0, 1.5) with dimensions 1x1x1"
"Add a sphere at (0, 0, 3) with radius 0.5"
"Step the simulation 300 times"
"Get all collisions"

Objetos Restringidos

Cree objetos conectados por una articulación:

"Create a simulation"
"Add a box at (0, 0, 2) with dimensions 1x1x1"  # Object 0
"Add a sphere at (2, 0, 2) with radius 0.5"     # Object 1
"Create a fixed constraint between object 0 and object 1"
"Apply a torque of [0, 0, 10] to object 1"
"Step the simulation 200 times"

Guardar y Cargar

Persista una simulación:

"Create a simulation"
"Add a box at (0, 0, 1)"
"Add a sphere at (1, 0, 1)"
"Step the simulation 50 times"
"Save the simulation to my_sim.json"

# Later...
"Load the simulation from my_sim.json"
"Step the simulation 50 more times"

Simulación de Robot

Cargue y controle un modelo de robot URDF:

"Create a simulation with GUI enabled"
"Load URDF from /path/to/robot.urdf at position (0, 0, 1)"
"How many joints does object 0 have?"
"Get information about joint 0 of object 0"
"Get the current state of joint 0"
"Set joint 0 to position 1.57 with position control and force 100"
"Step the simulation 100 times"
"Get the state of joint 0 again to see it moved"
"Calculate inverse kinematics for object 0 end-effector link 6 at position [0.5, 0, 0.5]"

Características de Control de Robot:

  • Consultar número de articulaciones y propiedades de articulación (tipo, límites, eje)
  • Leer estados de articulación (posición, velocidad, fuerzas, torque)
  • Controlar articulaciones con tres modos:
    • Control de posición: Mover la articulación al ángulo/posición objetivo
    • Control de velocidad: Girar la articulación a la velocidad objetivo
    • Control de torque: Aplicar torque directo a la articulación
  • Calcular cinemática inversa para el posicionamiento del efector final

Formato de Archivo de Persistencia

Los estados de simulación se guardan como archivos JSON con la siguiente estructura:

{
  "gravity": [0.0, 0.0, -9.81],
  "timestep": 0.01,
  "objects": [
    {
      "object_id": 0,
      "type": "primitive",
      "shape": "box",
      "dimensions": [0.5, 0.5, 0.5],
      "position": [0.0, 0.0, 1.0],
      "orientation": [0.0, 0.0, 0.0, 1.0],
      "linear_velocity": [0.0, 0.0, -0.98],
      "angular_velocity": [0.0, 0.0, 0.0],
      "mass": 1.0,
      "color": [1.0, 0.0, 0.0, 1.0]
    },
    {
      "object_id": 1,
      "type": "urdf",
      "urdf_path": "/path/to/model.urdf",
      "position": [2.0, 0.0, 0.5],
      "orientation": [0.0, 0.0, 0.0, 1.0],
      "linear_velocity": [0.0, 0.0, 0.0],
      "angular_velocity": [0.0, 0.0, 0.0]
    }
  ],
  "constraints": [
    {
      "constraint_id": 0,
      "parent_id": 0,
      "child_id": 1,
      "joint_type": "fixed"
    }
  ]
}

Notas de Compatibilidad

  • IDs de Objetos: Los IDs de objetos se reasignan al cargar (pueden diferir de los IDs guardados)
  • Archivos URDF: Las rutas de archivos URDF deben ser válidas al cargar. Use rutas absolutas para mayor confiabilidad
  • ID de Simulación: Se genera un nuevo ID de simulación al cargar
  • Versión de Formato: El formato actual es compatible con PyBullet 3.2.5+
  • Restricciones: Las restricciones se serializan y restauran completamente

Problemas Comunes y Soluciones

Errores de Coordenadas

Problema: "force needs a 3 coordinates [x,y,z]" o errores similares

Solución: Siempre proporcione vectores 3D completos:

# Wrong
gravity = [-9.81]
position = [1, 2]
force = [10]

# Correct
gravity = [0, 0, -9.81]
position = [1, 2, 0]
force = [10, 0, 0]

Error de Validación de Masa

Problema: "Mass must be positive, got 0.0"

Solución: PyBullet requiere masa positiva. Para objetos estáticos, use masa grande:

# Wrong
add_box(mass=0)  # Error!

# Correct
add_box(mass=1000)  # Heavy static object

La Ventana GUI No Aparece

Problema: La ventana GUI no se muestra cuando gui=true

Solución:

  • Solo se permite una simulación GUI por instancia de servidor
  • Destruya la simulación GUI existente antes de crear una nueva
  • Algunos entornos (Docker, SSH sin X11) no admiten GUI
  • En Linux, asegúrese de que X11 esté disponible: echo $DISPLAY

La Carga de URDF Falla

Problema: "Failed to load URDF: File not found"

Solución:

  • Use rutas absolutas: /full/path/to/robot.urdf
  • O use rutas relativas al directorio de trabajo del servidor
  • Verifique que el archivo exista: ls -la /path/to/robot.urdf
  • Compruebe que los archivos de malla referenciados en el URDF también sean accesibles

Los Objetos Caen a Través del Suelo

Problema: Los objetos atraviesan el plano del suelo

Solución:

  • Asegúrese de estar avanzando la simulación: step_simulation(steps=100)
  • Use un paso de tiempo apropiado (el predeterminado 0.01 suele ser bueno)
  • Dé al plano del suelo dimensiones grandes y masa alta (por ejemplo, 1000)
  • Verifique que los objetos tengan masa positiva

Solución de Problemas

Problemas Comunes

1. Errores de importación al iniciar el servidor

ModuleNotFoundError: No module named 'mcp' or 'pybullet'

Solución: Asegúrese de que su entorno virtual esté activado y las dependencias estén instaladas:

source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install fastmcp pybullet

2. Errores de versión de Python

SyntaxError or version compatibility issues

Solución: Verifique la versión de Python (debe ser 3.9+):

python --version

Si es necesario, cree un venv con una versión específica de Python:

python3.9 -m venv venv

3. GUI de PyBullet no se muestra

GUI window doesn't appear when gui=true

Solución:

  • El modo GUI debe estar habilitado explícitamente: create_simulation(gui=true)
  • Algunos sistemas (servidores, Docker) no admiten el modo GUI: use el modo headless en su lugar
  • En Linux, asegúrese de que X11 esté disponible: echo $DISPLAY

4. Errores de permisos de archivo

PermissionError when saving/loading simulations

Solución:

  • Asegúrese de tener permisos de escritura en el directorio de destino
  • Use rutas absolutas: /full/path/to/simulation.json
  • Verifique el espacio en disco: df -h

5. El cliente MCP no puede conectarse al servidor

Server not responding

Solución:

  • Verifique que el servidor esté ejecutándose: python -m src.server
  • Compruebe que la URL en su configuración MCP coincida con el puerto del servidor (predeterminado: http://localhost:8000/mcp)
  • Reinicie su cliente MCP después de cambios de configuración
  • Revise la salida del terminal del servidor para ver mensajes de error

6. La simulación se comporta inesperadamente

Objects fall through the ground or constraints don't work

Solución:

  • Asegúrese de estar avanzando la simulación: step_simulation(sim_id, steps=100)
  • Verifique el valor del paso de tiempo (el predeterminado 0.01 suele ser bueno)
  • Verifique que las masas de los objetos sean positivas
  • Para planos de suelo, use una caja con dimensiones grandes y masa=1000

7. La carga de URDF falla

ToolError: Failed to load URDF

Solución:

  • Verifique que la ruta del archivo URDF sea correcta y accesible
  • Use rutas absolutas para archivos URDF
  • Compruebe que los archivos de malla referenciados en el URDF también sean accesibles
  • Valide la sintaxis del URDF directamente con PyBullet

Modo de Depuración

Para ver mensajes de error detallados, revise la salida del servidor en su terminal. El servidor registra todas las operaciones y errores.

Obtener Ayuda

Si encuentra problemas no cubiertos aquí:

  1. Revise los registros del servidor para ver mensajes de error detallados
  2. Verifique la configuración de su cliente MCP
  3. Pruebe el servidor directamente con Python para aislar problemas de MCP vs. PyBullet
  4. Revise la documentación de PyBullet para preguntas específicas de física

Arquitectura

El servidor sigue una arquitectura en capas:

MCP Client (Claude Desktop)
         ↓
   MCP Protocol
         ↓
FastMCP Server (37 tools)
         ↓
Manager Classes (helpers)
         ↓
PyBullet Physics Engine

Componentes Clave:

  • Servidor FastMCP (src/server.py): Expone 37 herramientas MCP usando decoradores @mcp.tool
  • SimulationManager: Gestiona clientes de física PyBullet y el ciclo de vida de la simulación
  • ObjectManager: Maneja la creación, manipulación y consulta de estado de objetos
  • ConstraintManager: Crea y gestiona articulaciones entre objetos
  • PersistenceHandler: Serializa/deserializa el estado de la simulación a JSON
  • CollisionQueryHandler: Consulta puntos de contacto e información de colisiones

Cada herramienta MCP valida entradas, llama al gestor apropiado y devuelve objetos Python (dict/list/str/int) directamente: FastMCP maneja la conversión del protocolo MCP automáticamente.

Contribuciones

¡Las contribuciones son bienvenidas! Por favor, asegúrese de:

  • Todas las pruebas pasen: pytest
  • El código esté formateado: black src tests
  • El código pase el linting: ruff check src tests
  • Los type hints sean correctos: mypy src
  • Las nuevas características incluyan pruebas (unitarias + basadas en propiedades)
  • La documentación esté actualizada

Agradecimientos

  • Construido con FastMCP por Jeremiah Lowin
  • Simulación de física impulsada por PyBullet
  • Pruebas basadas en propiedades con Hypothesis

Soporte

Para problemas, preguntas o contribuciones:

  • Revise este README y la sección de solución de problemas
  • Revise la documentación de PyBullet para preguntas específicas de física