JinDaGe - ros-mcp MCP Details

article

README

🚀 ROS 2 MCP Server

ROS 2 MCP Server 是一个用于 ROS 2 的模型上下文协议（MCP）服务器，它使 GitHub Copilot 和其他 AI 代理能够与 ROS 2 系统进行交互。该服务器提供了用于监控、调试和管理 ROS 2 节点、主题、服务和 TF2 框架的工具。

🚀 快速开始

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

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

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

现在你可以开始使用了！尝试输入 "List active ros topics" 进行测试。

✨ 主要特性

节点管理

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

手动设置

# 克隆或导航到仓库
cd /path/to/ROS-MCP

# 安装依赖
npm install

# 构建 TypeScript
npm run build

WSL 可能需要将 nvm 节点链接到默认节点路径：

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

💻 使用示例

运行服务器

# 直接执行（推荐用于 MCP 集成）
npm start

# 使用 ts-node 进行开发
npm run dev

与 GitHub Copilot 配合使用

在你的 GitHub Copilot 设置中配置 MCP 服务器：

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

工具示例

监控主题

工具：monitor_topic
参数：
  - topic_name: "/sensor_msgs/LaserScan"
  - duration_seconds: 5
  - message_count: 10

此示例在 5 秒内从 LaserScan 主题收集最多 10 条消息。

生成节点图

工具：generate_ros_graph
参数：
  - output_format: "text"（或 "dot" 用于 Graphviz）

返回节点和主题之间连接的可视化表示。

监控系统健康状况

工具：check_ros_system_status
参数：
  - include_diagnostics: true

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

🔧 技术细节

架构

该服务器使用以下技术构建：

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

工作原理

命令执行：每个工具执行相应的 ros2 CLI 命令。
输出解析：解析结果并将其格式化为适合代理使用的形式。
超时处理：观测工具使用可配置的超时来收集数据。
错误处理：失败的命令会优雅地返回错误消息。

为代理观测设计工具

此 MCP 服务器遵循与 AI 代理配合良好的模式：

阻塞观测操作：像 monitor_topic 这样的工具会在指定的时间段内阻塞，允许代理自然地等待结果。
有界时间窗口：所有监控工具都有最大持续时间（通常为 5 - 30 秒），以防止无限等待。
渐进式数据收集：工具逐步收集数据，并在观测窗口结束时返回结果。
清晰的输出格式：结果是结构化的文本，代理可以轻松解析和推理。

与 Copilot 的示例用法

使用此 MCP 的 Copilot 代理可以：

代理："当前正在发布哪些主题？"
[使用：list_ros_topics]

代理："让我观察 /cmd_vel 主题 5 秒钟"
[使用：monitor_topic，topic_name="/cmd_vel"，duration_seconds=5]
[等待 5 秒钟进行数据收集]

代理："以下是正在发送的速度命令：[解析后的数据]"

代理："给我展示所有节点是如何连接的"
[使用：generate_ros_graph，output_format="text"]

代理："让我尝试向 /cmd_vel 主题发布一条测试消息"
[使用：publish_to_topic]

代理："让我检查是否有节点出现问题"
[使用：check_ros_system_status，include_diagnostics=true]

局限性

一些 ROS 2 CLI 命令需要正确配置 ROS 2 环境。
TF2 监控需要安装 tf2_tools 包。
服务器在当前环境中执行命令，请确保正确安装了 ROS 2。
长时间运行的操作可能会超时，请根据需要调整持续时间参数。

未来增强功能

与 ROS 2 包记录/回放集成。
参数服务器监控。
动作客户端/服务器接口。
实时 rqt 插件集成。
Rviz2 数据流式传输。
自定义消息类型解析。
命令行界面（CLI）。

📄 许可证

MIT

贡献

欢迎贡献代码！请确保所有工具能够优雅地处理错误，并包含适当的参数验证。

ros-mcp