Nischal2017/SO101-CameraMan

Waypoint MCP Server

An MCP (Model Context Protocol) server that provides waypoint management and playback functionality for the SO100 robot. This server wraps the existing waypoint recording and playback scripts into a standardized MCP interface.

Features

The server provides three main tools:

🔍 read_waypoint

Read the current joint positions from the SO100 robot as a waypoint.

• Parameters:
  • name (optional): Custom name for the waypoint
  • port (optional): Serial port for robot connection (default: /dev/ttyACM1)
• Returns: JSON string with waypoint data including timestamp, joints, and metadata

▶️ play_waypoint

Execute waypoint sequences on the SO100 robot with smooth interpolation.

• Parameters:
  • waypoint_data: Can be:
    • String: Path to JSON file containing waypoints
    • Dict: Single waypoint with 'joints' key
    • List: Multiple waypoints or joint position arrays
  • port (optional): Serial port for robot connection (default: /dev/ttyACM1)
• Returns: Status message indicating success or failure

📏 get_joint_limits

Get the joint angle limits for the SO100 robot.

• Parameters:
  • port (optional): Serial port for robot connection (default: /dev/ttyACM1)
• Returns: JSON string containing min/max values for each joint

Installation

1. Install dependencies:

   uv sync --dev
   

2. Make sure the SO100 robot is connected via USB serial port (typically /dev/ttyACM1)

3. Copy the so100_client.py from the parent directory to ensure robot communication works

Usage

Starting the Server

HTTP Transport (Recommended for Development)

python main.py --transport streamable-http --port 8080

STDIO Transport (For MCP Clients)

python main.py --transport stdio

Custom Configuration

python main.py --transport streamable-http --host 0.0.0.0 --port 9000 --robot-port /dev/ttyACM0

Example Tool Usage

Reading Current Position

# Via MCP client
result = call_tool("read_waypoint", {"name": "home_position"})

Playing Waypoints from File

# Play waypoints from JSON file
result = call_tool("play_waypoint", {"waypoint_data": "my_waypoints.json"})

Playing Single Waypoint

# Move to specific joint angles
waypoint = {"joints": [0, 90, -45, 0, 0, 0]}
result = call_tool("play_waypoint", {"waypoint_data": waypoint})

Playing Multiple Waypoints

# Execute sequence of positions
waypoints = [
    [0, 0, 0, 0, 0, 0],      # Start position
    [90, 0, 0, 0, 0, 0],     # Move joint 1
    [90, 45, 0, 0, 0, 0]     # Move joint 2
]
result = call_tool("play_waypoint", {"waypoint_data": waypoints})

Getting Joint Limits

# Get robot joint limits
limits = call_tool("get_joint_limits")

Development

Project Structure

waypoint-mcp/
├── src/waypoint_mcp/
│   ├── __init__.py
│   ├── waypoint_controller.py    # Domain logic
│   └── server.py                 # MCP server implementation
├── tests/
│   ├── __init__.py
│   └── test_waypoint_mcp.py     # Basic tests
├── main.py                       # Entry point
├── pyproject.toml               # Dependencies
└── README.md

Running Tests

uv run pytest

Code Formatting

uv run black src/ tests/
uv run isort src/ tests/

Dependencies

• Core:

  • mcp[cli]>=1.1.2 - MCP protocol implementation
  • pyserial>=3.5 - Serial communication for robot
  • typing-extensions>=4.5.0 - Type hints

• Development:

  • pytest>=7.0.0 - Testing framework
  • pytest-asyncio>=0.21.0 - Async testing support
  • black>=23.0.0 - Code formatting
  • isort>=5.12.0 - Import sorting

Integration with Existing Scripts

This MCP server wraps the functionality from:

• distiller-record-wps.py - Waypoint recording capabilities
• distiller-play-wps.py - Waypoint playback capabilities

The server provides a cleaner API while maintaining compatibility with the existing waypoint file format.

Safety Notes

⚠️ IMPORTANT SAFETY WARNINGS:

1. Robot Movement: The play_waypoint tool will cause the robot to move. Ensure the workspace is clear.
2. Emergency Stop: Keep the robot's emergency stop button accessible.
3. Joint Limits: The server provides joint limits, but always verify safe positions.
4. Serial Connection: Ensure proper serial connection to avoid communication errors.

Troubleshooting

Common Issues

1. "SO100Client not available"

   • Ensure so100_client.py is accessible in the parent directory
   • Check Python path configuration

2. "Failed to connect to SO100"

   • Verify robot is powered on and connected via USB
   • Check serial port permissions: sudo chmod 666 /dev/ttyACM1
   • Try different serial ports: /dev/ttyACM0, /dev/ttyUSB0

3. "No available ports in range 8000-9000"

   • Use --port argument to specify a custom port
   • Check for conflicting services

4. Waypoint file errors

   • Ensure JSON files follow the expected format with "waypoints" array
   • Each waypoint should have a "joints" field with 6 joint angles

License

This project is part of the LeRobotDistiller examples and follows the same licensing terms.