Gausium OpenAPI MCP 服务器

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

存储库： https://github.com/cfrs2005/mcp-gs-robot

建筑学

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

MCP 协议流程

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

Related MCP server: ROS2 MCP Server

特征

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

• list_robots ：列出可通过 API 密钥访问的机器人。（基于： List Robots 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  # On Windows use `.venv\Scripts\activate`

3. 使用uv安装依赖项：

   uv pip install -r requirements.txt 
   # Or, if you prefer adding specific core packages:
   # 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 如何与此 MCP 服务器交互的示例：

调试

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

以下是运行过程中服务器日志输出示例：