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

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

Development

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:

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.