Ithreemcp

🚀 ithreemcp

ithreemcp 是一個 MCP 服務器，它能夠將所連接的 i3 窗口管理器的功能對外暴露。用戶可以通過 AI 助手，使用自然語言來控制 i3 窗口。你可以讓大語言模型（LLM）將窗口在不同工作區之間移動、聚焦應用程序、切換浮動模式等。

閱讀博客文章，瞭解該項目的誕生過程。

🚀 快速開始

要使用 ithreemcp，你需要滿足以下要求，並按照相應步驟進行安裝和運行。

✨ 主要特性

• 自然語言控制：藉助 AI 助手，使用自然語言對 i3 窗口進行控制。
• 豐富操作支持：支持移動窗口、聚焦應用、切換浮動模式等多種操作。

📦 安裝指南

從源代碼安裝

go install github.com/mschoch/ithreemcp@latest

或者手動克隆並構建：

git clone https://github.com/mschoch/ithreemcp.git
cd ithreemcp
go build

💻 使用示例

基礎用法

使用 ollmcp 快速啟動

這是使用 ithreemcp 最簡單的方法，需要藉助 ollmcp（一個適用於 Ollama 的 MCP 客戶端）。

1. 複製示例配置文件並根據你的環境進行調整：

cp ithreemcp.json.sample ithreemcp.json

2. 編輯 ithreemcp.json，確保 ithreemcp 的路徑正確，並且 DISPLAY 環境變量與你的設置匹配。
3. 使用你的配置文件運行 ollmcp：

uvx ollmcp --servers-json ithreemcp.json

現在你就可以與 Ollama 聊天，並讓它管理你的 i3 窗口了！

直接運行服務器

如果你要與其他 MCP 客戶端集成，可以直接運行服務器：

./ithreemcp

服務器通過標準輸入輸出使用 MCP 協議進行通信。

調試日誌

若要觀察 MCP 請求/響應流量（這對於瞭解 MCP 協議很有用），可以使用 --debug 標誌：

./ithreemcp --debug /tmp/mcp-debug.log

這會將所有 JSON-RPC 消息記錄到指定的文件中：

read: {"jsonrpc":"2.0","id":1,"method":"initialize","params":{...}}
write: {"jsonrpc":"2.0","id":1,"result":{...}}
read: {"jsonrpc":"2.0","method":"tools/call","params":{"name":"GetWorkspaces"}}
write: {"jsonrpc":"2.0","result":{...}}

高級用法

結合 FindWindows 和 RunCommand 進行窗口管理

FindWindows 和 RunCommand 工具結合使用，可以通過自然語言請求實現強大的窗口管理功能。

• 將窗口移動到另一個工作區
  • 用戶：“將 Firefox 移動到工作區 7”
  1. FindWindows(class: "firefox") → 找到窗口並返回其 con_id
  2. RunCommand(command: "[con_id=94285673947] move to workspace 7")
• 聚焦特定應用程序
  • 用戶：“切換到我的終端”
  1. FindWindows(class: "Alacritty") → 返回匹配的終端
  2. RunCommand(command: "[con_id=94285673948] focus")
• 關閉應用程序的所有窗口
  • 用戶：“關閉我所有的瀏覽器窗口”
  1. FindWindows(class: "firefox") → 返回所有 Firefox 窗口
  2. 對每個窗口執行：RunCommand(command: "[con_id=...] kill")
• 將窗口移動到暫存區
  • 用戶：“將 Slack 隱藏到暫存區”
  1. FindWindows(class: "Slack") → 找到 Slack 窗口
  2. RunCommand(command: "[con_id=94285673949] move scratchpad")
• 切換浮動模式
  • 用戶：“讓視頻播放器浮動”
  1. FindWindows(name: "VLC") → 通過窗口標題找到 VLC
  2. RunCommand(command: "[con_id=94285673950] floating toggle")
• 調整窗口大小
  • 用戶：“讓我的編輯器變寬”
  1. FindWindows(class: "code") → 找到 VS Code
  2. RunCommand(command: "[con_id=94285673951] resize grow width 200 px")
• 將窗口移動到特定輸出/顯示器
  • 用戶：“將這個窗口移動到我的外接顯示器” RunCommand(command: "[focused] move to output HDMI-1")
• 切換全屏模式
  • 用戶：“將我的瀏覽器全屏”
  1. FindWindows(class: "firefox")
  2. RunCommand(command: "[con_id=...] fullscreen toggle")

直接使用 i3 標準

對於簡單的情況，RunCommand 可以直接使用 i3 的內置標準，而無需使用 FindWindows：

RunCommand(command: "[class=\"firefox\"] move to workspace 7")
RunCommand(command: "[urgent=latest] focus")
RunCommand(command: "[workspace=3] move to workspace 5")

當按窗口類定位窗口時，這種方法很有用，但在以下情況下，建議使用 FindWindows：

• 按部分窗口標題進行搜索
• 在執行操作之前獲取匹配窗口的信息
• 分別處理多個匹配項
• 與用戶確認目標窗口

📚 詳細文檔

構建

go build

運行

前提條件：你需要運行 i3 窗口管理器，並具有訪問其套接字的權限。

支持的操作

GetTree

返回 i3 佈局樹，使用底層操作返回的確切格式。

GetWorkspaces

返回 i3 當前工作區的詳細信息。

FindWindows

搜索符合給定條件的窗口。返回匹配的窗口及其 con_id，可用於 RunCommand。 參數：

• name（可選） - 匹配窗口標題（不區分大小寫的子字符串）
• class（可選） - 匹配窗口類（例如，"firefox"，"Alacritty"）
• instance（可選） - 匹配窗口實例 返回：包含 con_id、name、class、instance、workspace 和 focused 狀態的窗口列表。

RunCommand

執行 i3 命令。使用 i3 命令語法 來指定條件和操作。 參數：

• command（必需） - 要執行的 i3 命令 返回：包含 success 狀態和可選 error 消息的結果數組。

🔧 技術細節

ithreemcp 程序是一個 MCP 服務器，允許 MCP 客戶端與運行中的 i3 窗口管理器進行交互。它使用 MCP Go SDK 來構建 MCP 服務器，封裝其功能。同時，它使用 go-i3 庫通過 IPC 接口與 i3 窗口管理器進行通信。

📄 許可證

本項目採用 Apache License 2.0 許可協議，詳情請參閱 LICENSE 文件。