remote-ros-mcp

한국어 안내 (README_KO.md) | Developer Guidelines (AGENTS.md) | Changelog

remote-ros-mcp is a production-grade Model Context Protocol (MCP) server that empowers LLM coding agents (Claude Desktop, Cursor, Antigravity, etc.) to interact with, control, and verify remote ROS2 robotics applications.

Built to pair with the high-performance C++17/ROS2 Jazzy API Gateway wrosbridge, it allows LLM agents to inspect topics, services, actions, parameters, TF transforms, and execute real-time automated verification suites without requiring any local ROS2 installation.

🌟 Highlights

• Zero Local ROS2 Dependency: Operates entirely over standard TCP/gRPC. No rclpy or ROS2 environment is required on the host or agent machine.
• Bi-directional CDR <-> JSON Codec Engine: Translates Little-Endian ROS2 CDR byte streams into clean, validated Python dictionaries/JSON for LLMs.
• Testing & Verification Suite:
  • ros2_assert_topic_published: Assert message arrival matching Python expressions (e.g. msg['linear']['x'] > 0.5).
  • ros2_measure_topic_hz: Real-time topic frequency, period, and jitter analysis.
  • ros2_mock_publish_sequence: Sequence injector to stimulate and test subscriber nodes.
  • ros2_record_and_inspect: Topic data recording and statistical summary.
• One-stop ROS2 Action Support: ros2_action_send_goal dispatches goals, monitors progress, and waits for final results.
• Enterprise Security: Full TLS encryption and API key header (x-api-key) authentication.
• Standalone CLI: Diagnoses remote nodes and topics directly via remote-ros-mcp test-connection and remote-ros-mcp inspect (--json supported).

🛠 Architecture

[LLM Coding Agent (Cursor / Claude / Antigravity)]
                    │
                    │ MCP Protocol (JSON-RPC over stdio)
                    ▼
          ┌─────────────────────┐
          │   remote-ros-mcp    │
          │   (FastMCP Server)  │
          │ ┌─────────────────┐ │
          │ │ CDR <-> JSON    │ │
          │ │ Codec Engine    │ │
          │ └─────────────────┘ │
          └──────────┬──────────┘
                     │
                     │ gRPC + TLS / API-Key
                     ▼
          ┌─────────────────────┐
          │     wrosbridge      │
          │ (ROS2 Jazzy Gateway)│
          └──────────┬──────────┘
                     │
                     │ rclcpp (CDR)
                     ▼
          [ROS2 Robot Node Graph]

🚀 Quick Start

1. Requirements

• Python 3.11+
• uv (recommended) or pip

2. Installation

git clone <repo-url> remote-ros-mcp
cd remote-ros-mcp
uv sync

3. Configuration Management

remote-ros-mcp adheres to OS-standard configuration paths (XDG on Linux, Application Support on macOS, AppData on Windows) with layered precedence: CLI flags > Environment Variables > config.json > Defaults.

• Default Config Path:
  • Linux: ~/.config/remote-ros-mcp/config.json
  • macOS: ~/Library/Application Support/remote-ros-mcp/config.json
  • Windows: %APPDATA%\remote-ros-mcp\config.json
  • Override Variable: REMOTE_ROS_CONFIG_PATH

# Print config path (using rrmcp alias)
uv run rrmcp config path

# Initialize default configuration
uv run rrmcp config init

# Set configuration parameters
uv run rrmcp config set host 192.168.1.100
uv run rrmcp config set port 50051

# View active configuration
uv run rrmcp config show --json

4. CLI Diagnostics

# Test connection health
uv run rrmcp test-connection

# Machine-readable JSON output
uv run rrmcp test-connection --json

# Discover active ROS2 graph
uv run rrmcp inspect --json

🤖 LLM Agent Integration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "remote-ros": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/remote-ros-mcp",
        "run",
        "remote-ros-mcp",
        "run"
      ],
      "env": {
        "ROS_BRIDGE_HOST": "127.0.0.1",
        "ROS_BRIDGE_PORT": "50051"
      }
    }
  }
}

📋 MCP Tools Reference

🧪 Testing & Quality

Strict compliance with the ncli view 24 engineering checklist:

# Run 24 unit & integration tests against in-memory mock server
uv run pytest -v

# Run with test coverage
uv run pytest --cov=remote_ros_mcp --cov-report=term-missing

# Lint & code format checks
uv run ruff check .
uv run ruff format --check .

📄 License

Apache License 2.0. See LICENSE for details.