Robotics MCP Server

Instructions

# Camera
result = await robot_behavior(
    robot_id="scout_01",
    category="camera",
    action="capture_image",
    output_path="C:/Images/capture.jpg"
)

# Navigation
result = await robot_behavior(
    robot_id="scout_01",
    category="navigation",
    action="plan_path",
    start_position={"x": 0, "y": 0, "z": 0},
    goal_position={"x": 5, "y": 0, "z": 0}
)

# Manipulation - Move arm
result = await robot_behavior(
    robot_id="g1_01",
    category="manipulation",
    action="move_arm",
    joint_positions={"shoulder": 45.0, "elbow": 90.0, "wrist": 0.0}
)

# Manipulation - Open gripper
result = await robot_behavior(
    robot_id="g1_01",
    category="manipulation",
    action="open_gripper"
)

Implementation Reference

• src/robotics_mcp/tools/robot_behavior.py:34-224 (handler)

  Main handler function for the 'robot_behavior' MCP tool. This portmanteau function handles animation, camera, navigation, and manipulation behaviors by routing to specialized sub-handlers based on the 'category' parameter. Includes full input schema via type hints and comprehensive docstring with examples.

  @self.mcp.tool()
  async def robot_behavior(
      robot_id: str,
      category: Literal["animation", "camera", "navigation", "manipulation"],
      action: str,
      # Animation parameters
      wheel_speeds: Optional[Dict[str, float]] = None,
      animation_name: Optional[str] = None,
      pose: Optional[str] = None,
      animation_speed: Optional[float] = None,
      loop: bool = False,
      # Camera parameters
      angle_x: Optional[float] = None,
      angle_y: Optional[float] = None,
      output_path: Optional[str] = None,
      stream_url: Optional[str] = None,
      # Navigation parameters
      start_position: Optional[Dict[str, float]] = None,
      goal_position: Optional[Dict[str, float]] = None,
      waypoint: Optional[Dict[str, float]] = None,
      obstacle_position: Optional[Dict[str, float]] = None,
      path_id: Optional[str] = None,
      # Manipulation parameters
      joint_positions: Optional[Dict[str, float]] = None,
      end_effector_pose: Optional[Dict[str, Any]] = None,
      gripper_position: Optional[float] = None,
      arm_id: Optional[str] = None,
      force_limit: Optional[float] = None,
      manipulation_speed: Optional[float] = None,
  ) -> Dict[str, Any]:
      """Robot behavior control portmanteau - Animation, camera, navigation, and manipulation.
  
      PORTMANTEAU PATTERN: Consolidates animation, camera, navigation, and manipulation operations
      into a single unified tool. This reduces tool explosion while maintaining
      full functionality across all behavior categories.
  
      CATEGORIES:
      - animation: Animation and pose control
      - camera: Camera feed and visual control
      - navigation: Path planning and navigation
      - manipulation: Arm and gripper control
  
      ANIMATION ACTIONS:
      - animate_wheels: Rotate wheels during movement (Scout mecanum wheels)
      - animate_movement: Play movement animations (walk, turn, etc.)
      - set_pose: Set robot pose (sitting, standing, etc. for Unitree)
      - play_animation: Play custom animations
      - stop_animation: Stop current animation
      - get_animation_state: Get current animation state
  
      CAMERA ACTIONS:
      - get_camera_feed: Get live camera feed (physical Scout camera)
      - get_virtual_camera: Get Unity camera view from robot perspective
      - set_camera_angle: Adjust camera angle
      - capture_image: Capture still image
      - start_streaming: Start video stream
      - stop_streaming: Stop video stream
      - get_camera_status: Get camera status and settings
  
      NAVIGATION ACTIONS:
      - plan_path: Plan path from A to B (A* or RRT)
      - follow_path: Execute planned path
      - set_waypoint: Set navigation waypoint
      - clear_waypoints: Clear waypoint list
      - get_path_status: Check path execution status
      - avoid_obstacle: Dynamic obstacle avoidance
      - get_current_path: Get current path being followed
  
      MANIPULATION ACTIONS:
      - move_arm: Move arm to target joint positions or end-effector pose
      - set_joint_positions: Set individual joint positions (dict of joint_name: angle)
      - set_end_effector_pose: Move end-effector to target pose (position + orientation)
      - get_arm_state: Get current arm joint positions and end-effector pose
      - open_gripper: Open gripper fully
      - close_gripper: Close gripper fully
      - set_gripper_position: Set gripper position (0.0 = open, 1.0 = closed)
      - get_gripper_state: Get current gripper position and force feedback
      - move_to_pose: Move arm to target pose with IK (inverse kinematics)
      - home_arm: Return arm to home/rest position
  
      Args:
          robot_id: Robot identifier (e.g., "scout_01", "vbot_scout_01").
          category: Behavior category: "animation", "camera", or "navigation".
          action: Action to perform (see category-specific actions above).
          # Animation parameters (used when category="animation")
          wheel_speeds: Wheel speeds for animate_wheels.
          animation_name: Animation name for play_animation.
          pose: Pose name for set_pose.
          animation_speed: Animation speed multiplier.
          loop: Whether to loop animation.
          # Camera parameters (used when category="camera")
          angle_x: Camera angle X (pitch) in degrees.
          angle_y: Camera angle Y (yaw) in degrees.
          output_path: Output file path for capture_image.
          stream_url: Stream URL for start_streaming.
          # Navigation parameters (used when category="navigation")
          start_position: Start position (x, y, z) for plan_path.
          goal_position: Goal position (x, y, z) for plan_path.
          waypoint: Waypoint position (x, y, z) for set_waypoint.
          obstacle_position: Obstacle position (x, y, z) for avoid_obstacle.
          path_id: Path identifier for follow_path or get_path_status.
          # Manipulation parameters (used when category="manipulation")
          joint_positions: Joint positions dict (e.g., {"shoulder": 45.0, "elbow": 90.0}).
          end_effector_pose: End-effector pose dict with position and orientation.
          gripper_position: Gripper position (0.0 = open, 1.0 = closed).
          arm_id: Arm identifier for multi-arm robots (e.g., "left", "right").
          force_limit: Maximum force/torque limit for movement.
          manipulation_speed: Movement speed (0.0-1.0) for arm/gripper motion.
  
      Returns:
          Dictionary containing operation result.
  
      Examples:
          # Animation
          result = await robot_behavior(
              robot_id="scout_01",
              category="animation",
              action="play_animation",
              animation_name="walk",
              animation_speed=1.0,
              loop=True
          )
  
          # Camera
          result = await robot_behavior(
              robot_id="scout_01",
              category="camera",
              action="capture_image",
              output_path="C:/Images/capture.jpg"
          )
  
          # Navigation
          result = await robot_behavior(
              robot_id="scout_01",
              category="navigation",
              action="plan_path",
              start_position={"x": 0, "y": 0, "z": 0},
              goal_position={"x": 5, "y": 0, "z": 0}
          )
  
          # Manipulation - Move arm
          result = await robot_behavior(
              robot_id="g1_01",
              category="manipulation",
              action="move_arm",
              joint_positions={"shoulder": 45.0, "elbow": 90.0, "wrist": 0.0}
          )
  
          # Manipulation - Open gripper
          result = await robot_behavior(
              robot_id="g1_01",
              category="manipulation",
              action="open_gripper"
          )
      """
      try:
          robot = self.state_manager.get_robot(robot_id)
          if not robot:
              return format_error_response(
                  f"Robot {robot_id} not found",
                  error_type="not_found",
                  robot_id=robot_id,
                  category=category,
                  action=action,
              )
  
          # Route to category handler
          if category == "animation":
              return await self._handle_animation(
                  robot, action, wheel_speeds, animation_name, pose, speed, loop
              )
          elif category == "camera":
              return await self._handle_camera(robot, action, angle_x, angle_y, output_path, stream_url)
          elif category == "navigation":
              return await self._handle_navigation(
                  robot, action, start_position, goal_position, waypoint, obstacle_position, path_id
              )
          elif category == "manipulation":
              return await self._handle_manipulation(
                  robot, action, joint_positions, end_effector_pose, gripper_position, arm_id, force_limit, manipulation_speed
              )
          else:
              return format_error_response(
                  f"Unknown category: {category}",
                  error_type="validation_error",
                  valid_categories=["animation", "camera", "navigation", "manipulation"],
              )
  
      except Exception as e:
          return handle_tool_error("robot_behavior", e, robot_id=robot_id, category=category, action=action)

• src/robotics_mcp/server.py:477-478 (registration)

  Registration of the RobotBehaviorTool instance to the MCP server. Called within the _register_tools method of RoboticsMCP class.

  self.robot_behavior.register()  # Behavior: animation, camera, navigation, manipulation
  logger.debug("Registered robot_behavior tool")

• src/robotics_mcp/server.py:185-185 (registration)

  Instantiation of the RobotBehaviorTool class instance in the RoboticsMCP server __init__ method.

  self.robot_behavior = RobotBehaviorTool(self.mcp, self.state_manager, self.mounted_servers)

• src/robotics_mcp/tools/robot_behavior.py:64-188 (schema)

  Detailed input/output schema and usage documentation for the robot_behavior tool, including all supported categories, actions, parameters, and examples.

  """Robot behavior control portmanteau - Animation, camera, navigation, and manipulation.
  
  PORTMANTEAU PATTERN: Consolidates animation, camera, navigation, and manipulation operations
  into a single unified tool. This reduces tool explosion while maintaining
  full functionality across all behavior categories.
  
  CATEGORIES:
  - animation: Animation and pose control
  - camera: Camera feed and visual control
  - navigation: Path planning and navigation
  - manipulation: Arm and gripper control
  
  ANIMATION ACTIONS:
  - animate_wheels: Rotate wheels during movement (Scout mecanum wheels)
  - animate_movement: Play movement animations (walk, turn, etc.)
  - set_pose: Set robot pose (sitting, standing, etc. for Unitree)
  - play_animation: Play custom animations
  - stop_animation: Stop current animation
  - get_animation_state: Get current animation state
  
  CAMERA ACTIONS:
  - get_camera_feed: Get live camera feed (physical Scout camera)
  - get_virtual_camera: Get Unity camera view from robot perspective
  - set_camera_angle: Adjust camera angle
  - capture_image: Capture still image
  - start_streaming: Start video stream
  - stop_streaming: Stop video stream
  - get_camera_status: Get camera status and settings
  
  NAVIGATION ACTIONS:
  - plan_path: Plan path from A to B (A* or RRT)
  - follow_path: Execute planned path
  - set_waypoint: Set navigation waypoint
  - clear_waypoints: Clear waypoint list
  - get_path_status: Check path execution status
  - avoid_obstacle: Dynamic obstacle avoidance
  - get_current_path: Get current path being followed
  
  MANIPULATION ACTIONS:
  - move_arm: Move arm to target joint positions or end-effector pose
  - set_joint_positions: Set individual joint positions (dict of joint_name: angle)
  - set_end_effector_pose: Move end-effector to target pose (position + orientation)
  - get_arm_state: Get current arm joint positions and end-effector pose
  - open_gripper: Open gripper fully
  - close_gripper: Close gripper fully
  - set_gripper_position: Set gripper position (0.0 = open, 1.0 = closed)
  - get_gripper_state: Get current gripper position and force feedback
  - move_to_pose: Move arm to target pose with IK (inverse kinematics)
  - home_arm: Return arm to home/rest position
  
  Args:
      robot_id: Robot identifier (e.g., "scout_01", "vbot_scout_01").
      category: Behavior category: "animation", "camera", or "navigation".
      action: Action to perform (see category-specific actions above).
      # Animation parameters (used when category="animation")
      wheel_speeds: Wheel speeds for animate_wheels.
      animation_name: Animation name for play_animation.
      pose: Pose name for set_pose.
      animation_speed: Animation speed multiplier.
      loop: Whether to loop animation.
      # Camera parameters (used when category="camera")
      angle_x: Camera angle X (pitch) in degrees.
      angle_y: Camera angle Y (yaw) in degrees.
      output_path: Output file path for capture_image.
      stream_url: Stream URL for start_streaming.
      # Navigation parameters (used when category="navigation")
      start_position: Start position (x, y, z) for plan_path.
      goal_position: Goal position (x, y, z) for plan_path.
      waypoint: Waypoint position (x, y, z) for set_waypoint.
      obstacle_position: Obstacle position (x, y, z) for avoid_obstacle.
      path_id: Path identifier for follow_path or get_path_status.
      # Manipulation parameters (used when category="manipulation")
      joint_positions: Joint positions dict (e.g., {"shoulder": 45.0, "elbow": 90.0}).
      end_effector_pose: End-effector pose dict with position and orientation.
      gripper_position: Gripper position (0.0 = open, 1.0 = closed).
      arm_id: Arm identifier for multi-arm robots (e.g., "left", "right").
      force_limit: Maximum force/torque limit for movement.
      manipulation_speed: Movement speed (0.0-1.0) for arm/gripper motion.
  
  Returns:
      Dictionary containing operation result.
  
  Examples:
      # Animation
      result = await robot_behavior(
          robot_id="scout_01",
          category="animation",
          action="play_animation",
          animation_name="walk",
          animation_speed=1.0,
          loop=True
      )
  
      # Camera
      result = await robot_behavior(
          robot_id="scout_01",
          category="camera",
          action="capture_image",
          output_path="C:/Images/capture.jpg"
      )
  
      # Navigation
      result = await robot_behavior(
          robot_id="scout_01",
          category="navigation",
          action="plan_path",
          start_position={"x": 0, "y": 0, "z": 0},
          goal_position={"x": 5, "y": 0, "z": 0}
      )
  
      # Manipulation - Move arm
      result = await robot_behavior(
          robot_id="g1_01",
          category="manipulation",
          action="move_arm",
          joint_positions={"shoulder": 45.0, "elbow": 90.0, "wrist": 0.0}
      )
  
      # Manipulation - Open gripper
      result = await robot_behavior(
          robot_id="g1_01",
          category="manipulation",
          action="open_gripper"
      )
  """

• src/robotics_mcp/tools/robot_behavior.py:298-354 (helper)

  Helper function for handling virtual animation behaviors, dispatching to Unity RobotAnimator methods via mounted server tool calls.

  async def _handle_virtual_animation(
      self,
      robot: Any,
      action: str,
      wheel_speeds: Optional[Dict[str, float]],
      animation_name: Optional[str],
      pose: Optional[str],
      animation_speed: Optional[float],
      loop: bool,
  ) -> Dict[str, Any]:
      """Handle virtual robot animation."""
      try:
          if robot.platform == "unity" and "unity" in self.mounted_servers:
              method_map = {
                  "animate_wheels": ("RobotAnimator", "AnimateWheels", {"robotId": robot.robot_id, "wheelSpeeds": wheel_speeds or {}}),
                  "animate_movement": ("RobotAnimator", "AnimateMovement", {"robotId": robot.robot_id, "animationName": animation_name or "walk", "speed": animation_speed or 1.0, "loop": loop}),
                  "set_pose": ("RobotAnimator", "SetPose", {"robotId": robot.robot_id, "pose": pose or "idle"}),
                  "play_animation": ("RobotAnimator", "PlayAnimation", {"robotId": robot.robot_id, "animationName": animation_name or "idle", "speed": animation_speed or 1.0, "loop": loop}),
                  "stop_animation": ("RobotAnimator", "StopAnimation", {"robotId": robot.robot_id}),
                  "get_animation_state": ("RobotAnimator", "GetAnimationState", {"robotId": robot.robot_id}),
              }
  
              if action not in method_map:
                  return format_error_response(f"Unknown animation action: {action}", error_type="validation_error")
  
              class_name, method_name, params = method_map[action]
              result = await call_mounted_server_tool(
                  self.mounted_servers,
                  "unity",
                  "execute_unity_method",
                  {
                      "class_name": class_name,
                      "method_name": method_name,
                      "parameters": params,
                  },
              )
  
              return format_success_response(
                  f"Animation {action} executed for {robot.robot_id}",
                  robot_id=robot.robot_id,
                  category="animation",
                  action=action,
                  data=result,
              )
          else:
              logger.info("Mock animation", robot_id=robot.robot_id, action=action)
              return format_success_response(
                  f"Mock animation: {action} for {robot.robot_id}",
                  robot_id=robot.robot_id,
                  category="animation",
                  action=action,
                  data={"note": "Mock mode - Unity/VRChat not available"},
              )
  
      except Exception as e:
          return handle_tool_error("_handle_virtual_animation", e, robot_id=robot.robot_id, action=action)