microduck-mcp: Instructions file for Claude Code

microduck-mcp — agent context

Agent-agnostic MCP server for the Pollen Robotics Microduck (~25cm, 800g biped, $399, ships ~Christmas 2026). Published under the MicroduckHub brand (microduckhub.com) but named for what it is: repo + npm are microduck-mcp. Decided 2026-08-29 — brand is the umbrella, product is named for search. This file is the working context for AI coding sessions on this repo.

The robot's actual architecture (verified against upstream docs, Aug 2026)

• Seven Rust daemons on a Rockchip RK3566, talking JSON-RPC 2.0, one object per line, over per-daemon Unix sockets:
  • robotd (/run/robotd.sock) — robot.* — the ONLY thing that touches motors. 50 Hz loop, safety authority: joint clamps, fall→limp, intent deadman. Clients send intents, not motor commands.
  • configd (/run/configd.sock) — net.*, pad.*, system.*
  • updaterd (/run/updaterd.sock) — update.* — signed releases, atomic swap, health gate, auto-rollback
  • btd/padd/mediad/tofd are transports/sensors; mediad serves WebRTC (console :8080, signalling :8443)
• robotctl is the on-robot CLI; robotctl health --json gives a support bundle and exits non-zero when unhealthy (script-gateable).
• Upstream: github.com/pollen-robotics/microduck (Apache 2.0). Design docs in docs/design/ are authoritative; when code and doc disagree, the doc that owns the mechanism wins.

Design decisions already made — don't relitigate without reason

1. Agent-agnostic. No Claude-specific assumptions. Tool descriptions must be self-sufficient for any model. Target clients: Claude, ChatGPT, Cursor, Gemini CLI, smolagents (HF's own stack — strategic given the duck is a HF product).
2. Transport abstraction (src/transport/): mock (default, no hardware), sim (CPU MuJoCo + the official pretrained ONNX policies, via a Python sidecar), unix (on-robot), ssh (laptop → the robot's sockets forwarded over ssh -L, then unix). Selected via DUCK_TRANSPORT env. Mock-first because nobody has hardware until ~Dec; sim is where behaviour gets validated before then.
3. Server-side safety layer (src/safety.ts) on top of robotd's own: velocity clamps, battery floor (15%) for motion, rate limiting, and a duck_stop tool that is NEVER gated. Rationale: we can't assume any calling agent is careful, and this moves physical hardware.
4. Deliberately excluded (for now): update.apply / rollback as tools. An agent auto-updating robot firmware is a footgun; revisit once the M8 Hub policy channel ships, because that's when it becomes DuckHub's deploy backend (see sibling repo duckhub).
5. Policy channel: load + reset only (src/policy.ts, upstream's policy-channel-design.md). duck_policy_list / duck_policy_load / duck_policy_reset. policy update and policy check are excluded by the same rule as (4): nothing that fetches "the newest" and applies it. Load and reset are the safe pair because reset is a one-word undo, and a load is a config edit that survives a reboot (§3) so it needs one. Needs upstream API_VERSION 17; a v16 daemon's METHOD_NOT_FOUND is translated into "your daemon is too old". Origin (pollen-robotics/* official, any other HF repo community, a path local) is a constant in protocol.ts and never a config key. walk = "none" is refused: everything falls back to it. The HF manifest.json pre-check can only REFUSE (wrong obs/action width, newer model_api) — a missing or partial manifest still loads, because most of the Hub publishes none and robotd's shape gate is the real check.