Documentation

// Navigate and extract
ghost_go("extract the top 30 stories from Hacker News with scores")

// Search the web
ghost_go("search for AI startups and extract the top results")

// Fill a form
ghost_go("go to example.com/contact and fill the form with name 'Alex', email 'alex@co.com'")

// Preview without executing
ghost_go("extract repos from github.com/trending", preview: true)

ghost_navigate("https://news.ycombinator.com")
// Returns: Navigated to news.ycombinator.com — 6 tools available (cache).

ghost_search("MCP server implementations", auto_navigate: true, num_results: 5)

ghost_analyze()
// Returns: Generated 8 tools for github.com:
// - github_extract_repository_stats (extract)
// - github_extract_files (extract)
// - github_click_tab (click)
// ...

// Step 1: Preview the plan
ghost_do("navigate to github trending and extract repos")
// Returns: plan with steps [ghost_navigate, ghost_analyze, auto_extract]

// Step 2: Execute
ghost_do("navigate to github trending and extract repos", confirm: true)

## Ghost Status
| Component       | Status                           |
|-----------------|----------------------------------|
| Extension       | Connected                        |
| API Key         | Set                              |
| Registry        | 12 domains, 87 tools cached      |
| Session tools   | 6 site tools active              |
| Auth            | 3 saved sessions                 |

{
  "name": "hn_paginated_extract",
  "description": "Extract stories from multiple pages of Hacker News",
  "steps": [
    { "tool": "ghost_navigate", "args": { "url": "https://news.ycombinator.com" }, "output_name": "nav" },
    { "tool": "hackernews_extract_stories", "args": {}, "output_name": "page_data" },
    { "tool": "hackernews_click_more", "args": {}, "output_name": "next" }
  ],
  "is_loop": true,
  "max_iterations": 3
}

// Add a monitor
ghost_monitor_add(url: "https://news.ycombinator.com", schedule: "1h", notify: "on_change")

// Run a check (extracts data, diffs against baseline)
ghost_monitor_check()

// List all monitors
ghost_monitor_list()

// Remove a monitor
ghost_monitor_remove(id: "mon_abc123")

// After logging into a site in the Ghost browser:
ghost_auth_save(domain: "github.com")

// List saved sessions
ghost_auth_list()
// Returns: { domains: ["github.com", "notion.so"], count: 2 }

// Open a new tab
ghost_tab_open(url: "https://github.com/trending")

// List all tabs
ghost_tab_list()
// Returns: { active_tab: "tab_1", tabs: [...], count: 3 }

// Close a tab
ghost_tab_close(tab_id: "tab_2")

ghost_download(url: "https://example.com/report.pdf", filename: "q4-report.pdf")
// Saved to ~/.ghost/downloads/q4-report.pdf

Claude Code / Codex / Any MCP Client
    | MCP/stdio
    v
Ghost MCP Server (packages/mcp-server/src/index.ts)
    |
    +--- Executor Router (picks fastest path)
    |    |
    |    +- Tier 1: API Replay    → ~226ms (direct HTTP, no browser)
    |    +- Tier 2: Browser Fetch → ~350ms (authenticated API via cookies)
    |    +- Tier 3: DOM Extract   → ~436ms (full browser with selectors)
    |
    +--- Registry Cache (~/.ghost/registry/)
    |    Cached tools as JSON — zero-cost on repeat visits
    |
    +--- Chrome Extension (WebSocket :3456)
    |    Visible browsing, login sessions, DOM analysis
    |
    +--- Playwright (headless fallback)
         Background tasks, parallel extraction

~/.ghost/
├── registry/              # Cached tools (JSON per domain/pattern)
│   ├── news.ycombinator.com/
│   │   └── _news.json
│   ├── github.com/
│   │   └── _owner_repo.json
│   └── ...
├── auth/                  # Saved session cookies and localStorage
│   ├── github.com.json
│   └── ...
├── monitors/              # Page change tracking data
│   └── ...
├── downloads/             # Downloaded files
├── speed-history.json     # Performance snapshots
└── debug.log              # Server debug log

ghost/
├── packages/
│   ├── mcp-server/src/           # MCP server — the brain
│   │   ├── index.ts              # Entry point, all tool registrations
│   │   ├── executor.ts           # Executor router (API → Bridge → Playwright)
│   │   ├── playwright-executor.ts  # Headless browser, DOM analysis, tool execution
│   │   ├── api-replay-executor.ts  # Direct HTTP for API-backed tools
│   │   ├── tool-generator.ts     # LLM-powered tool refinement
│   │   ├── nl-decomposer.ts      # Natural language → tool steps
│   │   ├── registry.ts           # Local JSON registry management
│   │   ├── quality.ts            # Tool health scoring
│   │   ├── macro-executor.ts     # Multi-step workflow engine
│   │   ├── monitor-store.ts      # Page change tracking
│   │   └── domain-api-map.ts     # Known domain → public API mappings
│   ├── extension/src/            # Chrome extension (Manifest V3)
│   │   ├── background/           # Service worker, tool generation via Claude
│   │   ├── content/              # DOM analysis, tool execution in page
│   │   └── popup/                # Extension dashboard UI
│   └── shared/src/               # Shared types (GhostTool, WsProtocol, Registry)
└── BENCHMARKS.md                 # Performance benchmark results

echo "ANTHROPIC_API_KEY=sk-ant-..." > ~/ghost/.env

export ANTHROPIC_API_KEY=sk-ant-...

claude mcp add ghost -- npx tsx ~/ghost/packages/mcp-server/src/index.ts

{
  "mcpServers": {
    "ghost": {
      "command": "npx",
      "args": ["tsx", "/path/to/ghost/packages/mcp-server/src/index.ts"],
      "env": {
        "ANTHROPIC_API_KEY": "sk-ant-..."
      }
    }
  }
}