@automatelab/ai-seo-mcp 0.7.0 → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +21 -21
- package/dist/index.js +75 -75
- package/dist/tools/generate-pricing-md.js +1 -1
- package/dist/tools/save-audit-report.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -134,27 +134,27 @@ The Action builds the auditor from the pinned ref, runs `audit_page` on each URL
|
|
|
134
134
|
|
|
135
135
|
| Tool | Purpose |
|
|
136
136
|
|------|---------|
|
|
137
|
-
| `
|
|
138
|
-
| `
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
141
|
-
| `
|
|
142
|
-
| `
|
|
143
|
-
| `
|
|
144
|
-
| `
|
|
145
|
-
| `
|
|
146
|
-
| `
|
|
147
|
-
| `
|
|
148
|
-
| `
|
|
149
|
-
| `
|
|
150
|
-
| `
|
|
151
|
-
| `
|
|
152
|
-
| `
|
|
153
|
-
| `
|
|
154
|
-
| `
|
|
155
|
-
| `
|
|
156
|
-
|
|
157
|
-
> **v0.4.0** renamed tools from flat `snake_case` to dot-notation (`
|
|
137
|
+
| `audit_page` | Composite AI-SEO audit with 8-dimension scoring (schema, technical, structure, robots, freshness, authority, entity density, sitemap). |
|
|
138
|
+
| `audit_schema` | Validate JSON-LD against Schema.org rules and AI-citation best practice. Flags deprecated patterns. |
|
|
139
|
+
| `audit_canonical` | Canonical link integrity, trailing-slash hygiene, `og:url` consistency. |
|
|
140
|
+
| `audit_site` | Single-call site sweep: `audit_page` + `check_robots` + `check_sitemap` + `audit_schema` with overall grade and top-5 fixes. |
|
|
141
|
+
| `audit_sitemap` | Site-wide content audit: stride-sample N URLs from the sitemap, run `audit_page` on each, return distribution + worst pages + top findings. |
|
|
142
|
+
| `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. |
|
|
143
|
+
| `check_sitemap` | Validate XML sitemaps: presence, URL count, `lastmod` freshness, image/video extensions. |
|
|
144
|
+
| `check_technical` | HEAD tag audit: canonical, OpenGraph, Twitter Card, hreflang, HTTPS, noindex, title hygiene. |
|
|
145
|
+
| `score_ai_overview_eligibility` | Score a page's probability of appearing in Google AI Overviews using current correlation factors. |
|
|
146
|
+
| `score_citation_worthiness` | Score how citable a page or text block is for Perplexity, ChatGPT, Google AI Overviews, and Claude. Includes per-section `chunk_analysis` / `extractability_score`: how cleanly an LLM can lift a standalone answer from each heading. |
|
|
147
|
+
| `score_agentic_browsing` | Score a page against the Lighthouse "Agentic Browsing" category (May 2026): llms.txt, WebMCP, accessibility-tree integrity, and layout stability. |
|
|
148
|
+
| `score_test_citation` | Simulate "would an AI engine cite this for this query?" via MCP sampling, with deterministic heuristic fallback. |
|
|
149
|
+
| `llms_txt_generate` | Generate `llms.txt` and optionally `llms-full.txt` from a domain's sitemap. |
|
|
150
|
+
| `llms_txt_validate` | Lint an existing `llms.txt` for spec compliance and broken links. |
|
|
151
|
+
| `rewrite_aeo` | Rewrite content for Answer Engine Optimization (BLUF structure, FAQ format, schema additions). |
|
|
152
|
+
| `rewrite_geo` | Rewrite content for Generative Engine Optimization (entity definitions, comparison tables, synthesis-ready structure). |
|
|
153
|
+
| `extract_entities` | Extract named entities, `sameAs` links, and citation-density score from a page's content and structured data. |
|
|
154
|
+
| `diff_pages` | Compare two URLs for AI citation-worthiness: side-by-side dimension scores, gap analysis, and prioritized fix recommendations for url_a. |
|
|
155
|
+
| `report_save` | Render an `audit_page` / `audit_site` result as a Markdown report and write it to disk under `MCP_WORKSPACE_ROOT`. |
|
|
156
|
+
|
|
157
|
+
> **v0.4.0** renamed tools from flat `snake_case` to dot-notation (`audit_page`, `check_robots`, …) for a navigable hierarchy. Update any saved invocations.
|
|
158
158
|
|
|
159
159
|
Environment variables: see [ENV.md](./ENV.md).
|
|
160
160
|
|
package/dist/index.js
CHANGED
|
@@ -70,15 +70,15 @@ function wrapHandler(handler) {
|
|
|
70
70
|
// report.* - report rendering and storage
|
|
71
71
|
// Renamed in v0.4.0 from the previous flat snake_case names.
|
|
72
72
|
// ---------------------------------------------------------------------------
|
|
73
|
-
// ---
|
|
74
|
-
server.registerTool("
|
|
73
|
+
// --- audit_page ---
|
|
74
|
+
server.registerTool("audit_page", {
|
|
75
75
|
title: "Audit page (full)",
|
|
76
76
|
description: [
|
|
77
77
|
"Full AI-SEO audit of a single URL: returns categorized findings (info/warning/error) with severity, fix instructions, and a 0-100 composite score plus per-dimension subscores.",
|
|
78
78
|
"Read-only. Fetches the URL once and runs every sub-audit (schema, robots, technical, sitemap, AI-Overview eligibility) against the response. No writes, no third-party APIs, no auth required, no rate limits beyond polite per-host throttling.",
|
|
79
79
|
"Deterministic, rule-based scoring; no LLM calls. Same URL + same input flags returns the same score.",
|
|
80
80
|
"Supports `render: \"static\" | \"headless\"`. Default `static` (fast, raw HTML only). Use `headless` for React/Vue/Angular SPAs — adds 3-10s and requires the optional `playwright-core` peer dep plus a one-time `npx playwright install chromium`.",
|
|
81
|
-
"When to use: the default entry point for `audit any page`. Use this instead of calling
|
|
81
|
+
"When to use: the default entry point for `audit any page`. Use this instead of calling check_technical / audit_schema / check_robots / check_sitemap / score_ai_overview_eligibility individually unless you specifically need only one dimension - this tool composes all of them.",
|
|
82
82
|
].join("\n\n"),
|
|
83
83
|
inputSchema: auditPageInputSchema.shape,
|
|
84
84
|
outputSchema: auditPageOutputShape,
|
|
@@ -90,14 +90,14 @@ server.registerTool("audit.page", {
|
|
|
90
90
|
openWorldHint: true,
|
|
91
91
|
},
|
|
92
92
|
}, async (input) => wrapHandler(() => auditPage(input)));
|
|
93
|
-
// ---
|
|
94
|
-
server.registerTool("
|
|
93
|
+
// --- audit_schema ---
|
|
94
|
+
server.registerTool("audit_schema", {
|
|
95
95
|
title: "Audit JSON-LD schema",
|
|
96
96
|
description: [
|
|
97
97
|
"Validate JSON-LD structured data against Schema.org rules and AI-citation best practices. Accepts either a URL (fetched) or a raw JSON string (parsed directly).",
|
|
98
98
|
"Read-only when given `url` (one HTTP GET). Zero network when given `schema_json`. No writes.",
|
|
99
99
|
"Deterministic, rule-based; no LLM. Validates required/recommended properties, @context correctness, sameAs links, and AI-search-friendly patterns.",
|
|
100
|
-
"When to use: focused JSON-LD audits, or to validate a schema block you're about to ship. For a full page audit that includes schema + everything else, use `
|
|
100
|
+
"When to use: focused JSON-LD audits, or to validate a schema block you're about to ship. For a full page audit that includes schema + everything else, use `audit_page` instead.",
|
|
101
101
|
"Either `url` or `schema_json` must be provided (not both). If both are provided, `schema_json` wins and no fetch happens.",
|
|
102
102
|
].join("\n\n"),
|
|
103
103
|
inputSchema: {
|
|
@@ -130,14 +130,14 @@ server.registerTool("audit.schema", {
|
|
|
130
130
|
}
|
|
131
131
|
return wrapHandler(() => auditSchema(input));
|
|
132
132
|
});
|
|
133
|
-
// ---
|
|
134
|
-
server.registerTool("
|
|
133
|
+
// --- audit_canonical ---
|
|
134
|
+
server.registerTool("audit_canonical", {
|
|
135
135
|
title: "Audit canonical link integrity",
|
|
136
136
|
description: [
|
|
137
137
|
"Audit a page's canonical link integrity: presence, self-reference, cross-domain mismatches, trailing-slash hygiene, and og:url consistency.",
|
|
138
138
|
"Read-only. One HTTP GET to fetch the HEAD section.",
|
|
139
139
|
"Deterministic, rule-based; no LLM.",
|
|
140
|
-
"When to use: a focused canonical-only audit (e.g. debugging a duplicate-content issue). For a full HEAD audit including OpenGraph, hreflang, noindex, title, use `
|
|
140
|
+
"When to use: a focused canonical-only audit (e.g. debugging a duplicate-content issue). For a full HEAD audit including OpenGraph, hreflang, noindex, title, use `check_technical`. For everything-on-a-page, use `audit_page`.",
|
|
141
141
|
].join("\n\n"),
|
|
142
142
|
inputSchema: auditCanonicalInputSchema.shape,
|
|
143
143
|
outputSchema: auditCanonicalOutputShape,
|
|
@@ -149,14 +149,14 @@ server.registerTool("audit.canonical", {
|
|
|
149
149
|
openWorldHint: true,
|
|
150
150
|
},
|
|
151
151
|
}, async (input) => wrapHandler(() => auditCanonical(input)));
|
|
152
|
-
// ---
|
|
153
|
-
server.registerTool("
|
|
152
|
+
// --- check_robots ---
|
|
153
|
+
server.registerTool("check_robots", {
|
|
154
154
|
title: "Check robots.txt crawler posture",
|
|
155
155
|
description: [
|
|
156
156
|
"Fetch and parse a domain's robots.txt; report per-crawler allow/disallow posture for every known AI training crawler (GPTBot, CCBot, Anthropic-AI, Google-Extended, etc.), AI search crawlers (ChatGPT-User, PerplexityBot, OAI-SearchBot), and user-triggered fetchers.",
|
|
157
157
|
"Read-only. One HTTP GET to /robots.txt. No auth, no rate limits applied.",
|
|
158
158
|
"Deterministic, rule-based; no LLM. Returns structured findings with per-crawler status.",
|
|
159
|
-
"When to use: figuring out which AI crawlers a site blocks vs allows. Combine with `
|
|
159
|
+
"When to use: figuring out which AI crawlers a site blocks vs allows. Combine with `check_sitemap` for a full pre-crawl audit. Distinct from `audit_page` which evaluates a single URL; this evaluates a whole-domain policy.",
|
|
160
160
|
].join("\n\n"),
|
|
161
161
|
inputSchema: checkRobotsInputSchema.shape,
|
|
162
162
|
outputSchema: checkRobotsOutputShape,
|
|
@@ -168,14 +168,14 @@ server.registerTool("check.robots", {
|
|
|
168
168
|
openWorldHint: true,
|
|
169
169
|
},
|
|
170
170
|
}, async (input) => wrapHandler(() => checkRobots(input)));
|
|
171
|
-
// ---
|
|
172
|
-
server.registerTool("
|
|
171
|
+
// --- check_sitemap ---
|
|
172
|
+
server.registerTool("check_sitemap", {
|
|
173
173
|
title: "Check XML sitemap health",
|
|
174
174
|
description: [
|
|
175
175
|
"Validate a domain's XML sitemap: presence, accessibility, URL count, lastmod freshness, sitemap-index handling, and image/video sitemap extensions.",
|
|
176
176
|
"Read-only. Issues N+1 HTTP GETs: one for robots.txt + sitemap, then up to `max_urls_to_check` HEADs against sampled URLs.",
|
|
177
177
|
"Deterministic, rule-based; no LLM.",
|
|
178
|
-
"When to use: site-wide indexing audits. Pair with `
|
|
178
|
+
"When to use: site-wide indexing audits. Pair with `check_robots` for a full pre-crawl picture. For per-page checks, use `audit_page` or `check_technical` instead.",
|
|
179
179
|
].join("\n\n"),
|
|
180
180
|
inputSchema: checkSitemapInputSchema.shape,
|
|
181
181
|
outputSchema: checkSitemapOutputShape,
|
|
@@ -187,14 +187,14 @@ server.registerTool("check.sitemap", {
|
|
|
187
187
|
openWorldHint: true,
|
|
188
188
|
},
|
|
189
189
|
}, async (input) => wrapHandler(() => checkSitemap(input)));
|
|
190
|
-
// ---
|
|
191
|
-
server.registerTool("
|
|
190
|
+
// --- check_technical ---
|
|
191
|
+
server.registerTool("check_technical", {
|
|
192
192
|
title: "Check technical HEAD signals",
|
|
193
193
|
description: [
|
|
194
194
|
"Audit a page's HEAD section for technical signals relevant to AI crawlers: HTTPS, canonical, OpenGraph, Twitter Card, hreflang, noindex, and title-vs-H1 hygiene.",
|
|
195
195
|
"Read-only. One HTTP GET, inspects HEAD only (body is not parsed).",
|
|
196
196
|
"Deterministic, rule-based; no LLM.",
|
|
197
|
-
"When to use: when you specifically need HEAD-tag audit findings. For the full page including schema and AI-Overview scoring, use `
|
|
197
|
+
"When to use: when you specifically need HEAD-tag audit findings. For the full page including schema and AI-Overview scoring, use `audit_page`. For canonical-only, use `audit_canonical`.",
|
|
198
198
|
].join("\n\n"),
|
|
199
199
|
inputSchema: checkTechnicalInputSchema.shape,
|
|
200
200
|
outputSchema: checkTechnicalOutputShape,
|
|
@@ -206,14 +206,14 @@ server.registerTool("check.technical", {
|
|
|
206
206
|
openWorldHint: true,
|
|
207
207
|
},
|
|
208
208
|
}, async (input) => wrapHandler(() => checkTechnical(input)));
|
|
209
|
-
// ---
|
|
210
|
-
server.registerTool("
|
|
209
|
+
// --- score_ai_overview_eligibility ---
|
|
210
|
+
server.registerTool("score_ai_overview_eligibility", {
|
|
211
211
|
title: "Score AI Overview eligibility",
|
|
212
212
|
description: [
|
|
213
213
|
"Score a page's probability of appearing in Google AI Overviews. Returns an overall 0-100 score plus six factor subscores: semantic completeness, structured data, E-E-A-T signals, entity density, freshness, and technical hygiene.",
|
|
214
214
|
"Read-only. One HTTP GET.",
|
|
215
215
|
"Deterministic, rule-based scoring derived from published 2025-2026 AI-Overview correlation studies. No LLM calls. Same URL returns the same score on repeated runs.",
|
|
216
|
-
"When to use: AI-Overview-specific prioritization. For a multi-dimensional audit that includes this scoring plus everything else, use `
|
|
216
|
+
"When to use: AI-Overview-specific prioritization. For a multi-dimensional audit that includes this scoring plus everything else, use `audit_page`. For citation-worthiness of a specific text passage (rather than a URL ranking probability), use `score_citation_worthiness`.",
|
|
217
217
|
].join("\n\n"),
|
|
218
218
|
inputSchema: scoreAiOverviewEligibilityInputSchema.shape,
|
|
219
219
|
outputSchema: scoreAiOverviewOutputShape,
|
|
@@ -225,14 +225,14 @@ server.registerTool("score.ai_overview_eligibility", {
|
|
|
225
225
|
openWorldHint: true,
|
|
226
226
|
},
|
|
227
227
|
}, async (input) => wrapHandler(() => scoreAiOverviewEligibility(input)));
|
|
228
|
-
// ---
|
|
229
|
-
server.registerTool("
|
|
228
|
+
// --- score_agentic_browsing ---
|
|
229
|
+
server.registerTool("score_agentic_browsing", {
|
|
230
230
|
title: "Score Agentic Browsing readiness",
|
|
231
231
|
description: [
|
|
232
232
|
"Score a page against the four signals Google added to the Lighthouse \"Agentic Browsing\" category in May 2026: presence of an llms.txt, WebMCP integration, accessibility-tree integrity, and layout stability. Returns an overall 0-100 score, a letter grade, and a per-factor breakdown.",
|
|
233
233
|
"Read-only. One HTTP GET for the page plus one for /llms.txt (skip with check_llms_txt=false). Pass `html` instead of `url` to score markup offline (llms.txt is then treated as absent).",
|
|
234
234
|
"Deterministic, rule-based heuristics over the fetched HTML; no LLM and no headless render required. This approximates Lighthouse's runtime signals from static markup - it does not execute Lighthouse.",
|
|
235
|
-
"When to use: checking whether a site is ready for AI agents / agentic browsers, or tracking the new Lighthouse Agentic Browsing category. For citation-eligibility of content, use `
|
|
235
|
+
"When to use: checking whether a site is ready for AI agents / agentic browsers, or tracking the new Lighthouse Agentic Browsing category. For citation-eligibility of content, use `score_citation_worthiness`; for a full page audit, use `audit_page`.",
|
|
236
236
|
].join("\n\n"),
|
|
237
237
|
inputSchema: {
|
|
238
238
|
url: z.string().url().optional().describe("Public URL to fetch and score. Either this OR `html` is required."),
|
|
@@ -255,14 +255,14 @@ server.registerTool("score.agentic_browsing", {
|
|
|
255
255
|
}
|
|
256
256
|
return wrapHandler(() => scoreAgenticBrowsingTool(input));
|
|
257
257
|
});
|
|
258
|
-
// ---
|
|
259
|
-
server.registerTool("
|
|
258
|
+
// --- llms_txt_generate ---
|
|
259
|
+
server.registerTool("llms_txt_generate", {
|
|
260
260
|
title: "Generate llms.txt",
|
|
261
261
|
description: [
|
|
262
262
|
"Generate a spec-compliant llms.txt (and optionally llms-full.txt) for a domain by reading its sitemap, sampling up to `max_pages` pages, and synthesizing a grouped, sectioned summary.",
|
|
263
263
|
"Read-only. Issues one HTTP GET for the sitemap then one per sampled page.",
|
|
264
264
|
"Deterministic; no LLM. Output is the file content as a string - this tool does NOT write to disk or upload anywhere. The caller is responsible for hosting the resulting file at `https://<domain>/llms.txt`.",
|
|
265
|
-
"When to use: bootstrapping llms.txt for a site you own. To check an existing llms.txt, use `
|
|
265
|
+
"When to use: bootstrapping llms.txt for a site you own. To check an existing llms.txt, use `llms_txt_validate` instead.",
|
|
266
266
|
].join("\n\n"),
|
|
267
267
|
inputSchema: generateLlmsTxtInputSchema.shape,
|
|
268
268
|
outputSchema: generateLlmsTxtOutputShape,
|
|
@@ -274,8 +274,8 @@ server.registerTool("llms_txt.generate", {
|
|
|
274
274
|
openWorldHint: true,
|
|
275
275
|
},
|
|
276
276
|
}, async (input) => wrapHandler(() => generateLlmsTxtTool(input)));
|
|
277
|
-
// ---
|
|
278
|
-
server.registerTool("
|
|
277
|
+
// --- pricing_generate ---
|
|
278
|
+
server.registerTool("pricing_generate", {
|
|
279
279
|
title: "Generate pricing.md",
|
|
280
280
|
description: [
|
|
281
281
|
"Generate a machine-readable /pricing.md for AI shopping/agent flows. Finds the site's pricing page (or uses `pricing_url`), extracts named tiers and price lines, and returns the file content as a string.",
|
|
@@ -292,14 +292,14 @@ server.registerTool("pricing.generate", {
|
|
|
292
292
|
openWorldHint: true,
|
|
293
293
|
},
|
|
294
294
|
}, async (input) => wrapHandler(() => generatePricingMdTool(input)));
|
|
295
|
-
// ---
|
|
296
|
-
server.registerTool("
|
|
295
|
+
// --- llms_txt_validate ---
|
|
296
|
+
server.registerTool("llms_txt_validate", {
|
|
297
297
|
title: "Validate llms.txt",
|
|
298
298
|
description: [
|
|
299
299
|
"Validate an existing llms.txt or llms-full.txt against the spec: structure, section ordering, link format, and (optionally) broken-link detection.",
|
|
300
300
|
"Read-only. One HTTP GET when given `url`; zero network when given `content`. Optional link-check issues HEAD requests against each link if `check_links` is true.",
|
|
301
301
|
"Deterministic; no LLM.",
|
|
302
|
-
"When to use: auditing an llms.txt you already have. To generate one from scratch, use `
|
|
302
|
+
"When to use: auditing an llms.txt you already have. To generate one from scratch, use `llms_txt_generate`.",
|
|
303
303
|
"Either `url` or `content` must be provided.",
|
|
304
304
|
].join("\n\n"),
|
|
305
305
|
inputSchema: {
|
|
@@ -332,15 +332,15 @@ server.registerTool("llms_txt.validate", {
|
|
|
332
332
|
}
|
|
333
333
|
return wrapHandler(() => validateLlmsTxt(input));
|
|
334
334
|
});
|
|
335
|
-
// ---
|
|
336
|
-
server.registerTool("
|
|
335
|
+
// --- score_citation_worthiness ---
|
|
336
|
+
server.registerTool("score_citation_worthiness", {
|
|
337
337
|
title: "Score AI citation worthiness",
|
|
338
338
|
description: [
|
|
339
339
|
"Score how citable a page or text block is for AI engines (ChatGPT, Claude, Perplexity, Google AI Overviews). Evaluates BLUF (bottom-line-up-front) opening, FAQ patterns, statistic density, entity clarity, and answer-shape fit for the optional `target_query`.",
|
|
340
340
|
"Also returns `extractability_score` plus per-section `chunk_analysis`: how cleanly an LLM can lift a self-contained answer from each heading-delimited section (length band, lead-sentence directness, anaphora, concrete anchors). This is the GEO mechanic - it pinpoints the exact sections to tighten, with `most_extractable` / `least_extractable` called out.",
|
|
341
341
|
"Read-only when given `url` (one HTTP GET). Zero network when given `text`. No writes.",
|
|
342
342
|
"Deterministic, rule-based; no LLM calls. Returns reproducible scores.",
|
|
343
|
-
"When to use: pre-publish content QA, or to triage which existing pages are worth optimizing for AI citation first. Distinct from `
|
|
343
|
+
"When to use: pre-publish content QA, or to triage which existing pages are worth optimizing for AI citation first. Distinct from `score_ai_overview_eligibility` which scores Google-AI-Overview ranking probability for a URL; this scores the inherent citability of a text passage regardless of host.",
|
|
344
344
|
"Either `url` or `text` must be provided.",
|
|
345
345
|
].join("\n\n"),
|
|
346
346
|
inputSchema: {
|
|
@@ -377,14 +377,14 @@ server.registerTool("score.citation_worthiness", {
|
|
|
377
377
|
}
|
|
378
378
|
return wrapHandler(() => scoreCitationWorthiness(input));
|
|
379
379
|
});
|
|
380
|
-
// ---
|
|
381
|
-
server.registerTool("
|
|
380
|
+
// --- rewrite_aeo ---
|
|
381
|
+
server.registerTool("rewrite_aeo", {
|
|
382
382
|
title: "Rewrite for Answer Engine Optimization",
|
|
383
383
|
description: [
|
|
384
384
|
"Rewrite a content block for Answer Engine Optimization. Adds a BLUF opening, FAQ structure, schema additions, and concise question-shaped headings tuned for ChatGPT / Perplexity / Google AI Overviews.",
|
|
385
385
|
"Read-only when given `url` (one HTTP GET). Zero network when given `text`. The tool does NOT write back to the URL - it only returns the rewritten content as a string. No side effects on the source.",
|
|
386
386
|
"This tool delegates the actual rewrite to the calling LLM via MCP sampling - it does not call any external API itself. The MCP host's model produces the rewrite. Same input may produce different output across runs (model-dependent).",
|
|
387
|
-
"When to use: optimizing content for direct-answer surfaces (definitions, how-tos, FAQs). For Generative Engine Optimization (entity-rich, comparison-ready synthesis), use `
|
|
387
|
+
"When to use: optimizing content for direct-answer surfaces (definitions, how-tos, FAQs). For Generative Engine Optimization (entity-rich, comparison-ready synthesis), use `rewrite_geo` instead.",
|
|
388
388
|
"Either `url` or `text` must be provided. `target_query` is required.",
|
|
389
389
|
].join("\n\n"),
|
|
390
390
|
inputSchema: {
|
|
@@ -433,14 +433,14 @@ server.registerTool("rewrite.aeo", {
|
|
|
433
433
|
}
|
|
434
434
|
return wrapHandler(() => rewriteForAeo(input, undefined, undefined, server));
|
|
435
435
|
});
|
|
436
|
-
// ---
|
|
437
|
-
server.registerTool("
|
|
436
|
+
// --- rewrite_geo ---
|
|
437
|
+
server.registerTool("rewrite_geo", {
|
|
438
438
|
title: "Rewrite for Generative Engine Optimization",
|
|
439
439
|
description: [
|
|
440
440
|
"Rewrite a content block for Generative Engine Optimization: entity-rich, comparison-ready, synthesis-friendly. Tuned for surfaces that summarize across sources (Perplexity, Google AI Mode, Claude search).",
|
|
441
441
|
"Read-only on input. Does NOT write back to the source URL - returns the rewritten content as a string.",
|
|
442
442
|
"This tool delegates the actual rewrite to the calling LLM via MCP sampling - it does not call any external API itself. The MCP host's model produces the rewrite. Output may vary across runs (model-dependent).",
|
|
443
|
-
"When to use: optimizing for synthesis-style answers across multiple sources. For direct-answer (BLUF + FAQ) optimization on a single page, use `
|
|
443
|
+
"When to use: optimizing for synthesis-style answers across multiple sources. For direct-answer (BLUF + FAQ) optimization on a single page, use `rewrite_aeo` instead.",
|
|
444
444
|
"Either `url` or `text` must be provided. `target_query` is required.",
|
|
445
445
|
].join("\n\n"),
|
|
446
446
|
inputSchema: {
|
|
@@ -489,14 +489,14 @@ server.registerTool("rewrite.geo", {
|
|
|
489
489
|
}
|
|
490
490
|
return wrapHandler(() => rewriteForGeo(input, undefined, undefined, server));
|
|
491
491
|
});
|
|
492
|
-
// ---
|
|
493
|
-
server.registerTool("
|
|
492
|
+
// --- extract_entities ---
|
|
493
|
+
server.registerTool("extract_entities", {
|
|
494
494
|
title: "Extract named entities and sameAs links",
|
|
495
495
|
description: [
|
|
496
496
|
"Extract named entities, linked concepts, and sameAs graph nodes from a page's content and structured data. Combines body-text NER with JSON-LD `@type` / `sameAs` walking.",
|
|
497
497
|
"Read-only when given `url` (one HTTP GET). Zero network when given `text`.",
|
|
498
498
|
"Primary path: MCP sampling - the host LLM does the NER and returns typed entities with sameAs URIs. Fallback path: deterministic regex-based extractor when sampling is unavailable. The result includes `mode: \"sampling\" | \"regex_fallback\"` so callers can tell which path ran.",
|
|
499
|
-
"When to use: building an entity map for schema generation, or auditing whether a page's entities match its target topic. To validate the JSON-LD itself, use `
|
|
499
|
+
"When to use: building an entity map for schema generation, or auditing whether a page's entities match its target topic. To validate the JSON-LD itself, use `audit_schema`.",
|
|
500
500
|
"Either `url` or `text` must be provided.",
|
|
501
501
|
].join("\n\n"),
|
|
502
502
|
inputSchema: {
|
|
@@ -535,14 +535,14 @@ server.registerTool("extract.entities", {
|
|
|
535
535
|
}
|
|
536
536
|
return wrapHandler(() => extractEntities(input, undefined, undefined, server));
|
|
537
537
|
});
|
|
538
|
-
// ---
|
|
539
|
-
server.registerTool("
|
|
538
|
+
// --- score_test_citation ---
|
|
539
|
+
server.registerTool("score_test_citation", {
|
|
540
540
|
title: "Test whether an AI engine would cite this page",
|
|
541
541
|
description: [
|
|
542
542
|
"Simulate `would an AI engine cite this page for this query?`. The host LLM role-plays the chosen engine (chatgpt / claude / perplexity / google_ai_overviews / any), reads the page content, and returns a cite/no-cite verdict with the verbatim excerpt it would surface plus ranked improvements.",
|
|
543
543
|
"Read-only when given `url` (one HTTP GET). Zero network when given `text`.",
|
|
544
|
-
"Primary path uses MCP sampling. If the host doesn't support sampling, falls back to a deterministic heuristic derived from `
|
|
545
|
-
"When to use: pre-publish gut-check for a specific query, or auditing whether existing content earns citation surface. Distinct from `
|
|
544
|
+
"Primary path uses MCP sampling. If the host doesn't support sampling, falls back to a deterministic heuristic derived from `score_citation_worthiness` (overall_score + per-engine subscore must both clear thresholds). The result includes `mode: \"sampling\" | \"static_heuristic\"` so callers can tell which path ran.",
|
|
545
|
+
"When to use: pre-publish gut-check for a specific query, or auditing whether existing content earns citation surface. Distinct from `score_citation_worthiness` (deterministic 0-100 score) and `audit_page` (whole-page rubric); this returns a binary cite/no-cite verdict tied to one query.",
|
|
546
546
|
"Either `url` or `text` must be provided. `target_query` is required.",
|
|
547
547
|
].join("\n\n"),
|
|
548
548
|
inputSchema: {
|
|
@@ -585,15 +585,15 @@ server.registerTool("score.test_citation", {
|
|
|
585
585
|
}
|
|
586
586
|
return wrapHandler(() => testCitation(input, undefined, undefined, server));
|
|
587
587
|
});
|
|
588
|
-
// ---
|
|
589
|
-
server.registerTool("
|
|
588
|
+
// --- diff_pages ---
|
|
589
|
+
server.registerTool("diff_pages", {
|
|
590
590
|
title: "Diff two pages for citation-worthiness",
|
|
591
591
|
description: [
|
|
592
592
|
"Compare two URLs for AI citation-worthiness and return a structured breakdown of which page is more likely to be cited and why. Typical use: your page (url_a) vs a competitor's page (url_b).",
|
|
593
|
-
"Read-only. Runs
|
|
593
|
+
"Read-only. Runs audit_page on both URLs in parallel (2 HTTP fetches per URL), then diffs dimension_scores and findings. No new fetch logic beyond what audit_page already does.",
|
|
594
594
|
"Deterministic, rule-based; no LLM calls. Same two URLs return the same comparison on repeated runs.",
|
|
595
|
-
"When to use: competitive gap analysis - understand exactly which dimensions (schema, structure, robots, entity density, freshness, technical, authority, sitemap) put a competitor ahead, and get prioritized fix_recommendations_for_a to close the gap. For a single-URL audit, use
|
|
596
|
-
"Capped at 2 URLs per call. Heuristic verdict - does not claim to know what AI assistants actually cite; verdict matches
|
|
595
|
+
"When to use: competitive gap analysis - understand exactly which dimensions (schema, structure, robots, entity density, freshness, technical, authority, sitemap) put a competitor ahead, and get prioritized fix_recommendations_for_a to close the gap. For a single-URL audit, use audit_page. For overall scoring of one page, use score_citation_worthiness.",
|
|
596
|
+
"Capped at 2 URLs per call. Heuristic verdict - does not claim to know what AI assistants actually cite; verdict matches audit_page's existing rubric.",
|
|
597
597
|
].join("\n\n"),
|
|
598
598
|
inputSchema: diffPagesInputSchema.shape,
|
|
599
599
|
outputSchema: diffPagesOutputShape,
|
|
@@ -605,14 +605,14 @@ server.registerTool("diff.pages", {
|
|
|
605
605
|
openWorldHint: true,
|
|
606
606
|
},
|
|
607
607
|
}, async (input) => wrapHandler(() => diffPages(input)));
|
|
608
|
-
// ---
|
|
609
|
-
server.registerTool("
|
|
608
|
+
// --- audit_site ---
|
|
609
|
+
server.registerTool("audit_site", {
|
|
610
610
|
title: "Audit site (homepage + robots + sitemap + schema)",
|
|
611
611
|
description: [
|
|
612
|
-
"Single-call site sweep: runs
|
|
613
|
-
"Read-only. Issues several HTTP GETs against the domain (homepage fetch, robots.txt, sitemap.xml, and up to 50 sitemap URL HEAD checks); no writes, no auth required, no rate limits beyond polite per-host throttling. The homepage GET is deduplicated across
|
|
614
|
-
"Output: domain, homepage_url, fetched_at, overall_score (0–100), overall_grade, top_5_fixes (Finding[]), and a parts breakdown with individual
|
|
615
|
-
"When to use: quick 'how does this site look overall?' — use when you want a single consolidated score and actionable fix list without calling 4 tools individually. Distinct from
|
|
612
|
+
"Single-call site sweep: runs audit_page (homepage), check_robots, check_sitemap, and audit_schema in parallel and returns an overall grade (A–F) plus top-5 highest-impact fixes.",
|
|
613
|
+
"Read-only. Issues several HTTP GETs against the domain (homepage fetch, robots.txt, sitemap.xml, and up to 50 sitemap URL HEAD checks); no writes, no auth required, no rate limits beyond polite per-host throttling. The homepage GET is deduplicated across audit_page and audit_schema (~2 network fetches for 4 logical checks). Deterministic, rule-based scoring; no LLM calls. Same domain returns the same grade on repeated runs given unchanged content.",
|
|
614
|
+
"Output: domain, homepage_url, fetched_at, overall_score (0–100), overall_grade, top_5_fixes (Finding[]), and a parts breakdown with individual audit_page, check_robots, check_sitemap, and audit_schema results — each may be a full result or { error: string } when that sub-audit fails.",
|
|
615
|
+
"When to use: quick 'how does this site look overall?' — use when you want a single consolidated score and actionable fix list without calling 4 tools individually. Distinct from audit_sitemap (samples N pages from the sitemap, not just the homepage) and audit_page (single-URL deep dive with all findings, not just top-5).",
|
|
616
616
|
].join("\n\n"),
|
|
617
617
|
inputSchema: auditSiteInputSchema.shape,
|
|
618
618
|
outputSchema: auditSiteOutputShape,
|
|
@@ -624,14 +624,14 @@ server.registerTool("audit.site", {
|
|
|
624
624
|
openWorldHint: true,
|
|
625
625
|
},
|
|
626
626
|
}, async (input) => wrapHandler(() => auditSite(input)));
|
|
627
|
-
// ---
|
|
628
|
-
server.registerTool("
|
|
627
|
+
// --- audit_sitemap ---
|
|
628
|
+
server.registerTool("audit_sitemap", {
|
|
629
629
|
title: "Audit a site's content by sampling its sitemap",
|
|
630
630
|
description: [
|
|
631
|
-
"Site-wide content audit: discovers the sitemap, samples N URLs by deterministic uniform stride, runs
|
|
632
|
-
"Read-only. One HTTP GET for sitemap discovery, optionally a few more for sitemap-index children, then `sample_size` ×
|
|
631
|
+
"Site-wide content audit: discovers the sitemap, samples N URLs by deterministic uniform stride, runs audit_page on each, and returns score distribution + worst pages + most-common findings.",
|
|
632
|
+
"Read-only. One HTTP GET for sitemap discovery, optionally a few more for sitemap-index children, then `sample_size` × audit_page calls (each one HTTP GET + parsing). Polite throttling is enforced per host.",
|
|
633
633
|
"Deterministic — same domain + same sample_size returns the same set of URLs (uniform-stride sampling). Per-page scoring is rule-based; no LLM.",
|
|
634
|
-
"When to use: portfolio-level health check across a site (\"how does our content score on average?\"). Distinct from `
|
|
634
|
+
"When to use: portfolio-level health check across a site (\"how does our content score on average?\"). Distinct from `audit_site` (homepage-only composite) and `check_sitemap` (validates sitemap.xml structure, not page content).",
|
|
635
635
|
].join("\n\n"),
|
|
636
636
|
inputSchema: auditSitemapInputSchema.shape,
|
|
637
637
|
outputSchema: auditSitemapOutputShape,
|
|
@@ -643,10 +643,10 @@ server.registerTool("audit.sitemap", {
|
|
|
643
643
|
openWorldHint: true,
|
|
644
644
|
},
|
|
645
645
|
}, async (input) => wrapHandler(() => auditSitemap(input)));
|
|
646
|
-
// ---
|
|
647
|
-
server.registerTool("
|
|
646
|
+
// --- report_save ---
|
|
647
|
+
server.registerTool("report_save", {
|
|
648
648
|
title: "Save audit report to disk",
|
|
649
|
-
description: "Render an
|
|
649
|
+
description: "Render an audit_page or audit_site result as a Markdown report and write it to a file under MCP_WORKSPACE_ROOT (defaults to cwd).",
|
|
650
650
|
inputSchema: saveAuditReportInputSchema.shape,
|
|
651
651
|
outputSchema: saveReportOutputShape,
|
|
652
652
|
annotations: {
|
|
@@ -670,9 +670,9 @@ server.prompt("audit_my_homepage", "Run a full AI-SEO audit of a site's homepage
|
|
|
670
670
|
role: "user",
|
|
671
671
|
content: {
|
|
672
672
|
type: "text",
|
|
673
|
-
text: `Call the \`
|
|
673
|
+
text: `Call the \`audit_site\` tool with domain="${domain}" and respect_robots=true. ` +
|
|
674
674
|
`When the result returns, summarize the overall_grade, the top_5_fixes (highest-impact first), ` +
|
|
675
|
-
`and the content_quality from the underlying
|
|
675
|
+
`and the content_quality from the underlying audit_page. Recommend the single most leveraged fix first.`,
|
|
676
676
|
},
|
|
677
677
|
},
|
|
678
678
|
],
|
|
@@ -683,7 +683,7 @@ server.prompt("find_citation_blockers", "Audit a URL and surface only the critic
|
|
|
683
683
|
role: "user",
|
|
684
684
|
content: {
|
|
685
685
|
type: "text",
|
|
686
|
-
text: `Call \`
|
|
686
|
+
text: `Call \`audit_page\` with url="${url}" and respect_robots=true. ` +
|
|
687
687
|
`From the result, filter findings to severity="critical" only. ` +
|
|
688
688
|
`Group them by category and present a prioritized fix list. ` +
|
|
689
689
|
`Ignore warnings and info-level findings for this pass.`,
|
|
@@ -697,7 +697,7 @@ server.prompt("generate_llms_txt_for_domain", "Generate a valid llms.txt for a d
|
|
|
697
697
|
role: "user",
|
|
698
698
|
content: {
|
|
699
699
|
type: "text",
|
|
700
|
-
text: `Call \`
|
|
700
|
+
text: `Call \`llms_txt_generate\` with domain="${domain}", max_pages=50, include_full=false. ` +
|
|
701
701
|
`Return the generated llms.txt verbatim in a code block, then summarize how many pages were indexed.`,
|
|
702
702
|
},
|
|
703
703
|
},
|
|
@@ -709,7 +709,7 @@ server.prompt("check_ai_crawler_access", "Report which AI training and search cr
|
|
|
709
709
|
role: "user",
|
|
710
710
|
content: {
|
|
711
711
|
type: "text",
|
|
712
|
-
text: `Call \`
|
|
712
|
+
text: `Call \`check_robots\` with domain="${domain}". ` +
|
|
713
713
|
`From the result, build a table grouped by training_crawlers / search_crawlers / user_triggered, ` +
|
|
714
714
|
`with one row per crawler and an allowed/blocked verdict. ` +
|
|
715
715
|
`Highlight any AI search crawlers that are blocked - those silently kill citation surface.`,
|
|
@@ -726,7 +726,7 @@ server.prompt("score_my_citation_worthiness", "Score how citable a URL is for AI
|
|
|
726
726
|
role: "user",
|
|
727
727
|
content: {
|
|
728
728
|
type: "text",
|
|
729
|
-
text: `Call \`
|
|
729
|
+
text: `Call \`score_citation_worthiness\` with url="${url}", target_query="${target_query}", respect_robots=true. ` +
|
|
730
730
|
`Present overall_score and per-engine scores (Perplexity, ChatGPT, Google AI Overviews, Claude). ` +
|
|
731
731
|
`Then suggest the 3 most impactful structural changes (BLUF opening, FAQ blocks, entity density) to lift the lowest score.`,
|
|
732
732
|
},
|
|
@@ -782,7 +782,7 @@ robots.txt allows OAI-SearchBot, PerplexityBot, Claude-SearchBot. Blocking train
|
|
|
782
782
|
## 13. Sitemap freshness
|
|
783
783
|
XML sitemap present, lastmod >80% coverage, listed in robots.txt.
|
|
784
784
|
|
|
785
|
-
Use \`
|
|
785
|
+
Use \`audit_page\` to score a URL across all 13 signals at once.
|
|
786
786
|
`;
|
|
787
787
|
const CRAWLERS_DOC = `# AI crawlers reference
|
|
788
788
|
|
|
@@ -836,7 +836,7 @@ Allow: /
|
|
|
836
836
|
\`\`\`
|
|
837
837
|
(Blocks training, allows everything else - including search crawlers.)
|
|
838
838
|
|
|
839
|
-
Use \`
|
|
839
|
+
Use \`check_robots\` to see your current posture per crawler.
|
|
840
840
|
`;
|
|
841
841
|
server.resource("ai-citation-signals", "ai-citation://signals", { mimeType: "text/markdown", description: "The 13 signals AI assistants use to decide what to cite, with examples." }, async (uri) => ({
|
|
842
842
|
contents: [{ uri: uri.href, mimeType: "text/markdown", text: SIGNALS_DOC }],
|
|
@@ -5,7 +5,7 @@ import { z } from "zod";
|
|
|
5
5
|
import { writeFile, mkdir } from "node:fs/promises";
|
|
6
6
|
import { dirname, isAbsolute, resolve, sep, relative } from "node:path";
|
|
7
7
|
export const saveAuditReportInputSchema = z.object({
|
|
8
|
-
audit_result: z.unknown().describe("The return value of `
|
|
8
|
+
audit_result: z.unknown().describe("The return value of `audit_page` or `audit_site`. Pass the structured result verbatim - the tool detects which shape it is and renders the matching Markdown report."),
|
|
9
9
|
path: z.string().min(1).describe("Target file path. May be relative to MCP_WORKSPACE_ROOT (or cwd if unset). Paths that escape the workspace root are rejected."),
|
|
10
10
|
overwrite: z.boolean().optional().default(true).describe("If true (default), overwrite an existing file. If false, the write fails when the target already exists."),
|
|
11
11
|
});
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@automatelab/ai-seo-mcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"mcpName": "io.github.AutomateLab-tech/ai-seo-mcp",
|
|
5
5
|
"description": "AI Citation Toolkit - audit, score, and rewrite web pages for AI-citation eligibility. AEO/GEO/LLM visibility for any MCP client.",
|
|
6
6
|
"license": "MIT",
|