mcp-screenshot

📸 MCP ACS スクリーンショットサーバー

AI エージェントに視覚的な力を与え、熟練した UX デザイナーのようにアプリケーションを確認、分析、記録できるようにします。

このエンタープライズグレードの MCP サーバーは、AI をコードだけを扱うアシスタントから、UI 分析、アクセシビリティ監査、ドキュメント生成、レスポンシブデザインテストができる視覚の専門家へと変えます。

🔗 リポジトリ

このパッケージは現在、独自のリポジトリで管理されています：https://github.com/Digital-Defiance/mcp-screenshot

このリポジトリは、GitHub の AI Capabilitites Suite の一部です。

🤔 AI エージェントに視覚機能が必要な理由

現在の AI エージェントは強力ですが、視覚的には盲目です：

• ❌ 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 ベースの検出により、メールアドレス、電話番号、クレジットカード番号などの個人情報をマスキング
• セキュリティ制御：パス検証、レート制限、監査ログ、設定可能なポリシー
• クロスプラットフォーム：Linux（X11/Wayland）、macOS、Windows のネイティブ API に対応
• マルチモニター対応：複数モニター環境で特定のディスプレイをキャプチャ
• エンタープライズセキュリティ：ウィンドウの除外、監査ログ、レート制限
• AI に最適化：AI エージェントのワークフローに最適な構造化レスポンス

インストール

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 エージェントが視覚情報をキャプチャ、分析し、活用できるように特化して設計されています。

このサーバーは、AI エージェントがアプリケーションを見て理解するための、包括的な 5 つの MCP ツールを提供します。

1. screenshot_capture_full

画面全体または特定のディスプレイをキャプチャします。

パラメーター：

• display（文字列、任意）：キャプチャするディスプレイ ID（デフォルトはプライマリディスプレイ）
• format（文字列、任意）：画像形式 - png、jpeg、webp、または bmp（デフォルト：png）
• quality（数値、任意）：非可逆形式の圧縮品質。1～100（デフォルト：90）
• savePath（文字列、任意）：スクリーンショットの保存先ファイルパス（指定しない場合は 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. screenshot_capture_window

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

画面上の特定の矩形領域をキャプチャします。

パラメーター：

• 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. 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：1 分あたりの最大キャプチャ数（デフォルト：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 ディスプレイでキャプチャすると解像度が 2 倍になる

解決方法： これは想定どおりの動作です。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：Issue を作成
• ドキュメント：テストガイドについては TESTING.md を参照してください
• セキュリティ：セキュリティ上の問題は [email protected] まで非公開で報告してください