@automatelab/ai-seo-mcp 0.3.0 → 0.4.1

package/README.md

@@ -17,7 +17,7 @@ Works inside Claude, Cursor, Windsurf, Codex, and any MCP client that speaks std
 - **AI crawler access** - GPTBot, OAI-SearchBot, ClaudeBot, and PerplexityBot allowed or blocked in `robots.txt`
 - **`llms.txt`** - present, spec-compliant, links alive
 - **Structured answer extraction** - FAQ headings, BLUF paragraphs, answer-ready blocks
-- **Schema completeness** - FAQPage, Article, Organization, Person; flags deprecated patterns
+- **[[schema]] completeness** - FAQPage, Article, Organization, Person; flags deprecated patterns
 - **Entity clarity** - named entity density and `sameAs` coverage that help AI systems identify the subject
 - **Citation formatting** - canonical URL hygiene, `og:url`, `hreflang`, noindex traps
 - **Sitemap freshness** - `lastmod` signals that tell crawlers the page is current
@@ -26,13 +26,13 @@ Works inside Claude, Cursor, Windsurf, Codex, and any MCP client that speaks std
 
 ## Run an audit. Get a list of citation-blockers, ranked.
 
-> **You:** Run an AI-SEO audit on `https://automatelab.tech/how-to-connect-zapier-to-notion`.
+> **You:** Run an AI-SEO audit on `https://automatelab.tech/launching-the-ai-seo-mcp/`.
 
 Result (truncated):
 
 ```json
 {
-  "url": "https://automatelab.tech/how-to-connect-zapier-to-notion",
+  "url": "https://automatelab.tech/launching-the-ai-seo-mcp/",
   "score": 61,
   "grade": "C",
   "dimension_scores": {
@@ -88,6 +88,19 @@ Add to `%APPDATA%\Claude\claude_desktop_config.json` (Windows) or `~/Library/App
 
 Restart Claude Desktop. Any MCP client that supports stdio transport works - same `command` / `args` pattern.
 
+### Optional: headless rendering for SPAs
+
+By default `audit_page` reads raw HTML — fast, but misses content on React/Vue/Angular SPAs. Pass `render: "headless"` to spin up Chromium and audit the rendered DOM (adds 3-10s per audit).
+
+One-time install:
+
+```bash
+npm install playwright-core
+npx playwright install chromium
+```
+
+Then call `audit_page` with `render: "headless"`. Use static for everything else — most marketing sites and docs render fine without it.
+
 ---
 
 ## Further reading
@@ -97,24 +110,30 @@ Restart Claude Desktop. Any MCP client that supports stdio transport works - sam
 ---
 
 <details>
-<summary>All 14 tools</summary>
+<summary>MCP tool surface (18 tools)</summary>
 
 | Tool | Purpose |
 |------|---------|
-| `audit_page` | Composite AI-SEO audit with 8-dimension scoring (schema, technical, structure, robots, freshness, authority, entity density, sitemap). |
-| `audit_schema` | Validate JSON-LD against Schema.org rules and AI-citation best practice. Flags deprecated patterns. |
-| `audit_canonical` | Canonical link integrity, trailing-slash hygiene, `og:url` consistency. |
-| `check_robots` | Parse `robots.txt` and report per-crawler allow/disallow for all known AI crawlers. Surfaces the GPTBot-blocked-but-OAI-SearchBot-allowed trap. |
-| `check_sitemap` | Validate XML sitemaps: presence, URL count, `lastmod` freshness, image/video extensions. |
-| `check_technical` | HEAD tag audit: canonical, OpenGraph, Twitter Card, hreflang, HTTPS, noindex, title hygiene. |
-| `score_ai_overview_eligibility` | Score a page's probability of appearing in Google AI Overviews using current correlation factors. |
-| `generate_llms_txt` | Generate `llms.txt` and optionally `llms-full.txt` from a domain's sitemap. |
-| `validate_llms_txt` | Lint an existing `llms.txt` for spec compliance and broken links. |
-| `score_citation_worthiness` | Score how citable a page or text block is for Perplexity, ChatGPT, Google AI Overviews, and Claude. |
-| `rewrite_for_aeo` | Rewrite content for Answer Engine Optimization (BLUF structure, FAQ format, schema additions). |
-| `rewrite_for_geo` | Rewrite content for Generative Engine Optimization (entity definitions, comparison tables, synthesis-ready structure). |
-| `extract_entities` | Extract named entities, `sameAs` links, and citation-density score from a page's content and structured data. |
-| `diff_pages` | Compare two URLs for AI citation-worthiness: side-by-side dimension scores, gap analysis, and prioritized fix recommendations for url_a. |
+| `audit.page` | Composite AI-SEO audit with 8-dimension scoring (schema, technical, structure, robots, freshness, authority, entity density, sitemap). |
+| `audit.schema` | Validate JSON-LD against Schema.org rules and AI-citation best practice. Flags deprecated patterns. |
+| `audit.canonical` | Canonical link integrity, trailing-slash hygiene, `og:url` consistency. |
+| `audit.site` | Single-call site sweep: `audit.page` + `check.robots` + `check.sitemap` + `audit.schema` with overall grade and top-5 fixes. |
+| `audit.sitemap` | Site-wide content audit: stride-sample N URLs from the sitemap, run `audit.page` on each, return distribution + worst pages + top findings. |
+| `check.robots` | Parse `robots.txt` and report per-crawler allow/disallow for all known AI crawlers. Surfaces the GPTBot-blocked-but-OAI-SearchBot-allowed trap. |
+| `check.sitemap` | Validate XML sitemaps: presence, URL count, `lastmod` freshness, image/video extensions. |
+| `check.technical` | HEAD tag audit: canonical, OpenGraph, Twitter Card, hreflang, HTTPS, noindex, title hygiene. |
+| `score.ai_overview_eligibility` | Score a page's probability of appearing in Google AI Overviews using current correlation factors. |
+| `score.citation_worthiness` | Score how citable a page or text block is for Perplexity, ChatGPT, Google AI Overviews, and Claude. |
+| `score.test_citation` | Simulate "would an AI engine cite this for this query?" via MCP sampling, with deterministic heuristic fallback. |
+| `llms_txt.generate` | Generate `llms.txt` and optionally `llms-full.txt` from a domain's sitemap. |
+| `llms_txt.validate` | Lint an existing `llms.txt` for spec compliance and broken links. |
+| `rewrite.aeo` | Rewrite content for Answer Engine Optimization (BLUF structure, FAQ format, schema additions). |
+| `rewrite.geo` | Rewrite content for Generative Engine Optimization (entity definitions, comparison tables, synthesis-ready structure). |
+| `extract.entities` | Extract named entities, `sameAs` links, and citation-density score from a page's content and structured data. |
+| `diff.pages` | Compare two URLs for AI citation-worthiness: side-by-side dimension scores, gap analysis, and prioritized fix recommendations for url_a. |
+| `report.save` | Render an `audit.page` / `audit.site` result as a Markdown report and write it to disk under `MCP_WORKSPACE_ROOT`. |
+
+> **v0.4.0** renamed tools from flat `snake_case` to dot-notation (`audit.page`, `check.robots`, …) for a navigable hierarchy. Update any saved invocations.
 
 Environment variables: see [ENV.md](./ENV.md).
 

package/dist/cli/audit-cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=audit-cli.d.ts.map

package/dist/cli/audit-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-cli.d.ts","sourceRoot":"","sources":["../../src/cli/audit-cli.ts"],"names":[],"mappings":""}

package/dist/cli/audit-cli.js

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// CLI wrapper around audit_page / audit_site, used by the ai-seo GitHub Action.
+// Not part of the MCP protocol; reads flags and prints results to stdout/stderr.
+//
+// Usage:
+//   ai-seo-audit --urls "https://a.com,https://b.com/post" [--min-score 70] [--respect-robots true] [--report-path report.md]
+//
+// Exit code:
+//   0  all audited URLs scored >= min-score
+//   1  any URL scored < min-score (regression)
+//   2  bad arguments / runtime error
+import { appendFileSync } from "node:fs";
+import { auditPage } from "../tools/audit-page.js";
+import { saveAuditReport } from "../tools/save-audit-report.js";
+function parseArgs(argv) {
+    const args = {
+        urls: [],
+        minScore: 70,
+        respectRobots: true,
+        reportPath: null,
+        failOnRegression: true,
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = () => {
+            const v = argv[i + 1];
+            if (v === undefined)
+                throw new Error(`flag ${a} requires a value`);
+            i++;
+            return v;
+        };
+        switch (a) {
+            case "--urls":
+                args.urls = next().split(",").map((s) => s.trim()).filter(Boolean);
+                break;
+            case "--min-score":
+                args.minScore = Number(next());
+                break;
+            case "--respect-robots":
+                args.respectRobots = next().toLowerCase() !== "false";
+                break;
+            case "--report-path":
+                args.reportPath = next();
+                break;
+            case "--fail-on-regression":
+                args.failOnRegression = next().toLowerCase() !== "false";
+                break;
+            case "--help":
+            case "-h":
+                console.log("Usage: ai-seo-audit --urls <csv> [--min-score N] [--respect-robots true|false] [--report-path FILE] [--fail-on-regression true|false]");
+                process.exit(0);
+                break;
+            default:
+                throw new Error(`unknown flag: ${a}`);
+        }
+    }
+    if (args.urls.length === 0)
+        throw new Error("at least one URL is required via --urls");
+    if (!Number.isFinite(args.minScore))
+        throw new Error("--min-score must be a number");
+    return args;
+}
+function emitGithubOutput(key, value) {
+    const file = process.env["GITHUB_OUTPUT"];
+    if (!file)
+        return;
+    const safe = String(value).replace(/\r?\n/g, " ");
+    try {
+        appendFileSync(file, `${key}=${safe}\n`);
+    }
+    catch {
+        // best-effort; CI step will still see stdout/stderr
+    }
+}
+async function main() {
+    let args;
+    try {
+        args = parseArgs(process.argv.slice(2));
+    }
+    catch (err) {
+        console.error("[ai-seo-audit] argument error:", err instanceof Error ? err.message : String(err));
+        process.exit(2);
+    }
+    const results = [];
+    let anyBelow = false;
+    let minObserved = 100;
+    for (const url of args.urls) {
+        try {
+            const result = await auditPage({
+                url,
+                include_raw_html: false,
+                respect_robots: args.respectRobots,
+                generate_report: false,
+                render: "static",
+            });
+            const below = result.score < args.minScore;
+            if (below)
+                anyBelow = true;
+            if (result.score < minObserved)
+                minObserved = result.score;
+            console.log(`${below ? "❌" : "✅"} ${url} — score=${result.score} grade=${result.grade} quality=${result.content_quality}`);
+            results.push(result);
+        }
+        catch (err) {
+            console.error(`[ai-seo-audit] failed for ${url}:`, err instanceof Error ? err.message : String(err));
+            anyBelow = true;
+        }
+    }
+    if (args.reportPath && results.length > 0) {
+        // Save the first result; users who pass multiple URLs typically want one report per run,
+        // and the action wires --report-path to a single file. Multi-URL reporting can be added if asked.
+        try {
+            const saved = await saveAuditReport({
+                audit_result: results[0],
+                path: args.reportPath,
+                overwrite: true,
+            });
+            console.log(`[ai-seo-audit] wrote ${saved.bytes_written}b -> ${saved.saved_to}`);
+            emitGithubOutput("report_path", saved.saved_to);
+        }
+        catch (err) {
+            console.error("[ai-seo-audit] could not save report:", err instanceof Error ? err.message : String(err));
+        }
+    }
+    emitGithubOutput("min_score_observed", minObserved);
+    emitGithubOutput("urls_audited", results.length);
+    if (anyBelow && args.failOnRegression) {
+        process.exit(1);
+    }
+    process.exit(0);
+}
+main().catch((err) => {
+    console.error("[ai-seo-audit] fatal:", err);
+    process.exit(2);
+});
+//# sourceMappingURL=audit-cli.js.map

package/dist/cli/audit-cli.js.map

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