PIB MCP Server

Ein Model Context Protocol (MCP) Server zur Steuerung des PIB-Roboters über natürliche Sprache mit LLMs.

Features

• 🤖 Inverse Kinematics: Bewege die Hand des Roboters zu einer gewünschten Position (x, y, z)
• 📐 Forward Kinematics: Berechne die Endeffektorposition aus Gelenkwinkeln
• 🎯 Gelenksteuerung: Setze spezifische Gelenkwinkel für präzise Kontrolle
• 💬 LLM-Integration: Nutze natürliche Sprache zur Robotersteuerung über Claude, ChatGPT, etc.

Installation

1. Voraussetzungen

• Python ≥ 3.9
• pip

2. Abhängigkeiten installieren

# Repository klonen oder in das Verzeichnis wechseln
cd pib-mcp

# Virtual Environment erstellen (empfohlen)
python -m venv venv

# Virtual Environment aktivieren
# Windows PowerShell:
.\venv\Scripts\Activate.ps1
# Windows CMD:
.\venv\Scripts\activate.bat
# Linux/Mac:
source venv/bin/activate

# Abhängigkeiten installieren
pip install mcp pib-sdk

Alternativ mit allen Abhängigkeiten aus pyproject.toml:

pip install -e .

Verwendung

Als MCP Server starten

python -m pib_mcp_server.server

Integration mit Claude Desktop

Füge folgende Konfiguration zu deiner Claude Desktop Config hinzu:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "pib-robot": {
      "command": "python",
      "args": [
        "-m",
        "pib_mcp_server.server"
      ],
      "cwd": "<PFAD_ZUM_PIB_MCP_ORDNER>"
    }
  }
}

Hinweis: Ersetze <PFAD_ZUM_PIB_MCP_ORDNER> durch den absoluten Pfad zu diesem Projekt!

Wenn du ein Virtual Environment verwendest, nutze den Python-Interpreter aus dem venv:

{
  "mcpServers": {
    "pib-robot": {
      "command": "<PFAD_ZUM_VENV>/Scripts/python.exe",
      "args": [
        "-m",
        "pib_mcp_server.server"
      ]
    }
  }
}

Windows: venv\Scripts\python.exe
macOS/Linux: venv/bin/python

Neustart von Claude Desktop

Nach der Konfiguration Claude Desktop neu starten, damit der MCP Server geladen wird.

Verfügbare Tools

1. move_hand_to_position

Bewegt die Hand des Roboters zu einer bestimmten Position im 3D-Raum.

Parameter:

• arm (string): "left" oder "right"
• x (number): X-Koordinate in Millimetern
• y (number): Y-Koordinate in Millimetern
• z (number): Z-Koordinate in Millimetern
• roll (number, optional): Roll-Winkel in Grad
• pitch (number, optional): Pitch-Winkel in Grad
• yaw (number, optional): Yaw-Winkel in Grad

Beispiel in Claude:

Bewege die rechte Hand des PIB-Roboters zur Position x=150, y=0, z=350

2. set_joint_angles

Setzt spezifische Gelenkwinkel für den Roboterarm.

Parameter:

• arm (string): "left" oder "right"
• joint1 bis joint6 (number): Gelenkwinkel in Grad

Beispiel in Claude:

Setze die Gelenkwinkel des rechten Arms auf: 0, 45, 0, 0, 90, 0

3. get_hand_position

Berechnet die Endeffektorposition aus gegebenen Gelenkwinkeln.

Parameter:

• arm (string): "left" oder "right"
• joint1 bis joint6 (number): Gelenkwinkel in Grad

Beispiel in Claude:

Wo befindet sich die Hand, wenn der rechte Arm folgende Winkel hat: 0, 45, 0, 0, 90, 0?

Beispiel-Konversationen mit Claude

Nach erfolgreicher Integration kannst du Claude folgende Anweisungen geben:

1. "Bewege die rechte Hand zur Position x=200, y=50, z=300"

   • Claude nutzt move_hand_to_position und berechnet die benötigten Gelenkwinkel

2. "Hebe die linke Hand 100mm höher als die aktuelle Position"

   • Claude kann die aktuelle Position abfragen und die neue Position berechnen

3. "Führe eine Greifbewegung aus"

   • Claude kann eine Sequenz von Bewegungen planen

Docker Deployment

Voraussetzung: Docker Desktop

Stelle sicher, dass Docker Desktop installiert und gestartet ist:

• Windows/macOS: Docker Desktop herunterladen
• Linux: Docker Engine installieren

Docker Image bauen

# Mit Docker Compose (empfohlen)
docker-compose build

# Oder direkt mit Docker
docker build -t pib-mcp-server:latest .

Mit Docker Desktop ausführen

Option 1: Docker Desktop GUI

1. Öffne Docker Desktop
2. Gehe zu "Images" → Suche pib-mcp-server:latest
3. Klicke auf "Run" → Wähle "Interactive" Modus
4. Container läuft nun und ist bereit für MCP-Kommunikation

Option 2: Kommandozeile

Windows (PowerShell/CMD):

# Image bauen
docker-compose build

# Container starten
docker run -i --rm pib-mcp-server:latest

Oder nutze das bereitgestellte Skript:

.\run-docker.bat

macOS/Linux:

# Skript ausführbar machen
chmod +x run-docker.sh

# Container starten
./run-docker.sh

Integration mit Claude Desktop (Docker Desktop)

Nachdem das Image gebaut wurde, füge diese Konfiguration zu deiner Claude Desktop Config hinzu:

Config-Pfad:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Methode 1: Direkter Docker-Befehl (empfohlen)

{
  "mcpServers": {
    "pib-robot": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "pib-mcp-server:latest"
      ]
    }
  }
}

Methode 2: Mit Wrapper-Skript (Windows)

{
  "mcpServers": {
    "pib-robot": {
      "command": "<PFAD_ZUM_PIB_MCP_ORDNER>\\run-docker.bat"
    }
  }
}

Methode 3: Mit Python-Wrapper

{
  "mcpServers": {
    "pib-robot": {
      "command": "python",
      "args": [
        "<PFAD_ZUM_PIB_MCP_ORDNER>/run-docker.py"
      ]
    }
  }
}

Wichtig:

• Das Docker Image muss vor der Nutzung mit docker-compose build gebaut werden
• Docker Desktop muss laufen
• Bei Änderungen am Code muss das Image neu gebaut werden: docker-compose build

Docker-Image-Verwaltung in Docker Desktop

Image neu bauen nach Code-Änderungen:

docker-compose build --no-cache

Laufende Container anzeigen:

docker ps

Logs anzeigen:

docker logs pib-mcp-server

Container stoppen:

docker stop pib-mcp-server

Aufräumen (alte Images/Container löschen):

docker system prune -a

Mit Docker Compose ausführen

# Starten
docker-compose up -d

# Logs anzeigen
docker-compose logs -f

# Stoppen
docker-compose down

Integration mit Claude Desktop (Docker)

In deiner Claude Desktop Config (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "pib-robot": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "pib-mcp-server"
      ]
    }
  }
}

Wichtig: Das Docker Image muss vorher gebaut worden sein!

Alternativ mit docker-compose:

{
  "mcpServers": {
    "pib-robot": {
      "command": "docker-compose",
      "args": [
        "-f",
        "<PFAD_ZUM_PIB_MCP_ORDNER>/docker-compose.yml",
        "run",
        "--rm",
        "pib-mcp-server"
      ]
    }
  }
}

Entwicklung

Tests ausführen

pip install -e ".[dev]"
pytest

Logging aktivieren

Der Server nutzt Python's logging. Für mehr Details:

import logging
logging.basicConfig(level=logging.DEBUG)

Technische Details

• MCP SDK: Verwendet das offizielle Model Context Protocol SDK
• pib-sdk: Nutzt die Robotics Toolbox für Forward/Inverse Kinematics
• Keine ROS/Gazebo Abhängigkeiten: Pure Python-Implementierung

Lizenz

AGPL-3.0 (gleiche Lizenz wie pib-sdk)

Hinweise

⚠️ Wichtig: Dieser Server berechnet nur die Gelenkwinkel. Die tatsächliche Bewegung des Roboters muss über den Roboter-Controller erfolgen. In einer vollständigen Implementation würdest du hier die Winkel an den Roboter senden.

Weiterführende Links

• PIB SDK Repository
• Model Context Protocol Documentation
• Claude Desktop MCP Guide