ros2_perception_mcp

ros2_perception_mcp は、ROS 2 認識システムの境界を定めた意味論的検査のための、専用の読み取り専用優先 MCP サーバーです。

バージョン 0.1.0 のターゲット:

• Ubuntu 24.04

• Python 3.12

• ROS 2 Jazzy

• MCP Python SDK 2.x

• stdio トランスポート

このプロジェクトは、汎用的な ROS 2 インターフェースではなく、専用の認識 MCP サーバーとして意図的に設計されています。

現在のステータス

現在の v0.1.0 開発ステータスは以下の通りです:

Phase 1  - Project foundation                         COMPLETE
Phase 2  - Architecture and scope                     COMPLETE
Phase 3A - Domain models                              COMPLETE
Phase 3B - Application ports and service boundary     NEXT
Phase 3  - Domain models and application ports        IN PROGRESS

フェーズ 3A は、ベンダーニュートラルな認識ドメインモデルを実装し、検証します。

焦点を絞ったフェーズ 3A の検証:

12 passed

このプロジェクトは、まだ認識 MCP ツール、リソース、プロンプト、ROS サブスクリプション、または物理センサー統合を意図的に公開していません。これらの機能は、対応するロードマップフェーズでのみ導入されます。

アーキテクチャ

意図されたアーキテクチャは以下の通りです:

MCP Client
    |
    | stdio
    v
MCP Server
    |
    v
Semantic Perception MCP Surface
    |
    v
PerceptionService
    |
    +--------------------+
    |                    |
    v                    v
Domain Models      Safety / Bounds
    ^
    |
Application Ports
    ^
    |
RosPerceptionAdapter
    ^
    |
JazzyRosPerceptionAdapter
    |
    v
ROS 2 Jazzy
    |
    +----------------------+
    |                      |
    v                      v
RealSense D435i       RPLIDAR A2M8
verification          verification

依存関係は内側を向いています。

ドメイン層とアプリケーション層が、ベンダーニュートラルな意味論的コアを形成します。

ROS 2、MCP、および物理センサー統合は、そのコアの周りのアダプターとして残ります。

ドメイン層は以下に依存してはなりません:

• rclpy

• ROS メッセージパッケージ

• tf2

• MCP SDK 型

• RealSense SDK

• SLAMTEC SDK

• OpenCV

• デバイス固有の API

RealSense D435i と RPLIDAR A2M8 は、計画された物理検証デバイスであり、公開 API の依存関係ではありません。

スコープ

ros2_perception_mcp は、ROS 2 認識システムの境界を定めた意味論的検査を担当します。

計画された v0.1.0 のスコープには以下が含まれます:

• センサー検出

• ストリーム検出

• 意味論的センサーメタデータ

• ストリームメタデータ

• カメラメタデータ

• CameraInfo から派生したキャリブレーションメタデータ

• 深度メタデータ

• PointCloud2 メタデータ

• LaserScan メタデータ

• フレーム関係

• 鮮度エビデンス

• 観測レートエビデンス

• センサーヘルスエビデンス

• 診断

• 明示的に境界を定められたサンプルまたはスナップショット

MCP サーフェスは、生の無制限の ROS インターフェースではなく、意味論的な認識操作を公開することを意図しています。

明示的な境界

バージョン 0.1.0 は以下を公開しません:

• 任意の ROS トピックへのアクセス

• 任意の ROS トピックへのパブリッシュ

• 任意の ROS サービスコール

• 任意の ROS アクションコール

• パラメータ変更

• プロセス実行

• 起動実行

• シェルコマンド

• カメラ設定

• LiDAR 設定

• LiDAR モーター制御

• モーター制御

• ロボット移動

• マニピュレーター移動

• 無制限のペイロード転送

• フルレートの画像ストリーミング

• フルレートの点群ストリーミング

このプロジェクトは読み取り専用優先です。

検査はデバイスを設定したり、動作を引き起こしたりしてはなりません。

責任分離

ROS 2 MCP プロジェクトは、意図的に異なる責任を持ちます。

ros2_mcp
    -> generic bounded ROS 2 inspection

ros2_control_mcp
    -> ros2_control semantics

ros2_manipulator_mcp
    -> manipulator-specific semantics

ros2_perception_mcp
    -> perception and sensor semantics

汎用的な ROS アクセスは ros2_mcp に属します。

制御セマンティクスは ros2_control_mcp に属します。

マニピュレーターセマンティクスは ros2_manipulator_mcp に属します。

認識固有の意味論的検査は ros2_perception_mcp に属します。

この分離により、個々の MCP サーバーが無制限の汎用ロボットインターフェースになることを防ぎます。

v0.1.0 のスコープ外

以下の高レベルの認識およびロボット機能は、明示的に v0.1.0 のスコープ外です:

• 物体検出

• セグメンテーション

• 姿勢推定

• SLAM

• Nav2

• MoveIt

• IMU サポート

これらの機能は、将来のアーキテクチャ作業で個別に検討される可能性がありますが、現在の v0.1.0 契約の一部ではありません。

フェーズ 3A ドメイン基盤

フェーズ 3A は、純粋な Python のベンダーニュートラルな認識ドメインを以下に実装します:

src/ros2_perception_mcp/domain/

主要な実装は以下の通りです:

src/ros2_perception_mcp/domain/models.py

ドメインには現在以下が含まれています:

• SensorDescriptor

• StreamDescriptor

• CameraDescriptor

• CameraIntrinsics

• DepthDescriptor

• PointCloudDescriptor

• PointCloudField

• LaserScanDescriptor

• FrameDescriptor

• FreshnessStatus

• SensorHealth

2 つの有限なアプリケーション所有の意味論的状態は、Python 3.12 の StrEnum を使用して表現されます:

• FreshnessCategory

• HealthCategory

センサーの種類、ストリームの種類、エンコーディング、メッセージカテゴリ、点群データ型、フレーム識別子などのオープンエンドな分類は、意図的に拡張可能な文字列値のままです。

ドメイン設計原則

フェーズ 3A は、いくつかの重要な設計ルールに従います。

ベンダーニュートラル

ドメインの動作は、RealSense D435i、RPLIDAR A2M8、またはその他の特定のデバイスに依存しません。

ROS 非依存

ROS メッセージと rclpy オブジェクトは、ドメイン API に登場しません。

ROS 2 Jazzy アダプターは、後で ROS 観測を意味論的ドメインオブジェクトに変換します。

MCP 非依存

ドメインモデルには、MCP SDK またはプロトコル型は含まれません。

MCP は、アプリケーション層とドメイン層の外部アダプターです。

不変

ドメインモデルは、凍結されたデータクラスを使用します。

不変のドメイン値に属するコレクションは、タプルを使用します。

不完全なメタデータは表現可能

未知のメタデータは、捏造されるのではなく、明示的に表現されます。

例えば、カメラ解像度、深度範囲、キャリブレーション情報、フレーム関係は、適切な場合に None になる可能性があります。

構造的検証のみ

ドメインは、決定論的な構造的不変条件を検証します。

以下を発明しません:

• ハードウェア制限

• ベンダー制限

• 鮮度しきい値

• レートしきい値

• 物理的安全ルール

鮮度とヘルス

鮮度とヘルスはエビデンス指向です。

FreshnessStatus は以下を表します:

• 観測時刻

• 経過時間

• エビデンス

• オプションの意味論的カテゴリ

鮮度しきい値はドメインモデルに埋め込まれていません。

しきい値の設定とカテゴリの導出は、後のアプリケーションおよびセーフティ/バウンド作業に属します。

SensorHealth は以下を表します:

• 可用性

• 鮮度エビデンス

• レートエビデンス

• 所見

• 意味論的ヘルスカテゴリ

ヘルス結果は、物理的安全認証ではありません。

サーバーは、センサーヘルスをロボットの移動やその他の動作の許可として決して解釈してはなりません。

境界を定められたデータ

認識システムは、大規模な連続データストリームを生成する可能性があります。

ros2_perception_mcp は、それらのストリームを無制限に MCP クライアントに転送することを意図していません。

意図されたアーキテクチャは以下の通りです:

Continuous ROS 2 perception stream
                |
                v
         ROS adapter observes
                |
                v
     Semantic metadata or
        bounded sample
                |
                v
          MCP response

画像、深度、点群、レーザースキャンへのアクセスは、明示的に境界を定められなければなりません。

フルレートのストリーミングは v0.1.0 のスコープ外です。

計画されたハードウェア検証

2 つの物理センサーが、後の v0.1.0 検証のために計画されています。

RealSense D435i

以下に計画されています:

Phase 14 - Real-hardware verification — RealSense D435i

期待される検証領域には、カメラ、深度、キャリブレーション、ストリームメタデータ、フレーム、鮮度、および境界を定められた認識検査が含まれます。

RPLIDAR A2M8

以下に計画されています:

Phase 15 - Real-hardware verification — RPLIDAR A2M8

期待される検証領域には、レーザースキャンメタデータ、フレーム、鮮度、レートエビデンス、ヘルスエビデンス、および境界を定められたスキャン検査が含まれます。

これらのデバイスは、ベンダーニュートラルなアーキテクチャを検証します。

それらはそれを定義するものではありません。

基盤サーバーの実行

プロジェクト環境をインストール/同期します:

uv sync

現在の基盤サーバーを実行します:

uv run ros2-perception-mcp

プロセスは、標準入力で MCP JSON-RPC を待機します。

現在の開発段階では、認識 MCP 機能を意図的に宣伝しません。

以下を設定:

ROS2_PERCEPTION_MCP_CONFIG

して、代替の TOML 設定ファイルを選択します。

開発テスト

pytest は開発依存関係として維持されています。

焦点を絞ったフェーズ 3A ドメインテストは、以下で実行できます:

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 \
uv run python -m pytest -q tests/test_domain_models.py

検証されたフェーズ 3A の結果:

............                                                             [100%]
12 passed in 0.01s

この焦点を絞ったドメインテストでは、ROS 2 Jazzy 環境が launch_testing などの無関係な ROS テストプラグインを公開する可能性があるため、サードパーティの pytest プラグインの自動ロードは無効になっています。

ROS 固有のテストは、対応する後のフェーズで明示的に導入されます。

プロジェクトロードマップ

v0.1.0 のロードマップは以下の通りです:

1. プロジェクト基盤 — 完了

2. アーキテクチャとスコープ — 完了

3. ドメインモデルとアプリケーションポート — 進行中

   • フェーズ 3A - ドメインモデル — 完了

   • フェーズ 3B - アプリケーションポートとサービス境界 — 次

4. ROS 2 Jazzy アダプター基盤

5. センサー検出と検査

6. カメラ / 画像 / CameraInfo

7. 深度

8. PointCloud2

9. LaserScan

10. TF / フレーム / 鮮度 / レート / ヘルス

11. MCP ツール / リソース / プロンプト

12. セーフティバウンドと診断

13. 焦点を絞ったソフトウェア検証

14. 実ハードウェア検証 — RealSense D435i

15. 実ハードウェア検証 — RPLIDAR A2M8

16. 最終監査、ドキュメント、および v0.1.0 リリース準備

各フェーズは明示的なスコープを必要とし、読み取り専用、境界を定められた、ベンダーニュートラルなアーキテクチャを維持しなければなりません。

ドキュメント

詳細な開発記録は以下に維持されています:

• フェーズロードマップ

• フェーズ 1 - プロジェクト基盤

• フェーズ 2 - アーキテクチャとスコープ

• フェーズ 3 - ドメインモデルとアプリケーションポート

フェーズドキュメントは、実装の進捗だけでなく、アーキテクチャ上の決定、明示的な除外、検証結果、責任境界を記録することを意図しています。

バージョン前提

プロジェクトは現在以下をターゲットにしています:

Ubuntu             24.04
Python             3.12
ROS 2              Jazzy
MCP Python SDK     2.x
MCP transport      stdio

ROS Python パッケージはシステム依存関係のままであり、ベンダーニュートラルなドメイン層から意図的に分離されています。

ROS メッセージセマンティクスは、ROS アダプターおよびセンサー固有の実装フェーズ中に、インストールされた公式の ROS 2 Jazzy 定義に対して検証されます。

RealSense および SLAMTEC ドライバーのバージョンと規約は、対応する統合およびハードウェア検証フェーズまで延期されます。

次のステップ

次の開発ステップは以下の通りです:

Phase 3B - Application ports and service boundary

フェーズ 3B は、後の ROS 2 Jazzy アダプターが必要とする最小限の意味論的アプリケーション契約を定義します。

依存関係の方向を維持しなければなりません:

MCP Adapter
     |
     v
Application Layer
     |
     v
Domain Layer
     ^
     |
ROS 2 Adapter

フェーズ 3B は、ROS サブスクリプション、ハードウェアアクセス、MCP 認識ツール、デバイス設定、または動作を導入してはなりません。