Controller MCP

🚀 XboxコントローラーMCPサーバー

FastMCPとvgamepadを使用して、Xboxコントローラーのエミュレーション機能を提供するMCP（Model Context Protocol）サーバーです。

✨ 主な機能

• ボタン制御：Xboxコントローラーの任意のボタンを押下、解放、またはタップできます。
• アナログスティック：左右のアナログスティックの位置を制御できます。
• トリガー：左右のトリガーの値を設定できます。
• 状態管理：現在のコントローラーの状態を取得し、中立状態にリセットできます。
• シミュレーションモード：ハードウェアドライバーなしで動作し、テストや開発に利用できます。
• ハードウェアモード：ViGEmBusドライバーを使用した完全な仮想コントローラーのサポートがあります。
• クロスプラットフォーム：Windows（主な対象）で動作し、潜在的にLinuxでもサポートされます。

📦 インストール

uvを使用する（推奨）

1. このリポジトリをクローンまたはダウンロードします。
2. uvを使用して依存関係をインストールします。

uv sync

これにより、仮想環境が作成され、pyproject.tomlからすべての依存関係がインストールされます。

代替案：pipを使用する

pipを使用する場合は、以下のコマンドを実行します。

pip install -r requirements.txt

ハードウェアモード用（オプション）

実際のコントローラー入力を有効にするには（シミュレーションモードではなく）、以下の手順を実行します。

1. ViGEmBusドライバーをインストールします。
   • ダウンロード先：https://github.com/ViGEm/ViGEmBus/releases
   • ViGEmBus_Setup_x64.exeを管理者として実行します。
   • システムを再起動します。 ViGEmBusドライバーがない場合、サーバーはシミュレーションモードで実行され、コントローラーの状態は追跡されますが、実際の入力はシステムに送信されません。

💻 使用例

MCPサーバーの起動

uvを使用する場合：

uv run main.py

または、Pythonを直接使用する場合：

python main.py

サーバーが起動し、MCP接続を待機します。ViGEmBusが利用可能かどうかを自動的に検出し、ハードウェアモードまたはシミュレーションモードで実行します。

利用可能なツール

ボタン制御

• press_button(button)：コントローラーのボタンを押下します。
• release_button(button)：コントローラーのボタンを解放します。
• tap_button(button, duration=0.1)：ボタンをタップします（押下と解放）。

アナログ制御

• set_left_stick(x, y)：左スティックの位置を設定します（-1.0から1.0）。
• set_right_stick(x, y)：右スティックの位置を設定します（-1.0から1.0）。
• set_triggers(left, right)：トリガーの値を設定します（0.0から1.0）。

状態管理

• reset_controller()：コントローラーを中立状態にリセットします。
• get_controller_state()：現在のコントローラーの状態を取得します。
• list_available_buttons()：利用可能なすべてのボタン名をリストします。
• get_system_info()：システム情報と設定状態を取得します。

利用可能なボタン

• フェイスボタン：A、B、X、Y
• ショルダーボタン：LB、RB
• メニューボタン：BACK、START
• スティッククリック：LS、RS
• 方向パッド：DPAD_UP、DPAD_DOWN、DPAD_LEFT、DPAD_RIGHT

MCPクライアントでの使用例

# Aボタンを押下する
await client.call_tool("press_button", {"button": "A"})

# 左スティックを右上に移動する
await client.call_tool("set_left_stick", {"x": 0.5, "y": 0.5})

# 両方のトリガーを半分押下する
await client.call_tool("set_triggers", {"left": 0.5, "right": 0.5})

# Xボタンを0.2秒間タップする
await client.call_tool("tap_button", {"button": "X", "duration": 0.2})

# すべてをリセットする
await client.call_tool("reset_controller", {})

🔧 技術詳細

• FastMCP：MCPサーバーフレームワークを提供します。
• vgamepad：仮想Xboxコントローラーの作成と入力注入を処理します。
• Pydantic：データの検証とシリアル化を行います。
• デュアルモード動作：
  • ハードウェアモード：ViGEmBusドライバーを使用した完全な仮想コントローラー。
  • シミュレーションモード：実際の入力なしで状態を追跡する（フォールバックモード）。

座標系

アナログスティック

• 範囲：X軸とY軸の両方で-1.0から1.0。
• X軸：-1.0（左）から1.0（右）。
• Y軸：-1.0（下）から1.0（上）。

トリガー

• 範囲：0.0（押下されていない）から1.0（完全に押下された）。

📚 ドキュメント

プロジェクトファイル

• main.py：Xboxコントローラーのエミュレーションを備えた主要なMCPサーバーの実装。
• pyproject.toml：プロジェクトの構成と依存関係（uv/pip互換）。
• requirements.txt：pipユーザー用のPython依存関係。
• uv.lock：正確な依存関係のバージョンのロックファイル（uv）。
• mcp-config.json：MCPクライアントの設定ファイル。
• README.md：このドキュメント。

MCPクライアントの設定

このサーバーをClaude Desktopまたは他のMCPクライアントで使用するには、mcp-config.jsonの設定をMCPクライアントの設定に追加します。

{
  "mcpServers": {
    "xbox-controller": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "c:\\Users\\blain\\Documents\\git\\controller_mcp",
      "env": {},
      "description": "Xbox Controller Emulator MCP Server - Provides tools to emulate Xbox controller inputs including buttons, analog sticks, and triggers. Supports both hardware mode (with ViGEmBus) and simulation mode."
    }
  }
}

uvを使用する場合

uvを使用する場合は、実行にuvを使用するように設定することもできます。

{
  "mcpServers": {
    "xbox-controller": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "c:\\Users\\blain\\Documents\\git\\controller_mcp",
      "env": {},
      "description": "Xbox Controller Emulator MCP Server - Provides tools to emulate Xbox controller inputs including buttons, analog sticks, and triggers. Supports both hardware mode (with ViGEmBus) and simulation mode."
    }
  }
}

トラブルシューティング

ハードウェアモードとシミュレーションモード

サーバーはViGEmBusドライバーが利用可能かどうかを自動的に検出します。

• ハードウェアモード：仮想コントローラーの入力がシステムに送信されます。
• シミュレーションモード：コントローラーの状態は追跡されますが、実際の入力はシステムに送信されません。 サーバーを起動するときのコンソール出力を確認して、どのモードがアクティブかを確認してください。

Windows

• 仮想デバイスを作成するための必要な権限があることを確認してください。
• 一部のウイルス対策ソフトが仮想デバイスの作成をブロックする場合があります。
• 初回実行時には管理者権限が必要な場合があります。
• ViGEmBusのインストールに失敗した場合でも、サーバーはシミュレーションモードで動作します。

ゲームアプリケーション

• ほとんどのゲームは自動的に仮想コントローラーを検出します（ハードウェアモードのみ）。
• Windowsの「ゲームコントローラー」設定でコントローラーが動作していることを確認できます。
• 一部のゲームでは、仮想コントローラーが唯一の接続されたコントローラーである必要がある場合があります。
• シミュレーションモードでは、実際のコントローラー入力はゲームに送信されません。

開発とテスト

• テストや開発にはシミュレーションモードを使用して、他のアプリケーションに影響を与えないようにします。
• get_system_info()ツールを使用して、現在のモードと設定状態を確認します。
• すべてのMCPツールは両方のモードで動作します - 実際の入力注入のみが異なります。

開発

プロジェクト構造

このプロジェクトは最新のPythonツールを使用しています。

• uv：高速な依存関係管理と仮想環境の作成。
• pyproject.toml：プロジェクトの構成。
• FastMCP：MCPサーバーの実装。
• Pydantic：データの検証。

新機能の追加

サーバーはモジュール化されて構築されています。新しい機能を追加するには、以下の手順を実行します。

1. main.pyのXboxControllerEmulatorクラスにメソッドを追加します。
2. @mcp.tool()デコレーターを使用して対応するMCPツールを作成します。
3. ドキュメントを更新します。
4. ハードウェアモードとシミュレーションモードの両方でテストします。

開発環境のセットアップ

1. リポジトリをクローンします。
2. 開発用の依存関係をインストールします。

uv sync --dev

3. サーバーを起動します。

uv run main.py

テスト

• サーバーにはハードウェアモードとシミュレーションモードの両方で包括的なロギングが含まれています。
• サーバーを起動し、MCPクライアントで接続することで個々の関数をテストします。
• get_system_info()ツールを使用して設定を確認します。
• すべての機能はハードウェア依存なしでテストできるシミュレーションモードで動作します。

📄 ライセンス

このプロジェクトはMITライセンスの下でライセンスされています。詳細については、LICENSEファイルを参照してください。

貢献

貢献は大歓迎です！バグや機能要求については、プルリクエストを送信したり、問題を報告したりしてください。