Skip to main content
Glama
robot-motion-mcp

robot-motion-mcp

by outerwang

robot-motion-mcp

A local stdio MCP server for inspecting robot motion-planning tasks and records, starting an isolated planning run, checking its status, and reporting validation evidence.

Tools

Tool

Purpose

list_tasks

List tasks found in the configured data roots and protocol fixtures.

get_task_info

Read task inputs, model/version information, completeness, and collision semantics.

get_experiment_report

Read a configured historical planning or validation record.

start_motion_plan

Start an offline planner in a per-run worktree and return a run ID.

get_plan_status

Read execution, planning-result, and validation state separately.

validate_motion

Report the available independent validation evidence.

The server does not control a physical robot. A planner finding a path does not by itself mean that the path passed independent validation. A timeout is not proof that a path does not exist.

Related MCP server: io.github.ibondarenko1/worldfuzz

Install

Requires Python 3.11 or newer.

git clone <repository-url> robot-motion-mcp
cd robot-motion-mcp
py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install -r requirements.txt
.\.venv\Scripts\python.exe -m pip install -e .

Configure local inputs

The repository contains the MCP server and Skill integration files. Planning inputs and the planner environment are configured on the machine that runs the server; they are not downloaded by the server automatically.

Set the roots to directories with the expected project layout. ROBOT_MOTION_NEW_DESIGN_ROOT points to a New_Design tree; ROBOT_MOTION_AUDIT_ROOT points to a directory of historical JSON records. For real planning, set ROBOT_MOTION_PLANNER_PYTHON to a Python interpreter that has the planner's required packages installed.

$env:ROBOT_MOTION_NEW_DESIGN_ROOT = 'D:\robot-data\New_Design'
$env:ROBOT_MOTION_AUDIT_ROOT = 'D:\robot-data\research_audit'
$env:ROBOT_MOTION_RUNS_ROOT = 'D:\robot-data\robot-motion-runs'
$env:ROBOT_MOTION_PLANNER_PYTHON = 'D:\Python\envs\planner\python.exe'

The supported variables are ROBOT_MOTION_WORKSPACE, ROBOT_MOTION_NEW_DESIGN_ROOT, ROBOT_MOTION_AUDIT_ROOT, ROBOT_MOTION_RUNS_ROOT, and ROBOT_MOTION_PLANNER_PYTHON. Explicit root variables take precedence over the workspace defaults. The planner interpreter is fixed by configuration and cannot be selected by a model tool argument.

Run

Start the server directly over stdio:

.\.venv\Scripts\python.exe -m robot_motion_mcp.server

For an MCP host that loads workspace configuration, open agent-workspace as its working directory and use the included .mcp.json; run_server.cmd resolves the project and virtual environment relative to itself.

Install the Skill

The companion repository, robot-motion-diagnosis-skill, contains the robot-motion-diagnosis Skill. Install it in the Skill directory used by your agent. The Skill expects the six tools listed above to be available.

Development

python -m pytest tests/test_runner.py -q

The included runner test uses a synthetic planner fixture. Tests that need a real planning workspace or a specific MCP host configuration should be run in an environment that provides those inputs.

Available Tools

6 tools
get_experiment_reportA

Read a frozen experiment/run report with honest status semantics: planner raw status + canonical state, candidate-path facts, independent-validation state (PASSED/FAILED/INCOMPLETE/NOT_VALIDATED/TOOL_ERROR), durations, error class, caveats and source-file references. run_id forms: '/' (e.g. 'rm_next_009_full_motion_generation_cost/T1_CM2B_P0', 'third_workpiece_process_boundary/EXPERIMENT', '_audit/FINAL_QA'), 'ND-SEED-', 'MOCK-*'. Timeouts are never reported as infeasibility.

Inputs: run_id (required). Returns: ok, mock, report, run_id

get_plan_statusA

Query a real planning run (run_id from start_motion_plan) with three separate dimensions: execution_status (PENDING/RUNNING/COMPLETED/FAILED/TIMEOUT/UNKNOWN - COMPLETED means the tool finished, not that a path was found), plan_result (PATH_FOUND/NO_CANDIDATE_WITHIN_BUDGET/ERROR/NOT_AVAILABLE) and validation_status. Status survives service restarts via persistent records; unverifiable outcomes are reported as UNKNOWN, never silently converted.

Inputs: run_id (required). Returns: ok, run_id, details, task_id, +4 more

get_task_infoA

Read one task's configuration: workpieces, placement/allocation, robots, planner methods, collision-semantics flags (verbatim from config), start/end data sources and data completeness. task_id forms: 'ND-SEED-', frozen research task ids (e.g. 'T1_CM2B'), or 'MOCK-*' fixtures.

Inputs: task_id (required). Returns: ok, info, kind, mock, +3 more

list_tasksB

List tasks that actually exist in the connected read-only sources (New_Design placement seeds, frozen research-audit tasks, labeled MOCK fixtures). No task ids are invented.

Inputs: include_mock. Returns: ok, tasks, server, sources, +2 more

start_motion_planA

Start ONE real offline planning run for a New_Design seed task (task_id 'ND-SEED-') inside an isolated per-run worktree copy; the upstream project is never written (pre/post SHA-256 manifests attached). planner: whitelist ['Lazy_PRM'] (applied to the worktree config). time_budget_seconds: 10-1800 (default 120); on expiry the process tree is killed and status becomes TIMEOUT (never 'no path exists'). request_id (optional, [\w.-]{1,64}) makes retries idempotent. Returns immediately with a run_id; poll get_plan_status. Only one real run at a time.

Inputs: task_id (required), planner, request_id, time_budget_seconds. Returns: ok, seed, run_id, message, +6 more

validate_motionA

Report the independent-validation status bound to a run's candidate path. For NEW local runs this is NOT_RUN until a scene-compatible strict validator is registered - planning success is never treated as PASS, and historical verdicts are never transferred to new paths. For frozen research-audit records the recorded verdict is reported verbatim, bound to the recorded path sha256 and input contract. run_id forms: local 'R-*' runs and historical records like 'rm_next_015_fr69b_transfer_expansion/Q1_RRT_E1' or '.../REF_T1_CM2B_P0'.

Inputs: run_id (required). Returns: ok, run_id, source, details, +7 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool maps to a distinct action/resource: listing tasks, reading task details, reading frozen experiment reports, starting a planning run, polling run status, and validating a run's path. The frozen-report versus live-run-status split is clearly described and unlikely to be confused.

    Naming Consistency5/5

    All tools use snake_case with a clear verb_noun pattern: list_tasks, get_task_info, get_experiment_report, start_motion_plan, get_plan_status, validate_motion. The convention is uniform and predictable.

    Tool Count5/5

    Six tools is well-scoped for a motion-planning server: task inspection, report reading, run initiation, status polling, and validation are each represented exactly once. There is no redundant or filler tool.

    Completeness4/5

    The core lifecycle is covered: discover tasks, inspect them, start a plan, poll status, and validate results. Minor gaps remain, such as canceling/stopping an in-flight planning run or listing available runs/reports directly.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      This MCP server enables inspecting ROS 2 manipulators, computing kinematics, planning motion, and managing primitive MoveIt planning-scene objects via a typed API, with no physical execution support.
      Apache 2.0
    • A
      license
      C
      quality
      B
      maintenance
      Enables MCP clients to inspect operational status and channels, lint human-reviewed plans, search and query ledger data, and run queue-based writes with dry-run defaults and safeguards against unverified or unapproved campaigns.
      47
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      A read-only MCP server that lets an AI agent inspect a ROS2 graph, its underlying DDS participants, readers, writers and QoS mismatches, and recorded bag files, with twelve typed tools that behave the same against a live robot or built-in mock fixtures. It has no write path at all, so it can never publish to the bus or command a robot.
      18
      339 PyPI
      3
      MIT