microduck-mcp 🦆

Steuern Sie die Pollen Robotics Microduck von jedem MCP-Client aus — Claude Code, Claude Desktop oder Ihrem eigenen Agenten. Eine KI erhält Werkzeuge, um die Ente herumlaufen zu lassen, Tricks auszulösen, sie zu stoßen und sie durch gerenderte Kamerabilder zu sehen.

Heute steuert es die simulierte Ente (CPU-MuJoCo mit den offiziellen vortrainierten ONNX-Policies aus pollen-robotics/microduck). Die Steuerungsebene ist rein absichtsbasiert — Geschwindigkeiten, Tricks, Blickrichtung — und spiegelt den robotd-Vertrag des echten Roboters wider, sodass ein Hardware-Backend hinter denselben Werkzeugen eingesetzt werden kann, wenn Ihre Ente eintrifft.

Alle Frames werden vom duck_camera-Werkzeug gerendert — das ist buchstäblich das, was die KI beim Steuern sieht.

Architektur

MCP client (Claude, ...)   duck CLI (humans / scripts)   browser: AX debug page
        │ stdio                          │                        │ http :8400
        ▼                                ▼                        ▼
   duck-mcp  ────────────►  Unix socket, JSON lines  ◄────  built-in web UI
                                    │
                                    ▼
                          duck-sim (50 Hz MuJoCo loop,
                          ONNX policy hot-swapping via
                          microduck_rl's PolicyInference)

Die Design-Grundsätze (Werkzeuge vs. Ressourcen, strukturierte Ausgabe, Fehlersemantik) sind in docs/mcp-design-notes.md dokumentiert.

Related MCP server: MuJoCo MCP Server

Einrichtung

Benötigt Klone der beiden offiziellen Repos (für Szenen/Policy-Runner und die mitgelieferten ONNX-Policies) sowie uv:

git clone https://github.com/pollen-robotics/microduck
git clone https://github.com/pollen-robotics/microduck_rl
git clone https://github.com/aj-dev-smith/microduck-mcp
cd microduck-mcp && uv sync

Ausführen

Starten Sie den Simulationsserver (die Standardeinstellungen gehen davon aus, dass die drei Repos nebeneinander liegen):

uv run duck-sim --rl-repo ../microduck_rl --policies ../microduck/policies

Standardmäßig headless. Um im MuJoCo-Viewer zu beobachten (macOS benötigt mjpython):

uv run mjpython -m microduck_mcp.sim_server --viewer \
    --rl-repo ../microduck_rl --policies ../microduck/policies

Probieren Sie es von einer Shell aus:

uv run duck state
uv run duck drive 0.2          # walk forward at 0.2 m/s
uv run duck trick roulade      # forward roll
uv run duck cam follow         # render a frame, prints the PNG path
uv run duck push               # shove it, watch it recover

Registrieren Sie den MCP-Server bei Claude Code:

claude mcp add duck -- uv --directory /path/to/microduck-mcp run duck-mcp

MCP-Werkzeuge

Alle Werkzeuge, die Zustand zurückgeben, erzeugen typisierte strukturierte Ausgaben (DuckState-Schema, Einheiten pro Feld dokumentiert); jedes mutierende Werkzeug gibt den Zustand nach der Aktion zurück, sodass der Agent selten eine Folgeabfrage benötigt.

AX-Debug-Seite

duck-sim bietet auch eine Agent Experience Debug-Seite unter http://127.0.0.1:8400 (--web PORT, --web 0 zum Deaktivieren): einen Live-Feed jedes Befehls, der den Steuerungs-Socket erreicht — gekennzeichnet nach Client (mcp, cli, web) — neben einer automatisch aktualisierenden Kameraansicht und einem Zustands-Dashboard. Öffnen Sie sie neben dem MuJoCo-Viewer, um in Echtzeit zu sehen, was der Agent tut und was er sehen kann. Einfaches Stdlib-HTTP + eine HTML-Datei; das gesamte Rendering erfolgt weiterhin im Sim-Thread über dieselbe Absichts-Warteschlange wie bei jedem anderen Client.

Hinweise

• Der Simulationsserver führt alle MuJoCo-Aufrufe in einem Thread aus; Socket-Clients stellen nur Absichten in die Warteschlange. Mehrere Clients sind in Ordnung (MCP + CLI gleichzeitig).

• Policies werden hinter dem gemeinsamen 61-dimensionalen Beobachtungsvertrag genau wie auf dem Roboter heiß getauscht: Fahren aktiviert Gehen, Null-Befehl kehrt zum Stehen zurück, episodische Tricks laufen in den Stand zurück.

• Das Kamera-Rendering erfolgt außerhalb des Bildschirms (kein Fenster erforderlich); im --viewer-Modus unter macOS ist Offscreen-Rendering möglicherweise nicht verfügbar — führen Sie es headless aus, wenn Sie Frames benötigen.

• Der mitgelieferte Policy-Satz enthält keine StandUp-Policy, sodass eine Ente, die auf der Seite landet (z. B. nach einer rauen Roulade-Landung), dort bleibt — duck_reset ist die Notluke. Eine zu trainieren (Mjlab-StandUp-* in microduck_rl) ist die Lösung.

Roadmap

• Echtes Roboter-Backend, das die WebSocket-API des Daemons spricht (siehe microduck-Dokumentation design/architecture.md §5.3) hinter denselben Werkzeugen

• Körperhaltungs-Absichten (Hocken/Lehnen im Stand)

• Optionaler StandUp-Policy-Slot, damit Stürze ohne duck_reset behebbar sind

Lizenz

Apache-2.0. Basierend auf microduck und microduck_rl von Pollen Robotics, beide Apache-2.0.