ros2_perception_mcp

ros2_perception_mcp ist ein dedizierter, schreibgeschützter MCP-Server für die begrenzte semantische Inspektion von ROS-2-Wahrnehmungssystemen.

Version 0.1.0 zielt auf:

• Ubuntu 24.04

• Python 3.12

• ROS 2 Jazzy

• MCP Python SDK 2.x

• stdio-Transport

Das Projekt ist bewusst als dedizierter Wahrnehmungs-MCP-Server konzipiert und nicht als generische ROS-2-Schnittstelle.

Aktueller Status

Der aktuelle Entwicklungsstand von v0.1.0 ist:

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

Phase 3A implementiert und verifiziert das herstellerneutrale Wahrnehmungs-Domänenmodell.

Fokussierte Phase-3A-Verifizierung:

12 passed

Das Projekt stellt bewusst noch keine Wahrnehmungs-MCP-Tools, Ressourcen, Prompts, ROS-Abonnements oder physischen Sensorintegrationen bereit. Diese Fähigkeiten werden erst in den entsprechenden Roadmap-Phasen eingeführt.

Architektur

Die vorgesehene Architektur ist:

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

Abhängigkeiten zeigen nach innen.

Die Domänen- und Anwendungsschichten bilden den herstellerneutralen semantischen Kern.

ROS-2-, MCP- und physische Sensorintegrationen bleiben Adapter um diesen Kern herum.

Die Domänenschicht darf nicht abhängen von:

• rclpy

• ROS-Nachrichtenpaketen

• tf2

• MCP-SDK-Typen

• RealSense-SDKs

• SLAMTEC-SDKs

• OpenCV

• gerätespezifischen APIs

Die RealSense D435i und der RPLIDAR A2M8 sind geplante physische Verifizierungsgeräte, keine Abhängigkeiten der öffentlichen API.

Umfang

ros2_perception_mcp besitzt die begrenzte semantische Inspektion von ROS-2-Wahrnehmungssystemen.

Der geplante Umfang von v0.1.0 umfasst:

• Sensorerkennung

• Stream-Erkennung

• semantische Sensormetadaten

• Stream-Metadaten

• Kamerametadaten

• aus CameraInfo abgeleitete Kalibrierungsmetadaten

• Tiefenmetadaten

• PointCloud2-Metadaten

• LaserScan-Metadaten

• Frame-Beziehungen

• Aktualitätsnachweise

• beobachtete Ratenachweise

• Sensor-Gesundheitsnachweise

• Diagnose

• explizit begrenzte Stichproben oder Schnappschüsse

Die MCP-Oberfläche soll semantische Wahrnehmungsoperationen bereitstellen, keine rohen uneingeschränkten ROS-Schnittstellen.

Explizite Grenzen

Version 0.1.0 wird nicht bereitstellen:

• willkürlichen ROS-Themenzugriff

• willkürliche ROS-Themenpublikation

• willkürliche ROS-Dienstaufrufe

• willkürliche ROS-Aktionsaufrufe

• Parameter-Mutation

• Prozessausführung

• Startausführung

• Shell-Befehle

• Kamera-Konfiguration

• LiDAR-Konfiguration

• LiDAR-Motorsteuerung

• Motorsteuerung

• Roboterbewegung

• Manipulatorbewegung

• uneingeschränkte Weiterleitung von Nutzlasten

• Vollraten-Bildstreaming

• Vollraten-Punktwolken-Streaming

Das Projekt ist schreibgeschützt.

Inspektion darf Geräte nicht konfigurieren oder eine Betätigung verursachen.

Verantwortungstrennung

Die ROS-2-MCP-Projekte haben bewusst getrennte Verantwortlichkeiten.

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

Generischer ROS-Zugriff gehört in ros2_mcp.

Steuerungssemantik gehört in ros2_control_mcp.

Manipulatorsemantik gehört in ros2_manipulator_mcp.

Wahrnehmungsspezifische semantische Inspektion gehört in ros2_perception_mcp.

Diese Trennung verhindert, dass die einzelnen MCP-Server zu uneingeschränkten universellen Roboterschnittstellen werden.

Außerhalb des Umfangs von v0.1.0

Die folgenden übergeordneten Wahrnehmungs- und Robotikfähigkeiten liegen explizit außerhalb des v0.1.0-Umfangs:

• Objekterkennung

• Segmentierung

• Pose-Schätzung

• SLAM

• Nav2

• MoveIt

• IMU-Unterstützung

Diese Fähigkeiten können in zukünftigen Architekturabeiten separat betrachtet werden, sind aber nicht Teil des aktuellen v0.1.0-Vertrags.

Phase 3A Domänenfundament

Phase 3A implementiert das reine Python-herstellerneutrale Wahrnehmungsdomänenmodell in:

src/ros2_perception_mcp/domain/

Die primäre Implementierung ist:

src/ros2_perception_mcp/domain/models.py

Die Domäne enthält derzeit:

• SensorDescriptor

• StreamDescriptor

• CameraDescriptor

• CameraIntrinsics

• DepthDescriptor

• PointCloudDescriptor

• PointCloudField

• LaserScanDescriptor

• FrameDescriptor

• FreshnessStatus

• SensorHealth

Zwei endliche anwendungseigene semantische Zustände werden mit Python 3.12 StrEnum dargestellt:

• FreshnessCategory

• HealthCategory

Offene Klassifikationen wie Sensorarten, Stream-Arten, Codierungen, Nachrichtenkategorien, Punktwolken-Datentypen und Frame-Bezeichner bleiben bewusst erweiterbare Zeichenfolgenwerte.

Domänen-Entwurfsprinzipien

Phase 3A folgt mehreren wichtigen Entwurfsregeln.

Herstellerneutral

Das Domänenverhalten hängt nicht von einer RealSense D435i, einem RPLIDAR A2M8 oder einem anderen spezifischen Gerät ab.

ROS-unabhängig

ROS-Nachrichten und rclpy-Objekte erscheinen nicht in der Domänen-API.

ROS-2-Jazzy-Adapter werden später ROS-Beobachtungen in semantische Domänenobjekte umwandeln.

MCP-unabhängig

Domänenmodelle enthalten keine MCP-SDK- oder Protokolltypen.

MCP ist ein externer Adapter um die Anwendungs- und Domänenschichten.

Unveränderlich

Domänenmodelle verwenden eingefrorene Datenklassen.

Sammlungen, die zu unveränderlichen Domänenwerten gehören, verwenden Tupel.

Unvollständige Metadaten sind darstellbar

Unbekannte Metadaten werden explizit dargestellt, nicht erfunden.

Zum Beispiel können Kameraauflösung, Tiefenbereiche, Kalibrierungsinformationen und Frame-Beziehungen gegebenenfalls None sein.

Nur strukturelle Validierung

Die Domäne validiert deterministische strukturelle Invarianten.

Sie erfindet nicht:

• Hardware-Grenzen

• Herstellergrenzen

• Aktualitätsschwellenwerte

• Ratenschwellenwerte

• physikalische Sicherheitsregeln

Aktualität und Gesundheit

Aktualität und Gesundheit sind nachweisorientiert.

FreshnessStatus repräsentiert:

• Beobachtungszeitpunkt

• Alter

• Nachweis

• optionale semantische Kategorie

Aktualitätsschwellenwerte sind nicht im Domänenmodell eingebettet.

Schwellenwertkonfiguration und Kategorieableitung gehören zu späteren Anwendungs- und Sicherheits-/Grenzarbeiten.

SensorHealth repräsentiert:

• Verfügbarkeit

• Aktualitätsnachweis

• Ratennachweis

• Ergebnisse

• semantische Gesundheitskategorie

Ein Gesundheitsergebnis ist keine Zertifizierung der physischen Sicherheit.

Der Server darf die Sensorgesundheit niemals als Autorisierung für Roboterbewegungen oder andere Betätigungen interpretieren.

Begrenzte Daten

Wahrnehmungssysteme können große kontinuierliche Datenströme erzeugen.

ros2_perception_mcp ist nicht dafür gedacht, diese Ströme uneingeschränkt an einen MCP-Client weiterzuleiten.

Die vorgesehene Architektur ist:

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

Der Zugriff auf Bild, Tiefe, Punktwolke und Laserscan muss explizit begrenzt bleiben.

Vollraten-Streaming liegt außerhalb des Umfangs von v0.1.0.

Geplante Hardware-Verifizierung

Zwei physische Sensoren sind für die spätere v0.1.0-Verifizierung geplant.

RealSense D435i

Geplant für:

Phase 14 - Real-hardware verification — RealSense D435i

Erwartete Verifizierungsbereiche umfassen Kamera, Tiefe, Kalibrierung, Stream-Metadaten, Frames, Aktualität und begrenzte Wahrnehmungsinspektion.

RPLIDAR A2M8

Geplant für:

Phase 15 - Real-hardware verification — RPLIDAR A2M8

Erwartete Verifizierungsbereiche umfassen Laserscan-Metadaten, Frames, Aktualität, Ratennachweise, Gesundheitsnachweise und begrenzte Scan-Inspektion.

Diese Geräte verifizieren die herstellerneutrale Architektur.

Sie definieren sie nicht.

Fundament-Server ausführen

Installieren/Synchronisieren der Projektumgebung:

uv sync

Aktuellen Fundament-Server ausführen:

uv run ros2-perception-mcp

Der Prozess wartet auf MCP JSON-RPC über die Standardeingabe.

Im aktuellen Entwicklungsstadium bewirbt er absichtlich keine MCP-Wahrnehmungsfähigkeiten.

Setzen Sie:

ROS2_PERCEPTION_MCP_CONFIG

um eine alternative TOML-Konfigurationsdatei auszuwählen.

Entwicklungstests

pytest wird als Entwicklungsabhängigkeit gepflegt.

Die fokussierten Phase-3A-Domänentests können ausgeführt werden mit:

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

Verifiziertes Phase-3A-Ergebnis:

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

Das automatische Laden von Drittanbieter-pytest-Plugins ist für diesen fokussierten Domänentest deaktiviert, da eine ROS-2-Jazzy-Umgebung nicht verwandte ROS-Test-Plugins wie launch_testing bereitstellen kann.

ROS-spezifisches Testen wird explizit in den entsprechenden späteren Phasen eingeführt.

Projekt-Roadmap

Die v0.1.0-Roadmap ist:

1. Projektfundament — ABGESCHLOSSEN

2. Architektur und Umfang — ABGESCHLOSSEN

3. Domänenmodelle und Anwendungsports — IN BEARBEITUNG

   • Phase 3A - Domänenmodelle — ABGESCHLOSSEN

   • Phase 3B - Anwendungsports und Dienstgrenze — ALS NÄCHSTES

4. ROS 2 Jazzy-Adapterfundament

5. Sensorerkennung und -inspektion

6. Kamera / Bild / CameraInfo

7. Tiefe

8. PointCloud2

9. LaserScan

10. TF / Frames / Aktualität / Rate / Gesundheit

11. MCP-Tools / Ressourcen / Prompts

12. Sicherheitsgrenzen und Diagnose

13. Fokussierte Softwareverifizierung

14. Echthardware-Verifizierung — RealSense D435i

15. Echthardware-Verifizierung — RPLIDAR A2M8

16. Abschließendes Audit, Dokumentation und v0.1.0-Release-Bereitschaft

Jede Phase erfordert einen expliziten Umfang und muss die schreibgeschützte, begrenzte, herstellerneutrale Architektur bewahren.

Dokumentation

Detaillierte Entwicklungsaufzeichnungen werden geführt in:

• Phasen-Roadmap

• Phase 1 - Projektfundament

• Phase 2 - Architektur und Umfang

• Phase 3 - Domänenmodelle und Anwendungsports

Die Phasendokumente sollen nicht nur den Implementierungsfortschritt, sondern auch Architekturentscheidungen, explizite Ausschlüsse, Validierungsergebnisse und Verantwortungsgrenzen festhalten.

Versionsannahmen

Das Projekt zielt derzeit auf:

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

ROS-Python-Pakete bleiben Systemabhängigkeiten und werden bewusst von der herstellerneutralen Domänenschicht getrennt.

Die ROS-Nachrichtensemantik wird während der ROS-Adapter- und sensorspezifischen Implementierungsphasen gegen installierte und offizielle ROS-2-Jazzy-Definitionen verifiziert.

RealSense- und SLAMTEC-Treiberversionen und -Konventionen bleiben bis zu ihren entsprechenden Integrations- und Hardware-Verifizierungsphasen zurückgestellt.

Nächster Schritt

Der nächste Entwicklungsschritt ist:

Phase 3B - Application ports and service boundary

Phase 3B wird die minimalen semantischen Anwendungsverträge definieren, die von späteren ROS-2-Jazzy-Adaptern benötigt werden.

Sie muss die Abhängigkeitsrichtung bewahren:

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

Phase 3B darf keine ROS-Abonnements, Hardwarezugriff, MCP-Wahrnehmungstools, Gerätekonfiguration oder Betätigung einführen.