┌──────────────────────────────────────────┐
│  MCP Client (Claude Code, Cursor, etc.)  │
└──────────────────┬───────────────────────┘
                   │ Streamable HTTP / stdio
┌──────────────────▼───────────────────────┐
│           xengager-mcp Server             │
│  ┌──────────┐  ┌──────────────────────┐  │
│  │ GraphQL   │  │  DOM Scraping        │  │
│  │ (primary) │  │  (Puppeteer fallback) │  │
│  └──────────┘  └──────────────────────┘  │
│  ┌──────────────────────────────────────┐│
│  │  Puppeteer + stealth plugin          ││
│  │  (anti-bot detection evasion)        ││
│  └──────────────────────────────────────┘│
└──────────────────────────────────────────┘

# Clone and install
git clone https://github.com/YOUR_USERNAME/xengager-mcp.git
cd xengager-mcp
bun install

# Configure credentials
cp .env.example .env
# Edit .env — paste your X_AUTH_TOKEN and X_CT0 values

# Run (stdio transport — for local MCP integration)
bun run stdio

# Or run as HTTP server (for remote/Cloudflare Tunnel setups)
bun run start

# With Cloudflare Tunnel (public MCP endpoint, requires CLOUDFLARE_TUNNEL_TOKEN in .env)
docker compose up

# Without tunnel
docker compose up mcp

{
  "mcpServers": {
    "xengager": {
      "command": "bun",
      "args": ["run", "stdio"],
      "cwd": "/path/to/xengager-mcp"
    }
  }
}

{
  "mcpServers": {
    "xengager": {
      "type": "http",
      "url": "https://your-tunnel.yourdomain.com/mcp",
      "headers": {
        "Authorization": "Bearer your-mcp-api-key"
      }
    }
  }
}

"What's trending?"         → x_trends
"Search for AI news"       → x_search("AI news", tab: "top")
"Show me @OpenAI's tweets" → x_user_posts("OpenAI")
"Get my notifications"     → x_notifications
"Like and bookmark this"   → x_like(url) → x_bookmark(url)
"Post a thread"            → x_post_tweet(["Part 1", "Part 2", "Part 3"])

bun test