mcp-see-screen
# mcp-see-screen
**让任意支持 MCP 的 agent 实时「看见」屏幕**——按画面变化量筛帧、把关键帧拼成一张图,静止画面几乎不花 token。
核心算法来自 [dsh-see-now](https://github.com/SAOS-3624/dsh-see-now)(Apache-2.0),但**完全剥离 DSH 依赖**:不装 DSH、不用它的工具契约、不写它的目录。一个标准的 stdio MCP server,Claude Desktop / Cursor / Cline / WorkBuddy / Continue 等都能接。
## 来源与改造说明(重要)
**这个项目是「复制 + 改造」,不是从零原创。**
| 项 | 说明 |
|---|---|
| 上游 | [SAOS-3624/dsh-see-now](https://github.com/SAOS-3624/dsh-see-now) v0.2.5 |
| 许可 | Apache-2.0;上游的 `LICENSE` 与 `NOTICE` 原样随附,版权归 SAOS-3624 |
| 复制范围 | `src/vendor/` 下 10 个纯 JS 核心模块(采集、判帧、装箱、拼图、token 计算等)逐字复制自上游 `src/` |
| 改造范围 | 把上游这个 **DSH 专用插件**改造成**通用 MCP server**,去掉 DSH 宿主依赖 |
**具体改了什么:**
1. **换协议层**:上游靠 DSH 私有的工具契约(tool-spec.js)与斜杠命令;这里换成标准 MCP stdio server(`@modelcontextprotocol/sdk` + zod),注册 5 个工具,任何支持 MCP 的 agent 都能接。上游的 DSH 专属模块(`chat.js` / `window.js` / `talk.js` 等)**没有复制**。
2. **ffmpeg 发现通用化**:上游写死 `~/.dsh/tools/ffmpeg/bin`;改成 `MCP_SEE_FFMPEG` → PATH → 常见目录 → 各 Python venv 里的 imageio-ffmpeg(有界扫描 + 缓存),不依赖 DSH 安装。
3. **配置路径独立**:上游用 `~/.dsh/see-now/`;改成 `~/.mcp-see-screen/`(可用 `MCP_SEE_HOME` 改),区域与默认值互不干扰。
4. **修了上游一个真 bug**:`src/vendor/capture.js` 的 `isDda()` 在 Windows `engine:auto` + region(走 gdigrab CPU 抓屏)时误加 `hwdownload,format=bgra`,ffmpeg 报 -22、0 帧;已改为有 region 时关闭。`test/core.test.mjs` 有回归测试守住。
5. **新增**:`see_status` / `see_stop` 运维工具、file/camera/rtmp 三种采集源的封装参数、区域持久化与画质档位对外暴露、11 项单元测试。
**没有复制的部分**:上游的音频回环抓声(WASAPI/PulseAudio)、ASR 转写、TTS 朗读、Tk 悬浮窗、`say` 语音通道、`/seenow` 斜杠命令、DSH 配置面板——这些与 DSH 宿主强绑定,不适配通用 agent。
想追溯原始实现请直接看上游仓库;本项目只维护「通用 MCP 化」这一层。改动位置也在 `src/vendor/capture.js` 里有行内注释标明。
## 为什么不是「每 2 秒截一张屏」
| 做法 | 问题 |
|---|---|
| 定时全屏截图 | 1 分钟 30 张,全是重复画面,token 烧穿 |
| 隔 30 秒截一张 | 中间发生什么全丢了,AI 只会说「看起来你在用电脑」 |
这里换了个思路:**先给每帧打变化分(0–255),只留有信息量的帧,再把几帧拼进同一张图**。一张图的固定成本摊到 4~8 帧上——多留一帧几乎免费,漏掉一帧才贵。静止桌面 20 秒才出一张兜底帧。
## 安装
```bash
git clone <this-repo> mcp-see-screen
cd mcp-see-screen
npm install
```
Node ≥ 20。**ffmpeg 必需**(自动探测顺序:`MCP_SEE_FFMPEG` → PATH → 常见目录 → 各 Python venv 里的 imageio-ffmpeg)。找不到时工具会返回可照做的安装提示。也可显式指定:
```bash
export MCP_SEE_FFMPEG=/path/to/ffmpeg # Windows: set MCP_SEE_FFMPEG=C:\path\ffmpeg.exe
```
## 接入各 agent
### WorkBuddy(本机 ~/.workbuddy/mcp.json)
```json
{
"mcpServers": {
"see-screen": {
"command": "node",
"args": ["D:/workbuddySpace/video/mcp-see-screen/src/server.js"],
"env": { "MCP_SEE_QUALITY": "low" }
}
}
}
```
写入后在 WorkBuddy 连接器管理页右上角「自定义连接器」里点 **Trust** 启用(新 MCP 不会自动激活)。
### Claude Desktop(claude_desktop_config.json)
```json
{
"mcpServers": {
"see-screen": {
"command": "node",
"args": ["/absolute/path/mcp-see-screen/src/server.js"]
}
}
}
```
### Cursor / Cline / Windsurf / Continue
这些客户端都支持 stdio MCP,配置格式同上(`command: node`,`args: [server.js 绝对路径]`)。具体入口:Cursor → Settings → MCP;Cline → MCP Servers → Configure;Continue → `~/.continue/config.yaml` 的 `mcpServers`。
## 工具一览
| 工具 | 作用 |
|---|---|
| `see_screen` | 看屏幕/摄像头/视频文件。返回一张 PNG(image content)+ 帧清单文本(text content) |
| `see_region` | 限定只看屏幕一块(`"x,y,w,h"` 物理像素,`"off"` 取消),持久化 |
| `see_status` | 采集状态、ffmpeg 来源、已见帧数、错误与 stderr 尾部——排查「看不到」先调它 |
| `see_stop` | 停掉常驻采集,避免后台吃 CPU |
| `see_help` | 完整手册:画质/token 换算、节奏门槛、平台依赖、已知限制 |
### `see_screen` 关键参数
| 参数 | 说明 |
|---|---|
| `action` | `watch`(默认,等到攒够一张有变化的图)/ `peek`(立刻返回当前一帧) |
| `seconds` | watch 最多等多久(默认 30 秒,上限 300);攒够提前返回,到点强制出当前帧 |
| `source` | `screen` / `camera` / `file` / `rtmp`,配 `path` / `device` / `url` |
| `quality` | `low`(798×450,~222 token)/ `standard`(392)/ `high`(560)/ `ultra`(860) |
| `pace` | `calm`(门槛 20,省)/ `normal`(12,默认)/ `dense`(7,灵敏)/ `game-economic`(80,高速运动) |
| `region` | `"x,y,w,h"`,只盯一块,按区域比例出竖/横图;不传则用上次保存的 |
| `scene` | `true` = 逐场景模式:每换一次画面单独给一张满幅图 |
| `fps` | 采集帧率,默认 12 |
**用法建议**:给 agent 的提示里说清楚——`watch` 是阻塞的,它本身就是「等用户操作」的停顿,拿到图后直接继续下一轮 `watch`,别结束对话;`peek` 用来立刻核对当前画面;读不清小字就把 `quality` 调高再 peek,不要猜。
## 平台依赖
| 平台 | 屏幕引擎 | 额外要求 |
|---|---|---|
| Windows | `ddagrab`(0.28 核)→ `gdigrab` 自动回退 | 无 |
| macOS | `avfoundation` | 给运行 MCP 的 App 开「屏幕录制」权限(没权限不报错,只是全黑) |
| Linux | `portal`(ScreenCast → PipeWire → gst) | `python3-gi` / `gstreamer1.0-plugins-base` / `gstreamer1.0-pipewire`;无桌面环境的服务器用不了 |
摄像头和视频文件源跨平台走 ffmpeg,无需屏幕权限。
## 配置
落在 `~/.mcp-see-screen/`(可用 `MCP_SEE_HOME` 改):
- `region.json` — 当前框选区域
- `config.json` — 默认值:`{"quality":"low","pace":"normal","fps":12,"engine":"auto","ffmpeg":"","scene":false}`
环境变量覆盖文件:`MCP_SEE_QUALITY` / `MCP_SEE_PACE` / `MCP_SEE_FPS` / `MCP_SEE_ENGINE` / `MCP_SEE_FFMPEG` / `MCP_SEE_IDLE_MS`(默认 120000,闲置多久自动停采集)。
## 已知限制
- **只认「画面变了」,不认「语义变了」**:长得像但内容不同的两页可能算没变;同一句话换了排版算变化。不做跨帧语义去重。
- **抓的是前台像素**:被遮挡/最小化的窗口抓不到;锁屏、UAC 安全桌面、远程桌面下退化为纯色底板。需要抓后台窗口请配 OBS 虚拟摄像头作源。
- **音频台词(ASR)这一版没做**:跨平台依赖太重(Windows WASAPI / macOS BlackHole / Linux PulseAudio + 转写服务),留待后续。
- **长会话的 token 大头在历史累积**:单张图 222 token 很便宜,但图在会话里是 base64,陪看一两个小时后建议开新会话。
- 修改过上游 `capture.js` 一处 bug:Windows `auto` + region 时误加 `hwdownload` 导致 0 帧(`test/core.test.mjs` 有回归测试守住)。
## 验证
```bash
npm test # 11 项:参数、区域、PNG、token 阶梯、ffmpeg 参数回归
npm run check # 语法检查
```
## 协议与致谢
本项目为 [dsh-see-now](https://github.com/SAOS-3624/dsh-see-now) 的复制与改造版本(Apache-2.0)。核心判帧/拼图算法 vendored 自上游 `src/`,LICENSE 与 NOTICE 原样随附,版权归 SAOS-3624。具体复制/改造边界见上文「来源与改造说明」。MCP 协议由 `@modelcontextprotocol/sdk` 实现。
TDQS
Scored across 5 tools
Each tool has a clearly distinct role: see_screen captures, see_region restricts capture, see_stop halts it, see_status reports runtime diagnostics, and see_help is declarative documentation. The only mild adjacency is see_status vs see_help, but the descriptions explicitly separate 'can't see the screen' troubleshooting from parameter-selection guidance.
All five tools use the same see_ + noun pattern (see_screen, see_status, see_region, see_stop, see_help), giving a predictable, readable surface with no mixing of conventions.
Five tools map exactly onto the lifecycle needs of a screen-capture server: capture, scope, halt, inspect state, and read docs. Nothing is redundant and nothing feels padded.
The surface covers capture (watch/peek), region scoping, stopping, status, and documentation, which handles the core workflow end to end. Minor gaps remain, such as no tool for persisting default quality/pace settings or managing capture source selection outside of per-call parameters.