reachy-mini-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

A control layer for the Reachy Mini robot. Nothing here drives motors directly — every action is an HTTP call to the Reachy Mini daemon (default http://localhost:8000), which must be running separately. The code lives in the reachy_mini_mcp/ package (a pip-installable distribution, reachy-mini-mcp, built with hatchling). It exposes the daemon's capabilities to LLMs two ways, both backed by one shared tool repository:

• reachy_mini_mcp/server.py — a FastMCP (stdio) MCP server. Exposes exactly one MCP tool, operate_robot, a meta-tool that dispatches to every robot operation by name. Individual tools are loaded into an in-process registry but deliberately not surfaced as separate MCP tools.
• reachy_mini_mcp/server_openai.py — a FastAPI HTTP server (port 8100) that speaks an OpenAI-ish dialect: GET /tools, POST /execute_tool, POST /v1/chat/completions. Here each tool is exposed individually in OpenAI function-calling format.

In front of both sits reachy_mini_mcp/cli/ — the reachy-mini-mcp console script, an MCP-server manager: overview, show (print the mcp.json snippet), explain, install/uninstall (merge/remove the entry in a client config), doctor, and serve (run the server — what mcp.json launches). The manager imports no robot dependencies; only serve pulls in the FastMCP stack (lazily), so a bare pip install reachy-mini-mcp is a working manager and the robot runtime lives behind the [server] / [tts] / [openai] extras.

MCP client / HTTP client  →  reachy_mini_mcp.server | .server_openai  →  Reachy daemon (:8000)  →  robot/sim
                  manager:  reachy-mini-mcp {show,install,doctor,serve,...}

Beyond the robot-control layer, this repo is also an AgentCulture mesh agent — its mesh identity and vendored skill kit are described under Mesh identity and Skills below.