rm_mcp

rm_mcp 是面向 rm_ws 的 ROS Noetic MCP Server。它把团队已有的调试 SOP、ROS 状态内省、控制器操作、受控激振和 PID 分析能力提供给 Agent，使调参过程可重复、可审计，并保留实车安全边界。

背景

在控制组的任务中，除了控制器开发，还需要在仿真和实车中进行参数调试与标定。其中一部分工作，例如云台 PID 调试、底盘功率限制调试和拨盘 offset 调试，具有固定流程、指令格式以及可以量化的验收指标。

因此可以让 LLM 通过 MCP 与 ROS 系统结合，按照团队 SOP 完成环境检查、参数修改、受控激振、数据采集和分析，形成自动化调参闭环。

Related MCP server: RobotMCP

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。

使用约定

1. 开始会话时先调用 configure_target(mode="sim", robot_type="<type>")；real 模式调用 configure_target(mode="real")，车型由远程车辆发现。

2. 优先使用 MCP 工具；只有工具明确不覆盖所需能力时才退回 rostopic、rosparam、rosservice 或 rosbag CLI，并说明工具缺口。

3. 实车写操作、红线关键字以及高幅值激振可能返回 PENDING_CONFIRMATION；取得用户确认后使用返回的 confirm_token 重试。

4. 对实时控制参数使用 set_dynamic_param，不要期望 set_param 写入后被运行中控制器自动重读。

5. 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 makes ready=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-supplied robot_type; real discovers ROBOT_TYPE from 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 supported rosapi and rosbridge_websocket infrastructure 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 error error < 0.006 rad at 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 via skip_final_sec; unexcluded trailing edges are reported in warnings.

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

• uv

安装与启动

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 pytest

Gazebo 硬件在环测试需显式启用：

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 调参。