comet-mcp

# CLAUDE.md

## What This Is
MCP server connecting Claude Code to Perplexity's Comet browser via Chrome DevTools Protocol (CDP).

**v3.0.0**: Now uses a DEDICATED MCP Comet instance (port 9223) - your personal browser tabs are never touched.

## Architecture
```
Claude Code → MCP Server (index.ts) → CometAI (comet-ai.ts) → CDP Client (cdp-client.ts) → MCP Comet Browser
                                                                                              ↓
                                                                                    Port 9223 (isolated)
                                                                                    Data: ~/.comet-mcp
```

## 8 Tools
- `comet_connect` - Start/connect to MCP-dedicated Comet (separate from personal browser)
- `comet_ask` - Send prompt, wait for response (15s default, use poll for longer)
- `comet_poll` - Check status of long-running tasks
- `comet_stop` - Stop current task
- `comet_screenshot` - Capture current page
- `comet_mode` - Switch Perplexity modes (search/research/labs)
- `comet_folders` - Manage research spaces (list/create/save)
- `comet_library` - Search existing research in Perplexity library

## Key Implementation Details

**Isolated MCP Instance (NEW in v3.0)**:
- Uses port 9223 (not 9222) to avoid conflicts with personal Comet
- Separate data directory: `~/.comet-mcp` (macOS/Linux) or `%LOCALAPPDATA%\comet-mcp` (Windows)
- **macOS**: Requires separate app bundle at `~/.comet-mcp/Comet-MCP.app` (see README setup instructions)
- Visual indicator: "[MCP]" in title + badge on page
- First launch prompts for Perplexity login

**Response extraction** (`comet-ai.ts:getAgentStatus`):
- Collects ALL prose elements (not just last) - fixes text truncation
- Scrolls to load lazy content before extraction
- 50KB response limit (up from 8KB)
- Filters UI text (Library, Discover, etc.) and questions

**Follow-up detection** (`index.ts`):
- Captures old prose count/text before sending
- Waits for NEW response (different text or more elements)

**Startup reliability**:
- 3 retry attempts on failure
- Kills stale processes before starting
- Extended timeout (30s) for slow startups

**Login detection**:
- Checks for logged-in indicators on connect
- Returns instructions if not logged in

## Build & Test
```bash
npm run build
pgrep -f "node.*comet-mcp" | xargs kill  # Restart MCP
```

Manual testing only (integration code, external DOM dependency).

## Test Cases
1. **Quick queries** - Simple questions should return within 15s
2. **Full text** - Research mode returns complete text (not truncated)
3. **Isolated instance** - Personal Comet tabs unaffected
4. **First login** - Fresh install prompts for Perplexity sign-in
5. **Agentic task** - "Take control of browser" triggers browsing
6. **Mode switching** - `comet_mode` changes search/research/labs
7. **Spaces** - `comet_folders` lists/creates/saves to spaces
8. **Library search** - `comet_library` finds past research

## Known Edge Cases
- **Prompt not submitted**: If response shows 0 steps + COMPLETED, retry or use newChat
- **Stale poll response**: If poll returns unrelated response, send prompt again
- **Research mode**: Takes longer than search, may need multiple polls
- **Folder UI changes**: Perplexity may update UI, folder operations may need adjustment

## Skills (Claude Code Integration)

The project includes a bundled Skill that teaches Claude how to use tools effectively:

```
skills/
└── comet-research/
    └── SKILL.md    # Teaches Claude research workflow
```

**Skill provides**:
- Mode selection guidance (search vs research vs labs)
- Best practices for tool usage
- Error handling patterns
- Response formatting with citations

**Install to system**:
```bash
cp -r skills/comet-research ~/.claude/skills/
```

**Plugin structure** (`.claude-plugin/plugin.json`):
- Enables distribution via Claude plugin marketplace
- Bundles both MCP server and skills together