mcp-screenshot

跨平台 MCP server，让 AI agent 自己截取微信开发者工具模拟器画面，形成「改代码 → 截图 → 看效果」闭环。

它解决什么问题

以前 agent 改完小程序看不到效果，要人工截图 → 传 OSS → 给链接。本 MCP 把这一环自动化：agent 调一个工具截当前画面，拿到本地路径后自己 Read 读取，不依赖 OSS、不依赖网络。

核心思路：agent 本身能读本地图片，所以 MCP 的职责只是「截图 → 存本地 → 返回绝对路径」，剩下的闭环 agent 自己完成。

Related MCP server: Screenshot MCP Server

工具

screenshot_capture

成功返回本地 PNG 绝对路径，agent 用 Read 工具读取该路径即可看到画面。失败返回结构化错误 + 可读的 hint（例如建议改用 scope=full 兜底）。

只截模拟器区域

scope=window 默认截整个开发者工具窗口（含目录树、调试器）。如果你只想要模拟器（手机预览）那一块画面，加参数 simulator=true：

screenshot_capture { scope: "window", simulator: true }

模拟器在窗口内的位置由环境变量 SIMULATOR_RECT 配置，格式 "x1,x2,y1,y2" 四个百分比整数（0-100），分别表示模拟器在窗口 bounds 内的左、右、顶、底边界：

{
  "mcp": {
    "servers": {
      "screenshot": {
        "type": "stdio",
        "command": "node",
        "args": ["/absolute/path/to/mcp-screenshot/dist/index.js"],
        "env": {
          "SIMULATOR_RECT": "50,64,7,99"
        }
      }
    }
  }
}

含义：模拟器位于窗口左 50% 到右 64%、顶 7% 到底 99% 的矩形区域。运行时会按当前窗口实际尺寸换算成屏幕坐标，所以窗口移动、换屏幕、调整 ZCode 窗口大小都不影响，只要开发者工具内部布局（目录树/模拟器/调试器的比例）不变。

怎么量出适合自己的百分比：先用 scope=window 截一张完整窗口图，目测模拟器四条边在窗口里的百分比位置（左边占窗口宽的百分之几、右边到百分之几、顶部从百分之几开始、底部到百分之几），填进 SIMULATOR_RECT。配一次长期用，开发者工具布局没大改就不用动。

注意：simulator=true 仅在 scope=window 时有意义（需要先定位窗口，再裁子区域）。不配 SIMULATOR_RECT 就调用 simulator=true 会返回明确错误提示。

接入 ZCode

在项目工作区 .zcode/config.json（配置文件不展开 ${...} 模板变量，必须用绝对路径）：

{
  "mcp": {
    "servers": {
      "screenshot": {
        "type": "stdio",
        "command": "node",
        "args": ["/absolute/path/to/mcp-screenshot/dist/index.js"]
      }
    }
  }
}

重启会话，输入 /mcp 查看连接状态（应显示 connected）。截图保存在项目 .screenshots/（已自动加入 gitignore）。

备注：projectRoot 默认用 server 进程的 process.cwd()；如果 ZCode 启动 server 时的 cwd 不是你期望的项目根，可设置环境变量 MCP_SCREENSHOT_PROJECT_ROOT 指向目标项目目录，截图就会存到那里的 .screenshots/。

开发

cd mcp-screenshot
bun install
bun run build      # 编译到 dist/（tsc，零错误）
bun test           # 跑测试（bun test）
bun run start      # 等价于 node dist/index.js

源码结构：

src/
├── index.ts              # stdio 入口
├── server.ts             # MCP 工具定义（screenshot_capture）
├── paths.ts              # 截图路径/gitignore 维护（纯函数，已测）
└── platform/
    ├── types.ts          # 平台捕获接口
    ├── index.ts          # 按 process.platform 分发
    ├── win32.ts          # Windows: PowerShell + System.Drawing
    └── darwin.ts         # macOS: screencapture + osascript

平台支持

设计原则

• capture() 永远 resolve，绝不 reject——失败也通过结构化的 CaptureFailure 表达。stdio MCP server 一旦 crash，整个会话的工具都没了，所以稳定性是第一约束。

• 窗口找不到是正常情况——返回清晰错误 + hint，让 agent 自己判断（例如改用 scope=full 兜底）。

• YAGNI——MVP 只截当前画面，不做点击/导航/OCR/对比。

后续规划

• v2: screenshot.list_windows 列出所有窗口，让 agent 精确指定截哪个

• v3: 接 miniprogram-automator，加 navigate/tap，真正"控制+截图"闭环

• v4: CDP 直连模拟器 Chromium，截纯渲染画面