Gausium OpenAPI MCP サーバー

このプロジェクトは、Gausium OpenAPI へのブリッジとして機能する MCP (モデル制御プロトコル) サーバーを実装し、AI モデルやその他のクライアントが標準化されたインターフェースを介して Gausium ロボットと対話できるようにします。

リポジトリ: https://github.com/cfrs2005/mcp-gs-robot

建築

サーバーは、懸念事項を分離し保守性を促進する階層化アーキテクチャに従います。

MCPプロトコルフロー

下の図は、AI モデルが MCP プロトコルを介して Gausium ロボットと対話する方法を示しています。

Related MCP server: Eufy RoboVac MCP Server

特徴

サーバーは現在、MCP ツールとして次の機能をサポートしています。

• list_robots : APIキーでアクセスできるロボットを一覧表示します。( List Robots APIに基づいています)

• get_robot_status : 特定のロボットのシリアル番号から詳細なステータスを取得します。( Get Robot Status APIに基づく)

• list_robot_task_reports : 特定のロボットの清掃タスクレポートを取得します。オプションで時間フィルタリングも可能です。( List Robot Task Reports APIに基づいています)

• list_robot_maps : 特定のロボットに関連付けられたマップを一覧表示します。( 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/ : httpxを使用して Gausium OpenAPI エンドポイントを直接呼び出す関数を含むモジュール ( robots.py 、 maps.py ) が含まれています。

• 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 アクセス キー。

   これらはシェルで直接設定できます:

   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

   デフォルトでは、 http://0.0.0.0:8000でSSEトランスポートを使用してサーバーを起動します。必要に応じて、 main.py変更してstdioトランスポートを使用するように設定できます。

MCPクライアントの接続

サーバーが実行される場合、MCP クライアント (Cursor や他の互換性のあるツールなど) は適切なトランスポート (SSE または stdio) を介してサーバーに接続し、定義されたツールを利用できるようになります。

カーソルとの使用

以下は、Cursor がこの MCP サーバーと対話する方法の例です。

デバッグ

デバッグ情報を得るためにサーバーログを監視できます。main.py main.py基本的なログ設定では、タイムスタンプ、レベル、ソース情報が提供されます。

以下は操作中のサーバーログ出力の例です。