How It Works

Asteria is an MCP server that bridges AI assistants with Perplexity Comet — the agentic browser that researches, browses, and answers questions autonomously. Unlike simple search APIs, Comet navigates pages, follows links, and reasons over live web content. Asteria exposes all of that through 13 MCP tools via Chrome DevTools Protocol (CDP), with no Puppeteer or Playwright dependencies.

graph LR
  A["AI Agent\n(Claude / GPT / Gemini)"] -->|"MCP stdio"| B["Asteria\nMCP Server"]
  B -->|"CDP WebSocket"| C["Perplexity\nComet Browser"]
  C -->|"HTTP requests"| D["Web Pages\n& Sources"]
  D -->|"Response + Sources"| C
  C -->|"Research results"| B
  B -->|"Formatted response"| A

The agent sends a prompt through MCP. Asteria connects to Comet over CDP, submits the query, monitors Comet's agentic research cycle, and returns the full response with cited sources.

Features

| | Feature | Description | |---|---------|-------------| | 🔌 | 13 MCP tools | Connect, ask, poll, wait, stop, screenshot, mode switch, tab management, source extraction, conversation history, page content | | ⚡ | Non-blocking polling | Submit a prompt and poll for completion — the agent keeps working while Comet researches | | ⏳ | Blocking wait | comet_wait blocks until Comet finishes, ideal when comet_ask times out mid-response | | 🔍 | Auto-detect Comet | Finds Comet on Windows, macOS, and Linux; launches it with the correct debug port | | 🔄 | Auto-reconnect | Exponential backoff with health checks — survives Comet restarts without dropping the session | | 🧠 | Version-aware selectors | Auto-detects Comet's Chrome version and routes to the correct CSS selectors | | 📑 | Tab categorization | Tracks main, sidecar, agent-browsing, and overlay tabs separately | | 🚫 | Zero browser dependencies | No Puppeteer or Playwright — uses CDP directly via chrome-remote-interface | | 🛠️ | CLI included | asteria detect to check installation, asteria snapshot to capture DOM structure |

Requirements

• Node.js >= 18
• Perplexity Comet installed and running
• Windows, macOS, or Linux (Linux requires setting COMET_PATH)

Installation

npm install -g @onestepat4time/asteria

Quick Start

1. Add to your MCP client config

Claude Code (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "asteria": {
      "type": "stdio",
      "command": "asteria",
      "args": ["start"]
    }
  }
}

Cursor (~/.cursor/mcp.json) — same format.

2. Make sure Comet is running

Open Perplexity Comet on your machine. Asteria auto-detects the running instance.

3. Use in your agent

> Ask Perplexity what the latest AI research papers are this week

Asteria connects to Comet, sends the query, waits for the full research response, and returns it with cited sources to your assistant.

Tools

| Tool | Description | Docs | |------|-------------|------| | comet_connect | Connect to or launch Perplexity Comet | Reference | | comet_ask | Send a prompt and start an agentic search | Reference | | comet_poll | Check current agent status, steps, and response content | Reference | | comet_wait | Block until the agent finishes responding; use after comet_ask times out | Reference | | comet_stop | Stop the currently running agent | Reference | | comet_screenshot | Capture a screenshot of the active tab | Reference | | comet_mode | Get or switch the search mode (standard, deep-research, model-council, etc.) | Reference | | comet_list_tabs | List all open tabs by category (main, sidecar, agent-browsing, overlay) | Reference | | comet_switch_tab | Switch focus to a specific tab by ID or title | Reference | | comet_get_sources | Extract cited sources from the current response | Reference | | comet_list_conversations | List recent conversation links visible on the page | Reference | | comet_open_conversation | Navigate to a specific conversation URL | Reference | | comet_get_page_content | Extract full text from the active page | Reference |

CLI

asteria start      # Start MCP stdio server
asteria detect     # Detect Comet installation path and debug port
asteria --version  # Print version
asteria --help     # Print help

Configuration

All settings can be overridden via environment variables:

| Variable | Default | Description | |----------|---------|-------------| | ASTERIA_PORT | 9222 | CDP debug port | | COMET_PATH | auto-detect | Path to Comet executable | | ASTERIA_LOG_LEVEL | info | Log level: debug / info / warn / error | | ASTERIA_TIMEOUT | 30000 | Comet launch timeout (ms) | | ASTERIA_RESPONSE_TIMEOUT | 180000 | Max wait for response (ms) | | ASTERIA_POLL_INTERVAL | 1000 | Status poll interval (ms) | | ASTERIA_SCREENSHOT_FORMAT | png | Screenshot format: png / jpeg | | ASTERIA_MAX_RECONNECT | 5 | Max reconnection attempts | | ASTERIA_RECONNECT_DELAY | 5000 | Max reconnection backoff delay (ms) |

See Configuration for the full reference.

Guides

| Guide | Description | |-------|-------------| | Tool Reference | All 13 tools with parameters, return values, and examples | | Integration Guide | Set up with Claude Code, Cursor, or custom MCP clients | | Configuration | Environment variables and config files | | Troubleshooting | Common issues and error codes | | Architecture | How Asteria works internally |

Architecture

graph TD
  subgraph MCP["MCP Protocol Layer"]
    T1[comet_connect] & T2[comet_ask] & T3[comet_poll]
    T4[comet_wait] & T5[comet_stop] & T6[comet_screenshot]
    T7[comet_mode] & T8[comet_list_tabs] & T9[comet_switch_tab]
    T10[comet_get_sources] & T11[comet_list_conversations]
    T12[comet_open_conversation] & T13[comet_get_page_content]
  end

  subgraph UI["UI Automation"]
    S[Selector Strategies]
    I[Prompt Input]
    ST[Status Detection]
    EX[Content Extraction]
  end

  subgraph CDP["CDP Transport"]
    BR[Browser Launcher]
    CO[WebSocket Connection]
    TA[Tab Management]
    RC[Auto-Reconnect]
  end

  T2 --> I
  T3 --> ST
  T4 --> ST
  T10 & T13 --> EX
  T6 & T8 --> TA
  I & ST & EX --> S
  CO --> BR
  TA & RC --> CO
  CO --> Comet[Perplexity Comet]

Roadmap

• [ ] Streaming responses — stream Comet responses token-by-token instead of polling
• [ ] MCP Resources — expose Perplexity pages as MCP resources for direct reading
• [ ] Multi-Comet sessions — control multiple Comet instances simultaneously
• [ ] HTTP/SSE transport — support N8N and REST clients in addition to stdio
• [ ] Browser extension — package as a browser extension for tighter integration

Contributing

Contributions are welcome. Open an issue before submitting large PRs.

git clone https://github.com/OneStepAt4time/asteria.git
cd asteria
npm install
npm run build
npm test

See Contributing for code style, adding Comet versions, and commit conventions.

Support the Project

If Asteria saves you time, consider sponsoring:

License

MIT © 2026 OneStepAt4time