@harusame64/desktop-touch-mcp 0.11.12 → 0.13.0

package/README.md

@@ -497,6 +497,103 @@ Setting `DESKTOP_TOUCH_FORCE_FOCUS=1` makes `forceFocus: true` the default for a
 
 ---
 
+## Auto Guard (v0.12+)
+
+Action tools (`mouse_click`, `mouse_drag`, `keyboard_type`, `keyboard_press`, `click_element`, `set_element_value`, `browser_click_element`, `browser_navigate`) automatically guard each action when you pass `windowTitle` / `tabId`:
+
+- Verifies target window identity (process restart / HWND replacement detected)
+- Confirms click coordinates are inside the target window rect
+- Returns `post.perception.status` on every response — including failures — so the LLM can recover without a screenshot
+
+**Disabling auto guard** — set `DESKTOP_TOUCH_AUTO_GUARD=0` to restore v0.11.12 behavior (no auto guard):
+
+```json
+{
+  "mcpServers": {
+    "desktop-touch": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@harusame64/desktop-touch-mcp"],
+      "env": {
+        "DESKTOP_TOUCH_AUTO_GUARD": "0"
+      }
+    }
+  }
+}
+```
+
+When auto guard is enabled (default), `post.perception.status` will be one of:
+
+| Status | Meaning |
+|---|---|
+| `ok` | Guard passed — target verified |
+| `unguarded` | `windowTitle` not provided; action ran without guard |
+| `target_not_found` | No window matched the given title |
+| `ambiguous_target` | Multiple windows matched; use a more specific title |
+| `identity_changed` | Window was replaced (process restart / HWND change) |
+| `unsafe_coordinates` | Click coordinates are outside the target window rect |
+| `needs_escalation` | Use `browser_click_element` or specify `windowTitle` |
+
+When `unsafe_coordinates` or `identity_changed` is returned, the response may include a `suggestedFix.fixId`. Pass that `fixId` to the relevant tool call to approve the recovery:
+
+```json
+{ "name": "mouse_click",           "arguments": { "fixId": "fix-..." } }
+{ "name": "keyboard_type",         "arguments": { "fixId": "fix-...", "text": "hello" } }
+{ "name": "click_element",         "arguments": { "fixId": "fix-..." } }
+{ "name": "browser_click_element", "arguments": { "fixId": "fix-..." } }
+```
+
+The fix is one-shot and expires in 15 seconds. The server revalidates the target process identity before executing.
+
+---
+
+## v0.13 Additions
+
+### Target-Identity Timeline
+
+The server tracks a semantic timeline of what happened to each target window/tab. Recent events are included in:
+
+- `get_history` → `recentTargetKeys`: array of 3 most recently active target keys (compact, no event bodies)
+- `perception_read(lensId)` → `recentEvents`: up to 10 events for that lens's target, each with `tsMs`, `semantic`, `summary`
+
+Enable the MCP resources below to browse timelines:
+
+```json
+{ "env": { "DESKTOP_TOUCH_PERCEPTION_RESOURCES": "1" } }
+```
+
+MCP resources available when enabled:
+
+| URI | Content |
+|---|---|
+| `perception://target/{targetKey}/timeline` | Semantic event timeline for a target |
+| `perception://targets/recent` | Most recently active target keys |
+| `perception://lens/{lensId}/summary` | Lens attention/guard state |
+
+### Manual Lens Eviction: FIFO → LRU
+
+Manual lenses (created via `perception_register`) are now evicted by **least-recently-used** instead of insertion order. Using `perception_read`, `evaluatePreToolGuards`, or `buildEnvelopeFor` on a lens promotes it. The hard limit of 16 active lenses is unchanged.
+
+### browser_eval Structured Mode
+
+Pass `withPerception: true` to receive a structured JSON response with `post.perception` instead of raw text:
+
+```json
+{ "name": "browser_eval", "arguments": { "expression": "document.title", "withPerception": true } }
+```
+
+Returns `{ ok: true, result: "...", post: { perception: { status: "ok", ... } } }`.
+
+### mouse_drag Cross-Window Guard
+
+`mouse_drag` now guards both start and end coordinates. Drags that cross window boundaries (or reach the desktop wallpaper) are blocked by default. To allow intentional cross-window or range-selection drags:
+
+```json
+{ "name": "mouse_drag", "arguments": { "startX": 100, "startY": 100, "endX": 900, "endY": 900, "allowCrossWindowDrag": true } }
+```
+
+---
+
 ## Known limitations
 
 | Limitation | Detail | Workaround |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harusame64/desktop-touch-mcp",
-  "version": "0.11.12",
+  "version": "0.13.0",
   "description": "LLM-native Windows computer-use MCP server with 56 tools for screenshots, UIA, mouse/keyboard, Chrome CDP, terminal, SmartScroll, and perception guards",
   "engines": {
     "node": ">=20.0.0"