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

두 개의 유한한 애플리케이션 소유 의미론적 상태는 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 범위 밖에 있습니다.

계획된 하드웨어 검증

두 개의 물리적 센서가 이후 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 환경은 launch_testing과 같은 관련 없는 ROS 테스트 플러그인을 노출할 수 있기 때문입니다.

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 인식 도구, 장치 구성 또는 작동을 도입해서는 안 됩니다.