# lpigeon/ros-mcp-server architecture

> Architecture diagram of the GitHub repository lpigeon/ros-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/lpigeon/ros-mcp-server
- Repository: https://github.com/lpigeon/ros-mcp-server

## Overview

##### Project type and purpose
- This is a middleware robotics service (“ROS MCP Server”) that exposes a WebSocket-based Model Context Protocol (MCP) interface for converting natural-language/LLM requests into ROS/ROS2 commands via rosbridge.
- It sits between any LLM or AI client and a running ROS/ROS2 ecosystem, translating function calls into topic publishes or service calls.

##### File structure
- Top level
- server.py: entry point for the WebSocket MCP server
- Dockerfile: containerizes the MCP server
- smithery.yaml: Smithery installer config
- pyproject.toml / uv.lock: Python project and dependency lock files
- MCPFUNCTIONS.md: lists the exposed robot control functions
- Directories
- msgs/: Python definitions for ROS message types (geometry_msgs/Twist, sensor_msgs/Image, sensor_msgs/JointState)
- utils/websocket_manager.py: manages WebSocket connections to clients and to rosbridge
- img/: static images (used in README)
- Configuration
- mcp.json (user-provided) configures how Claude or other clients launch server.py via uv

##### Key architectural insights from the README
- The server uses rosbridge_websocket on ROS 1 or ROS 2 to talk to the robot’s topics/services.
- Clients connect over WebSocket to server.py, send MCP function calls, receive responses.
- The server can optionally invoke native ROS/ROS2 libraries directly instead of rosbridge.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    subgraph "AI Client Layer"
        direction TB
        Client["LLM/AI Client (WebSocket)"]:::client
    end

    %% MCP Server Layer
    subgraph "MCP Server Layer"
        direction TB
        Server["MCP Server (server.py)"]:::mcp
        WSManager["WebSocket Manager"]:::mcp
        Dispatcher["MCP Function Dispatcher"]:::mcp
        subgraph "Message Models"
            direction TB
            GM_Twist["geometry_msgs/Twist"]:::mcp
            SM_Image["sensor_msgs/Image"]:::mcp
            SM_JointState["sensor_msgs/JointState"]:::mcp
        end
        OptionalNative["Native ROS Library Interface"]:::mcp
        DockerArtefact["Docker Container"]:::mcp
        SmitheryCfg["Smithery Config"]:::mcp
        PyProj["pyproject.toml / uv.lock"]:::mcp
        StaticImg["Static Assets (img/)"]:::mcp
    end

    %% ROS Bridge Layer
    subgraph "ROS Bridge Layer"
        direction TB
        Rosbridge["rosbridge_websocket"]:::bridge
    end

    %% ROS Ecosystem Layer
    subgraph "ROS Ecosystem"
        direction TB
        ROSCore["ROS Core"]:::roscore
        ROSNodes["Robot Nodes (topics/services)"]:::roscore
    end

    %% Connections
    Client -->|"MCP function calls"| Server
    Server -->|"manages sockets"| WSManager
    WSManager -->|"forwards MCP calls"| Rosbridge
    Dispatcher -->|"loads functions from MCPFUNCTIONS.md"| Dispatcher
    Dispatcher -->|">> uses"| GM_Twist
    Dispatcher -->|">> uses"| SM_Image
    Dispatcher -->|">> uses"| SM_JointState
    Server -->|"optional"| OptionalNative
    Rosbridge -->|"publishes/subscribes"| ROSCore
    ROSCore -->|"routes to"| ROSNodes
    ROSNodes -->|"responses"| Rosbridge
    Rosbridge -->|"forwards responses"| WSManager
    WSManager -->|"sends responses"| Client

    %% Click Events
    click Server "https://github.com/lpigeon/ros-mcp-server/blob/main/server.py"
    click WSManager "https://github.com/lpigeon/ros-mcp-server/blob/main/utils/websocket_manager.py"
    click Dispatcher "https://github.com/lpigeon/ros-mcp-server/blob/main/MCPFUNCTIONS.md"
    click GM_Twist "https://github.com/lpigeon/ros-mcp-server/blob/main/msgs/geometry_msgs/twist.py"
    click SM_Image "https://github.com/lpigeon/ros-mcp-server/blob/main/msgs/sensor_msgs/image.py"
    click SM_JointState "https://github.com/lpigeon/ros-mcp-server/blob/main/msgs/sensor_msgs/jointstate.py"
    click GM_Twist "https://github.com/lpigeon/ros-mcp-server/blob/main/msgs/geometry_msgs/__init__.py"
    click SM_Image "https://github.com/lpigeon/ros-mcp-server/blob/main/msgs/sensor_msgs/__init__.py"
    click DockerArtefact "https://github.com/lpigeon/ros-mcp-server/tree/main/Dockerfile"
    click SmitheryCfg "https://github.com/lpigeon/ros-mcp-server/blob/main/smithery.yaml"
    click PyProj "https://github.com/lpigeon/ros-mcp-server/blob/main/pyproject.toml"
    click PyProj "https://github.com/lpigeon/ros-mcp-server/blob/main/uv.lock"
    click StaticImg "https://github.com/lpigeon/ros-mcp-server/tree/main/img/"

    %% Styles
    classDef client fill:#C3E0FF,stroke:#2B7CE9,color:#000
    classDef mcp fill:#D4F8C4,stroke:#2D862D,color:#000
    classDef bridge fill:#FFD8A8,stroke:#D97706,color:#000
    classDef roscore fill:#F0F0F0,stroke:#6B7280,color:#000
```
