ros-mcp

ROS 2 MCP 服务

一个适用于 ROS 2 的模型上下文协议（MCP）服务，可让 GitHub Copilot 和其他 AI Agent 与 ROS 2 系统交互。此服务提供用于监控、调试和管理 ROS 2 节点、话题、服务及 TF2 帧的工具。

快速开始

将以下内容添加到 .vscode/mcp.json

{
  "servers": {
    "ros": {
      "command": "npx",
      "args": ["ros-mcp"]
    }
  }
}

确保在 VS Code Copilot 的工具中选择了此服务。

现在就可以开始使用了！ 试试“列出活动的 ROS 话题”来进行测试。

功能

节点管理

• list_ros_nodes：列出所有正在运行的 ROS 2 节点及其详细信息
• get_node_connections：查看某个节点发布和订阅的所有话题
• get_node_parameters：列出指定节点的参数
• set_node_parameter：在运行时修改节点参数
• run_ros_node：从软件包启动 ROS 2 节点
• run_ros_launch：执行启动文件

话题监控

• list_ros_topics：列出所有可用话题，并可选择显示详细类型信息
• get_topic_info：获取指定话题的详细信息
• monitor_topic：订阅话题并在指定时长内收集消息（支持等待的观测工具）
• publish_to_topic：向话题发布消息

服务管理

• list_ros_services：列出所有可用服务
• call_service：调用服务，可选择传入参数

TF2 帧监控

• monitor_tf2_frames：监控 TF2 变换帧及其关系（包括静态和动态变换）

系统可视化与调试

• generate_ros_graph：生成显示节点与话题之间连接关系的依赖图（支持文本和 Graphviz DOT 格式）
• check_ros_system_status：检查整体系统运行状况、守护进程状态，以及节点、话题和服务的数量

安装

前提条件

• ROS 2（已在 Humble 及更高版本上测试）
• Node.js 18+
• npm 或 yarn

手动设置

# Clone or navigate to the repository
cd /path/to/ROS-MCP

# Install dependencies
npm install

# Build the TypeScript
npm run build

在 WSL 中，可能需要将 nvm 的 Node.js 链接到默认 Node.js 路径

sudo ln -s ~/.nvm/versions/node/v24.11.0/bin/node /usr/local/bin/node sudo ln -s ~/.nvm/versions/node/v24.11.0/bin/npm /usr/local/bin/npm

使用方法

运行服务

# Direct execution (recommended for MCP integration)
npm start

# Development with ts-node
npm run dev

使用 GitHub Copilot

在 GitHub Copilot 设置中配置 MCP 服务：

{
  "servers": {
    "ros": {
      "command": "node",
      "args": ["/path/to/ROS-MCP/build/index.js"]
    }
  }
}

工具详情

观测工具（支持等待）

某些工具会随时间收集数据，让 Agent 能够等待并观察：

• monitor_topic：等待 1-30 秒，收集话题消息。支持自定义消息数量上限。适用于：

  • 观察传感器数据流
  • 验证话题发布模式
  • 调试消息吞吐量

• monitor_tf2_frames：在指定时长（1-30 秒）内观测 TF2 帧变换

工具示例

监控话题

Tool: monitor_topic
Parameters:
  - topic_name: "/sensor_msgs/LaserScan"
  - duration_seconds: 5
  - message_count: 10

此操作会在 5 秒内从 LaserScan 话题收集最多 10 条消息。

生成节点图

Tool: generate_ros_graph
Parameters:
  - output_format: "text" (or "dot" for Graphviz)

返回节点和话题连接关系的可视化表示。

监控系统运行状况

Tool: check_ros_system_status
Parameters:
  - include_diagnostics: true

提供全面的系统状态，包括守护进程运行状况、活动节点和服务。

架构

此服务使用以下组件构建：

• @modelcontextprotocol/sdk：用于 Agent 通信的 MCP 框架
• Zod：类型安全的参数验证
• Node.js Child Process：用于执行 ROS 2 CLI 工具的命令执行功能

工作原理

1. 命令执行：每个工具都会执行相应的 ros2 CLI 命令
2. 输出解析：解析结果并格式化，以供 Agent 使用
3. 超时处理：观测类工具使用可配置的超时时间来收集数据
4. 错误处理：命令失败时会正常返回错误消息

面向 Agent 观测的工具设计

此 MCP 服务遵循适用于 AI Agent 的模式：

1. 阻塞式观测操作：像 monitor_topic 这样的工具会在指定时长内阻塞，让 Agent 可以自然地等待结果
2. 有界时间窗口：所有监控工具都设有最长时长（通常为 5-30 秒），以避免无限期等待
3. 渐进式数据收集：工具逐步收集数据，并在观测窗口结束时返回结果
4. 清晰的输出格式：结果以结构化文本呈现，方便 Agent 解析和推理

使用 Copilot 的示例

使用此 MCP 的 Copilot Agent 可以：

Agent: "What topics are currently being published?"
[Uses: list_ros_topics]

Agent: "Let me observe the /cmd_vel topic for 5 seconds"
[Uses: monitor_topic with topic_name="/cmd_vel", duration_seconds=5]
[Waits 5 seconds for data collection]

Agent: "Here are the velocity commands being sent: [parsed data]"

Agent: "Show me how all nodes are connected"
[Uses: generate_ros_graph with output_format="text"]

Agent: "Let me try publishing a test message to the /cmd_vel topic"
[Uses: publish_to_topic]

Agent: "Let me check if any node is having issues"
[Uses: check_ros_system_status with include_diagnostics=true]

限制

• 某些 ROS 2 CLI 命令要求正确加载 ROS 2 环境
• TF2 监控要求安装 tf2_tools 软件包
• 服务会在当前环境中执行命令——请确保已正确安装 ROS 2
• 长时间运行的操作可能会超时；请根据需要调整时长参数

未来增强

• 集成 ROS 2 bag 录制/回放
• 参数服务器监控
• Action 客户端/服务端接口
• 实时 rqt 插件集成
• Rviz2 数据流
• 自定义消息类型解析
• CLI

许可证

MIT

贡献

欢迎贡献！请确保所有工具都能妥善处理错误，并包含适当的参数验证。