dotcms-custom-mcp 1.2.0 → 1.4.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.
Files changed (36) hide show
  1. package/README.md +77 -0
  2. package/dotcms.js +65 -1
  3. package/guides.js +277 -0
  4. package/index.js +418 -1
  5. package/package.json +2 -2
  6. package/seo.js +365 -0
  7. package/skills/NOTICE.md +17 -0
  8. package/skills/brightdata/LICENSE +21 -0
  9. package/skills/brightdata/skills/seo-audit/SKILL.md +109 -0
  10. package/skills/brightdata/skills/seo-audit/references/audit-framework.md +71 -0
  11. package/skills/brightdata/skills/seo-audit/references/bdata-recipes.md +551 -0
  12. package/skills/brightdata/skills/seo-audit/references/output-templates.md +107 -0
  13. package/skills/brightdata/skills/seo-audit/references/site-type-playbooks.md +113 -0
  14. package/skills/marketing/LICENSE +202 -0
  15. package/skills/marketing/skills/seo-audit/SKILL.md +190 -0
  16. package/skills/searchfit-seo/LICENSE +21 -0
  17. package/skills/searchfit-seo/agents/competitor-analyzer/AGENT.md +92 -0
  18. package/skills/searchfit-seo/agents/content-strategist/AGENT.md +122 -0
  19. package/skills/searchfit-seo/agents/seo-auditor/AGENT.md +110 -0
  20. package/skills/searchfit-seo/commands/create-content.md +98 -0
  21. package/skills/searchfit-seo/commands/create-topic.md +116 -0
  22. package/skills/searchfit-seo/commands/generate-schema.md +66 -0
  23. package/skills/searchfit-seo/commands/keyword-cluster.md +58 -0
  24. package/skills/searchfit-seo/commands/seo-check.md +80 -0
  25. package/skills/searchfit-seo/commands/translate-content.md +86 -0
  26. package/skills/searchfit-seo/skills/ai-visibility/SKILL.md +126 -0
  27. package/skills/searchfit-seo/skills/broken-links/SKILL.md +122 -0
  28. package/skills/searchfit-seo/skills/content-brief/SKILL.md +127 -0
  29. package/skills/searchfit-seo/skills/content-strategy/SKILL.md +137 -0
  30. package/skills/searchfit-seo/skills/content-translation/SKILL.md +142 -0
  31. package/skills/searchfit-seo/skills/internal-linking/SKILL.md +108 -0
  32. package/skills/searchfit-seo/skills/keyword-clustering/SKILL.md +117 -0
  33. package/skills/searchfit-seo/skills/on-page-seo/SKILL.md +111 -0
  34. package/skills/searchfit-seo/skills/schema-markup/SKILL.md +159 -0
  35. package/skills/searchfit-seo/skills/seo-audit/SKILL.md +109 -0
  36. package/skills/searchfit-seo/skills/technical-seo/SKILL.md +161 -0
package/seo.js ADDED
@@ -0,0 +1,365 @@
1
+ // SEO analysis of a dotCMS page or a content item. Pure functions: the server fetches the data,
2
+ // these decide what is wrong with it.
3
+ //
4
+ // Two sources, depending on what is analysed:
5
+ // - a regular (drag-and-drop) page: its SEO values live on the page itself
6
+ // - a detail page (URL-mapped content) or a content item: the values come from the content's
7
+ // fields, and its content type says which SEO fields exist at all
8
+ // When the public site URL is known, the rendered HTML is checked too (title tag, meta tags,
9
+ // headings, images), since that is what search engines actually see.
10
+
11
+ export const LIMITS = { titleMin: 30, titleMax: 60, descMin: 70, descMax: 160, urlMax: 75 };
12
+
13
+ const TITLE_FIELDS = ["seoTitle", "metaTitle", "title", "headline", "name"];
14
+ const DESC_FIELDS = ["seoDescription", "metaDescription", "description", "teaser", "summary", "abstract", "excerpt"];
15
+ const IMAGE_FIELDS = ["ogImage", "image", "heroImage", "mainImage", "featuredImage", "teaserImage", "thumbnail", "photo"];
16
+
17
+ const finding = (severity, id, message, where) => ({ severity, id, message, where });
18
+ const SEVERITY_ORDER = { error: 0, warning: 1, info: 2 };
19
+
20
+ const decode = (s) =>
21
+ s
22
+ .replace(/ /g, " ")
23
+ .replace(/"/g, '"')
24
+ .replace(/&#0?39;|'/g, "'")
25
+ .replace(/&lt;/g, "<")
26
+ .replace(/&gt;/g, ">")
27
+ .replace(/&amp;/g, "&");
28
+
29
+ /** Plain text of a field value (WYSIWYG fields hold HTML). */
30
+ const text = (v) => (typeof v === "string" ? decode(v.replace(/<[^>]*>/g, " ")).replace(/\s+/g, " ").trim() : "");
31
+
32
+ /** A site path from a path or a full URL; only the path is kept. Throws when it is not a plain path. */
33
+ export function normalizePagePath(input) {
34
+ const raw = String(input ?? "").trim();
35
+ if (!raw) throw new Error("Pass the page path, e.g. '/about-us'.");
36
+ // The URL parser would quietly resolve "/a/../b" to "/b": refuse dot segments in what was typed.
37
+ const typed = raw.replace(/^[a-z][a-z0-9+.-]*:\/\/[^/]*/i, "").split(/[?#]/)[0];
38
+ const dotSegment = typed.split("/").some((seg) => {
39
+ try {
40
+ const decoded = decodeURIComponent(seg);
41
+ return decoded === "." || decoded === "..";
42
+ } catch {
43
+ return true;
44
+ }
45
+ });
46
+ let pathname;
47
+ try {
48
+ pathname = new URL(raw, "http://placeholder.invalid").pathname;
49
+ } catch {
50
+ throw new Error(`Invalid path '${raw}'.`);
51
+ }
52
+ if (dotSegment || !/^\/[A-Za-z0-9\-._~/%@+]*$/.test(pathname) || /%(?![0-9A-Fa-f]{2})/.test(pathname)) {
53
+ throw new Error(`Invalid path '${raw}': use a site path such as '/blog/my-post'.`);
54
+ }
55
+ return pathname.length > 1 ? pathname.replace(/\/+$/, "") : pathname;
56
+ }
57
+
58
+ /** First non-empty text value among the named fields (case-insensitive). */
59
+ export function pickText(obj, names) {
60
+ if (!obj || typeof obj !== "object") return null;
61
+ const byLower = new Map(Object.keys(obj).map((k) => [k.toLowerCase(), k]));
62
+ for (const name of names) {
63
+ const key = byLower.get(name.toLowerCase());
64
+ const value = key ? text(obj[key]) : "";
65
+ if (value) return { field: key, value };
66
+ }
67
+ return null;
68
+ }
69
+
70
+ const IMAGE_NAME = /image|photo|picture|thumbnail|banner|hero/i;
71
+ const hasValue = (v) => (typeof v === "string" ? v.trim() !== "" && v !== "TITLE_IMAGE_NOT_FOUND" : !!v && typeof v === "object");
72
+
73
+ /** First image-like field that has a value: a well-known name first, then any field named like an image. */
74
+ function pickPresent(obj, names) {
75
+ if (!obj || typeof obj !== "object") return null;
76
+ const keys = Object.keys(obj);
77
+ const byLower = new Map(keys.map((k) => [k.toLowerCase(), k]));
78
+ for (const name of names) {
79
+ const key = byLower.get(name.toLowerCase());
80
+ if (key && hasValue(obj[key])) return key;
81
+ }
82
+ return keys.find((k) => IMAGE_NAME.test(k) && !/^(has|is)[A-Z]/.test(k) && hasValue(obj[k])) || null;
83
+ }
84
+
85
+ const NAME_LIKE = /title|name|headline/i;
86
+ const DESC_LIKE = /desc|summary|teaser|abstract|excerpt|overview/i;
87
+
88
+ /** The variable of a title or name field of a content type (dotCMS itself always generates a "title" value). */
89
+ function typeTitleField(ct) {
90
+ return typeField(ct, TITLE_FIELDS) || (ct?.fields || []).find((f) => f.variable && NAME_LIKE.test(f.variable))?.variable || null;
91
+ }
92
+
93
+ /** The variable of a description-like field of a content type. */
94
+ function typeDescriptionField(ct) {
95
+ return typeField(ct, DESC_FIELDS) || (ct?.fields || []).find((f) => f.variable && DESC_LIKE.test(f.variable))?.variable || null;
96
+ }
97
+
98
+ /** The variable of an image field of a content type: a well-known name, an image or binary field, or one named like an image. */
99
+ function typeImageField(ct) {
100
+ return (
101
+ typeField(ct, IMAGE_FIELDS) ||
102
+ (ct?.fields || []).find((f) => f.variable && (/(Image|Binary)Field$/.test(f.clazz || "") || IMAGE_NAME.test(f.variable)))?.variable ||
103
+ null
104
+ );
105
+ }
106
+
107
+ /** The variable of the first field of a content type that has one of these names. */
108
+ export function typeField(ct, names) {
109
+ const byLower = new Map((ct?.fields || []).filter((f) => f.variable).map((f) => [f.variable.toLowerCase(), f.variable]));
110
+ for (const name of names) {
111
+ const v = byLower.get(name.toLowerCase());
112
+ if (v) return v;
113
+ }
114
+ return null;
115
+ }
116
+
117
+ function lengthFindings(out, { id, label, value, min, max, where, severity = "warning" }) {
118
+ const n = [...value].length;
119
+ if (n < min) out.push(finding(severity, `${id}-short`, `${label} is ${n} characters; aim for ${min}–${max}.`, where));
120
+ else if (n > max) out.push(finding(severity, `${id}-long`, `${label} is ${n} characters; search results cut it off after about ${max}.`, where));
121
+ }
122
+
123
+ /** URL hygiene: readable, lowercase, hyphenated, not too long or deep. */
124
+ export function checkUrl(urlPath) {
125
+ const out = [];
126
+ const where = "url";
127
+ if (urlPath.length > LIMITS.urlMax) out.push(finding("warning", "url-long", `The URL is ${urlPath.length} characters; keep it under ${LIMITS.urlMax}.`, where));
128
+ if (/[A-Z]/.test(urlPath)) out.push(finding("warning", "url-uppercase", "The URL contains uppercase letters; search engines treat /Page and /page as different URLs.", where));
129
+ if (urlPath.includes("_")) out.push(finding("warning", "url-underscore", "The URL uses underscores; hyphens are read as word separators, underscores are not.", where));
130
+ if (/%20|\s/.test(urlPath)) out.push(finding("warning", "url-space", "The URL contains spaces.", where));
131
+ if (/\.(html?|php|aspx?|jsp)$/i.test(urlPath)) out.push(finding("info", "url-extension", "The URL ends in a file extension; extension-less URLs are cleaner.", where));
132
+ if (urlPath.split("/").filter(Boolean).length > 4) out.push(finding("info", "url-deep", "The URL is more than 4 levels deep.", where));
133
+ return out;
134
+ }
135
+
136
+ /**
137
+ * Checks of the values stored in dotCMS.
138
+ * kind: "page" | "detail-page" | "content"
139
+ * page / content: the page contentlet, or the (mapped) content item
140
+ * contentType: the content type entity of the content, when there is one
141
+ * htmlSeen: { title, description } — the rendered HTML has them, so field checks for them are skipped
142
+ */
143
+ export function analyzeFields({ kind, page, content, contentType, htmlSeen = {} }) {
144
+ const findings = [];
145
+ const source = kind === "page" ? page : content;
146
+ const where = kind === "page" ? "page fields" : `${contentType?.variable || "content"} fields`;
147
+
148
+ const title = pickText(source, TITLE_FIELDS);
149
+ const desc = pickText(source, DESC_FIELDS);
150
+ const image = kind === "page" ? null : pickPresent(source, IMAGE_FIELDS);
151
+
152
+ if (!htmlSeen.title) {
153
+ if (!title) findings.push(finding("error", "title-missing", "No title value found.", where));
154
+ // A content title is usually only part of the page <title> (the template adds more), so it is a note, not a warning.
155
+ else lengthFindings(findings, { id: "title", label: `Title (${title.field})`, value: title.value, min: LIMITS.titleMin, max: LIMITS.titleMax, where, severity: kind === "page" ? "warning" : "info" });
156
+ }
157
+ if (!htmlSeen.description) {
158
+ if (!desc) {
159
+ const hint = kind === "page" ? " Add one to the page, or make sure the template sets <meta name=\"description\">." : "";
160
+ findings.push(finding("warning", "description-missing", `No description value found.${hint}`, where));
161
+ } else {
162
+ lengthFindings(findings, { id: "description", label: `Description (${desc.field})`, value: desc.value, min: LIMITS.descMin, max: LIMITS.descMax, where });
163
+ }
164
+ }
165
+ if (title && desc && title.value.toLowerCase() === desc.value.toLowerCase()) {
166
+ findings.push(finding("warning", "title-equals-description", "The title and the description are identical.", where));
167
+ }
168
+ if (kind !== "page" && !image) {
169
+ findings.push(finding("info", "image-missing", "No image value found; shares of this page will have no preview picture.", where));
170
+ }
171
+
172
+ if (kind !== "page" && contentType) {
173
+ const v = contentType.variable;
174
+ const typeWhere = `content type ${v}`;
175
+ if (!typeTitleField(contentType)) findings.push(finding("warning", "type-no-title", `Content type ${v} has no field that looks like a title or name, so pages can only use the title dotCMS generates.`, typeWhere));
176
+ if (!typeDescriptionField(contentType)) findings.push(finding("warning", "type-no-description", `Content type ${v} has no description field, so its pages cannot carry a unique meta description.`, typeWhere));
177
+ if (!typeImageField(contentType)) findings.push(finding("info", "type-no-image", `Content type ${v} has no image field for social previews.`, typeWhere));
178
+ const pattern = contentType.urlMapPattern;
179
+ if (!pattern) {
180
+ if (kind === "content") findings.push(finding("warning", "type-not-mapped", `Content type ${v} has no URL map pattern, so its content has no page of its own for search engines.`, typeWhere));
181
+ } else if (/\{(identifier|inode)\}/i.test(pattern)) {
182
+ findings.push(finding("warning", "pattern-id", `The URL map pattern ${pattern} builds URLs from an id; a descriptive field such as a url title reads better and ranks better.`, typeWhere));
183
+ }
184
+ }
185
+
186
+ return {
187
+ findings,
188
+ data: {
189
+ title: title?.value,
190
+ titleField: title?.field,
191
+ description: desc?.value,
192
+ descriptionField: desc?.field,
193
+ imageField: image || undefined,
194
+ },
195
+ };
196
+ }
197
+
198
+ const attr = (tag, name) => {
199
+ const m = new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, "i").exec(tag);
200
+ return m ? (m[1] ?? m[2] ?? m[3] ?? "") : null;
201
+ };
202
+
203
+ /** Checks of the rendered page, the way a crawler reads it. */
204
+ export function analyzeHtml(html) {
205
+ const findings = [];
206
+ const where = "rendered HTML";
207
+
208
+ const titleMatch = /<title[^>]*>([\s\S]*?)<\/title>/i.exec(html);
209
+ const title = titleMatch ? text(titleMatch[1]) : "";
210
+ const metas = [...html.matchAll(/<meta\b[^>]*>/gi)].map((m) => m[0]);
211
+ const meta = (key, by = "name") => {
212
+ for (const tag of metas) if ((attr(tag, by) || "").toLowerCase() === key) return attr(tag, "content") ?? "";
213
+ return null;
214
+ };
215
+ const description = text(meta("description") ?? "");
216
+ const robots = (meta("robots") ?? "").toLowerCase();
217
+ const canonicalTag = [...html.matchAll(/<link\b[^>]*>/gi)].map((m) => m[0]).find((t) => /\bcanonical\b/i.test(attr(t, "rel") || ""));
218
+ const canonical = canonicalTag ? attr(canonicalTag, "href") : null;
219
+ const h1s = [...html.matchAll(/<h1\b[^>]*>([\s\S]*?)<\/h1>/gi)].map((m) => text(m[1]));
220
+ const imgs = [...html.matchAll(/<img\b[^>]*>/gi)].map((m) => m[0]);
221
+ const noAlt = imgs.filter((t) => attr(t, "alt") === null).length;
222
+ const htmlTag = /<html\b[^>]*>/i.exec(html)?.[0] || "";
223
+
224
+ if (!title) findings.push(finding("error", "html-title-missing", titleMatch ? "The <title> tag is empty." : "The page has no <title> tag.", where));
225
+ else lengthFindings(findings, { id: "html-title", label: "The <title>", value: title, min: LIMITS.titleMin, max: LIMITS.titleMax, where });
226
+
227
+ if (!description) {
228
+ findings.push(
229
+ finding("warning", "html-description-missing", meta("description") === null ? 'The page has no <meta name="description">.' : "The meta description is empty.", where),
230
+ );
231
+ }
232
+ else lengthFindings(findings, { id: "html-description", label: "The meta description", value: description, min: LIMITS.descMin, max: LIMITS.descMax, where });
233
+
234
+ if (/\bnoindex\b/.test(robots)) findings.push(finding("error", "html-noindex", "The page tells search engines not to index it (robots noindex).", where));
235
+ if (/\bnofollow\b/.test(robots)) findings.push(finding("warning", "html-nofollow", "The page tells search engines not to follow its links (robots nofollow).", where));
236
+ if (!canonical) findings.push(finding("warning", "html-canonical-missing", "The page has no canonical link, so duplicate URLs may compete with each other.", where));
237
+
238
+ if (!h1s.length) findings.push(finding("error", "html-h1-missing", "The page has no <h1>.", where));
239
+ else if (h1s.length > 1) findings.push(finding("warning", "html-h1-multiple", `The page has ${h1s.length} <h1> headings; use one.`, where));
240
+
241
+ const og = ["og:title", "og:description", "og:image"].filter((k) => meta(k, "property") === null);
242
+ if (og.length) findings.push(finding("info", "html-og-missing", `Missing Open Graph tags: ${og.join(", ")}. Shared links will look plain.`, where));
243
+
244
+ if (noAlt) findings.push(finding("warning", "html-img-alt", `${noAlt} of ${imgs.length} images have no alt attribute.`, where));
245
+ if (!/\slang\s*=/.test(htmlTag)) findings.push(finding("warning", "html-lang-missing", "The <html> tag has no lang attribute.", where));
246
+ if (meta("viewport") === null) findings.push(finding("warning", "html-viewport-missing", "The page has no viewport meta tag, so it is not mobile-friendly.", where));
247
+ if (!/application\/ld\+json/i.test(html)) findings.push(finding("info", "html-structured-data", "No structured data (JSON-LD) found.", where));
248
+
249
+ return {
250
+ findings,
251
+ data: {
252
+ title: title || undefined,
253
+ description: description || undefined,
254
+ canonical: canonical || undefined,
255
+ robots: robots || undefined,
256
+ h1: h1s.slice(0, 3),
257
+ images: imgs.length,
258
+ imagesWithoutAlt: noAlt,
259
+ },
260
+ };
261
+ }
262
+
263
+ const clip = (s, n = 50) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
264
+
265
+ /** Values dotCMS holds that the rendered page does not show: the template is not outputting them. */
266
+ export function crossCheck(fieldData, htmlData) {
267
+ const out = [];
268
+ if (!htmlData) return out;
269
+ if (fieldData?.title && !htmlData.title) {
270
+ out.push(finding("warning", "template-title-not-rendered", `dotCMS has a title ("${clip(fieldData.title)}") but the rendered <title> is empty; check that the template outputs it.`, "template"));
271
+ }
272
+ if (fieldData?.description && !htmlData.description) {
273
+ out.push(finding("warning", "template-description-not-rendered", `dotCMS has a description ("${clip(fieldData.description)}") but the rendered meta description is empty; check that the template outputs it.`, "template"));
274
+ }
275
+ return out;
276
+ }
277
+
278
+ export function summarize(findings) {
279
+ const count = (s) => findings.filter((f) => f.severity === s).length;
280
+ return { errors: count("error"), warnings: count("warning"), notes: count("info") };
281
+ }
282
+
283
+ const ICON = { error: "✗", warning: "⚠", info: "ℹ" };
284
+
285
+ /** The report as plain text, most serious first. */
286
+ export function renderSeoReport({ heading, sources, findings }) {
287
+ const c = summarize(findings);
288
+ const lines = [heading, ...sources.map((s) => ` · ${s}`), "", `${c.errors} error(s) · ${c.warnings} warning(s) · ${c.notes} note(s)`, ""];
289
+ const sorted = [...findings].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
290
+ for (const f of sorted) lines.push(`${ICON[f.severity]} ${f.message} [${f.where}]`);
291
+ if (!findings.length) lines.push("No issues found in the checks that ran.");
292
+ return lines.join("\n");
293
+ }
294
+
295
+ // ---------------------------------------------------------------------------
296
+ // Auditing many pages
297
+ // ---------------------------------------------------------------------------
298
+
299
+ /** One row of an audit: a page and what is wrong with it. */
300
+ export function auditRow({ path, title, findings, htmlChecked }) {
301
+ const counts = summarize(findings);
302
+ const sorted = [...findings].sort((a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity]);
303
+ return {
304
+ path,
305
+ title: title || undefined,
306
+ ...counts,
307
+ htmlChecked: !!htmlChecked,
308
+ issues: sorted.map(({ severity, id, message }) => ({ severity, id, message })),
309
+ };
310
+ }
311
+
312
+ /** Pages with the most serious problems first. */
313
+ export const sortRows = (rows) =>
314
+ [...rows].sort((a, b) => b.errors - a.errors || b.warnings - a.warnings || b.notes - a.notes || a.path.localeCompare(b.path));
315
+
316
+ /** How many pages each kind of problem touches, most serious and most common first. */
317
+ export function commonIssues(rows) {
318
+ const byId = new Map();
319
+ for (const row of rows) {
320
+ for (const issue of row.issues) {
321
+ const entry = byId.get(issue.id) || { id: issue.id, severity: issue.severity, pages: 0, example: issue.message };
322
+ entry.pages++;
323
+ byId.set(issue.id, entry);
324
+ }
325
+ }
326
+ return [...byId.values()].sort(
327
+ (a, b) => SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity] || b.pages - a.pages || a.id.localeCompare(b.id),
328
+ );
329
+ }
330
+
331
+ /** The audit as plain text: one line per page, then the most common problems. */
332
+ export function renderAuditReport({ heading, sources, rows, total, nextPage, onlyIssues }) {
333
+ const withErrors = rows.filter((r) => r.errors).length;
334
+ const warningsOnly = rows.filter((r) => !r.errors && r.warnings).length;
335
+ const clean = rows.length - withErrors - warningsOnly;
336
+ const short = (s, n = 90) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
337
+
338
+ const lines = [
339
+ heading,
340
+ ...sources.map((s) => ` · ${s}`),
341
+ "",
342
+ `${rows.length} page(s) checked: ${withErrors} with errors · ${warningsOnly} with warnings only · ${clean} without problems` +
343
+ (total > rows.length ? ` (the search matched ${total})` : ""),
344
+ "",
345
+ ];
346
+ const listed = sortRows(onlyIssues ? rows.filter((r) => r.errors || r.warnings) : rows);
347
+ for (const r of listed) {
348
+ const mark = r.errors ? `✗${r.errors}${r.warnings ? ` ⚠${r.warnings}` : ""}` : r.warnings ? `⚠${r.warnings}` : "✓";
349
+ const top = r.issues
350
+ .filter((i) => i.severity !== "info")
351
+ .slice(0, 2)
352
+ .map((i) => short(i.message))
353
+ .join(" · ");
354
+ lines.push(`${mark.padEnd(7)} ${r.path}${top ? ` — ${top}` : ""}`);
355
+ }
356
+ if (!listed.length) lines.push(onlyIssues ? "No page has errors or warnings." : "No pages found.");
357
+
358
+ const common = commonIssues(rows).filter((i) => i.severity !== "info").slice(0, 8);
359
+ if (common.length) {
360
+ lines.push("", "Most common problems:");
361
+ for (const i of common) lines.push(` ${String(i.pages).padStart(3)} page(s) · ${i.id} (${i.severity})`);
362
+ }
363
+ if (nextPage) lines.push("", `More pages exist: ask for page ${nextPage}.`);
364
+ return lines.join("\n");
365
+ }
@@ -0,0 +1,17 @@
1
+ # Bundled SEO playbooks
2
+
3
+ The files in this folder are copied, unmodified, from the plugins below, as installed in the Claude desktop
4
+ app on 2026-11-17. Each folder keeps its own `LICENSE` file. They are served by the server as MCP prompts
5
+ and through the `get_seo_guide` tool; the server's own code is in `../guides.js`.
6
+
7
+ | Folder | Plugin | Version | Author | Licence | What was copied |
8
+ | --- | --- | --- | --- | --- | --- |
9
+ | `searchfit-seo/` | searchfit-seo (https://github.com/searchfit/searchfit-seo) | 1.0.0 | SearchFit.ai | MIT | 11 skills, 6 commands, 3 agents |
10
+ | `marketing/` | marketing | 1.2.0 | Anthropic | Apache-2.0 | the `seo-audit` skill |
11
+ | `brightdata/` | brightdata-plugin | 1.9.0 | Bright Data | MIT | the `seo-audit` skill and its reference files |
12
+
13
+ Notes:
14
+
15
+ - The Bright Data `seo-audit` skill uses the Bright Data CLI (`bdata`), a separate product, for live web data.
16
+ - The Marketing `seo-audit` skill mentions optional SEO tool connectors that this server does not provide.
17
+ - The playbooks name Claude Code tools (Read, Glob, Grep, Bash, WebFetch, WebSearch). Other clients use their closest equivalents.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Bright Data
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,109 @@
1
+ ---
2
+ name: seo-audit
3
+ description: When the user wants to audit, review, or diagnose SEO issues on their site. Uses live web data via the Bright Data CLI for accurate detection of JS-injected schema, hreflang, canonicals, and live SERP-based ranking checks. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," "SEO health check," "my traffic dropped," "lost rankings," "not showing up in Google," "site isn't ranking," "Google update hit me," "page speed," "core web vitals," "crawl errors," or "indexing issues." Use this even if the user just says something vague like "my SEO is bad" or "help with SEO" — start with an audit. For building pages at scale to target keywords, see programmatic-seo. For implementing structured data, see schema-markup. For AI search optimization, see ai-seo.
4
+ ---
5
+
6
+ # SEO Audit (Bright Data)
7
+
8
+ You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance — using the Bright Data CLI (`bdata`) to access live, JavaScript-rendered web data.
9
+
10
+ **Never fabricate findings.** Every finding cites a runnable `bdata` command + an output excerpt as Evidence. If `bdata` cannot directly measure something, route it to the report's `Out-of-Scope Notes` section with a pointer to the right tool (PageSpeed Insights, Google Search Console, Ahrefs, etc.).
11
+
12
+ ## Why Bright Data
13
+
14
+ The inspiration for this skill noted that `web_fetch` and `curl` cannot detect JS-injected schema markup (Yoast, RankMath, AIOSEO, Next.js). `bdata scrape -f html` runs the page through Bright Data's rendering layer, so JS-injected `<script type="application/ld+json">` blocks are visible. Same for client-side hreflang and canonical injection. Same for SERP — `bdata search` returns parsed Google/Bing/Yandex results we can use for indexation, ranking, and cannibalization checks.
15
+
16
+ ## Prerequisites
17
+
18
+ The user must have the Bright Data CLI installed and authenticated:
19
+
20
+ ```bash
21
+ curl -fsSL https://cli.brightdata.com/install.sh | bash
22
+ bdata login
23
+ ```
24
+
25
+ If `bdata` is missing or unauthenticated, stop and point at the **brightdata-cli** skill — it has the full installation walkthrough including SSH/headless and direct-API-key paths. Don't reproduce that walkthrough here.
26
+
27
+ ## Initial Assessment
28
+
29
+ **Check for product marketing context first:**
30
+ If `.agents/product-marketing-context.md` exists (or `.claude/product-marketing-context.md` in older setups), read it before asking questions. Use that context and only ask for information not already covered.
31
+
32
+ **Then clarify:**
33
+ 1. **Site context** — What type of site? Primary business goal for SEO? Priority keywords/topics?
34
+ 2. **Current state** — Known issues? Current organic traffic level? Recent changes or migrations?
35
+ 3. **Scope** — Full site audit or specific pages? Search Console / analytics access?
36
+
37
+ ## Mode Selection
38
+
39
+ The skill auto-routes between two modes based on the user's input:
40
+
41
+ - **Mode A — Single-page deep audit.** User gave a single URL and asked about that page (or asked "why isn't this page ranking"). Audit covers the page, its `robots.txt`, its `sitemap.xml`, and the homepage if different. ~5–10 `bdata` calls.
42
+ - **Mode B — Site-wide audit.** User gave a domain or said "audit my site". Sitemap-stratified sampling, default 10–15 pages, budget configurable. ~20–40 `bdata` calls.
43
+
44
+ If the input is ambiguous (single URL but no page-specific question), default to Mode A and ask whether to expand to Mode B.
45
+
46
+ ## SERP Triggers (mode-independent)
47
+
48
+ `bdata search` runs only when there is a clear signal:
49
+ - User mentions a target keyword.
50
+ - User asks "why am I not ranking for X" / "traffic dropped" / similar.
51
+ - User asks about a specific page's performance.
52
+
53
+ Generic "audit my site" prompts do **not** trigger keyword-ranking SERP queries.
54
+
55
+ The one exception that always fires: a single `bdata search "site:<domain>" --json` for the indexation proxy in Tier 1 (R-12). This is one SERP call total per audit, too cheap to skip.
56
+
57
+ ## Workflow
58
+
59
+ ### 1. Gather (always)
60
+ - **Mode B**: fetch `robots.txt` (R-01) + `sitemap.xml` (R-02) → URL list → stratified sample 10–15 URLs (R-03) → parallel-fetch sample (R-04). Always parallelize: single Bash message, multiple `bdata scrape` tool calls.
61
+ - **Mode A**: fetch the target URL + homepage + `robots.txt` + `sitemap.xml`.
62
+ - Always: indexation proxy (R-12).
63
+
64
+ ### 2. Detect site type (R-15)
65
+ Apply matching playbook(s) from `references/site-type-playbooks.md`. Multiple playbooks can apply.
66
+
67
+ ### 3. Run framework checks
68
+ Walk the priority order from `references/audit-framework.md`:
69
+ 1. Crawlability & Indexation
70
+ 2. Technical Foundations
71
+ 3. On-Page Optimization
72
+ 4. Content Quality
73
+ 5. Authority & Links (HTML-only)
74
+
75
+ If a Tier-1 issue is critical (e.g., `Disallow: /` in robots.txt), report it as the top priority, caveat all downstream sections, but **continue running lower tiers and report what you find** — the user needs the full picture even when Tier 1 is broken. Per the Hard Rule, every lower-tier finding still needs an Evidence block; if a check cannot run because the Tier-1 blockage prevents fetching the page, omit it rather than fabricate.
76
+
77
+ ### 4. Run signal-driven SERP (if triggered)
78
+ - R-13 ranking position for each user-supplied target keyword.
79
+ - R-14 cannibalization for each user-supplied target keyword.
80
+
81
+ ### 5. Format report
82
+ Use the exact structure from `references/output-templates.md`. Every finding has Issue / Impact / Evidence / Fix / Priority. Evidence cites the `bdata` command + output excerpt.
83
+
84
+ ## Hard Rules
85
+
86
+ 1. **Never claim "no schema found" without running R-07.** `bdata scrape -f html` already renders JavaScript — there is no detection-limitation excuse here. The inspiration skill's biggest pain point doesn't apply to us.
87
+ 2. **Every finding has Evidence.** Command + output excerpt. No exceptions. No fabricated findings.
88
+ 3. **Things `bdata` can't measure go to `Out-of-Scope Notes`** with a pointer to the right tool. CWV field data → PageSpeed Insights. Coverage detail → Google Search Console. Backlinks → Ahrefs/Semrush. We provide HTML-level CWV proxies but always caveat them.
89
+ 4. **Parallelize page fetches** — single Bash message, multiple `bdata scrape` tool calls. Never loop sequentially over the sampled URLs.
90
+ 5. **Default budget 10–15 pages** for Mode B. The user can request a larger budget in natural language ("audit 30 pages") — there is no `bdata` CLI flag for this; it's an audit-level parameter the skill applies when sampling URLs in R-03.
91
+ 6. **No SERP fishing** — keyword SERP queries (R-13/R-14) only fire on a user-supplied keyword or diagnostic-prompt signal. The `site:` indexation proxy (R-12) is the only always-on SERP call.
92
+ 7. **Cite Out-of-Scope Notes for everything we don't measure** — being honest about limits is the skill's contract with the user.
93
+
94
+ ## References
95
+
96
+ - [audit-framework.md](references/audit-framework.md) — Five-tier priority order, every check.
97
+ - [bdata-recipes.md](references/bdata-recipes.md) — 25 concrete `bdata` recipes (R-01..R-25).
98
+ - [site-type-playbooks.md](references/site-type-playbooks.md) — SaaS / e-commerce / blog / local / multilingual extras.
99
+ - [output-templates.md](references/output-templates.md) — Report structure, finding shape, exec-summary rubric.
100
+
101
+ ## Related Skills
102
+
103
+ - **brightdata-cli** — for installation/login walkthrough and full `bdata` command reference.
104
+ - **scrape** — for ad-hoc scraping outside an audit context.
105
+ - **search** — for ad-hoc SERP queries outside an audit context.
106
+ - **schema-markup** — if user wants to *implement* (not audit) structured data; defer.
107
+ - **competitive-intel** — for cross-competitor analysis (overlaps on SEO content/positioning).
108
+ - **programmatic-seo** — for building pages at scale to target keywords.
109
+ - **ai-seo** — for AEO / GEO / LLMO / AI Overview optimization.
@@ -0,0 +1,71 @@
1
+ # Audit Framework — SEO Audit
2
+
3
+ The auditor's brain. Five-tier priority order, every check, when to short-circuit. Recipes (concrete `bdata` commands) live in `bdata-recipes.md`. Site-type extras live in `site-type-playbooks.md`. Report shape lives in `output-templates.md`.
4
+
5
+ ## Priority Order (Short-Circuiting)
6
+
7
+ The audit walks tiers top-to-bottom; lower-tier findings are partial signal until higher-tier blockers are fixed.
8
+
9
+ 1. **Crawlability & Indexation** — can Google find and index the site at all?
10
+ 2. **Technical Foundations** — is the site fast, secure, mobile-friendly?
11
+ 3. **On-Page Optimization** — titles, meta, headings, internal links.
12
+ 4. **Content Quality** — does each page deserve to rank?
13
+ 5. **Authority & Links** — out of scope for direct measurement; HTML red flags only.
14
+
15
+ When a Tier-1 critical issue is found (e.g., `Disallow: /` in robots.txt), the rule is: report it as the top priority, explicitly tell the user that lower-tier findings may be misleading until the Tier-1 issue is fixed, but **still run lower tiers and report what you find** — caveat each downstream section so the user has a full picture without taking the findings as definitive. Lower-tier findings still require an Evidence block per the Hard Rule below; if a check cannot run because the Tier-1 blockage prevents fetching the page, omit it from the report rather than fabricate a finding.
16
+
17
+ ## Tier 1 — Crawlability & Indexation (always run)
18
+
19
+ - **robots.txt** — fetch with R-01. Parse for `Disallow:` directives that match indexable paths (defined as: any path appearing in the sitemap, or the homepage, or any path matching common SEO-important patterns — `/products/`, `/category/`, `/categories/`, `/blog/`, `/posts/`, `/articles/`, `/locations/`, `/services/`, `/about`, `/`). Standard utility paths (`/wp-admin`, `/cgi-bin`, `/api`, `/admin`, `/cart`, `/checkout`, `/account`) being disallowed is normal and should not be flagged. Also confirm a `Sitemap:` line is present.
20
+ - **sitemap.xml** — fetch with R-02. Direct check: exists, parseable, contains canonical and indexable URLs, uses `<xhtml:link>` if multilingual.
21
+ - **Indexation proxy** — R-12: `bdata search "site:<domain>" --json`. Approximate indexed-URL count from the SERP sample. Flag as critical when the indexed sample is below 30% of the sitemap URL count for sitemaps under 100 URLs, or when the absolute gap exceeds 100 URLs for larger sitemaps (e.g., 12 indexed vs. 847 in sitemap is critical; 6 indexed vs. 10 is not because `site:` returns a sample, not exact counts). Always note in the finding that `site:` is a sample, not a precise index count, and direct the user to Google Search Console's Coverage report for authoritative numbers (Out-of-Scope Notes).
22
+ - **Per-page robots and canonical** — from rendered HTML: `<meta name="robots">`, `<link rel="canonical">`, self-referencing canonical. Flag `noindex` on indexable pages (using the same definition as the robots.txt rule above: pages that appear in the sitemap, the homepage, or pages matching common SEO-important path patterns). `noindex` on utility pages like `/cart` or `/account` is normal and should not be flagged.
23
+ - **Hreflang** (multilingual sites only) — R-08: parsed from rendered HTML head and sitemap. Self-referencing entry, reciprocal links, valid ISO codes, `x-default` present.
24
+
25
+ ## Tier 2 — Technical Foundations
26
+
27
+ - **HTTPS** — final URL after redirects. If `bdata scrape http://<domain>` lands on `https://`, we're fine.
28
+ - **Mobile-friendliness** — viewport meta tag present, no fixed-width inline styles, responsive image markup (`srcset`, `<picture>`).
29
+ - **Core Web Vitals proxies** (HTML-level only — explicit "confirm with PageSpeed Insights" caveat in every CWV finding):
30
+ - Page weight from total HTML bytes.
31
+ - Render-blocking — count of synchronous `<script>` (no `async`/`defer`) and non-deferred `<link rel="stylesheet">` in `<head>`.
32
+ - CLS risk — `<img>` tags missing explicit `width`/`height`.
33
+ - Resource hints — `preconnect` / `preload` / `dns-prefetch` for critical origins.
34
+ - Lazy loading — `loading="lazy"` on below-fold images.
35
+ - **URL structure** — readable, no parameters, hyphenated, lowercase, consistent trailing slash.
36
+
37
+ ## Tier 3 — On-Page Optimization (per sampled page)
38
+
39
+ - **Title tag** — present, unique across sample, 50–60 chars, primary topic word in first half.
40
+ - **Meta description** — present, unique, 150–160 chars.
41
+ - **Heading structure** — exactly one H1, H1 contains primary topic, no skipped levels.
42
+ - **Schema markup** — R-07: `bdata scrape -f html` (CLI renders JS, so this is a direct check). Extract `script[type="application/ld+json"]` blocks and parse with `jq` for `@type` + basic shape validity. **Never claim "no schema found" without running R-07** — the inspiration skill got bitten by `web_fetch` falsely reporting no schema.
43
+ - **Image alt text** — count of `<img>` without `alt`; ratio across page.
44
+ - **Internal linking** — R-10: internal-link count per page, descriptive anchor text vs. generic ("click here", "read more"), orphan-page detection across the sample.
45
+
46
+ ## Tier 4 — Content Quality
47
+
48
+ - **Word count** + paragraph count + heading-to-content ratio.
49
+ - **E-E-A-T signals** from HTML: author byline present, date published/updated visible, links to authoritative sources, contact/about reachable.
50
+ - **Keyword cannibalization** — only when SERP is triggered by a signal (user named a target keyword, asked "why am I not ranking", or asked about specific page performance). R-14: `bdata search "<keyword> site:<domain>" --json` and flag if multiple URLs from the domain rank.
51
+ - **AI-writing red flags** — em-dash overuse, hedge phrases ("delve", "in the realm of"). Soft signal only — never a hard finding.
52
+
53
+ ## Tier 5 — Authority & Links
54
+
55
+ Out of scope for direct measurement. The report's `Out-of-Scope Notes` directs the user to Ahrefs / Semrush for backlink data. Flag only what HTML reveals — testimonials, customer logos, case studies — as "trust signals" in Tier 4.
56
+
57
+ ## SERP Trigger Rules (mode-independent)
58
+
59
+ `bdata search` runs only when there is a clear signal — regardless of whether the audit is Mode A or Mode B:
60
+
61
+ - User mentions a target keyword.
62
+ - User asks "why am I not ranking for X" / "traffic dropped" / similar diagnostic prompts.
63
+ - User asks about a specific page's performance.
64
+
65
+ Generic "audit my site" prompts do **not** trigger SERP queries.
66
+
67
+ The one exception that always fires: R-12 (`bdata search "site:<domain>"`) for indexation proxy in Tier 1. This is one SERP call total per audit and is too cheap to skip.
68
+
69
+ ## The Hard Rule
70
+
71
+ Any check we cannot perform via `bdata` produces a clearly-labeled "out-of-scope, use [tool]" entry in `Out-of-Scope Notes` rather than a fabricated finding. **Never claim a finding without an Evidence block citing a runnable command.**