uMouse MCP

uMouse MCP — 面向 AI Agent 的硬件鼠标控制

English | 简体中文

为 AI Agent 配备真正的硬件鼠标。uMouse MCP 是一个 Model Context Protocol（MCP）服务，可在 Windows 上控制 USB HID 鼠标并进行语音听写。鼠标移动、点击、滚动和拖动操作使用兼容的 uMouse 设备；语音输入支持可插拔的语音识别提供商。

**需要兼容的 uMouse 硬件和固件、Windows x64，以及单独安装的 Node.js 运行时（使用 Node.js 22 x64）。**普通 USB 鼠标无法满足要求。MIT 许可证适用于服务代码；原生 SDK 二进制文件适用单独的条款。请参阅许可证。

下载 · 快速开始 · 参考演示 · 文档 · 获取硬件 / 支持 · uMouse SDK

下载

软件包	下载	要求
MCPB · Windows x64 · v0.1.1	下载 MCPB · 发行说明和 SHA-256	兼容 MCPB 的客户端；兼容的 uMouse 硬件；x64 Node.js 22+
Windows x64 · v0.1.0	下载 ZIP · 发行说明和 SHA-256	兼容的 uMouse 设备和固件；需单独安装 Node.js

所有发行版 · Gitee 发行版镜像

**MCPB 安装：**将 .mcpb 导入支持 MCPB Node 扩展的客户端。0.1.1 版本封装了旧版 0.1.0 运行时，不包含云凭据，并默认将语音识别设为 disabled；windows-speech 是可选的本地提供商。数据默认存储在 ~/.umouse-mcp-mcpb。请参阅双语 MCPB 指南。该项目已作为 io.github.SonicloudTech/mouse-mcp 发布到官方 MCP Registry；元数据见 server.json，发布和验证信息。

ZIP 包含生产环境所需的 Node 依赖、原生 SDK DLL、语音预览界面和 VC 运行时库。使用发行版无需运行 npm install 或进行编译；不包含 Node.js 本身。

**发行版和源代码采用不同的安装方式：**v0.1.0 安装程序会注册旧版 stdio 入口 mcp/dist/index.js。下文介绍的 shared-v2 工具、原生主机和验收实验室属于源代码实现。此 ZIP 并非完整的 shared-v2 软件包：其中不包含该原生主机或验收实验室。请根据已安装服务的工具列表以及 ZIP 中附带的 README 了解发行版的具体行为。

快速开始

以下步骤使用原始 ZIP。对于 MCPB，请先使用上文的导入说明，然后执行第 5 步中的状态和设备检查。

1. 安装 Node.js 22 x64，并确认 node --version 可以正常运行。连接兼容的 uMouse USB 接收器/设备，并打开鼠标电源。要检查设备或固件兼容性，请参阅硬件与支持。
2. 下载上方的 ZIP 并解压。打开 umouse-mcp-os-win-x64 文件夹；请将其保存在固定位置，因为客户端配置会指向此文件夹。
3. 双击 install-agents.cmd，以用户级方式注册 ZCode；或者在解压后的文件夹中，为所选客户端运行一条命令：

客户端	PowerShell 命令
ZCode	node mcp/scripts/install-agents.mjs zcode
Claude Desktop	node mcp/scripts/install-agents.mjs claude
Cursor	node mcp/scripts/install-agents.mjs cursor

安装程序会在所选客户端的配置中添加或更新 umouse 条目。如果本地数据目录中尚无配置文件，安装程序还会将随附的试用版 ASR 配置复制到该目录。生产环境使用时，请将试用凭据替换为自己的凭据。

4. 根据需要，打开新的 ZCode 会话、完全退出并重新打开 Claude Desktop，或重新加载 Cursor 窗口。
5. 让你的 Agent 调用 umouse_status、umouse_get_capabilities 和 umouse_list_devices。检查 SDK 健康状况、设备列表和报告的功能。返回的 sdkVersion 只能确认 SDK 可访问，不能证明硬件控制可正常工作。在依赖任何鼠标操作之前，请确认操作结果可见。

对于接受 mcpServers JSON 格式的客户端，可手动添加此条目，并将路径替换为解压后的文件夹路径。其他客户端可能需要使用不同的配置格式。

{
  "mcpServers": {
    "umouse": {
      "command": "node",
      "args": ["C:\\path\\to\\umouse-mcp-os-win-x64\\mcp\\dist\\index.js"]
    }
  }
}

手动配置不会执行安装程序的 ASR 设置。如果需要语音听写，请单独配置语音提供方；请参阅语音听写（可插拔 ASR 提供方）。

对于源码开发，npm ci、npm run build 和 npm test 可安装依赖、构建 TypeScript 并运行默认测试。它们不会生成完整的 shared-v2 原生打包版本。目前尚未提供完整的公开 shared-v2 打包工作流。shared-v2 开发与维护说明（中文）和原生主机构建说明（中文）可作为此独立开发路径的参考。

参考演示

鼠标实验室录屏展示的是 shared-v2 源码实现，而非旧版 ZIP 安装。

硬件鼠标驱动真实浏览器实验室页面（金色箭头 = 叠加在录屏上的系统光标）——计数器、滚轮和命中反馈均来自真实浏览器事件：

语音输入：开口说话，文字即刻输入到任意窗口

按住设备的语音键，说话，然后松开——识别出的文字会输入到当前获得焦点的窗口中。两个片段均为实时 1080p 录制：

Agent 客户端（终端）——语音命令输入后执行：

mcp/acceptance/demo/voice-typing-agent.mp4

打开/下载视频

微信——语音消息输入到输入框并发送：

mcp/acceptance/demo/voice-typing-wechat.mp4

打开/下载视频

Shared-v2 功能（源代码实现）

Model → MCP 主机 → shared 守护进程（:47192）→ C++ 原生主机 → USB HID 0xF0/0xF1 → uMouse 设备 → Windows 输入管道

• 硬件操作：umouse_mouse_action — 在桌面物理像素坐标中移动、点击、滚动和拖动；支持带负坐标的多显示器，可选 precision: standard | high。
• 任务互斥：umouse_control 开始 → 操作 → 结束；同一时间只有一个任务可以控制鼠标和键盘；会自动清理已断开的连接。
• 只读传感器：umouse_input_status — 光标位置、实时按键状态、前台窗口标识；只读，绝不拦截输入。
• 语音听写：麦克风采集 → VAD 分段 → 可插拔 ASR 提供方 → 预览 / 最终转录文本；独立通道，绝不会抢占鼠标控制（见下文）。
• 共享守护进程：每台机器运行一个实例（端口 47192），供 ZCode / Codex / Claude 主机共享，空闲时回收。

语音听写：可插拔 ASR 提供方

这里的 ASR 并非绑定单一供应商的黑箱，而是一个精简的接口约定：实现 begin / writePcm / finishInput / cancel 并恰好一次发出 preview / segmentFinal / warning / terminal，即可成为有效的提供方。切换识别服务只需替换一个工厂函数；mcp/src/sinicloud-asr.ts 是完整的参考实现。

提供方（UMSDK_ASR_PROVIDER）	说明
sinicloud（旧版 Windows ZIP / 源代码的默认选项）	Sonicloud 开放平台流式 ASR：纯 TypeScript，无需依赖 DLL；以 16k/16bit/mono PCM 流式传输，提供中间预览；余额不足时发出警告，但不会中断流
windows-speech	Windows 内置识别器；支持离线，音频不会离开本机
whisper-cpp	可自托管的 whisper-cli + ggml 模型（路径可配置），支持 CPU 离线转录
http	自定义转录端点：输入 multipart WAV，输出 {"text"}
disabled	关闭听写；缺少提供方时会平稳降级为 asr_unavailable

凭据仅通过配置传递，并且每个会话都会热读取——无需重启即可更换密钥：默认从 <data-dir>/sinicloud_asr.json JSON 文件读取（appId / apiKey / apiSecret / userId / lanid / streamUrl / tokenUrl）；环境变量 UMSDK_ASR_APP_ID / UMSDK_ASR_API_KEY / UMSDK_ASR_API_SECRET / … 会覆盖文件中的值。绝不硬编码、绝不打印、绝不记录日志、绝不提交。旧版 v0.1.0 ZIP 附带开放平台的试用凭据；用于生产环境时请替换为自己的密钥。v0.1.1 MCPB 不含云凭据，仅接受 disabled（默认）或 windows-speech。完整的源代码提供方矩阵请参见 mcp/SHARED-V2.md。

Shared-v2 自适应定位

Windows 指针加速度（“增强指针精确度”）会使协议点到像素的增益随移动幅度变化。umouse-mcp 内置 11 步加速度增益曲线：首次使用设备时只读地从本地指针设置初始化，并在 [0.125, 10] 范围内逐帧在线学习；空闲 60 s 后逐渐回退至初始值——更换机器或设备时无需调整；初始值过时只会多花 1–2 帧。设计与测量结果：mcp/sdk-host/POSITIONING.md。

指标	standard	high
停止容差	残差 ≤ 4 px	残差 ≤ 1 px
测量结果（参考设备）	中位数 356 ms / 2 帧	最大值 1 px，平均值 0.67 px
故障模式	相同；high 最差也只会降至 ≤ 4 px 的尽力而为，残差按原样报告

Shared-v2 参考验收

准备好完整的 shared-v2 构建后，请按照验收设置指南操作。测试环境位于此仓库中，不在 v0.1.0 ZIP 内。

32 个用例会在真实浏览器页面上通过闭环验证效果：左键 / 右键 / 中键点击次数、双击间隔、滚轮 scrollTop、拖动线性度、1 px 靶心命中。

cd mcp/acceptance
$env:UMCFG = "C:\path\to\client.json"
$env:UMBUNDLE = "C:\path\to\shared-v2-bundle"
node run-matrix.mjs
# Writes acceptance-report.json; the documented reference run passed 32/32 cases.

Shared-v2 安全性与验证

• 锁定屏幕 / UAC / 安全桌面：关键操作会被拒绝，并返回 button_feedback_input_desktop_unavailable——这是安全特性，不是 bug。
• effectConfirmed 始终为 false：传输成功 ≠ 应用效果；验收实验室的页面证据才是事实依据。
• ASR 凭据只能通过本地配置文件和环境变量提供——绝不提交、打印或记录；recover 需要由人工携带 --hardware-reset-confirmed 执行。

文档

文档	内容
mcp/SHARED-V2.md	Shared-v2 安装、升级、维护与恢复
mcp/acceptance/MOUSE-CAPABILITY-TESTS.md	32 项测试目录（可复制粘贴的 MCP 调用和通过标准）
mcp/sdk-host/POSITIONING.md	弹道定位：历史、算法、跨设备矩阵
mcp/README.md	完整的 MCP 工具参考（中文）

硬件与支持

需要兼容设备、评估设备或固件检查？请联系 [email protected]，并提供目标平台、设备型号、固件版本和预期使用场景。

由 SonicloudTech（Anhui SoniCloud Intelligent Technology Co., Ltd.）维护——AI 输入硬件与语音开放平台。

• 网站：https://sinicloud.com/
• 语音开放平台：https://open.sinicloud.com/ — 为默认 ASR 提供方提供支持；注册即可获得试用额度
• 商务与技术联系：[email protected] — OEM / 分销 / 定制固件 / 联合开发；请提供目标平台、预期数量、设备型号、固件版本和预期使用场景

相关项目：uMouse SDK

想将智能鼠标硬件集成到自己的应用中？uMouse SDK 提供用于 USB HID/BLE 设备连接、按键事件和音频的 C ABI。请从英文 SDK README、集成指南或 SDK 下载开始。SDK 有自己的平台与许可矩阵；这些平台选项不会让此 MCP 服务的支持范围超出 Windows x64。请使用每个 MCP 版本随附的原生 SDK DLL，不要用独立 SDK 软件包替代。

路线图

• 跨设备自适应增益曲线（v0.4）
• 可插拔 ASR 提供方：sinicloud 流式服务，凭据完全可配置
• 由固件执行的 1–2 计数微校正帧
• 滚轮 ACK 和滚动量闭环
• 绝对定位模式

许可证

MCP 服务代码基于 MIT 许可证发布。原生 SDK 以闭源 DLL 形式提供，并附带公开头文件（include/umouse_sdk.h）。