pagesight 0.9.0 → 0.10.0

package/README.md

@@ -8,93 +8,40 @@ See your site the way search engines and AI see it.
 npm install pagesight
 ```
 
-Most SEO tools flag "title over 60 characters" and "only one H1 allowed." [Google's own engineers say those rules don't exist.](#why-not-other-seo-tools) Pagesight skips the myths and goes to the sources.
+Google Search Console + PageSpeed Insights + CrUX + 139 AI crawlers. One package.
 
 ## Tools
 
-### `inspect`
-
-Ask Google: is this page indexed? What canonical did you choose? Any crawl errors? Structured data issues?
-
-Returns index status, canonical (yours vs Google's), crawl status, rich results validation, sitemaps, and referring URLs.
-
-### `pagespeed`
-
-Run Google Lighthouse on any URL:
-
-- **Scores**: performance, accessibility, best-practices, seo
-- **Core Web Vitals (lab)**: FCP, LCP, TBT, CLS, Speed Index, TTI
-- **CrUX field data**: real Chrome user metrics (page + origin)
-- **Opportunities**: ranked by severity with potential savings
-- **Strategy**: `mobile` or `desktop`
-
-### `crux`
-
-Real-world Core Web Vitals from Chrome users (28-day rolling window):
-
-- **Metrics**: LCP, FCP, INP, CLS, TTFB, RTT, navigation types, form factors
-- **Granularity**: by URL or origin, by device (DESKTOP, PHONE, TABLET)
-- **Data**: p75 values + histogram distributions
-
-### `crux_history`
-
-Core Web Vitals trends over time — up to 40 weekly data points (~10 months):
-
-- Trend detection (improved/stable/worse) with percentage change
-- Recent data points table for core metrics
-- Custom period count (1-40)
-
-### `performance`
-
-Google Search Console search analytics:
-
-- **Dimensions**: `query`, `page`, `country`, `device`, `date`, `searchAppearance`, `hour`
-- **Search types**: `web`, `image`, `video`, `news`, `discover`, `googleNews`
-- **Filters**: `equals`, `contains`, `notEquals`, `notContains`, `includingRegex`, `excludingRegex`
-- **Pagination**: up to 25,000 rows
-
-### `robots`
-
-Analyze any site's robots.txt:
-
-- **Syntax validation** per [RFC 9309](https://www.rfc-editor.org/rfc/rfc9309)
-- **AI crawler audit** — 139+ bots from the [ai-robots-txt](https://github.com/ai-robots-txt/ai.robots.txt) community registry
-- **Bot categories**: training scrapers, AI search crawlers, AI assistants, AI agents
-- **Per-bot status**: blocked or allowed, with the matched rule
+| Tool | What it does |
+|------|-------------|
+| `audit` | One-call site audit. Runs pagespeed + metatags + robots + sitemaps + inspect in parallel. Returns prioritized findings. |
+| `pagespeed` | Lighthouse scores, Core Web Vitals, opportunities with resource URLs, failing audits with selectors and fix links. |
+| `metatags` | OG, Twitter Card, canonical, JSON-LD with schema validation, redirect chain, image validation. |
+| `inspect` | Google index status, canonical choice, crawl state, rich results. |
+| `sample_inspect` | Sample URLs from a sitemap and batch-inspect via GSC. Diagnoses indexing patterns. |
+| `performance` | Search analytics — clicks, impressions, CTR, position. `compare: true` for period-over-period deltas. |
+| `crux` | Real-world Core Web Vitals from Chrome users (p75, histograms). |
+| `crux_history` | CWV trends over time — up to 40 weekly data points. |
+| `robots` | robots.txt validation (RFC 9309) + AI crawler audit (139+ bots). |
+| `sitemaps` | GSC properties and sitemaps with submitted/indexed counts. |
+| `setup` | Auth status and OAuth setup. |
 
 ```
-=== robots.txt: https://www.nytimes.com ===
-AI Crawlers: 35 blocked, 104 allowed (of 139 known)
-
-  BLOCKED  GPTBot (OpenAI) — GPT model training
-  BLOCKED  ClaudeBot (Anthropic) — Claude model training
-  ALLOWED  Claude-User (Anthropic) — User-initiated fetching
+=== Site Audit: https://fipe.chat ===
+
+HIGH    Missing canonical URL
+HIGH    7,772 sitemap URLs submitted, 0 indexed
+MEDIUM  Missing og:image — no social preview image
+MEDIUM  Accessibility score: 89/100
+LOW     Missing Twitter Card tags
+LOW     No structured data (JSON-LD) found
 ```
 
-### `sitemaps`
-
-Search Console properties and sitemaps (read-only):
-
-- `list_sites` — all properties with permission level
-- `get_site` — details for a specific property
-- `list_sitemaps` — sitemaps with error/warning counts
-- `get_sitemap` — full details for a specific sitemap
-
-### `setup`
-
-Check auth status or walk through OAuth interactively.
-
 ## Setup
 
-### 1. Google Cloud project
-
-1. Go to [Google Cloud Console](https://console.cloud.google.com/)
-2. Create a project (or use existing)
-3. Enable: **Search Console API**, **PageSpeed Insights API**, **Chrome UX Report API**
-4. Create **OAuth client ID** (Desktop app) — for Search Console
-5. Create **API key** — for PageSpeed and CrUX
-
-### 2. Configure
+1. [Google Cloud Console](https://console.cloud.google.com/) — enable Search Console API, PageSpeed Insights API, Chrome UX Report API
+2. Create OAuth client ID (Desktop app) + API key
+3. Configure:
 
 ```env
 GSC_CLIENT_ID=your-client-id.apps.googleusercontent.com
@@ -103,16 +50,16 @@ GSC_REFRESH_TOKEN=your-refresh-token
 GOOGLE_API_KEY=your-api-key
 ```
 
-The `robots` tool works without any credentials.
+`robots`, `metatags`, and `pagespeed` work without credentials.
 
-### 3. Use with your AI assistant
+### MCP config
 
 ```json
 {
   "mcpServers": {
     "pagesight": {
-      "command": "bun",
-      "args": ["run", "/path/to/pagesight/src/index.ts"],
+      "command": "npx",
+      "args": ["pagesight"],
       "env": {
         "GSC_CLIENT_ID": "your-client-id",
         "GSC_CLIENT_SECRET": "your-secret",
@@ -124,36 +71,15 @@ The `robots` tool works without any credentials.
 }
 ```
 
-Then just ask:
-
-```
-"Is https://mysite.com indexed?"
-"Run pagespeed on my homepage"
-"Which AI crawlers can access my site?"
-"How have my Core Web Vitals changed?"
-"Which queries bring traffic to this page?"
-```
-
 ## Why not other SEO tools?
 
 We checked every common SEO "rule" against official Google documentation:
 
-- **"Title must be under 60 characters"** — Google: "there's no limit." Gary Illyes: "an externally made-up metric."
-- **"Meta description must be 155 characters"** — Google: "there's no limit on how long a meta description can be."
-- **"Only one H1 per page"** — John Mueller: "You can use H1 tags as often as you want. There's no limit."
-- **"Minimum 300 words per page"** — Mueller: "the number of words on a page is not a quality factor."
-- **"Text-to-HTML ratio matters"** — Mueller: "it makes absolutely no sense at all for SEO."
+- **"Title must be under 60 characters"** — Gary Illyes: "an externally made-up metric."
+- **"Only one H1 per page"** — John Mueller: "You can use H1 tags as often as you want."
+- **"Minimum 300 words per page"** — Mueller: "not a quality factor."
 
-Tools that flag these are reporting their opinions. Pagesight only reports what the sources actually return.
-
-## Development
-
-```bash
-bun install
-bun run start     # start server
-bun run lint      # biome check
-bun run format    # biome format
-```
+Pagesight only reports what the sources actually return.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pagesight",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "See your site the way search engines and AI see it.",
   "keywords": [
     "seo",

package/src/tools/pagespeed.ts

@@ -91,7 +91,7 @@ function formatOpportunities(audits: Record<string, PsiAudit>): string[] {
 }
 
 function formatDiagnostics(audits: Record<string, PsiAudit>): string[] {
-  const failing: Array<{ title: string; displayValue: string }> = [];
+  const failing: PsiAudit[] = [];
 
   for (const audit of Object.values(audits)) {
     if (
@@ -100,15 +100,31 @@ function formatDiagnostics(audits: Record<string, PsiAudit>): string[] {
       (audit.scoreDisplayMode === "numeric" || audit.scoreDisplayMode === "metricSavings") &&
       audit.displayValue
     ) {
-      failing.push({ title: audit.title, displayValue: audit.displayValue });
+      failing.push(audit);
     }
   }
 
   if (failing.length === 0) return [];
 
+  failing.sort((a, b) => (a.score ?? 0) - (b.score ?? 0));
+
   const lines: string[] = ["--- Diagnostics ---", ""];
-  for (const item of failing.slice(0, 10)) {
-    lines.push(`${item.title}: ${item.displayValue}`);
+  for (const audit of failing.slice(0, 10)) {
+    lines.push(`${audit.title}: ${audit.displayValue}`);
+
+    const linkMatch = audit.description?.match(/\[.*?\]\((https?:\/\/[^)]+)\)/);
+    if (linkMatch) lines.push(`  Learn more: ${linkMatch[1]}`);
+
+    const items = audit.details?.items;
+    if (items && items.length > 0) {
+      for (const item of items.slice(0, 3)) {
+        lines.push(...formatDetailItem(item));
+      }
+      if (items.length > 3) {
+        lines.push(`  ... and ${items.length - 3} more`);
+      }
+    }
+    lines.push("");
   }
 
   return lines;