Robotics MCP Server

Instructions

Implementation Reference

• src/robotics_mcp/tools/robotics_system.py:37-111 (handler)

  Core handler function for the 'robotics_system' tool. Dispatches to specific handlers based on 'operation' parameter (help, status, list_robots). Includes input schema via type hints and comprehensive docstring.
  @self.mcp.tool() async def robotics_system( operation: Literal["help", "status", "list_robots"], robot_type: Optional[str] = None, is_virtual: Optional[bool] = None, ) -> Dict[str, Any]: """System management portmanteau for Robotics MCP. PORTMANTEAU PATTERN RATIONALE: Instead of creating 3 separate tools (help, status, list_robots), this tool consolidates related system operations into a single interface. This design: - Prevents tool explosion (3 tools → 1 tool) while maintaining full functionality - Improves discoverability by grouping related operations together - Reduces cognitive load when working with system management tasks - Enables consistent system interface across all operations - Follows FastMCP 2.13+ best practices for feature-rich MCP servers SUPPORTED OPERATIONS: - help: Get comprehensive help information about the server and its tools - status: Get server status with connectivity tests and robot counts - list_robots: List all registered robots with optional filtering Args: operation: The system operation to perform. MUST be one of: - "help": Get help information (no additional parameters) - "status": Get server status (no additional parameters) - "list_robots": List robots (optional: robot_type, is_virtual filters) robot_type: Optional filter for list_robots operation. Valid values: "scout", "go2", "g1", or any custom robot type. If None, returns all robot types. is_virtual: Optional filter for list_robots operation. - True: Only virtual robots (vbots) - False: Only physical robots (bots) - None: Both virtual and physical robots Returns: Dictionary containing operation-specific results: - help: Server info, tool list, features, mounted servers - status: Server health, robot counts, connectivity tests, HTTP status - list_robots: Robot list with filtering applied Examples: Get help information: result = await robotics_system(operation="help") Get server status: result = await robotics_system(operation="status") List all robots: result = await robotics_system(operation="list_robots") List only Scout robots: result = await robotics_system(operation="list_robots", robot_type="scout") List only virtual robots: result = await robotics_system(operation="list_robots", is_virtual=True) """ try: if operation == "help": return await self._handle_help() elif operation == "status": return await self._handle_status() elif operation == "list_robots": return await self._handle_list_robots(robot_type, is_virtual) else: return format_error_response( f"Unknown operation: {operation}", error_type="validation_error", operation=operation, ) except Exception as e: return handle_tool_error("robotics_system", e, operation=operation)
• src/robotics_mcp/server.py:471-472 (registration)

  Registration of the robotics_system tool by calling the register() method on the instantiated RoboticsSystemTool.
  self.robotics_system.register() # System: help, status, list_robots logger.debug("Registered robotics_system tool")
• src/robotics_mcp/server.py:174-183 (registration)

  Import of RoboticsSystemTool class and instantiation with required dependencies (MCP server, state_manager, config, etc.).
  from robotics_mcp.tools.robotics_system import RoboticsSystemTool from robotics_mcp.tools.robot_behavior import RobotBehaviorTool from robotics_mcp.tools.robot_virtual import RobotVirtualTool from robotics_mcp.tools.workflow_management import WorkflowManagementTool # Consolidated portmanteau tools (SOTA: max 15 tools) # Note: RobotControlTool and RobotModelTools are imported at module level self.robotics_system = RoboticsSystemTool( self.mcp, self.state_manager, self.config, self.config_loader, self.mounted_servers )
• src/robotics_mcp/tools/robotics_system.py:112-161 (helper)

  Helper method implementing the 'help' operation, providing server info, tools list, features, and configuration.
  async def _handle_help(self) -> Dict[str, Any]: """Handle help operation.""" try: # Get all registered tools tools_info = [] # FastMCP stores tools in _tools dict - get description from docstring for tool_name, tool_func in getattr(self.mcp, '_tools', {}).items(): description = "" if hasattr(tool_func, '__doc__') and tool_func.__doc__: # Get first line of docstring as description description = tool_func.__doc__.split('\n')[0].strip() tools_info.append( { "name": tool_name, "description": description, } ) return format_success_response( "Help information retrieved", data={ "server_name": "Robotics-MCP", "version": "0.1.0", "description": ( "Unified robotics control via MCP - Physical and virtual robots (bot + vbot). " "Provides comprehensive control for Moorebot Scout, Unitree robots, and virtual " "robots in Unity/VRChat. Integrates with osc-mcp, unity3d-mcp, vrchat-mcp, and " "avatar-mcp for seamless virtual robotics testing." ), "features": [ "Physical robot control (ROS 1.4 via rosbridge)", "Virtual robot control (Unity3D/VRChat/Resonite)", "YDLIDAR SuperLight (95g) LiDAR integration", "World Labs Marble/Chisel environment generation", "Multi-robot coordination", "Dual transport (stdio + HTTP)", ], "tools": tools_info, "mounted_servers": list(self.mounted_servers.keys()), "configuration": { "http_enabled": self.config.enable_http, "http_port": self.config.http_port if self.config.enable_http else None, "config_path": str(self.config_loader.config_path), }, }, ) except Exception as e: logger.error("Failed to generate help", error=str(e), exc_info=True) return format_error_response("Failed to generate help information", details={"error": str(e)})
• src/robotics_mcp/tools/robotics_system.py:162-232 (helper)

  Helper method implementing the 'status' operation, including robot counts, mounted servers status, and HTTP connectivity.
  async def _handle_status(self) -> Dict[str, Any]: """Handle status operation.""" try: robots = self.state_manager.list_robots() # Test mounted server connectivity mounted_servers_status: Dict[str, Any] = {} for server_name, server_instance in self.mounted_servers.items(): try: if hasattr(server_instance, "list_tools"): tools = server_instance.list_tools() mounted_servers_status[server_name] = { "available": True, "tools_count": len(tools) if isinstance(tools, dict) else 0, } else: mounted_servers_status[server_name] = { "available": True, "tools_count": "unknown", } except Exception as e: logger.warning("Mounted server connectivity test failed", server=server_name, error=str(e)) mounted_servers_status[server_name] = { "available": False, "error": str(e), } # Test HTTP server if enabled http_status = None if self.config.enable_http: try: import socket sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) sock.settimeout(1) result = sock.connect_ex((self.config.http_host, self.config.http_port)) sock.close() http_status = { "enabled": True, "host": self.config.http_host, "port": self.config.http_port, "reachable": result == 0, } except Exception as e: logger.warning("HTTP server status check failed", error=str(e)) http_status = { "enabled": True, "host": self.config.http_host, "port": self.config.http_port, "reachable": False, "error": str(e), } return format_success_response( "Server status retrieved successfully", data={ "version": "0.1.0", "status": "healthy", "robots": [r.to_dict() for r in robots], "robots_count": len(robots), "mounted_servers": mounted_servers_status, "http": http_status, "config": { "http_enabled": self.config.enable_http, "log_level": self.config.log_level, }, }, ) except Exception as e: return handle_tool_error("robotics_system", e, operation="status")