@automatelab/ai-seo-mcp 0.1.0

package/dist/tools/score-citation-worthiness.js

@@ -0,0 +1,145 @@
+// Tool: score_citation_worthiness
+// Scores how citable a page or text block is for AI engines.
+import { z } from "zod";
+import { politeFetch } from "../lib/fetch.js";
+import { parseBody } from "../lib/html.js";
+import { parseJsonLd, getAllSchemaTypes } from "../lib/schema.js";
+export const scoreCitationWorthinessInputSchema = z
+    .object({
+    url: z.string().url().optional(),
+    text: z.string().optional(),
+    target_query: z.string().optional(),
+    respect_robots: z.boolean().optional().default(true),
+})
+    .refine((d) => d.url !== undefined || d.text !== undefined, {
+    message: "One of url or text is required",
+});
+function computeBluf(bodyText, targetQuery) {
+    const first100Words = bodyText.split(/\s+/).slice(0, 100).join(" ");
+    // Direct answer heuristic: a sentence with a number, or containing the target query
+    if (targetQuery && first100Words.toLowerCase().includes(targetQuery.toLowerCase()))
+        return true;
+    if (/\b\d+\b/.test(first100Words) && /\.\s/.test(first100Words))
+        return true;
+    return false;
+}
+function computeStatisticDensity(bodyText) {
+    const wordCount = bodyText.split(/\s+/).filter((w) => w.length > 0).length;
+    if (wordCount === 0)
+        return 0;
+    const statMatches = bodyText.match(/\b\d[\d,.'%]+\b/g) ?? [];
+    const statsPerThousand = (statMatches.length / wordCount) * 1000;
+    return Math.min(100, Math.round(statsPerThousand * 10)); // >10 stats/1000 words = 100
+}
+function computeEntityClarity(bodyText) {
+    const definitionPatterns = /\b\w+\s+(is an?\s+|refers to\s+|means\s+|defined as\s+)/gi;
+    const definitions = (bodyText.match(definitionPatterns) ?? []).length;
+    const uniqueNouns = new Set(bodyText.match(/\b[A-Z][a-z]+\b/g) ?? []).size;
+    if (uniqueNouns === 0)
+        return 0;
+    return Math.min(100, Math.round((definitions / Math.max(1, uniqueNouns)) * 100 * 10));
+}
+function countFaqBlocks(h3s, paragraphs) {
+    // FAQ block = H3 ending in "?" followed by a paragraph
+    return h3s.filter((h) => h.endsWith("?")).length;
+}
+export async function scoreCitationWorthiness(input, hostDelays, robotsCache) {
+    const findings = [];
+    let bodyText = "";
+    let h3s = [];
+    let paragraphs = [];
+    let hasStructuredData = false;
+    let wordCount = 0;
+    if (input.url) {
+        const result = await politeFetch(input.url, {
+            respectRobots: input.respect_robots,
+            hostDelays,
+            robotsCache,
+        });
+        const body = parseBody(result.body, input.url);
+        bodyText = body.bodyText;
+        h3s = body.h3s;
+        paragraphs = body.paragraphs;
+        wordCount = body.wordCount;
+        const jsonLdBlocks = parseJsonLd(result.body);
+        const foundTypes = getAllSchemaTypes(jsonLdBlocks);
+        hasStructuredData = foundTypes.length > 0;
+    }
+    else {
+        bodyText = input.text;
+        wordCount = bodyText.split(/\s+/).filter((w) => w.length > 0).length;
+        // Extract H3-like lines from plain text (lines ending in ?)
+        const lines = bodyText.split("\n");
+        h3s = lines.filter((l) => l.trim().endsWith("?") && l.trim().length < 100);
+        paragraphs = lines.filter((l) => l.trim().split(/\s+/).length >= 20);
+    }
+    // Sub-scores
+    const bluf_present = computeBluf(bodyText, input.target_query);
+    const faq_blocks = countFaqBlocks(h3s, paragraphs);
+    const statistic_density = computeStatisticDensity(bodyText);
+    const entity_clarity = computeEntityClarity(bodyText);
+    const totalHeadings = h3s.length + (input.text ? 0 : 0); // simplified
+    const questionHeadings = h3s.filter((h) => h.endsWith("?")).length;
+    const heading_question_ratio = totalHeadings > 0 ? Math.round((questionHeadings / totalHeadings) * 100) : 0;
+    // Longest self-contained paragraph (word count proxy)
+    const answer_completeness = paragraphs.length > 0
+        ? Math.min(100, Math.max(...paragraphs.map((p) => p.split(/\s+/).filter((w) => w.length > 0).length)) / 2)
+        : 0;
+    // Engine-specific scores
+    const blufScore = bluf_present ? 100 : 0;
+    const faqScore = Math.min(100, faq_blocks * 25);
+    const structuredDataScore = hasStructuredData ? 80 : 0;
+    // Perplexity: faq_blocks 40%, bluf_present 30%, statistic_density 30%
+    const perplexity = Math.round(faqScore * 0.4 + blufScore * 0.3 + statistic_density * 0.3);
+    // ChatGPT: answer_completeness 35%, structured_data 35%, bluf_present 30%
+    const chatgpt = Math.round(answer_completeness * 0.35 + structuredDataScore * 0.35 + blufScore * 0.3);
+    // Google AI Overviews: faq_blocks 30%, entity_clarity 30%, heading_question_ratio 20%, statistic_density 20%
+    const google_ai_overviews = Math.round(faqScore * 0.3 +
+        entity_clarity * 0.3 +
+        heading_question_ratio * 0.2 +
+        statistic_density * 0.2);
+    // Claude: statistic_density 35%, bluf_present 35%, entity_clarity 30%
+    const claude = Math.round(statistic_density * 0.35 + blufScore * 0.35 + entity_clarity * 0.30);
+    const overall_score = Math.round((perplexity + chatgpt + google_ai_overviews + claude) / 4);
+    // Improvements
+    const improvements = [];
+    if (!bluf_present) {
+        improvements.push("Add a direct 40-60 word answer in the first paragraph (BLUF - Bottom Line Up Front).");
+    }
+    if (faq_blocks < 3) {
+        improvements.push("Structure 3-5 FAQ-formatted Q&A blocks with H3 headings ending in '?'.");
+    }
+    if (statistic_density < 30) {
+        improvements.push("Include at least 3 cited statistics with year and source to increase statistic density.");
+    }
+    if (entity_clarity < 20) {
+        improvements.push("Define key terms inline (e.g., 'X is a type of Y that...') to improve entity clarity.");
+    }
+    const topImprovements = improvements.slice(0, 3);
+    // Findings
+    if (overall_score < 40) {
+        findings.push({
+            severity: "warning",
+            category: "structure",
+            where: "page-level",
+            message: `Low citation worthiness score (${overall_score}/100).`,
+            fix: "Apply BLUF structure, add FAQ blocks, and include cited statistics.",
+            estimated_impact: "high",
+        });
+    }
+    return {
+        overall_score,
+        engine_scores: { perplexity, chatgpt, google_ai_overviews, claude },
+        sub_scores: {
+            bluf_present,
+            faq_blocks,
+            statistic_density,
+            entity_clarity,
+            heading_question_ratio,
+            answer_completeness,
+        },
+        improvements: topImprovements,
+        findings,
+    };
+}
+//# sourceMappingURL=score-citation-worthiness.js.map

package/dist/tools/score-citation-worthiness.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"score-citation-worthiness.js","sourceRoot":"","sources":["../../src/tools/score-citation-worthiness.ts"],"names":[],"mappings":"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"}

package/dist/tools/validate-llms-txt.d.ts

@@ -0,0 +1,33 @@
+import { z } from "zod";
+import { type HostDelayMap } from "../lib/fetch.js";
+import type { Finding } from "../types.js";
+export declare const validateLlmsTxtInputSchema: z.ZodEffects<z.ZodObject<{
+    url: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+    check_links: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+}, "strip", z.ZodTypeAny, {
+    check_links: boolean;
+    url?: string | undefined;
+    content?: string | undefined;
+}, {
+    url?: string | undefined;
+    content?: string | undefined;
+    check_links?: boolean | undefined;
+}>, {
+    check_links: boolean;
+    url?: string | undefined;
+    content?: string | undefined;
+}, {
+    url?: string | undefined;
+    content?: string | undefined;
+    check_links?: boolean | undefined;
+}>;
+export type ValidateLlmsTxtInput = z.infer<typeof validateLlmsTxtInputSchema>;
+export interface ValidateLlmsTxtResult {
+    valid: boolean;
+    links_total: number;
+    links_broken: number;
+    findings: Finding[];
+}
+export declare function validateLlmsTxt(input: ValidateLlmsTxtInput, hostDelays?: HostDelayMap, robotsCache?: Map<string, string>): Promise<ValidateLlmsTxtResult>;
+//# sourceMappingURL=validate-llms-txt.d.ts.map

package/dist/tools/validate-llms-txt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-llms-txt.d.ts","sourceRoot":"","sources":["../../src/tools/validate-llms-txt.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAA2B,KAAK,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAE7E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAE3C,eAAO,MAAM,0BAA0B;;;;;;;;;;;;;;;;;;;;EAQnC,CAAC;AAEL,MAAM,MAAM,oBAAoB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,0BAA0B,CAAC,CAAC;AAE9E,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,wBAAsB,eAAe,CACnC,KAAK,EAAE,oBAAoB,EAC3B,UAAU,CAAC,EAAE,YAAY,EACzB,WAAW,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,OAAO,CAAC,qBAAqB,CAAC,CAoDhC"}

package/dist/tools/validate-llms-txt.js

@@ -0,0 +1,62 @@
+// Tool: validate_llms_txt
+// Validates an existing llms.txt or llms-full.txt against the spec.
+import { z } from "zod";
+import { politeFetch, politeHead } from "../lib/fetch.js";
+import { validateLlmsTxtContent, extractLlmsLinks } from "../lib/llms-txt.js";
+export const validateLlmsTxtInputSchema = z
+    .object({
+    url: z.string().url().optional(),
+    content: z.string().optional(),
+    check_links: z.boolean().optional().default(true),
+})
+    .refine((d) => d.url !== undefined || d.content !== undefined, {
+    message: "One of url or content is required",
+});
+export async function validateLlmsTxt(input, hostDelays, robotsCache) {
+    let content;
+    if (input.url) {
+        // If given a domain-style URL, append /llms.txt
+        let fetchUrl = input.url;
+        if (!fetchUrl.endsWith(".txt") && !fetchUrl.includes("llms")) {
+            fetchUrl = fetchUrl.replace(/\/$/, "") + "/llms.txt";
+        }
+        const result = await politeFetch(fetchUrl, {
+            respectRobots: false,
+            hostDelays,
+            robotsCache,
+        });
+        content = result.body;
+    }
+    else {
+        content = input.content;
+    }
+    const findings = validateLlmsTxtContent(content);
+    let links_total = 0;
+    let links_broken = 0;
+    if (input.check_links) {
+        const links = extractLlmsLinks(content);
+        links_total = links.length;
+        const delays = hostDelays ?? new Map();
+        for (const link of links) {
+            const status = await politeHead(link.url, { hostDelays: delays });
+            if (status === null || status === 404 || status === 410) {
+                links_broken++;
+                findings.push({
+                    severity: "warning",
+                    category: "llms_txt",
+                    where: link.url,
+                    message: `Broken link: "${link.title}" returns ${status ?? "no response"}.`,
+                    fix: `Update or remove the link to ${link.url}.`,
+                });
+            }
+        }
+    }
+    const valid = !findings.some((f) => f.severity === "critical");
+    return {
+        valid,
+        links_total,
+        links_broken,
+        findings,
+    };
+}
+//# sourceMappingURL=validate-llms-txt.js.map

package/dist/tools/validate-llms-txt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-llms-txt.js","sourceRoot":"","sources":["../../src/tools/validate-llms-txt.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,48 @@
+export type Severity = "critical" | "warning" | "info";
+export type FindingCategory = "schema" | "robots" | "technical" | "freshness" | "structure" | "authority" | "presence" | "sitemap" | "llms_txt";
+export interface Finding {
+    /** Severity determines triage priority. critical = blocks citation, warning = hurts probability, info = nice-to-have. */
+    severity: Severity;
+    category: FindingCategory;
+    /** Where the issue was found. Use CSS selector, JSON-LD path like "Article.author", robots.txt line ref, or "page-level". */
+    where: string;
+    /** Human-readable message. Sentence case. <=120 chars. Do not repeat the fix here. */
+    message: string;
+    /** Concrete, copy-pasteable fix. Code snippets are acceptable. <=300 chars. */
+    fix: string;
+    /** Estimated impact on AI citation probability if this finding is resolved. Omit for info-level findings. */
+    estimated_impact?: "high" | "medium" | "low";
+}
+export interface AuditResult {
+    url: string;
+    fetched_at: string;
+    findings: Finding[];
+    score: number;
+    grade: "A" | "B" | "C" | "D" | "F";
+}
+export type ToolError = {
+    type: "invalid_url";
+    message: string;
+} | {
+    type: "fetch_timeout";
+    url: string;
+    timeout_ms: number;
+} | {
+    type: "robots_blocked";
+    url: string;
+    user_agent: string;
+} | {
+    type: "non_html_response";
+    url: string;
+    content_type: string;
+} | {
+    type: "parse_error";
+    url: string;
+    detail: string;
+} | {
+    type: "fetch_error";
+    url: string;
+    status?: number;
+    message: string;
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvD,MAAM,MAAM,eAAe,GACvB,QAAQ,GACR,QAAQ,GACR,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,UAAU,GACV,SAAS,GACT,UAAU,CAAC;AAEf,MAAM,WAAW,OAAO;IACtB,yHAAyH;IACzH,QAAQ,EAAE,QAAQ,CAAC;IACnB,QAAQ,EAAE,eAAe,CAAC;IAC1B,6HAA6H;IAC7H,KAAK,EAAE,MAAM,CAAC;IACd,sFAAsF;IACtF,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,GAAG,EAAE,MAAM,CAAC;IACZ,6GAA6G;IAC7G,gBAAgB,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,CAAC;CAC9C;AAED,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;CACpC;AAED,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,mBAAmB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACpD;IAAE,IAAI,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC"}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Shared types for the AI-SEO MCP server.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,0CAA0C"}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@automatelab/ai-seo-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for AI-SEO auditing: schema, robots.txt, llms.txt, citation scoring, and AEO/GEO rewrites",
+  "license": "MIT",
+  "author": "automatelab.tech",
+  "homepage": "https://github.com/AutomateLab-tech/ai-seo",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AutomateLab-tech/ai-seo.git"
+  },
+  "engines": { "node": ">=20" },
+  "type": "module",
+  "bin": {
+    "ai-seo-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src tests --ext .ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.29.0",
+    "cheerio": "1.0.0",
+    "fast-xml-parser": "5.8.0",
+    "robots-parser": "3.0.1",
+    "undici": "7.25.0",
+    "zod": "3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "22.19.19",
+    "tsx": "4.22.0",
+    "typescript": "5.7.3",
+    "vitest": "3.2.4"
+  },
+  "files": [
+    "dist",
+    "src/lib/crawlers.json",
+    "src/lib/schema-types.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "mcp",
+    "seo",
+    "ai-seo",
+    "aeo",
+    "geo",
+    "ai-overview",
+    "schema",
+    "robots",
+    "llms-txt",
+    "citation"
+  ]
+}

package/src/lib/crawlers.json

@@ -0,0 +1,6 @@
+{
+  "training": ["GPTBot", "ClaudeBot", "CCBot", "Meta-ExternalAgent", "Amazonbot"],
+  "search": ["OAI-SearchBot", "Claude-SearchBot", "PerplexityBot", "Bingbot", "DuckAssistBot"],
+  "user_triggered": ["ChatGPT-User", "Claude-User", "Google-Agent"],
+  "robots_token_only": ["Google-Extended", "Applebot-Extended"]
+}

package/src/lib/schema-types.json

@@ -0,0 +1,56 @@
+[
+  "Article",
+  "BlogPosting",
+  "NewsArticle",
+  "FAQPage",
+  "Question",
+  "Answer",
+  "HowTo",
+  "HowToStep",
+  "HowToSection",
+  "HowToTool",
+  "HowToSupply",
+  "Organization",
+  "LocalBusiness",
+  "Person",
+  "Product",
+  "Offer",
+  "AggregateOffer",
+  "Review",
+  "AggregateRating",
+  "Rating",
+  "BreadcrumbList",
+  "ListItem",
+  "SoftwareApplication",
+  "WebApplication",
+  "MobileApplication",
+  "WebSite",
+  "WebPage",
+  "ItemPage",
+  "AboutPage",
+  "ContactPage",
+  "SearchResultsPage",
+  "ImageObject",
+  "VideoObject",
+  "AudioObject",
+  "MediaObject",
+  "Event",
+  "CreativeWork",
+  "Book",
+  "Course",
+  "Recipe",
+  "Dataset",
+  "SpeakableSpecification",
+  "SearchAction",
+  "EntryPoint",
+  "PostalAddress",
+  "GeoCoordinates",
+  "OpeningHoursSpecification",
+  "PriceSpecification",
+  "MonetaryAmount",
+  "ContactPoint",
+  "Brand",
+  "Intangible",
+  "Thing",
+  "Place"
+]