JinDaGe - ithreemcp MCP Details

article

README

🚀 ithreemcp

ithreemcp 是一个 MCP 服务器，它能够将所连接的 i3 窗口管理器的功能对外暴露。用户可以通过 AI 助手，使用自然语言来控制 i3 窗口。你可以让大语言模型（LLM）将窗口在不同工作区之间移动、聚焦应用程序、切换浮动模式等。

ithreemcp 演示

阅读博客文章，了解该项目的诞生过程。

🚀 快速开始

要使用 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 客户端）。

复制示例配置文件并根据你的环境进行调整：

cp ithreemcp.json.sample ithreemcp.json

编辑 ithreemcp.json，确保 ithreemcp 的路径正确，并且 DISPLAY 环境变量与你的设置匹配。
使用你的配置文件运行 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 文件。

ithreemcp