AI导哈

AI视觉截图服务

为企业级AI代理提供视觉能力，包括UI分析、无障碍审计、文档生成和响应式设计测试的截图服务。

  • by Digital-Defiance
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 Digital-Defiance/mcp-screenshot

使用说明

📸 MCP ACS屏幕截图服务器

赋予人工智能代理视觉超能力，使其能够像高级用户体验设计师一样查看、分析和记录您的应用程序。

这个企业级MCP服务器将人工智能从仅限代码的助手转变为能够进行UI分析、可访问性审计、文档生成和响应式设计测试的视觉专家。

🔗 仓库

此包现在保存在自己的存储库中： https://github.com/Digital-Defiance/mcp-screenshot

此存储库是 AI 能力套件 在GitHub上。

🤔 为什么AI代理需要视觉功能？

今天的人工智能代理功能强大，但视觉上是盲目的：

  • ❌ 可以阅读HTML/CSS，但看不到实际的布局
  • ❌ 可以在没有看到真实用户体验的情况下提出UI改进建议
  • ❌ 无法检测到对比度或间距差等可访问性问题
  • ❌ 无法创建可视化文档或错误报告
  • ❌ 无法分析不同屏幕尺寸的响应式设计

结果： 你陷入了手动创建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，创建详细的bug报告”

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..."

📱 “人工智能，测试响应式设计”

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评估视觉层次和用户体验
  • ✅ 专业报告 -人工智能为错误和改进创建了详细的视觉证据

🚀 特性

  • 多格式支持：PNG、JPEG、WebP、BMP，质量可配置
  • 灵活捕捉：全屏、特定窗口或自定义区域
  • 隐私保护：通过基于OCR的电子邮件、电话号码和信用卡检测进行PII屏蔽
  • 安全控制：路径验证、速率限制、审核日志记录和可配置策略
  • 跨平台：Linux（X11/Wayland）、macOS、带有原生API的Windows
  • 多显示器支持：在多显示器设置中从特定显示器捕获
  • 企业安全：窗口排除、审计日志记录、速率限制
  • AI优化：结构化响应非常适合AI代理工作流程

安装

NPM安装

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

系统要求

Linux：

  • X11： imagemagick 套餐（提供 import 命令）
  • 韦兰： grim 包裹
# Ubuntu/Debian
sudo apt-get install imagemagick grim

# Fedora
sudo dnf install ImageMagick grim

# Arch
sudo pacman -S imagemagick grim

macOS：

  • 内建 screencapture 命令（无其他依赖项）
  • 需要屏幕录制权限（系统首选项>安全与隐私>隐私>屏幕录制）

窗户：

  • 不需要额外的依赖关系

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代理捕获、分析和处理视觉信息而构建：

该服务器提供了5个全面的MCP工具，使AI代理能够查看和理解您的应用程序：

1.截图_完整

捕获全屏或特定显示。

参数：

  • display （字符串，可选）：要捕获的显示ID（默认为主显示）
  • format （字符串，可选）：图像格式- png, jpeg, webp，或 bmp （默认值： png)
  • quality （数字，可选）：有损格式的压缩质量为1-100（默认值：90）
  • savePath （string，可选）：保存屏幕截图的文件路径（如果未提供，则返回base64）
  • enablePIIMasking （布尔值，可选）：启用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.截图_窗口

按ID或标题模式捕获特定的应用程序窗口。

参数：

  • windowId （字符串，可选）：窗口标识符（使用 windowId 或 windowTitle)
  • windowTitle （字符串，可选）：要匹配的窗口标题模式（使用 windowId 或 windowTitle)
  • includeFrame （布尔值，可选）：包括窗口框架和标题栏（默认值：false）
  • format （字符串，可选）：图像格式（默认值： png)
  • quality （数字，可选）：压缩质量1-100（默认值：90）
  • savePath （字符串，可选）：保存截图的文件路径

例子：

{
  "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.截图_区域

捕捉屏幕的特定矩形区域。

参数：

  • x （数字，必填）：左上角的X坐标
  • y （数字，必填）：左上角Y坐标
  • width （数字，必填）：区域宽度（像素）
  • height （数字，必填）：区域高度（像素）
  • format （字符串，可选）：图像格式（默认值： png)
  • quality （数字，可选）：压缩质量1-100（默认值：90）
  • savePath （字符串，可选）：保存截图的文件路径

例子：

{
  "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.屏幕截图_列表_显示

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

参数： 无

例子：

{
  "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.屏幕截图_列表_窗口

列出所有可见的窗口，包括标题、进程和位置信息。

参数： 无

例子：

{
  "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();

错误处理

所有工具都会返回带有错误代码和补救建议的结构化错误响应。

错误代码

代码 描述 补救
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，这在大图像上可能很慢

问题： 大文件大小

解决方案：

  • 对于较小的文件，使用质量较低的JPEG格式（60-80）
  • 使用WebP格式进行最佳压缩
  • 如果可能，减小捕获区域大小

问题： 内存不足错误

解决方案：

  • 捕获较小的区域而不是全屏
  • 减少质量设置
  • 关闭其他应用程序以释放内存
  • 使用流媒体进行非常大的捕获

程序化使用

Types/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能力套件monorepo的一部分。

构建

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的最佳实践
  • 新功能包括测试和文档
  • 安全考虑已得到解决

许可证

麻省理工学院

支持

对于问题和疑问：

相关 MCP