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 兜底）。

接入 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，截纯渲染画面