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: list + search + load + reset (src/policy.ts, upstream's policy-channel-design.md, shipped in daemon 0.13 = API_VERSION 18–20). duck_policy_list / duck_policy_search / duck_policy_load / duck_policy_reset. policy.check and policy.install (the official set's update path) 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. On the wire a load of a Hub repo is policy.fetch (updaterd, downloads into /var/lib/robot/policies/ and reads the manifest) then robot.loadPolicy {slot, path} (robotd); an absolute path skips the fetch. LoadPolicyParams is deny_unknown_fields: only slot and path ever go on the wire. Reset = same method, no path; reset-all = neither field, one call. An older daemon's METHOD_NOT_FOUND is translated into "your daemon is too old". Daemon 0.18+ refuses a community fetch until the owner sets [policy] allow_community = true (PERMISSION_DENIED, code 14); we add that flipping it is the owner's call, not the agent's (communityOff). Origin (pollen-robotics/* official, any other HF repo community, a path local) is decided by the daemon and reported back; our constant in protocol.ts is only for what we say before asking. walk = "none" is refused (by us first, by the daemon too). We do NOT read manifests ourselves any more: policy.fetch answers with the daemon's reading of it.