pagesight 0.7.0 → 0.9.0

package/package.json

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

package/src/tools/metatags.ts

@@ -134,6 +134,189 @@ function formatJsonLd(data: unknown, indent = 0): string[] {
   return lines;
 }
 
+// --- Structured data validation (per Google Rich Results docs) ---
+
+interface SchemaRule {
+  required: string[];
+  recommended: string[];
+  imageFields: string[];
+}
+
+// Required/recommended fields sourced from Google's Rich Results documentation
+// https://developers.google.com/search/docs/appearance/structured-data
+const SCHEMA_RULES: Record<string, SchemaRule> = {
+  WebSite: {
+    required: ["name", "url"],
+    recommended: ["potentialAction"],
+    imageFields: [],
+  },
+  Organization: {
+    required: ["name", "url"],
+    recommended: ["logo", "sameAs", "contactPoint"],
+    imageFields: ["logo"],
+  },
+  Article: {
+    required: ["headline", "image", "datePublished", "author"],
+    recommended: ["dateModified", "publisher"],
+    imageFields: ["image"],
+  },
+  NewsArticle: {
+    required: ["headline", "image", "datePublished", "author"],
+    recommended: ["dateModified", "publisher"],
+    imageFields: ["image"],
+  },
+  Product: {
+    required: ["name", "image"],
+    recommended: ["description", "offers", "brand", "review", "aggregateRating"],
+    imageFields: ["image"],
+  },
+  LocalBusiness: {
+    required: ["name", "address"],
+    recommended: ["telephone", "openingHoursSpecification", "image", "url"],
+    imageFields: ["image"],
+  },
+  FAQPage: {
+    required: ["mainEntity"],
+    recommended: [],
+    imageFields: [],
+  },
+  BreadcrumbList: {
+    required: ["itemListElement"],
+    recommended: [],
+    imageFields: [],
+  },
+  Event: {
+    required: ["name", "startDate", "location"],
+    recommended: ["endDate", "image", "description", "offers", "organizer"],
+    imageFields: ["image"],
+  },
+  Recipe: {
+    required: ["name", "image"],
+    recommended: ["author", "datePublished", "description", "recipeIngredient", "recipeInstructions"],
+    imageFields: ["image"],
+  },
+  VideoObject: {
+    required: ["name", "description", "thumbnailUrl", "uploadDate"],
+    recommended: ["duration", "contentUrl", "embedUrl"],
+    imageFields: ["thumbnailUrl"],
+  },
+};
+
+interface ValidationIssue {
+  type: string;
+  level: "required" | "recommended";
+  field: string;
+}
+
+function getNestedValue(obj: Record<string, unknown>, field: string): unknown {
+  const val = obj[field];
+  if (val !== undefined && val !== null && val !== "") return val;
+  // Check if it's a nested object with a value (e.g., logo might be {url: "..."} or a string)
+  if (typeof val === "object" && val !== null) return val;
+  return undefined;
+}
+
+function validateJsonLd(blocks: unknown[]): { issues: ValidationIssue[]; imageUrls: string[] } {
+  const issues: ValidationIssue[] = [];
+  const imageUrls: string[] = [];
+
+  function validateBlock(data: unknown) {
+    if (Array.isArray(data)) {
+      for (const item of data) validateBlock(item);
+      return;
+    }
+    if (!data || typeof data !== "object") return;
+
+    const obj = data as Record<string, unknown>;
+    const rawType = obj["@type"];
+    const types = Array.isArray(rawType) ? rawType : rawType ? [rawType] : [];
+
+    for (const type of types) {
+      const rule = SCHEMA_RULES[String(type)];
+      if (!rule) continue;
+
+      for (const field of rule.required) {
+        if (getNestedValue(obj, field) === undefined) {
+          issues.push({ type: String(type), level: "required", field });
+        }
+      }
+
+      for (const field of rule.recommended) {
+        if (getNestedValue(obj, field) === undefined) {
+          issues.push({ type: String(type), level: "recommended", field });
+        }
+      }
+
+      // Collect image URLs for validation
+      for (const field of rule.imageFields) {
+        const val = obj[field];
+        if (typeof val === "string" && val.startsWith("http")) {
+          imageUrls.push(val);
+        } else if (val && typeof val === "object") {
+          const nested = val as Record<string, unknown>;
+          const url = nested.url ?? nested.contentUrl;
+          if (typeof url === "string" && url.startsWith("http")) {
+            imageUrls.push(url);
+          }
+        }
+      }
+    }
+
+    // Recurse into nested objects
+    for (const val of Object.values(obj)) {
+      if (val && typeof val === "object" && !Array.isArray(val)) {
+        const nested = val as Record<string, unknown>;
+        if (nested["@type"]) validateBlock(nested);
+      }
+    }
+  }
+
+  for (const block of blocks) validateBlock(block);
+  return { issues, imageUrls };
+}
+
+// What each recommended field enables (sourced from Google Rich Results docs)
+const FIELD_HINTS: Record<string, string> = {
+  "WebSite.potentialAction": "enables sitelinks searchbox",
+  "Organization.logo": "appears in knowledge panel",
+  "Organization.contactPoint": "may appear in knowledge panel",
+  "Organization.sameAs": "links social profiles in knowledge panel",
+  "Article.dateModified": "shows freshness in search results",
+  "Article.publisher": "required for some article rich results",
+  "Product.offers": "enables price display in search",
+  "Product.review": "enables star ratings in search",
+  "Product.aggregateRating": "enables aggregate star ratings",
+  "Product.brand": "shown in product rich results",
+  "LocalBusiness.openingHoursSpecification": "shows business hours in maps",
+  "LocalBusiness.image": "shown in local pack results",
+  "Event.image": "shown in event rich results",
+  "Event.offers": "shows ticket prices in search",
+  "Recipe.author": "shown in recipe rich results",
+  "VideoObject.duration": "shown in video rich results",
+};
+
+function formatValidation(issues: ValidationIssue[]): string[] {
+  if (issues.length === 0) return ["All validated types have their required fields."];
+
+  const lines: string[] = [];
+  const required = issues.filter((i) => i.level === "required");
+  const recommended = issues.filter((i) => i.level === "recommended");
+
+  if (required.length > 0) {
+    for (const i of required) {
+      lines.push(`MISSING  ${i.type}.${i.field} (required for Rich Results)`);
+    }
+  }
+  if (recommended.length > 0) {
+    for (const i of recommended) {
+      const hint = FIELD_HINTS[`${i.type}.${i.field}`];
+      lines.push(`OPTIONAL ${i.type}.${i.field}${hint ? ` — ${hint}` : ""}`);
+    }
+  }
+
+  return lines;
+}
+
 interface RedirectHop {
   url: string;
   status: number;
@@ -381,6 +564,31 @@ export function registerMetatagsTool(server: McpServer): void {
           }
         }
 
+        // Structured data validation
+        if (parsed.jsonLd.length > 0) {
+          const { issues, imageUrls } = validateJsonLd(parsed.jsonLd);
+          if (issues.length > 0 || imageUrls.length > 0) {
+            output.push("", "--- Structured Data Validation ---", "");
+            output.push(...formatValidation(issues));
+
+            // HEAD-check image URLs from structured data
+            if (imageUrls.length > 0) {
+              const deduped = [...new Set(imageUrls)];
+              const imgChecks = await Promise.all(deduped.map((u) => checkImage(u, "schema")));
+              for (const check of imgChecks) {
+                if (check.error) {
+                  output.push(`BROKEN   Image: ${check.url} — ${check.error}`);
+                } else if (check.status && check.status >= 400) {
+                  output.push(`BROKEN   Image: ${check.url} — HTTP ${check.status}`);
+                } else {
+                  const sizeKB = check.contentLength ? Math.round(check.contentLength / 1024) : null;
+                  output.push(`OK       Image: ${check.url}${sizeKB ? ` (${sizeKB} KB)` : ""}`);
+                }
+              }
+            }
+          }
+        }
+
         return {
           content: [{ type: "text", text: output.join("\n") }],
         };