Skip to main content
Glama
Harusame64

desktop-touch-mcp

by Harusame64
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

workspace_launch

Launches an executable, waits for its window to appear, and returns the window title, HWND, and PID so you can target the right desktop window.

Instructions

Purpose: Launch an application and wait for its window to appear, returning the window's title, HWND, and PID. Details: Starts the executable (well-known names and App Paths entries resolve to a full path), lists the top-level windows before the launch, then checks every 200 ms, for up to waitMs, for a window whose HWND was not there before or whose title changed. Returns {launched, args, windowTitle, hwnd, pid, region, foundWindow}; the window fields are null when no window appeared in time, and a hint says why. foundWindow is the same as windowTitle, kept for older callers. Works for localized window titles (e.g. '電卓' for calc.exe) because detection is HWND-based. waitMs default 2000, max 30000; waitMs:0 returns right after the launch with the window fields null. Prefer: Use instead of run_macro({exec, sleep, desktop_discover}) combos. Follow with desktop_discover({target:{hwnd}}) using the returned hwnd, which names this window even when another has a similar title (or focus_window(windowTitle)). Caveats: Single-instance apps that reuse an existing window will not register as a new HWND — call desktop_discover first to check if the window is already open. Minimized windows and windows smaller than 50×50 are not reported. When no new window appears within waitMs, an already-open window whose title changed during the wait is reported instead, which may not be the launched app; such an app (one that only retitles its existing window) answers after the whole waitMs. pid is the process that owns the window, which can differ from the one launched (an app that hands off to another process). Examples: workspace_launch({command:'notepad.exe'}) → {windowTitle:'', hwnd:'...', pid:...} workspace_launch({command:'calc.exe', waitMs:15000})

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
argsNoCommand-line arguments (max 20). Shell metacharacters (; & | ` $() ${}) are not allowed.
waitMsNoMilliseconds to wait for the window to appear (default 2000)
commandYesExecutable name or full path (e.g. 'notepad.exe', 'calc.exe'). Shell interpreters (cmd.exe, powershell.exe, etc.) are blocked.
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).

Schema Changelog

Changes observed during successful MCP inspections.

  1. Changed3 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 / args / items
      Added value: +{
+  "maxLength": 1000,
+  "type": "string"
+}
  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. Changed7 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 / args
      Added value: +{
+  "default": [],
+  "description": "Command-line arguments (max 20). Shell metacharacters (; & | ` $() ${}) are not allowed.",
+  "maxItems": 20,
+  "type": "array"
+}
    • addedInput schema / properties / command
      Added value: +{
+  "description": "Executable name or full path (e.g. 'notepad.exe', 'calc.exe'). Shell interpreters (cmd.exe, powershell.exe, etc.) are blocked.",
+  "maxLength": 260,
+  "type": "string"
+}
    • addedInput schema / properties / waitMs
      Added value: +{
+  "default": 2000,
+  "description": "Milliseconds to wait for the window to appear (default 2000)",
+  "maximum": 30000,
+  "minimum": 0,
+  "type": "integer"
+}
    • addedInput schema / required
      Added value: +[
+  "command"
+]
  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 delivers: polling cadence, null-window semantics, single-instance no-new-HWND behavior, minimized and <50x50 exclusion, the title-change fallback, and the fact that pid may differ from the launched process. This is exactly the behavioral context an agent needs.

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?

Front-loaded with Purpose then Details, and organized under Prefer/Caveats/Examples headers so an agent can scan it. It is on the long side and the caveat list is dense, but nearly every sentence encodes a distinct behavior rather than padding.

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?

Although there is no output schema, the description fully specifies the return object ({launched, args, windowTitle, hwnd, pid, region, foundWindow}) and notes the foundWindow/windowTitle alias and the 'hint' field. Nothing needed to call or interpret the result is missing.

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%, so the baseline is 3, but the description adds meaning beyond the schema: waitMs:0 returns immediately with null window fields, command resolves well-known names and App Paths entries to a full path, and localized titles are handled via HWND-based detection.

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?

The opening states a specific verb and resource—launch an application and wait for its window—and enumerates the return fields (title, HWND, PID). It clearly distinguishes itself from siblings like run_macro and desktop_discover by naming what it replaces.

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?

The 'Prefer' section explicitly tells the agent to use this instead of run_macro({exec, sleep, desktop_discover}) combos, and prescribes follow-up calls (desktop_discover with the returned hwnd, or focus_window). Both the condition and the alternatives are stated.

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