🤖 Gausium OpenAPI MCP服务器
](https://www.python.org/downloads/) ](https://pypi.org/project/mcp-gs-robot/)   
🔧 强大的MCP服务器将AI模型与Gausium机器人连接起来
*通过Claude、Cursor和其他人工智能助手控制和监控Gausium清洁机器人*
______________________________________________________________________
🌟 这是什么？
这个MCP（模型控制协议）服务器通过标准化的界面实现了AI模型和Gausium清洁机器人之间的无缝交互。非常适合使用Claude Code、Cursor和其他兼容MCP的AI工具构建智能自动化工作流程。
🔗 存储库：
🎯 关键利益
- 🤖 AI优先设计：专为AI助手集成而构建
- 🔄 实时控制：即时监控和指挥机器人
- 📊 丰富的数据访问：获取详细的状态、地图和任务报告
- 🛡️ 安全：使用环境变量进行基于OAuth的身份验证
- 🌐 通用：适用于Claude、Cursor和任何MCP客户端
🏗️ 建筑
服务器遵循分层架构，分离关注点并提高可维护性：
🔄 MCP协议流
下图显示了AI模型如何通过MCP协议与Gausium机器人交互：
✨ 特性
🛠️ 核心MCP工具
| 工具 | 描述 | 状态 |
|---|---|---|
🤖 list_robots | 列出所有可访问的机器人 | ✅ 准备好了 |
📊 get_robot_status | 获取详细的机器人状态和位置 | ✅ 准备好了 |
📋 list_robot_task_reports | 通过筛选检索清洁任务报告 | ✅ 准备好了 |
🗺️ list_robot_maps | 获取机器人导航的可用地图 | ✅ 准备好了 |
🎯 create_robot_command | 向机器人发送命令（启动/暂停/停止） | ✅ 准备好了 |
🏢 get_site_info | 获取建筑和楼层信息 | ✅ 准备好了 |
📍 get_map_subareas | 获取任务的详细区域信息 | ✅ 准备好了 |
🚀 submit_temp_task | 提交临时清洁任务 | ✅ 准备好了 |
🧠 智能路由工具（在v0.1.12中增强）
| 工具 | 描述 | 状态 |
|---|---|---|
🎯 get_robot_status_smart | 基于机器人系列的自动选择V1/V2 API | ✅ 准备好了 |
📊 get_task_reports_smart | 智能任务报告API路由 | ✅ 准备好了 |
🔍 get_robot_capabilities | 显示特定机器人支持的API | ✅ 准备好了 |
🔧 高级工作流
- 🎛️ 自动化任务执行：从状态完成工作流→ 任务选择→ 执行
- 📈 批量操作：同时处理多个机器人
- 🗺️ 地图管理：上传、下载和管理机器人地图
- 📊 报告生成：从任务报告生成PNG地图
- 🏗️ 基于站点的任务：使用建筑/楼层上下文创建高级任务
🤝 支持的机器人生产线
M线机器人（传统清洁机器人）
- OMNIE公司 （OMNIE系列）-多用途清洁机器人
- 真空40 （40系列）-真空吸尘机器人
- 洗涤器50 （50系列）-扫地机器人
- 洗涤器75 （75系列）-重型扫地机器人
S线机器人（高级智能机器人，包括SW系列）
- Phantas （S系列）-幻影智能清洁机器人
- 甲虫 （SW系列）-甲壳虫智能清洁机器人
📁 项目结构
该项目遵循为MCP开发优化的结构化布局：
🗂️ 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🔍 关键组件
| 组件 | 用途 | 图标 |
|---|---|---|
| config.py | 基本URL、API路径、环境变量 | ⚙️ |
| token_manager.py | OAuth令牌获取和刷新 | 🔐 |
| api/robots.py | 机器人状态、命令、任务报告 | 🤖 |
| api/maps.py | 地图列表、上传、下载 | 🗺️ |
| gausium_mcp.py | MCP服务器集成层 | 🌉 |
| task_engine.py | 自动化工作流编排 | 🎯 |
| main.py | 服务器初始化和工具注册 | 🚀 |
🚀 快速开始
📦 安装
选项1：从PyPI安装（推荐）
pip install mcp-gs-robot选项2：从源代码安装
# 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 .🔧 配置
设置您的Gausium API证书：
# 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"🔑 从获取凭据 Gausium开发者门户
🏃♂️ 运行服务器
# Start MCP server (stdio mode)
python -m gs_openapi.main
# or if installed via pip:
mcp-gs-robot✅ 服务器开始使用 stdio 运输（非常适合克劳德密码）
🔌 Claude代码集成
方法1：自动安装并设置环境
# 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"方法2：手动配置
添加到您的 claude_desktop_config.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"
}
}
}
}方法3：使用环境文件
如果你更喜欢使用 .env 文件：
# 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💡 备注：此MCP服务器使用 stdio 传输（不是SSE），非常适合Claude Code集成🎯 例子
📱 Claude代码使用
# 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集成
光标配置：
樱桃工作室配置：
🐛 调试
监视服务器日志以进行故障排除：
📖 文档
| 文件 | 目的 |
|---|---|
| 🎯 Claude代码集成 | 完整的Claude代码设置指南 |
| 📋 api参考 | 完整的API文件 |
| 🧪 测试指导 | 如何测试MCP服务器 |
| 🔧 配置 | 详细的设置说明 |
🤝 贡献
我们欢迎捐款！拜托：
- 🍴 分叉存储库
- 🌿 创建要素分支
- ✅ 为您的更改添加测试
- 📝 更新文档
- 🔄 提交拉取请求
📄 许可证
MIT许可证-请参阅 许可证 文件以获取详细信息。
🆘 支持
- 📝 问题
- 📧 电子邮件
- 📚 Gausium开发人员文档
______________________________________________________________________
由以下材料制成❤️ Claude Code社区
*实现人工智能驱动的机器人自动化，一次完成一项任务* 🤖✨