seo-gravity-mcp 1.0.0

package/dist/types/seo.d.ts

@@ -0,0 +1,354 @@
+export interface SerpResultItem {
+    rank: number;
+    title: string;
+    url: string;
+    snippet: string;
+    displayedBreadcrumbs?: string;
+    isFeaturedSnippet?: boolean;
+}
+export interface SerpAnalysisResponse {
+    query: string;
+    totalResultsFound?: string;
+    organicResults: SerpResultItem[];
+    peopleAlsoAsk: string[];
+    relatedSearches: string[];
+    serpFeaturesDetected: string[];
+}
+export interface CompetitorPageProfile {
+    url: string;
+    title: string;
+    description: string;
+    h1: string[];
+    h2: string[];
+    h3: string[];
+    h4: string[];
+    wordCount: number;
+    readingTimeMinutes: number;
+    readingGradeLevel: string;
+    schemasFound: string[];
+    canonical: string;
+    robotsDirectives: string;
+    openGraph: Record<string, string>;
+    imageCount: number;
+    imagesMissingAlt: number;
+    internalLinksCount: number;
+    externalLinksCount: number;
+}
+export interface ContentGapAnalysis {
+    targetUrlOrKeyword: string;
+    analyzedCompetitors: string[];
+    averageCompetitorWordCount: number;
+    targetWordCount: number;
+    wordCountDelta: number;
+    missingEntities: Array<{
+        term: string;
+        competitorFrequency: number;
+        targetFrequency: number;
+        importance: 'high' | 'medium' | 'low';
+    }>;
+    headingCoverageGaps: Array<{
+        subtopic: string;
+        coveredByCompetitorUrls: string[];
+    }>;
+    suggestedActionItems: string[];
+}
+export interface CompetitorDiffMatrix {
+    myUrl: string;
+    competitorUrl: string;
+    focusKeyword: string;
+    scorecard: Array<{
+        metric: string;
+        myValue: string | number;
+        competitorValue: string | number;
+        winner: 'my_site' | 'competitor' | 'tie';
+        notes: string;
+    }>;
+    summary: {
+        myScore: number;
+        competitorScore: number;
+        winner: 'my_site' | 'competitor' | 'tie';
+        topPriorityFixes: string[];
+    };
+}
+export interface ForumDiscussionsPulse {
+    topic: string;
+    rankingDiscussions: Array<{
+        platform: 'Reddit' | 'Quora' | 'Other Forum';
+        title: string;
+        url: string;
+        snippet: string;
+    }>;
+    extractedThemes: string[];
+    frequentUserPainPoints: string[];
+    consensusRecommendations: string[];
+}
+export interface GeoAiReadinessReport {
+    targetQuery: string;
+    overallGeoScore: number;
+    citationLikelihood: 'High' | 'Medium' | 'Low';
+    checks: {
+        directAnswerParagraph: {
+            passed: boolean;
+            score: number;
+            feedback: string;
+            detectedSnippet?: string;
+        };
+        semanticChunking: {
+            passed: boolean;
+            score: number;
+            feedback: string;
+        };
+        structuredDataAndLists: {
+            passed: boolean;
+            score: number;
+            feedback: string;
+        };
+        authoritativeCitationsAndStats: {
+            passed: boolean;
+            score: number;
+            feedback: string;
+            detectedStatsCount: number;
+        };
+        entityClarity: {
+            passed: boolean;
+            score: number;
+            feedback: string;
+        };
+    };
+    recommendedSnippetsForAiCitation: Array<{
+        section: string;
+        suggestedFormat: string;
+        exampleText: string;
+    }>;
+}
+export interface InformationGainReport {
+    targetKeyword: string;
+    informationGainScore: number;
+    noveltyTier: 'Exceptional (High Information Gain)' | 'Moderate' | 'Low (Rehashed / Generic AI Risk)';
+    uniqueEntitiesDetected: string[];
+    competitorOverlapPercentage: number;
+    originalElementsFound: {
+        dataPointsAndStats: string[];
+        caseStudiesOrExamples: string[];
+        uniqueMethodologiesOrQuotes: string[];
+    };
+    recommendationsToIncreaseGain: string[];
+}
+export interface EeatAuditReport {
+    overallEeatScore: number;
+    trustLevel: 'High Authority' | 'Moderate' | 'Needs Improvement';
+    signals: {
+        authorIdentity: {
+            hasAuthorByline: boolean;
+            hasAuthorBio: boolean;
+            hasPersonSchema: boolean;
+            sameAsProfilesLinked: string[];
+        };
+        transparency: {
+            hasEditorialPolicy: boolean;
+            hasFactCheckDisclaimer: boolean;
+            hasPublishDate: boolean;
+            hasModifiedDate: boolean;
+        };
+        contactAndEntity: {
+            hasAboutPageLink: boolean;
+            hasContactInfo: boolean;
+            hasPhysicalAddress: boolean;
+        };
+        citationsAndReferences: {
+            externalAuthoritativeCitationsCount: number;
+            peerReviewedOrGovLinksCount: number;
+        };
+    };
+    actionableImprovements: string[];
+}
+export interface OnPageAuditReport {
+    urlOrTitle: string;
+    focusKeyword?: string;
+    overallScore: number;
+    titleAudit: {
+        text: string;
+        characterCount: number;
+        estimatedPixelWidth: number;
+        status: 'optimal' | 'too_short' | 'too_long';
+        containsKeyword: boolean;
+        recommendation?: string;
+    };
+    metaDescriptionAudit: {
+        text: string;
+        characterCount: number;
+        status: 'optimal' | 'too_short' | 'too_long' | 'missing';
+        containsKeyword: boolean;
+        hasCallToAction: boolean;
+        recommendation?: string;
+    };
+    headingsAudit: {
+        h1Count: number;
+        h1Texts: string[];
+        h2Count: number;
+        h3Count: number;
+        hierarchyValid: boolean;
+        keywordInH1: boolean;
+        keywordInH2: boolean;
+        issues: string[];
+    };
+    contentBodyAudit: {
+        wordCount: number;
+        keywordOccurrences: number;
+        keywordDensityPercent: number;
+        keywordInFirst100Words: boolean;
+        readabilityGrade: string;
+    };
+    imagesAudit: {
+        totalImages: number;
+        missingAltCount: number;
+        imagesWithAltCount: number;
+        suspiciouslyLargeImages: string[];
+    };
+    linksAudit: {
+        internalLinksCount: number;
+        externalLinksCount: number;
+        genericAnchorTextsFound: string[];
+    };
+    urlSlugAudit: {
+        slug: string;
+        hasStopWords: boolean;
+        containsKeyword: boolean;
+        status: 'optimal' | 'warning';
+    };
+}
+export interface ContentBrief {
+    primaryKeyword: string;
+    secondaryKeywords: string[];
+    searchIntent: 'Informational' | 'Transactional' | 'Commercial Investigation' | 'Navigational';
+    recommendedWordCount: {
+        min: number;
+        target: number;
+        max: number;
+    };
+    recommendedTitleFormulas: string[];
+    recommendedMetaDescriptions: string[];
+    headingOutline: Array<{
+        level: 'H1' | 'H2' | 'H3';
+        text: string;
+        intentNotes: string;
+        suggestedEntitiesToMention: string[];
+    }>;
+    requiredSemanticEntities: string[];
+    peopleAlsoAskFaqSection: Array<{
+        question: string;
+        suggestedAnswerBullets: string[];
+    }>;
+}
+export interface JsRenderingDiffReport {
+    url: string;
+    serverHtmlLength: number;
+    hydratedDomLength: number;
+    contentDifferencePercent: number;
+    jsDependentElements: {
+        linksOnlyInClientDom: string[];
+        headingsOnlyInClientDom: string[];
+        metaTagsRewrittenByClient: Array<{
+            tag: string;
+            serverValue: string;
+            clientValue: string;
+        }>;
+    };
+    seoCrawlerRisk: 'Low' | 'Medium' | 'High (Significant Hydration Dependence)';
+    recommendations: string[];
+}
+export interface TechnicalAuditReport {
+    url: string;
+    statusCode: number;
+    responseTimeMs: number;
+    redirectChain: string[];
+    isHttps: boolean;
+    canonicalTag: {
+        present: boolean;
+        value: string;
+        isSelfReferencing: boolean;
+    };
+    robotsDirectives: {
+        metaRobots: string;
+        xRobotsTag: string;
+        isNoIndex: boolean;
+        isNoFollow: boolean;
+    };
+    hreflangTags: Array<{
+        lang: string;
+        href: string;
+    }>;
+    openGraphTags: {
+        hasTitle: boolean;
+        hasDescription: boolean;
+        hasImage: boolean;
+        hasType: boolean;
+    };
+    twitterCards: {
+        hasCard: boolean;
+        hasTitle: boolean;
+        hasImage: boolean;
+    };
+    issuesFound: Array<{
+        severity: 'critical' | 'warning' | 'info';
+        message: string;
+        fix: string;
+    }>;
+}
+export interface EntitySalienceItem {
+    name: string;
+    salienceScore: number;
+    type: string;
+    wikidataId?: string;
+    contextSentence?: string;
+}
+export interface SpoTriple {
+    subject: string;
+    predicate: string;
+    object: string;
+    sourceSentence: string;
+}
+export interface EntitySalienceMapReport {
+    totalEntitiesFound: number;
+    topEntities: EntitySalienceItem[];
+    semanticTriples: SpoTriple[];
+    knowledgeGraphSummary: string;
+}
+export interface SchemaValidationResult {
+    schemasDetectedCount: number;
+    schemas: Array<{
+        type: string;
+        rawObject: Record<string, any>;
+        isValid: boolean;
+        missingMandatoryFields: string[];
+        recommendedImprovements: string[];
+    }>;
+    googleRichResultEligibility: Array<{
+        feature: string;
+        eligible: boolean;
+        missingRequirements: string[];
+    }>;
+}
+export interface KeywordClusterGroup {
+    clusterName: string;
+    pillarTopic: string;
+    primaryKeyword: string;
+    supportingKeywords: string[];
+    recommendedArticleType: string;
+    recommendedUrlSlug: string;
+}
+export interface SearchIntentClassification {
+    keyword: string;
+    intent: 'Informational' | 'Transactional' | 'Commercial Investigation' | 'Navigational';
+    confidenceScore: number;
+    recommendedPageFormat: string;
+}
+export interface ContentDecayReport {
+    urlOrTitle: string;
+    freshnessScore: number;
+    decayLevel: 'Fresh' | 'Mild Decay' | 'Severe Decay';
+    staleYearReferences: string[];
+    detectedOutdatedStats: string[];
+    brokenOutboundLinks: string[];
+    suggestedUpdateChecklist: string[];
+}

package/dist/types/seo.js

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

package/dist/utils/jsdomRenderer.d.ts

@@ -0,0 +1,5 @@
+import { JsRenderingDiffReport } from '../types/seo.js';
+/**
+ * Compares initial server HTML with the rendered DOM (JavaScript SEO Hydration diffing).
+ */
+export declare function compareServerVsClientDom(url: string): Promise<JsRenderingDiffReport>;

package/dist/utils/jsdomRenderer.js

@@ -0,0 +1,79 @@
+import { JSDOM, VirtualConsole } from 'jsdom';
+import axios from 'axios';
+import { getRandomUserAgent } from './scraper.js';
+/**
+ * Compares initial server HTML with the rendered DOM (JavaScript SEO Hydration diffing).
+ */
+export async function compareServerVsClientDom(url) {
+    let serverHtml = '';
+    try {
+        const response = await axios.get(url, {
+            headers: {
+                'User-Agent': getRandomUserAgent(),
+                'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8'
+            },
+            timeout: 12000,
+            validateStatus: () => true
+        });
+        serverHtml = typeof response.data === 'string' ? response.data : JSON.stringify(response.data);
+    }
+    catch (err) {
+        throw new Error(`Failed to fetch server HTML from ${url}: ${err.message}`);
+    }
+    // Render in JSDOM with script execution enabled
+    const virtualConsole = new VirtualConsole();
+    virtualConsole.on('error', () => { }); // silence js console errors
+    virtualConsole.on('warn', () => { });
+    let hydratedDomHtml = serverHtml;
+    try {
+        const dom = new JSDOM(serverHtml, {
+            url,
+            runScripts: 'outside-only',
+            resources: 'usable',
+            virtualConsole
+        });
+        hydratedDomHtml = dom.serialize();
+    }
+    catch {
+        hydratedDomHtml = serverHtml;
+    }
+    const serverLength = serverHtml.length;
+    const clientLength = hydratedDomHtml.length;
+    const lengthDiff = Math.abs(clientLength - serverLength);
+    const percentDiff = Number(((lengthDiff / Math.max(serverLength, 1)) * 100).toFixed(1));
+    // Inspect link and heading differences
+    const serverLinks = Array.from(serverHtml.matchAll(/href=["'](https?:\/\/[^"']+|\/[^"']+)["']/gi)).map(m => m[1]);
+    const clientLinks = Array.from(hydratedDomHtml.matchAll(/href=["'](https?:\/\/[^"']+|\/[^"']+)["']/gi)).map(m => m[1]);
+    const linksOnlyInClient = clientLinks.filter(l => !serverLinks.includes(l)).slice(0, 10);
+    const serverH1s = Array.from(serverHtml.matchAll(/<h1[^>]*>([\s\S]*?)<\/h1>/gi)).map(m => m[1].replace(/<[^>]+>/g, '').trim());
+    const clientH1s = Array.from(hydratedDomHtml.matchAll(/<h1[^>]*>([\s\S]*?)<\/h1>/gi)).map(m => m[1].replace(/<[^>]+>/g, '').trim());
+    const headingsOnlyInClient = clientH1s.filter(h => !serverH1s.includes(h));
+    const crawlerRisk = linksOnlyInClient.length > 5 || percentDiff > 50
+        ? 'High (Significant Hydration Dependence)'
+        : percentDiff > 20
+            ? 'Medium'
+            : 'Low';
+    const recommendations = [];
+    if (linksOnlyInClient.length > 0) {
+        recommendations.push(`Ensure critical navigation links (${linksOnlyInClient.length} detected) are present in the initial Server-Side Rendered (SSR) HTML rather than injected via client JavaScript.`);
+    }
+    if (headingsOnlyInClient.length > 0) {
+        recommendations.push('H1 tag is rendered via client-side JavaScript. Pre-render H1 in server HTML to guarantee immediate crawler indexing.');
+    }
+    if (percentDiff < 15 && linksOnlyInClient.length === 0) {
+        recommendations.push('Excellent hydration parity. Initial HTML matches rendered DOM cleanly for search engine bots.');
+    }
+    return {
+        url,
+        serverHtmlLength: serverLength,
+        hydratedDomLength: clientLength,
+        contentDifferencePercent: percentDiff,
+        jsDependentElements: {
+            linksOnlyInClientDom: linksOnlyInClient,
+            headingsOnlyInClientDom: headingsOnlyInClient,
+            metaTagsRewrittenByClient: []
+        },
+        seoCrawlerRisk: crawlerRisk,
+        recommendations
+    };
+}

package/dist/utils/nlp.d.ts

@@ -0,0 +1,41 @@
+import { SpoTriple, EntitySalienceItem } from '../types/seo.js';
+/**
+ * Extract meaningful 1-gram, 2-gram, and 3-gram keyphrases and calculate their frequencies.
+ */
+export declare function extractKeyphrases(text: string, maxItems?: number): Array<{
+    term: string;
+    count: number;
+    tf: number;
+}>;
+/**
+ * Computes TF-IDF between target text and a set of competitor texts to detect content gaps.
+ */
+export declare function computeContentGapTfIdf(targetText: string, competitorTexts: string[]): Array<{
+    term: string;
+    competitorFrequency: number;
+    targetFrequency: number;
+    importance: 'high' | 'medium' | 'low';
+}>;
+/**
+ * Calculates Flesch Reading Ease, Flesch-Kincaid Grade Level, and Gunning Fog index.
+ */
+export declare function calculateReadability(text: string): {
+    fleschReadingEase: number;
+    gradeLevel: number;
+    gunningFog: number;
+    readingLevelSummary: string;
+    totalWords: number;
+    totalSentences: number;
+    wordsPerSentence: number;
+    passiveVoicePercent: number;
+    longSentencesCount: number;
+    sampleLongSentences: string[];
+};
+/**
+ * Extracts Subject-Predicate-Object (SPO) semantic triples from text for Knowledge Graph analysis.
+ */
+export declare function extractSpoTriples(text: string): SpoTriple[];
+/**
+ * Extracts key named entities with approximate salience scoring.
+ */
+export declare function extractEntitiesWithSalience(text: string): EntitySalienceItem[];