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 传输

该项目有意设计为专用的感知 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 订阅或物理传感器集成。这些能力将在其对应的路线图阶段中引入。

Related MCP server: ros2-mcp

架构

预期的架构为：

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 动作调用

• 参数修改

• 进程执行

• 启动执行

• shell 命令

• 相机配置

• 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 环境可能暴露无关的 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

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 感知工具、设备配置或执行。