{"id":29340410,"url":"https://github.com/williamkapke/kapture","last_synced_at":"2025-07-08T08:03:19.163Z","repository":{"id":299122660,"uuid":"1002098938","full_name":"williamkapke/kapture","owner":"williamkapke","description":"Chrome DevTools Extension that enables browser automation through MCP","archived":false,"fork":false,"pushed_at":"2025-07-07T06:39:27.000Z","size":1712,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-07T07:40:50.306Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","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/williamkapke.png","metadata":{"files":{"readme":"README.md","changelog":null,"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}},"created_at":"2025-06-14T17:57:55.000Z","updated_at":"2025-07-07T06:39:31.000Z","dependencies_parsed_at":"2025-06-14T20:33:02.775Z","dependency_job_id":"2175535b-62e9-41ff-9856-9533b2ac89e8","html_url":"https://github.com/williamkapke/kapture","commit_stats":null,"previous_names":["williamkapke/kapture"],"tags_count":9,"template":false,"template_full_name":null,"purl":"pkg:github/williamkapke/kapture","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamkapke%2Fkapture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamkapke%2Fkapture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamkapke%2Fkapture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamkapke%2Fkapture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/williamkapke","download_url":"https://codeload.github.com/williamkapke/kapture/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/williamkapke%2Fkapture/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264229175,"owners_count":23576233,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-07-08T08:01:44.418Z","updated_at":"2025-07-08T08:03:19.154Z","avatar_url":"https://github.com/williamkapke.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Kapture - Browser Automation via Chrome DevTools\n\nKapture is a Chrome DevTools Extension that enables browser automation through the Model Context Protocol (MCP). It allows AI applications like Claude to control web browsers via a three-layer architecture.\n\n**✨ Key Feature**: Multiple AI clients can connect to the same server! Claude Desktop, Cline, and other MCP clients can all control browser tabs through a single server instance.\n\n![Available in the Chrome Web Store](https://to.kap.co/kapture-extension)]\n\n![Kapture DevTools Extension Panel](website/assets/images/ScreenshotWithExtensionPanel.webp)\n\n## Overview\n\nKapture bridges AI assistants with web browsers through:\n- **MCP Server**: Handles MCP protocol communication\n- **Chrome Extension**: DevTools panel for browser automation\n- **WebSocket Bridge**: Real-time communication between server and extensions\n- **Multi-Client Support**: Multiple AI clients can connect simultaneously via WebSocket\n\n## Architecture\n![How Kapture Works](website/assets/images/HowKaptureWorks.webp)\n\n## Quick Start\n\n### 1. Install Dependencies\n\n```bash\n# Server\ncd server\nnpm install\nnpm run build\n\n# Test App (optional)\ncd test-app\nnpm install\n```\n\n### 2. Install Chrome Extension\n\n#### Option A: Install from Chrome Web Store (Recommended)\n1. Visit the [Kapture Chrome Web Store page](https://to.kap.co/kapture-extension)\n2. Click \"Add to Chrome\"\n3. Confirm the installation\n\n#### Option B: Load Unpacked (Developer Mode)\n1. Open Chrome and navigate to `chrome://extensions/`\n2. Enable \"Developer mode\"\n3. Click \"Load unpacked\"\n4. Select the `extension` folder\n\n### 3. Start MCP Server\n[Configure your AI client](https://williamkapke.github.io/kapture/MCP_USAGE.html) and open it. It will start the MCP server automatically.\n\n**OR**\n\nRun the Test App:\n\n```bash\ncd test-app\nnpm run dev\n```\n\nThe server starts on port 61822.\n\n```bash\n# Server\ncd server\nnpm start\n\n# Test App\ncd test-app\nnpm start\n```\n\n### 4. Connect via DevTools\n\n1. Open any website in Chrome\n2. Open Chrome/Brave Developer Tools (F12 on Windows/Linux, Cmd+Option+I on macOS)\n3. Navigate to \"Kapture\" panel\n4. The extension will automatically connect to the server on port 61822\n5. Select a server from the dropdown to connect automatically\n\n## Using with Claude Desktop\n\nAdd to your Claude Desktop config:\n\n### Option 1: Using the bridge command (Recommended)\nThis single command starts the server and handles stdio-to-WebSocket translation:\n```json\n{\n  \"mcpServers\": {\n    \"kapture\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"kapture-mcp\", \"bridge\"]\n    }\n  }\n}\n```\n\n### Option 2: Direct WebSocket connection (Advanced)\nFor advanced use cases where you need manual server control:\n\n1. Start the server manually:\n```bash\nnpx kapture-mcp\n```\n\n2. Configure Claude Desktop to connect via WebSocket:\n```json\n{\n  \"mcpServers\": {\n    \"kapture\": {\n      \"transport\": \"websocket\",\n      \"url\": \"ws://localhost:61822/mcp\"\n    }\n  }\n}\n```\n\n**Note**: This approach requires manually managing the server lifecycle. Use Option 1 (bridge command) for most use cases.\n\n## 🚀 Run Multiple AI Assistants Simultaneously\n\nKapture supports multiple MCP clients connecting to the same server! You can run Claude Desktop, Cline, and other MCP clients simultaneously through a single server instance.\n\n### How It Works\n- All MCP clients connect via WebSocket to `ws://localhost:61822/mcp`\n- All MCP clients share access to the same browser tabs\n- Notifications are broadcast to all connected clients\n\n### Smart Server Detection\nWhen running `npx kapture-mcp`, the command automatically detects if a server is already running:\n- **No existing server**: Starts a new server on port 61822\n- **Server already running**: Shows connection information and exits gracefully\n\nThis prevents errors and confusion when multiple clients try to start servers.\n\n### Setting Up Multiple Clients\n\nEach client should use the same bridge command configuration:\n\n**Claude Desktop**:\n```json\n{\n  \"mcpServers\": {\n    \"kapture\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"kapture-mcp\", \"bridge\"]\n    }\n  }\n}\n```\n\n**Cline/VS Code**:\n```json\n{\n  \"cline.mcpServers\": {\n    \"kapture\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"kapture-mcp\", \"bridge\"]\n    }\n  }\n}\n```\n\n**Other MCP Clients**:\nUse the same configuration pattern with `\"command\": \"npx\"` and `\"args\": [\"-y\", \"kapture-mcp\", \"bridge\"]`.\n\n[See the complete multi-assistant guide →](https://williamkapke.github.io/kapture/MULTI_ASSISTANT_GUIDE.html)\n\n### Benefits of Multiple AI Assistants:\n- **Parallel Workflows**: Have Claude Desktop research while Cline develops code\n- **Specialized Tasks**: Use different AI clients for different types of automation\n- **Team Collaboration**: Multiple team members can use their preferred AI tools simultaneously\n- **Testing \u0026 Development**: Test automation scripts with one AI while developing with another\n\nThen ask Claude to interact with web pages:\n- \"Navigate to example.com and take a screenshot\"\n- \"Click the search button\"\n- \"Fill in the email field with test@example.com\"\n\n## Available MCP Tools\n\n- `navigate` - Navigate to URL\n- `back` - Browser back button\n- `forward` - Browser forward button\n- `reload` - Reload the current page (similar to pressing F5)\n- `click` - Click elements (uses first matching element, returns unique selector)\n- `hover` - Hover over elements (uses first matching element, returns unique selector)\n- `fill` - Fill input fields (uses first matching element, returns unique selector)\n- `select` - Select dropdown options (HTML `\u003cselect\u003e` only, uses first matching element, returns unique selector)\n- `keypress` - Send keyboard events to the page or specific elements (supports modifier keys)\n- `elements` - Query all elements matching a CSS selector or XPath with optional visibility filtering\n\n**Note on Selectors**: Tools that accept a `selector` parameter (`click`, `hover`, `fill`, `select`, `keypress`, `screenshot`, `dom`) will only operate on the **first element** that matches the CSS selector. The tool response includes the unique selector of the actual element that was used, which may include an auto-generated ID if the element didn't have one.\n\n**XPath Support**: All tools that accept a `selector` parameter also accept an `xpath` parameter as an alternative. This is particularly useful for:\n- Finding elements by text content: `xpath: \"//button[contains(text(), 'Submit')]\"`\n- Complex element relationships: `xpath: \"//div[@class='container']//span[2]\"`\n- When CSS selectors are insufficient\n\nUse either `selector` OR `xpath`, not both. If both are provided, `selector` takes precedence.\n\n### Keypress Tool\n\nThe `keypress` tool simulates keyboard events. It accepts:\n- `key` (required): The key combination to press. Can be:\n  - Single key: `\"a\"`, `\"Enter\"`, `\"Tab\"`, `\"Escape\"`, `\" \"` (space), `\"Shift\"`, `\"Control\"`\n  - With modifiers: `\"Control+a\"`, `\"Shift+Tab\"`, `\"Alt+F4\"`, `\"Meta+Shift+p\"`\n  - Modifier names: `Control` (or `Ctrl`), `Shift`, `Alt`, `Meta` (or `Cmd`/`Command`)\n  - Note: When sending just a modifier key (e.g., `\"Shift\"`), it's treated as pressing that key alone\n  - Duplicate modifiers are ignored (e.g., `\"Shift+Shift+a\"` is same as `\"Shift+a\"`)\n- `selector` or `xpath` (optional): Target a specific element. If not provided, sends to document.body\n\nExamples:\n```json\n// Press Enter\n{ \"key\": \"Enter\", \"selector\": \"#login-form\" }\n\n// Select all text (Ctrl+A)\n{ \"key\": \"Control+a\", \"selector\": \"#username\" }\n\n// Zoom in (Ctrl+Plus)\n{ \"key\": \"Control++\", \"selector\": \"body\" }\n\n// Zoom out (Ctrl+Minus)\n{ \"key\": \"Control+-\", \"selector\": \"body\" }\n\n// New tab (Ctrl+T)\n{ \"key\": \"Control+t\" }\n\n// Close tab (Ctrl+W or Cmd+W on Mac)\n{ \"key\": \"Meta+w\" }\n```\n\n### MCP Resources\n\n- `kapture://tabs` - List all connected browser tabs\n- `kapture://tab/{tabId}` - Get detailed information about a specific tab\n- `kapture://tab/{tabId}/console` - Get console logs from a specific tab (with pagination support)\n- `kapture://tab/{tabId}/screenshot` - Capture screenshots of a tab or element\n- `kapture://tab/{tabId}/dom` - Get HTML content of a tab or element\n- `kapture://tab/{tabId}/elementsFromPoint` - Get elements at specific coordinates\n- `kapture://tab/{tabId}/elements?selector={selector}\u0026visible={true|false|all}` - Query all elements matching a CSS selector or XPath with optional visibility filtering\n\n## Development\n\n### Server Development\n\n```bash\ncd server\nnpm run dev    # Development with hot-reload\n```\n\n### Test App\n\n```bash\ncd test-app\nnpm run dev    # Run Electron test app\n```\n\n### Extension Development\n\nAfter making changes:\n1. Go to `chrome://extensions/`\n2. Click refresh on Kapture extension\n\n\n### Key Components\n\n**Server** (`/server`):\n- `mcp-handler.ts` - MCP protocol implementation\n- `websocket-manager.ts` - WebSocket server\n- `tab-registry.ts` - Tab tracking\n- `tools/*.ts` - MCP tool implementations\n\n**Extension** (`/extension`):\n- `panel/command-executor.js` - Command execution\n- `panel/command-queue.js` - Sequential execution\n- `background.js` - Screenshot service worker\n\n## DevTools Panel Features\n\n- **Automatic Connection** - Connects to server on port 61822\n- **Server Selection** - Dropdown to choose between multiple running servers\n- **Connection Status** - Real-time server connection indicator\n- **Tab Info** - Current tab ID and URL display\n- **Command Testing** - Manual command execution interface\n- **Console Viewer** - Live console log capture\n- **History** - Command history\n- **Dark Theme** - Toggle between light/dark modes\n\n## Troubleshooting\n\n### Connection Issues\n- The extension will automatically connect to the server on port 61822\n- If no servers are found, verify the server is running\n- Check the server dropdown to see which servers were discovered\n- Check browser console for errors\n- Check server logs in the terminal\n\n### Extension Not Showing\n- Ensure extension is loaded and enabled\n- Close and reopen DevTools\n- Reload extension in `chrome://extensions/`\n\n### Command Timeouts\n- Default timeout is 5 seconds\n- Some commands accept custom timeout parameter\n- Check element selectors are correct\n\n### Performance Considerations\n**Important**: The `click` and `hover` tools may experience performance issues when the Kapture DevTools panel is not the active/selected tab in Chrome DevTools. For optimal performance:\n- Keep the Kapture panel selected during automation\n- If experiencing delays with click/hover operations, switch to the Kapture panel\n- This is due to Chrome's optimization of inactive DevTools panels\n\n## Security\n\n- Commands execute within Chrome's DevTools sandbox\n- Each tab has unique ID preventing cross-tab interference\n- No direct file system access from extension\n- Tab registry enforces command isolation\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamkapke%2Fkapture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwilliamkapke%2Fkapture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwilliamkapke%2Fkapture/lists"}