{"id":34502774,"url":"https://github.com/gnana997/deveyes","last_synced_at":"2026-05-06T00:02:53.982Z","repository":{"id":328821292,"uuid":"1116672327","full_name":"gnana997/deveyes","owner":"gnana997","description":"MCP server that gives AI coding assistants eyes to see visual output from local development environments","archived":false,"fork":false,"pushed_at":"2025-12-15T19:12:53.000Z","size":177,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-26T23:57:11.245Z","etag":null,"topics":["ai","developer-tools","mcp","model-context-protocol","playwright","screenshot","visual-feedback"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gnana997.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-15T08:06:22.000Z","updated_at":"2025-12-23T05:16:08.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gnana997/deveyes","commit_stats":null,"previous_names":["gnana997/deveyes"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/gnana997/deveyes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnana997%2Fdeveyes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnana997%2Fdeveyes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnana997%2Fdeveyes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnana997%2Fdeveyes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gnana997","download_url":"https://codeload.github.com/gnana997/deveyes/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gnana997%2Fdeveyes/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32672684,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","developer-tools","mcp","model-context-protocol","playwright","screenshot","visual-feedback"],"created_at":"2025-12-24T02:19:57.071Z","updated_at":"2026-05-06T00:02:53.966Z","avatar_url":"https://github.com/gnana997.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# DevEyes\n\n**Give AI coding assistants \"eyes\" to see your local development UI.**\n\nDevEyes is a Model Context Protocol (MCP) server that captures screenshots from your local development environment and automatically optimizes them for LLM consumption. It bridges the gap between cloud-based AI tools (Bolt.new, Lovable, v0) and local development where AI assistants like Claude, Cursor, and Cline are effectively blind to UI output.\n\n## Features\n\n- **Smart Screenshot Capture** - Capture screenshots from any localhost URL with automatic LLM optimization\n- **Authentication Support** - Login once, screenshot protected pages (dashboards, admin panels) automatically\n- **Full-Page Screenshots** - Capture entire scrollable pages with auto-scroll to trigger lazy-loaded content\n- **Auto-Compression** - Automatically resizes and compresses images to stay within Claude's limits (8000px max, 1568px optimal)\n- **Local Save Fallback** - Save screenshots locally for MCP clients that don't support embedded images (Augment, Cline)\n- **Viewport Presets** - Built-in presets for mobile, tablet, and desktop testing\n- **Console Capture** - Captures browser console errors, warnings, and network failures\n- **Multi-Browser Support** - Choose between Chromium (default), Firefox, or WebKit\n- **Auto Browser Install** - Automatically installs the required browser on first run\n- **Zero Configuration** - Works out of the box with sensible defaults\n\n## Installation\n\n```bash\nnpm install deveyes\n```\n\nOr run directly with npx:\n\n```bash\nnpx deveyes\n```\n\n### Browser Installation\n\nDevEyes **automatically installs** the required browser on first run. No manual setup needed!\n\nIf you prefer to pre-install or use a different browser:\n\n```bash\n# Pre-install (optional)\nnpx playwright install chromium\n\n# Or install Firefox/WebKit\nnpx playwright install firefox\nnpx playwright install webkit\n```\n\n## Configuration\n\n### Claude Desktop\n\nAdd to your Claude Desktop configuration (`~/.config/claude/claude_desktop_config.json` on macOS/Linux or `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"deveyes\": {\n      \"command\": \"npx\",\n      \"args\": [\"deveyes\"]\n    }\n  }\n}\n```\n\n### Cursor\n\nAdd to your Cursor MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"deveyes\": {\n      \"command\": \"npx\",\n      \"args\": [\"deveyes\"]\n    }\n  }\n}\n```\n\n### Cline\n\nAdd to your Cline MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"deveyes\": {\n      \"command\": \"npx\",\n      \"args\": [\"deveyes\"]\n    }\n  }\n}\n```\n\n### Using a Different Browser\n\nBy default, DevEyes uses Chromium. To use Firefox or WebKit:\n\n**Via CLI argument:**\n```json\n{\n  \"mcpServers\": {\n    \"deveyes\": {\n      \"command\": \"npx\",\n      \"args\": [\"deveyes\", \"--browser\", \"firefox\"]\n    }\n  }\n}\n```\n\n**Via environment variable:**\n```json\n{\n  \"mcpServers\": {\n    \"deveyes\": {\n      \"command\": \"npx\",\n      \"args\": [\"deveyes\"],\n      \"env\": {\n        \"DEVEYES_BROWSER\": \"webkit\"\n      }\n    }\n  }\n}\n```\n\nSupported browsers: `chromium` (default), `firefox`, `webkit`\n\n### Local Screenshot Storage\n\nFor MCP clients that don't display embedded images (like Augment Code or Cline), you can enable local screenshot saving:\n\n**Enable by default (recommended for Augment/Cline users):**\n```json\n{\n  \"mcpServers\": {\n    \"deveyes\": {\n      \"command\": \"npx\",\n      \"args\": [\"deveyes\"],\n      \"env\": {\n        \"DEVEYES_SAVE_SCREENSHOTS\": \"true\"\n      }\n    }\n  }\n}\n```\n\n**With automatic cleanup (keep only last 50 screenshots):**\n```json\n{\n  \"mcpServers\": {\n    \"deveyes\": {\n      \"command\": \"npx\",\n      \"args\": [\"deveyes\"],\n      \"env\": {\n        \"DEVEYES_SAVE_SCREENSHOTS\": \"true\",\n        \"DEVEYES_MAX_SCREENSHOTS\": \"50\"\n      }\n    }\n  }\n}\n```\n\n**With custom directory (full control):**\n```json\n{\n  \"mcpServers\": {\n    \"deveyes\": {\n      \"command\": \"npx\",\n      \"args\": [\"deveyes\"],\n      \"env\": {\n        \"DEVEYES_SAVE_SCREENSHOTS\": \"true\",\n        \"DEVEYES_SCREENSHOT_DIR\": \"/Users/me/screenshots\"\n      }\n    }\n  }\n}\n```\n\n#### Screenshot Directory Detection\n\nDevEyes automatically detects where to save screenshots using this priority:\n\n1. **`DEVEYES_SCREENSHOT_DIR`** - If set, uses this exact path\n2. **Project root** - Looks for `package.json` or `.git` walking up from cwd, saves to `{project}/.deveyes/screenshots/`\n3. **Home directory fallback** - If no project found, saves to `~/.deveyes/screenshots/`\n\nThis ensures screenshots work reliably across all platforms (Windows, macOS, Linux) and MCP client configurations.\n\n### Authentication for Protected Pages\n\nDevEyes can capture screenshots of pages behind login (dashboards, admin panels, etc.) by saving your session.\n\n#### Step 1: Login and Save Session\n\n```bash\nnpx deveyes login http://localhost:3000\n```\n\nThis opens a headed browser. Log in to your app, then press Enter in the terminal. Your session (cookies + localStorage) is saved to `.deveyes/auth/localhost-3000.json`.\n\n#### Step 2: Screenshot Protected Pages\n\nNow all screenshots for that domain automatically use your saved session:\n\n```\nTake a screenshot of http://localhost:3000/dashboard\n```\n\nNo more login pages in your screenshots!\n\n#### Managing Auth States\n\n```bash\n# List all saved auth states\nnpx deveyes auth-list\n\n# Remove auth for a domain\nnpx deveyes logout http://localhost:3000\n\n# See all commands\nnpx deveyes --help\n```\n\n#### How It Works\n\n- Auth is saved per-domain (e.g., `localhost:3000`, `app.example.com`)\n- Session cookies may expire based on your app's settings - just re-run `login` when needed\n- Auth files are stored in `.deveyes/auth/` (already in `.gitignore`)\n- Response metadata shows `authenticated: { domain, used: true }` when auth was applied\n\n## Usage\n\nOnce configured, your AI assistant can use the `screenshot` tool to capture your UI:\n\n### Basic Screenshot\n\n```\nTake a screenshot of http://localhost:3000\n```\n\n### Mobile Viewport\n\n```\nCapture http://localhost:3000 with mobile viewport\n```\n\n### Full Page\n\n```\nTake a full page screenshot of http://localhost:3000/about\n```\n\n### Available Viewports\n\n| Name | Dimensions | Device Scale | Description |\n|------|------------|--------------|-------------|\n| `mobile` | 375x667 | 2x | iPhone SE / Standard mobile |\n| `mobile-lg` | 428x926 | 3x | iPhone 14 Pro Max |\n| `tablet` | 768x1024 | 2x | iPad |\n| `tablet-landscape` | 1024x768 | 2x | iPad Landscape |\n| `desktop` | 1440x900 | 1x | Standard laptop |\n| `desktop-lg` | 1920x1080 | 1x | Full HD monitor |\n| `desktop-hd` | 2560x1440 | 1x | 2K monitor |\n\nYou can also use custom dimensions: `1280x720` or `1280x720@2x` for retina.\n\n## Tool Reference\n\n### `screenshot`\n\nCapture a screenshot from any URL with automatic optimization for LLM consumption.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `url` | string | Yes | - | Full URL to capture (e.g., `http://localhost:3000`) |\n| `viewport` | string | No | `desktop` | Viewport preset or custom `WxH` dimensions |\n| `fullPage` | boolean | No | `false` | Capture full scrollable page (auto-scrolls to load lazy content) |\n| `waitFor` | string | No | `networkIdle` | Wait condition: `networkIdle`, `domStable`, `load`, `none` |\n| `waitForSelector` | string | No | - | CSS selector to wait for before capture |\n| `save` | boolean | No | `false` | Save screenshot to local `.deveyes/screenshots/` folder |\n\n**Returns:**\n\n- Optimized JPEG image (base64)\n- Metadata including:\n  - Original and processed dimensions\n  - Transforms applied\n  - Estimated token cost\n  - Console errors/warnings\n  - Network errors\n  - `savedTo` / `relativePath` (when `save=true`)\n  - `hint` - Helpful message for retry or configuration\n\n## Image Optimization\n\nDevEyes automatically optimizes images to work within Claude's constraints:\n\n| Constraint | Limit | What DevEyes Does |\n|------------|-------|-------------------|\n| Max dimension | 8,000 px | Resizes to 1,568 px (optimal) |\n| Optimal dimension | 1,568 px | Targets this for best quality/token ratio |\n| Max file size | 5 MB | Compresses to ~750 KB (for base64 overhead) |\n| Token cost | (w×h)/750 | Reports estimated tokens in response |\n| Full-page minimum width | 800 px | Maintains readable width for tall screenshots |\n\n### Full-Page Screenshot Handling\n\nWhen `fullPage=true`, DevEyes:\n1. **Auto-scrolls** through the entire page to trigger lazy-loaded content (Intersection Observer, scroll animations)\n2. **Forces animation completion** by disabling CSS animations/transitions\n3. **Maintains readable width** (minimum 800px) even for very tall pages\n4. **Allows larger file size** (~1.5MB vs ~750KB) for detailed full-page captures\n\n## Development\n\n### Setup\n\n```bash\ngit clone https://github.com/gnana997/deveyes.git\ncd deveyes\nnpm install\nnpx playwright install chromium\n```\n\n### Commands\n\n```bash\n# Development mode (with hot reload)\nnpm run dev\n\n# Build for production\nnpm run build\n\n# Run tests\nnpm test\n\n# Run tests once\nnpm run test:run\n\n# Debug with MCP Inspector\nnpm run inspect\n```\n\n### Testing with MCP Inspector\n\nThe MCP Inspector provides a visual interface for testing your server:\n\n```bash\nnpm run inspect\n```\n\nThis opens a browser UI at `http://localhost:6274` where you can:\n- List available tools\n- Execute the screenshot tool with different parameters\n- View responses and debug issues\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                        MCP CLIENT                               │\n│            (Claude Desktop / Cursor / Cline)                    │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n                              │ JSON-RPC over stdio\n                              ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                     DEVEYES MCP SERVER                          │\n├─────────────────────────────────────────────────────────────────┤\n│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │\n│  │   Tool      │  │   Image     │  │   Browser               │ │\n│  │   Handler   │  │   Processor │  │   Manager               │ │\n│  │             │  │   (Sharp)   │  │   (Playwright)          │ │\n│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │\n└─────────────────────────────────────────────────────────────────┘\n                              │\n                              │ HTTP\n                              ▼\n┌─────────────────────────────────────────────────────────────────┐\n│                   YOUR LOCAL DEV SERVER                         │\n│                (localhost:3000, 5173, etc.)                     │\n└─────────────────────────────────────────────────────────────────┘\n```\n\n## Troubleshooting\n\n### \"Browser not found\" error\n\nDevEyes automatically installs browsers, but if installation fails, manually install:\n\n```bash\nnpx playwright install chromium\n# or for other browsers:\nnpx playwright install firefox\nnpx playwright install webkit\n```\n\n### Screenshot times out\n\nIncrease the wait time or try a different wait strategy:\n\n```\nTake a screenshot of http://localhost:3000 with waitFor: load\n```\n\n### Image too large\n\nDevEyes automatically optimizes images. If you're still seeing issues, the page content itself may be very large. Try:\n- Using a smaller viewport\n- Capturing a specific section instead of full page\n- Ensuring your dev server is responding quickly\n\n### Console not capturing errors\n\nMake sure your page has finished loading. Use `waitFor: load` or `waitForSelector` to ensure the page is ready:\n\n```\nScreenshot http://localhost:3000 waitForSelector: #app\n```\n\n### Image not displaying in Augment/Cline\n\nSome MCP clients (Augment Code, Cline) don't support embedded images in tool responses. Use the `save` parameter or enable it by default:\n\n**Option 1: Per-request**\n```\nTake a screenshot of http://localhost:3000 with save=true\n```\n\n**Option 2: Set as default (recommended)**\nAdd `DEVEYES_SAVE_SCREENSHOTS=true` to your MCP server config (see [Local Screenshot Storage](#local-screenshot-storage)).\n\nThe screenshot will be saved to `.deveyes/screenshots/` and you can attach it manually to your chat.\n\n### Full-page screenshot missing content\n\nIf sections appear blank in full-page screenshots, the page may have:\n- **Heavy lazy loading** - Try waiting longer with `waitFor: load`\n- **Scroll-triggered animations** - DevEyes auto-scrolls but some complex animations may need `waitForSelector`\n- **Dynamic content loading** - Use `waitForSelector` to wait for specific elements\n\n### Screenshot shows login page instead of dashboard\n\nYour session may have expired. Re-authenticate:\n\n```bash\nnpx deveyes login http://localhost:3000\n```\n\nTo check if auth exists for a domain:\n```bash\nnpx deveyes auth-list\n```\n\n### Screenshot save fails on macOS/Linux\n\nIf `save=true` fails with a path or permission error:\n\n1. **Check the logs** - DevEyes logs which directory it's using:\n   ```\n   [DevEyes] Screenshot dir (project): /path/to/.deveyes/screenshots\n   [DevEyes] Screenshot dir (home fallback): ~/.deveyes/screenshots\n   ```\n\n2. **Use custom directory** - Set `DEVEYES_SCREENSHOT_DIR` to a writable path:\n   ```json\n   {\n     \"env\": {\n       \"DEVEYES_SCREENSHOT_DIR\": \"/Users/me/screenshots\"\n     }\n   }\n   ```\n\n3. **Home directory fallback** - If no project is detected, DevEyes saves to `~/.deveyes/screenshots/` which should always be writable.\n\n## Contributing\n\nContributions are welcome! Please read our contributing guidelines and submit PRs to the main repository.\n\n## License\n\nMIT\n\n## Links\n\n- [GitHub Repository](https://github.com/gnana997/deveyes)\n- [Report Issues](https://github.com/gnana997/deveyes/issues)\n- [MCP Documentation](https://modelcontextprotocol.io)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgnana997%2Fdeveyes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgnana997%2Fdeveyes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgnana997%2Fdeveyes/lists"}