rosclaw-nav2-mcp

# ROSClaw-Native Nav2 MCP Server [](https://docs.ros.org) [](https://www.python.org/) [](https://opensource.org/licenses/Apache-2.0) [](https://modelcontextprotocol.io/) > Production-grade MCP server for Nav2 autonomous navigation with ROSClaw OS integration. > **"Teach Once, Embody Anywhere. Share Skills, Shape Reality."** [中文文档](README.zh.md) | [Documentation](https://docs.rosclaw.org/nav2-mcp) --- ## Overview `rosclaw-nav2-mcp` is a ROSClaw-Native MCP (Model Context Protocol) server that bridges Large Language Models (LLMs) with Nav2 autonomous navigation for mobile robots. It implements 6 ROSClaw-Native Standards for production-grade embodied AI applications. ### Key Features - **Asynchronous ROS 2 Actions**: Non-blocking action clients with async/await - **Flywheel-Ready Responses**: Structured JSON for Data Flywheel ingestion - **Digital Twin Firewall**: MuJoCo-based safety validation before real execution - **Graceful Preemption**: Active task tracking with cancel support - **State-Aware Affordance**: Local state machine prevents invalid operations - **Semantic Spatial Binding**: TF2 integration for semantic navigation targets ### Supported Robots - TurtleBot3 / TurtleBot4 - Unitree Go2 / G1 (with mobile base) - Clearpath Husky - Any ROS 2 mobile robot with Nav2 --- ## Installation ### Prerequisites - ROS 2 Humble or Jazzy - Python 3.10+ - Nav2 installed ### Install from PyPI ```bash pip install rosclaw-nav2-mcp ``` ### Install from Source ```bash git clone https://github.com/ros-claw/rosclaw-nav2-mcp.git cd rosclaw-nav2-mcp pip install -e ".[dev]" ``` --- ## Quick Start ### 1. Start ROS 2 and Nav2 ```bash # Terminal 1: Start ROS 2 source /opt/ros/humble/setup.bash ros2 launch nav2_bringup navigation_launch.py ``` ### 2. Start the MCP Server ```bash # Terminal 2: Start MCP Server rosclaw-nav2-mcp ``` Or with explicit transport: ```bash python -m rosclaw_nav2_mcp.server --transport stdio ``` ### 3. Configure MCP Client Add to your MCP client configuration (e.g., Claude Desktop): ```json { "mcpServers": { "rosclaw-nav2": { "command": "rosclaw-nav2-mcp", "transportType": "stdio" } } } ``` --- ## Available Tools | Tool | Description | ROSClaw Standard | |------|-------------|------------------| | `nav2_get_state` | Get current pose & navigation status | State-Aware | | `nav2_navigate_to_pose` | Navigate to (x, y, theta) with semantic labels | Async Actions | | `nav2_navigate_to_pose_firewalled` | Navigate with MuJoCo validation | Firewall | | `nav2_navigate_through_waypoints` | Multi-waypoint navigation | Async Actions | | `nav2_cancel_navigation` | Cancel active navigation | Preemption | | `nav2_lookup_tf_pose` | TF2 semantic pose lookup | TF2 Binding | | `nav2_get_active_navigations` | List active navigation tasks | State-Aware | | `nav2_dock_robot` | Dock to charging station | State-Aware | | `nav2_set_semantic_location` | Set semantic location context | Data Flywheel | --- ## Usage Examples ### Basic Navigation ```python # Navigate to a specific pose result = await nav2_navigate_to_pose( x=2.5, y=1.0, theta=1.57, semantic_label="Go to kitchen" ) ``` ### Semantic Navigation ```python # Use TF frames for semantic navigation result = await nav2_navigate_to_pose( x=0, y=0, theta=0, # Overridden by TF lookup target_tf_frame="kitchen_table", # Automatic pose lookup semantic_label="Navigate to kitchen table" ) ``` ### Firewalled Navigation ```python # Validate path in MuJoCo before real execution result = await nav2_navigate_to_pose_firewalled( x=2.5, y=1.0, theta=1.57, semantic_label="Safe navigation to charging dock" ) # Returns validation status in result.firewall_validated ``` ### Waypoint Navigation ```python # Navigate through multiple waypoints waypoints = "[[1.0, 2.0, 0.0], [3.0, 4.0, 1.57], [5.0, 2.0, 3.14]]" result = await nav2_navigate_through_waypoints( waypoints_json=waypoints, semantic_label="Patrol route A" ) ``` ### Cancel Navigation ```python # Cancel active navigation result = await nav2_cancel_navigation( task_id="nav12345" ) ``` --- ## ROSClaw-Native Standards ### 1. Asynchronous ROS 2 Actions Non-blocking action clients using `rclpy.action.ActionClient` with async/await: ```python # Non-blocking navigation result = await nav2_client.navigate_to_pose(...) # Other operations can run concurrently ``` ### 2. Flywheel-Ready Responses All responses are structured JSON for Data Flywheel ingestion: ```json { "status": "SUCCEEDED", "action_id": "nav12345", "action_type": "navigate_to_pose", "semantic_goal": "Go to kitchen", "timestamp_start": 1234567890.0, "timestamp_end": 1234567895.0, "duration_seconds": 5.0, "start_pose": {"x": 0.0, "y": 0.0, "theta": 0.0}, "goal_pose": {"x": 2.5, "y": 1.0, "theta": 1.57}, "path": { "waypoints": 1, "estimated_length_meters": 5.2 }, "execution": { "success": true, "error_code": null, "error_message": null }, "safety": { "firewall_validated": true, "violations": [] } } ``` ### 3. Firewall Integration MuJoCo-based path validation before real execution: ```python @mujoco_firewall( model_path="src/rosclaw/specs/nav2_sim.xml", safety_level=SafetyLevel.MODERATE ) async def nav2_navigate_to_pose_firewalled(...): # Only executes if MuJoCo validation passes ``` ### 4. Graceful Preemption Cancel active navigation without system instability: ```python async def cancel_navigation(self, task_id: str) -> Dict[str, Any]: goal_handle = self._active_tasks[task_id] cancel_future = goal_handle.cancel_goal_async() cancel_result = await self._await_future(cancel_future) ``` ### 5. State-Aware Affordance Local state machine prevents invalid operations: ```python if self.state.is_navigating: return Nav2ActionResult( status=NavigationStatus.REJECTED, error_message="Robot is already navigating." ) ``` ### 6. Semantic Spatial Binding TF2 integration for semantic navigation: ```python # LLM just provides semantic frame names pose = await lookup_tf_pose("kitchen_table", "map") # No coordinate math required! ``` --- ## Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ LLM Agent (Claude, etc.) │ └─────────────────────────────────────────────────────────────┘ │ MCP Protocol ▼ ┌─────────────────────────────────────────────────────────────┐ │ ROSClaw-Native Nav2 MCP Server │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ Async Action │ │ State Machine│ │ TF2 Semantic │ │ │ │ Client │ │ │ │ Binding │ │ │ └──────────────┘ └──────────────┘ └──────────────────┘ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │ │ │ Flywheel JSON│ │ Firewall │ │ Preemption │ │ │ │ Responses │ │ Validation │ │ Support │ │ │ └──────────────┘ └──────────────┘ └──────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ ROS 2 Actions ▼ ┌─────────────────────────────────────────────────────────────┐ │ Nav2 Navigation Stack │ └─────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────┐ │ Physical Mobile Robot │ └─────────────────────────────────────────────────────────────┘ ``` --- ## Configuration ### Environment Variables | Variable | Default | Description | |----------|---------|-------------| | `ROS_NAMESPACE` | `` | ROS namespace prefix | | `NAV2_MAP_FRAME` | `map` | Default map frame | | `FIREWALL_MODEL_PATH` | `nav2_sim.xml` | MuJoCo model for validation | | `FIREWALL_SAFETY_LEVEL` | `MODERATE` | Safety validation level | ### Robot Configuration Create `robot_config.yaml`: ```yaml navigation: map_frame: "map" odom_frame: "odom" base_frame: "base_link" max_waypoints: 100 velocity_limits: linear: max: 0.5 min: 0.1 angular: max: 1.0 min: 0.1 firewall: model_path: "models/turtlebot3.xml" safety_level: MODERATE ``` --- ## Development ### Setup Development Environment ```bash git clone https://github.com/ros-claw/rosclaw-nav2-mcp.git cd rosclaw-nav2-mcp # Create virtual environment python -m venv .venv source .venv/bin/activate # Install with dev dependencies pip install -e ".[dev]" ``` ### Running Tests ```bash # Run all tests pytest # Run with coverage pytest --cov=rosclaw_nav2_mcp --cov-report=term-missing # Run specific test pytest tests/test_navigation.py -v ``` ### Code Quality ```bash # Format code ruff format . # Check linting ruff check . # Type checking mypy src/rosclaw_nav2_mcp ``` --- ## Data Flywheel Integration All navigation results are structured for automatic Data Flywheel ingestion: ```python { "status": "SUCCEEDED", "semantic_goal": "Go to kitchen", "start_pose": {...}, "goal_pose": {...}, "path": {...}, "execution": {...}, "safety": {...} } ``` This data feeds into: - **Skill Learning**: VLA model training - **Path Planning**: Improved navigation algorithms - **Failure Analysis**: Automatic root cause analysis --- ## Safety Features ### Digital Twin Firewall All navigation validated in MuJoCo before real execution: ```python @mujoco_firewall( model_path="turtlebot3.xml", safety_level=SafetyLevel.MODERATE ) ``` ### Obstacle Avoidance Nav2's built-in obstacle detection and avoidance. ### Dynamic Replanning Automatic path replanning when obstacles are detected. ### Emergency Stop Immediate cancellation via `nav2_cancel_navigation()`. --- ## Troubleshooting ### Server won't start ```bash # Check ROS 2 environment echo $ROS_DISTRO source /opt/ros/humble/setup.bash # Check Nav2 is running ros2 topic list | grep navigate_to_pose ``` ### Navigation fails ```bash # Check robot pose ros2 topic echo /amcl_pose # Check costmaps ros2 service call /global_costmap/clear_entirely std_srvs/srv/Empty # Verify navigation stack ros2 node list | grep navigator ``` ### TF lookup fails ```bash # Check TF tree ros2 run tf2_tools view_frames # Echo specific transform ros2 topic echo /tf ``` --- ## Contributing We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. ### Development Workflow 1. Fork the repository 2. Create a feature branch (`git checkout -b feature/amazing-feature`) 3. Commit changes (`git commit -m 'Add amazing feature'`) 4. Push to branch (`git push origin feature/amazing-feature`) 5. Open a Pull Request --- ## Related Projects - [rosclaw-moveit2-mcp](https://github.com/ros-claw/rosclaw-moveit2-mcp) - MoveIt2 MCP Server - [rosclaw-firewall](https://github.com/ros-claw/rosclaw-firewall) - Digital Twin Firewall - [sdk_to_mcp](https://github.com/ros-claw/sdk_to_mcp) - SDK to MCP Generator - [unitree-sdk2-mcp](https://github.com/ros-claw/unitree-sdk2-mcp) - Unitree Robot MCP Server --- ## Citation If you use ROSClaw in your research, please cite: ```bibtex @software{rosclaw_nav2_mcp, title = {ROSClaw-Native Nav2 MCP Server}, author = {{ROSClaw Team}}, year = {2025}, url = {https://github.com/ros-claw/rosclaw-nav2-mcp} } ``` --- ## License This project is licensed under the Apache License 2.0 - see [LICENSE](LICENSE) for details. --- ## Support - 📖 [Documentation](https://docs.rosclaw.org/nav2-mcp) - 🐛 [Issue Tracker](https://github.com/ros-claw/rosclaw-nav2-mcp/issues) - 💬 [Discussions](https://github.com/ros-claw/rosclaw-nav2-mcp/discussions) --- <p align="center"> <strong>ROSClaw - Embodied Intelligence Operating System</strong><br> <em>Teach Once, Embody Anywhere. Share Skills, Shape Reality.</em> </p>