Controller MCP

🚀 Xbox 控制器 MCP 服務器

本項目是一個 MCP（模型上下文協議）服務器，藉助 FastMCP 和 vgamepad 實現了 Xbox 控制器模擬功能。它能模擬各種 Xbox 控制器操作，為開發和測試提供便利。

✨ 主要特性

• 按鍵控制：可按下、釋放或輕點任意 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 控制器模擬器 MCP 服務器 - 提供模擬 Xbox 控制器輸入的工具，包括按鍵、模擬搖桿和扳機。支持硬件模式（使用 ViGEmBus）和模擬模式。"
    }
  }
}

使用 uv 配置

若你使用 uv，也可將其配置為使用 uv 執行：

{
  "mcpServers": {
    "xbox-controller": {
      "command": "uv",
      "args": ["run", "main.py"],
      "cwd": "c:\\Users\\blain\\Documents\\git\\controller_mcp",
      "env": {},
      "description": "Xbox 控制器模擬器 MCP 服務器 - 提供模擬 Xbox 控制器輸入的工具，包括按鍵、模擬搖桿和扳機。支持硬件模式（使用 ViGEmBus）和模擬模式。"
    }
  }
}

故障排除

硬件模式與模擬模式

服務器會自動檢測 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 文件。

貢獻說明

歡迎貢獻代碼！請隨時提交拉取請求，或針對漏洞和功能需求提出問題。