microduck-mcp 🦆

Conduce el Pollen Robotics Microduck desde cualquier cliente MCP — Claude Code, Claude Desktop o tu propio agente. Una IA obtiene herramientas para pasear al pato, activar trucos, empujarlo y verlo a través de fotogramas de cámara renderizados.

Actualmente conduce el pato simulado (MuJoCo en CPU ejecutando las políticas ONNX preentrenadas oficiales de pollen-robotics/microduck). El plano de control es solo de intenciones — velocidades, trucos, mirada — reflejando el contrato robotd del robot real, de modo que un backend de hardware pueda encajar detrás de las mismas herramientas cuando llegue tu pato.

Todos los fotogramas son renderizados por la herramienta duck_camera — esto es literalmente lo que la IA ve mientras conduce.

Arquitectura

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)

La justificación del diseño (herramientas frente a recursos, salida estructurada, semántica de errores) está documentada en docs/mcp-design-notes.md.

Related MCP server: MuJoCo MCP Server

Configuración

Requiere clonar los dos repositorios oficiales (para scenes/policy-runner y las políticas ONNX incluidas), además de 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

Ejecutar

Inicia el servidor de simulación (los valores predeterminados asumen que los tres repositorios son directorios hermanos):

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

Sin interfaz gráfica por defecto. Para verlo en el visor de MuJoCo (en macOS se necesita mjpython):

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

Pruébalo desde una shell:

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

Registra el servidor MCP con Claude Code:

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

Herramientas MCP

Todas las herramientas que devuelven estado emiten una salida estructurada tipada (esquema DuckState, unidades documentadas por campo); cada herramienta que muta devuelve el estado posterior a la acción, de modo que el agente rara vez necesita una consulta de seguimiento.

Página de depuración AX

duck-sim también sirve una página de depuración de Agent Experience en http://127.0.0.1:8400 (--web PORT, --web 0 para desactivarla): un flujo en vivo de cada comando que llega al socket de control — etiquetado por cliente (mcp, cli, web) — junto a una vista de cámara con autorefresco y un panel de estado. Ábrela junto al visor de MuJoCo para ver qué hace el agente y qué puede ver, en tiempo real. HTTP simple de la biblioteca estándar + un archivo HTML; todo el renderizado sigue ocurriendo en el hilo de simulación a través de la misma cola de intenciones que cualquier otro cliente.

Notas

• El servidor de simulación ejecuta todas las llamadas a MuJoCo en un único hilo; los clientes de socket solo encolan intenciones. Múltiples clientes funcionan bien (MCP + CLI simultáneamente).

• Las políticas se intercambian en caliente detrás del contrato compartido de observación de 61 dimensiones, exactamente igual que en el robot: conducir activa la marcha, el comando cero devuelve a la posición de pie, y los trucos episódicos caducan y regresan a la posición de pie.

• El renderizado de la cámara es fuera de pantalla (no se necesita ventana); en el modo --viewer en macOS, el renderizado fuera de pantalla puede no estar disponible — ejecuta sin interfaz gráfica si necesitas fotogramas.

• El conjunto de políticas incluidas no contiene una política StandUp, por lo que un pato que acabe de lado (p. ej., tras un aterrizaje brusco de roulade) se queda ahí — duck_reset es la vía de escape. Entrenar una (Mjlab-StandUp-* en microduck_rl) es la solución.

Hoja de ruta

• Backend de robot real que hable con la API WebSocket del daemon (ver la documentación de microduck design/architecture.md §5.3) detrás de las mismas herramientas

• Intenciones de postura corporal (agacharse/inclinarse estando de pie)

• Ranura opcional para una política StandUp para que las caídas sean recuperables sin duck_reset

Licencia

Apache-2.0. Construido sobre microduck y microduck_rl por Pollen Robotics, ambos con licencia Apache-2.0.