[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-105321":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":15,"stars30d":15,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":16,"rankGlobal":10,"rankLanguage":10,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":18,"hasPages":18,"topics":20,"createdAt":10,"pushedAt":10,"updatedAt":35,"readmeContent":36,"aiSummary":10,"trendingCount":15,"starSnapshotCount":15,"syncStatus":37,"lastSyncTime":38,"discoverSource":39},105321,"mouse-mcp","SonicloudTech\u002Fmouse-mcp","SonicloudTech","Hardware mouse MCP server for AI agents on Windows x64. USB HID control and voice dictation; requires compatible uMouse hardware and firmware. 面向 AI 智能体的硬件鼠标 MCP：USB HID 控制与语音听写，需要兼容的 uMouse 设备与固件。","https:\u002F\u002Fsinicloud.com\u002F",null,"TypeScript",88,1,64,0,36.9,"MIT License",false,"main",[21,22,23,24,25,26,27,28,29,30,31,32,33,34],"ai-agents","computer-use","desktop-automation","hardware","mcp","mcp-server","model-context-protocol","mouse-control","sonicloud","speech-to-text","typescript","usb-hid","voice-input","windows","2026-11-01 00:14:11","# uMouse MCP — Hardware Mouse Control for AI Agents\n\n**English** | [简体中文](README.zh-CN.md)\n\n[![release](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCPB-v0.1.1-blue)](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-mcp\u002Freleases\u002Ftag\u002Fv0.1.1)\n[![MCP Registry](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP_Registry-published-008060)](https:\u002F\u002Fregistry.modelcontextprotocol.io\u002Fv0.1\u002Fservers\u002Fio.github.SonicloudTech%2Fmouse-mcp\u002Fversions\u002Flatest)\n[![code license](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fcode-MIT-blue.svg)](LICENSE)\n![platform](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Fplatform-Windows%20x64-6f42c1.svg)\n[![ASR](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FASR-pluggable-6f42c1.svg)](#voice-dictation-pluggable-asr-providers)\n\nGive AI agents a **real hardware mouse**. uMouse MCP is a Model Context Protocol (MCP) server for USB HID mouse control and voice dictation on Windows. Mouse movement, clicks, scrolling and dragging use a compatible uMouse device; voice input supports pluggable speech recognition providers.\n\n**Requires compatible uMouse hardware and firmware, Windows x64, and a separately installed Node.js runtime (use Node.js 22 x64).** An ordinary USB mouse is not sufficient. The MIT license covers the server code; native SDK binaries have separate terms. See [License](#license).\n\n[Download](#download) · [Quick start](#quick-start) · [Reference demos](#reference-demos) · [Documentation](#documentation) · [Compatibility & FAQ](#faq) · [Get hardware \u002F support](#hardware--support) · [uMouse SDK](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-sdk)\n\n## Download\n\n| Package | Download | Requirements |\n|---|---|---|\n| MCPB · Windows x64 · v0.1.1 | [Download MCPB](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-mcp\u002Freleases\u002Fdownload\u002Fv0.1.1\u002Fumouse-mcp-0.1.1-win-x64.mcpb) · [Release notes and SHA-256](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-mcp\u002Freleases\u002Ftag\u002Fv0.1.1) | MCPB-compatible client; compatible uMouse hardware; x64 Node.js 22+ |\n| Windows x64 · v0.1.0 | [Download ZIP](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-mcp\u002Freleases\u002Fdownload\u002Fv0.1.0\u002Fumouse-mcp-os-win-x64-0.1.0.zip) · [Release notes and SHA-256](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-mcp\u002Freleases\u002Ftag\u002Fv0.1.0) | Compatible uMouse device and firmware; Node.js installed separately |\n\n[All releases](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-mcp\u002Freleases) · [Gitee release mirror](https:\u002F\u002Fgitee.com\u002FSonicloudTech\u002Fmouse-mcp\u002Freleases\u002Ftag\u002Fv0.1.0)\n\n**MCPB installation:** import the `.mcpb` into a client that supports MCPB Node extensions. Version 0.1.1 wraps the legacy 0.1.0 runtime, includes no cloud credentials, and defaults speech recognition to `disabled`; `windows-speech` is the optional local provider. Data defaults to `~\u002F.umouse-mcp-mcpb`. See the [bilingual MCPB guide](mcpb\u002FREADME.md). Published in the [official MCP Registry](https:\u002F\u002Fregistry.modelcontextprotocol.io\u002Fv0.1\u002Fservers\u002Fio.github.SonicloudTech%2Fmouse-mcp\u002Fversions\u002Flatest) as `io.github.SonicloudTech\u002Fmouse-mcp`; metadata in [`server.json`](server.json), [publication and validation](mcpb\u002FPUBLISHING.md).\n\nThe ZIP includes production Node dependencies, native SDK DLLs, the voice preview UI and VC runtime libraries. No `npm install` or compilation is required to use the release; Node.js itself is **not** bundled.\n\n**Release and source are different installation paths:** the v0.1.0 installer registers the legacy stdio entry, `mcp\u002Fdist\u002Findex.js`. The shared-v2 tools, native host and acceptance lab described below belong to the source implementation. This ZIP is not a complete shared-v2 bundle: it does not contain that native host or the acceptance lab. Use the installed server's tool list and the README shipped inside the ZIP for release-specific behavior.\n\n## Quick start\n\nThe following steps use the original ZIP. For MCPB, use the import instructions above, then perform the status\u002Fdevice checks in step 5.\n\n1. Install Node.js 22 x64 and confirm `node --version` works. Connect a compatible uMouse USB receiver\u002Fdevice and power on the mouse. For a device or firmware compatibility check, see [Hardware & support](#hardware--support).\n2. Download the ZIP above and extract it. Open the `umouse-mcp-os-win-x64` folder; keep it in a permanent location because client configuration points to this folder.\n3. Double-click `install-agents.cmd` to register **ZCode at user scope**, or run **one** command for your chosen client from the extracted folder:\n\n| Client | PowerShell command |\n|---|---|\n| ZCode | `node mcp\u002Fscripts\u002Finstall-agents.mjs zcode` |\n| Claude Desktop | `node mcp\u002Fscripts\u002Finstall-agents.mjs claude` |\n| Cursor | `node mcp\u002Fscripts\u002Finstall-agents.mjs cursor` |\n\nThe installer adds or updates the `umouse` entry in the selected client's configuration. It also copies the bundled trial ASR configuration into the local data directory if no configuration already exists. Replace trial credentials with your own for production use.\n\n4. Open a new ZCode session, fully quit and reopen Claude Desktop, or reload the Cursor window, as appropriate.\n5. Ask your agent to call `umouse_status`, `umouse_get_capabilities`, and `umouse_list_devices`. Check SDK health, the device list, and the reported capabilities. A returned `sdkVersion` only confirms SDK access; it does **not** prove that hardware control works. Confirm the visible result of any requested mouse action before relying on it.\n\nFor a client that accepts the `mcpServers` JSON format, add this entry manually, replacing the path with your extracted folder. Other clients may require a different configuration format.\n\n```json\n{\n  \"mcpServers\": {\n    \"umouse\": {\n      \"command\": \"node\",\n      \"args\": [\"C:\\\\path\\\\to\\\\umouse-mcp-os-win-x64\\\\mcp\\\\dist\\\\index.js\"]\n    }\n  }\n}\n```\n\nManual configuration does not run the installer's ASR setup. Configure a speech provider separately if you need voice dictation; see [Voice dictation](#voice-dictation-pluggable-asr-providers).\n\nFor source development, `npm ci`, `npm run build`, and `npm test` install dependencies, build TypeScript, and run the default tests. They do not produce a complete shared-v2 native bundle. A complete public shared-v2 packaging workflow is not yet provided. The [shared-v2 development and maintenance notes (Chinese)](mcp\u002FSHARED-V2.md) and [native host build notes (Chinese)](mcp\u002Fsdk-host\u002FREADME.md) are references for that separate development path.\n\n## Reference demos\n\nThe mouse lab recording demonstrates the shared-v2 source implementation, not the legacy ZIP installation.\n\nHardware mouse driving a real browser lab page (gold arrow = system cursor overlaid on the recording) — counters, wheel and hit feedback all come from real browser events:\n\n![uMouse hardware mouse demo](mcp\u002Facceptance\u002Fdemo\u002Fmouse-capabilities.gif)\n\n### Voice typing: speak, and it lands in any window\n\nHold the device voice key, speak, release — the recognized text is typed into whatever window currently has focus. Both clips recorded live at 1080p:\n\n**Agent client (terminal)** — spoken command typed in and executed:\n\n\u003Cvideo src=\"mcp\u002Facceptance\u002Fdemo\u002Fvoice-typing-agent.mp4\" controls muted width=\"720\">mcp\u002Facceptance\u002Fdemo\u002Fvoice-typing-agent.mp4\u003C\u002Fvideo>\n\n[Open \u002F download video](mcp\u002Facceptance\u002Fdemo\u002Fvoice-typing-agent.mp4)\n\n**WeChat** — spoken message typed into the input box and sent:\n\n\u003Cvideo src=\"mcp\u002Facceptance\u002Fdemo\u002Fvoice-typing-wechat.mp4\" controls muted width=\"720\">mcp\u002Facceptance\u002Fdemo\u002Fvoice-typing-wechat.mp4\u003C\u002Fvideo>\n\n[Open \u002F download video](mcp\u002Facceptance\u002Fdemo\u002Fvoice-typing-wechat.mp4)\n\n## Shared-v2 capabilities (source implementation)\n\n> Model → MCP host → shared daemon (`:47192`) → C++ native host → USB HID `0xF0\u002F0xF1` → uMouse device → Windows input pipeline\n\n- **Hardware actions**: `umouse_mouse_action` — move \u002F click \u002F scroll \u002F drag in desktop physical-pixel coordinates, multi-monitor with negative coords, optional `precision: standard | high`.\n- **Task exclusivity**: `umouse_control` begin → actions → end; only one task drives the mouse and keyboard at a time; dead connections are cleaned up automatically.\n- **Read-only sensors**: `umouse_input_status` — cursor position, live key state, foreground window identity; read-only, never intercepts.\n- **Voice dictation**: mic capture → VAD segmentation → pluggable ASR provider → preview \u002F final transcript; an independent lane that never preempts mouse control (see below).\n- **Shared daemon**: one instance per machine (port 47192), shared across ZCode \u002F Codex \u002F Claude hosts, reclaimed when idle.\n\n## Voice dictation: pluggable ASR providers\n\nASR here is not a black box tied to one vendor — it is a tiny interface contract: implement `begin \u002F writePcm \u002F finishInput \u002F cancel` and emit `preview \u002F segmentFinal \u002F warning \u002F terminal` (exactly once), and you have a valid provider. Swapping recognition services means swapping one factory function; `mcp\u002Fsrc\u002Fsinicloud-asr.ts` is a complete reference implementation.\n\n| Provider (`UMSDK_ASR_PROVIDER`) | Notes |\n|---|---|\n| `sinicloud` (default for the legacy ZIP\u002Fsource on Windows) | Sonicloud open-platform streaming ASR: pure TypeScript, no DLL dependency; streams 16k\u002F16bit\u002Fmono PCM, interim previews, low-balance warnings without dropping the stream |\n| `windows-speech` | Built-in Windows recognizer; offline, audio never leaves the machine |\n| `whisper-cpp` | Self-hosted whisper-cli + ggml model (paths configurable), offline CPU transcription |\n| `http` | Custom transcription endpoint: multipart WAV in, `{\"text\"}` out |\n| `disabled` | Dictation off; a missing provider degrades gracefully to `asr_unavailable` |\n\nCredentials travel only through configuration and are **hot-read per session — swap keys without a restart**: by default a JSON file at `\u003Cdata-dir>\u002Fsinicloud_asr.json` (`appId \u002F apiKey \u002F apiSecret \u002F userId \u002F lanid \u002F streamUrl \u002F tokenUrl`); environment variables `UMSDK_ASR_APP_ID \u002F UMSDK_ASR_API_KEY \u002F UMSDK_ASR_API_SECRET \u002F …` override the file. Never hardcoded, never printed, never logged, never committed. The **legacy v0.1.0 ZIP** ships a trial credential for the open platform; replace it with your own key for production use. The **v0.1.1 MCPB** contains no cloud credentials and accepts only `disabled` (default) or `windows-speech`. See [mcp\u002FSHARED-V2.md](mcp\u002FSHARED-V2.md) for the full source provider matrix.\n\n## Shared-v2 adaptive positioning\n\nWindows pointer ballistics (\"Enhance pointer precision\") make the protocol-dots → pixels gain vary with amplitude. umouse-mcp ships an 11-step ballistic gain curve: read-only seeded from local pointer settings on first use of a device, learned online frame-by-frame within `[0.125, 10]`, decaying back to the seed after 60 s idle — **no tuning when you change machines or devices**; a stale seed costs 1–2 extra frames. Design and measurements: [mcp\u002Fsdk-host\u002FPOSITIONING.md](mcp\u002Fsdk-host\u002FPOSITIONING.md).\n\n| Metric | standard | high |\n|---|---|---|\n| Stop tolerance | residual ≤ 4 px | residual ≤ 1 px |\n| Measured (reference rig) | median 356 ms \u002F 2 frames | max 1 px, mean 0.67 px |\n| Failure mode | identical; high at worst degrades to ≤ 4 px best-effort, residuals reported as-is | |\n\n## Shared-v2 reference acceptance\n\nAfter preparing a complete shared-v2 build, follow the [acceptance setup guide](mcp\u002Facceptance\u002FREADME.md). The lab is in this repository, not the v0.1.0 ZIP.\n\n32 cases verify effects in closed loop on a real browser page: left \u002F right \u002F middle click counts, double-click interval, wheel `scrollTop`, drag linearity, 1 px bullseye hits.\n\n```powershell\ncd mcp\u002Facceptance\n$env:UMCFG = \"C:\\path\\to\\client.json\"\n$env:UMBUNDLE = \"C:\\path\\to\\shared-v2-bundle\"\nnode run-matrix.mjs\n# Writes acceptance-report.json; the documented reference run passed 32\u002F32 cases.\n```\n\n## Shared-v2 security and verification\n\n- Locked screen \u002F UAC \u002F secure desktop: key actions are rejected with `button_feedback_input_desktop_unavailable` — that is a safety property, not a bug.\n- `effectConfirmed` is always `false`: transport success ≠ application effect; the acceptance lab's page evidence is the ground truth.\n- ASR credentials enter only via local config file and environment variables — never committed, printed or logged; `recover` requires a human carrying `--hardware-reset-confirmed`.\n\n\u003Ca id=\"faq\">\u003C\u002Fa>\n\n## Hardware mouse MCP: frequently asked questions\n\n### Can I use an ordinary USB or Bluetooth mouse?\n\nNo. uMouse MCP needs compatible uMouse hardware and firmware that implement its hardware-control protocol. A normal mouse, a software-only cursor controller, or the SDK version string alone does not establish compatibility. Confirm the device and firmware through [hardware support](#hardware--support) before choosing a package.\n\n### Which package should I use with an MCP client?\n\nUse the [v0.1.1 MCPB](mcpb\u002FREADME.md) with a client that supports MCPB Node extensions, or the [v0.1.0 ZIP and manual configuration](#quick-start) for a stdio MCP client. Both require Windows x64, Node.js 22 x64, and compatible hardware. MCPB 0.1.1 packages the legacy 0.1.0 runtime; neither release includes the shared-v2 native host or acceptance lab. Check the installed server's tool list before using source-only examples.\n\n### Does this MCP server support macOS or Linux?\n\nThe published MCP packages target Windows x64. The separate [uMouse SDK](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-sdk) has its own platform packages for application integration; those packages do not provide macOS or Linux support for this MCP server.\n\n### Can voice dictation work without a cloud ASR service?\n\nThe MCPB package defaults to dictation disabled and optionally uses the local `windows-speech` provider. Other providers, including `whisper-cpp`, belong to the [source provider configuration](mcp\u002FSHARED-V2.md); they are not all available in MCPB. Local providers need their own runtime, language or model setup. Mouse control does not require enabling a cloud speech provider.\n\n### How do I verify that the hardware action actually worked?\n\nStart with `umouse_status`, `umouse_get_capabilities`, and `umouse_list_devices`. Then request an action in a test window and check the cursor and the application's visible response. SDK access and a successful transport receipt are separate from application effects. For a complete shared-v2 source build, use the [hardware acceptance lab](mcp\u002Facceptance\u002FREADME.md).\n\n### Should I integrate mouse-mcp or mouse-sdk?\n\nChoose this repository to expose hardware mouse actions and voice input to an AI agent through MCP. Choose [mouse-sdk](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-sdk) to receive device events and audio in your own C\u002FC++, C#, Python, or Electron application. Keep each project's hardware, package, and licensing requirements separate.\n\n## Documentation\n\n| Doc | Contents |\n|---|---|\n| [mcp\u002FSHARED-V2.md](mcp\u002FSHARED-V2.md) | Shared-v2 install, upgrade, maintenance and recovery |\n| [mcp\u002Facceptance\u002FMOUSE-CAPABILITY-TESTS.md](mcp\u002Facceptance\u002FMOUSE-CAPABILITY-TESTS.md) | The 32-case catalog (copy-paste MCP calls and pass criteria) |\n| [mcp\u002Fsdk-host\u002FPOSITIONING.md](mcp\u002Fsdk-host\u002FPOSITIONING.md) | Ballistic positioning: history, algorithm, cross-device matrix |\n| [mcp\u002FREADME.md](mcp\u002FREADME.md) | Full MCP tool reference (Chinese) |\n\n## Hardware & support\n\nNeed a compatible device, evaluation unit or firmware check? Contact [xu_heng_yu@sinicloud.com](mailto:xu_heng_yu@sinicloud.com) with your target platform, device model, firmware version and intended use case.\n\nMaintained by [SonicloudTech](https:\u002F\u002Fgithub.com\u002FSonicloudTech) (Anhui SoniCloud Intelligent Technology Co., Ltd.) — AI input hardware and the speech open platform.\n\n- Website: \u003Chttps:\u002F\u002Fsinicloud.com\u002F>\n- Speech open platform: \u003Chttps:\u002F\u002Fopen.sinicloud.com\u002F> — powers the default ASR provider; sign up for a trial quota\n- Business & technical contact: [xu_heng_yu@sinicloud.com](mailto:xu_heng_yu@sinicloud.com) — OEM \u002F distribution \u002F custom firmware \u002F co-development; include the target platform, expected volume, device model, firmware version and intended use case\n\n\u003Cimg src=\"img\u002F微信.png\" alt=\"SoniCloud contact QR code\" width=\"200\" style=\"max-width: 100%; height: auto;\">\n\n## Related project: uMouse SDK\n\nIntegrating smart-mouse hardware into your own application? [uMouse SDK](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-sdk) provides a C ABI for USB HID\u002FBLE device connections, key events and audio. Start with the [English SDK README](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-sdk\u002Fblob\u002Fmain\u002FREADME.en.md), [integration guide](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-sdk\u002Fblob\u002Fmain\u002Fdocs\u002FIntegration-Guide.en.md), or [SDK downloads](https:\u002F\u002Fgithub.com\u002FSonicloudTech\u002Fmouse-sdk\u002Freleases). The SDK has its own platform and licensing matrix; those platform options do not extend this MCP server beyond Windows x64. Use the native SDK DLLs bundled with each MCP release rather than substituting a standalone SDK package.\n\n## Roadmap\n\n- [x] Cross-machine adaptive gain curves (v0.4)\n- [x] Pluggable ASR providers: sinicloud streaming, fully configurable credentials\n- [ ] Firmware-executed 1–2 count micro-correction frames\n- [ ] Wheel ACK and scroll-amount closed loop\n- [ ] Absolute positioning mode\n\n## License\n\nThe MCP server code is released under the [MIT license](LICENSE). The native SDK ships as closed-source DLLs with a public header (`include\u002Fumouse_sdk.h`).\n",2,"2026-10-31 04:26:25","CREATED_QUERY"]