ScreenHand

使用说明（简明、面向开发者和部署运维）

• 项目简介 ScreenHand 是一个本地 MCP 服务器，使用 MCP 协议与 MCP 客户端（如 Claude/Code/Cursor 等）交互，提供 82 种工具，涵盖桌面自动化、Chrome 浏览器控件、内存学习、任务队列、Playbook 引擎等，目标是在本地环境为 LLM 客户端提供快速、可扩展的桌面上下文服务。

• 主要功能点

  • MCP 服务端：标准 JSON-RPC 调用与响应，支持初始化、工具查询、工具执行等标准 MCP 交互。
  • 资源与工具：提供屏幕截图、OCR、桌面 UI 自动化（Accessibility/UI Automation）、Chrome CDP 控制、键盘鼠标输入等工具。
  • Playbook/记忆系统：内存/学习模块、策略（策略缓存、回忆引擎、错误模式），支持平台相关的 Playbook 引擎和任务队列。
  • 会话与并发：多代理会话、会话租期、任务队列、后台守护进程（Supervisor/Worker）、Playbook 驱动等。
  • 本地化部署：支持 macOS 和 Windows，原生桥接实现（Swift/ C#），通过统一的 JSON-RPC 接口暴露功能。
  • 扩展性：提供 mcp-entry.ts 等模块化入口，便于后续替换适配器、增添新的运行时支持。

• 安装与运行步骤

  1. 克隆项目并安装依赖
     • 在命令行执行常规安装步骤（包含 Node 依赖与本地原生桥接的编译需求）。
  2. 构建本地桥接（可选，若运行环境需要本地原生桥接）
     • 运行 build:native 等构建步骤来生成 macOS/Windows 桥接二进制。
  3. 启动 MCP 服务器
     • 使用 npx tsx 路径/to/screenhand/mcp-desktop.ts 启动 MCP 服务器，服务器将使用标准的 stdio 传输方式暴露 JSON-RPC 接口。
  4. 与客户端对接
     • MCP 客户端通过 JSON-RPC 与服务器通信，配置中需提供服务器启动命令和参数（见下方配置示例）。

• 服务器配置（MCP 客户端需要的配置信息） 下面的配置格式用于 MCP 客户端连接 ScreenHand 的 MCP 服务器。请将 path/to/screenhand/mcp-desktop.ts 替换为实际服务器脚本路径。 { "mcpServers": { "screenhand": { "command": "npx", "args": ["tsx", "/path/to/screenhand/mcp-desktop.ts"] } // 说明：transport 使用默认的 stdio，可以与 MCP 客户端进行 JSON-RPC 通信 } }

• 基本使用方法

  • 启动后，MCP 客户端通过标准 MCP 协议初始化并获取服务器能力信息与工具列表。
  • 客户端可以读取资源、注册并调用工具、获取 Prompt 模板等，服务器根据请求返回 JSON-RPC 风格的响应。
  • ScreenHand 提供会话管理、工具执行日志和内存/学习的自动回调提示，便于 LLm 客户端进行高效的任务编排。
  • 如需桌面自动化，服务器会通过本地原生桥接调用系统 API，支持 macOS 的 Accessibility/AX、Windows 的 UI Automation，以及 Chrome CDP 控制等能力。

• 相关注意事项

  • 运行环境：macOS 与 Windows，需具备相应的本地桥权限与依赖。
  • 安全性：服务器端执行涉及 UI 操作的工具时，请由客户端控制访问权限与执行范围。
  • 部署扩展：可结合 supervisor、worker、Playbook 引擎等模块实现长期、可靠的后台任务处理与自动化。

• 参考与扩展

  • ScreenHand 提供了 mcp-desktop.ts 作为 MCP 服务器的核心入口，包含 82 种工具与完整的架构模块，适合在本地对接 LLM 客户端完成上下文服务与外部功能访问。