Create site_stats repo: standalone multi-site GA4 analytics service (MCP + HTTP)

[chedong]

Context

GA4 analytics was originally scoped as a phpMan MCP tool (v4.10 design). That was rejected on 2026-07-14 — site analytics is a multi-site concern that doesn't belong in a documentation server.

Goal

Standalone site_stats Python service exposing categorized reports (栏目) for any number of websites over MCP + HTTP. phpMan is one of many consumers, not the primary user.

Layout

site_stats/
├── src/site_stats/
│   ├── server.py                 # FastAPI app
│   ├── mcp_server.py             # MCP tool registration
│   ├── data_sources/
│   │   ├── base.py               # DataSource ABC
│   │   ├── ga4.py                # GA4 (v1)
│   │   └── plausible.py          # (future, pluggable)
│   ├── reports/
│   │   ├── traffic.py, content.py, users.py,
│   │   ├── sources.py, releases.py, anomalies.py, search.py
│   ├── auth/ga_jwt.py            # pure Python JWT (~80 lines)
│   └── cache/filesystem.py       # 10-min file cache
├── config/sites.yaml             # multi-property registry
└── deploy/systemd/site-stats.service

MCP tools (4)

• site_list() — list registered sites
• site_report(site_id, category, start_date, end_date, metrics, dimensions, order_by, limit) — categorized report
• site_compare(site_id, category, period_a, period_b) — period-over-period deltas
• site_release_impact(site_id, event_time, window_hours) — before/after a deploy

Report categories (栏目)

traffic | content | users | sources | releases | anomalies | search

phpMan integration (optional, 5 lines)

$stats = @file_get_contents("https://stats.example.com/api/v1/sites/chedong-phpman/reports/content?startDate=7daysAgo&endDate=today&metrics=screenPageViews&dimensions=pagePath&limit=10");
if ($stats !== false) foreach (json_decode($stats, true)['rows'] ?? [] as $r) renderPopularPage($r['pagePath'], $r['screenPageViews']);

phpMan has no other knowledge of this service. If removed, phpMan keeps working.

What moves to site_stats

From	To
docs/06-ANALYTICS.md (full design)	site_stats/docs/DESIGN.md (verbatim)
(no existing code)	full greenfield implementation
GA4 config keys (proposed but never added to phpman.config.php)	site_stats/config/sites.yaml

phpMan contributes zero code to site_stats. Only the design doc moves.

Steps (Phase E from docs/05-PLAN.md §3, week 3-4)

1. W3: FastAPI skeleton + /sites endpoint
2. W3: GA4 JWT auth + runReport() client
3. W3: Implement 7 report categories
4. W3: MCP tool registration
5. W4: Multi-property config, filesystem cache, systemd deploy

Tech: Python (not PHP)

• GA4 SDK + MCP tooling more mature in Python
• Different release cadence, failure domain from phpMan
• Operator already has Python for LLM tools — one more service in same language

Related

• Full design: docs/06-ANALYTICS.md
• Companion issue: Create llm_enhance repo: extract LLM enhancement from phpMan with Source/Transform/Sink abstraction #222 (llm_enhance repo)
• See companion issue for phpMan v5.0 cleanup.