ros2_perception_mcp

ros2_perception_mcp — это выделенный, ориентированный на чтение MCP-сервер для ограниченной семантической инспекции систем восприятия ROS 2.

Версия 0.1.0 нацелена на:

• Ubuntu 24.04

• Python 3.12

• ROS 2 Jazzy

• MCP Python SDK 2.x

• stdio transport

Проект намеренно спроектирован как выделенный MCP-сервер для восприятия, а не как универсальный интерфейс ROS 2.

Текущее состояние

Текущее состояние разработки 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

• SDK RealSense

• SDK SLAMTEC

• 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

• управление моторами

• движение робота

• движение манипулятора

• неограниченную пересылку полезной нагрузки

• потоковую передачу изображений с полной частотой

• потоковую передачу облаков точек с полной частотой

Проект ориентирован на чтение.

Инспекция не должна настраивать устройства или вызывать активацию.

Разделение ответственности

Проекты MCP для ROS 2 намеренно имеют раздельные обязанности.

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

Два конечных семантических состояния, принадлежащих приложению, представлены с помощью StrEnum из Python 3.12:

• 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.

Запланированная аппаратная верификация

Два физических датчика запланированы для более поздней верификации 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

Автоматическая загрузка сторонних плагинов pytest отключена для этого сфокусированного теста домена, поскольку окружение ROS 2 Jazzy может предоставлять несвязанные плагины тестирования ROS, такие как launch_testing.

Специфичное для 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

Пакеты Python ROS остаются системными зависимостями и намеренно отделены от вендорно-нейтрального доменного уровня.

Семантика сообщений ROS будет верифицирована по установленным и официальным определениям ROS 2 Jazzy во время фаз реализации адаптера ROS и специфичных для датчиков.

Версии и соглашения драйверов 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, настройку устройств или активацию.