Magic Mouse
README.md
<div align="center">
# Magic Skill · Magic Mouse
**Give Cursor Agent hands on your desktop — a Cursor-style desktop pet that operates your whole computer.**
[](https://github.com/WangYuecheng1106/Magic-Mouse/releases/latest)
[](https://github.com/WangYuecheng1106/Magic-Mouse/releases)
[](LICENSE)
[](https://github.com/WangYuecheng1106/Magic-Mouse/releases)
[](https://github.com/WangYuecheng1106/Magic-Mouse/stargazers)
[](https://github.com/WangYuecheng1106/Magic-Mouse/issues)
[English](#english) · [中文](#中文) · [Download](#download) · [Docs](docs/使用文档.md) · [Developer Guide](docs/developer-guide.md)
<br/>
<a href="https://github.com/WangYuecheng1106/Magic-Mouse">
<img height="165" src="https://github-readme-stats.vercel.app/api/pin/?username=WangYuecheng1106&repo=Magic-Mouse&theme=radical&hide_border=true&bg_color=0d1117&title_color=58a6ff&icon_color=58a6ff" alt="Magic-Mouse repo card" />
</a>
<a href="https://github.com/WangYuecheng1106">
<img height="165" src="https://github-readme-stats.vercel.app/api/top-langs/?username=WangYuecheng1106&layout=compact&theme=radical&hide_border=true&bg_color=0d1117&title_color=58a6ff&langs_count=6" alt="Top languages" />
</a>
</div>
---
<a id="download"></a>
## 📥 Download / 下载
> **Windows 10 / 11 only** — Download the installer below, run it, restart Cursor once. Ready to use.
>
> **仅支持 Windows 10 / 11** — 直接下载下方安装包，安装后重启一次 Cursor 即可使用。
### v0.1.0 Installers / 安装包
| App | Size | Download |
|-----|------|----------|
| **Magic Mouse** ⭐ 主程序（桌宠 + Hub） | 4.39 MB | [**⬇ Magic Mouse_0.1.0_x64-setup.exe**](releases/Magic%20Mouse_0.1.0_x64-setup.exe) |
| **Magic Skill Launcher** 可选控制台 | 2.09 MB | [**⬇ Magic Skill 控制台_0.1.0_x64-setup.exe**](releases/Magic%20Skill%20%E6%8E%A7%E5%88%B6%E5%8F%B0_0.1.0_x64-setup.exe) |
[](releases/Magic%20Mouse_0.1.0_x64-setup.exe)
[](releases/Magic%20Skill%20%E6%8E%A7%E5%88%B6%E5%8F%B0_0.1.0_x64-setup.exe)
> Installers are stored in the [`releases/`](releases/) folder of this repo.
> 安装包位于本仓库 [`releases/`](releases/) 目录，点击上方链接即可下载。
**After install / 安装后：**
1. Launch **Magic Mouse** from Start Menu → **Magic Mouse**
2. On first run it auto-installs the Cursor Skill, writes `mcp.json`, and pairs locally
3. **Restart Cursor** once
4. In Cursor chat, try: `用 Magic Mouse 查一下状态` — reply should say the pet is online
<details>
<summary><b>Manual build from source / 从源码构建</b></summary>
```bash
git clone https://github.com/WangYuecheng1106/Magic-Mouse.git
cd Magic-Mouse
npm run setup
npm run build:mouse # → apps/magic-mouse/src-tauri/target/release/bundle/nsis/
npm run build:launcher # optional; use: npx tauri build --bundles nsis
npm run shortcut # desktop shortcut (Windows)
```
</details>
---
<a id="english"></a>
## English
### What is Magic Skill?
**Magic Skill** is a bridge between **Cursor Agent** and your **real desktop**. It combines:
| Component | Role | Stack |
|-----------|------|-------|
| **Magic Mouse** | A Cursor-style desktop pet that roams your screen, shows status, and physically moves mouse & keyboard | Tauri 2 · Rust · Svelte |
| **Magic Skill (MCP)** | Cursor Skill + MCP server — exposes 17+ `mm_*` tools to the Agent | Node 20+ · TypeScript · MCP SDK |
```
You in Cursor → Agent calls mm_* tools → MCP Server → ws://127.0.0.1:3721 → Magic Mouse → Windows OS
```
Inspired by **Codex Computer Use** and **Agent-S**: screenshot → reason → single action → verify → loop (≤30 steps).
### Features
- 🐭 **Desktop pet** — Cursor isometric cube avatar, roam, drag, double-tap reactions
- 🖱️ **Full computer use** — screenshot, click, type, hotkey, scroll, drag, app launch, window focus
- 🤖 **Cursor integration** — auto Skill install, MCP registration, local token pairing
- 🛡️ **Safety first** — localhost-only Hub, audit log, approval gates, **Ctrl+Shift+.** emergency stop
- 💬 **DeepSeek tab** — optional on-device API chat in the pet panel
- 📋 **Clipboard history**, custom YAML actions, i18n UI
### Quick start (developers)
```bash
npm run setup
npm run dev:mouse # Vite :1420 + Hub :3721
```
Verify in Cursor:
```text
用 Magic Mouse 查一下状态
```
See [docs/使用文档.md](docs/使用文档.md) for full usage, shortcuts, and FAQ.
### Pet controls
| Action | Effect |
|--------|--------|
| Click pet / tray icon | Open Magic Mouse panel |
| Double-click pet | Poke animation |
| Ctrl+Alt+P | Toggle panel |
| Drag pet | Move (position persisted) |
| Ctrl+Shift+. | Emergency stop |
| Ctrl+Shift+Y / N | Approve / deny pending action |
### Project layout
```
magic-skill/
├── apps/magic-mouse/ # Desktop pet (main user app)
├── apps/magic-launcher/ # Optional control console
├── packages/cursor-skill/ # SKILL.md + MCP server
├── scripts/ # setup, pair, shortcut, install-skill
├── docs/ # User & developer docs
└── shared/ # WebSocket protocol
```
### Safety
- WebSocket binds to **127.0.0.1** only, token-authenticated
- Mutating actions logged to `~/.magic-skill/audit.log`
- Destructive ops require user approval in the pet panel
### Contributing & license
MIT License — see [LICENSE](LICENSE). Bug reports and PRs welcome on [Issues](https://github.com/WangYuecheng1106/Magic-Mouse/issues).
---
<a id="中文"></a>
## 中文
### Magic Skill 是什么？
**Magic Skill** 让 **Cursor Agent** 拥有操作你整台电脑的能力。它由两部分组成：
| 组件 | 作用 | 技术栈 |
|------|------|--------|
| **Magic Mouse** | Cursor 风格桌宠，在桌面上漫游、展示状态，并驱动真实鼠标键盘 | Tauri 2 · Rust · Svelte |
| **Magic Skill (MCP)** | Cursor Skill + MCP 服务，向 Agent 暴露 17+ 个 `mm_*` 工具 | Node 20+ · TypeScript · MCP SDK |
```
你在 Cursor 说话 → Agent 调用 mm_* → MCP Server → ws://127.0.0.1:3721 → Magic Mouse → 操作系统
```
设计思路融合 **Codex Computer Use** 与 **Agent-S**：截图 → 推理 → 单步动作 → 验证 → 循环（约 ≤30 步）。
### 核心功能
- 🐭 **桌面宠物** — Cursor 立体方块形象，漫游、拖动、双击互动
- 🖱️ **完整 Computer Use** — 截图、点击、输入、快捷键、滚动、拖拽、启动应用、聚焦窗口
- 🤖 **Cursor 深度集成** — 自动安装 Skill、写入 MCP、本地令牌配对
- 🛡️ **安全可控** — 仅本机 Hub、审计日志、操作审批、**Ctrl+Shift+.** 紧急停止
- 💬 **问 DeepSeek** — 面板内可选的本机 API 对话
- 📋 **剪贴板历史**、YAML 自定义动作、中英界面
### 开发者快速开始
```bash
npm run setup
npm run dev:mouse # Vite :1420 + Hub :3721
```
在 Cursor 聊天验证：
```text
用 Magic Mouse 查一下状态
```
完整说明见 [docs/使用文档.md](docs/使用文档.md)。
### 桌宠操作
| 操作 | 效果 |
|------|------|
| 单击宠物 / 托盘图标 | 打开 Magic Mouse 面板 |
| 双击宠物 | 戳戳动画 |
| Ctrl+Alt+P | 打开/关闭面板 |
| 拖动宠物 | 移动位置（重启后记住） |
| Ctrl+Shift+. | 紧急停止 |
| Ctrl+Shift+Y / N | 批准 / 拒绝待确认操作 |
### 目录结构
```
magic-skill/
├── apps/magic-mouse/ # 桌宠（主程序）
├── apps/magic-launcher/ # 可选控制台
├── packages/cursor-skill/ # SKILL.md + MCP 服务
├── scripts/ # 安装、配对、快捷方式
├── docs/ # 用户与开发者文档
└── shared/ # WebSocket 协议
```
### 安全说明
- WebSocket 仅绑定 **127.0.0.1**，令牌鉴权
- 修改类操作写入 `~/.magic-skill/audit.log`
- 破坏性操作需在桌宠面板中批准
### 参与贡献
MIT 开源协议 — 详见 [LICENSE](LICENSE)。欢迎通过 [Issues](https://github.com/WangYuecheng1106/Magic-Mouse/issues) 反馈问题或提交 PR。
---
<div align="center">
**Made with ❤️ for Cursor users**
</div>
This server cannot be deployed
Maintenance
ActivityStale
ResponsivenessNo issues