# GS机器人控制插件
## 基本信息
- Slug: `cfrs2005-mcp-gs-robot`
- Source: modelscope
- Publisher: @cfrs2005/mcp-gs-robot
- Categories: home-automation-and-iot / os-automation
- Hosted: No
- License: Unknown
- Source URL: https://www.modelscope.cn/mcp/servers/@cfrs2005/mcp-gs-robot
## 简介
一种用于控制GS清洁机器人的模型控制协议插件，支持机器人列表、状态监控、导航命令、任务执行和远程控制操作。
## 安装提示

```bash
. ├── .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
```

## MCP Server 详情

# Gausium OpenAPI MCP 服务器

该项目实现了一个MCP（模型控制协议）服务器，作为与Gausium OpenAPI之间的桥梁，允许AI模型或其他客户端通过标准化接口与Gausium机器人交互。

仓库: [https://github.com/cfrs2005/mcp-gs-robot](https://github.com/cfrs2005/mcp-gs-robot)

## 架构

该服务器遵循分层架构，分离关注点并促进可维护性：

![架构图](docs/images/architecture.svg)

### MCP 协议流程

下图展示了AI模型如何通过MCP协议与Gausium机器人进行交互：

![MCP 协议流程](docs/images/mcp-flow.svg)

## 功能

服务器当前支持以下功能作为MCP工具：

*   **`list_robots`**: 列出可通过API密钥访问的机器人。(基于: [列出机器人 API](https://developer.gs-robot.com/zh_CN/Robot%20Information%20Service/List%20Robots))
*   **`get_robot_status`**: 通过序列号获取特定机器人的详细状态。(基于: [获取机器人状态 API](https://developer.gs-robot.com/zh_CN/Robot%20Information%20Service/V1%20Get%20Robot%20Status))
*   **`list_robot_task_reports`**: 检索特定机器人的清洁任务报告，并可选择时间过滤。(基于: [列出机器人任务报告 API](https://developer.gs-robot.com/zh_CN/Robot%20Cleaning%20Data%20Service/V1%20List%20Robot%20Task%20Reports))
*   **`list_robot_maps`**: 列出与特定机器人关联的地图。(基于: [列出机器人地图 API](https://developer.gs-robot.com/zh_CN/Robot%20Map%20Service/V1%20List%20Robot%20Map))

## 项目结构

该项目遵循基于Python最佳实践的结构化布局：

```
. 
├── .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`**: 包含基础URL、API路径和环境变量名称。
*   **`src/gs_openapi/auth/token_manager.py`**: 管理获取和刷新OAuth令牌。
*   **`src/gs_openapi/api/`**: 包含模块（如 `robots.py`, `maps.py`），这些模块使用 `httpx` 直接调用Gausium OpenAPI端点。
*   **`src/gs_openapi/mcp/gausium_mcp.py`**: 定义了集成API调用和令牌管理的 `GausiumMCP` 类。
*   **`main.py`**: 初始化 `GausiumMCP`，使用 `@mcp.tool()` 注册API功能为MCP工具，配置基本日志记录，并使用 `mcp.run()` 启动服务器。

## 设置与运行

1.  **克隆仓库：**
    ```bash
    git clone https://github.com/cfrs2005/mcp-gs-robot.git
    cd mcp-gs-robot
    ```

2.  **使用 `uv` 创建并激活虚拟环境：**
    ```bash
    uv venv
    source .venv/bin/activate  # 在 Windows 上使用 `.venv\Scripts\activate`
    ```

3.  **使用 `uv` 安装依赖项：**
    ```bash
    uv pip install -r requirements.txt 
    # 或者，如果你更喜欢添加特定的核心包：
    # uv add httpx "mcp[cli]"
    ```

4.  **配置凭证：**
    应用程序期望 Gausium API 凭证设置为环境变量：
    *   `GS_CLIENT_ID`：你的 Gausium 应用客户端 ID。
    *   `GS_CLIENT_SECRET`：你的 Gausium 应用客户端密钥。
    *   `GS_OPEN_ACCESS_KEY`：你的 Gausium OpenAPI 访问密钥。

    你可以在 shell 中直接设置这些变量：
    ```bash
    export GS_CLIENT_ID="your_client_id"
    export GS_CLIENT_SECRET="your_client_secret"
    export GS_OPEN_ACCESS_KEY="your_access_key"
    ```
    （或者，修改 `src/gs_openapi/config.py` 用于开发，但**不要提交凭证**）。

5.  **运行服务器：**
    ```bash
    python main.py
    ```
    默认情况下，这将使用 SSE 传输在 `http://0.0.0.0:8000` 上启动服务器。如果需要，可以修改 `main.py` 以使用 `stdio` 传输。

## 连接 MCP 客户端

一旦服务器运行起来，MCP 客户端（如 Cursor 或其他兼容工具）可以通过适当的传输方式（SSE 或 stdio）连接到它，以利用已定义的工具。

### 使用 Cursor

下面是一个关于 Cursor 如何与此 MCP 服务器交互的例子：

![Cursor 使用截图](docs/images/cursor_usage_screenshot.png)

## 调试

你可以监控服务器日志以获取调试信息。`main.py` 中的基本日志配置提供了时间戳、级别和来源信息。

下面是服务器运行期间的日志输出示例：

![MCP 调试截图](docs/images/mcp_debug_screenshot.png)