ithreemcp (Mschoch)

Ithremcp


一个MCP服务器，暴露了连接的i3窗口管理器的功能。

通过AI助手使用自然语言控制i3窗口。让你的LLM在工作区之间移动窗口、聚焦应用程序、切换浮动模式等等。

ithreemcp demo

阅读 博客文章 关于这个项目是如何结合在一起的。

需求

• i3窗口管理器 使用套接字访问运行
• 转到1.23+（从源代码构建）

安装

来自源头

go install github.com/mschoch/ithreemcp@latest

或者手动克隆和构建：

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

建筑

go build

跑步

先决条件： 您需要运行i3窗口管理器，并有权访问其套接字。

使用ollmcp快速入门

使用ithremcp最简单的方法是 ollmcp，Ollama的MCP客户。

1. 复制示例配置并根据您的环境进行调整：

   cp ithreemcp.json.sample ithreemcp.json

1. 编辑 ithreemcp.json 确保通往 ithreemcp 是正确的 DISPLAY 环境变量与您的设置相匹配。

1. 使用您的配置运行ollmcp：

   uvx ollmcp --servers-json ithreemcp.json

现在，您可以与Ollama聊天，让它管理您的i3窗口！

直接运行服务器

如果要与其他MCP客户端集成，可以直接运行服务器：

./ithreemcp

服务器使用MCP协议通过stdio进行通信。

调试日志记录

要观察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":{...}}

运作原理

ithreemcp程序是一个MCP服务器，允许MCP客户端与正在运行的i3窗口管理器进行交互。 ithremcp程序使用 MCP Go SDK 构建封装功能的MCP服务器。 ithremcp程序使用 go-i3 库使用其IPC接口与i3窗口管理器通信。

支持的操作

GetTree

使用底层操作返回的确切格式返回i3布局树。

GetWorkspaces

返回i3当前工作区的详细信息。

查找Windows

搜索与给定条件匹配的窗口。返回匹配的窗口及其 con_id，可与 RunCommand.

参数：

• name （可选）-匹配窗口标题（不区分大小写的子字符串）
• class （可选）-匹配窗口类（例如，“firefox”、“Alacrity”）
• instance （可选）-匹配窗口实例

退货： 窗口列表 con_id, name, class, instance, workspace，以及 focused 状态。

运行命令

执行i3命令。使用 i3命令语法 标准和行动。

参数：

• command （必填）-要执行的i3命令

退货： 结果数组 success 状态和可选 error 消息。

例子

这 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代码
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 当您需要以下情况时，它是首选：

• 按部分窗口标题搜索
• 在采取行动之前，获取有关哪些窗口匹配的信息
• 单独处理多场比赛
• 与用户确认目标窗口

许可证

Apache许可证2.0-请参阅 许可证 了解详情。