@shawnowen/comet-mcp 2.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,196 @@
+# comet-mcp
+
+[![npm version](https://img.shields.io/npm/v/comet-mcp.svg)](https://www.npmjs.com/package/comet-mcp)
+
+<a href="https://glama.ai/mcp/servers/@hanzili/comet-mcp">
+  <img width="380" height="200" src="https://glama.ai/mcp/servers/@hanzili/comet-mcp/badge" />
+</a>
+
+**Give Claude Code a browser that thinks.**
+
+An MCP server that connects Claude Code to [Perplexity Comet](https://www.perplexity.ai/comet) - enabling agentic web browsing, deep research, and real-time task monitoring.
+
+![Demo](demo.gif)
+
+## Why?
+
+Existing web tools for Claude Code fall into two categories, both with limitations:
+
+### 1. Search APIs (Tavily, Perplexity API, WebFetch)
+Return static text. No interaction, no login, no dynamic content. Great for quick lookups, but can't navigate complex sites or fill forms.
+
+### 2. Browser Automation (browser-use, Puppeteer MCP, Playwright MCP)
+Can interact with pages, but use a **one-agent-do-all** approach: the same reasoning model that's writing your code is also deciding where to click, what to type, and how to navigate. This overwhelms the context window and fragments focus.
+
+### 3. Comet MCP: Multi-Agent Delegation
+**Comet MCP takes a different approach.** Instead of Claude controlling a browser directly, it delegates to [Perplexity Comet](https://www.perplexity.ai/comet) - an AI purpose-built for web research and browsing.
+
+- **Claude** stays focused on your coding task
+- **Comet** handles the browsing: navigation, login walls, dynamic content, deep research
+- **Result**: Claude's coding intelligence + Perplexity's web intelligence, working together
+
+## Quick Start
+
+### 1. Configure Claude Code
+
+Add to `~/.claude.json` or `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "comet-bridge": {
+      "command": "npx",
+      "args": ["-y", "comet-mcp"]
+    }
+  }
+}
+```
+
+### 2. Install Comet Browser
+
+Download and install [Perplexity Comet](https://www.perplexity.ai/comet).
+
+That's it! The MCP server automatically launches Comet with remote debugging when needed.
+
+### 3. Use in Claude Code
+
+```
+You: "Use Comet to research the top AI frameworks in 2025"
+Claude: [delegates to Comet, monitors progress, returns results]
+
+You: "Log into my GitHub and check my notifications"
+Claude: [Comet handles the login flow and navigation]
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `comet_connect` | Connect to Comet (auto-starts if needed) |
+| `comet_ask` | Send a task and wait for response |
+| `comet_poll` | Check progress on long-running tasks |
+| `comet_stop` | Stop current task |
+| `comet_screenshot` | Capture current page |
+| `comet_mode` | Switch modes: search, research, labs, learn |
+| `comet_tab_groups` | Manage Chrome tab groups (list, create, update, delete) |
+
+## Tab Groups
+
+Control Comet's native Chrome tab groups programmatically — create, rename, recolor, collapse, and delete groups.
+
+**Requires a one-time extension install** (included in the `extension/` directory):
+
+1. Open `comet://extensions` in Comet
+2. Enable **Developer mode** (top-right toggle)
+3. Click **Load unpacked** → select the `extension/` folder from this repo
+4. The "Comet Tab Groups Bridge" extension appears
+
+**How it works**: CDP cannot access Chrome's tab group API. The included MV3 extension provides `tabGroups` permission, and comet-mcp connects to the extension's service worker via CDP to evaluate `chrome.tabGroups.*` calls directly. No native messaging host needed.
+
+```
+Claude Code → MCP Server → CDP → Extension Service Worker → chrome.tabGroups API → Comet UI
+```
+
+**Available actions**:
+
+| Action | Parameters | Description |
+|--------|-----------|-------------|
+| `list` | — | List all tab groups (id, title, color, collapsed state) |
+| `list_tabs` | — | List all tabs with their group assignments |
+| `create` | `tabIds`, `title?`, `color?` | Group tabs and optionally name/color them |
+| `update` | `groupId`, `title?`, `color?`, `collapsed?` | Change group properties |
+| `move` | `groupId`, `index` | Reorder a group |
+| `ungroup` | `tabIds` | Remove tabs from their groups |
+| `delete` | `groupId` | Dissolve a group (tabs remain open) |
+
+**Colors**: `grey`, `blue`, `red`, `yellow`, `green`, `pink`, `purple`, `cyan`, `orange`
+
+## HTTP REST Bridge
+
+For environments that can't use MCP directly (e.g., sandboxed VMs), an HTTP server exposes all tools as REST endpoints:
+
+```bash
+npm run build && npm run http
+# Starts on http://localhost:3456
+```
+
+See [COWORK-BRIDGE.md](COWORK-BRIDGE.md) for full endpoint documentation.
+
+## How It Works
+
+```
+Claude Code  →  MCP Server  →  CDP  →  Comet Browser  →  Perplexity AI
+   (reasoning)     (bridge)                              (web browsing)
+```
+
+Claude sends high-level goals ("research X", "log into Y"). Comet figures out the clicks, scrolls, and searches. Results flow back to Claude.
+
+## Requirements
+
+- Node.js 18+
+- [Perplexity Comet Browser](https://www.perplexity.ai/comet)
+- Claude Code (or any MCP client)
+- **Supported platforms**: macOS, Windows, WSL2
+
+## Windows & WSL Support
+
+### Native Windows
+Works out of the box. Comet MCP auto-detects Windows and launches Comet from its default install location.
+
+### WSL2 (Windows Subsystem for Linux)
+WSL2 requires **mirrored networking** to connect to Comet running on Windows:
+
+1. **Enable mirrored networking** (one-time setup):
+   ```
+   # Create/edit %USERPROFILE%\.wslconfig (Windows side)
+   [wsl2]
+   networkingMode=mirrored
+   ```
+
+2. **Restart WSL**:
+   ```bash
+   wsl --shutdown
+   # Then reopen your WSL terminal
+   ```
+
+3. **That's it!** Comet MCP auto-detects WSL and uses PowerShell to communicate with Windows.
+
+If mirrored networking isn't available, you'll see a helpful error message with setup instructions.
+
+### Custom Comet Path
+If Comet is installed in a non-standard location:
+```json
+{
+  "mcpServers": {
+    "comet-bridge": {
+      "command": "npx",
+      "args": ["-y", "comet-mcp"],
+      "env": {
+        "COMET_PATH": "/path/to/your/Comet"
+      }
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+**"Cannot connect to Comet"**
+- **macOS**: Ensure Comet is installed at `/Applications/Comet.app`
+- **Windows**: Comet should be in `%LOCALAPPDATA%\Perplexity\Comet\Application\`
+- Check if port 9222 is available
+
+**"WSL cannot connect to Windows localhost"**
+- Enable mirrored networking (see WSL section above)
+- Or run Claude Code from Windows PowerShell instead of WSL
+
+**"Tools not showing in Claude"**
+- Restart Claude Code after config changes
+
+## License
+
+MIT
+
+---
+
+[Report Issues](https://github.com/hanzili/comet-mcp/issues) · [Contribute](https://github.com/hanzili/comet-mcp)

package/dist/cdp-client.d.ts

@@ -0,0 +1,118 @@
+import type { CDPTarget, CDPVersion, NavigateResult, ScreenshotResult, EvaluateResult, CometState, NetworkIdleResult } from "./types.js";
+export declare class CometCDPClient {
+    private client;
+    private cometProcess;
+    private state;
+    private lastTargetId;
+    private reconnectAttempts;
+    private maxReconnectAttempts;
+    private isReconnecting;
+    get isConnected(): boolean;
+    /**
+     * Health check - verify connection is actually alive (not just "connected" in state)
+     * This catches cases where WebSocket died silently
+     */
+    isHealthy(): Promise<boolean>;
+    /**
+     * Ensure we have a healthy connection, reconnecting if needed
+     * Call this before any CDP operation
+     */
+    ensureHealthyConnection(): Promise<void>;
+    get currentState(): CometState;
+    /**
+     * Auto-reconnect wrapper for operations with exponential backoff
+     */
+    private withAutoReconnect;
+    /**
+     * Reconnect to the last connected tab
+     */
+    reconnect(): Promise<string>;
+    /**
+     * List tabs with categorization
+     */
+    listTabsCategorized(): Promise<{
+        main: CDPTarget | null;
+        sidecar: CDPTarget | null;
+        agentBrowsing: CDPTarget | null;
+        overlay: CDPTarget | null;
+        others: CDPTarget[];
+    }>;
+    /**
+     * Check if Comet process is running
+     */
+    private isCometProcessRunning;
+    /**
+     * Kill any running Comet process
+     */
+    private killComet;
+    /**
+     * Start Comet browser with remote debugging enabled
+     * Handles macOS, Windows, and WSL environments
+     */
+    startComet(port?: number): Promise<string>;
+    /**
+     * Get CDP version info
+     */
+    getVersion(): Promise<CDPVersion>;
+    /**
+     * List all available tabs/targets
+     */
+    listTargets(): Promise<CDPTarget[]>;
+    /**
+     * Connect to a specific tab
+     */
+    connect(targetId?: string): Promise<string>;
+    /**
+     * Disconnect from current tab
+     */
+    disconnect(): Promise<void>;
+    /**
+     * Navigate to a URL
+     */
+    navigate(url: string, waitForLoad?: boolean, waitForNetworkIdle?: boolean): Promise<NavigateResult & {
+        networkIdle?: NetworkIdleResult;
+    }>;
+    /**
+     * Capture screenshot
+     */
+    screenshot(format?: "png" | "jpeg"): Promise<ScreenshotResult>;
+    /**
+     * Execute JavaScript in the page context
+     */
+    evaluate(expression: string): Promise<EvaluateResult>;
+    /**
+     * Execute JavaScript with auto-reconnect on connection loss
+     * This is the PREFERRED method - always use this instead of evaluate()
+     */
+    safeEvaluate(expression: string): Promise<EvaluateResult>;
+    /**
+     * Press a key
+     */
+    pressKey(key: string): Promise<void>;
+    /**
+     * Create a new tab
+     */
+    newTab(url?: string): Promise<CDPTarget>;
+    /**
+     * Close a tab
+     */
+    closeTab(targetId: string): Promise<boolean>;
+    /**
+     * Get the page's accessibility tree as a compact text representation
+     */
+    getAccessibilityTree(maxDepth?: number, maxLength?: number): Promise<string>;
+    /**
+     * Extract clean readable text from the current page
+     */
+    getPageText(maxLength?: number): Promise<string>;
+    /**
+     * Wait for network activity to settle (no pending requests for idleTime ms)
+     */
+    waitForNetworkIdle(options?: {
+        idleTime?: number;
+        timeout?: number;
+    }): Promise<NetworkIdleResult>;
+    private ensureConnected;
+}
+export declare const cometClient: CometCDPClient;
+//# sourceMappingURL=cdp-client.d.ts.map

package/dist/cdp-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp-client.d.ts","sourceRoot":"","sources":["../src/cdp-client.ts"],"names":[],"mappings":"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"}