# CLAUDE.md

## Overview

Google Search Console data retriever: search analytics (rankings, CTR, impressions), sitemap status, and index coverage.

## Quick Start

```bash
pip install -r scripts/requirements.txt

# Requires service account credentials
# ~/.credential/ourdigital-seo-agent.json

python scripts/gsc_client.py --site sc-domain:example.com --action summary
```

## Scripts

| Script | Purpose |
|--------|---------|
| `gsc_client.py` | Search Console API client |
| `base_client.py` | Shared utilities |

## Configuration

Service account setup:
```bash
# Credentials file location
~/.credential/ourdigital-seo-agent.json

# Add service account email to GSC property as user
ourdigital-seo-agent@ourdigital-insights.iam.gserviceaccount.com
```

## Usage

```bash
# Performance summary (last 28 days)
python scripts/gsc_client.py --site sc-domain:example.com --action summary

# Query-level data
python scripts/gsc_client.py --site sc-domain:example.com --action queries --limit 100

# Page-level data
python scripts/gsc_client.py --site sc-domain:example.com --action pages

# Custom date range
python scripts/gsc_client.py --site sc-domain:example.com --action queries \
  --start 2024-01-01 --end 2024-01-31

# Sitemap status
python scripts/gsc_client.py --site sc-domain:example.com --action sitemaps

# JSON output
python scripts/gsc_client.py --site sc-domain:example.com --action summary --json
```

## Actions

| Action | Description |
|--------|-------------|
| `summary` | Overview metrics (clicks, impressions, CTR, position) |
| `queries` | Top search queries |
| `pages` | Top pages by clicks |
| `sitemaps` | Sitemap submission status |
| `coverage` | Index coverage issues |

## Output: Summary

```json
{
  "site": "sc-domain:example.com",
  "date_range": "2024-01-01 to 2024-01-28",
  "totals": {
    "clicks": 15000,
    "impressions": 500000,
    "ctr": 3.0,
    "position": 12.5
  }
}
```

## Output: Queries

```json
{
  "queries": [
    {
      "query": "keyword",
      "clicks": 500,
      "impressions": 10000,
      "ctr": 5.0,
      "position": 3.2
    }
  ]
}
```

## Rate Limits

| Limit | Value |
|-------|-------|
| Queries per minute | 1,200 |
| Rows per request | 25,000 |

## Site Property Formats

| Format | Example |
|--------|---------|
| Domain property | `sc-domain:example.com` |
| URL prefix | `https://www.example.com/` |

## Dependencies

```
google-api-python-client>=2.100.0
google-auth>=2.23.0
python-dotenv>=1.0.0
rich>=13.7.0
pandas>=2.1.0
```

## Notion Output (Required)

**IMPORTANT**: All audit reports MUST be saved to the OurDigital SEO Audit Log database.

### Database Configuration

| Field | Value |
|-------|-------|
| Database ID | `2c8581e5-8a1e-8035-880b-e38cefc2f3ef` |
| URL | https://www.notion.so/dintelligence/2c8581e58a1e8035880be38cefc2f3ef |

### Required Properties

| Property | Type | Description |
|----------|------|-------------|
| Issue | Title | Report title (Korean + date) |
| Site | URL | Audited website URL |
| Category | Select | Technical SEO, On-page SEO, Performance, Schema/Structured Data, Sitemap, Robots.txt, Content, Local SEO |
| Priority | Select | Critical, High, Medium, Low |
| Found Date | Date | Audit date (YYYY-MM-DD) |
| Audit ID | Rich Text | Format: [TYPE]-YYYYMMDD-NNN |

### Language Guidelines

- Report content in Korean (한국어)
- Keep technical English terms as-is (e.g., SEO Audit, Core Web Vitals, Schema Markup)
- URLs and code remain unchanged

### Example MCP Call

```bash
mcp-cli call notion/API-post-page '{"parent": {"database_id": "2c8581e5-8a1e-8035-880b-e38cefc2f3ef"}, "properties": {...}}'
```