# @harusame64/desktop-touch-mcp 中文文档

规范地址：https://npmcn.com/package/%40harusame64/desktop-touch-mcp/

版本：2\.4\.3
npm 元数据更新时间：2026-11-14T10:17:32.614Z
中文译文更新时间：2026-11-17T19:48:16.641Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40harusame64/desktop-touch-mcp
原文对照：https://npmcn.com/package/%40harusame64/desktop-touch-mcp/?lang=original
项目主页：https://github.com/Harusame64/desktop-touch-mcp#readme
源码仓库：https://github.com/Harusame64/desktop-touch-mcp

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：109 kB，5 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- Node.js 要求：\>=20\.0\.0
- 运行依赖：0 个
- 首次发布：2026-04-16T08:56:18.690Z
- 最新版本发布：2026-11-14T10:17:32.270Z
- 近 30 天下载量：4470（2026-10-18 至 2026-11-16，npm 官方下载统计）
- 已发布版本数：77（近 12 个月 77 个）

## 中文简介

让 Claude, Cursor 或任何 MCP 客户端查看和操作您的 Windows 10/11 桌面. 32个用于截图,UI Automation,Chrome CDP,键盘/mouse,终端的工具,有语义发现-当时动作瞄准和能避免出错-wi的每个动作感知守护器

## 安装

```sh
npm install @harusame64/desktop-touch-mcp
```

也可以使用：`pnpm add @harusame64/desktop-touch-mcp`、`yarn add @harusame64/desktop-touch-mcp`、`bun add @harusame64/desktop-touch-mcp`

## README

# 桌面- 触摸- mcp

[![desktop-touch-mcp MCP server](https://glama.ai/mcp/servers/Harusame64/desktop-touch-mcp/badges/card.svg)](https://glama.ai/mcp/servers/Harusame64/desktop-touch-mcp)

[日本語](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/README.ja.md)

> **Windows的计算机用MCP服务器.** 让 Claude, Cursor 或任何 MCP 客户端看到并操作您的 Windows 10/11 桌面 — 截图、 UI 自动化、 Chrome CDP、 键盘 / 鼠标、 终端 — 与 **语义 发现- 此时- 动作瞄准** 避免像素坐标猜想 **每个行动感知卫士** 在它发生之前 捕捉错误的窗口打字.

```bash
npx -y @harusame64/desktop-touch-mcp
```

32个工具,本土Rust引擎 (UIA in 2 ms),零配置的PowerShell倒置,完整的CJK支持,MIT许可. 在您的 Claude / Cursor / VS 代码副驾驶配置中添加上面的片段, Claude 可以驱动 Notepad, Excel, Chrome, Windows 终端, 以及您机器上的任何其他应用程序 .

> **为什么要用像素点击?** 每个工具都有两种想法: **发现当时的动作** —— 说 `desktop_discover` 返回具有短寿命租赁而不是原始坐标的互动实体,所以 `desktop_act` 运行于 _什麽_ 你是说,不是 _地点_ 这是... 和 **每个行动感知卫士** 在输入地之前验证目标窗口的身份和界限,在输入地之前捕获错误的窗口打入和 stale-坐标点击.
> 
> **2.1 国家** 通过元素计数而不是深度读取UI自动化:Chrome, Edge和VS代码页面,探索者和设置值,Word的正文被读取并可以被操作,而UIA仍然无法看到的东西和以前一样倒回OCR和Set-of-Marks. `desktop_act` 也可以输入 Word 的正文,并在询问用户后输入 Windows 终端. **2.0 数据** 拒绝采取无法采取的行动,有其理由,而不是报告已采取的行动,并拒绝采取旨在 `hwnd` 只到那扇窗户 见 [变化](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/CHANGELOG.md)。 。 。 .

* * *

## 特征

-   **每个行为都报告它做了什么** —— 说 `desktop_act` 答案与变化: 出现或消失的元素, 模式, 焦点动作, 屏幕的再油漆(`observation`),并与 `narrate:"rich"` 改变的价值观和名称。 代理从回复中读取点击的结果,而不是取取另一个截图. 在UIA盲目目标上,它也可以附带一个仅是变化区域(PNG)的PNG`roiCapture`;默认为明显变化, `returnCapture:"never"` 镇压, `"always"` (第2条).
-   **\* 拒绝无法采取的行为,不按规定报告** ——无法到达字段的输入,被对话框所屏蔽的窗口,被关闭的窗口,另一个虚拟桌面上的窗口:没有发送任何信息,而回复名称为原因和下一步要做什么. 以下列行为为目标: `hwnd` 永远不要降落在另一个拥有相同所有权的窗口.
-   **读取深窗(2.1)** ——UI自动化读取深度为64和500个元素. Chrome, Edge和VS代码页面,2.0称其被忽略的盲,探索和设置值,而Word的正文被读取并可以被操作(一Chrome页面:387ms = 45 in 186ms).
-   **\* 设定马可视倒置** ——游戏,没有无障碍树的RDP会话和app仍然返回可点击元素:当UIA失明时, `desktop_discover` 财务报告和审定财务报表 `screenshot(detail="text")` 切换到混合非CDP管线 — Rust- power grayscale + bilinear upscale → Windows OCR → 集群 → 有编号徽章的红边框 (`[1]`, (中文(简体) ), `[2]`(......) (中文(简体) ). 两种表述方式重新出现:一种是用于空间取向的巴布亚新几内亚表述方式;另一种是用于空间取向的巴布亚新几内亚表述方式 `elements[]` 列表为 `clickAt` coords——不需要CDP.
-   **QQ 背景输入达不到的类型** — Windows 终端, 其中 `desktop_act` 每次询问用户( 需要带引出功能的 MCP 客户端, 超过 stdio) 和 `terminal` 编号 : `keyboard` 检查粘贴前的标签, 和Word的身体, 在Word的注意, 无论它是在前面还是后面.
-   **QQ 密钥锁定器 — 终端自动填充您的 SSH / sudo 密码** ——将证书保存到储物柜自己的安全对话框中一次(用 Windows DPAPI 存储在机器上加密;从未显示给助手),然后运行 `ssh` 编号 : `sudo` 在打开的操纵台中 `key_locker(action='launch_console')` ——隐藏提示出现时,密码会自动填入,默认情况下每填入确认提示. 见 [密钥锁定器](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#key-locker-terminal-credential-autofill)。 。 。 .
-   **rust 原生核** ——UIA桥和图像分接是一出Rust土生土长的活塞(英语:`napi-rs` + 键 `windows-rs`:UIA从一条专用线被叫上"COM"来代替产入"PowerShell",图像diffs使用SSE2 SIMD. 没有附加物,每个功能都会透明地回归到PowerShell. npm 启动器只获取匹配其版本的 GitHub 发布器,并在取出它之前验证了 Windows 运行时的zip.
-   **LLM-内在设计** ——围绕LLMS的思维,而不是人类的点击. `run_macro` 将多个操作分批成一个API呼叫; `diffMode` 只发送自上一个框架以来变化的窗口。 最小的代币,最小的回程.
-   **反应感知图** - 登记a `lensId` 用于窗口或浏览器标签,将其传递给动作工具,并进行守护检查 `post.perception` 每次动作后反馈。 减少重复 `screenshot` 编号 : `desktop_state` 调用并阻止错误的窗口打字或 stale-coorders 点击.
-   **完整的 CJK 支持** - 使用Win32 `GetWindowTextW` 对于窗口标题, 避免坚果Js 夹克。 为日文/中文/韩文环境支持的IME绕行输入.
-   **3级指数减少** —— 说 `detail="image"` (~443吨) / `detail="text"` (~100-300吨) / `diffMode=true` (~160吨). 只在需要看到像素时才发送像素.
-   **1:1坐标模式** —— 说 `dotByDot=true` 以本地分辨率捕获(WebP). 图像像素=屏幕坐标——不需要比例数学. 与 `origin`\+ 键`scale` 转至 `mouse_click`,服务器转换为您使用的coords——去除离相/比例错误.
-   **浏览器抓取数据减少** —— 说 `grayscale=true` (~50%大小), `dotByDotMaxDimension=1280` (自动标出并保留了coord),以及 `windowTitle + region` 子 crops 帮助排除了浏览器铬和其他无关像素. 重捕的典型减少:50-70%.
-   **铬智能倒置** —— 说 `detail="text"` 在Chrome/Edge/Brave自动滑行UIA上(禁止在那里慢跑)并运行Windows OCR. `hints.chromiumGuard` + 键 `hints.ocrFallbackFired` 标记所走道路.
-   **UIA 元素提取** —— 说 `detail="text"` 返回按钮名称和 `clickAt` or为JSON. Claude可以点击正确的元素,而不会看到截图.
-   **自动锁定 CLI** —— 说 `window_dock(action='dock')` 将任何窗口按到屏幕角, 并始终在上方。 设定 `DESKTOP_TOUCH_DOCK_TITLE='@parent'` 在 MCP 启动时自动锁定终端托管 Claude —— 进程- 树上行走器可以找到正确的窗口, 不管标题是什么 .
-   **紧急停站( 故障)** ——把鼠标放入 **主显示器左上角** (10px以0,0为单位)500ms可触发紧急停站.

* * *

## 所需资源

|  |  |
| --- | --- |
| 监督办 | Windows 10 / 11(64位). **苹果硅上macOS 14+:有限预览,仅4个工具** 看到了吗 [macOS (审查)](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/#readme-macos-preview) |
| 节点.js | v20+推荐(测试于v22+)——\*\*开发或运行测试套房, 22.12 |
| 动力壳 | 5.1+ (与 Windows 捆绑在一起) – 仅当 Rust 本地引擎无法使用时用作倒置 |
| . NET 网络 | .NET 10桌面运行时间(x64),用于捆绑的助手:OCR,键锁,并打入后台窗口. 没有它 OCR 和 密钥锁定器 不运行, 背景打入控制台 回到张贴的字符, 它会丢失一个相同的字符运行 |
| 克劳德·CLI | `claude` 命令必须可用 |

> **说明:** 坚果-js 本地绑定需要视觉 C++ Redistributable. 从 [微软](https://learn.microsoft.com/en-us/cpp/windows/latest-supported-vc-redist) 如果尚未安装.

> **注 (Key Locker): (英语)** 证书式帮助键 Locker 使用的是一个未签名的可执行文件, 例如 有些机器 Windows SmartScreen 或反病毒可能显示“未知的出版商”警告 第一次运行。 预计将使用桌面-touch-mcp 并在当地运行的助手船 您可以允许它继续运行。 计划在将来发布代码.

* * *

## 安装

```bash
npx -y @harusame64/desktop-touch-mcp
```

Npm出發器严格通过npm包版本解决运行时间. 对于软件包 `X.Y.Z`,它只获取 GitHub 释放标记 `vX.Y.Z`,为您的平台下载拉链(`desktop-touch-mcp-windows.zip`,或 `desktop-touch-mcp-macos-arm64.zip` 在苹果硅Mac上,验证其SHA256文摘,然后在下方扩展 `%USERPROFILE%\.desktop-touch-mcp` (单位:千美元)`~/.desktop-touch-mcp` (原始内容存档于2018-09-28). on macOS. 经核实的缓存释放在后期运行时被再利用.

设定 `DESKTOP_TOUCH_MCP_HOME` 以覆盖缓存根目录.

旧版本在服务器启动后被移除,保留了运行中的版本和相机(Windows上每个版本约180 MB). 设定 `DESKTOP_TOUCH_MCP_KEEP_RELEASES` 保留更多(`0` 留着吧 正在运行的另一客户端的发布被保存 。 删除旧的 `releases/vX.Y.Z` 在没有客户端运行的情况下,手动文件夹也是安全的.

> **在一个共享或CI网络上?** 第一个运行读取 GitHub 释放 API 到 找到运行时间拉链。 匿名限制是每个IP60个请求/小时,即 共享公共地址( CI 运行器, 办公室 NAT) 在下载前可以耗尽 甚至开始。 设定 `GITHUB_TOKEN` (或 `GH_TOKEN`环境和环境 发射机对请求进行认证,将限制提高到5000个请求/小时. 普通的家用连接不需要任何标志.

> **运行发射装置 从源检出?** 源头构建 `bin/launcher.js` 携带一个占位符完整性散列(`sha256: "PENDING"`(中文(简体) ) 而不是最后决定。 而不是下载和运行 一个未经验证的运行时间, 发射装置没有关闭 —— 这个警卫阻止了一个不小心发表的,或者 未完成的发射装置 从静悄悄地开始 未经验证的密码。 已发布 npm 释放总是运送一个真正的SHA256, 所以终端用户从来没有看到这一点。 如果你是的话 故意从源头运行发射装置 `DESKTOP_TOUCH_MCP_ALLOW_UNVERIFIED=1` 以跳过完整性验证 (仅限发展).

> **你的东道主在发射机完成前会放弃吗?** 一些桌面主机 允许一个插件一个固定的预算——60秒是常见的——准备就绪,并且 等待一个无法到达的GitHub的发射机可以花费全部. 两个环境 变量涵盖该情况.
> 
> `DESKTOP_TOUCH_MCP_FETCH_TIMEOUT_MS` (默认) `15000`限制时间 发射机等待时没有听到GitHub的消息. 它适用于发布搜索 和下载; 对于下载来说,它意味着沉默而不是完全 时间,所以大型运行时间仍然安装在缓慢的连接上. 一个值 不是一个正数毫秒被忽略的警告.
> 
> `DESKTOP_TOUCH_MCP_OFFLINE_FALLBACK=1` 让发射装置开始发布 当 GitHub 完全无法到达时已安装。 这是关闭的 默认。 GitHub 总是先联系,所以仍然可以联系到的网络 重新下载并修复被损坏的安装; 只有网络故障到达 倒置,它从磁盘上开始复制您的版本——没有 重新核查——或者,在从未安装该版本时,更新的老版本 释放完成已核实安装的软件。 非网络的回答 失败( a 404, API 率限制, 完整性不匹配的散列) 仍然停止 开始大声。 离开它,除非一个主机超时 强迫你的手: 设置,您当前版本被损坏的安装被重新使用而不是被使用 修复.
> 
> 两个工作在一起: 倒计时,启动仍然等待 退后前暂停,再低一点 `DESKTOP_TOUCH_MCP_FETCH_TIMEOUT_MS` 若为 你的东道主的预算很紧张 请注意, 下载仍然 抵达,无论速度如何缓慢,从不中断——在到达时的倒数答案 网络已经沉默,而不是仅仅缓慢.

### 与克洛德·CLI登记

添加为 `~/.claude.json` 下级 `mcpServers`数字 :

```json
{
  "mcpServers": {
    "desktop-touch": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@harusame64/desktop-touch-mcp"]
    }
  }
}
```

**无需系统提示 .** 命令引用通过 MCP 自动注入 Claude `initialize` 答复 `instructions` 字段.

### 与其他客户端注册( HTTP 模式)

需要 HTTP 端点( GPT 桌面、 VS 代码 Copilot、 Cursor等) 的客户端可以使用内建流式 HTTP 传输 :

```bash
npx -y @harusame64/desktop-touch-mcp --http
# or with a custom port:
npx -y @harusame64/desktop-touch-mcp --http --port 8080
```

服务器开始于 `http://127.0.0.1:23847/mcp` (仅限本地主机). 在您的 MCP 客户端设置中注册 URL 。 健康检查: `http://127.0.0.1:<port>/health`。 。 。 .

在 HTTP 模式下,系统托盘图标显示活动的 URL ,并提供快速复制和打开浏览器快捷键.

### 开发安装

```bash
git clone https://github.com/Harusame64/desktop-touch-mcp.git
cd desktop-touch-mcp
npm install
```

安装后构建 :

```bash
npm run build
```

对于本地取出, 请直接注册已建服务器 :

```json
{
  "mcpServers": {
    "desktop-touch": {
      "type": "stdio",
      "command": "node",
      "args": ["D:/path/to/desktop-touch-mcp/dist/index.js"]
    }
  }
}
```

> **说明:** 替换 `D:/path/to/desktop-touch-mcp` 与您克隆此寄存器的实际路径.

## macOS (审查)

> **有限预览.** MacOS构建只有4个工具——Windows构建的一个小子集——其行为可能在发布之间发生变化.

在苹果硅Mac上(macOS 14或后期)相同 `npx` 命令启动 macOS 服务器,有四个工具: `desktop_state`, (中文(简体) ), `desktop_discover`, (中文(简体) ), `desktop_act` (按下,打开查找器侧边栏条目,替换或附加文本)和 `screenshot` (一扇窗户). 其他工具只有Windows,没有在macOS上列出.

-   赠款 **无障碍** - 和 **屏幕记录** 用于窗口标题和截图 – 到运行服务器的应用程序(Terminal, iTerm, VS Code, Claude app,.) 在 System Sets QQ隐私和安全. 在最近 macOS 上,可访问面板可以有另一个名称;这些命令直接打开两个面板:
    
    ```bash
    open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
    open "x-apple.systempreferences:com.apple.preference.security?Privacy_ScreenCapture"
    ```
    
    礛 **重新启动 MCP 服务器** ——在客户端中重新启动或重新连接,或重新启动运行它的应用程序:已经运行的服务器没有看到新的访问权限。 如果截图在允许屏幕录制后仍然失败,则退出并重新打开该应用. 在那之前,工具会回答 `PermissionRequired` 并说什么是给予.
-   安装方式 `npx` 仅:带有浏览器下载的放行zip被Gatelayer拒绝(原生模块没有公证).
-   仅限stdio(`--http` 尚未提供). 不支持英特尔·麦克斯和Linux.

* * *

## 工具(32个优化工具)

> 📖 **充分参考**数字 : [`docs/system-overview.md`](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/system-overview.md) ——关于参数的精通指南,还原计划,协调数学.

### • 世界图V2(初级路径)

| 工具 | 说明 |
| --- | --- |
| `desktop_discover` | 观察桌面. 以租赁方式返回互动实体(UIA、CDP、终端、Visual SoM). |
| `desktop_act` | 通过租赁验证对实体执行动作(单击、输入、设定一个值、选择)。 返回语义 diffs - 加上一个可选 `roiCapture` (已改变区域 PNG + 下个目标预览) 关于可视化目标. |

### 观测状态

| 工具 | 说明 |
| --- | --- |
| `desktop_state` | 轻量级检查焦点,活性窗口,光标,以及自动接受关注信号. |
| `screenshot` | 多模式抓取 : `detail='text'` (律师事务所/律师事务所), `diffMode` (P-框架), `dotByDot` (1:1),以及 `background`返回廉价 `screenshot://by-ref/{id}` 链接到保存的图像,而不是每次内置像素. |
| `screenshot_query` 编号 : `screenshot_gc` | 查看和浏览 disk 截图缓存 : `screenshot_query` 列出不重读像素而保存的捕获; `screenshot_gc` 通过保留策略(默认运行后干燥)恢复空间. |
| `workspace_snapshot` | 即时会话取向:一个呼叫中所有窗口缩略图+UI摘要. |
| `server_status` | 本地引擎健康和特性活化的诊断检查,哪个版本回答(`version`) (中文(简体) ). |

### 输入控件

| 工具 | 说明 |
| --- | --- |
| `keyboard` | 发送键盘输入 。 支持背景输入(WM CHAR)和IME安全剪贴板绕行. |
| `mouse_click` 编号 : `mouse_drag` | 基于精确协调的与跟踪和以力量为重点的保护的互动. |
| `scroll` | 多战略: `raw` (结节), `to_element`, (中文(简体) ), `smart` (虚拟清单),以及 `capture` (st. |
| `click_element` | 基于UIA的后遗症点击名称/ID(当没有实体时返回). |

### QQ 浏览器 CDP (Chrome/Edge/Brave)

| 工具 | 说明 |
| --- | --- |
| `browser_open` 编号 : `browser_navigate` | 同上,调试-模式发射和可靠的导航. |
| `browser_click` 编号 : `browser_fill` 编号 : `browser_form` | 高级DOM互动稳定地跨越再油漆和框架重组. |
| `browser_eval` | 深入检查通过 `js` (书写), `dom` (HTML),和 `appState` (SPA数据提取). |
| `browser_overview` 编号 : `browser_search` 编号 : `browser_locate` | 语义学发现,grep-like DOM搜索,和像素精确坐标搜索. |

### 公用事业和工作流程

| 工具 | 说明 |
| --- | --- |
| `terminal` | 统一命令执行 : `run` (发送+等+读出), `read` (OCR/UIA)和 `send`。 。 。 . `run` 补全模式 : `quiet`, (中文(简体) ), `pattern`,以及 `exit` (等待命令完成 + 返回其退出代码—— 见) [终端命令完成](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#terminal-command-completion-until)) (中文(简体) ). |
| `wait_until` | 用于窗口、焦点、文本或 URL 状态变化的高效服务器侧投票 . |
| `window_dock` 编号 : `focus_window` | 窗口管理 : `pin` (总是在顶上), `unpin`, (中文(简体) ), `dock` (橡皮屑),和 `focus`。 。 。 . |
| `workspace_launch` | 启动应用程序和自动检测的新HWND(支持本地化标题). |
| `run_macro` | 将最多可达50个操作分成一次往返,以达到最高效率. |
| `clipboard` 编号 : `notification_show` | 系统级文本交换和用户提示. |
| `key_locker` | 管理您的终端自动填充( SSH 密钥密码句、 sudo / 登录密码) 。 秘密一旦输入到储物柜自己的安全对话框中,并存储在这个机器(Windows DPAPI)上加密;从未向助手显示. `action='launch_console'` 打开自动填充功能控制台(返回 a) `paneId` 要驱动 `ssh`编号 :`sudo` 进入通过 `terminal`(三); `save` 编号 : `list` 编号 : `forget` 编号 : `set_policy` 编号 : `status` 管理约束; `fill_once` 请求您一次输入密码到一个快速自动填充中不会处理( 无保存; 带有 `tag` 它保存在窗格的内存中,直到窗格关闭,然后填充只要求填充/取消。 自动填充和 `fill_once` 只有打开的控制台工作 `launch_console`启用 `DESKTOP_TOUCH_DISABLE_KEY_LOCKER=1`。 。 。 . |

### 办公室(外卖)

| 工具 | 说明 |
| --- | --- |
| `excel` | 作者并通过COM运行Excel VBA宏. `action='run_vba'` 将宏写入管理下的托管位置并运行; `action='check_access_vbom'` 是一个只读的飞行前。 运行无法使用公式工具的 VBA 。 一次性设置 : `node scripts/enable-access-vbom.mjs`。 。 。 . |

* * *

## 标准工作流程(v1.0.0)

V2 世界- Graph 表面 (`desktop_discover` 编号 : `desktop_act`)是推荐的调度路径。 四呼的外形同样适用于本地的应用程序,浏览器,和终端.

```
desktop_state          → orient: focused window/element, modal, attention signal
desktop_discover       → find actionable entities (returns lease + windows[])
desktop_act(lease, …)  → act on entity (returns attention + post.perception)
desktop_state          → confirm the world changed as expected
```

点击 - 优先排序 :

```
browser_click(selector)               → Chrome / Edge (CDP, stable across repaints)
desktop_act(lease, action='click')    → native / dialog / visual (entity-based; use after desktop_discover)
click_element(name | automationId)    → native UIA fallback if desktop_act returns ok:false (not for list/tree/grid items)
mouse_click(x, y, origin?, scale?)    → pixel last resort; origin+scale from dotByDot screenshots only
```

对每次拒绝的追偿提示以及租约的到期: [指南-追回提示和租赁](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#recovery-hints-and-leases)。 。 。 .

* * *

## 更多在指南中

细节存在于 [指南](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md)数字 :

-   [回收提示和租赁](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#recovery-hints-and-leases)
-   [终端命令完成( E)`until`(中文(简体) )](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#terminal-command-completion-until)
-   [密钥锁定器( 最终证书自动填充)](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#key-locker-terminal-credential-autofill)
-   [浏览器 CDP 自动化](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#browser-cdp-automation)
-   [启动时自动锁定 CLI](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#auto-dock-cli-on-startup)
-   [鼠标旋转校正](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#mouse-homing-correction)
-   [`screenshot` 关键参数](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#screenshot-key-parameters)
-   [警卫](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#security)
-   [鼠标移动速度](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#mouse-movement-speed)
-   [力量焦点( 插入)](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#force-focus-attachthreadinput)
-   [自动守护](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#auto-guard)
-   [诊断日志](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#diagnostic-log)
-   [高级响应选项](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#advanced-response-options)
-   [本地发动机的性能(在v.0.15计量)](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#performance-of-the-native-engine-measured-at-v015)
-   [UI 操作层( V2)](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#ui-operating-layer-v2)
-   [参考成本](https://npmcn.com/package/%40harusame64/desktop-touch-mcp/docs/guide.md#token-cost-reference)

* * *

## 已知的限制

| 限制 | 细节 | 工作周边 |
| --- | --- | --- |
| 游戏/ 视频播放器可能返回黑色或在 PrintWindow 抓取中挂起 | DirectX 全屏应用程序不能在下面重画 `PW_RENDERFULLCONTENT`窗口目标 `screenshot(detail='image')` 当 PrintWindow 不返回数据或全黑+零变相框时,已经自动倒回BitBlt,但挂起呼叫的DirectX表面不会表面为倒置. | 重试 `screenshot({mode:'background', fullContent:false})` 切换到遗留的 PrintWindow 旗; 如果仍然是黑色的, BitBlt 倒转路径( 默认) `mode='normal'`)将至少返回屏幕上的矩形—— `hints.captureFallbackReason` 会说 `printwindow-all-black` |
| UIA 调用间接费用 | ~2 ms(焦)/~100 ms(树木)通过Rust本土引擎;~300 ms通过PowerShell倒置 | (一) 涡轮发动机自动装载; `workspace_snapshot` 内部使用 2 s 超时 |
| `screenshot(detail='text')` 返回 Chrome / WinUI3 上很少的 UIA 元素 | 读取在铬上保持浅度`desktop_discover` 阅读自2.1起的页控件 | `screenshot(detail='text')` 自动检测铬并返回到 Windows OCR(`hints.chromiumGuard=true`) (中文(简体) ). 使用 `desktop_discover` 用于页面控件,或 `browser_open` + 键 `browser_locate` dOM 访问 |
| 重写网站时chromium 标题- regex 缺失 `document.title` | 警卫依靠 `- Google Chrome` 后缀存在; 有网站将其从长标题的末尾推出 | 标题作为平原Chrome(UIA跑道)处理. OCR 路径仍然可以通过 `ocrFallback='always'` 或当UIA返回时 `<5` 要素`uiaSparse`(中文(简体) ) |
| `browser_*` CDP 工具需要使用 Chrome 启动 `--remote-debugging-port` | 如果Chrome已经运行在默认配置文件上,没有旗帜, `browser_open` 失败。 CDP E2E套房(`tests/e2e/browser-cdp.test.ts`)也会在那种状态下失败 | 先关上Chrome,然后 `browser_open({launch:{}})` 以调试模式重新启动,或手动启动 Chrome `--remote-debugging-port=9222 --user-data-dir=C:\tmp\cdp` |
| 层缓冲 TTL | 90后自动清除 ~ 下一个 `diffMode` 成为I-框架 | 等了很久,打个电话 `workspace_snapshot` 以明确重置缓冲器 |
| `keyboard(action='type')` 编号 : `keyboard(action='press')` 跟踪焦点 | 何时 `window_dock(action='dock')(pin=true)` 在顶部保留另一个窗口(如克洛德 CLI),键盘被该窗口所吸收 | 打电话 `focus_window(title=...)` 首先核实 `isActive=true` 通过 `screenshot(detail='meta')` 发送密钥前 |
| `keyboard(action='type')` em-dash / 在 Chrome/ Edge 中的智能引用 | 非 ASCII 标注 `—`时 `–`,聪明引用 `"" ''`)可以作为键盘加速器被截取,将焦点转移到地址栏 | 总是使用 `use_clipboard=true` 当文字包含这些字符时 |
| `browser_eval(action='js')` 在 React / Vue / Svelte 输入上 | 设置 `element.value = ...` 或发送合成事件 不更新框架的内部状态 | 使用 `browser_fill(selector, value)` 它使用本地原型设置器 + 输入Event , 它确实更新 React/Vue/Svelte 状态 |

* * *

## 谢谢

感谢所有尝试过桌面自定义 MCP 服务器, 提交问题的人, 打开公关, 分享什么打破。 每一份bug报告都让下一次发布更精彩. 谢谢你跟我一起建楼!

* * *

## 许可证

麻省理工学院

提供如上,没有保证。 无遥测: 见 [隐私政策](https://harusame64.github.io/desktop-touch-mcp/articles/privacy.html) 以它所派遣的,和所保存的 [安全政策](https://github.com/Harusame64/desktop-touch-mcp/blob/main/SECURITY.md) 报告脆弱性.

## 常见问题

### @harusame64/desktop-touch-mcp 是什么？

让 Claude, Cursor 或任何 MCP 客户端查看和操作您的 Windows 10/11 桌面\. 32个用于截图,UI Automation,Chrome CDP,键盘/mouse,终端的工具,有语义发现-当时动作瞄准和能避免出错-wi的每个动作感知守护器

### 如何安装 @harusame64/desktop-touch-mcp？

在项目目录运行 npm install @harusame64/desktop-touch-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 desktop-touch-mcp，可以用 npx desktop-touch-mcp 直接运行。

### @harusame64/desktop-touch-mcp 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/harusame64\_\_desktop-touch-mcp 是否存在。

### @harusame64/desktop-touch-mcp 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @harusame64/desktop-touch-mcp 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.0\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @harusame64/desktop-touch-mcp 可以商用吗？

@harusame64/desktop-touch-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @harusame64/desktop-touch-mcp 的下载量有多少？

根据 npm 官方下载统计，@harusame64/desktop-touch-mcp 在 2026/10/18 – 2026/11/16 这 30 天内被下载 4,470 次，日均约 149 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @harusame64/desktop-touch-mcp 还在维护吗？

最新版本 2\.4\.3 发布于 2026/11/14（3 天前）；至今共发布 77 个版本，其中过去 12 个月发布了 77 个；首次发布于 2026/04/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

