mcp-gs-robot 0.1.4

Gausium OpenAPI MCP Server - Control Gausium robots through Claude

Gausium OpenAPI MCP Server

This project implements an MCP (Model Control Protocol) server that acts as a bridge to the Gausium OpenAPI, allowing AI models or other clients to interact with Gausium robots through a standardized interface.

Repository: https://github.com/cfrs2005/mcp-gs-robot

Architecture

The server follows a layered architecture that separates concerns and promotes maintainability:

MCP Protocol Flow

The diagram below shows how AI models interact with Gausium robots through the MCP protocol:

Features

The server currently supports the following functionalities as MCP tools:

• list_robots: Lists robots accessible via the API key. (Based on: List Robots API)
• get_robot_status: Fetches the detailed status of a specific robot by its serial number. (Based on: Get Robot Status API)
• list_robot_task_reports: Retrieves cleaning task reports for a specific robot, with optional time filtering. (Based on: List Robot Task Reports API)
• list_robot_maps: Lists the maps associated with a specific robot. (Based on: List Robot Maps API)

Project Structure

The project follows a structured layout based on Python best practices:

. 
├── .venv/                # Virtual environment directory
├── src/
│   └── gs_openapi/
│       ├── __init__.py
│       ├── api/            # Modules for direct API interactions
│       │   ├── __init__.py
│       │   ├── maps.py
│       │   └── robots.py
│       ├── auth/           # Authentication related modules
│       │   ├── __init__.py
│       │   └── token_manager.py # Handles OAuth token lifecycle
│       ├── config.py       # Configuration (URLs, Env Vars)
│       └── mcp/            # MCP server specific implementations
│           ├── __init__.py
│           └── gausium_mcp.py # GausiumMCP class extending FastMCP
├── .gitignore
├── docs/
│   └── images/            # Documentation images
├── main.py               # Main application entry point, tool registration, server run
├── README.md             # This file
└── requirements.txt      # Project dependencies

• src/gs_openapi/config.py: Contains base URLs, API paths, and environment variable names.
• src/gs_openapi/auth/token_manager.py: Manages acquiring and refreshing OAuth tokens.
• src/gs_openapi/api/: Contains modules (robots.py, maps.py) with functions that directly call the Gausium OpenAPI endpoints using httpx.
• src/gs_openapi/mcp/gausium_mcp.py: Defines the GausiumMCP class which integrates the API calls and token management.
• main.py: Initializes GausiumMCP, registers the API functionalities as MCP tools using @mcp.tool(), configures basic logging, and starts the server using mcp.run().

Setup and Running

1. Clone the repository:

   git clone https://github.com/cfrs2005/mcp-gs-robot.git
   cd mcp-gs-robot
   

2. Create and activate a virtual environment using uv:

   uv venv
   source .venv/bin/activate  # On Windows use `.venv\Scripts\activate`
   

3. Install dependencies using uv:

   uv pip install -r requirements.txt 
   # Or, if you prefer adding specific core packages:
   # uv add httpx "mcp[cli]"
   

4. Configure Credentials: The application expects Gausium API credentials to be set as environment variables:

   • GS_CLIENT_ID: Your Gausium Application Client ID.
   • GS_CLIENT_SECRET: Your Gausium Application Client Secret.
   • GS_OPEN_ACCESS_KEY: Your Gausium OpenAPI Access Key.

   You can set these directly in your shell:

   export GS_CLIENT_ID="your_client_id"
   export GS_CLIENT_SECRET="your_client_secret"
   export GS_OPEN_ACCESS_KEY="your_access_key"
   

   (Alternatively, modify src/gs_openapi/config.py for development, but do not commit credentials).

5. Run the server:

   python main.py
   

   By default, this starts the server using SSE transport on http://0.0.0.0:8000. You can modify main.py to use stdio transport if needed.

Connecting an MCP Client

Once the server is running, an MCP client (like Cursor or another compatible tool) can connect to it via the appropriate transport (SSE or stdio) to utilize the defined tools.

Usage with Cursor

Below is an example of how Cursor interacts with this MCP server:

Debugging

You can monitor the server logs for debugging information. The basic logging configuration in main.py provides timestamps, levels, and source information.

Below is an example of the server log output during operation: