seo-gravity-mcp 1.0.0

package/dist/tools/eeat.js

@@ -0,0 +1,155 @@
+import { fetchAndParsePage } from '../utils/scraper.js';
+import { scrapeGoogleSerp } from '../utils/searchEngines.js';
+import { extractEntitiesWithSalience } from '../utils/nlp.js';
+export async function scoreInformationGain(myContentOrUrl, targetKeyword) {
+    let myText = myContentOrUrl;
+    if (myContentOrUrl.startsWith('http') || myContentOrUrl.includes('<html') || myContentOrUrl.endsWith('.html')) {
+        const page = await fetchAndParsePage(myContentOrUrl);
+        myText = page.cleanText;
+    }
+    // 1. Fetch top competitor texts
+    const serp = await scrapeGoogleSerp(targetKeyword, 'us', 'en', 3);
+    const competitorTexts = [];
+    for (const r of serp.organicResults.slice(0, 3)) {
+        try {
+            const p = await fetchAndParsePage(r.url);
+            competitorTexts.push(p.cleanText);
+        }
+        catch { }
+    }
+    const myEntities = extractEntitiesWithSalience(myText);
+    const compEntities = extractEntitiesWithSalience(competitorTexts.join(' '));
+    const compEntityNames = new Set(compEntities.map(e => e.name.toLowerCase()));
+    const uniqueEntities = myEntities
+        .filter(e => !compEntityNames.has(e.name.toLowerCase()))
+        .map(e => e.name);
+    // Detect specific novel signals: data points, unique methodologies, case studies
+    const dataPointsAndStats = (myText.match(/\b\d+(\.\d+)?%\b|\b\$\d+(\.\d+)?\b|\b\d{2,}\s+(users|companies|participants|queries|customers|nodes)\b/gi) || [])
+        .slice(0, 6);
+    const caseStudiesOrExamples = (myText.match(/\b(for example|case study|in our testing|we found that|our data shows|in practice)\b[\s\S]{10,80}\./gi) || [])
+        .slice(0, 4);
+    const uniqueQuotes = (myText.match(/"([^"]{15,100})"/g) || []).slice(0, 3);
+    // Score calculation:
+    // Base 30
+    // + 5 per unique entity (max 25)
+    // + 5 per distinct stat (max 20)
+    // + 10 per case study/test result (max 20)
+    // + 5 per quote (max 10)
+    let rawScore = 30 + (uniqueEntities.length * 5) + (dataPointsAndStats.length * 4) + (caseStudiesOrExamples.length * 7) + (uniqueQuotes.length * 3);
+    const informationGainScore = Math.min(100, Math.max(10, rawScore));
+    const noveltyTier = informationGainScore >= 75
+        ? 'Exceptional (High Information Gain)'
+        : informationGainScore >= 50
+            ? 'Moderate'
+            : 'Low (Rehashed / Generic AI Risk)';
+    const recommendations = [];
+    if (dataPointsAndStats.length < 2) {
+        recommendations.push('Include proprietary metrics, benchmark percentages, or original experiment numbers to distinguish from generic summary articles.');
+    }
+    if (caseStudiesOrExamples.length === 0) {
+        recommendations.push('Add a real-world case study or first-person testing walkthrough ("In our tests...", "When we implemented X...").');
+    }
+    if (uniqueEntities.length < 3) {
+        recommendations.push('Introduce unique frameworks, tools, or named methodologies not already saturated across top competitor pages.');
+    }
+    return {
+        targetKeyword,
+        informationGainScore,
+        noveltyTier,
+        uniqueEntitiesDetected: uniqueEntities.slice(0, 8),
+        competitorOverlapPercentage: Math.max(20, 100 - uniqueEntities.length * 8),
+        originalElementsFound: {
+            dataPointsAndStats,
+            caseStudiesOrExamples,
+            uniqueMethodologiesOrQuotes: uniqueQuotes
+        },
+        recommendationsToIncreaseGain: recommendations
+    };
+}
+export async function auditEeat(urlOrHtml) {
+    const page = await fetchAndParsePage(urlOrHtml);
+    const html = page.html;
+    const cleanText = page.cleanText;
+    // 1. Author signals
+    const hasAuthorByline = /\b(by\s+[A-Z][a-z]+|written by|author|editorial team)\b/i.test(html) || page.$('[rel="author"], .author, .byline, [itemprop="author"]').length > 0;
+    const hasAuthorBio = /\b(bio|about the author|author-bio|experience|credentials)\b/i.test(html);
+    const personSchemas = page.schemas.filter(s => s['@type'] === 'Person' || (s['@graph'] && s['@graph'].some((g) => g['@type'] === 'Person')));
+    const hasPersonSchema = personSchemas.length > 0;
+    const sameAsProfiles = [];
+    page.$('a[href*="linkedin.com"], a[href*="twitter.com"], a[href*="x.com"], a[href*="wikipedia.org"], a[href*="wikidata.org"]').each((_, el) => {
+        const href = page.$(el).attr('href');
+        if (href && !sameAsProfiles.includes(href)) {
+            sameAsProfiles.push(href);
+        }
+    });
+    // 2. Transparency signals
+    const hasEditorialPolicy = /editorial\s+policy|fact\s+check|correction\s+policy|methodology/i.test(html);
+    const hasFactCheckDisclaimer = /fact-checked|medical\s+review|financial\s+disclaimer|reviewed\s+by/i.test(html);
+    const hasPublishDate = /datePublished|published\s+on|date-published|<time/i.test(html);
+    const hasModifiedDate = /dateModified|updated\s+on|last\s+updated|last-modified/i.test(html);
+    // 3. Contact & Entity signals
+    const hasAboutPageLink = page.links.internal.some(l => /about|company|team/i.test(l)) || page.links.external.some(l => /about/i.test(l));
+    const hasContactInfo = /contact|support|mailto:|tel:|customer-service/i.test(html);
+    const hasPhysicalAddress = /address|postalCode|streetAddress|HQ|headquarters/i.test(html);
+    // 4. External authoritative citations
+    const govEduOrgLinks = page.links.external.filter(l => /\.gov|\.edu|\.org|wikipedia\.org|ncbi\.nlm\.nih\.gov/i.test(l)).length;
+    // Calculate score
+    let score = 20;
+    if (hasAuthorByline)
+        score += 15;
+    if (hasAuthorBio)
+        score += 10;
+    if (hasPersonSchema)
+        score += 15;
+    if (sameAsProfiles.length > 0)
+        score += 10;
+    if (hasEditorialPolicy || hasFactCheckDisclaimer)
+        score += 10;
+    if (hasPublishDate && hasModifiedDate)
+        score += 10;
+    if (hasAboutPageLink && hasContactInfo)
+        score += 10;
+    const overallEeatScore = Math.min(100, score);
+    const trustLevel = overallEeatScore >= 75 ? 'High Authority' : overallEeatScore >= 50 ? 'Moderate' : 'Needs Improvement';
+    const improvements = [];
+    if (!hasPersonSchema) {
+        improvements.push('Embed Schema.org Person structured data for the author with explicit sameAs links (LinkedIn, Wikidata).');
+    }
+    if (!hasAuthorBio) {
+        improvements.push('Add an author biography highlighting subject-matter credentials, years of experience, and industry background.');
+    }
+    if (!hasModifiedDate) {
+        improvements.push('Display visible "Last Updated / Modified" timestamps to reinforce freshness.');
+    }
+    if (sameAsProfiles.length === 0) {
+        improvements.push('Link author social profiles (LinkedIn, X/Twitter, personal website) to establish clear verifiable entity connection.');
+    }
+    return {
+        overallEeatScore,
+        trustLevel,
+        signals: {
+            authorIdentity: {
+                hasAuthorByline,
+                hasAuthorBio,
+                hasPersonSchema,
+                sameAsProfilesLinked: sameAsProfiles.slice(0, 5)
+            },
+            transparency: {
+                hasEditorialPolicy,
+                hasFactCheckDisclaimer,
+                hasPublishDate,
+                hasModifiedDate
+            },
+            contactAndEntity: {
+                hasAboutPageLink,
+                hasContactInfo,
+                hasPhysicalAddress
+            },
+            citationsAndReferences: {
+                externalAuthoritativeCitationsCount: page.links.external.length,
+                peerReviewedOrGovLinksCount: govEduOrgLinks
+            }
+        },
+        actionableImprovements: improvements
+    };
+}

package/dist/tools/geo.d.ts

@@ -0,0 +1,17 @@
+import { GeoAiReadinessReport } from '../types/seo.js';
+export declare function auditGeoAiReadiness(urlOrText: string, targetQuery: string): Promise<GeoAiReadinessReport>;
+export declare function generateLlmsTxt(siteName: string, siteDescription: string, keyPages: Array<{
+    title: string;
+    url: string;
+    description: string;
+}>): {
+    llmsTxt: string;
+    llmsFullTxt: string;
+};
+export declare function auditAiBotsRobots(domainOrUrl: string): Promise<{
+    domain: string;
+    robotsTxtFound: boolean;
+    botDirectives: Record<string, 'Allowed' | 'Disallowed' | 'Default (Allowed)'>;
+    summary: string;
+    recommendedConfig: string;
+}>;

package/dist/tools/geo.js

@@ -0,0 +1,190 @@
+import axios from 'axios';
+import { fetchAndParsePage, getRandomUserAgent } from '../utils/scraper.js';
+export async function auditGeoAiReadiness(urlOrText, targetQuery) {
+    let content = urlOrText;
+    let hasHeadings = false;
+    let listItemsCount = 0;
+    let tablesCount = 0;
+    if (urlOrText.startsWith('http') || urlOrText.includes('<html') || urlOrText.endsWith('.html')) {
+        const page = await fetchAndParsePage(urlOrText);
+        content = page.cleanText;
+        hasHeadings = page.headings.h2.length > 0;
+        listItemsCount = page.$('li').length;
+        tablesCount = page.$('table').length;
+    }
+    else {
+        hasHeadings = /^#{1,4}\s+/m.test(urlOrText);
+        listItemsCount = (urlOrText.match(/^[-*]\s+/gm) || []).length;
+        tablesCount = (urlOrText.match(/\|[\s\S]*?\|/g) || []).length > 2 ? 1 : 0;
+    }
+    const queryWords = targetQuery.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+    const first300Words = content.split(/\s+/).slice(0, 300).join(' ').toLowerCase();
+    // 1. Direct Answer Check: Does the first 150 words contain a direct definition or concise answer?
+    const directAnswerPassed = queryWords.some(w => first300Words.includes(w)) &&
+        (first300Words.includes(' is ') || first300Words.includes(' refers to ') || first300Words.includes(' can be defined as '));
+    const directAnswerScore = directAnswerPassed ? 25 : 10;
+    // 2. Semantic Chunking Check: Are there distinct sections with clear H2/H3 anchors?
+    const semanticChunkingPassed = hasHeadings && content.length > 500;
+    const chunkingScore = semanticChunkingPassed ? 20 : 5;
+    // 3. Structured Data & Lists: Are there bullet points or comparison tables for LLM digestion?
+    const structuredDataPassed = listItemsCount >= 3 || tablesCount >= 1;
+    const structuredScore = structuredDataPassed ? 20 : 5;
+    // 4. Authoritative Citations & Stats: Are there numbers, %, or citations?
+    const statsMatches = content.match(/\b\d+(\.\d+)?%\b|\b\$\d+(\.\d+)?\b|\b\d{4}\b|\baccording to\b|\bstudy by\b/gi) || [];
+    const statsScore = statsMatches.length >= 3 ? 20 : statsMatches.length >= 1 ? 10 : 0;
+    // 5. Entity Clarity
+    const entityScore = queryWords.every(w => content.toLowerCase().includes(w)) ? 15 : 5;
+    const totalScore = directAnswerScore + chunkingScore + structuredScore + statsScore + entityScore;
+    const citationLikelihood = totalScore >= 75 ? 'High' : totalScore >= 50 ? 'Medium' : 'Low';
+    const firstSentence = content.split(/[.!?]+/)[0] || '';
+    return {
+        targetQuery,
+        overallGeoScore: totalScore,
+        citationLikelihood,
+        checks: {
+            directAnswerParagraph: {
+                passed: directAnswerPassed,
+                score: directAnswerScore,
+                feedback: directAnswerPassed
+                    ? 'Clear introductory direct answer detected, ideal for AI Overview snippet extraction.'
+                    : 'Missing a bold, concise definition or executive summary in the first 100-150 words.',
+                detectedSnippet: firstSentence.substring(0, 150)
+            },
+            semanticChunking: {
+                passed: semanticChunkingPassed,
+                score: chunkingScore,
+                feedback: semanticChunkingPassed
+                    ? 'Content is partitioned into distinct semantic subtopics with heading markers.'
+                    : 'Content lacks clear modular headings, reducing LLM citation accuracy.'
+            },
+            structuredDataAndLists: {
+                passed: structuredDataPassed,
+                score: structuredScore,
+                feedback: `Found ${listItemsCount} bullet items and ${tablesCount} tables. LLMs favor bulleted lists and tables when generating comparison answers.`
+            },
+            authoritativeCitationsAndStats: {
+                passed: statsMatches.length >= 2,
+                score: statsScore,
+                feedback: `Detected ${statsMatches.length} specific data points/statistics. Hard data significantly increases AI citation probability.`,
+                detectedStatsCount: statsMatches.length
+            },
+            entityClarity: {
+                passed: entityScore === 15,
+                score: entityScore,
+                feedback: 'Primary subject entity is clearly referenced throughout the document.'
+            }
+        },
+        recommendedSnippetsForAiCitation: [
+            {
+                section: 'Executive Summary / Direct Answer Box',
+                suggestedFormat: '3-sentence summary in bold or callout box',
+                exampleText: `**${targetQuery}** refers to [concise definition]. It allows [key benefit] and is primarily used for [core use case].`
+            },
+            {
+                section: 'Key Takeaways Bullet Points',
+                suggestedFormat: 'Unordered list of 3-5 high-impact bullet items',
+                exampleText: `• Core Feature 1: [Specific metric or capability]\n• Core Feature 2: [Specific metric or capability]\n• Key Difference: [How it differs from alternatives]`
+            }
+        ]
+    };
+}
+export function generateLlmsTxt(siteName, siteDescription, keyPages) {
+    const llmsTxt = `# ${siteName}
+
+> ${siteDescription}
+
+## Core Documentation & Key Pages
+${keyPages.map(p => `- [${p.title}](${p.url}): ${p.description}`).join('\n')}
+
+## Guidelines for AI Ingestion
+- Prefer concise markdown extraction.
+- Link citations directly to the canonical URLs listed above.
+`;
+    const llmsFullTxt = `# ${siteName} - Comprehensive AI Knowledge Index
+
+> ${siteDescription}
+
+## Table of Contents
+${keyPages.map(p => `- [${p.title}](#${p.title.toLowerCase().replace(/\s+/g, '-')})`).join('\n')}
+
+---
+
+${keyPages.map(p => `### ${p.title}
+- **URL**: ${p.url}
+- **Description**: ${p.description}
+- **Canonical Reference**: Direct citation recommended for queries regarding ${p.title.toLowerCase()}.
+`).join('\n---\n')}
+`;
+    return { llmsTxt, llmsFullTxt };
+}
+export async function auditAiBotsRobots(domainOrUrl) {
+    const domain = domainOrUrl.startsWith('http') ? new URL(domainOrUrl).origin : `https://${domainOrUrl}`;
+    const robotsUrl = `${domain}/robots.txt`;
+    let robotsContent = '';
+    let found = false;
+    try {
+        const res = await axios.get(robotsUrl, {
+            headers: { 'User-Agent': getRandomUserAgent() },
+            timeout: 8000,
+            validateStatus: () => true
+        });
+        if (res.status === 200 && typeof res.data === 'string') {
+            robotsContent = res.data;
+            found = true;
+        }
+    }
+    catch {
+        found = false;
+    }
+    const aiBots = [
+        'GPTBot',
+        'ChatGPT-User',
+        'ClaudeBot',
+        'anthropic-ai',
+        'PerplexityBot',
+        'Google-Extended',
+        'Bytespider',
+        'Applebot-Extended',
+        'CCBot'
+    ];
+    const botDirectives = {};
+    aiBots.forEach(bot => {
+        const regex = new RegExp(`User-agent:\\s*${bot}[\\s\\S]*?Disallow:\\s*(\\/|.*)`, 'i');
+        if (regex.test(robotsContent)) {
+            const match = robotsContent.match(regex);
+            if (match && match[1] && match[1].trim() === '/') {
+                botDirectives[bot] = 'Disallowed';
+            }
+            else {
+                botDirectives[bot] = 'Allowed';
+            }
+        }
+        else {
+            // Check if global User-agent: * disallows all
+            const globalDisallow = /User-agent:\s*\*[\s\S]*?Disallow:\s*\/\s*$/m.test(robotsContent);
+            botDirectives[bot] = globalDisallow ? 'Disallowed' : 'Default (Allowed)';
+        }
+    });
+    const disallowedCount = Object.values(botDirectives).filter(v => v === 'Disallowed').length;
+    return {
+        domain,
+        robotsTxtFound: found,
+        botDirectives,
+        summary: disallowedCount > 0
+            ? `${disallowedCount} AI crawlers are explicitly disallowed from indexing content.`
+            : 'All major AI search crawlers (GPTBot, ClaudeBot, PerplexityBot) are currently allowed.',
+        recommendedConfig: `# Recommended AI Bot Directives in robots.txt
+User-agent: GPTBot
+Allow: /
+
+User-agent: ClaudeBot
+Allow: /
+
+User-agent: PerplexityBot
+Allow: /
+
+User-agent: Google-Extended
+Allow: /
+`
+    };
+}

package/dist/tools/keywords.d.ts

@@ -0,0 +1,26 @@
+import { KeywordClusterGroup, SearchIntentClassification } from '../types/seo.js';
+export declare function getKeywordSuggestions(seedKeyword: string, includeAlphabetSoup?: boolean, modifiers?: string[]): Promise<{
+    seed: string;
+    totalSuggestions: number;
+    coreSuggestions: string[];
+    modifierSuggestions: Record<string, string[]>;
+    alphabetSoupSuggestions?: Record<string, string[]>;
+}>;
+export declare function findQuestions(topic: string): Promise<{
+    topic: string;
+    totalQuestions: number;
+    questionClusters: {
+        how: string[];
+        what: string[];
+        why: string[];
+        can: string[];
+        is: string[];
+        best: string[];
+    };
+}>;
+export declare function clusterKeywords(keywords: string[], similarityThreshold?: number): {
+    totalKeywords: number;
+    clusterCount: number;
+    clusters: KeywordClusterGroup[];
+};
+export declare function classifySearchIntent(keywords: string[]): SearchIntentClassification[];

package/dist/tools/keywords.js

@@ -0,0 +1,112 @@
+import { getGoogleAutocomplete, getAlphabetSoupSuggestions } from '../utils/searchEngines.js';
+export async function getKeywordSuggestions(seedKeyword, includeAlphabetSoup = true, modifiers = ['best', 'vs', 'pricing', 'alternative', 'how to', 'free']) {
+    const core = await getGoogleAutocomplete(seedKeyword);
+    const modResults = {};
+    await Promise.all(modifiers.map(async (mod) => {
+        const results = await getGoogleAutocomplete(`${seedKeyword} ${mod}`);
+        if (results.length > 0)
+            modResults[mod] = results.slice(0, 5);
+    }));
+    let alphabetSoup;
+    if (includeAlphabetSoup) {
+        alphabetSoup = await getAlphabetSoupSuggestions(seedKeyword);
+    }
+    let total = core.length;
+    Object.values(modResults).forEach(arr => total += arr.length);
+    if (alphabetSoup) {
+        Object.values(alphabetSoup).forEach(arr => total += arr.length);
+    }
+    return {
+        seed: seedKeyword,
+        totalSuggestions: total,
+        coreSuggestions: core,
+        modifierSuggestions: modResults,
+        alphabetSoupSuggestions: alphabetSoup
+    };
+}
+export async function findQuestions(topic) {
+    const questionWords = ['how to', 'what is', 'why does', 'can you', 'is it', 'best'];
+    const clusters = { how: [], what: [], why: [], can: [], is: [], best: [] };
+    await Promise.all(questionWords.map(async (q) => {
+        const results = await getGoogleAutocomplete(`${q} ${topic}`);
+        const key = q.split(' ')[0];
+        if (clusters[key]) {
+            clusters[key] = results.filter(r => r.length > 10).slice(0, 6);
+        }
+    }));
+    let total = 0;
+    Object.values(clusters).forEach((arr) => total += arr.length);
+    return {
+        topic,
+        totalQuestions: total,
+        questionClusters: clusters
+    };
+}
+export function clusterKeywords(keywords, similarityThreshold = 0.6) {
+    const clusters = [];
+    const assigned = new Set();
+    keywords.forEach(kw => {
+        if (assigned.has(kw))
+            return;
+        const words = kw.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+        const related = [];
+        keywords.forEach(other => {
+            if (other === kw || assigned.has(other))
+                return;
+            const otherWords = other.toLowerCase().split(/\s+/).filter(w => w.length > 2);
+            // Jaccard similarity between words
+            const intersection = words.filter(w => otherWords.includes(w)).length;
+            const union = new Set([...words, ...otherWords]).size;
+            const sim = union > 0 ? intersection / union : 0;
+            if (sim >= similarityThreshold || (words.length > 1 && other.toLowerCase().includes(words[0]))) {
+                related.push(other);
+            }
+        });
+        assigned.add(kw);
+        related.forEach(r => assigned.add(r));
+        const pillar = kw;
+        const slug = pillar.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+        clusters.push({
+            clusterName: `${pillar} Topic Hub`,
+            pillarTopic: pillar,
+            primaryKeyword: pillar,
+            supportingKeywords: related,
+            recommendedArticleType: related.length > 2 ? 'Pillar Guide with Cluster Subpages' : 'Standalone Target Article',
+            recommendedUrlSlug: `/${slug}`
+        });
+    });
+    return {
+        totalKeywords: keywords.length,
+        clusterCount: clusters.length,
+        clusters: clusters.sort((a, b) => b.supportingKeywords.length - a.supportingKeywords.length)
+    };
+}
+export function classifySearchIntent(keywords) {
+    return keywords.map(kw => {
+        const lower = kw.toLowerCase();
+        let intent = 'Informational';
+        let confidence = 0.85;
+        let format = 'In-depth Tutorial / Guide / Explanation';
+        if (/\b(buy|order|discount|coupon|deal|pricing|price|cost|shop|purchase)\b/i.test(lower)) {
+            intent = 'Transactional';
+            confidence = 0.95;
+            format = 'Product / Checkout / Pricing Page with direct Buy CTAs';
+        }
+        else if (/\b(best|top|review|reviews|vs|versus|comparison|alternative|alternatives)\b/i.test(lower)) {
+            intent = 'Commercial Investigation';
+            confidence = 0.92;
+            format = 'Comparison Matrix / Roundup Review Table with pros & cons';
+        }
+        else if (/\b(login|sign in|portal|official|app|account|status)\b/i.test(lower)) {
+            intent = 'Navigational';
+            confidence = 0.90;
+            format = 'Landing Page / Direct Portal Link';
+        }
+        return {
+            keyword: kw,
+            intent,
+            confidenceScore: confidence,
+            recommendedPageFormat: format
+        };
+    });
+}

package/dist/tools/onpage.d.ts

@@ -0,0 +1,15 @@
+import { OnPageAuditReport, ContentBrief } from '../types/seo.js';
+export declare function auditOnPage(urlOrHtml: string, focusKeyword?: string): Promise<OnPageAuditReport>;
+export declare function generateContentBrief(primaryKeyword: string, secondaryKeywords?: string[], searchIntent?: 'Informational' | 'Transactional' | 'Commercial Investigation' | 'Navigational'): Promise<ContentBrief>;
+export declare function scoreReadability(textOrUrl: string): Promise<{
+    fleschReadingEase: number;
+    gradeLevel: number;
+    gunningFog: number;
+    readingLevelSummary: string;
+    totalWords: number;
+    totalSentences: number;
+    wordsPerSentence: number;
+    passiveVoicePercent: number;
+    longSentencesCount: number;
+    sampleLongSentences: string[];
+}>;