# osracer-mcp

MCP server and agent skill for safe OSRacer vehicle control.

This repository is intended to live as an independent Git repository and be
added to `osrbot/osracer` as a submodule after the remote repository exists.

## Scope

- Expose OSRacer ROS 2 control and status surfaces through MCP tools.
- Expose OSRCore MCU serial commands through a strict whitelist.
- Keep movement operations gated by preflight, arming, limits, and emergency stop.
- Bundle an agent skill that tells AI agents how to use the tools safely.

## Current Status

- MCU serial adapter: implemented for whitelisted commands and parsed read-only
  responses.
- State aggregation: implemented for ROS graph state plus MCU diagnostic commands.
- Core control logic: isolated in a ROS-free `ControlCore` that depends on
  motion/state interfaces; MCP tools provide the ROS and serial adapters.
- MCU parameter tools: implemented for PID, compass filter, and magnetometer
  calibration commands through explicit mutating tools.
- MCU onboard peripheral tools: implemented for RGB LED, buzzer tone, and alert
  beep commands supported by the matching OSRCore firmware serial protocol.
- ROS 2 graph preflight: implemented through the `ros2` CLI for topic, node,
  and service availability checks.
- Motion control: short-lived Ackermann publishing and zero-motion stop are
  implemented through the `ros2` CLI, but not hardware-validated yet.
- LED matrix, Nav2 NavigateToPose, and Nav2 SaveMap command construction:
  implemented through the `ros2` CLI and covered by fake-runner tests.
- Agent skill: initial safety workflow draft.

## Non-goals

- Do not bypass ROS 2 safety and state feedback for high-level navigation.
- Do not expose arbitrary serial passthrough to the MCU.
- Do not provide remote network access to the robot by default.

## Initial Architecture

```txt
Agent Skill
  -> MCP tools
  -> Safety policy
  -> Core control logic
  -> Interface adapters
     -> ROS 2 adapter
     -> MCU serial adapter
  -> OSRacer ROS stack / OSRCore firmware
```

## Development

```bash
uv sync
uv run osracer-mcp
```

The first implementation target is stdio transport. Streamable HTTP should be
added only after authentication and network exposure policy are explicit.

On Windows, prefer checking this repository out under an ASCII-only path. Some
editable installs can encode non-ASCII paths incorrectly; tests use `src/`
directly to avoid that during local validation.

## Submodule Integration

After the remote repository exists:

```bash
git submodule add git@github.com:osrbot/osracer-mcp.git tools/osracer-mcp
git commit -m "chore: add osracer MCP submodule"
```

Do this from a clean `osracer` working tree so the submodule pointer commit is
not mixed with unrelated ROS package changes.