Skip to main content
Glama
Harusame64

desktop-touch-mcp

by Harusame64
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

wait_until

Poll desktop and browser states—window appearance, element readiness, terminal output, or URL changes—to detect changes without screenshot loops.

Instructions

Purpose: Server-side poll for an observable condition — eliminates screenshot-polling loops when waiting for state changes. Details: condition selects what to watch: window_appears/window_disappears (target.windowTitle required), focus_changes (optional target.fromHwnd), element_appears/value_changes (target.windowTitle + target.elementName required, UIA; min 500ms interval), ready_state (target.windowTitle; visible + not minimized), terminal_output_contains (target.windowTitle + target.pattern required [+target.regex:true], needs terminal tools loaded), element_matches (target.by + target.pattern required, needs browser tools loaded), url_matches (target.pattern required [+target.regex:true]; matches the active tab's location.href via CDP — use for SPA route changes, redirects, OAuth flows). Returns {ok:true, elapsedMs, observed} on success, or WaitTimeout error with suggest hints. timeoutMs default 5000 (max 60000). Prefer: Use instead of run_macro({sleep:N}) + screenshot loops. Use terminal_output_contains to detect CLI command completion. Use element_matches for browser DOM readiness after navigation. Use url_matches when the URL is the most reliable signal (SPA routing / redirect cascades). Caveats: terminal_output_contains/element_matches/url_matches need a browser CDP connection (open --remote-debugging-port=9222 first). element_appears/value_changes spawn a UIA process per poll (interval floor 500ms). On timeout: {ok:false, code:'WaitTimeout', error, suggest:[...]}; suggest[] may open with a line earned by the last poll — read it, do not index. Those two also return context.lastLook: did the element resolve, why not, and for value_changes baseline/latest — the field's VALUE, so a masked credential arrives as mask characters. Other codes: 'ToolError' (validation / missing hook — read the message), 'BrowserNotConnected' (re-attach via browser_open), and 'WindowExcluded' for a target this server may not act through, answered at once rather than polled. Branch on code. Examples: wait_until({condition:'window_appears', target:{windowTitle:'Save As'}, timeoutMs:10000}) wait_until({condition:'terminal_output_contains', target:{windowTitle:'Terminal', pattern:'$ '}, timeoutMs:30000}) wait_until({condition:'element_matches', target:{by:'text', pattern:'Submit', scope:'#checkout-form'}}) wait_until({condition:'url_matches', target:{pattern:'/dashboard'}, timeoutMs:15000}) wait_until({condition:'url_matches', target:{pattern:'^https://app\\.example\\.com/orders/[0-9]+$', regex:true}})

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
targetNoTarget descriptor — fields used depend on condition. Accepts an object literal or a JSON-stringified object.
includeNoOptional response-shape opt-in. `['envelope']` returns the self-documenting envelope (`_version` / `data` / `as_of` / `confidence`). `['raw']` forces raw shape (overrides DESKTOP_TOUCH_ENVELOPE=1 server default). Default behaviour is raw shape (compat with existing clients).
conditionYesCondition to wait for. See per-condition target requirements.
timeoutMsNoMaximum time to wait (default 5000ms)
intervalMsNoPoll interval (default 200ms — terminal_output_contains uses 500 internally)

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed4 schema fields changedv2.3.1
    • addedInput schema / $schema
      Added value: +"http://json-schema.org/draft-07/schema#"
    • removedInput schema / additionalProperties
      Removed value: -false
    • addedInput schema / properties / target / properties
      Added value: +{
+  "by": {
+    "enum": [
+      "text",
+      "regex",
+      "role",
+      "ariaLabel"
+    ],
+    "type": "string"
+  },
+  "elementName": {
+    "type": "string"
+  },
+  "elementSelector": {
+    "type": "string"
+  },
+  "fromHwnd": {
+    "type": "string"
+  },
+  "pattern": {
+    "type": "string"
+  },
+  "port": {
+    "type": "number"
+  },
+  "regex": {
+    "type": "boolean"
+  },
+  "scope": {
+    "type": "string"
+  },
+  "tabId": {
+    "type": "string"
+  },
+  "windowTitle": {
+    "type": "string"
+  }
+}
    • addedInput schema / properties / target / type
      Added value: +"object"
  2. Addedv1.9.2
  3. Removedv1.8.0
  4. Addedv1.6.0
  5. Removedv1.5.1
  6. Addedv1.5.0
  7. Removedv1.4.3
  8. Addedv1.4.2
  9. Removedv1.4.0
  10. Changed1 schema field changedv1.2.1
    • addedInput schema / properties / include
      Added value: +{
+  "description": "Optional response-shape opt-in. `['envelope']` returns the self-documenting envelope (`_version` / `data` / `as_of` / `confidence`). `['raw']` forces raw shape (overrides DESKTOP_TOUCH_ENVELOPE=1 server default). Default behaviour is raw shape (compat with existing clients).",
+  "items": {
+    "type": "string"
+  },
+  "type": "array"
+}
  11. Addedv1.1.1
  12. Removedv1.1.0
  13. Addedv1.0.3
  14. Removedv0.15.7
  15. Changed8 schema fields changedv0.10.0
    • removedInput schema / $schema
      Removed value: -"http://json-schema.org/draft-07/schema#"
    • addedInput schema / additionalProperties
      Added value: +false
    • removedInput schema / properties / _stub
      Removed value: -{
-  "description": "Stub tool — arguments ignored."
-}
    • addedInput schema / properties / condition
      Added value: +{
+  "description": "Condition to wait for. See per-condition target requirements.",
+  "enum": [
+    "window_appears",
+    "window_disappears",
+    "focus_changes",
+    "value_changes",
+    "element_appears",
+    "ready_state",
+    "terminal_output_contains",
+    "element_matches"
+  ],
+  "type": "string"
+}
    • addedInput schema / properties / intervalMs
      Added value: +{
+  "default": 200,
+  "description": "Poll interval (default 200ms — terminal_output_contains uses 500 internally)",
+  "maximum": 5000,
+  "minimum": 50,
+  "type": "integer"
+}
    • addedInput schema / properties / target
      Added value: +{
+  "description": "Target descriptor — fields used depend on condition. Accepts an object literal or a JSON-stringified object."
+}
    • addedInput schema / properties / timeoutMs
      Added value: +{
+  "default": 5000,
+  "description": "Maximum time to wait (default 5000ms)",
+  "maximum": 60000,
+  "minimum": 100,
+  "type": "integer"
+}
    • addedInput schema / required
      Added value: +[
+  "condition"
+]
  16. First observedv0.6.2

TDQS

A4.8/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does so: it discloses the success shape ({ok, elapsedMs, observed}), the four error codes (WaitTimeout, ToolError, BrowserNotConnected, WindowExcluded) and how to branch on them, the CDP connection prerequisite, and that element_appears/value_changes spawn a UIA process per poll. It even warns that suggest[] may open with a poll-earned line and that the lastLook baseline can surface masked credentials.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Purpose/Details/Prefer/Caveats/Examples headers front-load the key information and the length is defensible for a nine-branch condition poller. Some caveat clauses are packed densely (the suggest-indexing and masked-value asides) and could be trimmed without losing call correctness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and no annotations exist, yet the description still documents return values, timeout semantics, all failure codes, prerequisites, and per-condition target requirements. An agent has everything needed to select a condition, supply the right target fields, and handle the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% but the nested target object's fields carry no per-field descriptions in the schema, so the description's per-condition requirement mapping (which conditions need windowTitle, elementName, pattern, regex, by) is genuinely additive. It stops short of explaining by's role/ariaLabel values, port, tabId, or elementSelector, so a few nested fields remain unglossed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource ('server-side poll for an observable condition') and immediately positions itself against the screenshot-polling pattern agents typically fall back on. The nine condition branches make the scope unambiguous, and an agent can tell it apart from run_macro/screenshot siblings without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Use instead of run_macro({sleep:N}) + screenshot loops' and then routes by scenario (terminal_output_contains for CLI completion, element_matches for DOM readiness, url_matches for SPA routing/redirect cascades). Both when-to-use and the named alternatives are present, so nothing is left to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server

Other Tools