desktop-mcp 0.1.0__tar.gz

desktop_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaimen Bell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

desktop_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.4
+Name: desktop-mcp
+Version: 0.1.0
+Summary: Windows desktop-control MCP server: screenshot, window mgmt, mouse/keyboard input, and screen-recording. Config-gated tool groups (observe/window/input/record) -- input disabled by default. Local-only, single-machine.
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp==3.4.2
+Requires-Dist: mss==10.2.0
+Requires-Dist: pyautogui==0.9.54
+Requires-Dist: PyGetWindow==0.0.9
+Requires-Dist: pywin32==312
+Provides-Extra: test
+Requires-Dist: pytest==9.0.3; extra == "test"
+Dynamic: license-file
+
+# desktop-mcp
+
+Windows desktop-control MCP server: screenshot, window management, mouse/keyboard
+input, and ffmpeg screen-recording -- built to the same standard as
+[mcp-factory](https://github.com/jaimenbell/mcp-factory) and rag-mcp (own
+pyproject, fastmcp server, honest README, real test suite). Config-gated tool
+groups, **input disabled by default**.
+
+## Tool groups
+
+| Group | Tools | Default state |
+|---|---|---|
+| `observe` | `screenshot`, `list_windows`, `get_active_window`, `window_info` | always on |
+| `window` | `focus_window`, `move_resize_window`, `minimize_window`, `restore_window` | env-gated, off unless `DESKTOP_MCP_ENABLE_WINDOW=1` |
+| `input` | `mouse_move`, `mouse_click`, `mouse_drag`, `mouse_scroll`, `key_press`, `hotkey`, `type_text` | env-gated, **OFF by default** -- requires `DESKTOP_MCP_ENABLE_INPUT=1` |
+| `record` | `record_start`, `record_status`, `record_stop` | env-gated, off unless `DESKTOP_MCP_ENABLE_RECORD=1` |
+
+A disabled group returns a structured `policy_refusal` error (never a silent
+no-op, never a crash). Input actions are additionally rate-capped (default 60
+actions/min, tunable via `DESKTOP_MCP_RATE_LIMIT_PER_MIN`) -- exceeding the
+cap returns a structured `rate_limited` error.
+
+This is defense-in-depth: harness-level permission prompts are the first
+gate, but the server itself refuses input/window/record actions unless its
+own env explicitly enables them, so a misconfigured or overly-permissive
+harness can't turn on capabilities the operator didn't opt into for this
+process.
+
+## Honest-capabilities table
+
+Every claim below maps to the file that implements it and the test(s) that
+verify it -- no capability is asserted without a corresponding
+implementation + test.
+
+| Claim | Implementation | Verified by |
+|---|---|---|
+| Capture a screenshot (monitor / region / window) as PNG | `desktop_mcp/groups/observe.py::screenshot` | `tests/test_observe.py::TestScreenshot`, live: `tests/test_live_smoke.py::test_live_screenshot_real_png` |
+| Enumerate windows / get active window / look up by title | `desktop_mcp/groups/observe.py` | `tests/test_observe.py::TestListWindows`, `TestGetActiveWindow`, `TestWindowInfo` |
+| Focus / move+resize / minimize / restore a window | `desktop_mcp/groups/window.py` | `tests/test_window.py` |
+| Mouse move/click/drag/scroll, key press/hotkey, type text | `desktop_mcp/groups/input_tools.py` | `tests/test_input.py` (mocked pyautogui only -- see Limitations) |
+| Screen recording via ffmpeg gdigrab, hard duration cap, graceful stop | `desktop_mcp/groups/record.py` | `tests/test_record.py`, live: `tests/test_live_smoke.py::test_live_record_real_mp4` |
+| Input group OFF by default, structured refusal when disabled | `desktop_mcp/config.py::group_enabled`, `gated` | `tests/test_config.py::TestGroupEnabled`, `tests/test_input.py::TestGateDisabledByDefault` |
+| Rate cap on input actions (default 60/min) | `desktop_mcp/config.py::TokenBucket`, `RateLimiterRegistry` | `tests/test_config.py::TestTokenBucket`, `tests/test_input.py::TestRateLimit` |
+| DPI-awareness bootstrap (per-monitor-v2) so mss/pyautogui coords agree on scaled displays | `desktop_mcp/config.py::ensure_dpi_awareness` | `tests/test_config.py::TestDpiAwareness` (idempotency only; visual coord-agreement is not automated -- see Limitations) |
+| Coordinate validation against virtual-desktop bounds before any mouse action | `desktop_mcp/groups/input_tools.py::_validate_point` | `tests/test_input.py` (out-of-bounds cases) |
+| Orphan-guard: a stale recorder from a crashed process gets killed before a new one starts | `desktop_mcp/groups/record.py::_orphan_guard` | `tests/test_record.py::TestRecordStart::test_orphan_guard_kills_stale_recorder` |
+
+## Limitations (read before relying on this)
+
+- **UIPI (User Interface Privilege Isolation).** A medium-integrity process
+  (this server, unless you elevate it) cannot send input to or manipulate
+  windows owned by a higher-integrity (elevated/admin) process. Window and
+  input tools surface this as a structured `window_action_failed` /
+  `input_failed` error naming UIPI, never a silent no-op -- but there is no
+  workaround short of running the server elevated, which this project does
+  not do or recommend.
+- **DPI scaling.** The server sets per-monitor-v2 DPI awareness at startup so
+  `mss` pixel coordinates and `pyautogui` point coordinates should agree on
+  scaled displays. This bootstrap is unit-tested for idempotency/no-crash
+  only -- actual coordinate agreement on a live multi-DPI multi-monitor setup
+  has not been automated-tested and should be spot-checked if you're
+  targeting a non-100%-scaled monitor.
+- **UAC secure desktop.** When Windows switches to the secure desktop (UAC
+  elevation prompts, Ctrl+Alt+Del, lock screen), no process running on the
+  regular desktop -- including this server -- can see or interact with it.
+  Screenshots will show whatever was on the regular desktop before the
+  switch; input calls will not reach the secure desktop at all.
+- **Single machine, local only.** No network transport, no remote control.
+  stdio only, spawned by the MCP host on the same machine.
+- **Input group is off by default in this repo's own registration.** See
+  `~/.claude.json`'s `desktop-mcp` entry -- `DESKTOP_MCP_ENABLE_INPUT` is not
+  set there. Enabling it is a deliberate per-registration operator choice,
+  not a code change.
+- **pyautogui failsafe.** `FAILSAFE=True` is intentional: slamming the cursor
+  into a screen corner mid-action raises inside pyautogui and aborts the
+  call. This can interrupt an in-flight `mouse_drag`. Treated as acceptable
+  v1 behavior (see plan's Open questions) -- it's a deliberate human
+  kill-switch, not a bug.
+- **No OCR / vision analysis.** Screenshots are raw PNGs; interpreting their
+  content is the consumer's job, not this server's.
+- **No clipboard tools.** Credential-adjacent surface, deferred to a v2 with
+  its own safety design.
+- **Not registered with the mcp-factory hub.** This ships as a standalone
+  repo (own pyproject, own venv-free system-Python312 install), matching the
+  rag-mcp model. Hub/registry integration is a v2 candidate.
+
+## Env vars
+
+| Var | Effect | Default |
+|---|---|---|
+| `DESKTOP_MCP_ENABLE_WINDOW` | enable the `window` tool group | unset (off) |
+| `DESKTOP_MCP_ENABLE_INPUT` | enable the `input` tool group | unset (off) |
+| `DESKTOP_MCP_ENABLE_RECORD` | enable the `record` tool group | unset (off) |
+| `DESKTOP_MCP_RATE_LIMIT_PER_MIN` | input-group rate cap | `60` |
+| `DESKTOP_MCP_SCRATCH_DIR` | where screenshots/recordings/pidfiles are written | `%TEMP%\desktop-mcp-scratch` |
+| `DESKTOP_MCP_LIVE` | `1` to run real-hardware smoke tests (see Testing) | unset (skip) |
+
+## Usage examples
+
+```jsonc
+// A tool call from the MCP host, illustrative -- not a shell command.
+{"tool": "screenshot", "arguments": {"monitor": 0}}
+// -> {"ok": true, "path": "C:\\Users\\...\\Temp\\desktop-mcp-scratch\\screenshot-....png", "w": 3840, "h": 1080, "monitor": 0}
+
+{"tool": "record_start", "arguments": {"fps": 30, "max_duration_s": 30}}
+// -> {"ok": true, "path": "...\\recording-....mp4", "pid": 12345, "fps": 30, "max_duration_s": 30}
+{"tool": "record_stop", "arguments": {}}
+// -> {"ok": true, "path": "...\\recording-....mp4", "bytes": 800560, "duration_s": 3.13}
+
+// input group disabled (default):
+{"tool": "mouse_click", "arguments": {"x": 500, "y": 500}}
+// -> {"ok": false, "error": {"type": "policy_refusal", "group": "input", "required_env": "DESKTOP_MCP_ENABLE_INPUT", ...}}
+```
+
+## Testing
+
+```
+# unit suite (mocked backends, no real screen/input/recording touched)
+python -m pytest -q
+
+# handshake check -- prints every registered tool name
+python scripts/list_tools.py
+
+# real-hardware smokes (real screenshot PNG, real ~3s screen recording;
+# never input-injection -- see safety rails above)
+DESKTOP_MCP_LIVE=1 python -m pytest -q -k live_screenshot
+DESKTOP_MCP_LIVE=1 python -m pytest -q -k live_record
+```
+
+## Install
+
+```
+pip install -r requirements.txt   # or: pip install .
+# deps: fastmcp==3.4.2, mss==10.2.0, pyautogui==0.9.54, PyGetWindow==0.0.9, pywin32==312
+# also requires ffmpeg + ffprobe on PATH for the record group
+```
+
+Registered in `~/.claude.json` as `desktop-mcp` (stdio, system Python312,
+`observe`+`window`+`record` groups enabled, `input` group absent from env).
+
+<!-- MCP registry ownership marker -->
+mcp-name: io.github.jaimenbell/desktop-mcp

desktop_mcp-0.1.0/README.md

@@ -0,0 +1,142 @@
+# desktop-mcp
+
+Windows desktop-control MCP server: screenshot, window management, mouse/keyboard
+input, and ffmpeg screen-recording -- built to the same standard as
+[mcp-factory](https://github.com/jaimenbell/mcp-factory) and rag-mcp (own
+pyproject, fastmcp server, honest README, real test suite). Config-gated tool
+groups, **input disabled by default**.
+
+## Tool groups
+
+| Group | Tools | Default state |
+|---|---|---|
+| `observe` | `screenshot`, `list_windows`, `get_active_window`, `window_info` | always on |
+| `window` | `focus_window`, `move_resize_window`, `minimize_window`, `restore_window` | env-gated, off unless `DESKTOP_MCP_ENABLE_WINDOW=1` |
+| `input` | `mouse_move`, `mouse_click`, `mouse_drag`, `mouse_scroll`, `key_press`, `hotkey`, `type_text` | env-gated, **OFF by default** -- requires `DESKTOP_MCP_ENABLE_INPUT=1` |
+| `record` | `record_start`, `record_status`, `record_stop` | env-gated, off unless `DESKTOP_MCP_ENABLE_RECORD=1` |
+
+A disabled group returns a structured `policy_refusal` error (never a silent
+no-op, never a crash). Input actions are additionally rate-capped (default 60
+actions/min, tunable via `DESKTOP_MCP_RATE_LIMIT_PER_MIN`) -- exceeding the
+cap returns a structured `rate_limited` error.
+
+This is defense-in-depth: harness-level permission prompts are the first
+gate, but the server itself refuses input/window/record actions unless its
+own env explicitly enables them, so a misconfigured or overly-permissive
+harness can't turn on capabilities the operator didn't opt into for this
+process.
+
+## Honest-capabilities table
+
+Every claim below maps to the file that implements it and the test(s) that
+verify it -- no capability is asserted without a corresponding
+implementation + test.
+
+| Claim | Implementation | Verified by |
+|---|---|---|
+| Capture a screenshot (monitor / region / window) as PNG | `desktop_mcp/groups/observe.py::screenshot` | `tests/test_observe.py::TestScreenshot`, live: `tests/test_live_smoke.py::test_live_screenshot_real_png` |
+| Enumerate windows / get active window / look up by title | `desktop_mcp/groups/observe.py` | `tests/test_observe.py::TestListWindows`, `TestGetActiveWindow`, `TestWindowInfo` |
+| Focus / move+resize / minimize / restore a window | `desktop_mcp/groups/window.py` | `tests/test_window.py` |
+| Mouse move/click/drag/scroll, key press/hotkey, type text | `desktop_mcp/groups/input_tools.py` | `tests/test_input.py` (mocked pyautogui only -- see Limitations) |
+| Screen recording via ffmpeg gdigrab, hard duration cap, graceful stop | `desktop_mcp/groups/record.py` | `tests/test_record.py`, live: `tests/test_live_smoke.py::test_live_record_real_mp4` |
+| Input group OFF by default, structured refusal when disabled | `desktop_mcp/config.py::group_enabled`, `gated` | `tests/test_config.py::TestGroupEnabled`, `tests/test_input.py::TestGateDisabledByDefault` |
+| Rate cap on input actions (default 60/min) | `desktop_mcp/config.py::TokenBucket`, `RateLimiterRegistry` | `tests/test_config.py::TestTokenBucket`, `tests/test_input.py::TestRateLimit` |
+| DPI-awareness bootstrap (per-monitor-v2) so mss/pyautogui coords agree on scaled displays | `desktop_mcp/config.py::ensure_dpi_awareness` | `tests/test_config.py::TestDpiAwareness` (idempotency only; visual coord-agreement is not automated -- see Limitations) |
+| Coordinate validation against virtual-desktop bounds before any mouse action | `desktop_mcp/groups/input_tools.py::_validate_point` | `tests/test_input.py` (out-of-bounds cases) |
+| Orphan-guard: a stale recorder from a crashed process gets killed before a new one starts | `desktop_mcp/groups/record.py::_orphan_guard` | `tests/test_record.py::TestRecordStart::test_orphan_guard_kills_stale_recorder` |
+
+## Limitations (read before relying on this)
+
+- **UIPI (User Interface Privilege Isolation).** A medium-integrity process
+  (this server, unless you elevate it) cannot send input to or manipulate
+  windows owned by a higher-integrity (elevated/admin) process. Window and
+  input tools surface this as a structured `window_action_failed` /
+  `input_failed` error naming UIPI, never a silent no-op -- but there is no
+  workaround short of running the server elevated, which this project does
+  not do or recommend.
+- **DPI scaling.** The server sets per-monitor-v2 DPI awareness at startup so
+  `mss` pixel coordinates and `pyautogui` point coordinates should agree on
+  scaled displays. This bootstrap is unit-tested for idempotency/no-crash
+  only -- actual coordinate agreement on a live multi-DPI multi-monitor setup
+  has not been automated-tested and should be spot-checked if you're
+  targeting a non-100%-scaled monitor.
+- **UAC secure desktop.** When Windows switches to the secure desktop (UAC
+  elevation prompts, Ctrl+Alt+Del, lock screen), no process running on the
+  regular desktop -- including this server -- can see or interact with it.
+  Screenshots will show whatever was on the regular desktop before the
+  switch; input calls will not reach the secure desktop at all.
+- **Single machine, local only.** No network transport, no remote control.
+  stdio only, spawned by the MCP host on the same machine.
+- **Input group is off by default in this repo's own registration.** See
+  `~/.claude.json`'s `desktop-mcp` entry -- `DESKTOP_MCP_ENABLE_INPUT` is not
+  set there. Enabling it is a deliberate per-registration operator choice,
+  not a code change.
+- **pyautogui failsafe.** `FAILSAFE=True` is intentional: slamming the cursor
+  into a screen corner mid-action raises inside pyautogui and aborts the
+  call. This can interrupt an in-flight `mouse_drag`. Treated as acceptable
+  v1 behavior (see plan's Open questions) -- it's a deliberate human
+  kill-switch, not a bug.
+- **No OCR / vision analysis.** Screenshots are raw PNGs; interpreting their
+  content is the consumer's job, not this server's.
+- **No clipboard tools.** Credential-adjacent surface, deferred to a v2 with
+  its own safety design.
+- **Not registered with the mcp-factory hub.** This ships as a standalone
+  repo (own pyproject, own venv-free system-Python312 install), matching the
+  rag-mcp model. Hub/registry integration is a v2 candidate.
+
+## Env vars
+
+| Var | Effect | Default |
+|---|---|---|
+| `DESKTOP_MCP_ENABLE_WINDOW` | enable the `window` tool group | unset (off) |
+| `DESKTOP_MCP_ENABLE_INPUT` | enable the `input` tool group | unset (off) |
+| `DESKTOP_MCP_ENABLE_RECORD` | enable the `record` tool group | unset (off) |
+| `DESKTOP_MCP_RATE_LIMIT_PER_MIN` | input-group rate cap | `60` |
+| `DESKTOP_MCP_SCRATCH_DIR` | where screenshots/recordings/pidfiles are written | `%TEMP%\desktop-mcp-scratch` |
+| `DESKTOP_MCP_LIVE` | `1` to run real-hardware smoke tests (see Testing) | unset (skip) |
+
+## Usage examples
+
+```jsonc
+// A tool call from the MCP host, illustrative -- not a shell command.
+{"tool": "screenshot", "arguments": {"monitor": 0}}
+// -> {"ok": true, "path": "C:\\Users\\...\\Temp\\desktop-mcp-scratch\\screenshot-....png", "w": 3840, "h": 1080, "monitor": 0}
+
+{"tool": "record_start", "arguments": {"fps": 30, "max_duration_s": 30}}
+// -> {"ok": true, "path": "...\\recording-....mp4", "pid": 12345, "fps": 30, "max_duration_s": 30}
+{"tool": "record_stop", "arguments": {}}
+// -> {"ok": true, "path": "...\\recording-....mp4", "bytes": 800560, "duration_s": 3.13}
+
+// input group disabled (default):
+{"tool": "mouse_click", "arguments": {"x": 500, "y": 500}}
+// -> {"ok": false, "error": {"type": "policy_refusal", "group": "input", "required_env": "DESKTOP_MCP_ENABLE_INPUT", ...}}
+```
+
+## Testing
+
+```
+# unit suite (mocked backends, no real screen/input/recording touched)
+python -m pytest -q
+
+# handshake check -- prints every registered tool name
+python scripts/list_tools.py
+
+# real-hardware smokes (real screenshot PNG, real ~3s screen recording;
+# never input-injection -- see safety rails above)
+DESKTOP_MCP_LIVE=1 python -m pytest -q -k live_screenshot
+DESKTOP_MCP_LIVE=1 python -m pytest -q -k live_record
+```
+
+## Install
+
+```
+pip install -r requirements.txt   # or: pip install .
+# deps: fastmcp==3.4.2, mss==10.2.0, pyautogui==0.9.54, PyGetWindow==0.0.9, pywin32==312
+# also requires ffmpeg + ffprobe on PATH for the record group
+```
+
+Registered in `~/.claude.json` as `desktop-mcp` (stdio, system Python312,
+`observe`+`window`+`record` groups enabled, `input` group absent from env).
+
+<!-- MCP registry ownership marker -->
+mcp-name: io.github.jaimenbell/desktop-mcp

desktop_mcp-0.1.0/desktop_mcp/config.py

@@ -0,0 +1,252 @@
+"""Config/safety layer for desktop-mcp.
+
+Tool-group gating + rate limiting + structured refusal errors + DPI-awareness
+bootstrap. This is the server's own defense-in-depth layer: even if a caller
+gets past harness permission prompts, the server itself refuses input/window/
+record actions unless explicitly enabled via env, and caps input-action
+throughput.
+
+Groups:
+  observe -- screenshot / window-read (always on, no gate)
+  window  -- focus/move/resize/minimize/restore (env-gated)
+  input   -- mouse/keyboard (env-gated, OFF by default)
+  record  -- ffmpeg screen recording (env-gated)
+
+Env vars:
+  DESKTOP_MCP_ENABLE_INPUT=1   -- enable the input group
+  DESKTOP_MCP_ENABLE_WINDOW=1  -- enable the window group
+  DESKTOP_MCP_ENABLE_RECORD=1  -- enable the record group
+  DESKTOP_MCP_RATE_LIMIT_PER_MIN=<int> -- input-action rate cap (default 60)
+"""
+from __future__ import annotations
+
+import os
+import sys
+import time
+from dataclasses import dataclass, field
+from threading import Lock
+
+DEFAULT_RATE_LIMIT_PER_MIN = 60
+
+GROUP_OBSERVE = "observe"
+GROUP_WINDOW = "window"
+GROUP_INPUT = "input"
+GROUP_RECORD = "record"
+
+_ENV_GATES = {
+    GROUP_WINDOW: "DESKTOP_MCP_ENABLE_WINDOW",
+    GROUP_INPUT: "DESKTOP_MCP_ENABLE_INPUT",
+    GROUP_RECORD: "DESKTOP_MCP_ENABLE_RECORD",
+}
+
+
+def _env_truthy(name: str) -> bool:
+    val = os.environ.get(name, "")
+    return val.strip().lower() in ("1", "true", "yes", "on")
+
+
+def group_enabled(group: str) -> bool:
+    """observe is always on; other groups require their env gate."""
+    if group == GROUP_OBSERVE:
+        return True
+    env_name = _ENV_GATES.get(group)
+    if env_name is None:
+        return False
+    return _env_truthy(env_name)
+
+
+def policy_refusal(group: str, tool: str) -> dict:
+    """Structured refusal payload for a disabled tool group."""
+    env_name = _ENV_GATES.get(group, f"DESKTOP_MCP_ENABLE_{group.upper()}")
+    return {
+        "ok": False,
+        "error": {
+            "type": "policy_refusal",
+            "message": (
+                f"Tool group '{group}' is disabled. Set {env_name}=1 in the "
+                f"server's environment to enable it."
+            ),
+            "group": group,
+            "tool": tool,
+            "required_env": env_name,
+        },
+    }
+
+
+def rate_limited(group: str, tool: str, limit_per_min: int, retry_after_s: float) -> dict:
+    """Structured rate-limit payload."""
+    return {
+        "ok": False,
+        "error": {
+            "type": "rate_limited",
+            "message": (
+                f"Rate limit exceeded for group '{group}': max {limit_per_min} "
+                f"actions/min. Retry after ~{retry_after_s:.1f}s."
+            ),
+            "group": group,
+            "tool": tool,
+            "limit_per_min": limit_per_min,
+            "retry_after_s": round(retry_after_s, 2),
+        },
+    }
+
+
+@dataclass
+class TokenBucket:
+    """Simple token-bucket rate limiter, one bucket per gated group.
+
+    Capacity == limit_per_min, refills continuously at limit_per_min / 60
+    tokens/sec. Thread-safe (guards a single Lock) since MCP tool calls could
+    in principle be dispatched concurrently by the host.
+    """
+
+    limit_per_min: int
+    _tokens: float = field(init=False)
+    _last_refill: float = field(init=False)
+    _lock: Lock = field(init=False, default_factory=Lock, repr=False)
+
+    def __post_init__(self) -> None:
+        self._tokens = float(self.limit_per_min)
+        self._last_refill = time.monotonic()
+
+    def _refill(self) -> None:
+        now = time.monotonic()
+        elapsed = now - self._last_refill
+        self._last_refill = now
+        rate_per_s = self.limit_per_min / 60.0
+        self._tokens = min(self.limit_per_min, self._tokens + elapsed * rate_per_s)
+
+    def try_acquire(self) -> tuple[bool, float]:
+        """Attempt to consume one token. Returns (allowed, retry_after_s)."""
+        with self._lock:
+            self._refill()
+            if self._tokens >= 1.0:
+                self._tokens -= 1.0
+                return True, 0.0
+            rate_per_s = self.limit_per_min / 60.0
+            deficit = 1.0 - self._tokens
+            retry_after = deficit / rate_per_s if rate_per_s > 0 else float("inf")
+            return False, retry_after
+
+
+class RateLimiterRegistry:
+    """Holds one TokenBucket per group, keyed by the current configured limit.
+
+    Recreates the bucket if the configured limit_per_min changes (e.g. tests
+    that monkeypatch the env between calls), so limit changes take effect
+    without needing a fresh process.
+    """
+
+    def __init__(self) -> None:
+        self._buckets: dict[str, TokenBucket] = {}
+        self._limits: dict[str, int] = {}
+
+    def acquire(self, group: str) -> tuple[bool, float, int]:
+        limit = get_rate_limit_per_min()
+        bucket = self._buckets.get(group)
+        if bucket is None or self._limits.get(group) != limit:
+            bucket = TokenBucket(limit_per_min=limit)
+            self._buckets[group] = bucket
+            self._limits[group] = limit
+        allowed, retry_after = bucket.try_acquire()
+        return allowed, retry_after, limit
+
+    def reset(self) -> None:
+        """Test helper: clear all buckets so each test starts fresh."""
+        self._buckets.clear()
+        self._limits.clear()
+
+
+def get_rate_limit_per_min() -> int:
+    raw = os.environ.get("DESKTOP_MCP_RATE_LIMIT_PER_MIN")
+    if not raw:
+        return DEFAULT_RATE_LIMIT_PER_MIN
+    try:
+        val = int(raw)
+        return val if val > 0 else DEFAULT_RATE_LIMIT_PER_MIN
+    except ValueError:
+        return DEFAULT_RATE_LIMIT_PER_MIN
+
+
+# Module-level singleton registry shared by all input-group tools within a
+# process. Tests call `reset()` on this (or construct their own registry) to
+# avoid cross-test bucket state leaking.
+RATE_LIMITER = RateLimiterRegistry()
+
+
+_dpi_bootstrapped = False
+
+
+def ensure_dpi_awareness() -> None:
+    """Set per-monitor-v2 DPI awareness so mss pixel coords line up with
+    pyautogui point coords on scaled displays. Idempotent; no-op on failure
+    (e.g. non-Windows, or already set by host process) and never raises --
+    this is a best-effort bootstrap, not a safety boundary.
+    """
+    global _dpi_bootstrapped
+    if _dpi_bootstrapped:
+        return
+    _dpi_bootstrapped = True
+    if sys.platform != "win32":
+        return
+    try:
+        import ctypes
+
+        # DPI_AWARENESS_CONTEXT_PER_MONITOR_AWARE_V2 = -4
+        try:
+            ctypes.windll.user32.SetProcessDpiAwarenessContext(-4)
+            return
+        except (AttributeError, OSError):
+            pass
+        try:
+            ctypes.windll.shcore.SetProcessDpiAwareness(2)
+        except (AttributeError, OSError):
+            pass
+    except Exception:  # noqa: BLE001 - best-effort only
+        pass
+
+
+def check_group(group: str, tool: str) -> dict | None:
+    """Gate check for a tool call. Returns a structured refusal dict if the
+    group is disabled, else None (caller proceeds)."""
+    if not group_enabled(group):
+        return policy_refusal(group, tool)
+    return None
+
+
+def check_rate_limit(group: str, tool: str) -> dict | None:
+    """Rate-limit check for a gated action. Returns a structured rate_limited
+    dict if the caller is over the cap, else None (caller proceeds)."""
+    allowed, retry_after, limit = RATE_LIMITER.acquire(group)
+    if not allowed:
+        return rate_limited(group, tool, limit, retry_after)
+    return None
+
+
+def gated(group: str, *, rate_limited_group: bool = False):
+    """Decorator applied directly to group-module functions so the policy
+    gate (and, for input-group actions, the rate limiter) is enforced at the
+    source -- not just in the MCP tool wrapper -- and is unit-testable without
+    spinning up the fastmcp server.
+
+    Order: group gate first (cheaper, and a disabled group shouldn't consume
+    rate-limit budget), then rate limit if requested.
+    """
+
+    def decorator(fn):
+        def wrapper(*args, **kwargs):
+            refusal = check_group(group, fn.__name__)
+            if refusal is not None:
+                return refusal
+            if rate_limited_group:
+                limited = check_rate_limit(group, fn.__name__)
+                if limited is not None:
+                    return limited
+            return fn(*args, **kwargs)
+
+        wrapper.__name__ = fn.__name__
+        wrapper.__doc__ = fn.__doc__
+        wrapper.__wrapped__ = fn
+        return wrapper
+
+    return decorator