Tool: discover()

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/server.py
• pyproject.toml
• src/init.py
• LICENSE (Existence referenced in README.md)

The discover() tool provides a mechanism for an AI system to query the available pre-recorded moves that the Reachy Mini robot can perform. These moves, choreographed by Pollen Robotics, offer a library of nuanced expressions and dances, which can be executed using the show(move=...) tool. This introspection capability is fundamental to the project's goal of enabling "expressive robotics" by allowing the AI to dynamically learn its own physical capabilities.

Sources: src/server.py:31-33, 1002-1004, README.md:14, 34

Architecture and Data Flow

The discover() tool functions by making an HTTP GET request from the MCP Server to the Reachy Mini Daemon. The daemon, in turn, is responsible for fetching the list of available moves from the specified HuggingFace dataset. The MCP server then formats this list and returns it as a string to the calling AI system.

Sources: src/server.py:1002-1023, README.md:40

The following diagram illustrates the data flow when discover() is called.

Function Definition

The discover() tool is implemented as a Python function within src/server.py and exposed to the MCP interface using the @mcp.tool() decorator.

Sources: src/server.py:1002-1004

# File: src/server.py

@mcp.tool()
def discover(library: Literal["emotions", "dances"] = "emotions") -> str:
    """
    Discover available moves from Pollen's HuggingFace libraries.

    Returns move names that can be passed to show(move=...).
    Moves are professionally choreographed by Pollen Robotics.

    Args:
        library: Which library - "emotions" (81 expressions) or "dances"

    Returns:
        Available move names
    """
    # ... implementation ...

Sources: src/server.py:1002-1016

Parameters

The function accepts a single optional parameter to specify which move library to query.

Parameter	Type	Default	Description
library	Literal["emotions", "dances"]	emotions	The name of the move library to discover.

Sources: src/server.py:1003, 1012-1013

Move Libraries

The discover() tool queries one of two predefined move libraries, which are mapped to specific HuggingFace dataset identifiers. This mapping is stored in the MOVE_LIBRARIES dictionary.

Library Key	HuggingFace Dataset Identifier	Description
emotions	pollen-robotics/reachy-mini-emotions-library	A collection of 81 expressive emotional movements.
dances	pollen-robotics/reachy-mini-dances-library	A collection of dance movements.

Sources: src/server.py:996-999, 1012

The logic for selecting the dataset is handled internally by the discover function.

Daemon Interaction

Communication with the Reachy Mini Daemon is performed over HTTP. The base URL for the daemon's API is configurable via the REACHY_DAEMON_URL environment variable, which defaults to http://localhost:8321/api.

Sources: src/server.py:985, README.md:83

The discover() function constructs a specific endpoint URL to list moves from a dataset:
{DAEMON_URL}/move/recorded-move-datasets/list/{dataset}

An httpx.get request is sent to this endpoint. The function includes error handling for connection issues (e.g., if the daemon is not running) and other request failures.

Sources: src/server.py:1020-1023

Error Handling

The function is designed to return user-friendly error messages in case of failure.

• Unknown Library: If the library parameter is not emotions or dances, it returns an error listing the available libraries.
• Connection Error: If the httpx request fails to connect to the daemon, it returns a message advising the user to check if the daemon is running.
• Other HTTP Errors: Any other non-200 status code from the daemon will be caught, and a generic failure message will be returned.

Sources: src/server.py:1018-1019, 1024-1027

Return Value

Upon success, the discover() tool returns a formatted string containing the name of the library, the count of moves found, and a comma-separated list of the move names.

Example Success Response:

"Available emotions (81): afraid1, angry1, ..., serenity1, surprised1"

Example Error Response:

"Cannot connect to daemon. Is it running on localhost:8321?"

Sources: src/server.py:1023, 1025

Summary

The discover() tool is an essential utility in the reachy-mini-mcp ecosystem. It empowers an AI agent by providing runtime knowledge of the robot's expressive capabilities. By querying the Reachy Mini Daemon for lists of professionally choreographed moves from Pollen Robotics' HuggingFace libraries, it enables dynamic and varied physical expression through the show(move=...) command, fulfilling a core aspect of the project's vision for embodied AI.

Sources: src/server.py:31-33, 1005-1007, src/init.py:1