SDK-to-MCP: Hardware SDK to MCP Server Converter

🌐 English | 中文

<div align="center">

Transform any hardware SDK or protocol document into a standardized MCP Server

</div>

🎯 Overview

sdk-to-mcp is an intelligent automation pipeline that converts heterogeneous hardware interfaces (PDF protocols, C++/Python SDKs, ROS interfaces) into standardized Model Context Protocol (MCP) servers. This enables AI assistants like Claude to control physical robots and devices through natural language.

Key Features

• 🔌 Multi-Protocol Support: Serial, DDS, ROS/ROS2, HTTP/REST
• 🤖 AI-Powered Analysis: LLM-driven protocol extraction from PDFs and code
• 🛡️ Built-in Safety: Automatic safety guards and limit validation
• ⚡ Code Generation: Jinja2-based template engine for MCP server generation
• ✅ Auto-Validation: Automatic syntax checking and error correction
• 🔧 Production Ready: Full type hints, async support, comprehensive error handling
• 📊 SDK Version Tracking: Automatic checksum generation for version verification

---

📚 SDK References and Sources

This project maintains strict version tracking for all integrated SDKs. Each MCP server generated includes:

• SDK Version: Exact version number of the source SDK
• Source URL: Link to official repository or documentation
• Checksum: SHA256 hash for integrity verification
• License: Compliance with original SDK licensing terms

Supported SDKs

| SDK Name | Version | Protocol | Source Repository | Documentation | License | |----------|---------|----------|-------------------|---------------|---------| | Unitree SDK2 | 2.1.0+ | DDS | unitreerobotics/unitree_sdk2 | Unitree Docs | BSD-3-Clause | | GCU Gimbal SDK | V2.0.6 | Serial | Proprietary | GCU Protocol PDF | Proprietary | | Universal Robots ROS2 Driver | 2.4.0+ | ROS2 | UniversalRobots/Universal_Robots_ROS2_Driver | ROS2 Driver Docs | Apache-2.0 | | ur_rtde | 1.0.0+ | TCP | sdurw/ur_rtde | ur_rtde Docs | MIT | | Inspire Robots SDK | Latest | Serial | inspire-robotics/sdk | Proprietary | Proprietary | | Paxini SDK | Latest | DDS/Serial | Proprietary | Proprietary | Proprietary |

Hardware Documentation

| Hardware | Model | Manufacturer | Key Specs | Documentation | |----------|-------|--------------|-----------|---------------| | Unitree G1 | G1-23D/43D | Unitree Robotics | 23/43 DOF, 35kg, 2.5h runtime | User Manual | | Unitree Go2 | Go2-Air/Pro/EDU | Unitree Robotics | 12 DOF quadruped, 15kg | Go2 Docs | | Unitree H1 | H1 | Unitree Robotics | 19 DOF humanoid, 47kg | H1 Docs | | GCU Z-2Mini | Z-2Mini | Xianfei Tech | 3-axis gimbal, ±150°/s, 115200 baud | User Manual | | UR5e | UR5e | Universal Robots | 6 DOF arm, 5kg payload, ±360° joints | UR5e Specs | | Inspire Hand | RH56DFX/RH56BFX | Inspire Robots | 6 DOF dexterous hand | Proprietary |

---

📁 Repository Structure

sdk_to_mcp/
├── sdk_to_mcp_core.py          # Core transformation engine (enhanced)
│                               # - SDK version tracking
│                               # - Safety constraint extraction
│                               # - Error code mapping
│                               # - Hardware spec extraction
│
├── SKILL.md                    # Skill definition for AI agents
│
├── example/                    # Example MCP servers (production-ready)
│   ├── ros-mcp-server/         # Full-featured ROS MCP server
│   │   └── ros_mcp/            # Source: ROS/ROS2
│   ├── ros2-mcp-server/        # ROS 2 native MCP server
│   │   └── Source: ROS 2 Humble/Jazzy
│   ├── unitree-go2-mcp-server/ # Unitree Go2 robot MCP
│   │   └── Source: unitree_sdk2
│   └── robot_MCP/              # SO-ARM100/LeKiwi robot MCP
│       └── Source: LeRobot
│
├── sdk/                        # Hardware SDKs (version-pinned)
│   ├── xianfei/                # GCU Gimbal SDK V2.0.6
│   │   ├── GCU私有通信协议-XF(A5)V2.0.6.pdf
│   │   ├── Z-2Mini用户手册-XF(A5)V1.4.pdf
│   │   └── gcu_gimbal_control.py
│   │
│   ├── unitree_sdk2/           # Unitree SDK2 (latest)
│   │   ├── README.md
│   │   └── examples/           # G1, Go2, H1, B2 examples
│   │
│   ├── Universal_Robots_ROS2_Driver/  # UR ROS2 Driver
│   │   └── Source: GitHub main
│   │
│   ├── ur_rtde/                # ur_rtde C++ library
│   │   ├── doc/                # API documentation
│   │   └── examples/           # Python/C++ examples
│   │
│   ├── inspire_robots/         # Inspire hand SDK
│   │   └── Source: Proprietary
│   │
│   └── paxini/                 # Paxini tactile sensor SDK
│       └── Source: Proprietary
│
├── generated/                  # Generated MCP servers
│   ├── gcu_gimbal_mcp_server.py  # GCU Gimbal MCP Server
│   │                               # SDK Version: V2.0.6
│   │                               # Checksum: [auto-generated]
│   ├── sdk_metadata.json       # Version tracking metadata
│   └── README.md               # Generated server usage guide
│
└── README.md                   # This file

---

🚀 Quick Start

Installation

# Clone the repository
git clone https://github.com/ros-claw/sdk_to_mcp.git
cd sdk_to_mcp

# Install dependencies
pip install mcp pyserial

# For ROS2 support
pip install rclpy

# For DDS support (Unitree)
pip install cyclonedds

Transform an SDK

from sdk_to_mcp_core import SDKToMCPTransformer, SDKMetadata, CommunicationProtocol

# Initialize transformer
transformer = SDKToMCPTransformer()

# Define SDK metadata with version tracking
metadata = SDKMetadata(
    name="gcu_gimbal",
    version="V2.0.6",
    protocol=CommunicationProtocol.SERIAL,
    source_url="https://github.com/xianfei/GCU-SDK",
    doc_url="https://docs.xianfei.com/gcu",
    license="Proprietary",
    hardware_models=["Z-2Mini", "A5 Gimbal"],
)

# Transform SDK to MCP server
result = transformer.transform_sdk(
    metadata=metadata,
    sdk_path=Path("./sdk/xianfei"),
    output_path=Path("./generated/gcu_gimbal")
)

print(f"Generated files: {result}")

Generated Output Structure

Each transformation generates:

generated/{sdk_name}/
├── {sdk_name}_mcp_server.py   # Main MCP server with:
│                               # - SDK version metadata
│                               # - Safety constraint validation
│                               # - Error code handling
│                               # - Hardware-specific bridge class
│
├── README.md                   # Comprehensive documentation:
│                               # - SDK version info
│                               # - Source references
│                               # - Safety limits table
│                               # - Error code reference
│                               # - Troubleshooting guide
│
├── sdk_metadata.json           # Machine-readable metadata:
│                               # - name, version, checksum
│                               # - source_url, doc_url
│                               # - hardware_models
│
└── mcp_config.json             # MCP client configuration

---

🏗️ Architecture

The enhanced SDK-to-MCP pipeline consists of 8 phases:

┌─────────────────────────────────────────────────────────────┐
│  Phase 1: SDK Discovery & Metadata Extraction               │
│  - SDK version detection (package.json, setup.py, etc.)     │
│  - Source URL extraction                                    │
│  - Checksum calculation for integrity tracking              │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 2: Protocol Analysis                                 │
│  - PDF protocol extraction (GCU, proprietary)               │
│  - Code parsing (ROS/DDS topics, services)                  │
│  - Command mapping and data structure extraction            │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 3: Safety Constraint Extraction                      │
│  - Hardware limit detection from docs                       │
│  - Velocity/position/torque limits                          │
│  - Safety level classification (CRITICAL/HIGH/MEDIUM)       │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 4: Error Code Mapping                                │
│  - Extract error codes from SDK headers                     │
│  - Map error names to descriptions                          │
│  - Define recovery actions                                  │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 5: Hardware Specification                            │
│  - Extract hardware specs from datasheets                   │
│  - Dimensions, weight, power consumption                    │
│  - Communication interfaces                                 │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 6: MCP Server Generation                             │
│  - Generate bridge class with protocol implementation       │
│  - Create MCP tools with safety validation                  │
│  - Add comprehensive docstrings                             │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 7: Documentation Generation                          │
│  - Generate README with version info                        │
│  - Create safety limits table                               │
│  - Document error codes and troubleshooting                 │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│  Phase 8: Metadata Export                                   │
│  - Export sdk_metadata.json                                 │
│  - Generate mcp_config.json                                 │
│  - Verify checksums match                                   │
└─────────────────────────────────────────────────────────────┘

---

🛡️ Safety Features

All generated MCP servers include comprehensive safety features:

Safety Constraint System

# Example from generated GCU Gimbal MCP server
SAFETY_LIMITS = {
    "pitch_speed": {
        "min": -150.0,
        "max": 150.0,
        "units": "°/s",
        "safety_level": "high",
        "hardware_limit": True,
        "software_guard": True,
        "descriptio