macinput (Sigma711)

macinput

语言： 英语 | 中文

macinput 是用于AI代理的macOS键盘、鼠标和屏幕截图控制工具。此存储库现在被构造为可安装的Python项目和MCP服务器，因此桌面代理可以通过标准的MCP工具调用来控制macOS GUI。

该项目有两个目标：

• 提供稳定的低级macOS输入和屏幕截图原语。
• 为MCP服务器提供实用的工具界面、运行时安全限制和部署指南。

特性

• 鼠标移动、左键单击、右键单击和双击
• 当前鼠标位置查找
• 按键、向下键、向上键和修饰符组合
• Unicode文本输入
• 剪贴板支持粘贴输入
• 带有自动清理功能的全屏截图
• MCP资源和代理指导提示模板

用例

• 控制macOS应用程序的桌面AI代理
• UI自动化原型
• 人机交互桌面工作流程
• 屏幕截图观察加键盘/鼠标动作代理循环

需求

• macOS
• Python 3.10+
• 启动主机应用程序必须具有：

- 无障碍权限 - 屏幕录制权限

重要提示：权限适用于启动MCP服务器的程序，而不仅仅是Python。如果您通过Claude Desktop、Terminal、iTerm2、Cursor或VS Code启动，则必须授予该主机应用程序权限。

安装

uv

uv sync

pip

python -m pip install -e .

运行MCP服务器

stdio 是桌面AI客户端的推荐默认值：

macinput-mcp

如果您的MCP主机需要HTTP传输：

macinput-mcp --transport streamable-http --host 127.0.0.1 --port 8000 --path /mcp

MCP客户端配置示例

通用的 stdio 配置：

{
  "mcpServers": {
    "macinput": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/macinput",
        "run",
        "macinput-mcp"
      ]
    }
  }
}

如果软件包已安装到当前环境中：

{
  "mcpServers": {
    "macinput": {
      "command": "macinput-mcp",
      "args": []
    }
  }
}

可用工具

• get_server_settings
• get_mouse_position
• move_mouse
• click_mouse
• scroll_mouse
• press_keyboard_key
• keyboard_key_down
• keyboard_key_up
• type_text_input
• paste_text_input
• capture_screenshot
• cleanup_screenshot_file

可用资源和提示

资源：

• macinput://overview
• macinput://best-practices
• macinput://permissions

提示：

• ui_action_protocol(goal, current_context="")

这些是产品表面的一部分，不是装饰。它们允许主机将使用指南与服务器一起发送，而不是在每个系统提示中重写。

推荐用法

对于用户：

1. 更喜欢 stdio 用于桌面代理集成。
2. 在首次实际运行之前验证macOS权限。
3. 更喜欢专用的macOS帐户、测试机或VM进行自动化。
4. 保持截图TTL简短，以减少数据残留。

对于代理商：

1. 行动前截取屏幕截图。
2. 一次执行一个状态更改操作。
3. 在点击、快捷方式或文本提交后捕获新的屏幕截图。
4. UI更改后，不要重复使用旧坐标。
5. 保持键入的文本简短且针对特定任务。
6. 当不再需要时，清理屏幕截图。

环境变量

• MACINPUT_DEFAULT_SCREENSHOT_TTL

- 默认屏幕截图清理超时（秒）。违约： 30

• MACINPUT_MAX_SCREENSHOT_TTL

- 允许的最大屏幕截图保留时间（秒）。违约： 300

• MACINPUT_MAX_TYPING_LENGTH

- 每次键入操作的最大字符数。违约： 2000

• MACINPUT_MIN_ACTION_DELAY

- 每次工具操作后的最小延迟。违约： 0.05

• MACINPUT_DEFAULT_TYPING_INTERVAL

- 默认每字符键入间隔。违约： 0.02

用作Python库

from macinput import click, move_to, press_key, type_text, capture_screen

move_to(400, 300)
click()
type_text("hello macOS")
press_key("a", modifiers=["command"])
path = capture_screen(cleanup_after=10)
print(path)

发展

项目布局

src/macinput/
  __init__.py
  __main__.py
  cli.py
  keyboard.py
  mouse.py
  screenshot.py
  server.py
  settings.py
docs/
  mcp-engineering.md
tests/

本地工作流

uv sync --extra dev
uv run pytest
uv run ruff check .

GitHub操作

• CI工作流程：
• 发布工作流程：

CI工作流在以下对象上运行lint和测试 push 和 pull_request发布工作流程基于以下内容构建发行版 workflow_dispatch 以及版本标签，例如 v0.1.0，然后上传工件并发布到PyPI（如果您的存储库配置为可信发布）。

项目规则

• 将低级自动化与MCP服务器层分开。
• 保持MCP工具小巧稳定。
• 更喜欢 stdio 默认情况下。
• 保持状态更改操作的可解释性和可组合性。
• 记录用户集成和开发人员维护工作流程。

文档

• 工程注意事项： docs/mcp-engineering.md
• 用户指南： docs/user-guide.md
• 代理商最佳实践： docs/agent-best-practices.md
• 开发者指南： docs/developer-guide.md

局限性

• 仅限macOS
• 需要真正的GUI会话
• CI可以验证导入和配置，但UI注入仍然需要进行真实的机器验证
• paste_text_input 使用系统剪贴板，当前仅保留/恢复纯文本剪贴板内容
• press_keyboard_key, keyboard_key_down，以及 keyboard_key_up 接受以下任一字符串键 "3" 或数字输入，如 3
• 不包括OCR、UI元素检测或语义窗口理解

建议的后续工作

1. 添加 LICENSE.
2. 添加发布自动化。
3. 在真正的macOS运行器上添加烟雾测试。
4. 添加一个 examples/ 常见MCP主机的目录。
5. 添加可选区域屏幕截图、输出目录和审计日志。