# macOS Native Computer MCP

让支持 MCP 的 Agent 通过系统截图操作 macOS 鼠标和键盘。执行器通过 Quartz 发送移动、点击、滚轮、Unicode 文本和快捷键事件，不需要浏览器调试连接或网页脚本注入。

支持十个工具：查看桌面状态、切换前台应用、截图、移动、停顿、点击、滚动、输入文字、快捷键和换行。多步任务可以复用同一个 MCP 连接；动作也可以在同一次响应中附带截图，由 Agent 观察后决定下一步。

## 安装

需要 macOS 图形桌面、Python 3.11+、uv 和 Xcode Command Line Tools。进入源码根目录：

```sh
sh install.sh
.venv/bin/python doctor.py
.venv/bin/python mcp_config.py --format json
```

完整步骤见 [安装指南](docs/INSTALL.md)，工具参数与坐标换算见 [使用指南](docs/USAGE.md)。`install.sh` 只构建和执行程序检查；系统辅助功能和屏幕录制权限需要使用者授权。`doctor.py` 的 `build_ok` 表示构建和 MCP 检查结果，`ready_for_input` 表示系统是否允许发送输入，截图需要另行验证。

配置生成器会根据当前安装位置生成宿主配置，仓库不保存个人目录。源码可以放在含空格或中文的目录里；移动后需要重新建立虚拟环境、构建并更新宿主入口。

## 动作与安全检查

默认动作库按鼠标 70%、触控板 30% 选择类别，再选择一个完整动作，保留轨迹、时长、落点和按住时间之间的对应关系。公开数据仅保留归一化动作及执行所需的相对时长，没有原始会话编号、采样日期、桌面坐标或原始文件哈希。这些模板来自有限样本，不代表所有使用者的操作习惯。

点击限制在调用者指定的安全圆内，允许重复落点，不强制抖动；短于 10 ms 的观测间隔保留原值，发送时使用 10 ms 下限。显式传入时长会覆盖模板默认值。`calibration-lock.json` 校验动作库内容，构建时会核对哈希。

发送输入前会检查前台应用和系统权限。按住 Escape 或把鼠标移到全局左上角 4×4 点区域可中止输入。同一时刻只允许一个输入操作。工具返回成功表示事件已发送，任务是否完成还需要看后续截图；结果不明确时不要直接重试点击。

键盘不读写剪贴板；文本换行发送真实 Return。未实现对象拖拽、多点触控、触控板硬件身份模拟和拼音输入法逐字选词。MCP 仅通过 stdio 运行，本地验证页仅监听回环地址。

## 项目结构

```text
server.py / client.py       MCP 服务和命令行客户端
NativeInput.swift           Quartz 输入与动作计划
build.sh / install.sh       本机编译、签名和安装检查
run-mcp.sh / mcp_config.py   启动入口和宿主配置生成
doctor.py / package.py      诊断与源码打包
calibration*.json           归一化动作库及校验锁
docs/                       安装、使用、开发和验证说明
tools/                      采样服务、拟合、离线检查和实机验证
web/                        本地验证页和采样页
tests/                      程序测试与采样页脚本检查
```

开发与重新拟合见 [开发指南](docs/DEVELOPMENT.md)，验证方式和限制见 [验证说明](docs/VALIDATION.md)。历史实验脚本和记录不是运行依赖，不包含在公开项目中。

## 分发与隐私

```sh
.venv/bin/python package.py
```

输出 `dist/macos-native-computer-mcp.tar.gz`，包含完整源码、测试、文档、动作库和文件哈希清单。接收者在自己的 Mac 上构建并授权。打包使用明确的文件范围，排除虚拟环境、编译产物、原始采样、截图和会话日志。

运行时生成的 `artifacts/` 可能包含输入文字、桌面画面、应用名称和显示器布局，已被 Git 忽略。本地冻结清单和宿主配置也不应提交。提交前仍需查看实际暂存的文件，尤其不要强制加入被忽略的记录。

本项目采用 [MIT 许可证](LICENSE)。