ROS 2 Workspace Inspector

ROS 2 Workspace Inspector MCP

English | 简体中文

ROS 2 Workspace Inspector MCP は、Codex、Claude Code、Cursor などの MCP クライアントに ROS 2 ワークスペースの構造化情報を提供する、ローカル優先かつ読み取り専用の静的解析 MCP サーバーです。7 つの静的解析ツールが、ROS 2 を必要とせずに、パッケージの検出、構成、依存関係、インターフェース、launch ファイル、ロボット記述ファイル、および対象を限定したワークスペース診断をカバーします。また、簡潔な読み取り専用リソースを 2 つと、ガイド付きレビュー用プロンプトを 1 つ提供します。

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

このプロジェクトが検査するのはファイルのみです。ロボットの制御、ROS ノードの実行、ワークスペースのビルド、launch ファイルや Xacro ファイルの実行、setup.py の実行、トピックのパブリッシュ、サービスやアクションの呼び出し、ユーザーファイルの変更は行いません。すべてのアクセスは、設定されたルートのサンドボックス内に限定されます。stdio のみをサポートします。

ツール

• scan_workspace — ROS 2 パッケージ、ワークスペースの構成、ビルドタイプ、基本的なマニフェストメタデータを検出します。
• inspect_package — パッケージのマニフェスト、ビルド設定、実行可能ファイル、launch ファイル、インターフェース、ロボット記述ファイル、テストを検査します。
• analyze_dependencies — パッケージの依存関係、内部の依存エッジ、トポロジカル順序、依存関係の循環を解析します。
• inspect_interfaces — ROS 2 の Msg、Srv、Action インターフェース定義を解析して検査します。
• analyze_launch_file — Python、XML、YAML の ROS 2 launch ファイルを実行せずに静的解析します。
• 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

このプロセスは MCP プロトコルを使用して stdout 経由で通信します。通常のログを 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".

利用可能なツール

サーバーが公開するツールは、次の 7 つです。

1. scan_workspace — パッケージと基本的なメタデータを検出します。
2. inspect_package — 1 つのパッケージのマニフェスト、ビルドファイル、実行可能ファイル、ファイル構成を検査します。
3. analyze_dependencies — 宣言を解析し、ワークスペースの依存関係グラフを構築します。
4. inspect_interfaces — 1 つのパッケージの .msg、.srv、.action ファイルを解析します。
5. analyze_launch_file — 1 つの Python、XML、YAML launch ファイルを静的解析します。
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") は、プロンプトの生成時にワークスペースを読み取ることなく、7 つのツールを使用して、簡易、標準、または詳細なレビューを行うよう案内します。

リソースは読み取り時に生成され、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 を参照してください。