mcp-screenshot

📸 MCP ACS 截图服务

赋予 AI Agent 视觉超能力，让它们像资深 UX 设计师一样查看、分析和记录你的应用。

这款企业级 MCP 服务可将 AI 从只能处理代码的助手转变为视觉专家，使其能够进行 UI 分析、无障碍审计、文档生成和响应式设计测试。

🔗 仓库

此软件包现已在独立仓库中维护：https://github.com/Digital-Defiance/mcp-screenshot

此仓库是 GitHub 上 AI Capabilitites Suite 的一部分。

🤔 AI Agent 为什么需要视觉能力？

如今的 AI Agent 虽然功能强大，却无法识别视觉内容：

• ❌ 能读取 HTML/CSS，却看不到实际布局
• ❌ 看不到真实的用户体验，却能提出 UI 改进建议
• ❌ 无法检测对比度不足、间距不当等无障碍问题
• ❌ 无法创建视觉文档或错误报告
• ❌ 无法分析不同屏幕尺寸下的响应式设计

结果： 你只能手动创建截图、文档和视觉分析，而这些本应由 AI 完成。

---

🎯 革命性的使用场景

📚 “AI，创建专业文档”

You: "Document the checkout process with screenshots"
AI: *Captures each step, analyzes UI flow*
AI: "Generated complete user guide with 6 annotated screenshots, highlighting key interactions and error states..."

🔍 “AI，审查此页面的无障碍情况”

You: "Check if this form meets WCAG guidelines"
AI: *Captures form, analyzes visual elements*
AI: "Found 4 accessibility issues: contrast ratio 2.1:1 (needs 4.5:1), missing focus indicators, touch targets too small..."

🐛 “AI，创建详细的错误报告”

You: "The mobile navigation is broken"
AI: *Captures different viewport sizes*
AI: "Created bug report with before/after screenshots, exact breakpoint where it fails, and CSS fix suggestions..."

🎨 “AI，比较这些设计变体”

You: "Which hero section design works better?"
AI: *Captures both versions, analyzes visual hierarchy*
AI: "Version B has 28% better visual flow—CTA more prominent, text hierarchy clearer, better use of whitespace..."

📱 “AI，测试响应式设计”

You: "How does this look on different screen sizes?"
AI: *Captures multiple viewport sizes*
AI: "Layout breaks at 768px—sidebar overlaps content. Here's the media query fix with visual proof..."

---

✨ 这带来了哪些改变

之前： AI 无法直观看到界面，只能依赖代码描述

• ❌ “按钮看起来不对” → AI 只能猜测问题
• ❌ “创建文档” → AI 只能编写泛泛的内容
• ❌ “检查无障碍情况” → AI 只能审查代码
• ❌ “测试响应式设计” → AI 看不到实际断点

之后： AI 能够查看并分析你的实际用户界面

• ✅ 视觉调试 - AI 能识别精确到像素的问题
• ✅ 智能文档 - AI 能创建包含真实截图和注释的指南
• ✅ 无障碍审计 - AI 能测量实际对比度和间距
• ✅ 响应式测试 - AI 能捕获并比较不同屏幕尺寸的画面
• ✅ 设计分析 - AI 能评估视觉层级和用户体验
• ✅ 专业报告 - AI 能为错误和改进创建详细的视觉证据

---

🚀 功能

• 多格式支持：PNG、JPEG、WebP、BMP，可配置质量
• 灵活捕获：整个屏幕、指定窗口或自定义区域
• 隐私保护：通过基于 OCR 的检测对个人身份信息 (PII) 进行遮蔽，包括电子邮件地址、电话号码和信用卡号
• 安全控制：路径验证、速率限制、审计日志和可配置策略
• 跨平台：Linux (X11/Wayland)、macOS、Windows，使用原生 API
• 多显示器支持：在多显示器设置中从指定显示器捕获画面
• 企业级安全：窗口排除、审计日志、速率限制
• 针对 AI 优化：结构化响应，非常适合 AI Agent 工作流

安装

NPM 安装

npm install @ai-capabilities-suite/mcp-screenshot

系统要求

Linux：

• X11：imagemagick 软件包（提供 import 命令）
• Wayland：grim 软件包

# Ubuntu/Debian
sudo apt-get install imagemagick grim

# Fedora
sudo dnf install ImageMagick grim

# Arch
sudo pacman -S imagemagick grim

macOS：

• 内置 screencapture 命令（无需额外依赖）
• 需要屏幕录制权限（系统偏好设置 > 安全性与隐私 > 隐私 > 屏幕录制）

Windows：

• 无需额外依赖

MCP 配置

添加到 MCP 设置文件中（例如 ~/.kiro/settings/mcp.json 或 .kiro/settings/mcp.json）：

{
  "mcpServers": {
    "screenshot": {
      "command": "node",
      "args": ["/path/to/mcp-screenshot/dist/cli.js"],
      "env": {
        "SCREENSHOT_ALLOWED_DIRS": "/home/user/screenshots,/tmp",
        "SCREENSHOT_MAX_CAPTURES_PER_MIN": "60",
        "SCREENSHOT_ENABLE_AUDIT_LOG": "true"
      }
    }
  }
}

🛠️ 5 个专业 MCP 工具

专为 AI Agent 打造，用于捕获、分析和处理视觉信息：

该服务提供 5 个全面的 MCP 工具，让 AI Agent 能够查看和理解你的应用程序：

1. screenshot_capture_full

捕获整个屏幕或指定显示器。

参数：

• display（string，可选）：要捕获的显示器 ID（默认为主显示器）
• format（string，可选）：图像格式——png、jpeg、webp 或 bmp（默认为 png）
• quality（number，可选）：有损格式的压缩质量，范围为 1–100（默认为 90）
• savePath（string，可选）：保存截图的文件路径（如果未提供，则返回 base64）
• enablePIIMasking（boolean，可选）：启用 PII 检测和遮蔽（默认为 false）

示例：

{
  "name": "screenshot_capture_full",
  "arguments": {
    "format": "png",
    "savePath": "/home/user/screenshots/desktop.png",
    "enablePIIMasking": true
  }
}

响应：

{
  "status": "success",
  "filePath": "/home/user/screenshots/desktop.png",
  "metadata": {
    "width": 1920,
    "height": 1080,
    "format": "png",
    "fileSize": 245678,
    "timestamp": "2024-12-01T10:30:00.000Z",
    "display": {
      "id": "0",
      "name": "Primary Display",
      "resolution": { "width": 1920, "height": 1080 },
      "position": { "x": 0, "y": 0 },
      "isPrimary": true
    },
    "piiMasking": {
      "emailsRedacted": 2,
      "phonesRedacted": 1,
      "creditCardsRedacted": 0,
      "customPatternsRedacted": 0
    }
  }
}

2. screenshot_capture_window

根据 ID 或标题模式捕获指定应用程序窗口。

参数：

• windowId（string，可选）：窗口标识符（使用 windowId 或 windowTitle）
• windowTitle（string，可选）：要匹配的窗口标题模式（使用 windowId 或 windowTitle）
• includeFrame（boolean，可选）：包含窗口边框和标题栏（默认为 false）
• format（string，可选）：图像格式（默认为 png）
• quality（number，可选）：压缩质量，范围为 1–100（默认为 90）
• savePath（string，可选）：保存截图的文件路径

示例：

{
  "name": "screenshot_capture_window",
  "arguments": {
    "windowTitle": "Chrome",
    "includeFrame": false,
    "format": "jpeg",
    "quality": 85
  }
}

响应：

{
  "status": "success",
  "data": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mimeType": "image/jpeg",
  "metadata": {
    "width": 1280,
    "height": 720,
    "format": "jpeg",
    "fileSize": 89234,
    "timestamp": "2024-12-01T10:31:00.000Z",
    "window": {
      "id": "12345",
      "title": "Google Chrome",
      "processName": "chrome",
      "pid": 5678,
      "bounds": { "x": 100, "y": 100, "width": 1280, "height": 720 }
    }
  }
}

3. screenshot_capture_region

捕获屏幕上的指定矩形区域。

参数：

• x（number，必填）：左上角的 X 坐标
• y（number，必填）：左上角的 Y 坐标
• width（number，必填）：区域宽度，单位为像素
• height（number，必填）：区域高度，单位为像素
• format（string，可选）：图像格式（默认为 png）
• quality（number，可选）：压缩质量，范围为 1–100（默认为 90）
• savePath（string，可选）：保存截图的文件路径

示例：

{
  "name": "screenshot_capture_region",
  "arguments": {
    "x": 100,
    "y": 100,
    "width": 800,
    "height": 600,
    "format": "png"
  }
}

响应：

{
  "status": "success",
  "data": "iVBORw0KGgoAAAANSUhEUgAA...",
  "mimeType": "image/png",
  "metadata": {
    "width": 800,
    "height": 600,
    "format": "png",
    "fileSize": 123456,
    "timestamp": "2024-12-01T10:32:00.000Z",
    "region": {
      "x": 100,
      "y": 100,
      "width": 800,
      "height": 600
    }
  }
}

4. screenshot_list_displays

列出所有已连接显示器及其分辨率和位置信息。

**参数：**无

示例：

{
  "name": "screenshot_list_displays",
  "arguments": {}
}

响应：

{
  "status": "success",
  "displays": [
    {
      "id": "0",
      "name": "Primary Display",
      "resolution": { "width": 1920, "height": 1080 },
      "position": { "x": 0, "y": 0 },
      "isPrimary": true
    },
    {
      "id": "1",
      "name": "Secondary Display",
      "resolution": { "width": 1920, "height": 1080 },
      "position": { "x": 1920, "y": 0 },
      "isPrimary": false
    }
  ]
}

5. screenshot_list_windows

列出所有可见窗口及其标题、进程和位置信息。

**参数：**无

示例：

{
  "name": "screenshot_list_windows",
  "arguments": {}
}

响应：

{
  "status": "success",
  "windows": [
    {
      "id": "12345",
      "title": "Google Chrome",
      "processName": "chrome",
      "pid": 5678,
      "bounds": { "x": 100, "y": 100, "width": 1280, "height": 720 },
      "isMinimized": false
    },
    {
      "id": "67890",
      "title": "Terminal",
      "processName": "gnome-terminal",
      "pid": 9012,
      "bounds": { "x": 200, "y": 200, "width": 800, "height": 600 },
      "isMinimized": false
    }
  ]
}

安全配置

该服务会执行安全策略，以控制截图操作。可通过环境变量或安全策略文件进行配置。

环境变量

• SCREENSHOT_ALLOWED_DIRS：允许保存截图的目录列表，以逗号分隔
• SCREENSHOT_MAX_CAPTURES_PER_MIN：每分钟最多捕获次数（默认为 60）
• SCREENSHOT_ENABLE_AUDIT_LOG：启用审计日志（默认为 true）
• SCREENSHOT_BLOCKED_WINDOWS：要排除的窗口标题模式列表，以逗号分隔

安全策略文件

创建 security-policy.json 文件：

{
  "allowedDirectories": ["/home/user/screenshots", "/tmp/screenshots"],
  "blockedWindowPatterns": [
    ".*Password.*",
    ".*1Password.*",
    ".*LastPass.*",
    ".*Bitwarden.*",
    ".*Authentication.*"
  ],
  "maxCapturesPerMinute": 60,
  "enableAuditLog": true
}

启动服务时加载策略：

import { MCPScreenshotServer } from "@ai-capabilities-suite/mcp-screenshot";
import * as fs from "fs";

const policy = JSON.parse(fs.readFileSync("security-policy.json", "utf-8"));
const server = new MCPScreenshotServer(policy);
await server.start();

错误处理

所有工具都会返回结构化错误响应，其中包含错误代码和修复建议。

错误代码

Code	描述	解决方法
PERMISSION_DENIED	截屏权限不足	授予屏幕录制权限（macOS），或检查用户权限
INVALID_PATH	文件路径不在允许的目录内	使用配置的允许目录中的路径
WINDOW_NOT_FOUND	指定的窗口不存在	使用 screenshot_list_windows 查找可用窗口
DISPLAY_NOT_FOUND	指定的显示器不存在	使用 screenshot_list_displays 查找可用显示器
UNSUPPORTED_FORMAT	不支持请求的格式	使用 png、jpeg、webp 或 bmp
CAPTURE_FAILED	屏幕截图失败	检查权限并重试
RATE_LIMIT_EXCEEDED	时间窗口内截屏次数过多	等待一段时间后再发送请求
INVALID_REGION	区域坐标或尺寸无效	确保坐标非负且尺寸为正值
OUT_OF_MEMORY	操作所需内存不足	缩小截屏尺寸或关闭其他应用
ENCODING_FAILED	图像编码失败	尝试使用其他格式或降低质量
FILE_SYSTEM_ERROR	文件系统操作失败	检查权限和磁盘空间

错误响应格式

{
  "status": "error",
  "error": {
    "code": "WINDOW_NOT_FOUND",
    "message": "Window with ID '12345' not found",
    "details": {
      "windowId": "12345"
    },
    "remediation": "Verify the window exists and is visible. Use screenshot_list_windows to see available windows."
  }
}

故障排除

Linux 问题

问题： import: command not found 或 grim: command not found

解决方法： 安装所需软件包：

# X11
sudo apt-get install imagemagick

# Wayland
sudo apt-get install grim

问题： 黑屏或截屏内容为空

解决方法： 检查显示服务器环境变量：

echo $DISPLAY  # Should show :0 or similar for X11
echo $WAYLAND_DISPLAY  # Should show wayland-0 or similar for Wayland

macOS 问题

问题： PERMISSION_DENIED 错误

解决方法： 授予屏幕录制权限：

1. 打开“系统偏好设置”>“安全性与隐私”>“隐私”
2. 在列表中选择“屏幕录制”
3. 将终端应用或 Node.js 添加到允许列表
4. 重启应用

问题： Retina 显示屏截屏分辨率翻倍

解决方法： 这是预期行为。Retina 显示屏的像素密度为 2 倍。使用元数据中的 width 和 height 确定实际尺寸。

Windows 问题

问题： 截屏失败并提示拒绝访问

解决方法： 以管理员权限运行应用，或检查 Windows Defender 设置。

问题： 多显示器截屏显示了错误的显示器

解决方法： 使用 screenshot_list_displays 获取正确的显示器 ID 和位置。

常见问题

问题： RATE_LIMIT_EXCEEDED 错误

解决方法： 服务会限制截屏次数，以防止滥用。等待 60 秒，或调整安全策略中的 maxCapturesPerMinute。

问题： 保存时出现 INVALID_PATH 错误

解决方法： 确保保存路径位于安全策略中配置的允许目录内。

问题： PII 遮罩未生效

解决方法：

• 确保已正确安装 tesseract.js
• 检查 eng.traineddata 语言文件是否可用
• PII 遮罩需要使用 OCR，处理大图像时可能较慢

问题： 文件过大

解决方法：

• 使用较低质量（60-80）的 JPEG 格式，以减小文件
• 使用压缩效果最佳的 WebP 格式
• 尽可能缩小截屏区域

问题： 内存不足错误

解决方法：

• 截取较小区域，而非整个屏幕
• 降低质量设置
• 关闭其他应用以释放内存
• 对于非常大的截屏，使用流式传输

程序化使用

TypeScript/JavaScript

import { MCPScreenshotServer } from "@ai-capabilities-suite/mcp-screenshot";

// Create server with custom security policy
const server = new MCPScreenshotServer({
  allowedDirectories: ["/home/user/screenshots"],
  maxCapturesPerMinute: 30,
  enableAuditLog: true,
  blockedWindowPatterns: [".*Password.*"],
});

// Start server
await server.start();

// Server will handle MCP protocol requests via stdio
// Keep process running
process.on("SIGINT", async () => {
  await server.stop();
  process.exit(0);
});

直接捕获引擎用法

import { createCaptureEngine } from "@ai-capabilities-suite/mcp-screenshot";

// Create platform-specific capture engine
const engine = createCaptureEngine();

// Capture full screen
const fullScreen = await engine.captureScreen();

// List and capture windows
const windows = await engine.getWindows();
const window = windows.find((w) => w.title.includes("Chrome"));
if (window) {
  const buffer = await engine.captureWindow(window.id, false);
}

// Capture region
const region = await engine.captureRegion(100, 100, 800, 600);

// List displays
const displays = await engine.getDisplays();
console.log(`Found ${displays.length} displays`);

开发

此软件包是 AI Capabilities Suite 单体仓库的一部分。

构建

npm run build

测试

# Run all tests
npm test

# Run specific test suites
npm test -- capture
npm test -- security
npm test -- property

# Run with coverage
npm test -- --coverage

项目结构

packages/mcp-screenshot/
├── src/
│   ├── capture/          # Platform-specific capture engines
│   ├── processing/       # Image processing and encoding
│   ├── privacy/          # PII detection and masking
│   ├── security/         # Security policy enforcement
│   ├── storage/          # File operations
│   ├── tools/            # MCP tool implementations
│   ├── interfaces/       # TypeScript interfaces
│   ├── types/            # Type definitions
│   ├── errors/           # Error classes
│   ├── server.ts         # MCP server implementation
│   └── cli.ts            # CLI entry point
├── README.md
├── TESTING.md
└── package.json

贡献

欢迎贡献！请确保：

• 所有测试均通过（npm test）
• 代码遵循 TypeScript 最佳实践
• 新功能包含测试和文档
• 已考虑安全事项

许可证

MIT

支持

如有问题或疑问：

• GitHub Issues：创建问题
• 文档：请参阅 TESTING.md 中的测试指南
• 安全：请将安全问题私下报告至 [email protected]