ros2_perception_mcp

ros2_perception_mcp es un servidor MCP dedicado, de solo lectura en primera instancia, para la inspección semántica acotada de sistemas de percepción ROS 2.

La versión 0.1.0 está dirigida a:

• Ubuntu 24.04

• Python 3.12

• ROS 2 Jazzy

• MCP Python SDK 2.x

• Transporte stdio

El proyecto está diseñado intencionadamente como un servidor MCP de percepción dedicado, en lugar de una interfaz ROS 2 genérica.

Estado actual

El estado actual de desarrollo de la v0.1.0 es:

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

La fase 3A implementa y verifica el modelo de dominio de percepción independiente del proveedor.

Verificación enfocada de la fase 3A:

12 passed

El proyecto aún no expone intencionadamente herramientas, recursos, indicaciones, suscripciones ROS ni integraciones de sensores físicos de percepción MCP. Estas capacidades se introducen solo en las fases correspondientes de la hoja de ruta.

Arquitectura

La arquitectura prevista es:

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

Las dependencias apuntan hacia adentro.

Las capas de dominio y aplicación forman el núcleo semántico independiente del proveedor.

Las integraciones de ROS 2, MCP y sensores físicos siguen siendo adaptadores alrededor de ese núcleo.

La capa de dominio no debe depender de:

• rclpy

• Paquetes de mensajes ROS

• tf2

• Tipos del SDK de MCP

• SDK de RealSense

• SDK de SLAMTEC

• OpenCV

• APIs específicas de dispositivos

Los dispositivos RealSense D435i y RPLIDAR A2M8 son dispositivos de verificación física planificados, no dependencias de API pública.

Alcance

ros2_perception_mcp posee la inspección semántica acotada de sistemas de percepción ROS 2.

El alcance planificado de la v0.1.0 incluye:

• descubrimiento de sensores

• descubrimiento de flujos

• metadatos semánticos de sensores

• metadatos de flujo

• metadatos de cámara

• metadatos de calibración derivados de CameraInfo

• metadatos de profundidad

• metadatos de PointCloud2

• metadatos de LaserScan

• relaciones de marcos

• evidencia de frescura

• evidencia de tasa observada

• evidencia de salud del sensor

• diagnósticos

• muestras o instantáneas explícitamente acotadas

La superficie MCP está destinada a exponer operaciones de percepción semántica en lugar de interfaces ROS brutas sin restricciones.

Límites explícitos

La versión 0.1.0 no expondrá:

• acceso arbitrario a temas ROS

• publicación arbitraria en temas ROS

• llamadas arbitrarias a servicios ROS

• llamadas arbitrarias a acciones ROS

• mutación de parámetros

• ejecución de procesos

• ejecución de lanzamientos

• comandos de shell

• configuración de cámara

• configuración de LiDAR

• control de motor de LiDAR

• control de motor

• movimiento de robot

• movimiento de manipulador

• reenvío de carga útil sin restricciones

• transmisión de imágenes a velocidad completa

• transmisión de nubes de puntos a velocidad completa

El proyecto es de solo lectura en primera instancia.

La inspección no debe configurar dispositivos ni provocar actuación.

Separación de responsabilidades

Los proyectos MCP de ROS 2 tienen intencionadamente responsabilidades separadas.

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

El acceso genérico a ROS pertenece a ros2_mcp.

Las semánticas de control pertenecen a ros2_control_mcp.

Las semánticas de manipulador pertenecen a ros2_manipulator_mcp.

La inspección semántica específica de percepción pertenece a ros2_perception_mcp.

Esta separación evita que los servidores MCP individuales se conviertan en interfaces de robot de propósito general sin límites.

Fuera del alcance de la v0.1.0

Las siguientes capacidades de percepción y robótica de nivel superior están explícitamente fuera del alcance de la v0.1.0:

• detección de objetos

• segmentación

• estimación de pose

• SLAM

• Nav2

• MoveIt

• soporte de IMU

Estas capacidades pueden considerarse por separado en trabajos de arquitectura futuros, pero no forman parte del contrato actual de la v0.1.0.

Fundamento de dominio de la fase 3A

La fase 3A implementa el dominio de percepción independiente del proveedor en Python puro en:

src/ros2_perception_mcp/domain/

La implementación principal es:

src/ros2_perception_mcp/domain/models.py

El dominio actualmente contiene:

• SensorDescriptor

• StreamDescriptor

• CameraDescriptor

• CameraIntrinsics

• DepthDescriptor

• PointCloudDescriptor

• PointCloudField

• LaserScanDescriptor

• FrameDescriptor

• FreshnessStatus

• SensorHealth

Dos estados semánticos finitos propiedad de la aplicación se representan usando StrEnum de Python 3.12:

• FreshnessCategory

• HealthCategory

Las clasificaciones abiertas como tipos de sensores, tipos de flujo, codificaciones, categorías de mensajes, tipos de datos de nubes de puntos e identificadores de marcos permanecen deliberadamente como valores de cadena extensibles.

Principios de diseño del dominio

La fase 3A sigue varias reglas de diseño importantes.

Independiente del proveedor

El comportamiento del dominio no depende de un RealSense D435i, RPLIDAR A2M8 ni de ningún otro dispositivo específico.

Independiente de ROS

Los mensajes ROS y los objetos de rclpy no aparecen en la API del dominio.

Los adaptadores de ROS 2 Jazzy convertirán posteriormente las observaciones ROS en objetos de dominio semánticos.

Independiente de MCP

Los modelos de dominio no contienen tipos del SDK de MCP o del protocolo.

MCP es un adaptador externo alrededor de las capas de aplicación y dominio.

Inmutable

Los modelos de dominio usan dataclasses congeladas.

Las colecciones que pertenecen a valores de dominio inmutables usan tuplas.

Metadatos incompletos representables

Los metadatos desconocidos se representan explícitamente en lugar de inventarse.

Por ejemplo, la resolución de la cámara, los rangos de profundidad, la información de calibración y las relaciones de marcos pueden ser None cuando corresponda.

Solo validación estructural

El dominio valida invariales estructurales deterministas.

No inventa:

• límites de hardware

• límites del proveedor

• umbrales de frescura

• umbrales de tasa

• reglas de seguridad física

Frescura y salud

La frescura y la salud están orientadas a la evidencia.

FreshnessStatus representa:

• tiempo de observación

• edad

• evidencia

• categoría semántica opcional

Los umbrales de frescura no están incrustados en el modelo de dominio.

La configuración de umbrales y la derivación de categorías pertenecen a trabajos posteriores de aplicación y seguridad/límites.

SensorHealth representa:

• disponibilidad

• evidencia de frescura

• evidencia de tasa

• hallazgos

• categoría semántica de salud nUn resultado de salud no es una certifcación de seguridaf física. nEl servidor nunca debe interpretar la salud del sensor como autorización para el movimiento del robot u otra actuación.

Datos acotados

Los sistemas de percepción pueden producir grandes flujos de datos continuos.

ros2_perception_mcp no está destindo a reenviar esos flujos sin restricciones a un client MCP. nLa arquitectura prevista es:

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

El acceso a imáenes, profundiad, nubes de punt y escaneos láser debe permanecer explícitamente acotao. La transmisión a velcidad completa está fuera del alcance de la v0.1.0.

*** n

Verificación de hardware planificada

Se planifican dos sensores físicos para la v0.1.0 posterior. n### RealSense D435i

Planifcado para:

Phase 14 - Real-hardware verification — RealSense D435i

Las áreas de verificación esperadas incluyen cámara, profundidad, calibración, metadatos de flujo, marcos, frescura e inspección acotada de percepción.

RPLIDAR A2M8

Planificaco para:

Phase 15 - Real-hardware verification — RPLIDAR A2M8

Las áreas de verificación esperadas incluyen metadatos de escaneo láser, marcos, frescura, evidencia de tasa, evidencia de salud e inspección acotada de escaneo.

Estos dispositivos verifican la arquitectura independiente del proveedor.

No la definen.

Ejecutar el servidor base

Instalar/sincronizar el entorno del proyecto:

uv sync

Ejecutar el servidor base actual:

uv run ros2-perception-mcp

El proceso espera JSON-RPC de MCP en la entrada estándar.

En la etapa actual de desarrollo, intencionadamente no anuncia capacidades de percepción MCP.

Establecer:

ROS2_PERCEPTION_MCP_CONFIG

para seleccionar un archivo de configuración TOML alternativo.

Pruebas de desarrollo

pytest se mantiene como una dependencia de desarrollo.

Las pruebas de dominio enfocadas de la fase 3A se pueden ejecutar con:

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

Resultado verificado de la fase 3A:

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

La carga automática de plugins de pytest de terceros está deshabilitada para esta prueba de dominio enfocada porque un entorno ROS 2 Jazzy puede exponer plugins de prueba ROS no relacionados, como launch_testing.

Las pruebas específicas de ROS se introducirán explícitamente en las fases posteriores correspondientes.

Hoja de ruta del proyecto

La hoja de ruta de la v0.1.0 es:

1. Fundamento del proyecto — COMPLETO

2. Arquitectura y alcance — COMPLETO

3. Modelos de dominio y puertos de aplicción — EN PROGRESO

   • Fase 3A - Modelos de dominio — COMPLETO

   • Fase 3B - Puertos de aplicación y límite de servicio — SIGUIENTE

4. Fundamento del adaptador ROS 2 Jazzy

5. Descubrimiento e inspección de sensores

6. Cámara / Imagen / Camerainfo

7. Profundiad

8. PointClod2

9. LasrScan

10. TF / Maros / Fresr / Rata / Salu

11. Heramientas / Recursos / Inicaciones MCP

12. Líites de segridad y diagósticos

13. Verifcación de sofwre enfocada

14. Verifcación con hadware real — ReaSene D435i

15. Verifcación con hadware real — RPLIDAR A2M8

16. Audiía final, docuentación y prparación para el lanzamiento de la v0.1.0

Cada fase requiere un alcance explícito y debe preservar la arquitecura de solo letura, acotada e independiente del proveedor.

Documentación

Los registros detallados de desarrollo se mantienen en:

• Hoja de ruta de fases

• Fase 1 - Fundamento del Proyecto

• Fase2 - Arquitectura y Alcance

• Fase3 - Modelos de Domio y Puertos de Aplicación

Los docuentos de fase están destiados a registrar no solo el progreso de la implementación, sino también las decisioes arquitéctonicas, exclusiones explícitas, resultados de verificación y líites de responsabilidad.

Supuestos de versión

El proyecto actualmente se dirige a:

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

Los paquetes ROS de Python siguen siendo dependencias del sistema y están deliberadamente separados de la capa de dominio independiente del proveedor.

Las semánticas de los mensajes ROS se verificarán contra las definiciones oficiales instaladas de ROS 2 Jazzy durante las fases de implementación del adaptador ROS y específicas del sensor.

Las versiones y convenciones de los controladores de RealSense y SLAMTEC se posponen hasta sus correspondientes fases de integración y verificación de hardware.

Siguiente paso

El siguiente paso de desarrollo es:

Phase 3B - Application ports and service boundary

La fase 3B definirá los contratos mínimos de aplicación semántica requeridos por los adaptadores posteriores de ROS 2 Jazzy.

Debe preservar la dirección de dependencia:

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

La fase 3B no debe introducir suscripciones ROS, acceso a hardware, herramientas de percepción MCP, configuración de dispositivos ni actuación.