Ros MCP

🚀 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 工具的命令。

工作原理

1. 命令執行：每個工具執行相應的 ros2 CLI 命令。
2. 輸出解析：解析結果並將其格式化為適合代理使用的形式。
3. 超時處理：觀測工具使用可配置的超時來收集數據。
4. 錯誤處理：失敗的命令會優雅地返回錯誤消息。

為代理觀測設計工具

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

1. 阻塞觀測操作：像 monitor_topic 這樣的工具會在指定的時間段內阻塞，允許代理自然地等待結果。
2. 有界時間窗口：所有監控工具都有最大持續時間（通常為 5 - 30 秒），以防止無限等待。
3. 漸進式數據收集：工具逐步收集數據，並在觀測窗口結束時返回結果。
4. 清晰的輸出格式：結果是結構化的文本，代理可以輕鬆解析和推理。

與 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

貢獻

歡迎貢獻代碼！請確保所有工具能夠優雅地處理錯誤，幷包含適當的參數驗證。