robotics_system
Manage robotics system operations including getting help, checking server status, and listing registered robots with filtering options.
Instructions
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)
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| operation | Yes | ||
| robot_type | No | ||
| is_virtual | No |
Input Schema (JSON Schema)
{
"properties": {
"is_virtual": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null
},
"operation": {
"enum": [
"help",
"status",
"list_robots"
],
"type": "string"
},
"robot_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null
}
},
"required": [
"operation"
],
"type": "object"
}
Implementation Reference
- The register() method defines and registers the robotics_system tool handler using @self.mcp.tool(). This portmanteau tool handles 'help', 'status', and 'list_robots' operations.def register(self): """Register robotics system tool with MCP server.""" @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:355-369 (registration)The _register_tools() method in the main server class calls self.robotics_system.register() (line 360) to register the robotics_system tool.def _register_tools(self): """Register all MCP tools.""" # Note: MCP servers are already mounted in __init__ # Register portmanteau tools (SOTA: max 15 tools) self.robotics_system.register() # Portmanteau: help, status, list_robots self.robot_control.register() # Portmanteau: movement, status, control self.virtual_robotics.register() # Portmanteau: virtual robot operations self.vbot_crud.register() # Portmanteau: CRUD for virtual robots self.robot_model_tools.register() # Portmanteau: create, import, export, convert self.robot_animation.register() # Portmanteau: animation and behavior control self.robot_camera.register() # Portmanteau: camera and visual feed control self.robot_navigation.register() # Portmanteau: path planning and navigation self.spz_converter.register() # Portmanteau: .spz file conversion and Unity plugin management
- src/robotics_mcp/server.py:120-125 (registration)Instantiation of RoboticsSystemTool class in the server __init__ method, passing required dependencies.# Initialize tool handlers (after MCP is created and servers are mounted) from robotics_mcp.tools.robotics_system import RoboticsSystemTool self.robotics_system = RoboticsSystemTool( self.mcp, self.state_manager, self.config, self.config_loader, self.mounted_servers )
- Helper method _handle_help() called by robotics_system for the 'help' operation.async def _handle_help(self) -> Dict[str, Any]: """Handle help operation.""" try: # Get all registered tools tools_info = [] for tool_name, tool_info in self.mcp.list_tools().items(): tools_info.append( { "name": tool_name, "description": tool_info.get("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)})
- The docstring of the robotics_system tool provides detailed schema information including args, returns, and examples."""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) """