Gausium OpenAPI MCP 服务器

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

仓库: https://github.com/cfrs2005/mcp-gs-robot

架构

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

MCP 协议流程

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

功能

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

• list_robots: 列出可通过API密钥访问的机器人。(基于: 列出机器人 API)
• get_robot_status: 通过序列号获取特定机器人的详细状态。(基于: 获取机器人状态 API)
• list_robot_task_reports: 检索特定机器人的清洁任务报告，并可选择时间过滤。(基于: 列出机器人任务报告 API)
• list_robot_maps: 列出与特定机器人关联的地图。(基于: 列出机器人地图 API)

项目结构

该项目遵循基于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. 克隆仓库：

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

2. 使用 uv 创建并激活虚拟环境：

   uv venv
   source .venv/bin/activate  # 在 Windows 上使用 `.venv\Scripts\activate`
   

3. 使用 uv 安装依赖项：

   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 中直接设置这些变量：

   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. 运行服务器：

   python main.py
   

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

连接 MCP 客户端

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

使用 Cursor

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

调试

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

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