{
  "markdown": "# 📸 MCP ACS Screenshot Server\n\n[![NPM Version](https://img.shields.io/npm/v/@ai-capabilities-suite/mcp-screenshot)](https://www.npmjs.com/package/@ai-capabilities-suite/mcp-screenshot)\n[![GitHub Release](https://img.shields.io/github/v/release/digital-defiance/mcp-screenshot?label=Release&logo=github)](https://github.com/digital-defiance/mcp-screenshot/releases)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)\n[![Docker Pulls](https://img.shields.io/docker/pulls/digitaldefiance/mcp-screenshot)](https://hub.docker.com/r/digitaldefiance/mcp-screenshot)\n\n**Give AI agents visual superpowers to see, analyze, and document your applications like senior UX designers.**\n\nThis enterprise-grade MCP server transforms AI from code-only assistants into visual experts capable of UI analysis, accessibility auditing, documentation generation, and responsive design testing.\n\n## 🔗 Repository\n\nThis package is now maintained in its own repository: **[https://github.com/Digital-Defiance/mcp-screenshot](https://github.com/Digital-Defiance/mcp-screenshot)**\n\nThis repository is part of the [AI Capabilitites Suite](https://github.com/Digital-Defiance/ai-capabilitites-suite) on GitHub.\n\n## 🤔 Why Do AI Agents Need Visual Capabilities?\n\n**AI agents today are powerful but visually blind:**\n\n- ❌ Can read HTML/CSS but can't see actual layouts\n- ❌ Can suggest UI improvements without seeing the real user experience\n- ❌ Can't detect accessibility issues like poor contrast or spacing\n- ❌ Can't create visual documentation or bug reports\n- ❌ Can't analyze responsive design across different screen sizes\n\n**Result:** You're stuck manually creating screenshots, documentation, and visual analysis that AI should handle.\n\n---\n\n## 🎯 Revolutionary Use Cases\n\n### 📚 **\"AI, create professional documentation\"**\n\n```\nYou: \"Document the checkout process with screenshots\"\nAI: *Captures each step, analyzes UI flow*\nAI: \"Generated complete user guide with 6 annotated screenshots, highlighting key interactions and error states...\"\n```\n\n### 🔍 **\"AI, audit this page for accessibility\"**\n\n```\nYou: \"Check if this form meets WCAG guidelines\"\nAI: *Captures form, analyzes visual elements*\nAI: \"Found 4 accessibility issues: contrast ratio 2.1:1 (needs 4.5:1), missing focus indicators, touch targets too small...\"\n```\n\n### 🐛 **\"AI, create a detailed bug report\"**\n\n```\nYou: \"The mobile navigation is broken\"\nAI: *Captures different viewport sizes*\nAI: \"Created bug report with before/after screenshots, exact breakpoint where it fails, and CSS fix suggestions...\"\n```\n\n### 🎨 **\"AI, compare these design variations\"**\n\n```\nYou: \"Which hero section design works better?\"\nAI: *Captures both versions, analyzes visual hierarchy*\nAI: \"Version B has 28% better visual flow—CTA more prominent, text hierarchy clearer, better use of whitespace...\"\n```\n\n### 📱 **\"AI, test responsive design\"**\n\n```\nYou: \"How does this look on different screen sizes?\"\nAI: *Captures multiple viewport sizes*\nAI: \"Layout breaks at 768px—sidebar overlaps content. Here's the media query fix with visual proof...\"\n```\n\n---\n\n## ✨ What This Changes\n\n**Before:** AI worked blind, relying on code descriptions\n\n- ❌ \"The button looks wrong\" → AI guesses the issue\n- ❌ \"Create documentation\" → AI writes generic text\n- ❌ \"Check accessibility\" → AI only reviews code\n- ❌ \"Test responsive design\" → AI can't see actual breakpoints\n\n**After:** AI sees and analyzes your actual user interface\n\n- ✅ **Visual debugging** - AI identifies exact pixel-level issues\n- ✅ **Smart documentation** - AI creates guides with real screenshots and annotations\n- ✅ **Accessibility audits** - AI measures actual contrast ratios and spacing\n- ✅ **Responsive testing** - AI captures and compares different screen sizes\n- ✅ **Design analysis** - AI evaluates visual hierarchy and user experience\n- ✅ **Professional reports** - AI creates detailed visual evidence for bugs and improvements\n\n---\n\n## 🚀 Features\n\n- **Multi-format Support**: PNG, JPEG, WebP, BMP with configurable quality\n- **Flexible Capture**: Full screen, specific windows, or custom regions\n- **Privacy Protection**: PII masking with OCR-based detection for emails, phone numbers, and credit cards\n- **Security Controls**: Path validation, rate limiting, audit logging, and configurable policies\n- **Cross-platform**: Linux (X11/Wayland), macOS, Windows with native APIs\n- **Multi-monitor Support**: Capture from specific displays in multi-monitor setups\n- **Enterprise Security**: Window exclusion, audit logging, rate limiting\n- **AI-Optimized**: Structured responses perfect for AI agent workflows\n\n## Installation\n\n### NPM Installation\n\n```bash\nnpm install @ai-capabilities-suite/mcp-screenshot\n```\n\n### System Requirements\n\n**Linux:**\n\n- X11: `imagemagick` package (provides `import` command)\n- Wayland: `grim` package\n\n```bash\n# Ubuntu/Debian\nsudo apt-get install imagemagick grim\n\n# Fedora\nsudo dnf install ImageMagick grim\n\n# Arch\nsudo pacman -S imagemagick grim\n```\n\n**macOS:**\n\n- Built-in `screencapture` command (no additional dependencies)\n- Screen Recording permission required (System Preferences > Security & Privacy > Privacy > Screen Recording)\n\n**Windows:**\n\n- No additional dependencies required\n\n### MCP Configuration\n\nAdd to your MCP settings file (e.g., `~/.kiro/settings/mcp.json` or `.kiro/settings/mcp.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"screenshot\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/mcp-screenshot/dist/cli.js\"],\n      \"env\": {\n        \"SCREENSHOT_ALLOWED_DIRS\": \"/home/user/screenshots,/tmp\",\n        \"SCREENSHOT_MAX_CAPTURES_PER_MIN\": \"60\",\n        \"SCREENSHOT_ENABLE_AUDIT_LOG\": \"true\"\n      }\n    }\n  }\n}\n```\n\n## 🛠️ 5 Professional MCP Tools\n\n**Purpose-built for AI agents to capture, analyze, and work with visual information:**\n\nThe server exposes 5 comprehensive MCP tools that enable AI agents to see and understand your applications:\n\n### 1. screenshot_capture_full\n\nCapture full screen or specific display.\n\n**Parameters:**\n\n- `display` (string, optional): Display ID to capture (defaults to primary display)\n- `format` (string, optional): Image format - `png`, `jpeg`, `webp`, or `bmp` (default: `png`)\n- `quality` (number, optional): Compression quality 1-100 for lossy formats (default: 90)\n- `savePath` (string, optional): File path to save screenshot (returns base64 if not provided)\n- `enablePIIMasking` (boolean, optional): Enable PII detection and masking (default: false)\n\n**Example:**\n\n```json\n{\n  \"name\": \"screenshot_capture_full\",\n  \"arguments\": {\n    \"format\": \"png\",\n    \"savePath\": \"/home/user/screenshots/desktop.png\",\n    \"enablePIIMasking\": true\n  }\n}\n```\n\n**Response:**\n\n```json\n{\n  \"status\": \"success\",\n  \"filePath\": \"/home/user/screenshots/desktop.png\",\n  \"metadata\": {\n    \"width\": 1920,\n    \"height\": 1080,\n    \"format\": \"png\",\n    \"fileSize\": 245678,\n    \"timestamp\": \"2024-12-01T10:30:00.000Z\",\n    \"display\": {\n      \"id\": \"0\",\n      \"name\": \"Primary Display\",\n      \"resolution\": { \"width\": 1920, \"height\": 1080 },\n      \"position\": { \"x\": 0, \"y\": 0 },\n      \"isPrimary\": true\n    },\n    \"piiMasking\": {\n      \"emailsRedacted\": 2,\n      \"phonesRedacted\": 1,\n      \"creditCardsRedacted\": 0,\n      \"customPatternsRedacted\": 0\n    }\n  }\n}\n```\n\n### 2. screenshot_capture_window\n\nCapture specific application window by ID or title pattern.\n\n**Parameters:**\n\n- `windowId` (string, optional): Window identifier (use `windowId` or `windowTitle`)\n- `windowTitle` (string, optional): Window title pattern to match (use `windowId` or `windowTitle`)\n- `includeFrame` (boolean, optional): Include window frame and title bar (default: false)\n- `format` (string, optional): Image format (default: `png`)\n- `quality` (number, optional): Compression quality 1-100 (default: 90)\n- `savePath` (string, optional): File path to save screenshot\n\n**Example:**\n\n```json\n{\n  \"name\": \"screenshot_capture_window\",\n  \"arguments\": {\n    \"windowTitle\": \"Chrome\",\n    \"includeFrame\": false,\n    \"format\": \"jpeg\",\n    \"quality\": 85\n  }\n}\n```\n\n**Response:**\n\n```json\n{\n  \"status\": \"success\",\n  \"data\": \"iVBORw0KGgoAAAANSUhEUgAA...\",\n  \"mimeType\": \"image/jpeg\",\n  \"metadata\": {\n    \"width\": 1280,\n    \"height\": 720,\n    \"format\": \"jpeg\",\n    \"fileSize\": 89234,\n    \"timestamp\": \"2024-12-01T10:31:00.000Z\",\n    \"window\": {\n      \"id\": \"12345\",\n      \"title\": \"Google Chrome\",\n      \"processName\": \"chrome\",\n      \"pid\": 5678,\n      \"bounds\": { \"x\": 100, \"y\": 100, \"width\": 1280, \"height\": 720 }\n    }\n  }\n}\n```\n\n### 3. screenshot_capture_region\n\nCapture specific rectangular region of the screen.\n\n**Parameters:**\n\n- `x` (number, required): X coordinate of top-left corner\n- `y` (number, required): Y coordinate of top-left corner\n- `width` (number, required): Width of region in pixels\n- `height` (number, required): Height of region in pixels\n- `format` (string, optional): Image format (default: `png`)\n- `quality` (number, optional): Compression quality 1-100 (default: 90)\n- `savePath` (string, optional): File path to save screenshot\n\n**Example:**\n\n```json\n{\n  \"name\": \"screenshot_capture_region\",\n  \"arguments\": {\n    \"x\": 100,\n    \"y\": 100,\n    \"width\": 800,\n    \"height\": 600,\n    \"format\": \"png\"\n  }\n}\n```\n\n**Response:**\n\n```json\n{\n  \"status\": \"success\",\n  \"data\": \"iVBORw0KGgoAAAANSUhEUgAA...\",\n  \"mimeType\": \"image/png\",\n  \"metadata\": {\n    \"width\": 800,\n    \"height\": 600,\n    \"format\": \"png\",\n    \"fileSize\": 123456,\n    \"timestamp\": \"2024-12-01T10:32:00.000Z\",\n    \"region\": {\n      \"x\": 100,\n      \"y\": 100,\n      \"width\": 800,\n      \"height\": 600\n    }\n  }\n}\n```\n\n### 4. screenshot_list_displays\n\nList all connected displays with resolution and position information.\n\n**Parameters:** None\n\n**Example:**\n\n```json\n{\n  \"name\": \"screenshot_list_displays\",\n  \"arguments\": {}\n}\n```\n\n**Response:**\n\n```json\n{\n  \"status\": \"success\",\n  \"displays\": [\n    {\n      \"id\": \"0\",\n      \"name\": \"Primary Display\",\n      \"resolution\": { \"width\": 1920, \"height\": 1080 },\n      \"position\": { \"x\": 0, \"y\": 0 },\n      \"isPrimary\": true\n    },\n    {\n      \"id\": \"1\",\n      \"name\": \"Secondary Display\",\n      \"resolution\": { \"width\": 1920, \"height\": 1080 },\n      \"position\": { \"x\": 1920, \"y\": 0 },\n      \"isPrimary\": false\n    }\n  ]\n}\n```\n\n### 5. screenshot_list_windows\n\nList all visible windows with title, process, and position information.\n\n**Parameters:** None\n\n**Example:**\n\n```json\n{\n  \"name\": \"screenshot_list_windows\",\n  \"arguments\": {}\n}\n```\n\n**Response:**\n\n```json\n{\n  \"status\": \"success\",\n  \"windows\": [\n    {\n      \"id\": \"12345\",\n      \"title\": \"Google Chrome\",\n      \"processName\": \"chrome\",\n      \"pid\": 5678,\n      \"bounds\": { \"x\": 100, \"y\": 100, \"width\": 1280, \"height\": 720 },\n      \"isMinimized\": false\n    },\n    {\n      \"id\": \"67890\",\n      \"title\": \"Terminal\",\n      \"processName\": \"gnome-terminal\",\n      \"pid\": 9012,\n      \"bounds\": { \"x\": 200, \"y\": 200, \"width\": 800, \"height\": 600 },\n      \"isMinimized\": false\n    }\n  ]\n}\n```\n\n## Security Configuration\n\nThe server enforces security policies to control screenshot operations. Configure via environment variables or security policy file.\n\n### Environment Variables\n\n- `SCREENSHOT_ALLOWED_DIRS`: Comma-separated list of allowed directories for saving screenshots\n- `SCREENSHOT_MAX_CAPTURES_PER_MIN`: Maximum captures per minute (default: 60)\n- `SCREENSHOT_ENABLE_AUDIT_LOG`: Enable audit logging (default: true)\n- `SCREENSHOT_BLOCKED_WINDOWS`: Comma-separated list of window title patterns to exclude\n\n### Security Policy File\n\nCreate a `security-policy.json` file:\n\n```json\n{\n  \"allowedDirectories\": [\"/home/user/screenshots\", \"/tmp/screenshots\"],\n  \"blockedWindowPatterns\": [\n    \".*Password.*\",\n    \".*1Password.*\",\n    \".*LastPass.*\",\n    \".*Bitwarden.*\",\n    \".*Authentication.*\"\n  ],\n  \"maxCapturesPerMinute\": 60,\n  \"enableAuditLog\": true\n}\n```\n\nLoad the policy when starting the server:\n\n```typescript\nimport { MCPScreenshotServer } from \"@ai-capabilities-suite/mcp-screenshot\";\nimport * as fs from \"fs\";\n\nconst policy = JSON.parse(fs.readFileSync(\"security-policy.json\", \"utf-8\"));\nconst server = new MCPScreenshotServer(policy);\nawait server.start();\n```\n\n## Error Handling\n\nAll tools return structured error responses with error codes and remediation suggestions.\n\n### Error Codes\n\n| Code                  | Description                              | Remediation                                                         |\n| --------------------- | ---------------------------------------- | ------------------------------------------------------------------- |\n| `PERMISSION_DENIED`   | Insufficient permissions to capture      | Grant Screen Recording permission (macOS) or check user permissions |\n| `INVALID_PATH`        | File path outside allowed directories    | Use a path within configured allowed directories                    |\n| `WINDOW_NOT_FOUND`    | Specified window does not exist          | Use `screenshot_list_windows` to find available windows             |\n| `DISPLAY_NOT_FOUND`   | Specified display does not exist         | Use `screenshot_list_displays` to find available displays           |\n| `UNSUPPORTED_FORMAT`  | Requested format not supported           | Use png, jpeg, webp, or bmp                                         |\n| `CAPTURE_FAILED`      | Screenshot capture failed                | Check permissions and try again                                     |\n| `RATE_LIMIT_EXCEEDED` | Too many captures in time window         | Wait before making additional requests                              |\n| `INVALID_REGION`      | Invalid region coordinates or dimensions | Ensure coordinates are non-negative and dimensions are positive     |\n| `OUT_OF_MEMORY`       | Insufficient memory for operation        | Reduce capture size or close other applications                     |\n| `ENCODING_FAILED`     | Image encoding failed                    | Try different format or reduce quality                              |\n| `FILE_SYSTEM_ERROR`   | File system operation failed             | Check permissions and disk space                                    |\n\n### Error Response Format\n\n```json\n{\n  \"status\": \"error\",\n  \"error\": {\n    \"code\": \"WINDOW_NOT_FOUND\",\n    \"message\": \"Window with ID '12345' not found\",\n    \"details\": {\n      \"windowId\": \"12345\"\n    },\n    \"remediation\": \"Verify the window exists and is visible. Use screenshot_list_windows to see available windows.\"\n  }\n}\n```\n\n## Troubleshooting\n\n### Linux Issues\n\n**Problem:** `import: command not found` or `grim: command not found`\n\n**Solution:** Install required packages:\n\n```bash\n# X11\nsudo apt-get install imagemagick\n\n# Wayland\nsudo apt-get install grim\n```\n\n**Problem:** Black screen or empty captures\n\n**Solution:** Check display server environment variables:\n\n```bash\necho $DISPLAY  # Should show :0 or similar for X11\necho $WAYLAND_DISPLAY  # Should show wayland-0 or similar for Wayland\n```\n\n### macOS Issues\n\n**Problem:** `PERMISSION_DENIED` error\n\n**Solution:** Grant Screen Recording permission:\n\n1. Open System Preferences > Security & Privacy > Privacy\n2. Select \"Screen Recording\" from the list\n3. Add your terminal application or Node.js to the allowed list\n4. Restart the application\n\n**Problem:** Retina display captures are double resolution\n\n**Solution:** This is expected behavior. Retina displays have 2x pixel density. Use the `width` and `height` from metadata to determine actual dimensions.\n\n### Windows Issues\n\n**Problem:** Capture fails with access denied\n\n**Solution:** Run the application with administrator privileges or check Windows Defender settings.\n\n**Problem:** Multi-monitor captures show wrong display\n\n**Solution:** Use `screenshot_list_displays` to get correct display IDs and positions.\n\n### General Issues\n\n**Problem:** `RATE_LIMIT_EXCEEDED` error\n\n**Solution:** The server limits captures to prevent abuse. Wait 60 seconds or adjust `maxCapturesPerMinute` in security policy.\n\n**Problem:** `INVALID_PATH` error when saving\n\n**Solution:** Ensure the save path is within allowed directories configured in security policy.\n\n**Problem:** PII masking not working\n\n**Solution:**\n\n- Ensure tesseract.js is properly installed\n- Check that `eng.traineddata` language file is available\n- PII masking requires OCR which may be slow on large images\n\n**Problem:** Large file sizes\n\n**Solution:**\n\n- Use JPEG format with lower quality (60-80) for smaller files\n- Use WebP format for best compression\n- Reduce capture region size if possible\n\n**Problem:** Out of memory errors\n\n**Solution:**\n\n- Capture smaller regions instead of full screen\n- Reduce quality settings\n- Close other applications to free memory\n- Use streaming for very large captures\n\n## Programmatic Usage\n\n### TypeScript/JavaScript\n\n```typescript\nimport { MCPScreenshotServer } from \"@ai-capabilities-suite/mcp-screenshot\";\n\n// Create server with custom security policy\nconst server = new MCPScreenshotServer({\n  allowedDirectories: [\"/home/user/screenshots\"],\n  maxCapturesPerMinute: 30,\n  enableAuditLog: true,\n  blockedWindowPatterns: [\".*Password.*\"],\n});\n\n// Start server\nawait server.start();\n\n// Server will handle MCP protocol requests via stdio\n// Keep process running\nprocess.on(\"SIGINT\", async () => {\n  await server.stop();\n  process.exit(0);\n});\n```\n\n### Direct Capture Engine Usage\n\n```typescript\nimport { createCaptureEngine } from \"@ai-capabilities-suite/mcp-screenshot\";\n\n// Create platform-specific capture engine\nconst engine = createCaptureEngine();\n\n// Capture full screen\nconst fullScreen = await engine.captureScreen();\n\n// List and capture windows\nconst windows = await engine.getWindows();\nconst window = windows.find((w) => w.title.includes(\"Chrome\"));\nif (window) {\n  const buffer = await engine.captureWindow(window.id, false);\n}\n\n// Capture region\nconst region = await engine.captureRegion(100, 100, 800, 600);\n\n// List displays\nconst displays = await engine.getDisplays();\nconsole.log(`Found ${displays.length} displays`);\n```\n\n## Development\n\nThis package is part of the AI Capabilities Suite monorepo.\n\n### Build\n\n```bash\nnpm run build\n```\n\n### Test\n\n```bash\n# Run all tests\nnpm test\n\n# Run specific test suites\nnpm test -- capture\nnpm test -- security\nnpm test -- property\n\n# Run with coverage\nnpm test -- --coverage\n```\n\n### Project Structure\n\n```\npackages/mcp-screenshot/\n├── src/\n│   ├── capture/          # Platform-specific capture engines\n│   ├── processing/       # Image processing and encoding\n│   ├── privacy/          # PII detection and masking\n│   ├── security/         # Security policy enforcement\n│   ├── storage/          # File operations\n│   ├── tools/            # MCP tool implementations\n│   ├── interfaces/       # TypeScript interfaces\n│   ├── types/            # Type definitions\n│   ├── errors/           # Error classes\n│   ├── server.ts         # MCP server implementation\n│   └── cli.ts            # CLI entry point\n├── README.md\n├── TESTING.md\n└── package.json\n```\n\n## Contributing\n\nContributions are welcome! Please ensure:\n\n- All tests pass (`npm test`)\n- Code follows TypeScript best practices\n- New features include tests and documentation\n- Security considerations are addressed\n\n## License\n\nMIT\n\n## Support\n\nFor issues and questions:\n\n- GitHub Issues: [Create an issue](https://github.com/your-org/ai-capabilities-suite/issues)\n- Documentation: See TESTING.md for testing guide\n- Security: Report security issues privately to <security@example.com>\n",
  "bytes": 19500,
  "sha": "2725117b200f6e0c9566059301f756bf98538493ba0c23c1332be82ddcfb6d75",
  "repo_slug": "digital-defiance/mcp-screenshot",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_digital_defiance_mcp_screensho_1b1f5a02/readme"
}