MCP Autogui Multinode

🚀 PyAutoGUI用MCPとHTTPサーバーラッパー

このサービスは、LLMがマウスとキーボードを制御できるようにする、PyAutoGUI用のMCPとHTTPサーバーラッパーです。

🚀 クイックスタート

前提条件

• Python >= 3.12
• uv パッケージマネージャー（推奨）

インストール

1. リポジトリをクローンします。

git clone https://github.com/stonehill-2345/mcp-autogui-multinode.git
cd mcp-autogui-multinode

2. デプロイメントシナリオに基づいて依存関係をインストールします。

ローカルフル開発

すべての機能（GUI制御 + テスト）を備えたローカル開発用：

uv sync --group gui --group dev

MCPサーバーのみデプロイ

リモートツールサービスに接続するMCPサーバーをデプロイする場合（GUI依存関係は不要）：

uv sync --no-group gui

ツールサービスのみデプロイ

実際のコンピューター制御を行うHTTPツールサービスをデプロイする場合（GUIが必要）：

uv sync --group gui

サービスの起動

このサービスは2つの独立したサーバーをサポートしています。

1. ツールサービス（HTTP API）を起動

コンピューター制御のためのHTTP APIサーバーを起動します。

uv run python tool.py

2. MCPサーバーを起動

リモートツールサービスに接続できるMCPサーバーを起動します。このサーバーは2つのトランスポートモードをサポートしています。

HTTPトランスポートモード：

uv run python mcp_local.py http

stdioトランスポートモード（デフォルト）：

uv run python mcp_local.py stdio

起動後、以下のURLにアクセスできます。

• HTTP APIドキュメント：http://localhost:8000/docs
• ヘルスチェック：http://localhost:8000/health
• MCPエンドポイント：http://localhost:8001/mcp（HTTPトランスポートを使用する場合）

✨ 主な機能

• 🚀 デュアルプロトコルサポート：HTTP REST APIとMCP（Model Context Protocol）
• 🔐 APIキー認証：サービス間通信のためのオプションのAPIキー認証
• 🌐 複数のMCPトランスポート：HTTPとstdio（標準入出力）の両方のトランスポートモードをサポート
• 🖱️ マウス制御：移動、クリック、ドラッグ、スクロール操作
• ⌨️ キーボード制御：キーの押下、テキスト入力、キーの組み合わせ
• 📸 スクリーンショット：画面をキャプチャし、Base64エンコードされた画像を取得
• 📊 画面情報：カーソル位置と画面解像度を取得
• ⚙️ 設定管理：環境変数をサポートするPydantic設定
• 📝 自動ドキュメント化：HTTP APIのSwagger UI
• 🔧 柔軟なデプロイメント：HTTPサーバーまたはMCPサーバーを独立して実行
• 📋 リクエストトレーシング：リクエスト追跡のためのリクエストIDミドルウェア
• 📝 構造化ロギング：リクエストIDを統合したLoguruベースのロギング
• 🔌 リモートMCPサポート：リモートツールサーバーの統合のためのオプションのHTTPクライアント

📦 インストール

前提条件

• Python >= 3.12
• uv パッケージマネージャー（推奨）

手順

1. リポジトリをクローンします。

git clone https://github.com/stonehill-2345/mcp-autogui-multinode.git
cd mcp-autogui-multinode

2. デプロイメントシナリオに基づいて依存関係をインストールします。

ローカルフル開発

すべての機能（GUI制御 + テスト）を備えたローカル開発用：

uv sync --group gui --group dev

MCPサーバーのみデプロイ

リモートツールサービスに接続するMCPサーバーをデプロイする場合（GUI依存関係は不要）：

uv sync --no-group gui

ツールサービスのみデプロイ

実際のコンピューター制御を行うHTTPツールサービスをデプロイする場合（GUIが必要）：

uv sync --group gui

💻 使用例

基本的な使用法

マウスを移動する

curl -X POST "http://localhost:8000/api/computer/MoveMouse" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-api-key-here" \
  -d '{"x": 100, "y": 200}'

マウスをクリックする

curl -X POST "http://localhost:8000/api/computer/ClickMouse" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-api-key-here" \
  -d '{"x": 100, "y": 200, "button": "left"}'

スクリーンショットを撮る

curl -X POST "http://localhost:8000/api/computer/TakeScreenshot" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-api-key-here" \
  -d '{}'

カーソル位置を取得する

curl -X POST "http://localhost:8000/api/computer/GetCursorPosition" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-secret-api-key-here" \
  -d '{}'

📚 ドキュメント

APIエンドポイント

基本エンドポイント

• GET / - ルートパス、API情報を返します。
• GET /health - ヘルスチェックエンドポイント

コンピューター制御エンドポイント

すべてのコンピューター制御アクションは以下のエンドポイントで利用できます。

• POST /api/computer/{action} - コンピューター制御アクションを実行します。
• GET /api/computer/actions - 利用可能なすべてのアクションをリストします。

利用可能なアクション

MCPツール

利用可能なMCPツール

すべてのHTTP APIアクションはMCPツールとして利用できます。MCPツール名はスネークケースを使用し、HTTP APIはパスカルケースを使用します。

• move_mouse - マウスカーソルを移動します（HTTP: MoveMouse）
• click_mouse - マウスボタンをクリックします（HTTP: ClickMouse）
• press_mouse - マウスボタンを押します（HTTP: PressMouse）
• release_mouse - マウスボタンを離します（HTTP: ReleaseMouse）
• drag_mouse - マウスをドラッグします（HTTP: DragMouse）
• scroll - マウスホイールをスクロールします（HTTP: Scroll）
• press_key - キーボードのキーを押します（HTTP: PressKey）
• type_text - テキストを入力します（HTTP: TypeText）
• wait - 指定された時間待機します（HTTP: Wait）
• take_screenshot - スクリーンショットを撮ります（HTTP: TakeScreenshot）
• get_cursor_position - カーソル位置を取得します（HTTP: GetCursorPosition）
• get_screen_size - 画面サイズを取得します（HTTP: GetScreenSize）

MCPトランスポートモード

MCPサーバーは2つのトランスポートモードをサポートしています。

1. stdio（デフォルト）：標準入出力トランスポート
   • stdin/stdoutを介したローカル通信に使用されます。
   • MCPクライアントとの直接統合に適しています。
   • 起動コマンド：python mcp_local.py stdio
2. http：ステートレスモードのHTTPベースのトランスポート
   • HTTPを介したリモート通信に使用されます。
   • サービス間通信に適しています。
   • 起動コマンド：python mcp_local.py http
   • アクセス可能なURL：http://localhost:8001/mcp

MCPツール登録モード

このサービスは2つのMCPツール登録モードをサポートしています。

1. ダイレクトツール (register_computer_tools)：ローカルコンピューター制御実装を直接呼び出すツール。endpointパラメーターは不要です。
   • mcp_local.pyでローカルMCPサーバーに使用されます。
   • ツールはコンピューター制御アクションを直接実行します。
2. クライアントベースのツール (register_computer_tools_with_client)：HTTPクライアントを使用してリモートツールサーバーを呼び出すツール。endpointパラメーターが必要です。
   • mcp_server/register.pyでリモートMCPサーバーに使用されます。
   • ツールはHTTPを介してリモートツールサービスにリクエストを転送します。

ローカルMCPサーバー (mcp_local.py) はデフォルトでダイレクトツールを使用します。リモートMCPサーバーはクライアントベースのツールを使用します。

🔧 技術詳細

アーキテクチャ

このサービスは2つのデプロイメントアーキテクチャをサポートしています。

LLM -> MCP -> TOOL (リモートツールサービス)

このアーキテクチャでは、MCPサーバーとツールサービスが分離されており、MCPサーバーはHTTPを介してリモートツールサービスに接続できます。

graph LR
    LLM[LLM Client] -->|MCP Protocol| MCP[MCP Server<br/>main.py<br/>Client-based Tools]
    MCP -->|HTTP API<br/>with API Key| TOOLA[Tool Service<br/>tool.py<br/>HTTP API Server]
    MCP -->|HTTP API<br/>with API Key| TOOLB[Tool Service<br/>tool.py<br/>HTTP API Server]

    TOOLA -->|PyAutoGUI| COMPUTERA[Computer Control]
    TOOLB -->|PyAutoGUI| COMPUTERB[Computer Control]
    style LLM fill:#e1f5ff
    style MCP fill:#fff4e1
    style TOOLA fill:#ffe1f5
    style COMPUTERA fill:#e1ffe1
    style COMPUTERB fill:#e1ffe1

特徴：

• MCPサーバーはクライアントベースのツール (register_computer_tools_with_client) を使用します。
• MCPサーバーはHTTPを介してリモートツールサービスにリクエストを転送します。
• ツールサービスは実際のコンピューター制御操作を実行します。
• MCPサーバーとツールサービスが異なるマシンで実行される分散デプロイメントに適しています。
• MCPツール呼び出しにはendpointパラメーターが必要です。

アーキテクチャ2: LLM -> MCP (ダイレクトツール)

このアーキテクチャでは、MCPサーバーが直接コンピューター制御操作を実行します。

graph LR
    LLM[LLM Client] -->|MCP Protocol<br/>stdio/http| MCP[MCP Server<br/>mcp_local.py<br/>Direct Tools]
    MCP -->|PyAutoGUI| COMPUTER[Computer Control]
    
    style LLM fill:#e1f5ff
    style MCP fill:#fff4e1
    style COMPUTER fill:#e1ffe1

特徴：

• MCPサーバーはダイレクトツール (register_computer_tools) を使用します。
• MCPサーバーは直接コンピューター制御操作を実行します。
• 別のツールサービスは必要ありません。
• すべてが同じマシンで実行されるローカルデプロイメントに適しています。
• MCPツール呼び出しにはendpointパラメーターは必要ありません。

📄 ライセンス

MITライセンス

トラブルシューティング

ポートがすでに使用されている場合

ポートがすでに使用されているエラーが発生した場合は、.envファイルでポートを変更します。

PORT=8002
MCP_PORT=8003

MCP接続問題

HTTPトランスポートの場合、MCPサーバーが実行中でアクセス可能であることを確認します。

# MCPエンドポイントをテストする
curl http://localhost:8001/mcp

# APIキーが有効な場合のテスト
curl -H "X-API-Key: your-secret-api-key-here" http://localhost:8001/mcp

stdioトランスポートの場合、MCPサーバーがstdioモードで起動されていることを確認します。

# stdioモードでMCPサーバーを起動する
uv python mcp_local.py stdio

APIキー認証問題

認証エラーが発生した場合は、以下を確認します。

• .envファイルでAPI_KEY_ENABLEDが正しく設定されていること。
• API_KEYがクライアントとサーバーで一致していること。
• APIキーがX-API-KeyヘッダーまたはAuthorization: Bearer <key>ヘッダーで渡されていること。
• リクエストパスが除外パスリストに含まれていないこと。

スクリーンショット問題

スクリーンショット機能が失敗した場合は、以下を確認します。

• Pythonバージョンの互換性（Python >= 3.12が必要）。
• macOS/Linuxでのディスプレイ権限。
• PyAutoGUIとその依存関係が正しくインストールされていること。

コントリビュート

コントリビューションは大歓迎です！プルリクエストを送信してください。