ros2_manipulator_mcp

ros2_manipulator_mcp is a backend-neutral Model Context Protocol server for inspecting ROS 2 manipulators, computing kinematics, planning and validating motion, managing primitive MoveIt planning-scene objects, and executing application-owned plans when execution has been explicitly enabled. It exposes a small typed manipulation API rather than arbitrary ROS, controller, or shell access.

Version 0.2.0 adds bounded execution, status, and cancellation workflows. The shipped default remains fail-closed: execution.enabled = false.

Architecture

MCP client
 -> stdio MCP server
 -> application service
 -> backend-neutral domain and safety policy
 -> application ports
 -> ROS 2 Jazzy / MoveIt adapter
 -> MoveIt 2 -> ros2_control -> manipulator hardware or mock hardware

MoveIt is replaceable backend infrastructure, not the Manipulator domain. Domain, application, and safety modules contain no ROS, MoveIt, or MCP types. ROS messages and version-specific Jazzy behavior, including execution stopping, remain behind the adapter boundary. Controller and hardware lifecycle management belong to ros2_control_mcp, not this project's public MCP surface.

Related MCP server: nrs_llm

Supported baseline

The verified v0.2.0 baseline is:

• Ubuntu 24.04.4 LTS and Python 3.12+

• ROS 2 Jazzy, rclpy 7.1.11

• MoveIt 2.12.4 and moveit_msgs 2.6.0

• ros2_control 4.45.2 and joint_trajectory_controller 4.40.1

• ROBOTIS OpenMANIPULATOR-X packages 4.1.3 and dynamixel_hardware_interface 1.5.2

• MCP Specification 2026-07-28, MCP Python SDK 2.0.0, and mcp-types 2.0.0

The MCP server exposes stdio only.

MCP surface

The public v0.2.0 surface contains 22 Tools, 7 static Resources, 4 Resource Templates, and 7 Prompts.

The Tools cover discovery; state, pose, FK, IK, and validity; joint, pose, and Cartesian planning; application-owned plan inspection, validation, and discard; primitive planning-scene operations; and these three execution operations:

• execute_motion_plan(plan_id)

• get_execution_status(execution_id)

• cancel_execution(execution_id)

Execution context is also available at manipulator://executions/{execution_id}, and diagnose_execution_failure(execution_id) provides a non-mutating diagnostic prompt. No raw trajectory, controller name, direct FollowJointTrajectory, arbitrary ROS service/action/topic, controller-management, or shell interface is exposed.

Safety and execution contract

Planning, scene mutation, and execution pass through deterministic application policy and validation. Stored plans are process-local, immutable, and application-owned. Before execution the service reserves the plan, requires a fresh matching start state, enforces start tolerance and exact scene revision, and permits only one active execution per manipulator. Backend acceptance consumes the plan permanently; a failure before acceptance releases its reservation. Ambiguous cancellation or unsafe timeout outcomes quarantine the backend until process/adapter restart.

These controls are application safeguards, not certified physical safety. In particular:

• physical execution is opt-in and disabled in the shipped configuration;

• cancel_execution is not an emergency stop or machinery-safety function;

• project CANCELLED requires causal MoveIt PREEMPTED and measured-state stabilization evidence, but does not certify physical standstill;

• the physical power cutoff remains the emergency mechanism;

• the /trajectory_execution_event stop mechanism is specific to the audited MoveIt 2.12.4 baseline and must be reverified for every newly supported MoveIt version.

OpenMANIPULATOR-X reference and verification

The generic API is manipulator-independent. The shipped reference profile uses the official ROBOTIS 4.1.3 model: world planning frame, four-joint arm group, gripper group, and end_effector_link. Only the independently commandable gripper_left_joint is exposed in the gripper group; gripper_right_joint remains its URDF mimic joint.

The complete MCP-to-MoveIt path is verified on official mock hardware. Phase 20 also verified real startup, Dynamixel IDs 11-15, controller and torque lifecycle, real execution and separately operator-visible movement for joints 1-4 and ID 15, orderly Torque OFF, and serial-device release. See Phase 20 for the evidence matrix.

Accepted hardware limitations are: real-hardware cancellation was deliberately not physically release-verified; the tested ID 15 mechanism has a mechanical or encoder-reference mismatch relative to the official model; one historical ID 12 shutdown has an unknown initiating cause; and FastSyncRead can return -3001 before the official driver successfully falls back to normal SyncRead. Do not change URDF/SRDF limits or offsets to mask the ID 15 mechanical-reference issue.

Installation

Install the ROS dependencies from the ROS 2 Jazzy apt repository:

sudo apt-get install \
  ros-jazzy-moveit \
  ros-jazzy-open-manipulator-bringup \
  ros-jazzy-open-manipulator-moveit-config

Then create the isolated Python environment from the lock file:

cd /path/to/ros2_manipulator_mcp
uv sync --frozen

Configuration and startup

The packaged configuration is src/ros2_manipulator_mcp/config/default.toml. Select a deployment-specific copy with ROS2_MANIPULATOR_MCP_CONFIG. The default selects the ros2_jazzy_moveit backend and open_manipulator_x profile and has:

[execution]
enabled = false

For planning-only use, start the desired ROS 2/MoveIt graph and then start the stdio server from a ROS-sourced shell. The verified mock-hardware example is:

export ROS_DOMAIN_ID=66
ros2 launch open_manipulator_bringup open_manipulator_x.launch.py \
  use_mock_hardware:=true init_position:=false start_rviz:=false

export ROS_DOMAIN_ID=66
ros2 launch open_manipulator_moveit_config open_manipulator_x_moveit.launch.py \
  start_rviz:=false

source /opt/ros/jazzy/setup.bash
export ROS_DOMAIN_ID=66
uv run ros2-manipulator-mcp

The server writes MCP protocol messages to stdout. A client that does not inherit a ROS-sourced environment should use a wrapper that sources Jazzy and then execs .venv/bin/ros2-manipulator-mcp.

To enable execution intentionally, make a reviewed deployment-specific copy of the configuration, set [execution] enabled = true, point ROS2_MANIPULATOR_MCP_CONFIG at that copy, and restart the server. This switch does not authorize a particular motion or make the system safe: operators must separately establish hardware readiness, clearance, observation, and immediate physical cutoff access. Never enable execution merely to inspect or plan.

Planning and execution workflow

A bounded planning workflow is:

1. Inspect overview, health, safety, current-state, group, and scene Resources.

2. Validate the fresh current state and select a returned planning group.

3. Plan a joint, pose, or Cartesian goal with conservative scaling.

4. Inspect the opaque plan_id and call validate_motion_plan.

5. Discard the plan if it will not be executed.

When execution is explicitly enabled and separately authorized:

1. Reconfirm current physical and backend readiness.

2. Call execute_motion_plan(plan_id) once; never submit a raw trajectory.

3. Observe get_execution_status or the execution Resource to a terminal state.

4. Treat telemetry, controller result, and physical observation as separate evidence.

5. Use cancel_execution only as an application stop request, never as an emergency-stop substitute.

Testing

Run the normal graph-independent regression suite with:

uv run pytest -q

Live integration tests are opt-in and require the documented official OpenMANIPULATOR-X mock graph. Each integration module documents its required ROS2_MANIPULATOR_MCP_RUN_* environment gate. Phase 20 hardware results are documented evidence and are not part of routine regression.

Known scope limits

v0.2.0 provides one production composition profile, one stdio transport, primitive collision objects, and process-local plans and executions. It does not provide attach/detach, meshes, Servo/jogging, Hybrid Planning, MoveIt Task Constructor, perception, navigation, task orchestration, controller or hardware management, persistent plan storage, authentication, or certified safety.

The development history and exact verification evidence are indexed in docs/README_PHASES.md.

License

Licensed under the Apache License 2.0. See NOTICE for copyright and attribution information.