# ts-screenshot-mcp

一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的电脑屏幕截图服务。通过 stdio 传输层与 MCP 客户端（如 Trae）通信，支持截取整个屏幕或指定矩形区域，并将截图保存为 PNG 文件、返回图片数据。

## 功能

| 工具名 | 说明 |
| --- | --- |
| `take_screenshot` | 截取整个屏幕，返回图片并保存到本地 |
| `capture_region` | 截取屏幕指定矩形区域，返回图片并保存到本地 |

## 技术栈

- TypeScript
- `@modelcontextprotocol/sdk`：MCP 协议实现
- `sharp`：区域截图的图像裁剪
- PowerShell（Windows `System.Drawing`）：底层屏幕捕获

> 说明：屏幕捕获使用 Windows 自带的 PowerShell + `System.Drawing`（`CopyFromScreen`）实现，避免了 `screenshot-desktop` 在 Windows 上需要现场用 `csc.exe` 编译辅助程序导致的兼容性问题。

## 环境要求

- Windows 操作系统（当前实现依赖 PowerShell 的 `System.Drawing` / `System.Windows.Forms`）
- Node.js（建议 18+）
- npm

## 安装

```powershell
npm install
```

## 构建

```powershell
npm run build
```

编译产物输出到 `dist/index.js`。

## 配置到 MCP 客户端（以 Trae 为例）

在 Trae 的 MCP 管理界面新增一个 **stdio** 类型的服务器，配置如下：

| 配置项 | 值 |
| --- | --- |
| 名称 | `screenshot`（可自定义） |
| command | `node` |
| args | `["dist/index.js"]` |
| cwd | `f:\university\grade4\item\MCP` |

对应的 JSON 配置：

```json
{
  "mcpServers": {
    "screenshot": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "f:/xxx/MCP"
    }
  }
}
```

配置完成后重启/刷新 MCP 服务器，即可在客户端中调用相关工具。

## 工具说明

### take_screenshot

截取整个屏幕。

- 入参：无
- 返回：一张 PNG 图片，同时保存到 `screenshots/screenshot-<时间戳>.png`

### capture_region

截取屏幕指定矩形区域。

- 入参：

| 参数 | 类型 | 说明 |
| --- | --- | --- |
| `x` | number | 左上角 X 坐标 |
| `y` | number | 左上角 Y 坐标 |
| `width` | number | 宽度 |
| `height` | number | 高度 |

- 返回：一张 PNG 图片，同时保存到 `screenshots/region-<时间戳>.png`

## 测试

在 MCP 客户端中直接对话调用即可验证，例如：

- 「调用 take_screenshot 截个屏」
- 「调用 capture_region，x=0 y=0 width=400 height=300」

判断成功标志：

1. 返回一张可渲染的 PNG 图片（而非报错文本）。
2. 项目根目录下的 `screenshots/` 目录中生成对应的 PNG 文件。
3. 返回内容中带有 `截图已保存到: ...` 的路径提示。

## 项目结构

```
.
├── src/
│   └── index.ts        # MCP 服务入口与截图实现
├── dist/               # 编译产物（npm run build 生成）
├── screenshots/        # 截图输出目录（运行时生成）
├── package.json
├── package-lock.json
└── tsconfig.json
```

## 工作原理

1. MCP 客户端（如 Trae）通过 stdio 启动 `node dist/index.js`。
2. 服务端注册 `take_screenshot` 和 `capture_region` 两个工具。
3. 调用工具时，服务端通过 PowerShell 执行 `System.Drawing` 的 `CopyFromScreen` 完成屏幕捕获，输出 PNG 文件。
4. `take_screenshot` 直接返回图片；`capture_region` 先捕获全屏，再用 `sharp` 裁剪指定区域。
5. 截图保存到 `screenshots/` 目录，并将图片数据（base64）与保存路径返回给客户端。

## 常见问题

### 修改代码后工具没有生效

MCP 客户端会缓存已启动的进程，需要重新编译并在客户端中重启/刷新 MCP 服务器。

### 截图目录没有生成文件

确认客户端使用的 `cwd` 指向项目根目录，且服务进程有写权限。