dotcms-custom-mcp 1.2.0 → 1.3.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 +58 -0
- package/dotcms.js +65 -1
- package/index.js +355 -2
- package/package.json +2 -2
- package/seo.js +365 -0
package/README.md
CHANGED
|
@@ -32,6 +32,7 @@ All configuration is through environment variables.
|
|
|
32
32
|
| `DOTCMS_WRITE_ROOTS` | `/application/apivtl/,/application/vtl/custom-fields/` | Comma-separated folders the write tools are limited to |
|
|
33
33
|
| `DOTCMS_READ_EXTENSIONS` | `vtl` | Comma-separated file extensions the read tools may return |
|
|
34
34
|
| `DOTCMS_CONFIRM` | *(on)* | Set to `off` to skip the server's own confirmation prompt before a write |
|
|
35
|
+
| `DOTCMS_SITE_URL` | *(none)* | Public URL of the website, e.g. `https://www.example.com`. Lets the SEO tools also check the rendered HTML. The API token is never sent to it. With several sites, use a host name or alias of the site you check; the report warns when it is not one |
|
|
35
36
|
| `DOTCMS_PLANS_DIR` | `~/.dotcms-mcp/plans` | Where pending change plans are stored |
|
|
36
37
|
|
|
37
38
|
### Behind a proxy
|
|
@@ -113,6 +114,8 @@ Add the server to the client's MCP configuration:
|
|
|
113
114
|
| `list_content_types` | Lists content types, with optional name filter, base-type filter and paging |
|
|
114
115
|
| `get_content_type_fields` | Returns the fields of a content type (variable, type, data type, required/unique/indexed flags, field variables, relationships). Layout-only fields are hidden unless requested |
|
|
115
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
|
+
| `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
|
+
| `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 |
|
|
116
119
|
| `list_vtl_files` | Finds VTL files by folder and/or file name, with paging |
|
|
117
120
|
| `read_vtl_file` | Returns the source of a VTL file by path or identifier, optionally for a specific site or language |
|
|
118
121
|
|
|
@@ -139,6 +142,60 @@ Blog (Blog)
|
|
|
139
142
|
|
|
140
143
|
A type that was already shown higher up is not expanded again, so circular relationships don't loop.
|
|
141
144
|
|
|
145
|
+
#### SEO analysis
|
|
146
|
+
|
|
147
|
+
`analyze_seo` checks one page and returns a text report plus the same findings as JSON. Give it either a page `path`, or a `contentType` with an `identifier`:
|
|
148
|
+
|
|
149
|
+
| You give | It checks |
|
|
150
|
+
| --- | --- |
|
|
151
|
+
| `path` of a regular (drag-and-drop) page | The page's own fields: title and description |
|
|
152
|
+
| `path` of a detail page (URL-mapped content) | The mapped content's fields, plus its **content type**: does it have title, description and image fields, and is the URL map pattern sensible |
|
|
153
|
+
| `contentType` + `identifier` | The content item and its content type; the URL is built from the URL map pattern |
|
|
154
|
+
|
|
155
|
+
What it looks for:
|
|
156
|
+
|
|
157
|
+
- title and description present, and within 30–60 and 70–160 characters
|
|
158
|
+
- title identical to the description
|
|
159
|
+
- URL shape: length, uppercase, underscores, spaces, file extensions, depth
|
|
160
|
+
- missing image for social previews
|
|
161
|
+
- content types with no description field, no URL map pattern, or a pattern built from an id
|
|
162
|
+
|
|
163
|
+
Set `DOTCMS_SITE_URL` to also check the **rendered HTML**, the way a crawler sees it: `<title>`, meta description, canonical link, robots `noindex`, number of `<h1>` headings, Open Graph tags, images without `alt`, `lang`, viewport and structured data. Without it, the report says the HTML was not checked. The public site is fetched anonymously; the dotCMS token is never sent there.
|
|
164
|
+
|
|
165
|
+
Options: `site` is the site's host name (or alias) and is needed when the page is not on the instance's default site; without it a miss says so. `languageId` picks a language. The live version is analysed, because that is what search engines see.
|
|
166
|
+
|
|
167
|
+
When the rendered HTML is checked and dotCMS has a title or description that the page does not output, the report says so: that points at the template, not at the content.
|
|
168
|
+
|
|
169
|
+
**Headless sites.** If the site is a front-end app that sets its own title and meta tags in the browser, the server HTML is an empty shell and every page will show an empty `<title>` and no `<h1>`. In that case leave `DOTCMS_SITE_URL` unset and rely on the field checks, or point it at the real public front-end rather than the dotCMS delivery domain.
|
|
170
|
+
|
|
171
|
+
#### SEO audit of many pages
|
|
172
|
+
|
|
173
|
+
`audit_seo_pages` checks every live page under a folder, so you can see which pages need attention first. It lists the pages with one content search and checks each page's own fields, with the same checks `analyze_seo` runs for a regular page.
|
|
174
|
+
|
|
175
|
+
```
|
|
176
|
+
SEO audit: /blog on demo.dotcms.com (batch 1)
|
|
177
|
+
|
|
178
|
+
3 page(s) checked: 0 with errors · 2 with warnings only · 1 without problems
|
|
179
|
+
|
|
180
|
+
⚠2 /blog/first-post — Title (title) is 2 characters; aim for 30–60. · No description value found.
|
|
181
|
+
⚠1 /blog/second_post — The URL uses underscores; hyphens are read as word separators, underscores are not.
|
|
182
|
+
✓ /blog
|
|
183
|
+
|
|
184
|
+
Most common problems:
|
|
185
|
+
1 page(s) · description-missing (warning)
|
|
186
|
+
1 page(s) · title-short (warning)
|
|
187
|
+
```
|
|
188
|
+
|
|
189
|
+
| Option | Default | Purpose |
|
|
190
|
+
| --- | --- | --- |
|
|
191
|
+
| `folder` | `/` | Folder to audit, including subfolders |
|
|
192
|
+
| `site` | none | Site host name (or alias). The search is limited to that site, so totals and batches count only its pages. Required when the pages exist on several sites |
|
|
193
|
+
| `languageId` | lowest per page | Which language version to check |
|
|
194
|
+
| `limit`, `page` | 25, 1 | Pages per call (up to 100), and which batch. The report says when more pages exist |
|
|
195
|
+
| `onlyIssues` | `false` | List only pages with errors or warnings |
|
|
196
|
+
|
|
197
|
+
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
|
+
|
|
142
199
|
### Only with `DOTCMS_ALLOW_WRITE=true`
|
|
143
200
|
|
|
144
201
|
| Tool | What it does |
|
|
@@ -187,6 +244,7 @@ The package ships a `PreToolUse` hook that shows the full plan and asks for appr
|
|
|
187
244
|
## Troubleshooting
|
|
188
245
|
|
|
189
246
|
- **`Cannot reach dotCMS at …`** — the instance isn't running or isn't reachable from this machine. Check `DOTCMS_URL`.
|
|
247
|
+
- **`analyze_seo` says the HTML was not checked** — set `DOTCMS_SITE_URL` to the public website, and make sure the machine running the server can reach it (the proxy settings apply).
|
|
190
248
|
- **Timeouts or connection errors on a corporate network** — set `HTTPS_PROXY` (see *Behind a proxy*); if dotCMS is local, add `localhost` to `NO_PROXY`.
|
|
191
249
|
- **401 / 403 responses** — the token is missing, expired, or belongs to a different instance. Tokens are per instance.
|
|
192
250
|
- **Write tools are missing** — set `DOTCMS_ALLOW_WRITE=true` and restart the server.
|
package/dotcms.js
CHANGED
|
@@ -10,6 +10,8 @@
|
|
|
10
10
|
// DOTCMS_CONFIRM "off" to skip the server's own confirmation prompt before a write
|
|
11
11
|
// (default: ask through the client when it supports MCP elicitation)
|
|
12
12
|
// HTTP_PROXY / HTTPS_PROXY / NO_PROXY standard proxy settings, honored for every request
|
|
13
|
+
// DOTCMS_SITE_URL public URL of the website (e.g. https://www.example.com), so the SEO tool
|
|
14
|
+
// can also check the rendered HTML. The API token is never sent to it.
|
|
13
15
|
|
|
14
16
|
// undici's own fetch and FormData must be used together: its fetch does not recognise the
|
|
15
17
|
// FormData built into Node, and Node's built-in fetch ignores the proxy variables.
|
|
@@ -30,7 +32,17 @@ export const READ_EXTENSIONS = (process.env.DOTCMS_READ_EXTENSIONS || "vtl")
|
|
|
30
32
|
.split(",")
|
|
31
33
|
.map((ext) => ext.trim().replace(/^\./, "").toLowerCase())
|
|
32
34
|
.filter((ext) => /^[a-z0-9]+$/.test(ext));
|
|
33
|
-
export const
|
|
35
|
+
export const SITE_URL = (() => {
|
|
36
|
+
const raw = (process.env.DOTCMS_SITE_URL || "").trim();
|
|
37
|
+
if (!raw) return "";
|
|
38
|
+
try {
|
|
39
|
+
const u = new URL(raw);
|
|
40
|
+
return /^https?:$/.test(u.protocol) ? u.origin + u.pathname.replace(/\/+$/, "") : "";
|
|
41
|
+
} catch {
|
|
42
|
+
return "";
|
|
43
|
+
}
|
|
44
|
+
})();
|
|
45
|
+
export const CONFIRM =!/^(off|false|0|no)$/i.test(process.env.DOTCMS_CONFIRM || "");
|
|
34
46
|
|
|
35
47
|
/** True when the token would travel unencrypted to another machine. */
|
|
36
48
|
export const INSECURE_TRANSPORT = (() => {
|
|
@@ -74,6 +86,58 @@ async function send(path, init = {}) {
|
|
|
74
86
|
}
|
|
75
87
|
}
|
|
76
88
|
|
|
89
|
+
const siteCache = new Map();
|
|
90
|
+
|
|
91
|
+
/** A site by host name (or alias) -> { identifier, hostname }. Cached for the life of the process. */
|
|
92
|
+
export async function resolveSite(name) {
|
|
93
|
+
const wanted = String(name ?? "").trim().toLowerCase();
|
|
94
|
+
if (!wanted) throw new Error("Pass the site's host name.");
|
|
95
|
+
if (siteCache.has(wanted)) return siteCache.get(wanted);
|
|
96
|
+
const data = await api("/api/v1/site", { params: { filter: wanted, per_page: 25 } });
|
|
97
|
+
const sites = (data.entity || []).filter((s) => s.identifier && s.hostname && !s.systemHost);
|
|
98
|
+
const match =
|
|
99
|
+
sites.find((s) => s.hostname.toLowerCase() === wanted) ||
|
|
100
|
+
sites.find((s) => String(s.aliases || "").toLowerCase().split(/\s+/).includes(wanted));
|
|
101
|
+
if (!match) {
|
|
102
|
+
const near = sites.slice(0, 10).map((s) => s.hostname);
|
|
103
|
+
throw new Error(`Site '${name}' not found.${near.length ? ` Sites matching it: ${near.join(", ")}.` : ""}`);
|
|
104
|
+
}
|
|
105
|
+
const site = {
|
|
106
|
+
identifier: match.identifier,
|
|
107
|
+
hostname: match.hostname,
|
|
108
|
+
aliases: String(match.aliases || "").split(/\s+/).filter(Boolean),
|
|
109
|
+
};
|
|
110
|
+
siteCache.set(wanted, site);
|
|
111
|
+
return site;
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
const MAX_HTML_BYTES = 3_000_000;
|
|
115
|
+
|
|
116
|
+
/** The rendered HTML of a page on the public site. Anonymous: the API token is not sent here. */
|
|
117
|
+
export async function fetchSiteHtml(path) {
|
|
118
|
+
if (!SITE_URL) throw new Error("DOTCMS_SITE_URL is not set.");
|
|
119
|
+
let res;
|
|
120
|
+
try {
|
|
121
|
+
res = await undiciFetch(SITE_URL + path, {
|
|
122
|
+
headers: { Accept: "text/html", "User-Agent": "dotcms-custom-mcp" },
|
|
123
|
+
dispatcher,
|
|
124
|
+
signal: AbortSignal.timeout(30_000),
|
|
125
|
+
});
|
|
126
|
+
} catch (err) {
|
|
127
|
+
throw new Error(`Cannot reach ${SITE_URL}: ${err.message}`);
|
|
128
|
+
}
|
|
129
|
+
const type = res.headers.get("content-type") || "";
|
|
130
|
+
if (!res.ok) {
|
|
131
|
+
await res.body?.cancel();
|
|
132
|
+
throw new Error(`${SITE_URL}${path} answered ${res.status} ${res.statusText}.`);
|
|
133
|
+
}
|
|
134
|
+
if (!/html/i.test(type) || Number(res.headers.get("content-length") || 0) > MAX_HTML_BYTES) {
|
|
135
|
+
await res.body?.cancel();
|
|
136
|
+
throw new Error(`${SITE_URL}${path} did not return an HTML page of a readable size (${type || "no content type"}).`);
|
|
137
|
+
}
|
|
138
|
+
return { html: (await res.text()).slice(0, MAX_HTML_BYTES), status: res.status, finalUrl: res.url };
|
|
139
|
+
}
|
|
140
|
+
|
|
77
141
|
/** JSON request against the dotCMS REST API. `body` may be an object (sent as JSON) or FormData. */
|
|
78
142
|
export async function api(path, { method = "GET", params = {}, body } = {}) {
|
|
79
143
|
const query = new URLSearchParams();
|
package/index.js
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
//
|
|
4
4
|
// Read-only tools (always available):
|
|
5
5
|
// list_content_types, get_content_type_fields, get_content_type_relations,
|
|
6
|
-
// list_vtl_files, read_vtl_file
|
|
6
|
+
// analyze_seo, audit_seo_pages, list_vtl_files, read_vtl_file
|
|
7
7
|
// Write tools (only when DOTCMS_ALLOW_WRITE=true, limited to DOTCMS_WRITE_ROOTS):
|
|
8
8
|
// plan_vtl_change (plans only, writes nothing) -> apply_vtl_change (writes, human-confirmed)
|
|
9
9
|
//
|
|
@@ -19,6 +19,7 @@ import {
|
|
|
19
19
|
CONFIRM,
|
|
20
20
|
INSECURE_TRANSPORT,
|
|
21
21
|
READ_EXTENSIONS,
|
|
22
|
+
SITE_URL,
|
|
22
23
|
TOKEN,
|
|
23
24
|
WRITE_ROOTS,
|
|
24
25
|
api,
|
|
@@ -27,14 +28,29 @@ import {
|
|
|
27
28
|
downloadFile,
|
|
28
29
|
ensureFolder,
|
|
29
30
|
escapeLucene,
|
|
31
|
+
fetchSiteHtml,
|
|
30
32
|
findFiles,
|
|
31
33
|
parseWritePath,
|
|
32
34
|
pickVersion,
|
|
35
|
+
resolveSite,
|
|
33
36
|
saveFile,
|
|
34
37
|
searchFiles,
|
|
35
38
|
} from "./dotcms.js";
|
|
36
39
|
import { deletePlan, diffLines, loadPlan, renderPlan, savePlan } from "./plans.js";
|
|
37
40
|
import { buildRelationTree, renderRelationTree } from "./relations.js";
|
|
41
|
+
import {
|
|
42
|
+
analyzeFields,
|
|
43
|
+
analyzeHtml,
|
|
44
|
+
auditRow,
|
|
45
|
+
checkUrl,
|
|
46
|
+
commonIssues,
|
|
47
|
+
crossCheck,
|
|
48
|
+
normalizePagePath,
|
|
49
|
+
renderAuditReport,
|
|
50
|
+
renderSeoReport,
|
|
51
|
+
sortRows,
|
|
52
|
+
summarize,
|
|
53
|
+
} from "./seo.js";
|
|
38
54
|
|
|
39
55
|
const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
|
|
40
56
|
const MAX_FILE_CHARS = 200_000;
|
|
@@ -92,7 +108,7 @@ const mapFile = (f) => ({
|
|
|
92
108
|
const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
|
|
93
109
|
const fail = (err) => ({ isError: true, content: [{ type: "text", text: err.message }] });
|
|
94
110
|
|
|
95
|
-
const server = new McpServer({ name: "dotcms", version: "1.
|
|
111
|
+
const server = new McpServer({ name: "dotcms", version: "1.3.0" });
|
|
96
112
|
|
|
97
113
|
// ---------------------------------------------------------------------------
|
|
98
114
|
// Read-only tools
|
|
@@ -276,6 +292,343 @@ server.registerTool(
|
|
|
276
292
|
},
|
|
277
293
|
);
|
|
278
294
|
|
|
295
|
+
/** A warning when DOTCMS_SITE_URL does not look like it serves this site (several sites share one instance). */
|
|
296
|
+
async function siteUrlNote(siteHostname) {
|
|
297
|
+
if (!SITE_URL || !siteHostname) return null;
|
|
298
|
+
try {
|
|
299
|
+
const publicHost = new URL(SITE_URL).hostname.toLowerCase();
|
|
300
|
+
const site = await resolveSite(siteHostname);
|
|
301
|
+
const known = [site.hostname, ...site.aliases].map((s) => s.toLowerCase());
|
|
302
|
+
return known.includes(publicHost)
|
|
303
|
+
? null
|
|
304
|
+
: `Check: DOTCMS_SITE_URL (${publicHost}) is not a host name or alias of site ${site.hostname}; make sure it serves that site`;
|
|
305
|
+
} catch {
|
|
306
|
+
return null;
|
|
307
|
+
}
|
|
308
|
+
}
|
|
309
|
+
|
|
310
|
+
/** Fill a URL map pattern such as /blog/post/{urlTitle} from a content item; null if a value is missing. */
|
|
311
|
+
function urlFromPattern(pattern, content) {
|
|
312
|
+
let missing = false;
|
|
313
|
+
const url = pattern.replace(/\{([^}]+)\}/g, (_, name) => {
|
|
314
|
+
const v = content?.[name];
|
|
315
|
+
if (typeof v !== "string" || !v) missing = true;
|
|
316
|
+
return v || "";
|
|
317
|
+
});
|
|
318
|
+
return missing ? null : url;
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
server.registerTool(
|
|
322
|
+
"analyze_seo",
|
|
323
|
+
{
|
|
324
|
+
title: "Analyze the SEO of a dotCMS page or content item",
|
|
325
|
+
description:
|
|
326
|
+
"Read-only. Check the SEO of one page and report errors, warnings and notes. Pass a page 'path' " +
|
|
327
|
+
"(e.g. '/about-us' or '/blog/post/my-post'), or a 'contentType' with an 'identifier'. " +
|
|
328
|
+
"A regular page is checked from its own fields. A detail page (URL-mapped content) or a content item is " +
|
|
329
|
+
"checked from the content's fields, and its content type is loaded to see whether it has title, " +
|
|
330
|
+
"description and image fields and a sensible URL map pattern. Checks title and description length, " +
|
|
331
|
+
"duplicates, URL shape and images. When the server has DOTCMS_SITE_URL, the rendered HTML is checked too: " +
|
|
332
|
+
"title tag, meta description, canonical, robots, h1, Open Graph tags, image alt text, lang and viewport.",
|
|
333
|
+
inputSchema: {
|
|
334
|
+
path: z
|
|
335
|
+
.string()
|
|
336
|
+
.optional()
|
|
337
|
+
.describe("Page path on the site, e.g. '/about-us' or '/blog/post/my-post' (a full URL is reduced to its path)"),
|
|
338
|
+
contentType: z.string().optional().describe("Content type variable (e.g. 'Blog'); use with 'identifier' instead of 'path'"),
|
|
339
|
+
identifier: z.string().optional().describe("Identifier of the content item; use with 'contentType'"),
|
|
340
|
+
site: z
|
|
341
|
+
.string()
|
|
342
|
+
.optional()
|
|
343
|
+
.describe("Site host name, for a 'path' on a site other than the instance's default one, e.g. 'us.rebuild.development'"),
|
|
344
|
+
languageId: z.number().int().optional().describe("Language id (default: the site's default language)"),
|
|
345
|
+
},
|
|
346
|
+
annotations: READ_ONLY,
|
|
347
|
+
},
|
|
348
|
+
async ({ path, contentType, identifier, site, languageId }) => {
|
|
349
|
+
try {
|
|
350
|
+
if (path && (contentType || identifier)) throw new Error("Pass either 'path', or 'contentType' with 'identifier' — not both.");
|
|
351
|
+
if (!path && !(contentType && identifier)) {
|
|
352
|
+
throw new Error("Pass a page 'path' (e.g. '/about-us'), or 'contentType' together with 'identifier'.");
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
const sources = [];
|
|
356
|
+
const extra = []; // findings that come from the process itself
|
|
357
|
+
let kind;
|
|
358
|
+
let heading;
|
|
359
|
+
let page = null;
|
|
360
|
+
let content = null;
|
|
361
|
+
let ct = null;
|
|
362
|
+
let urlPath = null;
|
|
363
|
+
let siteHostname = null;
|
|
364
|
+
|
|
365
|
+
if (path) {
|
|
366
|
+
urlPath = normalizePagePath(path);
|
|
367
|
+
const segments = urlPath === "/" ? "index" : urlPath.slice(1);
|
|
368
|
+
// Segments arrive percent-encoded from the path; decode first so they are not encoded twice.
|
|
369
|
+
const siteInfo = site ? await resolveSite(site) : null;
|
|
370
|
+
let data;
|
|
371
|
+
try {
|
|
372
|
+
data = await api(`/api/v1/page/render/${segments.split("/").map((s) => encodeURIComponent(decodeURIComponent(s))).join("/")}`, {
|
|
373
|
+
params: { mode: "LIVE", language_id: languageId, host_id: siteInfo?.identifier },
|
|
374
|
+
});
|
|
375
|
+
} catch (err) {
|
|
376
|
+
if (!site && /responded 404/.test(err.message)) {
|
|
377
|
+
err.message += " If the page belongs to another site than the instance's default one, pass 'site' (the site's host name).";
|
|
378
|
+
}
|
|
379
|
+
throw err;
|
|
380
|
+
}
|
|
381
|
+
const entity = data.entity || {};
|
|
382
|
+
page = entity.page || {};
|
|
383
|
+
content = entity.urlContentMap || null;
|
|
384
|
+
siteHostname = entity.site?.hostname || siteInfo?.hostname || null;
|
|
385
|
+
kind = content ? "detail-page" : "page";
|
|
386
|
+
sources.push(
|
|
387
|
+
`Page loaded from the dotCMS page API (live version${page.title ? `, "${page.title}"` : ""}${entity.site?.hostname ? `, site ${entity.site.hostname}` : ""})`,
|
|
388
|
+
);
|
|
389
|
+
if (content) {
|
|
390
|
+
const typeVar = content.contentType || content.contentTypeName;
|
|
391
|
+
if (typeVar) {
|
|
392
|
+
try {
|
|
393
|
+
ct = (await api(`/api/v1/contenttype/id/${encodeURIComponent(typeVar)}`)).entity || null;
|
|
394
|
+
sources.push(`Detail page: SEO values read from the ${ct?.variable || typeVar} content, definition from its content type`);
|
|
395
|
+
} catch (err) {
|
|
396
|
+
sources.push(`Detail page: SEO values read from the content; its content type could not be loaded (${err.message})`);
|
|
397
|
+
}
|
|
398
|
+
}
|
|
399
|
+
} else {
|
|
400
|
+
sources.push("Regular page: SEO values read from the page's own fields");
|
|
401
|
+
}
|
|
402
|
+
heading = `SEO analysis: ${urlPath} (${kind === "detail-page" ? `detail page${ct ? ` · ${ct.variable}` : ""}` : "page"})`;
|
|
403
|
+
} else {
|
|
404
|
+
kind = "content";
|
|
405
|
+
ct = (await api(`/api/v1/contenttype/id/${encodeURIComponent(contentType)}`)).entity;
|
|
406
|
+
if (!ct?.variable) throw new Error(`Content type '${contentType}' not found.`);
|
|
407
|
+
const base = `+contentType:${escapeLucene(ct.variable)} +identifier:${escapeLucene(identifier)}${languageId ? ` +languageId:${languageId}` : ""}`;
|
|
408
|
+
let state = "live";
|
|
409
|
+
let found = (await api("/api/content/_search", { method: "POST", body: { query: `${base} +live:true`, limit: 5 } })).entity?.jsonObjectView?.contentlets || [];
|
|
410
|
+
if (!found.length) {
|
|
411
|
+
state = "working";
|
|
412
|
+
found = (await api("/api/content/_search", { method: "POST", body: { query: `${base} +working:true`, limit: 5 } })).entity?.jsonObjectView?.contentlets || [];
|
|
413
|
+
}
|
|
414
|
+
if (!found.length) throw new Error(`No ${ct.variable} content with identifier '${identifier}'${languageId ? ` in language ${languageId}` : ""} was found.`);
|
|
415
|
+
content = found[0];
|
|
416
|
+
siteHostname = content.hostName || null;
|
|
417
|
+
sources.push(`Content loaded from dotCMS (${state} version), definition from content type ${ct.variable}`);
|
|
418
|
+
if (state === "working") extra.push({ severity: "warning", id: "not-live", message: "The content has no live version, so it is not visible to search engines yet.", where: "content" });
|
|
419
|
+
if (ct.urlMapPattern) urlPath = urlFromPattern(ct.urlMapPattern, content);
|
|
420
|
+
heading = `SEO analysis: ${ct.variable} content ${identifier}${urlPath ? ` (${urlPath})` : ""}`;
|
|
421
|
+
}
|
|
422
|
+
|
|
423
|
+
// The rendered page, when the public site is known.
|
|
424
|
+
let htmlResult = null;
|
|
425
|
+
if (urlPath && SITE_URL) {
|
|
426
|
+
try {
|
|
427
|
+
const { html, finalUrl } = await fetchSiteHtml(urlPath);
|
|
428
|
+
htmlResult = analyzeHtml(html);
|
|
429
|
+
sources.push(`Rendered HTML checked at ${finalUrl}`);
|
|
430
|
+
const urlNote = await siteUrlNote(siteHostname);
|
|
431
|
+
if (urlNote) sources.push(urlNote);
|
|
432
|
+
} catch (err) {
|
|
433
|
+
sources.push(`Rendered HTML not checked: ${err.message}`);
|
|
434
|
+
}
|
|
435
|
+
} else if (!SITE_URL) {
|
|
436
|
+
sources.push("Rendered HTML not checked (set DOTCMS_SITE_URL to the public site URL to include it)");
|
|
437
|
+
} else {
|
|
438
|
+
sources.push("Rendered HTML not checked (this content has no URL of its own)");
|
|
439
|
+
}
|
|
440
|
+
|
|
441
|
+
const fields = analyzeFields({
|
|
442
|
+
kind,
|
|
443
|
+
page,
|
|
444
|
+
content,
|
|
445
|
+
contentType: ct,
|
|
446
|
+
// The rendered page is the truth for a regular page. For content, a field finding is the cause
|
|
447
|
+
// behind a rendered-page finding, so it is only dropped when the page has the value anyway.
|
|
448
|
+
htmlSeen: {
|
|
449
|
+
title: !!htmlResult && (kind === "page" || !!htmlResult.data.title),
|
|
450
|
+
description: !!htmlResult && (kind === "page" || !!htmlResult.data.description),
|
|
451
|
+
},
|
|
452
|
+
});
|
|
453
|
+
const findings = [
|
|
454
|
+
...extra,
|
|
455
|
+
...fields.findings,
|
|
456
|
+
...(htmlResult?.findings || []),
|
|
457
|
+
...crossCheck(fields.data, htmlResult?.data),
|
|
458
|
+
...(urlPath ? checkUrl(urlPath) : []),
|
|
459
|
+
];
|
|
460
|
+
if (kind === "detail-page" && !htmlResult) {
|
|
461
|
+
findings.push({
|
|
462
|
+
severity: "info",
|
|
463
|
+
id: "detail-title-from-template",
|
|
464
|
+
message: "The browser title of a detail page comes from the template, not from these fields; check the rendered page to confirm it uses the content's title.",
|
|
465
|
+
where: "template",
|
|
466
|
+
});
|
|
467
|
+
}
|
|
468
|
+
|
|
469
|
+
return {
|
|
470
|
+
content: [
|
|
471
|
+
{ type: "text", text: renderSeoReport({ heading, sources, findings }) },
|
|
472
|
+
{
|
|
473
|
+
type: "text",
|
|
474
|
+
text: JSON.stringify(
|
|
475
|
+
{
|
|
476
|
+
kind,
|
|
477
|
+
path: urlPath || undefined,
|
|
478
|
+
contentType: ct?.variable,
|
|
479
|
+
summary: summarize(findings),
|
|
480
|
+
sources,
|
|
481
|
+
values: fields.data,
|
|
482
|
+
rendered: htmlResult?.data,
|
|
483
|
+
findings,
|
|
484
|
+
},
|
|
485
|
+
null,
|
|
486
|
+
2,
|
|
487
|
+
),
|
|
488
|
+
},
|
|
489
|
+
],
|
|
490
|
+
};
|
|
491
|
+
} catch (err) {
|
|
492
|
+
return fail(err);
|
|
493
|
+
}
|
|
494
|
+
},
|
|
495
|
+
);
|
|
496
|
+
|
|
497
|
+
const AUDIT_HTML_BUDGET_MS = 45_000; // stop fetching rendered pages after this; the rest use page fields only
|
|
498
|
+
const AUDIT_HTML_CONCURRENCY = 4;
|
|
499
|
+
|
|
500
|
+
/** Run fn over items with at most `size` running at once; results keep the order of items. */
|
|
501
|
+
async function mapPool(items, size, fn) {
|
|
502
|
+
const out = new Array(items.length);
|
|
503
|
+
let next = 0;
|
|
504
|
+
await Promise.all(
|
|
505
|
+
Array.from({ length: Math.min(size, items.length) }, async () => {
|
|
506
|
+
while (next < items.length) {
|
|
507
|
+
const i = next++;
|
|
508
|
+
out[i] = await fn(items[i], i);
|
|
509
|
+
}
|
|
510
|
+
}),
|
|
511
|
+
);
|
|
512
|
+
return out;
|
|
513
|
+
}
|
|
514
|
+
|
|
515
|
+
server.registerTool(
|
|
516
|
+
"audit_seo_pages",
|
|
517
|
+
{
|
|
518
|
+
title: "Audit the SEO of all pages in a folder",
|
|
519
|
+
description:
|
|
520
|
+
"Read-only. Check the SEO of every live page under a folder (default: the whole site) and report one line per " +
|
|
521
|
+
"page — errors, warnings and the top problems — most serious first, plus the problems that occur most often. " +
|
|
522
|
+
"Each page gets the same checks as analyze_seo for a regular page: title and description from the page's fields, " +
|
|
523
|
+
"URL shape, and, when the server has DOTCMS_SITE_URL, the rendered HTML. Pages are listed 'limit' at a time; " +
|
|
524
|
+
"ask for the next 'page' to continue. Detail pages (URL-mapped content) are not pages in dotCMS: check one with analyze_seo.",
|
|
525
|
+
inputSchema: {
|
|
526
|
+
folder: z.string().default("/").describe("Folder to audit, including its subfolders, e.g. '/blog' (default: '/', the whole site)"),
|
|
527
|
+
site: z.string().optional().describe("Site host name. Required when pages under the folder exist on several sites"),
|
|
528
|
+
languageId: z.number().int().optional().describe("Language id (default: the lowest language id each page has, usually the default language)"),
|
|
529
|
+
limit: z.number().int().min(1).max(100).default(25).describe("Pages to check per call"),
|
|
530
|
+
page: z.number().int().min(1).default(1).describe("Which batch of pages to check"),
|
|
531
|
+
onlyIssues: z.boolean().default(false).describe("List only pages that have errors or warnings"),
|
|
532
|
+
},
|
|
533
|
+
annotations: READ_ONLY,
|
|
534
|
+
},
|
|
535
|
+
async ({ folder, site, languageId, limit, page, onlyIssues }) => {
|
|
536
|
+
try {
|
|
537
|
+
const folderPath = normalizePagePath(folder);
|
|
538
|
+
const clauses = ["+baseType:5", "+live:true"];
|
|
539
|
+
if (folderPath !== "/") clauses.push(`+path:*${escapeLucene(folderPath.toLowerCase())}/*`);
|
|
540
|
+
// Filter by site inside the search, so totals and batches count only that site's pages.
|
|
541
|
+
const siteInfo = site ? await resolveSite(site) : null;
|
|
542
|
+
if (siteInfo) clauses.push(`+conhost:${siteInfo.identifier}`);
|
|
543
|
+
const offset = (page - 1) * limit;
|
|
544
|
+
const data = await api("/api/content/_search", {
|
|
545
|
+
method: "POST",
|
|
546
|
+
body: { query: clauses.join(" "), sort: "path asc", limit, offset },
|
|
547
|
+
});
|
|
548
|
+
const entity = data.entity || {};
|
|
549
|
+
const total = entity.resultsSize ?? 0;
|
|
550
|
+
let pages = (entity.jsonObjectView?.contentlets || []).filter(
|
|
551
|
+
(p) => typeof p.path === "string" && (folderPath === "/" || p.path.toLowerCase().startsWith(`${folderPath.toLowerCase()}/`)),
|
|
552
|
+
);
|
|
553
|
+
|
|
554
|
+
const sites = [...new Set(pages.map((p) => p.hostName).filter(Boolean))];
|
|
555
|
+
if (siteInfo) pages = pages.filter((p) => p.hostName?.toLowerCase() === siteInfo.hostname.toLowerCase());
|
|
556
|
+
else if (sites.length > 1) throw new Error(`Pages under ${folderPath} exist on several sites (${sites.join(", ")}). Pass 'site'.`);
|
|
557
|
+
const siteName = siteInfo?.hostname || sites[0];
|
|
558
|
+
|
|
559
|
+
if (languageId !== undefined) pages = pages.filter((p) => p.languageId === languageId);
|
|
560
|
+
else {
|
|
561
|
+
const lowest = new Map();
|
|
562
|
+
for (const p of pages) if (!lowest.has(p.identifier) || p.languageId < lowest.get(p.identifier).languageId) lowest.set(p.identifier, p);
|
|
563
|
+
pages = [...lowest.values()];
|
|
564
|
+
}
|
|
565
|
+
|
|
566
|
+
const deadline = Date.now() + AUDIT_HTML_BUDGET_MS;
|
|
567
|
+
let htmlFailures = 0;
|
|
568
|
+
let htmlSkipped = 0;
|
|
569
|
+
const rows = await mapPool(pages, AUDIT_HTML_CONCURRENCY, async (p) => {
|
|
570
|
+
const urlPath = p.path.replace(/\/index$/i, "") || "/";
|
|
571
|
+
let htmlResult = null;
|
|
572
|
+
if (SITE_URL) {
|
|
573
|
+
const segments = urlPath.split("/");
|
|
574
|
+
if (Date.now() >= deadline || segments.some((s) => s === "." || s === "..")) htmlSkipped++;
|
|
575
|
+
else {
|
|
576
|
+
try {
|
|
577
|
+
htmlResult = analyzeHtml((await fetchSiteHtml(segments.map(encodeURIComponent).join("/"))).html);
|
|
578
|
+
} catch {
|
|
579
|
+
htmlFailures++;
|
|
580
|
+
}
|
|
581
|
+
}
|
|
582
|
+
}
|
|
583
|
+
const fields = analyzeFields({ kind: "page", page: p, htmlSeen: { title: !!htmlResult, description: !!htmlResult } });
|
|
584
|
+
const findings = [...fields.findings, ...(htmlResult?.findings || []), ...crossCheck(fields.data, htmlResult?.data), ...checkUrl(urlPath)];
|
|
585
|
+
return auditRow({ path: urlPath, title: fields.data.title || htmlResult?.data.title, findings, htmlChecked: !!htmlResult });
|
|
586
|
+
});
|
|
587
|
+
|
|
588
|
+
const checked = rows.filter((r) => r.htmlChecked).length;
|
|
589
|
+
const sources = [
|
|
590
|
+
`Pages listed from the dotCMS content search (live versions${siteName ? `, site ${siteName}` : ""}); each page's own fields are checked`,
|
|
591
|
+
!SITE_URL
|
|
592
|
+
? "Rendered HTML not checked (set DOTCMS_SITE_URL to the public site URL to include it)"
|
|
593
|
+
: `Rendered HTML checked for ${checked} of ${rows.length} pages at ${SITE_URL}` +
|
|
594
|
+
(htmlFailures ? `; ${htmlFailures} could not be fetched` : "") +
|
|
595
|
+
(htmlSkipped ? `; ${htmlSkipped} skipped (time limit or unusual path)` : ""),
|
|
596
|
+
];
|
|
597
|
+
const urlNote = checked ? await siteUrlNote(siteName) : null;
|
|
598
|
+
if (urlNote) sources.push(urlNote);
|
|
599
|
+
const nextPage = offset + limit < total ? page + 1 : null;
|
|
600
|
+
const heading = `SEO audit: ${folderPath}${siteName ? ` on ${siteName}` : ""} (batch ${page})`;
|
|
601
|
+
|
|
602
|
+
return {
|
|
603
|
+
content: [
|
|
604
|
+
{ type: "text", text: renderAuditReport({ heading, sources, rows, total, nextPage, onlyIssues }) },
|
|
605
|
+
{
|
|
606
|
+
type: "text",
|
|
607
|
+
text: JSON.stringify(
|
|
608
|
+
{
|
|
609
|
+
folder: folderPath,
|
|
610
|
+
site: siteName,
|
|
611
|
+
batch: page,
|
|
612
|
+
limit,
|
|
613
|
+
matched: total,
|
|
614
|
+
checked: rows.length,
|
|
615
|
+
nextPage,
|
|
616
|
+
sources,
|
|
617
|
+
commonIssues: commonIssues(rows),
|
|
618
|
+
pages: sortRows(onlyIssues ? rows.filter((r) => r.errors || r.warnings) : rows),
|
|
619
|
+
},
|
|
620
|
+
null,
|
|
621
|
+
2,
|
|
622
|
+
),
|
|
623
|
+
},
|
|
624
|
+
],
|
|
625
|
+
};
|
|
626
|
+
} catch (err) {
|
|
627
|
+
return fail(err);
|
|
628
|
+
}
|
|
629
|
+
},
|
|
630
|
+
);
|
|
631
|
+
|
|
279
632
|
server.registerTool(
|
|
280
633
|
"list_vtl_files",
|
|
281
634
|
{
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dotcms-custom-mcp",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.3.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", "hooks/"],
|
|
33
|
+
"files": ["index.js", "dotcms.js", "plans.js", "relations.js", "seo.js", "hooks/"],
|
|
34
34
|
"scripts": { "start": "node index.js" },
|
|
35
35
|
"engines": { "node": ">=20.18.1" },
|
|
36
36
|
"dependencies": {
|
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(/�?39;|'/g, "'")
|
|
25
|
+
.replace(/</g, "<")
|
|
26
|
+
.replace(/>/g, ">")
|
|
27
|
+
.replace(/&/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
|
+
}
|