内容
# ros2-mcp
[](https://www.python.org/downloads/)
[](pyproject.toml)
[](LICENSE)
[](https://modelcontextprotocol.io)
[](https://github.com/mergeos-bounties)
**ros2-mcp** 是一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io) 服务器，使 AI 代理（Grok、Cursor、Claude 等）能够**检查和控制 ROS2** 图谱 — 主题、节点、服务、TF、动作 — 而无需手动编写每个 `ros2` 命令行调用。
**产品：** [mergeos-bounties/ros2-mcp](https://github.com/mergeos-bounties/ros2-mcp)
---
## 目录
- [模式](#模式)
- [亮点](#亮点)
- [截图](#截图)
- [快速入门](#快速入门)
- [命令行参考](#命令行参考)
- [MCP 主机配置](#mcp-主机配置)
- [图表](#图表)
- [存储库布局](#存储库布局)
- [开发](#开发)
- [MergeOS 悬赏计划](#mergeos-悬赏计划)
- [许可证](#许可证)
---
## 模式
| 模式 | 何时 | 行为 |
| --- | --- | --- |
| **模拟**（默认） | Windows / 持续集成 / 无 ROS2 安装 | 种子化的 turtlesim 类似图谱：主题、发布、回声、服务、TF、动作 |
| **实时** | 主机有 ROS2 + 命令行 | 通过 `ros2` 子进程桥接的真实图谱（日志中删除机密） |
---
## 亮点
| 功能 | 描述 |
| --- | --- |
| **离线演示** | `ros2-mcp demo` 演练医生、主题、发布/回声、生成、TF、动作 |
| **MCP 标准输入/输出服务** | 作为 MCP 服务器插入到代理主机 |
| **一次性调用** | `ros2-mcp call` 无需完整的 MCP 主机 |
| **工具列表** | 发现已注册的 MCP 工具 |
| **Lappa 友好** | 补充 [Lappa](https://github.com/mergeos-bounties/Lappa) 包 IDE 工作流程 |
---
## 截图
| 模拟图谱 | 发布 + 回声 |
| :---: | :---: |
|  |  |
| *种子图谱 / 医生* | *cmd_vel 发布 + pose 回声* |
---
## 快速入门
```powershell
cd ros2-mcp
python -m venv .venv
.\.venv\Scripts\activate
pip install -e ".[dev]"
ros2-mcp version
ros2-mcp demo
ros2-mcp tools list
```
模拟模式**不需要** ROS2 安装。
---
## 命令行参考
| 命令 | 目的 |
| --- | --- |
| `ros2-mcp version` | 版本 + 模式 |
| `ros2-mcp demo` | 核心后端 API 的离线测试 |
| `ros2-mcp serve` | 通过 **标准输入/输出** 的 MCP 服务器（用于主机） |
| `ros2-mcp call …` | 一次性工具调用（模拟/实时） |
| `ros2-mcp tools list` | 列出 MCP 工具 |
```powershell
# MCP for Cursor / Claude / Grok 兼容主机
ros2-mcp serve
```
---
## MCP 主机配置
stdio 服务器条目的示例（调整路径到您的虚拟环境）：
```json
{
"mcpServers": {
"ros2-mcp": {
"command": "ros2-mcp",
"args": ["serve"],
"env": {
"ROS2_MCP_MODE": "mock"
}
}
}
}
```
仅在具有有效 ROS2 环境的机器上设置 `ROS2_MCP_MODE=live`。
---
## 图表
系统架构和工作流程 — 全宽。打开 HTML 文件以获取**暗色/亮色主题**并导出（PNG/SVG）。
### 架构
[打开交互式图表](docs/diagrams/architecture.html)
<p align="center">
<img src="docs/diagrams/architecture.svg" alt="ros2-mcp 架构" width="100%" />
</p>
### 工作流程
[打开交互式图表](docs/diagrams/workflow.html)
<p align="center">
<img src="docs/diagrams/workflow.svg" alt="ros2-mcp 工作流程" width="100%" />
</p>
*使用 [archify](https://github.com/tt-a1i) 生成。*
---
## 存储库布局
```text
AI 代理（MCP 主机）
│ 标准输入/输出
▼
ros2-mcp 服务器
│
┌────┴────┐
│ 模拟 │ 种子图谱（持续集成 / Windows）
│ 实时 │ ros2 命令行子进程桥接
└─────────┘
src/ros2_mcp/
cli.py
backend/ # 模拟 + 实时后端
server.py # FastMCP 工具
docs/screenshots/
docs/diagrams/
```
---
## 开发
```powershell
pytest -q
ruff check src tests
ros2-mcp demo
```
实时模式测试应模拟子进程 — 持续集成**不要求** ROS2 发行版。
---
## MergeOS 悬赏计划
用于动作/TF、实时解析器、Lappa HTTP 桥、发布允许列表的工具。
星标 →认领 → PR **主分支** → 合并请求 **25–200**。证据：命令行日志 / MCP 主机配置代码片段（删除机密）。
---
## 越南语
**ros2-mcp** 使 AI 通过 MCP 控制 ROS2。离线：`ros2-mcp demo`（模拟）。实时：具有 ROS2 + `ROS2_MCP_MODE=live` 的机器。
---
## 许可证
MIT · MergeOS / ThanhTrucSolutions
