seo-gravity-mcp 1.0.2 → 1.2.0

package/dist/invariants/registry.js

@@ -0,0 +1,178 @@
+export const BUILTIN_INVARIANTS = [
+    {
+        id: 'INV-HTTP-200',
+        name: 'HTTP 200 Success Status',
+        description: 'Published routes must return HTTP 200 OK without 4xx client or 5xx server errors.',
+        category: 'http',
+        severity: 'critical',
+        scope: 'page',
+        expectedCondition: 'HTTP status code is 200 or intentional 3xx redirect',
+        failureEvidence: 'HTTP status returned 4xx or 5xx error.',
+        remediationGuide: 'Check route routing logic, fix broken redirect rules, or restore missing page handler.',
+        verificationMethod: 'Curl the URL and verify 200 OK header response.',
+        evaluate(ctx) {
+            const code = ctx.statusCode ?? 200;
+            const ok = code >= 200 && code < 400;
+            return {
+                satisfied: ok,
+                observedCondition: `HTTP status code: ${code}`,
+                evidence: ok ? 'Page returned healthy status code.' : `Page returned error status code: ${code}`
+            };
+        }
+    },
+    {
+        id: 'INV-CANONICAL-RESOLVES',
+        name: 'Canonical URL Declaration',
+        description: 'Indexable pages must explicitly declare a canonical master URL to prevent duplicate content indexation.',
+        category: 'canonical',
+        severity: 'high',
+        scope: 'page',
+        expectedCondition: 'Canonical tag (alternates.canonical or <link rel="canonical">) is declared',
+        failureEvidence: 'Canonical URL declaration is missing from page component/metadata.',
+        remediationGuide: 'Add alternates.canonical to export const metadata or insert <link rel="canonical"> in head.',
+        verificationMethod: 'Inspect rendered HTML <head> for valid <link rel="canonical">.',
+        evaluate(ctx) {
+            const has = Boolean(ctx.hasCanonical || ctx.extractedCanonical);
+            return {
+                satisfied: has,
+                observedCondition: has ? `Canonical declared (${ctx.extractedCanonical || 'present'})` : 'Canonical missing',
+                evidence: has ? 'Canonical tag present.' : 'No canonical tag found.'
+            };
+        }
+    },
+    {
+        id: 'INV-TITLE-PRESENT',
+        name: 'Search Snippet Title Metadata',
+        description: 'Pages must declare a descriptive, unique title for search engine result snippets.',
+        category: 'metadata',
+        severity: 'high',
+        scope: 'page',
+        expectedCondition: 'Title is declared in component metadata or <title> tag',
+        failureEvidence: 'Title tag or title export is missing.',
+        remediationGuide: 'Export title in page metadata or add <title> in component head.',
+        verificationMethod: 'Inspect page <title> in rendered DOM.',
+        evaluate(ctx) {
+            const has = Boolean(ctx.hasMetadata || ctx.extractedTitle);
+            return {
+                satisfied: has,
+                observedCondition: has ? `Title present ("${ctx.extractedTitle || 'Declared'}")` : 'Title missing',
+                evidence: has ? 'Title metadata defined.' : 'No title metadata found.'
+            };
+        }
+    },
+    {
+        id: 'INV-LINK-ACCESSIBLE',
+        name: 'Internal Link Reachability',
+        description: 'Published public pages must be accessible via internal links and must not be orphans.',
+        category: 'links',
+        severity: 'medium',
+        scope: 'crawl_graph',
+        expectedCondition: 'Incoming internal link count >= 1',
+        failureEvidence: 'Page has 0 incoming internal links from other crawlable routes.',
+        remediationGuide: 'Add navigation link or contextual internal links pointing to this route.',
+        verificationMethod: 'Run crawl graph analysis and verify incomingLinksCount > 0.',
+        evaluate(ctx) {
+            const count = ctx.incomingLinksCount ?? 1;
+            const ok = count > 0;
+            return {
+                satisfied: ok,
+                observedCondition: `Incoming link count: ${count}`,
+                evidence: ok ? 'Page is connected to internal crawl graph.' : 'Page is an orphan with 0 incoming links.'
+            };
+        }
+    },
+    {
+        id: 'INV-ROBOTS-ALLOWED',
+        name: 'Robots Configuration Present',
+        description: 'Project must provide robots.txt or robots.ts specifying crawl directives for search engines.',
+        category: 'robots',
+        severity: 'high',
+        scope: 'site_wide',
+        expectedCondition: 'robots.txt or robots.ts configuration file exists',
+        failureEvidence: 'No robots.txt or robots.ts configuration file detected.',
+        remediationGuide: 'Create public/robots.txt or app/robots.ts.',
+        verificationMethod: 'Check GET /robots.txt response.',
+        evaluate(ctx) {
+            const ok = Boolean(ctx.hasRobots);
+            return {
+                satisfied: ok,
+                observedCondition: ok ? 'Robots configuration detected' : 'Robots configuration missing',
+                evidence: ok ? 'robots.txt configuration present.' : 'No robots.txt found.'
+            };
+        }
+    },
+    {
+        id: 'INV-SITEMAP-PRESENT',
+        name: 'XML Sitemap Configuration Present',
+        description: 'Project must generate or publish an XML sitemap to ensure full discovery of published routes.',
+        category: 'robots',
+        severity: 'high',
+        scope: 'site_wide',
+        expectedCondition: 'sitemap.xml or sitemap.ts configuration exists',
+        failureEvidence: 'No sitemap configuration file detected.',
+        remediationGuide: 'Create public/sitemap.xml or app/sitemap.ts.',
+        verificationMethod: 'Check GET /sitemap.xml response.',
+        evaluate(ctx) {
+            const ok = Boolean(ctx.hasSitemap);
+            return {
+                satisfied: ok,
+                observedCondition: ok ? 'Sitemap configuration detected' : 'Sitemap configuration missing',
+                evidence: ok ? 'sitemap.xml configuration present.' : 'No sitemap.xml found.'
+            };
+        }
+    },
+    {
+        id: 'INV-LLMS-TXT',
+        name: 'AI Agent Context File (/llms.txt)',
+        description: 'Site should provide /llms.txt for AI search engine documentation and knowledge synthesis.',
+        category: 'ai_readiness',
+        severity: 'medium',
+        scope: 'site_wide',
+        expectedCondition: 'public/llms.txt exists',
+        failureEvidence: 'No /llms.txt found.',
+        remediationGuide: 'Generate /llms.txt using seo_llms_txt_generate.',
+        verificationMethod: 'Check GET /llms.txt response.',
+        evaluate(ctx) {
+            const ok = Boolean(ctx.hasLlmsTxt);
+            return {
+                satisfied: ok,
+                observedCondition: ok ? '/llms.txt present' : '/llms.txt missing',
+                evidence: ok ? '/llms.txt file detected.' : 'No /llms.txt found.'
+            };
+        }
+    }
+];
+export class InvariantRegistry {
+    invariants = new Map();
+    constructor(initial = BUILTIN_INVARIANTS) {
+        for (const inv of initial) {
+            this.invariants.set(inv.id, inv);
+        }
+    }
+    register(invariant) {
+        this.invariants.set(invariant.id, invariant);
+    }
+    get(id) {
+        return this.invariants.get(id);
+    }
+    getAll() {
+        return Array.from(this.invariants.values());
+    }
+    evaluateContext(invariantId, context, provenance) {
+        const def = this.invariants.get(invariantId);
+        if (!def)
+            return null;
+        const res = def.evaluate(context);
+        return {
+            id: def.id,
+            logicalPageId: context.logicalPageId,
+            url: context.url,
+            description: def.description,
+            expectedCondition: def.expectedCondition,
+            observedCondition: res.observedCondition,
+            satisfied: res.satisfied,
+            provenance
+        };
+    }
+}
+export const defaultInvariantRegistry = new InvariantRegistry();

package/dist/invariants/types.d.ts

@@ -0,0 +1,38 @@
+import { SeverityLevel } from '../types/findings.js';
+export type InvariantScope = 'site_wide' | 'page' | 'route' | 'crawl_graph';
+export type InvariantCategory = 'http' | 'indexability' | 'canonical' | 'metadata' | 'links' | 'schema' | 'robots' | 'ai_readiness';
+export interface InvariantEvaluationContext {
+    url: string;
+    logicalPageId: string;
+    sourceFilePath?: string;
+    statusCode?: number;
+    hasMetadata?: boolean;
+    hasCanonical?: boolean;
+    isIndexable?: boolean;
+    hasSchema?: boolean;
+    hasRobots?: boolean;
+    hasSitemap?: boolean;
+    hasLlmsTxt?: boolean;
+    incomingLinksCount?: number;
+    extractedTitle?: string;
+    extractedCanonical?: string;
+    rawPayload?: any;
+}
+export interface InvariantEvaluationResult {
+    satisfied: boolean;
+    observedCondition: string;
+    evidence: string;
+}
+export interface InvariantDefinition {
+    id: string;
+    name: string;
+    description: string;
+    category: InvariantCategory;
+    severity: SeverityLevel;
+    scope: InvariantScope;
+    expectedCondition: string;
+    failureEvidence: string;
+    remediationGuide: string;
+    verificationMethod: string;
+    evaluate(context: InvariantEvaluationContext): InvariantEvaluationResult;
+}

package/dist/invariants/types.js

@@ -0,0 +1 @@
+export {};

package/dist/providers/providerRegistry.d.ts

@@ -0,0 +1,65 @@
+import { SERPProvider, PageSpeedProvider, KnowledgeProvider, IndexingProvider } from './types.js';
+export declare class NativeSerpProvider implements SERPProvider {
+    id: string;
+    name: string;
+    isFree: boolean;
+    analyzeSerp(query: string, country?: string, language?: string, numResults?: number): Promise<import("../types/seo.js").SerpAnalysisResponse>;
+}
+export declare class NativePageSpeedProvider implements PageSpeedProvider {
+    id: string;
+    name: string;
+    audit(url: string, strategy?: 'mobile' | 'desktop'): Promise<{
+        url: string;
+        strategy: string;
+        performanceScore: number;
+        coreWebVitals: {
+            lcp: {
+                value: string;
+                status: "Good" | "Needs Improvement" | "Poor";
+            };
+            fcp: {
+                value: string;
+                status: "Good" | "Needs Improvement" | "Poor";
+            };
+            cls: {
+                value: string;
+                status: "Good" | "Needs Improvement" | "Poor";
+            };
+            ttfb: {
+                value: string;
+                status: "Good" | "Needs Improvement" | "Poor";
+            };
+        };
+        topSpeedFixes: string[];
+    }>;
+}
+export declare class NativeKnowledgeProvider implements KnowledgeProvider {
+    id: string;
+    name: string;
+    extractEntities(text: string): Promise<import("../types/seo.js").EntitySalienceItem[]>;
+}
+export declare class NativeIndexingProvider implements IndexingProvider {
+    id: string;
+    name: string;
+    submitUrls(host: string, key: string, keyLocation: string, urls: string[]): Promise<{
+        status: "submitted" | "error";
+        statusCode: number;
+        message: string;
+        submittedUrlsCount: number;
+    }>;
+}
+export declare class ProviderRegistry {
+    private serpProvider;
+    private pageSpeedProvider;
+    private knowledgeProvider;
+    private indexingProvider;
+    getSerpProvider(): SERPProvider;
+    setSerpProvider(provider: SERPProvider): void;
+    getPageSpeedProvider(): PageSpeedProvider;
+    setPageSpeedProvider(provider: PageSpeedProvider): void;
+    getKnowledgeProvider(): KnowledgeProvider;
+    setKnowledgeProvider(provider: KnowledgeProvider): void;
+    getIndexingProvider(): IndexingProvider;
+    setIndexingProvider(provider: IndexingProvider): void;
+}
+export declare const defaultProviderRegistry: ProviderRegistry;

package/dist/providers/providerRegistry.js

@@ -0,0 +1,64 @@
+import { analyzeSerp } from '../tools/serp.js';
+import { auditPageSpeed, submitIndexNow } from '../tools/performance.js';
+import { mapEntitySalience } from '../tools/schema.js';
+export class NativeSerpProvider {
+    id = 'native_google_scraper';
+    name = 'Native Web SERP Scraper';
+    isFree = true;
+    async analyzeSerp(query, country = 'us', language = 'en', numResults = 10) {
+        return analyzeSerp(query, country, language, numResults);
+    }
+}
+export class NativePageSpeedProvider {
+    id = 'native_pagespeed';
+    name = 'Native Core Web Vitals Analyzer';
+    async audit(url, strategy = 'mobile') {
+        return auditPageSpeed(url, strategy);
+    }
+}
+export class NativeKnowledgeProvider {
+    id = 'native_nlp';
+    name = 'Native Entity Salience NLP Engine';
+    async extractEntities(text) {
+        const res = await mapEntitySalience(text);
+        return res.topEntities;
+    }
+}
+export class NativeIndexingProvider {
+    id = 'native_indexnow';
+    name = 'IndexNow Protocol Provider';
+    async submitUrls(host, key, keyLocation, urls) {
+        return submitIndexNow(host, key, keyLocation, urls);
+    }
+}
+export class ProviderRegistry {
+    serpProvider = new NativeSerpProvider();
+    pageSpeedProvider = new NativePageSpeedProvider();
+    knowledgeProvider = new NativeKnowledgeProvider();
+    indexingProvider = new NativeIndexingProvider();
+    getSerpProvider() {
+        return this.serpProvider;
+    }
+    setSerpProvider(provider) {
+        this.serpProvider = provider;
+    }
+    getPageSpeedProvider() {
+        return this.pageSpeedProvider;
+    }
+    setPageSpeedProvider(provider) {
+        this.pageSpeedProvider = provider;
+    }
+    getKnowledgeProvider() {
+        return this.knowledgeProvider;
+    }
+    setKnowledgeProvider(provider) {
+        this.knowledgeProvider = provider;
+    }
+    getIndexingProvider() {
+        return this.indexingProvider;
+    }
+    setIndexingProvider(provider) {
+        this.indexingProvider = provider;
+    }
+}
+export const defaultProviderRegistry = new ProviderRegistry();

package/dist/providers/types.d.ts

@@ -0,0 +1,22 @@
+import { SerpAnalysisResponse, PageSpeedAuditReport, EntitySalienceItem } from '../types/seo.js';
+export interface SERPProvider {
+    id: string;
+    name: string;
+    isFree: boolean;
+    analyzeSerp(query: string, country?: string, language?: string, numResults?: number): Promise<SerpAnalysisResponse>;
+}
+export interface PageSpeedProvider {
+    id: string;
+    name: string;
+    audit(url: string, strategy?: 'mobile' | 'desktop'): Promise<PageSpeedAuditReport>;
+}
+export interface KnowledgeProvider {
+    id: string;
+    name: string;
+    extractEntities(text: string): Promise<EntitySalienceItem[]>;
+}
+export interface IndexingProvider {
+    id: string;
+    name: string;
+    submitUrls(host: string, key: string, keyLocation: string, urls: string[]): Promise<any>;
+}

package/dist/providers/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/registry.d.ts

@@ -0,0 +1,3 @@
+import { Tool } from '@modelcontextprotocol/sdk/types.js';
+export declare const TOOLS: Tool[];
+export declare function executeTool(name: string, a: Record<string, any>): Promise<any>;