# windows-mcp-lite

[windows-mcp](https://github.com/CursorTouch/Windows-MCP) はWindows操作用のMCPサーバーとして強力ですが、`Snapshot`のようなツールは常にデスクトップ全体（タスクバー・背面の全ウィンドウ含む）を走査するため、AIエージェントが消費するトークン量が大きくなりがちです。

windows-mcp-liteはこの課題に絞った軽量な代替です。対象ウィンドウ1つだけをスコープにし、コンパクトなテキスト形式で返すことで、同じ情報をより少ないトークンで提供します。

## 実測値

同じ電卓アプリのウィンドウに対して、実際に稼働中の両サーバーへ問い合わせて比較しました。

| | 文字数 |
|---|---|
| windows-mcp `Snapshot`（デスクトップ全体） | 5630文字 |
| windows-mcp-lite `ReadWindow`（電卓のみ） | 678文字 |
| **削減率** | **88.0%** |

生の比較データは [docs/note-assets](docs/note-assets) を参照してください。

## 提供ツール

**観測系**
- `ReadWindow` — 対象ウィンドウのUIツリーをコンパクトなテキストで取得
- `PeekWindow` — ウィンドウの存在確認、または特定テキストの有無だけを真偽値で取得（`ReadWindow`より軽量）
- `LocateElement` — 名前などから要素を検索し座標を取得
- `Screenshot` — スクリーンショットを取得（既定はデスクトップ全体。`window_name`を指定すると、そのウィンドウの領域だけを切り出す。タスクバーや背景の他ウィンドウ・無関係な情報を写り込ませたくない場合はこちらを使う）

**操作系**
- `Click` / `Type` / `Scroll` / `Move` — 座標を指定して操作（`ReadWindow`/`LocateElement`で得た座標を使う）
- `Shortcut` — キーボードショートカット送信
- `App` — アプリの起動（スタートメニュー名 or 実行ファイルパス指定）・切替・リサイズ

windows-mcpの`Snapshot`が返す数値ラベル（前回スナップショット参照用）は保持しないため、操作系ツールには常に明示的な`[x, y]`座標を渡します。

## インストール

`pyproject.toml`で[windows-mcp](https://pypi.org/project/windows-mcp/)をpinned依存として利用しています（Python 3.12+、Windows専用）。

```bash
uv sync
```

MCPクライアント（Claude Code等）の設定例:

```json
{
  "mcpServers": {
    "windows-mcp-lite": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "--project", "<このリポジトリのパス>", "windows-mcp-lite"]
    }
  }
}
```

## 既知の制約

- 電卓アプリの計算結果表示欄はUI Automationツリーに現れません（windows-mcp本体でも同様の制約）。
- モーダルダイアログを伴うウィンドウで、かつそのウィンドウがフォアグラウンドでもない場合は、windows-mcp本体・lite共通の制約として検出できないことがあります（詳細は [PLAN.md](PLAN.md) を参照）。

## アーキテクチャ

UI Automation/COM連携を再実装せず、[windows-mcp](https://github.com/CursorTouch/Windows-MCP)の内部クラス（`Desktop`/`Tree`等）をライブラリとして直接importしています。非公開の内部APIに依存する形になるため、windows-mcp側のアップデートで壊れる可能性があります。設計判断や実測の詳細な経緯は [PLAN.md](PLAN.md) にまとめています。

## ライセンス

MIT License（[LICENSE](LICENSE)）。

依存する [windows-mcp](https://github.com/CursorTouch/Windows-MCP) はMIT License, Copyright (c) 2025 Jeomon George です。