microduck-mcp 🦆

Управляйте Pollen Robotics Microduck из любого MCP-клиента — Claude Code, Claude Desktop или собственного агента. ИИ получает инструменты, чтобы водить утку, запускать трюки, толкать её и видеть её через отрисованные кадры камеры.

Сегодня он управляет симулированной уткой (CPU MuJoCo, выполняющий официальные предобученные ONNX-политики из pollen-robotics/microduck). Плоскость управления — только намерения: скорости, трюки, взгляд — повторяя контракт robotd реального робота, так что аппаратный бэкенд может встать за теми же инструментами, когда ваша утка прибудет.

Все кадры отрисованы инструментом duck_camera — это буквально то, что ИИ видит во время управления.

Архитектура

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)

Обоснование дизайна (инструменты против ресурсов, структурированный вывод, семантика ошибок) описано в docs/mcp-design-notes.md.

Related MCP server: MuJoCo MCP Server

Установка

Требуются клоны двух официальных репозиториев (для сцен/policy-runner и поставляемых ONNX-политик), а также 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

Запуск

Запустите симуляционный сервер (по умолчанию предполагается, что три репозитория находятся рядом):

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

По умолчанию работает без графического интерфейса (headless). Чтобы смотреть в MuJoCo viewer (на macOS нужен mjpython):

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

Потыкайте его из оболочки:

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

Зарегистрируйте MCP-сервер в Claude Code:

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

MCP-инструменты

Все инструменты, возвращающие состояние, выдают типизированный структурированный вывод (схема DuckState, единицы измерения описаны для каждого поля); каждый изменяющий состояние инструмент возвращает состояние после действия, так что агенту редко нужен дополнительный опрос.

Отладочная страница AX

duck-sim также обслуживает отладочную страницу Agent Experience на http://127.0.0.1:8400 (--web PORT, --web 0 для отключения): живая лента каждой команды, поступающей на управляющий сокет, — с меткой клиента (mcp, cli, web) — рядом с автоматически обновляющимся видом камеры и панелью состояния. Откройте её рядом с MuJoCo viewer, чтобы в реальном времени наблюдать что агент делает и что он видит. Простой HTTP из стандартной библиотеки + один HTML-файл; вся отрисовка по-прежнему происходит в потоке симуляции через ту же очередь намерений, что и для любого другого клиента.

Примечания

• Симуляционный сервер выполняет все вызовы MuJoCo в одном потоке; сокет-клиенты только ставят намерения в очередь. Несколько клиентов — нормально (MCP + CLI одновременно).

• Политики подменяются на лету за общим 61-мерным контрактом наблюдений точно так же, как на роботе: движение включает ходьбу, нулевая команда возвращает в положение стоя, эпизодические трюки по таймауту возвращаются в положение стоя.

• Отрисовка камеры происходит за экраном (окно не нужно); в режиме --viewer на macOS заэкранная отрисовка может быть недоступна — запускайте в headless-режиме, если нужны кадры.

• В поставляемый набор политик не входит политика StandUp, поэтому утка, оказавшаяся на боку (например, после жёсткого приземления с рулада), остаётся там — duck_reset — это запасной выход. Обучить такую политику (Mjlab-StandUp-* в microduck_rl) — вот решение.

Дорожная карта

• Бэкенд для реального робота, работающий через WebSocket API демона (см. документацию microduck, design/architecture.md §5.3) за теми же инструментами

• Намерения позы тела (присесть/наклониться в положении стоя)

• Опциональный слот для политики StandUp, чтобы после падений можно было подняться без duck_reset

Лицензия

Apache-2.0. Создано на основе microduck и microduck_rl от Pollen Robotics, оба под Apache-2.0.