rm_mcp
This server provides MCP tools for ROS Noetic debugging and tuning, primarily for RoboMaster robot gimbals. It enables:
Environment Inspection: Check ROS Master, topics, nodes, and infrastructure health (
preflight,list_topics,get_topic_info,list_nodes,get_node_info,echo_topic).Target & Process Management: Configure target mode (sim/real), launch/kill ROS launch files locally or via SSH, and ensure infrastructure services (
configure_target,launch,kill_launch,ensure_infrastructure).Controller Lifecycle: List, start/stop, or reload ros_control controllers (
list_controllers,switch_controller,reload_controller).Parameter Management: Read/write ROS parameters, hot-update via
dynamic_reconfigure, and query joint limits (get_param,set_param,set_dynamic_param,get_joint_limits).Excitation Signal Injection: Inject step/sine/square/triangle waveforms into command topics with safety gates (
inject_signal).Data Capture: In-memory topic capture (
capture_topic_sync) and combined capture+inject (capture_inject_sync); rosbag recording (record_bag,stop_record_bag).PID Analysis & Diagnostics: Analyze step/sine responses (
analyze_step_response), gimbal-specific PID analysis (analyze_gimbal_pid), and detailed diagnostics (diagnose_gimbal_tuning) with IAE/ITAE metrics and oscillation/windup detection.Simulation Recovery: Recover Gazebo joints safely (
recover_gazebo_joints).Safety: Confirmation tokens for real-vehicle writes, exclusive publisher arbitration, quiet state restoration, and honest failure reporting with remediation.
Provides integration with ROS (Robot Operating System) for state inspection, parameter tuning, signal injection, rosbag recording, and automated PID response analysis in RoboMaster workspaces.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@rm_mcp Show me the list of active topics and their types."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
rm_mcp
rm_mcp 是面向 rm_ws 的 ROS Noetic MCP Server。它把团队已有的调试 SOP、ROS 状态内省、控制器操作、受控激振和 PID 分析能力提供给 Agent,使调参过程可重复、可审计,并保留实车安全边界。
背景
在控制组的任务中,除了控制器开发,还需要在仿真和实车中进行参数调试与标定。其中一部分工作,例如云台 PID 调试、底盘功率限制调试和拨盘 offset 调试,具有固定流程、指令格式以及可以量化的验收指标。
因此可以让 LLM 通过 MCP 与 ROS 系统结合,按照团队 SOP 完成环境检查、参数修改、受控激振、数据采集和分析,形成自动化调参闭环。
Related MCP server: ROS 2 MCP Server
Why rm_mcp?
rm_mcp 是针对团队工作空间特化的 MCP Server。它既提供对接 ROS 调试流程的工具,也通过 docs/sop/ 记录连车、控制器启动和云台调试等操作规程。Agent 因而可以先理解当前系统与调试步骤,再在明确的安全约束下执行调参。
与直接编写 ROS 脚本相比,rm_mcp 提供:
结构化的 ROS 状态、话题、节点和控制器信息;
对实车及敏感动作的
confirm_token两阶段确认;独占发布仲裁、Quiet State 恢复、看门狗和诚实失败结果;
可直接用于 PID 分析的零落盘内存采样数据;
与团队 SOP 一致的故障诊断和调参建议。
工具列表
当前共有 22 个工具,按调试流程分为以下类别。
1. 环境检查与 ROS 内省
用于确认 ROS 图、话题、节点和系统前置条件;出现 success=False 时应根据 error 及返回中存在的 remediation 排查。
preflight():检查 ROS Master、基础设施、车型、TF 支持与控制器依赖。list_topics():列出活动话题及消息类型。get_topic_info(topic):查询话题类型、发布者和订阅者。list_nodes():列出活动节点。get_node_info(node):查询节点发布、订阅和服务信息。echo_topic(topic, duration_sec, max_messages):限时、限量采样话题消息。
2. 目标、进程与控制器生命周期
用于声明操作目标、启动调试环境以及检查或切换控制器状态。
configure_target(mode, robot_type, rosbridge_uri, ssh_host, confirm_token):设置目标。sim 必须由用户显式指定robot_type;real 从远程车辆~/environment.sh读取ROBOT_TYPE。launch(package, launch_file, args, confirm_token):仿真本地启动或实车 SSH 启动 launch 文件。list_launches():列出由 MCP 管理的 launch 进程。kill_launch(handle, confirm_token):停止指定 launch 进程组。ensure_infrastructure(target_services, confirm_token):检查并拉起rosapi、rosbridge_websocket等基础设施。list_controllers():列出 ros_control 控制器及其状态。switch_controller(start_controllers, stop_controllers, strictness, confirm_token):启停控制器。reload_controller(name, confirm_token):stop → unload → load → start 一步完成,用于应用 init() 时才读取的静态参数(如 feedforward.gravity/mass_origin);单纯 stop/start 不会重读此类参数。
调参 bring-up 参见 docs/sop/01-连车与手跑控制器.md。load_controllers.launch 只加载控制器,仍需通过 switch_controller 启动所需控制器。
3. 参数与机械约束
用于读取参数、热更新运行时配置以及检查关节边界。
get_param(param_name, name):读取 ROS 参数。set_param(param_name, value, confirm_token):写入 ROS 参数;运行中控制器参数请改用set_dynamic_param。set_dynamic_param(node, params, confirm_token, dry_run):通过 dynamic_reconfigure 热更新参数,或用dry_run=True查询可用 schema。get_joint_limits(joint_name, robot_type):查询 URDF 的物理限位、软限位、effort 与速度约束。
4. 激振与零落盘采集
用于在受控条件下发送测试输入并获取反馈数据。
inject_signal(topic, field, waveform, amplitude, frequency, duration_sec, publish_rate_hz, extra_fields, dry_run, force, confirm_token):发送阶跃、正弦、方波或三角波;包含独占发布仲裁、Quiet State 归零和消息时间戳补全。capture_topic_sync(topic, fields, duration_sec, max_messages, timeout_sec):零落盘内存采样,适用于稳态、外部输入或低速手动诊断。
动态激振闭环调参优先使用 rosbag 路径(record_bag → inject_signal → stop_record_bag → analyze_pid(bag_path=...)):返回体量可控、可持久化审计。capture_topic_sync 仅用于稳态或外部输入下的低速采样。
5. 录包与调参分析
用于持久化数据、分析闭环响应和生成诊断建议。
record_bag(topics, duration_sec, mode, output_path, background, trigger_on_topic, confirm_token):本地或远程录包;动态注入场景使用background=True。stop_record_bag(bag_handle, confirm_token):停止后台录包并读取元数据。analyze_pid(topic_data, bag_path, signal_type, settle_threshold, accept_threshold, diagnostics, angle_wrapping, axis, ...):统一 PID 分析——阶跃/正弦/跟踪指标、验收判定与 opt-in 诊断(oscillation/windup/saturation)。验收条件:正弦激振时位置环跟踪误差error < 0.006 rad(max|error|,accept_threshold=0.006)。
云台调参流程参见 docs/sop/04-云台调试.md。位置环跟踪误差的参考验收阈值为 0.006 rad。
使用约定
开始会话时先调用
configure_target(mode="sim", robot_type="<type>");real 模式调用configure_target(mode="real"),车型由远程车辆发现。优先使用 MCP 工具;只有工具明确不覆盖所需能力时才退回
rostopic、rosparam、rosservice或rosbagCLI,并说明工具缺口。实车写操作、红线关键字以及高幅值激振可能返回
PENDING_CONFIRMATION;取得用户确认后使用返回的confirm_token重试。对实时控制参数使用
set_dynamic_param,不要期望set_param写入后被运行中控制器自动重读。record_bag是动态调参的默认采集路径;capture_topic_sync仅用于稳态或外部输入场景。
Tools (English)
The server exposes 22 tools, grouped by their role in the debugging workflow.
1. Environment checks and ROS introspection
preflight(): Checks ROS Master reachability, target identity, required TF/feedback publishers, and controller dependencies. In simulation, BLOCKING or UNKNOWN TF/feedback status always makesready=False.list_topics(): Lists active ROS topics and message types.get_topic_info(topic): Reports a topic's type, publishers, and subscribers.list_nodes(): Lists active ROS nodes.get_node_info(node): Reports a node's publications, subscriptions, and services.echo_topic(topic, duration_sec, max_messages): Samples a topic with bounded duration and message count.
2. Target, process, and controller lifecycle
configure_target(mode, robot_type, rosbridge_uri, ssh_host, confirm_token): Selects the target. Sim requires a user-suppliedrobot_type; real discoversROBOT_TYPEfrom the remote vehicle's~/environment.sh.launch(package, launch_file, args, confirm_token): Starts a local simulation launch or a remote launch over SSH.list_launches(): Lists launch processes tracked by this MCP server.kill_launch(handle, confirm_token): Terminates a tracked launch process group.ensure_infrastructure(target_services, confirm_token): Ensures supportedrosapiandrosbridge_websocketinfrastructure is available.list_controllers(): Lists ros_control controllers and their states.switch_controller(start_controllers, stop_controllers, strictness, confirm_token): Starts or stops ros_control controllers.reload_controller(name, confirm_token): stop -> unload -> load -> start in one call, to apply static parameters read only in init() (e.g. feedforward.gravity/mass_origin); plain stop/start never re-reads them.
3. Parameters and mechanical constraints
get_param(param_name, name): Reads a ROS parameter.set_param(param_name, value, confirm_token): Writes a ROS parameter; for runtime parameters of a running controller use set_dynamic_param instead.set_dynamic_param(node, params, confirm_token, dry_run): Hot-updates dynamic_reconfigure parameters or returns their schema in dry-run mode.get_joint_limits(joint_name, robot_type): Reads physical and soft joint limits, effort/velocity constraints, and the robot identity and source that own those limits.
4. Excitation and zero-disk capture
inject_signal(topic, field, waveform, amplitude, frequency, duration_sec, publish_rate_hz, extra_fields, dry_run, force, confirm_token): Publishes bounded step/sine/square/triangle excitation with exclusive-publisher arbitration, timestamps, and Quiet State restoration.capture_topic_sync(topic, fields, duration_sec, max_messages, timeout_sec): Captures topic samples directly in memory for steady-state or externally driven diagnostics.
5. Recording and tuning analysis
record_bag(topics, duration_sec, mode, output_path, background, trigger_on_topic, confirm_token): Records local or remote rosbag data, with background mode for injection workflows.stop_record_bag(bag_handle, confirm_token): Stops a background recording and returns bag metadata.analyze_pid(topic_data, bag_path, signal_type, settle_threshold, accept_threshold, diagnostics, angle_wrapping, axis, effort_limit, skip_initial_sec, skip_final_sec, topic_filter): Unified PID analysis — step/sine/tracking metrics (python-control step_info conventions, IAE/ITAE), pass/fail acceptance (acceptance condition: position-loop tracking errorerror < 0.006 radat every sample under sinusoidal excitation;accept_threshold=0.006), and opt-in diagnostics (oscillation, windup cross-checked with saturation, saturation). Trailing quiet-window setpoint returns are excluded viaskip_final_sec; unexcluded trailing edges are reported inwarnings.
Use the rosbag path for the dynamic tuning loop (record_bag -> inject_signal -> stop_record_bag -> analyze_pid(bag_path)); use capture_topic_sync only for steady-state or externally driven sampling.
快速开始
环境要求
ROS Noetic
Python >= 3.10
安装与启动
cd src/rm_mcp
uv sync
uv run python -m rm_mcp.server也可以通过 MCP Inspector 调试:
cd src/rm_mcp
uv run mcp dev src/rm_mcp/server.py测试
cd src/rm_mcp
uv run pytestGazebo 硬件在环测试需显式启用:
cd src/rm_mcp
RUN_HW_TESTS=1 uv run pytest tests/hardware/ -m hardware -v相关文档
CONTEXT.md:工具行为、传输与安全边界。DEVELOPMENT.md:开发状态、设计决策和测试约定。docs/sop/01-连车与手跑控制器.md:连车与控制器启动。docs/sop/04-云台调试.md:云台 PID 调参。
Available Tools
26 toolsanalyze_gimbal_pidA
Domain-specific analysis tool for RoboMaster Gimbal PID tracking error (0.006 rad threshold).
PREFER passing in-memory topic_data directly from capture_topic_sync for fast tuning loops without disk I/O. Accepts bag_path for offline analysis.
Inputs: axis, loop, bag_path, topic_data, +2 more. Returns: result
analyze_step_responseC
Analyze step or tracking performance from rosbag signals.
Inputs: bag_path (required), mode, signal_type, topic_filter, +2 more. Returns: result
capture_inject_syncA
Capture a topic in memory while injecting an excitation signal — one call, zero disk I/O.
Preferred closed-loop tuning path in simulation (target_mode="sim") or high-bandwidth wired setups: combines capture_topic_sync-style in-memory sampling with inject_signal-style safe publishing, server-side.
Parameters:
capture_topic: Feedback ROS topic to sample (e.g. "/controllers/gimbal_controller/pos_state").
inject_topic: Command topic to publish to — inject at the controller INPUT (e.g. "/controllers/gimbal_controller/command"), NOT the PID output stage.
field: Message field to drive (e.g. "traj_yaw").
waveform / amplitude / frequency / duration_sec / publish_rate_hz / extra_fields / force / confirm_token: forwarded verbatim to inject_signal — all safety gates (red-tier confirm_token handshake, exclusive publisher arbitration, quiet-state restoration) are owned by inject_signal and NOT pre-consumed here.
dry_run: if True, skip the capture subscriber and perform only the inject_signal schema/no-publish check. Safe for e2e schema validation without a live ROS master; all confirmation semantics remain delegated to inject_signal.
quiet_window_sec: extra capture time AFTER the injection ends so the quiet-state restoration is fully sampled.
fields: capture field paths; omit for auto-discovery (GimbalPosState / PidState).
max_messages: capture sample cap.
Inputs: field (required), inject_topic (required), capture_topic (required), force, +11 more. Returns: result
capture_topic_syncA
PREFERRED & FASTEST data source for closed-loop PID tuning in simulation and wired setups (<10ms latency).
Captures high-frequency topic data in memory without disk I/O. Pass output directly to diagnose_gimbal_tuning(topic_data=...) or analyze_gimbal_pid(topic_data=...) for rapid tuning loops!
Inputs: topic (required), fields, timeout_sec, duration_sec, +1 more. Returns: result
configure_targetB
Set target mode and endpoints. Sim requires an explicit robot_type; real reads it from the vehicle.
Inputs: mode (required), ssh_host, robot_type, confirm_token, +1 more. Returns: result
diagnose_gimbal_tuningA
Detailed domain-specific diagnosis tool for RoboMaster Gimbal PID step response, velocity oscillation, windup, and saturation.
PREFER passing in-memory topic_data directly from capture_topic_sync for fast tuning loops without disk I/O. Accepts bag_path for offline analysis.
False-deadlock detection: when feedback already starts at the final setpoint (step test was not reset), returns step_info.initial_position_at_final_value=True, warnings code "initial_position_at_final_value", and prepends reset guidance (send traj_=0 first, then re-run the step test).
Inputs: axis, bag_path, topic_data, settle_criterion, +1 more. Returns: result
echo_topicC
Sample ROS topic messages with safety throttling via pure Rosbridge WebSocket API.
Inputs: topic (required), duration_sec, max_messages. Returns: result
ensure_infrastructureB
Ensure essential infrastructure services (rosapi, rosbridge) are running on the target.
Inputs: confirm_token, target_services. Returns: result
get_joint_limitsA
Query URDF physical and soft joint limits (lower/upper rad, effort, velocity).
Inputs: joint_name, robot_type. Returns: result
get_node_infoA
Inspect ROS node details (publications, subscriptions, services) via pure Rosbridge WebSocket API.
Inputs: node (required). Returns: result
get_paramA
Read a ROS parameter (L0 read-only). param_name: full parameter path, e.g. '/controllers/gimbal_controller/pid_pos/p' ('name' is accepted as an alias).
Inputs: name, param_name. Returns: result
get_topic_infoA
Inspect ROS topic details (msg_type, publishers, subscribers) via pure Rosbridge WebSocket API.
Inputs: topic (required). Returns: result
inject_signalA
Inject a step or sinusoidal excitation signal into a command topic.
Choosing the right injection point: inject at controller INPUT (e.g. /controllers/gimbal_controller/command, rm_msgs/GimbalCmd: extra_fields={"mode": 3}, (GimbalCmd mode constants: 0: RATE, 1: TRACK, 2: DIRECT, 3: TRAJ). field="traj_yaw"/"traj_pitch") — NOT */controllers//command (std_msgs/Float64), which is PID-computed OUTPUT. Quiet state restoration (0.0 signal) occurs automatically upon completion (1-loop RealtimeBuffer update delay).
Timestamps: after extra_fields are applied, a zero/absent top-level stamp or
header.stamp is filled with rospy.Time.now() on every published message
(quiet-state restoration included); an explicit nonzero stamp is preserved —
eliminating 0-timestamp artifacts in rosbag-based analysis.
Inputs: field (required), topic (required), force, dry_run, +7 more. Returns: result
kill_launchB
Terminate a running launch process by handle.
Inputs: handle (required), confirm_token. Returns: result
launchA
Launch a ROS launch file — local roslaunch in sim mode, SSH to vehicle NUC on real targets. package: ROS package name (REQUIRED, e.g. 'rm_config') launch_file: Launch filename (REQUIRED, e.g. 'load_controllers.launch') args: Optional arguments as list ['robot_type:=standard6'] or dict {'robot_type': 'standard6'}.
Inputs: package (required), launch_file (required), args, confirm_token. Returns: result
list_controllersA
List ros_control controllers and their states (L0 read-only).
Inputs: no named parameters. Returns: result
list_launchesA
List running roslaunch/mon launch processes.
Inputs: no named parameters. Returns: result
list_nodesA
List active ROS nodes via pure Rosbridge WebSocket API.
Inputs: no named parameters. Returns: result
list_topicsA
List active ROS topics and their message types via pure Rosbridge WebSocket API.
Inputs: no named parameters. Returns: result
preflightA
Inspect environment prerequisite states without mutating system state.
Inputs: no named parameters. Returns: result
record_bagA
Record a rosbag for specified topics over a set duration. Set background=True for async recording.
trigger_on_topic appends the named topic to the recorded topic list.
rosbag record --duration starts its countdown only after the first message
arrives on any recorded topic. Synchronous recording has a hard timeout of
duration_sec + 15s; a silent background recording remains active until
stop_record_bag(handle). Use background=True and choose duration_sec long
enough to cover inject latency + signal duration + margin.
Inject-then-record sequence: record_bag(background=True, trigger_on_topic=) -> confirm the returned handle -> inject_signal(...) -> stop_record_bag(handle). A synchronous record on a silent command topic (no publisher before injection) hangs because the synchronous call would block injection.
Inputs: topics (required), mode, background, output_path, +3 more. Returns: result
recover_gazebo_jointsA
Safely recover simulation gimbal joints through Gazebo services.
Simulation only. Resolves the live model first, requires its identity to match the robot-description/limit source, rejects positions outside those known soft limits, stops gimbal_controller, calls set_model_configuration, and verifies each joint through get_joint_properties. timeout_sec bounds service waits and invocations. Timed-out writes are explicitly ambiguous and may have occurred; no CLI fallback or automatic retry is attempted.
Inputs: joint_positions (required), model_name, timeout_sec, confirm_token. Returns: result
set_dynamic_paramA
Hot-update a running node's runtime parameters via dynamic_reconfigure. node: Target ROS node name (REQUIRED, e.g. '/controllers/gimbal_controller'). Accepted aliases: node_name, param_name. params: Dictionary of parameter values to write (e.g. {'p': 10}). Keys like 'yaw/pid/p' map to 'p'. dry_run: If True, inspect available keys and schema without mutating parameters.
Inputs: node, params, dry_run, node_name, +2 more. Returns: result
set_paramC
Set a ROS parameter with pre-read dry-run state capture and post-write verification. param_name: full parameter path, e.g. '/rm_config/rate' ('name' is accepted as an alias).
Inputs: name, value, param_name, confirm_token. Returns: result
stop_record_bagA
Stop a running background rosbag recording handle and retrieve metadata.
Metadata is read with allow_unindexed=True; the bag-internal start/end
timestamps — not wall-clock diffs — are the authoritative duration_sec
under use_sim_time (the sim clock can pause or drift).
Inputs: handle, bag_handle, confirm_token. Returns: result
switch_controllerB
Start/stop ros_control controllers (red-tier on real targets).
Inputs: strictness, confirm_token, stop_controllers, start_controllers. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 26 tools
Several tool pairs overlap in function: list_topics/get_topic_info, list_nodes/get_node_info, capture_topic_sync/capture_inject_sync, and the three analysis tools (analyze_step_response, analyze_gimbal_pid, diagnose_gimbal_tuning). While descriptions clarify the differences, the boundaries are not always obvious to an agent.
Most tools follow a verb_noun pattern (list_topics, get_param, set_param, etc.). Exceptions like 'preflight' and 'launch' are bare verbs, and 'capture_inject_sync' is a compound. Overall the pattern is consistent enough.
With 26 tools, the surface is heavy, and there is notable redundancy (e.g., three analysis tools, two capture tools). Some tools could be merged, making the count feel inflated for the stated purpose.
The core gimbal tuning workflow is well covered: parameter read/write, injection, capture, recording, and analysis. Minor gaps exist, such as a generic service caller or generic publish tool, but agents can work around these using existing tools.
Related MCP Connectors
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Zero-auth ROS 2 Humanoid, Q3 Proxemics, 3-Level Voice Arbiter, A2A-MCP Bridge & W3C VC 2.0.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
MCP-Native LLM Orchestration Agent
Related MCP Servers
- AlicenseBqualityBmaintenanceRobotMCP is a comprehensive Model Context Protocol (MCP) server that bridges the gap between human language and Robot Framework automation. It enables AI agents to understand test intentions, execute steps interactively, and generate complete test suites from successful executions.194,288 PyPI118Apache 2.0
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server for ROS 2, enabling AI assistants to introspect and interact with ROS 2 systems.2MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for AI agents to inspect and control ROS2 graphs, enabling topic listing, node info, service calls, parameter management, and pub/echo without manual ROS2 CLI usage.12MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server for ROS 2 that enables GitHub Copilot and other AI agents to interact with ROS 2 systems. This server provides tools for monitoring, debugging, and managing ROS 2 nodes, topics, services, and TF2 frames.1534 npmMIT