内容
ROS 工作空间检查器 MCPLicense: Apache-2..shields.io/badge-Apache--2.0-blue.svg)](LICENSE)
[](py)
[](https://github.com/doer0312/ros2-workspace-mcp/actions/workflows/ci.yml)
[English](README.md) | [简体中文](README.zh-CN.md)
ROS 2 工作空间检查器 MCP 是一个本地优先、只读的静态分析 MCP 服务器，为 Codex、Claude Code、Cursor 等 MCP 客户端提供 ROS 2 工作空间的结构化信息。七种静态分析工具涵盖了发现、软件包结构、依赖关系、接口、启动文件、机器人描述和有界工作空间诊断，无需 ROS 2还提供了两种紧凑的只读资源和一种引导式审查提示。
```text
7 种分析工具 · 2 种只读资源表单 · 1 种引导式审查提示
```
该项目仅检查文件。它不控制机器人、不运行 ROS 节点、不构建工作空间、不执行启动或 Xacro 文件、不执行 `setup.py`、不发布调用服务或动作、不修改用户文件。所有访问都停留在配置的根沙盒内。仅支持标准输入/输出。
## 工具
- `scan_workspace` — 发现 ROS 2 软件包、工作空间布局、构建类型和基本清单元数据。
- `inspect_package` — 检查软件包的清单、构建配置、可执行文件、启动文件、接口、机器人描述和测试。
- `analyze_dependencies` — 分析软件包依赖关系、内部依赖关系边、拓扑顺序和依赖关系循环。
- `inspect_interfaces` — 解析和检查 ROS 2 Msg、Srv 接口定义。
- `analyze_launch_file` — 在 Python、XML 或 YAML ROS 2 启动文件的情况下进行静态分析。
- `inspect_robot_description` — 检查 URDF 结构并在不扩展或执行 Xacro 文件的情况下进行静态汇总。
- `diagnose_workspace` — 对配置的 ROS 2 工作空间进行综合、有界的诊断。
## 需求和安装
- Python 3.10 或更高版本
- [`uv`](https://docs.astral.sh/uv/)
克隆仓库，进入并创建锁定环境：
```bash
git clone https://github.com/doer0312/ros2-workspace-mcp.git
cd ros2-workspace-mcp
uv sync --locked
```
针对本地工作空间运行：
```bash
uv2-workspace-mcp /absolute/path/to/your/ros2_ws
```
等效的模块入口点是：
```bash
uv run python -m ros2_workspace_mcp --root /absolute/path/to/your/ros2_ws
```
该进程通过 stdout 使用 MCP 协议通信。不要将普通日志重定向到 stdout。无效的会通过 stderr 以非零退出状态报告。
## 客户端配置
Codex TOML:
```tomlcp_servers.ros2-workspace-inspector]
"uv"
args = ["--directory", "/absolute/path2-workspace-mcp", "run",2-workspace-mcp", "--root", "/absolute/path/to/your/ros2```
Claude Desktop JSON:
```json
{
"mcpServers": {
"ros2-workspace-inspector": {
" "uv",
"args": ["--directory", "/absolute/path/to/ros2-workspace-mcp", " "ros2-workspace-mcp", "--rootabsolute/path/to/your/ros2_ws"]
}
}
}
```
可在 `examples/client-configs/` 下复制的版本。都运行已检出的，不假设 PyPI 发布。
在不安装 ROS，尝试包含的静态演示：
```bash run ros2-workspace-mcp --root ./examples/demo_ws
```
最小请求：
```text
扫描配置的 ROS 2 工作空间并总结其软件包。
```
引导式审查示例：
```text
使用 review_ros2_workspace，深度为 "standard"。
```
## 可用工具
服务器暴露了恰好七种工具：
1. `scan_workspace` — 发现软件包和基本元数据。
2. `inspect_package` — 检查一个软件包的清单、构建文件、可执行文件布局。
3. `analyze_dependencies` — 解析声明并构建工作空间依赖关系图。
4. `inspect_interfaces` — 解析一个软件包的 `.msg`、` 和 `.action` 文件。
5. `_file` — 静态分析一个 Python、XML 或 YAML 启动6. `inspect_robot_description` — 验证 URDF 或汇总未 Xacro。
7. `diagnose_workspace` — 运行一个有界的、去重的空间诊断。
示例请求：
```text
使用 scan_workspace 检查配置的 ROS 2 工作检查名为 demo_robot 的软件包。
分析 src/demo_robot/launch/demo.launch.py 而不运行它。
诊断配置的工作空间。
```
`scan_workspace` 不带参数，仅扫描使用 `--root` 空间。紧凑的结果如下：
```json
{
"layoutcolcon_workspace "package_count": 1,
"packages": [
{
"name": "demo "relative_path":/demo_pkg",
"": "ament_python",
"_source": "in "valid": true
}
],
"issues}
```
完整结果还包括服务器标识、规范根路径路径、软件包元数据/无效计数、重复结构化问题。参见/tools.md`](docs/tools## 资源和提示
-2-workspace://summary固定的紧凑工作空间摘要。
- `ros2-workpackage/{package_name}`包上下文模板，具有严格的名称验证义错误。
-_ros2_workspace(focus="standard")` 使用七种工具在生成提示时引导快速、标准或深入的审查读取工作空间。
资源生成，具有 `application/json` MIME 类型，永远不会返回文件。服务器故意不暴露任意文件资源、订阅、文件系统监视。客户端应用程序可以以不同的方式显示资源和提示。参见 [`docs/resources.md`](docs/resources.md) 和/prompts.md`](docs/prompts.md)。
## 安全边界
服务器绑定到一个已验证的、规范的工作空间目录。每个选定的文件都经过路径包含解析和检查，而不是字符串前缀。目录符号链接永远不会被遍历；可读的文件符号链接必须在根目录内解析。文本读取是 UTF-8、有限大小和集中的。Python 使用 AST 解析，XML 使用 `ElementTree`，YAML 使用 `safe_load设置、启动、Xacro、CMake 和进程声明永远不会被执行。参见 [`.md`](docs/security.md获取完整的安全边界。
```bash
uvuff check .
uv run r --check .
uv run```
更多文档：
工具](docs/tools.md)
- [资源](docs/resources- [提示](docs/prompts.md)
- [架构](docs/architecture.md)
- [](docs/security.md)
许可证
根据 Apache License.0 许可。参见 `LICENSE`。
