# ros2-mcp

ROS2 ↔ MCP bridge: let any AI agent (Claude Code, OpenClaw, Cursor) read ROS2
topics, call services, and **wrap telemetry into verifiable proof bundles**.

Two modes:

- **Mock mode (default)** — simulated robot, zero ROS2 required. Try it now.
- **ROS2 mode** — real topics/services via a Python sidecar (`rclpy`).

## Quick start (mock, 2 minutes)

```bash
npm install
npm run build
npm start
```

Register with your agent:

```bash
claude mcp add ros2-mcp -- npx tsx src/index.ts
```

Then ask:

> "List the robot topics, then tell me the current GPS position."
> "Move the robot forward, then wrap the telemetry into a proof bundle for task task_ros2_001."

## Tools

| Tool | Purpose |
|---|---|
| `list_topics` | list ROS2 topics |
| `read_topic` | latest value of a topic |
| `call_service` | call a service (e.g. `cmd_vel`) |
| `robot_status` | status + GPS + telemetry in one call |
| `wrap_proof` | wrap telemetry into an ai2robot proof bundle draft (hash-chained) |
| `chain_fingerprint` | genesis hash for a task |

## Real ROS2

Requires a ROS2 environment (tested pattern: `ros:humble` docker image):

```bash
docker run -it --rm ros:humble
apt-get install -y python3-pip && pip install rclpy  # usually preinstalled
```

Then run the server with the sidecar:

```bash
AI2ROBOT_ROS2=1 npm start
```

The sidecar (`python/ros2_bridge.py`) subscribes to all topics generically and
exposes them over stdio JSON-lines. It is a reference implementation; bring
your own transport if you need typed QoS or specific vendors.

## Why proof mode

`wrap_proof` emits bundles in the
[ai2robot proof format](https://github.com/ai2robot-network/ai2robot-proof)
(hash-chained action log + GPS traces; Ed25519 signature added by the
executor's key). Any fleet using this bridge can become an ai2robot executor
without changing hardware — the bridge is the adapter kernel.

## License

MIT