Yarp McpServers

A Python-based Model Context Protocol (MCP) server framework that bridges YARP (Yet Another Robot Platform) and enables communication through MCP. This project provides server implementations for various YARP interfaces through device and RPC-based servers, allowing seamless integration with AI models and applications that support the MCP protocol.

⚠️ Disclaimer

This codebase has been written with the contribution of generative AI. While the code has been tested, please use it carefully and review it for your specific use case before deploying in production environments.

This repository is under active development and may change significantly with each new commit. Breaking changes may occur without notice.

Overview

This project implements MCP servers that expose YARP interfaces. Each server runs as a separate thread and communicates with YARP through local network ports.

Available Server Types

The project supports the following categories of MCP servers:

Category	Location	Purpose
Device Servers	src/servers/devices/	Expose YARP device interfaces (IBattery, INavigation2D, ISpeechSynthesizer, etc.)
RPC Servers	src/servers/rpc/	Expose YARP RPC-based services

Device Servers

Device servers expose YARP hardware device interfaces through MCP tools:

• Yarp_mcpServer_IBattery - Battery status monitoring
• Yarp_mcpServer_INavigation2D - 2D robot navigation and path planning
• Yarp_mcpServer_ISpeechSynthesizer - Text-to-speech synthesis

Each device server is located in its own directory under src/servers/devices/ and can be independently configured and launched.

RPC Servers

RPC servers expose YARP services through the RPC protocol. Add new RPC server implementations in src/servers/rpc/.

Device Server Details

Yarp_mcpServer_IBattery

Exposes battery device functionality through MCP tools. Allows querying battery status, voltage, temperature, and other power-related metrics.

• Location: src/servers/devices/yarp_mcpServer_IBattery/
• Typical Device Type: battery_nwc_yarp
• Example Usage: See example_usage.py

Yarp_mcpServer_INavigation2D

Exposes 2D navigation interface for robot path planning and movement control.

• Location: src/servers/devices/yarp_mcpServer_INavigation2D/
• Typical Device Type: navigation_nwc_yarp
• Documentation: See README.md

Yarp_mcpServer_ISpeechSynthesizer

Exposes speech synthesis functionality for text-to-speech operations.

• Location: src/servers/devices/yarp_mcpServer_ISpeechSynthesizer/
• Typical Device Type: synth_nwc_yarp
• Example Usage: See example_usage.py
• Documentation: See README.md

Prerequisites

• Python >= 3.12
• YARP (Yet Another Robot Platform) installed and yarpserver running
• Connected YARP devices to communicate with

Installation

1. Clone the repository:

   git clone <repository-url>
   cd yarp-mcpServers-devices
   

2. Install dependencies using uv:

   uv sync
   

   Key dependencies (defined in pyproject.toml):

   • mcp[cli]>=1.14.1 - Model Context Protocol framework
   • fastapi>=0.118.0 - Web framework for MCP server
   • uvicorn>=0.37.0 - ASGI server
   • ollama>=0.6.0 - Optional: for local LLM support
   • python-dotenv>=1.1.1 - Environment configuration

   Note: This project uses uv for fast Python dependency management. Make sure it's installed on your system.

Quick Start

Using yarp_server_launcher.py

The yarp_server_launcher.py script launches one or more MCP servers based on a configuration file.

Basic usage:

python yarp_server_launcher.py --from config.xml

With multiple parameter overrides:

python yarp_server_launcher.py --from config.xml --set param_name new_value

Configuration

Configuration uses YARP's ResourceFinder format (XML files). Here's an example structure:

example.xml:

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE robot PUBLIC "-//YARP//DTD yarprobotinterface 3.0//EN" "http://www.yarp.it/DTD/yarprobotinterfaceV3.0.dtd">
<robot name="mcpServers" prefix="servers" portprefix="/servers" xmlns:xi="http://www.w3.org/2001/XInclude">
    <devices>
        <!-- Battery Server Configuration -->
        <device name="batteryDevice" type="Yarp_mcpServer_IBattery">
            <param name="yarp_device">battery_nwc_yarp</param>
            <param name="yarp_remote">/battery_nws</param>
            <param name="yarp_local">/battery_nwc</param>
        </device>

        <!-- Navigation Server Configuration -->
        <device name="navDevice" type="Yarp_mcpServer_INavigation2D">
            <param name="yarp_device">navigation_nwc_yarp</param>
            <param name="yarp_remote">/nav2d_nws</param>
            <param name="yarp_local">/nav2d_nwc</param>
        </device>

        <!-- Speech Synthesizer Server Configuration -->
        <device name="synthDevice" type="Yarp_mcpServer_ISpeechSynthesizer">
            <param name="yarp_device">synth_nwc_yarp</param>
            <param name="yarp_remote">/synth_nws</param>
            <param name="yarp_local">/synth_nwc</param>
        </device>
    </devices>
</robot>

example.ini (command-line parameter overrides):

config example.xml
yarp_remote /custom_battery_nws
yarp_local /custom_battery_nwc

How It Works

1. Configuration Parsing: The launcher reads the XML configuration file using YARP's ResourceFinder
2. Server Instantiation: For each device defined in the config, a corresponding MCP server class is instantiated
3. Thread Management: Each server runs in its own daemon thread for concurrent operation
4. Signal Handling: The launcher gracefully handles SIGINT (Ctrl+C) and SIGTERM signals to cleanly shut down all servers
5. YARP Communication: Servers connect to YARP devices through TCP/IP ports and expose their interfaces via MCP tools

Project Structure

yarp-mcpServers/
├── yarp_server_launcher.py      # Main launcher script
├── pyproject.toml               # Project dependencies and metadata
├── resources/
│   └── contexts/
│       └── test_servers/        # Test configuration files
└── src/
    ├── modules/
    │   └── McpConfigParser.py   # Configuration parsing utilities
    └── servers/
        ├── devices/             # Device-based MCP servers
        │   ├── yarp_mcpServer_IBattery/
        │   ├── yarp_mcpServer_INavigation2D/
        │   └── yarp_mcpServer_ISpeechSynthesizer/
        ├── rpc/                 # RPC-based MCP servers
        └── thrift/              # Thrift-based MCP servers

Running Servers

Device Servers

# Single device server
python yarp_server_launcher.py --from resources/contexts/test_servers/test_battery.xml

# Multiple device servers
python yarp_server_launcher.py --from resources/contexts/test_servers/test_batteryNnavigation.xml

# All device servers
python yarp_server_launcher.py --from resources/contexts/test_servers/test_batteryNnavigationNSynth.xml

With Parameter Overrides

python yarp_server_launcher.py --from config.xml \
    --set device_yarp_remote /my_device_nws \
    --set device_yarp_local /my_device_nwc

Stopping Servers

Press Ctrl+C to gracefully shut down all running servers. The launcher will:

• Catch the interrupt signal
• Clean up server instances
• Close YARP connections
• Exit cleanly

Troubleshooting

"yarpserver is not running"

Make sure YARP server is running:

yarpserver

"Cannot find device"

Verify that:

1. The YARP device is properly initialized
2. The yarp_remote port in your config matches the actual device's port
3. YARP network is properly configured (yarp detect to check)

"Server class not found"

Ensure the device type attribute in your XML config matches an available server class name

Development

Adding New Device Servers

1. Create a new package in src/servers/devices/yarp_mcpServer_<InterfaceName>/
2. Implement the server class following the pattern of existing device servers
3. Add the server to the configuration XML with type="Yarp_mcpServer_<InterfaceName>"
4. Launch with yarp_server_launcher.py

Adding New RPC Servers

1. Create a new module or package in src/servers/rpc/
2. Implement the RPC server class
3. Add the server to the configuration XML
4. Launch with yarp_server_launcher.py

Contributing

Contributions are welcome! Please ensure:

• Code follows Python standards
• Configuration files are well-documented
• Changes are tested with actual YARP devices when possible

License

[Add your license here]

References

• YARP Documentation
• Model Context Protocol (MCP)