You: "Where do we rank for 'best mcp servers' and how's our traffic this month?"

Claude: Let me check... [calls rank_check + analytics_overview]

  Rankings:
  - "best mcp servers" → #7 (up from #12 last week)
  - "mcp server tools" → #3

  Traffic (last 28 days):
  - Sessions: 4,231 (+18% vs previous period)
  - Top source: Organic Search (62%)
  - Bounce rate: 34% (good)

# 1. Clone and install
git clone https://github.com/itsjwill/seoctopus.git
cd seoctopus
npm install

# 2. Build
npm run build

# 3. Install browser for rank tracking
npx playwright install chromium

{
  "mcpServers": {
    "seoctopus": {
      "command": "node",
      "args": ["/path/to/seoctopus/dist/index.js"]
    }
  }
}

# One-time OAuth2 setup (requires Google Cloud project)
npx seoctopus auth setup -c /path/to/credentials.json

# Check where you rank
seoctopus rank check "best seo tools" "mcp server" -d example.com

# Full page audit
seoctopus audit page https://example.com

# Content analysis with keyword targeting
seoctopus audit content https://example.com -k "target keyword"

# Core Web Vitals check
seoctopus perf cwv https://example.com

# Keyword opportunities from Search Console
seoctopus keywords gaps -s https://example.com

# Generate HTML report
seoctopus report https://example.com -f html -o report.html

# Calculate OctoScore
seoctopus score https://example.com -k "target keyword"

# Competitor deep dive
seoctopus compete analyze "target keyword" -u https://yoursite.com

# Rank tracking
seoctopus rank check <keywords...> -d <domain> [-c country] [--device desktop|mobile]
seoctopus rank history -d <domain> [-k keywords...] [--days 30]

# SEO auditing
seoctopus audit page <url>
seoctopus audit site <url> [-p maxPages] [-d depth]
seoctopus audit content <url> [-k keyword]
seoctopus audit links <url> [-e checkExternal]

# Performance
seoctopus perf audit <url> [--device mobile|desktop]
seoctopus perf cwv <url> [-s mobile|desktop]
seoctopus perf compare <url1> <url2> [url3...] [--device mobile|desktop]

# Google Analytics
seoctopus analytics overview -p <propertyId> [--date last28days] [--compare previousPeriod]
seoctopus analytics pages -p <propertyId> [--sort pageviews|engagement|bounceRate|conversions]
seoctopus analytics realtime -p <propertyId>

# Keywords
seoctopus keywords gsc -s <siteUrl> [--sort clicks|impressions|ctr|position]
seoctopus keywords suggest <seed> [-c country]
seoctopus keywords gaps -s <siteUrl> [--min-impressions 100] [--max-position 20]
seoctopus keywords cluster <keyword1> <keyword2> [keyword3...]

# Competitive
seoctopus compete analyze <keyword> [-u yourUrl] [-n numCompetitors]
seoctopus compete gap <yourUrl> <competitorUrl1> [competitorUrl2...]
seoctopus compete share <keyword1> [keyword2...] -d <domain>

# Scoring & Reports
seoctopus score <url> [-k keyword] [-p ga4PropertyId]
seoctopus report <url> [-k keyword] [-f json|markdown|html] [-o outputFile]

# Auth & Config
seoctopus auth setup -c <credentialsFile>
seoctopus auth status
seoctopus config [--set key=value] [--get key]

seoctopus/
├── src/
│   ├── index.ts                    # MCP server entry (stdio transport)
│   ├── server.ts                   # 23 tool definitions with Zod schemas
│   ├── cli.ts                      # Full CLI with Commander
│   ├── auth/google.ts              # OAuth2 with auto token refresh
│   ├── data/store.ts               # SQLite (WAL mode) for history
│   ├── modules/
│   │   ├── rank-tracker/           # Playwright + anti-detection + SERP parsing
│   │   ├── analytics/              # GA4 Data API + Admin API + Realtime
│   │   ├── auditor/                # On-page, content, links, schema, crawler
│   │   ├── keywords/               # Search Console + autocomplete + clustering
│   │   ├── competitive/            # Competitor analysis + content gaps + SERP share
│   │   └── performance/            # Lighthouse + PageSpeed Insights + CWV
│   ├── scoring/                    # OctoScore: weights, grader, recommendations
│   ├── reports/                    # JSON, Markdown, HTML (dark theme) formatters
│   └── utils/                      # Config (Conf), logging, rate limiter
├── bin/seoctopus.ts                # CLI executable entry
├── tsup.config.ts                  # Dual-entry build (MCP + CLI)
└── package.json

npm run dev          # Watch mode (auto-rebuild on changes)
npm run typecheck    # TypeScript strict mode check
npm run lint         # ESLint
npm run format       # Prettier
npm run test         # Vitest