dotcms-custom-mcp 1.3.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.
- package/README.md +19 -0
- package/guides.js +277 -0
- package/index.js +66 -2
- package/package.json +2 -2
- package/skills/NOTICE.md +17 -0
- package/skills/brightdata/LICENSE +21 -0
- package/skills/brightdata/skills/seo-audit/SKILL.md +109 -0
- package/skills/brightdata/skills/seo-audit/references/audit-framework.md +71 -0
- package/skills/brightdata/skills/seo-audit/references/bdata-recipes.md +551 -0
- package/skills/brightdata/skills/seo-audit/references/output-templates.md +107 -0
- package/skills/brightdata/skills/seo-audit/references/site-type-playbooks.md +113 -0
- package/skills/marketing/LICENSE +202 -0
- package/skills/marketing/skills/seo-audit/SKILL.md +190 -0
- package/skills/searchfit-seo/LICENSE +21 -0
- package/skills/searchfit-seo/agents/competitor-analyzer/AGENT.md +92 -0
- package/skills/searchfit-seo/agents/content-strategist/AGENT.md +122 -0
- package/skills/searchfit-seo/agents/seo-auditor/AGENT.md +110 -0
- package/skills/searchfit-seo/commands/create-content.md +98 -0
- package/skills/searchfit-seo/commands/create-topic.md +116 -0
- package/skills/searchfit-seo/commands/generate-schema.md +66 -0
- package/skills/searchfit-seo/commands/keyword-cluster.md +58 -0
- package/skills/searchfit-seo/commands/seo-check.md +80 -0
- package/skills/searchfit-seo/commands/translate-content.md +86 -0
- package/skills/searchfit-seo/skills/ai-visibility/SKILL.md +126 -0
- package/skills/searchfit-seo/skills/broken-links/SKILL.md +122 -0
- package/skills/searchfit-seo/skills/content-brief/SKILL.md +127 -0
- package/skills/searchfit-seo/skills/content-strategy/SKILL.md +137 -0
- package/skills/searchfit-seo/skills/content-translation/SKILL.md +142 -0
- package/skills/searchfit-seo/skills/internal-linking/SKILL.md +108 -0
- package/skills/searchfit-seo/skills/keyword-clustering/SKILL.md +117 -0
- package/skills/searchfit-seo/skills/on-page-seo/SKILL.md +111 -0
- package/skills/searchfit-seo/skills/schema-markup/SKILL.md +159 -0
- package/skills/searchfit-seo/skills/seo-audit/SKILL.md +109 -0
- package/skills/searchfit-seo/skills/technical-seo/SKILL.md +161 -0
package/README.md
CHANGED
|
@@ -116,6 +116,7 @@ Add the server to the client's MCP configuration:
|
|
|
116
116
|
| `get_content_type_relations` | Shows the relationship tree of a content type: its relationship fields, the related content types and their relationships in turn, with cardinality and sides. Also lists category fields and relationships declared only on other types |
|
|
117
117
|
| `analyze_seo` | Checks the SEO of a page or content item and reports errors, warnings and notes. Regular pages are checked from the page; detail pages (URL-mapped content) and content items are checked from the content and its content type |
|
|
118
118
|
| `audit_seo_pages` | Checks the SEO of every live page under a folder and reports one line per page, most serious first, plus the most common problems across the pages |
|
|
119
|
+
| `get_seo_guide` | Reads one of the 22 bundled SEO playbooks (audits, on-page, technical SEO, schema markup, keywords, content strategy, translation, internal links, AI visibility) so the assistant can follow it. Without arguments it lists them |
|
|
119
120
|
| `list_vtl_files` | Finds VTL files by folder and/or file name, with paging |
|
|
120
121
|
| `read_vtl_file` | Returns the source of a VTL file by path or identifier, optionally for a specific site or language |
|
|
121
122
|
|
|
@@ -196,6 +197,24 @@ Most common problems:
|
|
|
196
197
|
|
|
197
198
|
With `DOTCMS_SITE_URL` set, each page's rendered HTML is also checked, four pages at a time, for up to about 45 seconds; pages after that are checked from their fields only, and the report says how many. Detail pages (URL-mapped content) are not pages in dotCMS, so check those one at a time with `analyze_seo`.
|
|
198
199
|
|
|
200
|
+
#### SEO playbooks
|
|
201
|
+
|
|
202
|
+
The package bundles 22 ready-made SEO playbooks, copied **unmodified** from three plugins: SearchFit SEO (MIT), the `seo-audit` skill of Anthropic's Marketing plugin (Apache-2.0) and the `seo-audit` skill of Bright Data's plugin (MIT). Each folder under `skills/` keeps its own `LICENSE`, and `skills/NOTICE.md` lists the sources and versions.
|
|
203
|
+
|
|
204
|
+
| Source | Playbooks |
|
|
205
|
+
| --- | --- |
|
|
206
|
+
| SearchFit SEO, skills | `searchfit-seo-audit`, `searchfit-technical-seo`, `searchfit-on-page-seo`, `searchfit-schema-markup`, `searchfit-keyword-clustering`, `searchfit-content-strategy`, `searchfit-content-brief`, `searchfit-content-translation`, `searchfit-internal-linking`, `searchfit-broken-links`, `searchfit-ai-visibility` |
|
|
207
|
+
| SearchFit SEO, commands (they take arguments) | `searchfit-seo-check`, `searchfit-create-content`, `searchfit-create-topic`, `searchfit-generate-schema`, `searchfit-keyword-cluster`, `searchfit-translate-content` |
|
|
208
|
+
| SearchFit SEO, agents | `searchfit-agent-seo-auditor`, `searchfit-agent-competitor-analyzer`, `searchfit-agent-content-strategist` |
|
|
209
|
+
| Others | `marketing-seo-audit`, `brightdata-seo-audit` |
|
|
210
|
+
|
|
211
|
+
There are two ways to use them:
|
|
212
|
+
|
|
213
|
+
- **As prompts.** Clients that support MCP prompts list each playbook by its id; in VS Code Copilot Chat type `/` and look for the server's name. A command prompt asks for its arguments (for example `topic` for `searchfit-create-content`); the others take an optional `input`, such as a URL or a topic.
|
|
214
|
+
- **Through the `get_seo_guide` tool**, for clients without prompt support. The assistant lists the playbooks, reads one and follows it. Reference files of a playbook (the Bright Data audit has four) are read with the `file` option.
|
|
215
|
+
|
|
216
|
+
Things to know: the playbooks are general SEO instructions and name Claude Code tools (Read, Glob, Grep, Bash, WebFetch, WebSearch), so a client uses its closest equivalents. The Bright Data audit relies on the Bright Data CLI (`bdata`), a separate product, and the Marketing audit mentions optional SEO tool connectors this server does not provide. Playbooks that audit a dotCMS page can use `analyze_seo`, `audit_seo_pages` and the content type tools for real data.
|
|
217
|
+
|
|
199
218
|
### Only with `DOTCMS_ALLOW_WRITE=true`
|
|
200
219
|
|
|
201
220
|
| Tool | What it does |
|
package/guides.js
ADDED
|
@@ -0,0 +1,277 @@
|
|
|
1
|
+
// Bundled SEO playbooks: the skills, commands and agents that live under skills/, copied unmodified
|
|
2
|
+
// from three plugins (see skills/NOTICE.md), served as MCP prompts and through the get_seo_guide tool.
|
|
3
|
+
//
|
|
4
|
+
// A playbook is a markdown file with a small frontmatter block. Commands may use placeholders such as
|
|
5
|
+
// {{ $ARGUMENTS.market ? "for the " + $ARGUMENTS.market + " market" : "" }} and $ARGUMENTS.topic
|
|
6
|
+
// which are filled in here by a tiny expression evaluator. It understands only strings, $ARGUMENTS.name,
|
|
7
|
+
// + || && ! === !== ?: and parentheses, and never runs code: anything else is left as written.
|
|
8
|
+
|
|
9
|
+
import fs from "node:fs";
|
|
10
|
+
import path from "node:path";
|
|
11
|
+
import { fileURLToPath } from "node:url";
|
|
12
|
+
|
|
13
|
+
export const GUIDES_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "skills");
|
|
14
|
+
|
|
15
|
+
const SOURCES = {
|
|
16
|
+
"searchfit-seo": { prefix: "searchfit", label: "SearchFit SEO", author: "SearchFit.ai", license: "MIT", version: "1.0.0" },
|
|
17
|
+
marketing: { prefix: "marketing", label: "Anthropic Marketing", author: "Anthropic", license: "Apache-2.0", version: "1.2.0" },
|
|
18
|
+
brightdata: { prefix: "brightdata", label: "Bright Data", author: "Bright Data", license: "MIT", version: "1.9.0" },
|
|
19
|
+
};
|
|
20
|
+
|
|
21
|
+
const unquote = (v) => {
|
|
22
|
+
const s = v.trim();
|
|
23
|
+
return /^"[\s\S]*"$/.test(s) || /^'[\s\S]*'$/.test(s) ? s.slice(1, -1) : s;
|
|
24
|
+
};
|
|
25
|
+
|
|
26
|
+
/** Split a markdown file into its frontmatter (simple keys, lists, lists of maps) and its body. */
|
|
27
|
+
export function parseFrontmatter(text) {
|
|
28
|
+
const m = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/.exec(text);
|
|
29
|
+
if (!m) return { meta: {}, body: text };
|
|
30
|
+
const meta = {};
|
|
31
|
+
let key = null;
|
|
32
|
+
let item = null;
|
|
33
|
+
for (const line of m[1].split(/\r?\n/)) {
|
|
34
|
+
let r;
|
|
35
|
+
if ((r = /^([A-Za-z][\w-]*):\s*(.*)$/.exec(line))) {
|
|
36
|
+
key = r[1];
|
|
37
|
+
item = null;
|
|
38
|
+
meta[key] = r[2] === "" ? [] : unquote(r[2]);
|
|
39
|
+
} else if (Array.isArray(meta[key]) && (r = /^-\s+([A-Za-z][\w-]*):\s*(.*)$/.exec(line))) {
|
|
40
|
+
item = { [r[1]]: unquote(r[2]) };
|
|
41
|
+
meta[key].push(item);
|
|
42
|
+
} else if (Array.isArray(meta[key]) && (r = /^-\s+(.*)$/.exec(line))) {
|
|
43
|
+
item = null;
|
|
44
|
+
meta[key].push(unquote(r[1]));
|
|
45
|
+
} else if (item && (r = /^\s+([A-Za-z][\w-]*):\s*(.*)$/.exec(line))) {
|
|
46
|
+
item[r[1]] = unquote(r[2]);
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
return { meta, body: m[2] };
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const OPERATORS = ["!==", "===", "||", "&&", "!=", "==", "?", ":", "+", "(", ")", "!"];
|
|
53
|
+
|
|
54
|
+
function tokenize(src) {
|
|
55
|
+
const tokens = [];
|
|
56
|
+
let i = 0;
|
|
57
|
+
while (i < src.length) {
|
|
58
|
+
const ch = src[i];
|
|
59
|
+
if (/\s/.test(ch)) {
|
|
60
|
+
i++;
|
|
61
|
+
continue;
|
|
62
|
+
}
|
|
63
|
+
if (ch === '"' || ch === "'") {
|
|
64
|
+
let j = i + 1;
|
|
65
|
+
let s = "";
|
|
66
|
+
while (j < src.length && src[j] !== ch) {
|
|
67
|
+
if (src[j] === "\\" && j + 1 < src.length) {
|
|
68
|
+
const n = src[j + 1];
|
|
69
|
+
s += n === "n" ? "\n" : n === "t" ? "\t" : n;
|
|
70
|
+
j += 2;
|
|
71
|
+
} else s += src[j++];
|
|
72
|
+
}
|
|
73
|
+
if (j >= src.length) return null;
|
|
74
|
+
tokens.push({ t: "str", v: s });
|
|
75
|
+
i = j + 1;
|
|
76
|
+
continue;
|
|
77
|
+
}
|
|
78
|
+
const arg = /^\$ARGUMENTS\.([A-Za-z_]\w*)/.exec(src.slice(i));
|
|
79
|
+
if (arg) {
|
|
80
|
+
tokens.push({ t: "arg", v: arg[1] });
|
|
81
|
+
i += arg[0].length;
|
|
82
|
+
continue;
|
|
83
|
+
}
|
|
84
|
+
const op = OPERATORS.find((o) => src.startsWith(o, i));
|
|
85
|
+
if (!op) return null;
|
|
86
|
+
tokens.push({ t: "op", v: op });
|
|
87
|
+
i += op.length;
|
|
88
|
+
}
|
|
89
|
+
return tokens;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** The value of a template expression as text, or null when it uses anything this evaluator does not know. */
|
|
93
|
+
export function evaluate(expression, lookup) {
|
|
94
|
+
const tokens = tokenize(expression);
|
|
95
|
+
if (!tokens || !tokens.length) return null;
|
|
96
|
+
let p = 0;
|
|
97
|
+
const eat = (op) => (tokens[p]?.t === "op" && tokens[p].v === op ? (p++, true) : false);
|
|
98
|
+
const truthy = (v) => v !== undefined && v !== null && v !== "" && v !== false;
|
|
99
|
+
|
|
100
|
+
const primary = () => {
|
|
101
|
+
const tk = tokens[p++];
|
|
102
|
+
if (!tk) throw new Error("unexpected end");
|
|
103
|
+
if (tk.t === "str") return tk.v;
|
|
104
|
+
if (tk.t === "arg") return lookup(tk.v);
|
|
105
|
+
if (tk.t === "op" && tk.v === "(") {
|
|
106
|
+
const v = ternary();
|
|
107
|
+
if (!eat(")")) throw new Error("missing )");
|
|
108
|
+
return v;
|
|
109
|
+
}
|
|
110
|
+
throw new Error("unexpected token");
|
|
111
|
+
};
|
|
112
|
+
const unary = () => (eat("!") ? !truthy(unary()) : primary());
|
|
113
|
+
const add = () => {
|
|
114
|
+
let v = unary();
|
|
115
|
+
while (eat("+")) v = `${v ?? ""}${unary() ?? ""}`;
|
|
116
|
+
return v;
|
|
117
|
+
};
|
|
118
|
+
const equality = () => {
|
|
119
|
+
let v = add();
|
|
120
|
+
for (;;) {
|
|
121
|
+
if (eat("!==") || eat("!=")) v = v !== add();
|
|
122
|
+
else if (eat("===") || eat("==")) v = v === add();
|
|
123
|
+
else return v;
|
|
124
|
+
}
|
|
125
|
+
};
|
|
126
|
+
const and = () => {
|
|
127
|
+
let v = equality();
|
|
128
|
+
while (eat("&&")) {
|
|
129
|
+
const r = equality();
|
|
130
|
+
v = truthy(v) ? r : v;
|
|
131
|
+
}
|
|
132
|
+
return v;
|
|
133
|
+
};
|
|
134
|
+
const or = () => {
|
|
135
|
+
let v = and();
|
|
136
|
+
while (eat("||")) {
|
|
137
|
+
const r = and();
|
|
138
|
+
v = truthy(v) ? v : r;
|
|
139
|
+
}
|
|
140
|
+
return v;
|
|
141
|
+
};
|
|
142
|
+
const ternary = () => {
|
|
143
|
+
const cond = or();
|
|
144
|
+
if (!eat("?")) return cond;
|
|
145
|
+
const a = ternary();
|
|
146
|
+
if (!eat(":")) throw new Error("missing :");
|
|
147
|
+
const b = ternary();
|
|
148
|
+
return truthy(cond) ? a : b;
|
|
149
|
+
};
|
|
150
|
+
|
|
151
|
+
try {
|
|
152
|
+
const v = ternary();
|
|
153
|
+
if (p !== tokens.length) return null;
|
|
154
|
+
return v === undefined || v === null || v === false ? "" : String(v);
|
|
155
|
+
} catch {
|
|
156
|
+
return null;
|
|
157
|
+
}
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** Fill the {{ ... }} expressions and the bare $ARGUMENTS.name placeholders of a command. */
|
|
161
|
+
export function renderTemplate(body, args = {}) {
|
|
162
|
+
const lookup = (name) => (typeof args[name] === "string" && args[name] !== "" ? args[name] : undefined);
|
|
163
|
+
return body
|
|
164
|
+
.replace(/\{\{([\s\S]*?)\}\}/g, (whole, expr) => {
|
|
165
|
+
const v = evaluate(expr, lookup);
|
|
166
|
+
return v === null ? whole : v;
|
|
167
|
+
})
|
|
168
|
+
.replace(/\$ARGUMENTS\.([A-Za-z_]\w*)/g, (_, name) => lookup(name) ?? "(not provided)");
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
function listFiles(dir, base = dir) {
|
|
172
|
+
const out = new Map();
|
|
173
|
+
for (const ent of fs.readdirSync(dir, { withFileTypes: true })) {
|
|
174
|
+
const abs = path.join(dir, ent.name);
|
|
175
|
+
if (ent.isDirectory()) for (const [k, v] of listFiles(abs, base)) out.set(k, v);
|
|
176
|
+
else if (ent.isFile() && ent.name !== ".DS_Store") out.set(path.relative(base, abs).split(path.sep).join("/"), abs);
|
|
177
|
+
}
|
|
178
|
+
return out;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/** Every playbook under skills/: { id, kind, name, description, arguments, hint, body, files, source... } */
|
|
182
|
+
export function loadGuides(root = GUIDES_ROOT) {
|
|
183
|
+
const guides = [];
|
|
184
|
+
let sources;
|
|
185
|
+
try {
|
|
186
|
+
sources = fs.readdirSync(root, { withFileTypes: true }).filter((d) => d.isDirectory());
|
|
187
|
+
} catch {
|
|
188
|
+
return guides;
|
|
189
|
+
}
|
|
190
|
+
for (const dir of sources) {
|
|
191
|
+
const src = SOURCES[dir.name] || { prefix: dir.name, label: dir.name, author: "see LICENSE", license: "see LICENSE", version: "" };
|
|
192
|
+
const add = (kind, name, file, extraFiles) => {
|
|
193
|
+
let parsed;
|
|
194
|
+
try {
|
|
195
|
+
parsed = parseFrontmatter(fs.readFileSync(file, "utf8"));
|
|
196
|
+
} catch {
|
|
197
|
+
return;
|
|
198
|
+
}
|
|
199
|
+
const { meta, body } = parsed;
|
|
200
|
+
guides.push({
|
|
201
|
+
id: `${src.prefix}-${kind === "agent" ? "agent-" : ""}${name}`,
|
|
202
|
+
kind,
|
|
203
|
+
name: typeof meta.name === "string" && meta.name ? meta.name : name,
|
|
204
|
+
description: typeof meta.description === "string" ? meta.description : "",
|
|
205
|
+
hint: typeof meta["argument-hint"] === "string" ? meta["argument-hint"] : "",
|
|
206
|
+
arguments: (Array.isArray(meta.arguments) ? meta.arguments : [])
|
|
207
|
+
.filter((a) => a && typeof a === "object" && a.name)
|
|
208
|
+
.map((a) => ({ name: a.name, description: a.description || "", required: a.required === "true" })),
|
|
209
|
+
tools: Array.isArray(meta.tools) ? meta.tools : [],
|
|
210
|
+
body,
|
|
211
|
+
files: extraFiles,
|
|
212
|
+
source: dir.name,
|
|
213
|
+
sourceLabel: src.label,
|
|
214
|
+
author: src.author,
|
|
215
|
+
license: src.license,
|
|
216
|
+
version: src.version,
|
|
217
|
+
});
|
|
218
|
+
};
|
|
219
|
+
|
|
220
|
+
const skills = path.join(root, dir.name, "skills");
|
|
221
|
+
if (fs.existsSync(skills)) {
|
|
222
|
+
for (const s of fs.readdirSync(skills, { withFileTypes: true }).filter((d) => d.isDirectory())) {
|
|
223
|
+
const file = path.join(skills, s.name, "SKILL.md");
|
|
224
|
+
if (!fs.existsSync(file)) continue;
|
|
225
|
+
const files = listFiles(path.join(skills, s.name));
|
|
226
|
+
files.delete("SKILL.md");
|
|
227
|
+
add("skill", s.name, file, files);
|
|
228
|
+
}
|
|
229
|
+
}
|
|
230
|
+
const commands = path.join(root, dir.name, "commands");
|
|
231
|
+
if (fs.existsSync(commands)) {
|
|
232
|
+
for (const c of fs.readdirSync(commands, { withFileTypes: true }).filter((d) => d.isFile() && d.name.endsWith(".md"))) {
|
|
233
|
+
add("command", c.name.replace(/\.md$/, ""), path.join(commands, c.name), new Map());
|
|
234
|
+
}
|
|
235
|
+
}
|
|
236
|
+
const agents = path.join(root, dir.name, "agents");
|
|
237
|
+
if (fs.existsSync(agents)) {
|
|
238
|
+
for (const a of fs.readdirSync(agents, { withFileTypes: true }).filter((d) => d.isDirectory())) {
|
|
239
|
+
const file = path.join(agents, a.name, "AGENT.md");
|
|
240
|
+
if (fs.existsSync(file)) add("agent", a.name, file, new Map());
|
|
241
|
+
}
|
|
242
|
+
}
|
|
243
|
+
}
|
|
244
|
+
return guides.sort((a, b) => a.id.localeCompare(b.id));
|
|
245
|
+
}
|
|
246
|
+
|
|
247
|
+
const ONE_LINE = (s, n = 130) => {
|
|
248
|
+
const first = s.replace(/\s+/g, " ").trim();
|
|
249
|
+
return first.length > n ? `${first.slice(0, n - 1)}…` : first;
|
|
250
|
+
};
|
|
251
|
+
|
|
252
|
+
/** The list of playbooks, one line each. */
|
|
253
|
+
export function renderCatalog(guides) {
|
|
254
|
+
const lines = guides.map((g) => `${g.id} [${g.kind} · ${g.sourceLabel}] ${ONE_LINE(g.description)}`);
|
|
255
|
+
return [
|
|
256
|
+
`${guides.length} SEO playbooks:`,
|
|
257
|
+
"",
|
|
258
|
+
...lines,
|
|
259
|
+
"",
|
|
260
|
+
'Read one with get_seo_guide using its id (a command takes "arguments", the others an "input"). A playbook may have bundled reference files: pass "file" to read one.',
|
|
261
|
+
].join("\n");
|
|
262
|
+
}
|
|
263
|
+
|
|
264
|
+
const TOOL_NOTE =
|
|
265
|
+
"Note: playbooks are written for Claude Code and name tools such as Read, Glob, Grep, Bash, WebFetch and WebSearch; use the closest tools your client has. " +
|
|
266
|
+
"For dotCMS pages, this server also gives real data: analyze_seo, audit_seo_pages, get_content_type_fields and get_content_type_relations.";
|
|
267
|
+
|
|
268
|
+
/** A playbook as text for the model: its body (commands with arguments filled in), then what it can use. */
|
|
269
|
+
export function renderGuide(guide, args = {}, input = "") {
|
|
270
|
+
const parts = [`Source: ${guide.sourceLabel} v${guide.version} by ${guide.author} (${guide.license} licence).`, "", guide.kind === "command" ? renderTemplate(guide.body, args) : guide.body.trim()];
|
|
271
|
+
if (guide.kind !== "command" && typeof input === "string" && input.trim()) parts.push("", "---", `Task: ${input.trim()}`);
|
|
272
|
+
if (guide.files.size) {
|
|
273
|
+
parts.push("", "---", `This playbook refers to bundled files. Read one with get_seo_guide (guide "${guide.id}", file "<path>"):`, ...[...guide.files.keys()].map((f) => `- ${f}`));
|
|
274
|
+
}
|
|
275
|
+
parts.push("", "---", TOOL_NOTE);
|
|
276
|
+
return parts.join("\n");
|
|
277
|
+
}
|
package/index.js
CHANGED
|
@@ -3,7 +3,8 @@
|
|
|
3
3
|
//
|
|
4
4
|
// Read-only tools (always available):
|
|
5
5
|
// list_content_types, get_content_type_fields, get_content_type_relations,
|
|
6
|
-
// analyze_seo, audit_seo_pages,
|
|
6
|
+
// analyze_seo, audit_seo_pages, get_seo_guide (bundled SEO playbooks, also MCP prompts),
|
|
7
|
+
// list_vtl_files, read_vtl_file
|
|
7
8
|
// Write tools (only when DOTCMS_ALLOW_WRITE=true, limited to DOTCMS_WRITE_ROOTS):
|
|
8
9
|
// plan_vtl_change (plans only, writes nothing) -> apply_vtl_change (writes, human-confirmed)
|
|
9
10
|
//
|
|
@@ -12,6 +13,7 @@
|
|
|
12
13
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
13
14
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
14
15
|
import crypto from "node:crypto";
|
|
16
|
+
import fs from "node:fs";
|
|
15
17
|
import { z } from "zod";
|
|
16
18
|
import {
|
|
17
19
|
ALLOW_WRITE,
|
|
@@ -37,6 +39,7 @@ import {
|
|
|
37
39
|
searchFiles,
|
|
38
40
|
} from "./dotcms.js";
|
|
39
41
|
import { deletePlan, diffLines, loadPlan, renderPlan, savePlan } from "./plans.js";
|
|
42
|
+
import { loadGuides, renderCatalog, renderGuide } from "./guides.js";
|
|
40
43
|
import { buildRelationTree, renderRelationTree } from "./relations.js";
|
|
41
44
|
import {
|
|
42
45
|
analyzeFields,
|
|
@@ -108,7 +111,7 @@ const mapFile = (f) => ({
|
|
|
108
111
|
const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
|
|
109
112
|
const fail = (err) => ({ isError: true, content: [{ type: "text", text: err.message }] });
|
|
110
113
|
|
|
111
|
-
const server = new McpServer({ name: "dotcms", version: "1.
|
|
114
|
+
const server = new McpServer({ name: "dotcms", version: "1.4.0" });
|
|
112
115
|
|
|
113
116
|
// ---------------------------------------------------------------------------
|
|
114
117
|
// Read-only tools
|
|
@@ -944,6 +947,67 @@ if (ALLOW_WRITE) {
|
|
|
944
947
|
);
|
|
945
948
|
}
|
|
946
949
|
|
|
950
|
+
// ---------------------------------------------------------------------------
|
|
951
|
+
// Bundled SEO playbooks (skills, commands and agents): MCP prompts, plus one tool for clients without prompts
|
|
952
|
+
// ---------------------------------------------------------------------------
|
|
953
|
+
|
|
954
|
+
const GUIDES = loadGuides();
|
|
955
|
+
if (GUIDES.length) {
|
|
956
|
+
const guideById = new Map(GUIDES.map((g) => [g.id, g]));
|
|
957
|
+
|
|
958
|
+
for (const g of GUIDES) {
|
|
959
|
+
const shape = {};
|
|
960
|
+
if (g.kind === "command" && g.arguments.length) {
|
|
961
|
+
for (const a of g.arguments) shape[a.name] = a.required ? z.string().describe(a.description || a.name) : z.string().optional().describe(a.description || a.name);
|
|
962
|
+
} else {
|
|
963
|
+
shape.input = z.string().optional().describe(g.hint || "What to apply this playbook to: a URL, a page, a file or a topic");
|
|
964
|
+
}
|
|
965
|
+
server.registerPrompt(
|
|
966
|
+
g.id,
|
|
967
|
+
{ title: `${g.sourceLabel}: ${g.name}`, description: g.description, argsSchema: shape },
|
|
968
|
+
(args) => ({
|
|
969
|
+
description: g.description,
|
|
970
|
+
messages: [{ role: "user", content: { type: "text", text: renderGuide(g, args, args.input) } }],
|
|
971
|
+
}),
|
|
972
|
+
);
|
|
973
|
+
}
|
|
974
|
+
|
|
975
|
+
server.registerTool(
|
|
976
|
+
"get_seo_guide",
|
|
977
|
+
{
|
|
978
|
+
title: "Read a bundled SEO playbook",
|
|
979
|
+
description:
|
|
980
|
+
"Read-only. Read one of the bundled SEO playbooks (audits, on-page, technical SEO, schema markup, keyword clustering, " +
|
|
981
|
+
"content strategy and briefs, translation, internal links, broken links, AI visibility) and follow it. " +
|
|
982
|
+
"Call it without arguments to list them. Ids: " +
|
|
983
|
+
`${GUIDES.map((g) => g.id).join(", ")}. ` +
|
|
984
|
+
"A command takes 'arguments'; the others take 'input' (what to apply them to). A playbook may have bundled reference files: pass 'file'.",
|
|
985
|
+
inputSchema: {
|
|
986
|
+
guide: z.string().optional().describe("Playbook id, e.g. 'searchfit-seo-audit'. Omit to list all playbooks"),
|
|
987
|
+
file: z.string().optional().describe("A bundled reference file of that playbook, e.g. 'references/audit-framework.md'"),
|
|
988
|
+
arguments: z.record(z.string(), z.string()).optional().describe("Arguments of a command playbook, e.g. { topic: 'mutual funds' }"),
|
|
989
|
+
input: z.string().optional().describe("What to apply the playbook to: a URL, a page, a file or a topic"),
|
|
990
|
+
},
|
|
991
|
+
annotations: READ_ONLY,
|
|
992
|
+
},
|
|
993
|
+
async ({ guide, file, arguments: args, input }) => {
|
|
994
|
+
try {
|
|
995
|
+
if (!guide) return { content: [{ type: "text", text: renderCatalog(GUIDES) }] };
|
|
996
|
+
const g = guideById.get(guide);
|
|
997
|
+
if (!g) throw new Error(`Unknown playbook '${guide}'. Available: ${GUIDES.map((x) => x.id).join(", ")}.`);
|
|
998
|
+
if (file) {
|
|
999
|
+
const abs = g.files.get(file);
|
|
1000
|
+
if (!abs) throw new Error(`'${file}' is not a bundled file of ${g.id}. ${g.files.size ? `Files: ${[...g.files.keys()].join(", ")}.` : "It has no bundled files."}`);
|
|
1001
|
+
return { content: [{ type: "text", text: fs.readFileSync(abs, "utf8") }] };
|
|
1002
|
+
}
|
|
1003
|
+
return { content: [{ type: "text", text: renderGuide(g, args || {}, input || "") }] };
|
|
1004
|
+
} catch (err) {
|
|
1005
|
+
return fail(err);
|
|
1006
|
+
}
|
|
1007
|
+
},
|
|
1008
|
+
);
|
|
1009
|
+
}
|
|
1010
|
+
|
|
947
1011
|
await server.connect(new StdioServerTransport());
|
|
948
1012
|
console.error(
|
|
949
1013
|
`dotcms-mcp running (${BASE_URL}${TOKEN ? "" : ", no DOTCMS_TOKEN set"}, ` +
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dotcms-custom-mcp",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.4.0",
|
|
4
4
|
"description": "MCP server for dotCMS: inspect content types and fields, and read or safely write Velocity (VTL) files from AI assistants such as GitHub Copilot and Claude",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"mcp",
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
"dotcms-custom-mcp": "index.js",
|
|
31
31
|
"dotcms-custom-mcp-confirm-write": "hooks/confirm-write.mjs"
|
|
32
32
|
},
|
|
33
|
-
"files": ["index.js", "dotcms.js", "plans.js", "relations.js", "seo.js", "hooks/"],
|
|
33
|
+
"files": ["index.js", "dotcms.js", "plans.js", "relations.js", "seo.js", "guides.js", "skills/", "hooks/"],
|
|
34
34
|
"scripts": { "start": "node index.js" },
|
|
35
35
|
"engines": { "node": ">=20.18.1" },
|
|
36
36
|
"dependencies": {
|
package/skills/NOTICE.md
ADDED
|
@@ -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.**
|