Ithreemcp

🚀 ithreemcp

このREADME文書は、ithreemcpに関する情報を提供しています。ithreemcpは、接続されたi3ウィンドウマネージャーの機能を公開するMCPサーバーです。AIアシスタントを通じて自然言語でi3ウィンドウを制御できます。

i3ウィンドウマネージャーの機能を公開するMCPサーバーです。AIアシスタントを通じて自然言語でi3ウィンドウを制御できます。ワークスペース間でウィンドウを移動させたり、アプリケーションにフォーカスを移したり、フローティングモードを切り替えたりすることができます。

このプロジェクトがどのようにまとまったかについてのブログ記事を読んでみてください。

🚀 クイックスタート

ithreemcpを使用するには、まずi3ウィンドウマネージャーをソケットアクセスで実行し、Go 1.23以上が必要です。その後、インストールを行い、サーバーを起動できます。

✨ 主な機能

• AIアシスタントを通じて自然言語でi3ウィンドウを制御
• ワークスペース間でウィンドウを移動
• アプリケーションにフォーカスを移す
• フローティングモードを切り替える

📦 インストール

ソースからのインストール

go install github.com/mschoch/ithreemcp@latest

または、手動でクローンしてビルドすることもできます。

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

🔧 ビルド

go build

実行

前提条件: i3ウィンドウマネージャーが実行され、そのソケットにアクセスする許可が必要です。

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

🔧 技術詳細

ithreemcpプログラムはMCPサーバーで、MCPクライアントが実行中のi3ウィンドウマネージャーとやり取りできるようにします。ithreemcpプログラムは、MCP Go SDKを使用して機能をラップしたMCPサーバーを構築します。また、go-i3ライブラリを使用して、IPCインターフェースを介して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 メッセージを持つ結果の配列。

💻 使用例

基本的な使用法

FindWindows と RunCommand ツールは、自然言語リクエストによる強力なウィンドウ管理を可能にするために連携して動作します。

ウィンドウを別のワークスペースに移動する

ユーザー: "Move Firefox to workspace 7"

1. FindWindows(class: "firefox") → ウィンドウを見つけてその con_id を返す
2. RunCommand(command: "[con_id=94285673947] move to workspace 7")

特定のアプリケーションにフォーカスを移す

ユーザー: "Switch to my terminal"

1. FindWindows(class: "Alacritty") → 一致するターミナルを返す
2. RunCommand(command: "[con_id=94285673948] focus")

アプリケーションのすべてのウィンドウを閉じる

ユーザー: "Close all my browser windows"

1. FindWindows(class: "firefox") → すべてのFirefoxウィンドウを返す
2. 各ウィンドウに対して: RunCommand(command: "[con_id=...] kill")

ウィンドウをスクラッチパッドに移動する

ユーザー: "Hide Slack in the scratchpad"

1. FindWindows(class: "Slack") → Slackウィンドウを見つける
2. RunCommand(command: "[con_id=94285673949] move scratchpad")

フローティングモードを切り替える

ユーザー: "Make the video player float"

1. FindWindows(name: "VLC") → ウィンドウタイトルでVLCを見つける
2. RunCommand(command: "[con_id=94285673950] floating toggle")

ウィンドウをリサイズする

ユーザー: "Make my editor wider"

1. FindWindows(class: "code") → VS Codeを見つける
2. RunCommand(command: "[con_id=94285673951] resize grow width 200 px")

ウィンドウを特定の出力/モニターに移動する

ユーザー: "Move this to my external monitor" RunCommand(command: "[focused] move to output HDMI-1")

全画面モードを切り替える

ユーザー: "Fullscreen my browser"

1. FindWindows(class: "firefox")
2. RunCommand(command: "[con_id=...] fullscreen toggle")

i3の条件を直接使用する

単純なケースでは、RunCommand は FindWindows を必要とせずにi3の組み込み条件を使用できます。

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

これは、クラスでウィンドウをターゲットにする場合に便利ですが、次のような場合には FindWindows が推奨されます。

• 部分的なウィンドウタイトルで検索する
• アクションを実行する前にどのウィンドウが一致するかに関する情報を取得する
• 複数の一致を個別に処理する
• ユーザーとターゲットウィンドウを確認する

📄 ライセンス

Apache License 2.0 - 詳細については LICENSE を参照してください。