GS Robot MCP Server

# 🤖 Gausium OpenAPI MCP Server <div align="center"> [](https://www.python.org/downloads/) [](https://pypi.org/project/mcp-gs-robot/) [](LICENSE) [](https://github.com/modelcontextprotocol) [](https://claude.ai/code) **🔧 A powerful MCP server bridging AI models with Gausium robots** *Control and monitor Gausium cleaning robots through Claude, Cursor, and other AI assistants* [🚀 Quick Start](https://github.com/cfrs2005/mcp-gs-robot#-quick-start) • [📖 Documentation](https://github.com/cfrs2005/mcp-gs-robot#-documentation) • [🛠️ Installation](https://github.com/cfrs2005/mcp-gs-robot#-installation-1) • [🎯 Examples](https://github.com/cfrs2005/mcp-gs-robot#-examples) • [🇨🇳 中文文档](https://github.com/cfrs2005/mcp-gs-robot/blob/main/README_CN.md) </div> --- ## 🌟 What is this? This MCP (Model Control Protocol) server enables seamless interaction between AI models and Gausium cleaning robots through a standardized interface. Perfect for building intelligent automation workflows with Claude Code, Cursor, and other MCP-compatible AI tools. **🔗 Repository:** [https://github.com/cfrs2005/mcp-gs-robot](https://github.com/cfrs2005/mcp-gs-robot) ### 🎯 Key Benefits - 🤖 **AI-First Design**: Built specifically for AI assistant integration - 🔄 **Real-time Control**: Monitor and command robots instantly - 📊 **Rich Data Access**: Get detailed status, maps, and task reports - 🛡️ **Secure**: OAuth-based authentication with environment variables - 🌐 **Universal**: Works with Claude, Cursor, and any MCP client ## 🏗️ 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 ### 🛠️ Core MCP Tools | Tool | Description | Status | |------|-------------|--------| | 🤖 `list_robots` | List all accessible robots | ✅ Ready | | 📊 `get_robot_status` | Get detailed robot status and position | ✅ Ready | | 📋 `list_robot_task_reports` | Retrieve cleaning task reports with filtering | ✅ Ready | | 🗺️ `list_robot_maps` | Get available maps for robot navigation | ✅ Ready | | 🎯 `create_robot_command` | Send commands to robots (start/pause/stop) | ✅ Ready | | 🏢 `get_site_info` | Get building and floor information | ✅ Ready | | 📍 `get_map_subareas` | Get detailed area information for tasks | ✅ Ready | | 🚀 `submit_temp_task` | Submit temporary cleaning tasks | ✅ Ready | ### 🧠 Smart Routing Tools (Enhanced in v0.1.12) | Tool | Description | Status | |------|-------------|--------| | 🎯 `get_robot_status_smart` | Auto-select V1/V2 API based on robot series | ✅ Ready | | 📊 `get_task_reports_smart` | Intelligent task report API routing | ✅ Ready | | 🔍 `get_robot_capabilities` | Show supported APIs for specific robot | ✅ Ready | ### 🔧 Advanced Workflows - 🎛️ **Automated Task Execution**: Complete workflows from status → task selection → execution - 📈 **Batch Operations**: Handle multiple robots simultaneously - 🗺️ **Map Management**: Upload, download, and manage robot maps - 📊 **Report Generation**: Generate PNG maps from task reports - 🏗️ **Site-based Tasks**: Advanced task creation with building/floor context ### 🤝 Supported Robot Lines #### M-line Robots (Traditional Cleaning Robots) - **OMNIE** (OMNIE series) - Multi-purpose cleaning robot - **Vacuum 40** (40 series) - Vacuum cleaning robot - **Scrubber 50** (50 series) - Floor scrubbing robot - **Scrubber 75** (75 series) - Heavy-duty floor scrubbing robot #### S-line Robots (Advanced Smart Robots, including SW series) - **Phantas** (S series) - Phantom intelligent cleaning robot - **BEETLE** (SW series) - Beetle smart cleaning robot ## 📁 Project Structure The project follows a structured layout optimized for MCP development: ``` 🗂️ mcp-gs-robot/ ├── 📦 src/gs_openapi/ # Main package │ ├── 🔌 api/ # Direct API integrations │ │ ├── 🤖 robots.py # Robot management APIs │ │ └── 🗺️ maps.py # Map management APIs │ ├── 🔐 auth/ # Authentication layer │ │ └── 🎫 token_manager.py # OAuth token lifecycle │ ├── ⚙️ config.py # Configuration management │ ├── 🔧 core/ # Core functionality │ │ ├── 📡 client.py # HTTP client wrapper │ │ └── 🛣️ endpoints.py # API endpoint definitions │ ├── 🔌 mcp/ # MCP server implementation │ │ └── 🌉 gausium_mcp.py # Main MCP bridge │ └── 🔄 workflows/ # Automated workflows │ └── 🎯 task_engine.py # Task automation engine ├── 📚 docs/ # Documentation │ ├── 🖼️ images/ # Visual documentation │ ├── 📖 apis.md # API documentation │ └── 🧪 TESTING_GUIDE.md # Testing instructions ├── 🚀 main.py # Application entry point └── 📋 pyproject.toml # Package configuration ``` ### 🔍 Key Components | Component | Purpose | Icon | |-----------|---------|------| | **config.py** | Base URLs, API paths, environment variables | ⚙️ | | **token_manager.py** | OAuth token acquisition and refresh | 🔐 | | **api/robots.py** | Robot status, commands, task reports | 🤖 | | **api/maps.py** | Map listing, upload, download | 🗺️ | | **gausium_mcp.py** | MCP server integration layer | 🌉 | | **task_engine.py** | Automated workflow orchestration | 🎯 | | **main.py** | Server initialization and tool registration | 🚀 | ## 🚀 Quick Start ### 📦 Installation #### Option 1: Install from PyPI (Recommended) ```bash pip install mcp-gs-robot ``` #### Option 2: Install from Source ```bash # Clone repository git clone https://github.com/cfrs2005/mcp-gs-robot.git cd mcp-gs-robot # Setup with uv (recommended) uv venv source .venv/bin/activate # Windows: .venv\Scripts\activate uv pip install -e . ``` ### 🔧 Configuration **Set up your Gausium API credentials:** ```bash # Required environment variables export GS_CLIENT_ID="your_client_id" export GS_CLIENT_SECRET="your_client_secret" export GS_OPEN_ACCESS_KEY="your_access_key" ``` > 🔑 **Get credentials from [Gausium Developer Portal](https://developer.gs-robot.com/)** ### 🏃‍♂️ Running the Server ```bash # Start MCP server (stdio mode) python -m gs_openapi.main # or if installed via pip: mcp-gs-robot ``` ✅ Server starts using `stdio` transport (perfect for Claude Code) ### 🔌 Claude Code Integration **Method 1: Automatic installation with environment setup** ```bash # Add MCP server with environment variables claude mcp add mcp-gs-robot \ --env GS_CLIENT_ID="your_client_id" \ --env GS_CLIENT_SECRET="your_client_secret" \ --env GS_OPEN_ACCESS_KEY="your_access_key" ``` **Method 2: Manual configuration** Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "mcp-gs-robot": { "command": "mcp-gs-robot", "env": { "GS_CLIENT_ID": "your_client_id", "GS_CLIENT_SECRET": "your_client_secret", "GS_OPEN_ACCESS_KEY": "your_access_key" } } } } ``` **Method 3: Using environment file** If you prefer to use a `.env` file: ```bash # Set global environment variables export GS_CLIENT_ID="your_client_id" export GS_CLIENT_SECRET="your_client_secret" export GS_OPEN_ACCESS_KEY="your_access_key" # Simple MCP installation claude mcp add mcp-gs-robot ``` > 💡 **Note**: This MCP server uses `stdio` transport (not SSE), which is perfect for Claude Code integration ## 🎯 Examples ### 📱 Claude Code Usage ```python # In Claude Code, you can now use natural language: "List all my robots" # → Calls mcp__mcp-gs-robot__list_robots "Get status of robot GS101-0100-V1P-B001" # → Calls mcp__mcp-gs-robot__get_robot_status "Start cleaning task for robot in building 5" # → Orchestrates site info → map selection → task creation ``` ### 🖥️ IDE Integration **Cursor Configuration:**  **Cherry Studio Configuration:**  ### 🐛 Debugging Monitor server logs for troubleshooting:  ## 📖 Documentation | Document | Purpose | |----------|----------| | 🎯 [Claude Code Integration](docs/CLAUDE_CODE_INTEGRATION.md) | Complete Claude Code setup guide | | 📋 [API Reference](docs/apis.md) | Complete API documentation | | 🧪 [Testing Guide](docs/TESTING_GUIDE.md) | How to test the MCP server | | 🔧 [Configuration](docs/README.md) | Detailed setup instructions | ## 🤝 Contributing We welcome contributions! Please: 1. 🍴 Fork the repository 2. 🌿 Create a feature branch 3. ✅ Add tests for your changes 4. 📝 Update documentation 5. 🔄 Submit a pull request ## 📄 License MIT License - see [LICENSE](LICENSE) file for details. ## 🆘 Support - 📝 [Issues](https://github.com/cfrs2005/mcp-gs-robot/issues) - 📧 [Email](mailto:cfrs2005@gmail.com) - 📚 [Gausium Developer Docs](https://developer.gs-robot.com/) --- <div align="center"> **Made with ❤️ for the Claude Code community** *Enabling AI-powered robot automation, one task at a time* 🤖✨ </div>