Skip to main content
Glama

dsh-zcode-cua

Brings ZCode's Computer Use into DeepSeek Harness.

The model can click, type, read the accessibility tree and take screenshots of native desktop apps through a single js tool. DSH's own dsh-cua-bundle reports unsupported-platform on Windows, so this is the route that works there.

中文 · Changelog

What it adds

One MCP tool, mcp__zcode-cua__js. Every call runs top-level await in a fresh Node.js kernel; the model drives the desktop with code:

const root =
  process.env.ZCODE_CUA_PLUGIN_ROOT ??
  process.env.ZCODE_PLUGIN_ROOT ??
  process.env.CLAUDE_PLUGIN_ROOT;
const { join } = await import("node:path");
const { pathToFileURL } = await import("node:url");
const { setupComputerUseRuntime } = await import(
  pathToFileURL(join(root, "scripts", "computer-use-client.mjs")).href
);
await setupComputerUseRuntime({ globals: globalThis });

const app = await agent.computerUse.getApp({ pid: 1234 });
await app.getAXState();      // read the accessibility tree
await app.click(12);         // click by element index
await app.typeText("hello");
await app.getScreenshot();

agent.computerUse exposes getState / getApp / listApps / requestAccess / stop, plus fourteen low-level computer.* tools. The ordered path is: getAXState() first, find the element by role and name, then act on its index. Coordinates are the last resort, for canvas and Electron content accessibility cannot see.

The full API reference is agent.documentation.get("computer-use"), fetched on demand.

Related MCP server: SXS Control

How it is wired

DSH  ──MCP stdio──▶  this plugin's server/index.js
                       ├─ injects ZCODE_CUA_PERMISSION_BROKER_SOCKET and friends
                       └──▶ node-repl-host (ZCode's official MCP server, one `js` tool)
                               └──▶ cua-helper (native Windows process, ax_native.node)
                                       └──▶ Win32 UI Automation / input injection

This plugin does exactly two things: resolve ZCode's installation layout, and translate between MCP 1.x and the modern protocol. The CUA execution logic is ZCode's own runtime, unmodified, which is why behaviour matches ZCode.

The upstream js tool is strict — anything beyond code, timeout_ms and title is refused — and this plugin passes it through untouched, adding no parameters.

Install

Prerequisites

  1. Windows

  2. ZCode installed and launched at least once — this plugin reuses the native helper in ZCode's install directory and redistributes none of it.

  3. DeepSeek Harness (this is a DSH bundle)

Into DSH

Option 1 (recommended): inside DSH, Plugins → Add plugin, then pick this directory. DSH links the checkout, so source edits take effect immediately.

Option 2: install from the checkout with the same command this was verified with:

cd "D:\path\to\dsh-zcode-cua"
dsh plugin --profile desktop add "link:$PWD"

Restart DSH afterwards. The tool appears as mcp__zcode-cua__js, and the plugin row reads ZCode computer control.

The package name must stay dsh-zcode-cua, unscoped. The registration row points at the relative path node_modules/dsh-zcode-cua/server/index.js; that is what makes one file work on every machine, and it assumes the package is installed under the profile's node_modules under exactly that directory name.

The tool works on its own, but the model will not know how to use it well. The skill lives at skills/zcode-computer-use/SKILL.md in this repository; install it into a DSH skill directory:

# user level (every project)
Copy-Item -Recurse .\skills\zcode-computer-use "$env:USERPROFILE\.dsh\skills\zcode-computer-use"

# or project level (only that project)
Copy-Item -Recurse .\skills\zcode-computer-use "D:\your-project\.dsh\skills\zcode-computer-use"

DSH does not load skills from a plugin directory — it scans <project>/.dsh/skills, <project>/.agents/skills and ~/.dsh/skills only, so this step is manual. Restart DSH afterwards.

Configuration

To change anything, find the zcode-cua row in the profile's cordis.patch.yml:

- id: zcode-cua
  name: '@deepseek-ai/dsh-mcp-client'
  config:
    serverName: zcode-cua
    transport: stdio
    command: 'node'
    args: ['node_modules/dsh-zcode-cua/server/index.js']
    toolCallTimeoutMs: 180000

command defaults to node, which needs Node 18.17+ on PATH. The DSH desktop app ships its own Node; point command at it if you prefer an absolute path.

Environment variables

When layout resolution fails — ZCode installed somewhere unusual — override the three probes:

Variable

Points at

ZCODE_BRIDGE_SERVER

node-repl-host's dist/mcp/server.js

ZCODE_CUA_PLUGIN_ROOT

the computer-use plugin root (holds scripts/computer-use-client.mjs)

ZCODE_BRIDGE_HELPER_ROOT

the cua-helper directory (holds build/Release/ax_native.node)

Usually none are needed: the plugin looks for ZCode in the uninstall registry (InstallLocation), in ZCODE_HOME, and in the conventional install locations.

Limitations

  • Windows only. It needs resources/tools/cua-helper from ZCode's install directory (the ax_native.node native module). ZCode currently has peer-identity verification disabled on Windows (WINDOWS_PEER_IDENTITY_GATE_TEMPORARILY_OPEN = true in windows-helper.js) — this plugin did not open that gate; the day ZCode closes it, this plugin stops working.

  • No on-screen activity indicator. ZCode's ghost cursor is drawn by a long-lived render scheduler inside the helper, and this path only has short-lived call processes, so the overlay never paints. Picture-in-picture is unavailable for the same reason — ax_native.node exports no pip* functions at all and pipSessionEnabled is always false on Windows.

  • No Browser Use. Upstream node-repl-host implements a Browser Use bridge, but it needs a browserBroker from the host and this plugin only wires the Computer Use bridge. Use DSH's own Browser Use for web pages.

  • Every js call is a fresh kernel. Variables do not survive between calls, so bootstrap every time.

  • The model really clicks and types on your desktop. That is the capability, not a defect; disable the plugin row when you do not need it.

Security notes

  • The helper's permission broker socket is created inside this plugin's own process under a random name (\\.\pipe\zcode-cua-helper-<uuid>) and disappears with the process.

  • This plugin reads, stores and forwards no ZCode or WorkBuddy credentials. It only drives a runtime already installed on the machine.

  • Tool calls are governed by DSH's tool permission system; use a DSH permission preset for tighter limits.

Development

server/paths.js     resolves ZCode's three install locations
server/index.js     the MCP stdio server; spawns upstream and translates the protocol
skills/             the skill (installed manually into a DSH skill directory)
locale/             plugin display metadata
docs/               detail page image
cordis.patch.yml    the registration row

No build step, no runtime dependencies, pure ESM. Restart DSH after a change.

License

MIT. See LICENSE.

This plugin contains no ZCode binaries or source. It drives a ZCode installation already present on your machine; those rights belong to their respective owners.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to observe and control the Windows desktop through the UI Automation accessibility tree — no vision model required — by exposing tools for reading windows and interactive elements, clicking, typing, scrolling, shortcuts, PowerShell, screenshots, virtual desktops, web scraping, file operations and persistent memory, including background-window control without stealing focus. An optional agent mode adds a single natural-language task tool that runs the full upstream agent loop when an LLM provider is configured.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables local AI clients on Windows to automate desktop and system tasks via MCP stdio, CLI, or optional localhost HTTP, including screenshots, mouse and keyboard input, files, processes, registry, and accessibility-tree window interactions, with local-only execution and no cloud fallback.
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP-capable AI agents to control Windows desktops through UI Automation element trees, native screenshots, app launching, batched action sequences, smart waits, and safety gates using normalized coordinates.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Exposes OpenAI's signed Windows Computer Use runtime as an MCP server so an MCP client's agent can inspect and control native Windows applications through JavaScript calls, without a nested model. It supports app and window discovery, screenshots, accessibility text, clicking, typing, scrolling, dragging, and other UI automation actions.
      3
      MIT