Robotics MCP Server

Instructions

Implementation Reference

• src/robotics_mcp/tools/robot_model_tools.py:46-204 (handler)

  Core handler function 'robot_model' implementing the tool logic as a portmanteau for create, import, export, convert, and SPZ operations on robot 3D models. Dispatches to private helper methods based on 'operation' parameter.
  @self.mcp.tool() async def robot_model( operation: Literal["create", "import", "export", "convert", "spz_check", "spz_convert", "spz_extract", "spz_install"], robot_type: Optional[str] = None, model_path: Optional[str] = None, output_path: Optional[str] = None, format: Literal["fbx", "glb", "obj", "vrm", "blend"] = "fbx", platform: Literal["unity", "vrchat", "resonite"] = "unity", dimensions: Optional[Dict[str, float]] = None, create_textures: bool = True, texture_style: Literal["realistic", "stylized", "simple"] = "realistic", robot_id: Optional[str] = None, include_animations: bool = True, project_path: Optional[str] = None, create_prefab: bool = True, source_path: Optional[str] = None, source_format: Optional[Literal["fbx", "glb", "obj", "blend", "vrm"]] = None, target_format: Optional[Literal["fbx", "glb", "obj", "vrm"]] = None, target_path: Optional[str] = None, spz_path: Optional[str] = None, output_format: Optional[str] = None, unity_project_path: Optional[str] = None, ) -> Dict[str, Any]: """Robot model management portmanteau for Robotics MCP. PORTMANTEAU PATTERN RATIONALE: Instead of creating 4 separate tools (create, import, export, convert), this tool consolidates related model operations into a single interface. This design: - Prevents tool explosion (4 tools → 1 tool) while maintaining full functionality - Improves discoverability by grouping related operations together - Reduces cognitive load when working with robot models - Enables consistent model interface across all operations - Follows FastMCP 2.13+ best practices for feature-rich MCP servers SUPPORTED OPERATIONS: - create: Create robot 3D model from scratch using Blender MCP - import: Import robot 3D model into Unity/VRChat/Resonite project - export: Export robot model from Unity to file format - convert: Convert robot model between formats - spz_check: Check .spz conversion tool availability - spz_convert: Convert .spz file to .ply or other format - spz_extract: Extract metadata from .spz file - spz_install: Install Unity Gaussian Splatting plugin (alternative to .spz) Args: operation: The model operation to perform. MUST be one of: - "create": Create model (requires: robot_type, output_path) - "import": Import model (requires: robot_type, model_path) - "export": Export model (requires: robot_id) - "convert": Convert model (requires: source_path, source_format, target_format) robot_type: Type of robot (required for create/import). Examples: "scout", "go2", "g1", "robbie", "custom" model_path: Path to model file (required for import). output_path: Path for output file (required for create, optional for export/convert). format: Model format (used by create/import/export). - "fbx": Industry standard (recommended for robots) - "glb": Modern glTF 2.0 format - "obj": Simple mesh format - "vrm": VRM format (ONLY for humanoid robots) platform: Target platform for import (unity/vrchat/resonite). dimensions: Custom dimensions for create (length, width, height in meters). create_textures: Create textures using gimp-mcp (for create). texture_style: Texture style for create (realistic/stylized/simple). robot_id: Virtual robot identifier (required for export). include_animations: Include animations in export. project_path: Unity project path (for import). create_prefab: Create Unity prefab after import. source_path: Source file path (required for convert). source_format: Source file format (required for convert). target_format: Target file format (required for convert). target_path: Output file path (optional for convert). Returns: Dictionary containing operation-specific results. Examples: Create Scout model: result = await robot_model( operation="create", robot_type="scout", output_path="D:/Models/scout_model.fbx", format="fbx" ) Import model to Unity: result = await robot_model( operation="import", robot_type="scout", model_path="D:/Models/scout_model.fbx", platform="unity" ) Export robot from Unity: result = await robot_model( operation="export", robot_id="vbot_scout_01", format="fbx" ) Convert FBX to GLB: result = await robot_model( operation="convert", source_path="D:/Models/scout.fbx", source_format="fbx", target_format="glb" ) """ try: if operation == "create": if not robot_type or not output_path: return format_error_response( "robot_type and output_path are required for 'create' operation", error_type="validation_error", ) return await self._handle_create( robot_type, output_path, format, dimensions, create_textures, texture_style ) elif operation == "import": if not robot_type or not model_path: return format_error_response( "robot_type and model_path are required for 'import' operation", error_type="validation_error", ) return await self._handle_import(robot_type, model_path, format, platform, project_path, create_prefab) elif operation == "export": if not robot_id: return format_error_response( "robot_id is required for 'export' operation", error_type="validation_error", ) return await self._handle_export(robot_id, format, output_path, include_animations) elif operation == "convert": if not source_path or not source_format or not target_format: return format_error_response( "source_path, source_format, and target_format are required for 'convert' operation", error_type="validation_error", ) return await self._handle_convert(source_path, source_format, target_format, target_path, robot_type) elif operation == "spz_check": return await self._handle_spz_check() elif operation == "spz_convert": if not spz_path: return format_error_response("spz_path required for spz_convert", error_type="validation_error") return await self._handle_spz_convert(spz_path, target_path, output_format) elif operation == "spz_extract": if not spz_path: return format_error_response("spz_path required for spz_extract", error_type="validation_error") return await self._handle_spz_extract(spz_path) elif operation == "spz_install": if not unity_project_path: return format_error_response("unity_project_path required for spz_install", error_type="validation_error") return await self._handle_spz_install(unity_project_path) else: return format_error_response(f"Unknown operation: {operation}", error_type="validation_error") except Exception as e: return handle_tool_error("robot_model", e, operation=operation)
• src/robotics_mcp/server.py:487-488 (registration)

  Registers the RobotModelTools instance, which adds the 'robot_model' tool to the FastMCP server.
  self.robot_model_tools.register() # Model: create, import, export, convert, spz operations logger.debug("Registered robot_model_tools tool")
• src/robotics_mcp/tools/robot_model_tools.py:47-68 (schema)

  Input schema defined by function parameters with Literal types for operations, formats, platforms, etc., providing validation and autocomplete.
  async def robot_model( operation: Literal["create", "import", "export", "convert", "spz_check", "spz_convert", "spz_extract", "spz_install"], robot_type: Optional[str] = None, model_path: Optional[str] = None, output_path: Optional[str] = None, format: Literal["fbx", "glb", "obj", "vrm", "blend"] = "fbx", platform: Literal["unity", "vrchat", "resonite"] = "unity", dimensions: Optional[Dict[str, float]] = None, create_textures: bool = True, texture_style: Literal["realistic", "stylized", "simple"] = "realistic", robot_id: Optional[str] = None, include_animations: bool = True, project_path: Optional[str] = None, create_prefab: bool = True, source_path: Optional[str] = None, source_format: Optional[Literal["fbx", "glb", "obj", "blend", "vrm"]] = None, target_format: Optional[Literal["fbx", "glb", "obj", "vrm"]] = None, target_path: Optional[str] = None, spz_path: Optional[str] = None, output_format: Optional[str] = None, unity_project_path: Optional[str] = None, ) -> Dict[str, Any]:
• src/robotics_mcp/tools/robot_model_tools.py:43-45 (registration)

  The register() method defines and registers the 'robot_model' tool using @self.mcp.tool() decorator.
  def register(self): """Register robot model portmanteau tool with MCP server."""
• src/robotics_mcp/tools/robot_model_tools.py:205-231 (helper)

  Example helper: _handle_create implements the 'create' operation logic, validating inputs and calling Blender MCP for model generation.
  async def _handle_create( self, robot_type: str, output_path: str, format: str, dimensions: Optional[Dict[str, float]], create_textures: bool, texture_style: str, ) -> Dict[str, Any]: """Handle create operation.""" try: if "blender" not in self.mounted_servers: return format_error_response( "blender-mcp not available - required for model creation", error_type="not_available", details={"mounted_servers": list(self.mounted_servers.keys())}, ) if not dimensions: dimensions = self._get_default_dimensions(robot_type) return await self._create_model_via_blender( robot_type, output_path, format, dimensions, create_textures, texture_style ) except Exception as e: return handle_tool_error("robot_model", e, operation="create")