Tool: show()

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

The show() tool is a high-level function within the Reachy Mini MCP server designed to make the robot express an emotion or perform a pre-recorded movement. It serves as a primary interface for an AI to give the robot a physical personality, abstracting away the low-level motor controls into simple, descriptive commands. The tool is intentionally designed for cognitive simplicity, allowing the caller to specify what to express, while the tool handles how to move the robot's head and antennas.

The show() function operates in two distinct modes, determined by which parameter is provided:

1. Built-in Emotions: Using the emotion parameter, one of 12 locally-defined, fast expressions can be triggered. These are motor-only choreographies.
2. Recorded Moves: Using the move parameter, one of 81+ professionally choreographed moves from Pollen Robotics' libraries can be played. These are more nuanced and may include audio. This mode overrides the emotion parameter if both are provided.

Sources: README.md, src/server.py:321-352

Architecture and Logic Flow

The show() tool is implemented as a Python function decorated with @mcp.tool(), making it available to a connected MCP client. Its core logic is a simple conditional check on the move parameter.

• If the move parameter has a value, the function calls the internal helper _do_play_move(move).
• If the move parameter is empty, it calls _do_express(emotion) using the value of the emotion parameter.

This logic ensures that recorded moves take precedence over built-in emotions.

Sources: src/server.py:350-352

The following diagram illustrates the primary decision flow within the show() function.

Built-in Emotions (emotion)

When called with the emotion parameter, show() executes a fast, locally-defined motor choreography. These are defined in the EXPRESSIONS dictionary, which maps an emotion name to a set of motor targets and movement properties.

Sources: src/server.py:60-161

The EXPRESSIONS Data Structure

The EXPRESSIONS constant is a dictionary where each key is an emotion name and the value is another dictionary specifying the target pose and animation style.

• head: A dictionary containing z, roll, pitch, and yaw target values in degrees.
• antennas: A list of two integers for the left and right antenna angles in degrees.
• duration: The time in seconds for the movement to complete.
• method: The interpolation technique for the movement, such as minjerk or cartoon.

Sources: src/server.py:60-65

Execution Flow: _do_express()

The internal _do_express() function is responsible for executing these built-in emotions.

1. It retrieves the expression details from the EXPRESSIONS dictionary.
2. It gets a connection to the robot via get_robot().
3. It converts antenna degrees to radians.
4. It calls the robot.goto_target() method from the reachy-mini SDK, passing the head pose, antenna positions, duration, and interpolation method.

The following diagram shows the process for expressing a built-in emotion.

Available Emotions

The following 12 built-in emotions are available via the emotion parameter.

Emotion	Head Pose (z, roll, pitch, yaw)	Antennas (L, R)	Duration (s)	Method
neutral	0, 0, 0, 0	0, 0	1.5	minjerk
curious	0, 0, 10, 8	20, 20	1.2	ease_in_out
uncertain	0, 8, -3, 3	-15, 15	2.0	minjerk
recognition	0, 0, 5, 0	30, 30	0.8	cartoon
joy	0, -3, 8, 0	40, 40	1.0	cartoon
thinking	0, 5, 3, 12	8, -8	1.5	ease_in_out
listening	0, -3, 8, 0	25, 25	1.0	minjerk
agreeing	0, 0, 8, 0	20, 20	0.5	ease_in_out
disagreeing	0, 0, 0, 12	-8, -8	0.4	ease_in_out
sleepy	0, 8, -10, 0	-20, -20	2.5	minjerk
surprised	0, 0, -8, 0	45, 45	0.3	cartoon
focused	0, 0, 6, 0	18, 18	1.0	minjerk

Sources: src/server.py:60-161

Recorded Moves (move)

When called with the move parameter, show() plays a more complex, professionally choreographed move from a library hosted on HuggingFace. This functionality is handled by the _do_play_move() helper function, which communicates with the Reachy Mini daemon.

Sources: README.md, src/server.py:350-351

Execution Flow: _do_play_move()

Unlike built-in emotions, recorded moves are not stored in the MCP server code. Instead, the server sends an HTTP request to the robot's daemon, which is responsible for fetching and executing the move.

1. The _do_play_move() function is called with a move_name.
2. It constructs a URL targeting the daemon's API endpoint: http://localhost:8321/api/move/play/recorded-move-dataset/{dataset}/{move_name}.
3. It sends an HTTP POST request to this endpoint.
4. The daemon receives the request, finds the corresponding move in its library, and commands the robot to perform it.
5. The MCP server returns a confirmation message, including a UUID for the move execution.

The available moves can be found using the discover() tool.

Sources: src/server.py:750-768

The sequence diagram below shows the interaction between the MCP server and the Reachy daemon when playing a recorded move.

API and Parameters

The show tool is defined with the @mcp.tool() decorator and has two optional string parameters.

@mcp.tool()
def show(
    emotion: Literal[
        "neutral", "curious", "uncertain", "recognition", "joy",
        "thinking", "listening", "agreeing", "disagreeing",
        "sleepy", "surprised", "focused"
    ] = "neutral",
    move: str = ""
) -> str:

Sources: src/server.py:321-331

Parameter	Type	Default	Description
emotion	string	"neutral"	The name of one of the 12 built-in emotions to express.
move	string	""	The name of a recorded move from the Pollen Robotics library. If provided, this overrides the emotion parameter.

Sources: src/server.py:322-352, README.md

Summary

The show() tool provides a powerful, dual-mode interface for controlling the Reachy Mini's expressive movements. By offering both simple, fast, built-in emotions and more complex, nuanced, recorded moves, it gives an AI flexible options for physical embodiment. The clear separation of concerns—with emotion handled locally and move delegated to the robot's daemon—creates a robust and extensible system for robotic expression. This tool is a cornerstone of the reachy-mini-mcp project's goal to "give your AI a body."

Sources: src/server.py, README.md, src/init.py