ROS 2 Workspace Inspector

ROS 2 Workspace Inspector MCP

English | 简体中文

ROS 2 Workspace Inspector MCP 是一个本地优先、只读的静态分析 MCP 服务，可为 Codex、Claude Code、Cursor 和其他 MCP 客户端提供 ROS 2 工作区的结构化信息。七种静态分析工具涵盖发现、软件包结构、依赖关系、接口、启动文件、机器人描述和有限范围的工作区诊断，无需 ROS 2。它还提供两个简洁的只读资源和一个引导式审查提示词。

7 analysis tools · 2 read-only resource forms · 1 guided review prompt

本项目只检查文件，不会控制机器人、运行 ROS 节点、构建工作区、执行启动文件或 Xacro 文件、执行 setup.py、发布话题、调用服务或动作，也不会修改用户文件。所有访问都限制在配置的根目录沙盒内。仅支持 stdio。

工具

• scan_workspace — 发现 ROS 2 软件包、工作区布局、构建类型和基本清单元数据。
• inspect_package — 检查软件包的清单、构建配置、可执行文件、启动文件、接口、机器人描述和测试。
• analyze_dependencies — 分析软件包依赖、内部依赖关系、有向无环顺序和依赖循环。
• inspect_interfaces — 解析并检查 ROS 2 Msg、Srv 和 Action 接口定义。
• analyze_launch_file — 静态分析 Python、XML 或 YAML ROS 2 启动文件，不执行该文件。
• inspect_robot_description — 检查 URDF 结构，并对 Xacro 文件进行静态摘要，不展开或执行这些文件。
• diagnose_workspace — 对配置的 ROS 2 工作区执行整合式、有限范围的诊断。

要求和安装

• Python 3.10 或更高版本
• uv

克隆仓库并进入其中，然后创建锁定的环境：

git clone https://github.com/doer0312/ros2-workspace-mcp.git
cd ros2-workspace-mcp
uv sync --locked

针对本地工作区运行：

uv run ros2-workspace-mcp --root /absolute/path/to/your/ros2_ws

等效的模块入口为：

uv run python -m ros2_workspace_mcp --root /absolute/path/to/your/ros2_ws

进程通过 stdout 使用 MCP 协议通信。不要将普通日志重定向到 stdout。无效的 CLI 输入会报告到 stderr，并返回非零退出状态。

客户端配置

Codex TOML：

[mcp_servers.ros2-workspace-inspector]
command = "uv"
args = ["--directory", "/absolute/path/to/ros2-workspace-mcp", "run", "ros2-workspace-mcp", "--root", "/absolute/path/to/your/ros2_ws"]

Claude Desktop JSON：

{
  "mcpServers": {
    "ros2-workspace-inspector": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/ros2-workspace-mcp", "run", "ros2-workspace-mcp", "--root", "/absolute/path/to/your/ros2_ws"]
    }
  }
}

可在 examples/client-configs/ 中获取可复制的配置。两个示例都会运行检出的仓库环境，不依赖 PyPI 发布版本。

尝试使用附带的静态演示，无需安装 ROS：

uv run ros2-workspace-mcp --root ./examples/demo_ws

最小请求：

Scan the configured ROS 2 workspace and summarize its packages.

引导式审查示例：

Use review_ros2_workspace with depth="standard".

可用工具

该服务恰好提供七种工具：

1. scan_workspace — 发现软件包和基本元数据。
2. inspect_package — 检查单个软件包的清单、构建文件、可执行文件和文件布局。
3. analyze_dependencies — 解析依赖声明并构建工作区依赖图。
4. inspect_interfaces — 解析单个软件包的 .msg、.srv 和 .action 文件。
5. analyze_launch_file — 静态分析单个 Python、XML 或 YAML 启动文件。
6. inspect_robot_description — 验证 URDF，或对尚未展开的 Xacro 进行摘要。
7. diagnose_workspace — 对整个工作区执行有限范围、去重后的诊断。

请求示例：

Use scan_workspace to inspect the configured ROS 2 workspace.
Inspect the package named demo_robot.
Analyze src/demo_robot/launch/demo.launch.py without running it.
Diagnose the configured workspace.

scan_workspace 不接受参数，只扫描通过 --root 提供的工作区。简洁的结果如下所示：

{
  "layout": "colcon_workspace",
  "package_count": 1,
  "packages": [
    {
      "name": "demo_pkg",
      "relative_path": "src/demo_pkg",
      "build_type": "ament_python",
      "build_type_source": "inferred",
      "valid": true
    }
  ],
  "issues": []
}

完整结果还包含服务身份、规范化的根目录和扫描路径、软件包元数据、有效／无效数量、重复名称和结构化问题。请参阅 docs/tools.md。

资源和提示词

• ros2-workspace://summary 是固定的精简工作区摘要。
• ros2-workspace://package/{package_name} 是一个软件包上下文模板，具有严格的名称验证和歧义错误处理。
• review_ros2_workspace(focus="", depth="standard") 使用七个工具引导快速、标准或深入审查，且生成提示词时不会读取工作区。

资源在读取时生成，MIME 类型为 application/json，绝不返回原始项目文件。该服务有意不提供任意文件资源、订阅、通知或文件系统监视功能。客户端应用程序可能会以不同方式显示资源和提示词。请参阅 docs/resources.md 和 docs/prompts.md。

安全边界

该服务绑定到一个经过验证的规范工作区目录。读取的每个文件都会通过路径包含关系而非字符串前缀进行解析和检查。绝不遍历目录符号链接；可读取的文件符号链接必须指向根目录内。文本读取采用 UTF-8，设有大小限制，并集中处理。Python 使用 AST 解析，XML 使用 ElementTree 解析，YAML 使用 safe_load 解析；绝不执行 setup、launch、Xacro、CMake 和进程声明。完整的安全边界请参阅 docs/security.md。

开发

uv run ruff check .
uv run ruff format --check .
uv run pytest

更多文档：

• 工具
• 资源
• 提示词
• 架构
• 安全边界

许可证

基于 Apache License 2.0 授权。请参阅 LICENSE。