dotcms-custom-mcp 1.2.0 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (36) hide show
  1. package/README.md +77 -0
  2. package/dotcms.js +65 -1
  3. package/guides.js +277 -0
  4. package/index.js +418 -1
  5. package/package.json +2 -2
  6. package/seo.js +365 -0
  7. package/skills/NOTICE.md +17 -0
  8. package/skills/brightdata/LICENSE +21 -0
  9. package/skills/brightdata/skills/seo-audit/SKILL.md +109 -0
  10. package/skills/brightdata/skills/seo-audit/references/audit-framework.md +71 -0
  11. package/skills/brightdata/skills/seo-audit/references/bdata-recipes.md +551 -0
  12. package/skills/brightdata/skills/seo-audit/references/output-templates.md +107 -0
  13. package/skills/brightdata/skills/seo-audit/references/site-type-playbooks.md +113 -0
  14. package/skills/marketing/LICENSE +202 -0
  15. package/skills/marketing/skills/seo-audit/SKILL.md +190 -0
  16. package/skills/searchfit-seo/LICENSE +21 -0
  17. package/skills/searchfit-seo/agents/competitor-analyzer/AGENT.md +92 -0
  18. package/skills/searchfit-seo/agents/content-strategist/AGENT.md +122 -0
  19. package/skills/searchfit-seo/agents/seo-auditor/AGENT.md +110 -0
  20. package/skills/searchfit-seo/commands/create-content.md +98 -0
  21. package/skills/searchfit-seo/commands/create-topic.md +116 -0
  22. package/skills/searchfit-seo/commands/generate-schema.md +66 -0
  23. package/skills/searchfit-seo/commands/keyword-cluster.md +58 -0
  24. package/skills/searchfit-seo/commands/seo-check.md +80 -0
  25. package/skills/searchfit-seo/commands/translate-content.md +86 -0
  26. package/skills/searchfit-seo/skills/ai-visibility/SKILL.md +126 -0
  27. package/skills/searchfit-seo/skills/broken-links/SKILL.md +122 -0
  28. package/skills/searchfit-seo/skills/content-brief/SKILL.md +127 -0
  29. package/skills/searchfit-seo/skills/content-strategy/SKILL.md +137 -0
  30. package/skills/searchfit-seo/skills/content-translation/SKILL.md +142 -0
  31. package/skills/searchfit-seo/skills/internal-linking/SKILL.md +108 -0
  32. package/skills/searchfit-seo/skills/keyword-clustering/SKILL.md +117 -0
  33. package/skills/searchfit-seo/skills/on-page-seo/SKILL.md +111 -0
  34. package/skills/searchfit-seo/skills/schema-markup/SKILL.md +159 -0
  35. package/skills/searchfit-seo/skills/seo-audit/SKILL.md +109 -0
  36. package/skills/searchfit-seo/skills/technical-seo/SKILL.md +161 -0
package/index.js CHANGED
@@ -3,6 +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
+ // analyze_seo, audit_seo_pages, get_seo_guide (bundled SEO playbooks, also MCP prompts),
6
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)
@@ -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,
@@ -19,6 +21,7 @@ import {
19
21
  CONFIRM,
20
22
  INSECURE_TRANSPORT,
21
23
  READ_EXTENSIONS,
24
+ SITE_URL,
22
25
  TOKEN,
23
26
  WRITE_ROOTS,
24
27
  api,
@@ -27,14 +30,30 @@ import {
27
30
  downloadFile,
28
31
  ensureFolder,
29
32
  escapeLucene,
33
+ fetchSiteHtml,
30
34
  findFiles,
31
35
  parseWritePath,
32
36
  pickVersion,
37
+ resolveSite,
33
38
  saveFile,
34
39
  searchFiles,
35
40
  } from "./dotcms.js";
36
41
  import { deletePlan, diffLines, loadPlan, renderPlan, savePlan } from "./plans.js";
42
+ import { loadGuides, renderCatalog, renderGuide } from "./guides.js";
37
43
  import { buildRelationTree, renderRelationTree } from "./relations.js";
44
+ import {
45
+ analyzeFields,
46
+ analyzeHtml,
47
+ auditRow,
48
+ checkUrl,
49
+ commonIssues,
50
+ crossCheck,
51
+ normalizePagePath,
52
+ renderAuditReport,
53
+ renderSeoReport,
54
+ sortRows,
55
+ summarize,
56
+ } from "./seo.js";
38
57
 
39
58
  const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
40
59
  const MAX_FILE_CHARS = 200_000;
@@ -92,7 +111,7 @@ const mapFile = (f) => ({
92
111
  const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
93
112
  const fail = (err) => ({ isError: true, content: [{ type: "text", text: err.message }] });
94
113
 
95
- const server = new McpServer({ name: "dotcms", version: "1.2.0" });
114
+ const server = new McpServer({ name: "dotcms", version: "1.4.0" });
96
115
 
97
116
  // ---------------------------------------------------------------------------
98
117
  // Read-only tools
@@ -276,6 +295,343 @@ server.registerTool(
276
295
  },
277
296
  );
278
297
 
298
+ /** A warning when DOTCMS_SITE_URL does not look like it serves this site (several sites share one instance). */
299
+ async function siteUrlNote(siteHostname) {
300
+ if (!SITE_URL || !siteHostname) return null;
301
+ try {
302
+ const publicHost = new URL(SITE_URL).hostname.toLowerCase();
303
+ const site = await resolveSite(siteHostname);
304
+ const known = [site.hostname, ...site.aliases].map((s) => s.toLowerCase());
305
+ return known.includes(publicHost)
306
+ ? null
307
+ : `Check: DOTCMS_SITE_URL (${publicHost}) is not a host name or alias of site ${site.hostname}; make sure it serves that site`;
308
+ } catch {
309
+ return null;
310
+ }
311
+ }
312
+
313
+ /** Fill a URL map pattern such as /blog/post/{urlTitle} from a content item; null if a value is missing. */
314
+ function urlFromPattern(pattern, content) {
315
+ let missing = false;
316
+ const url = pattern.replace(/\{([^}]+)\}/g, (_, name) => {
317
+ const v = content?.[name];
318
+ if (typeof v !== "string" || !v) missing = true;
319
+ return v || "";
320
+ });
321
+ return missing ? null : url;
322
+ }
323
+
324
+ server.registerTool(
325
+ "analyze_seo",
326
+ {
327
+ title: "Analyze the SEO of a dotCMS page or content item",
328
+ description:
329
+ "Read-only. Check the SEO of one page and report errors, warnings and notes. Pass a page 'path' " +
330
+ "(e.g. '/about-us' or '/blog/post/my-post'), or a 'contentType' with an 'identifier'. " +
331
+ "A regular page is checked from its own fields. A detail page (URL-mapped content) or a content item is " +
332
+ "checked from the content's fields, and its content type is loaded to see whether it has title, " +
333
+ "description and image fields and a sensible URL map pattern. Checks title and description length, " +
334
+ "duplicates, URL shape and images. When the server has DOTCMS_SITE_URL, the rendered HTML is checked too: " +
335
+ "title tag, meta description, canonical, robots, h1, Open Graph tags, image alt text, lang and viewport.",
336
+ inputSchema: {
337
+ path: z
338
+ .string()
339
+ .optional()
340
+ .describe("Page path on the site, e.g. '/about-us' or '/blog/post/my-post' (a full URL is reduced to its path)"),
341
+ contentType: z.string().optional().describe("Content type variable (e.g. 'Blog'); use with 'identifier' instead of 'path'"),
342
+ identifier: z.string().optional().describe("Identifier of the content item; use with 'contentType'"),
343
+ site: z
344
+ .string()
345
+ .optional()
346
+ .describe("Site host name, for a 'path' on a site other than the instance's default one, e.g. 'us.rebuild.development'"),
347
+ languageId: z.number().int().optional().describe("Language id (default: the site's default language)"),
348
+ },
349
+ annotations: READ_ONLY,
350
+ },
351
+ async ({ path, contentType, identifier, site, languageId }) => {
352
+ try {
353
+ if (path && (contentType || identifier)) throw new Error("Pass either 'path', or 'contentType' with 'identifier' — not both.");
354
+ if (!path && !(contentType && identifier)) {
355
+ throw new Error("Pass a page 'path' (e.g. '/about-us'), or 'contentType' together with 'identifier'.");
356
+ }
357
+
358
+ const sources = [];
359
+ const extra = []; // findings that come from the process itself
360
+ let kind;
361
+ let heading;
362
+ let page = null;
363
+ let content = null;
364
+ let ct = null;
365
+ let urlPath = null;
366
+ let siteHostname = null;
367
+
368
+ if (path) {
369
+ urlPath = normalizePagePath(path);
370
+ const segments = urlPath === "/" ? "index" : urlPath.slice(1);
371
+ // Segments arrive percent-encoded from the path; decode first so they are not encoded twice.
372
+ const siteInfo = site ? await resolveSite(site) : null;
373
+ let data;
374
+ try {
375
+ data = await api(`/api/v1/page/render/${segments.split("/").map((s) => encodeURIComponent(decodeURIComponent(s))).join("/")}`, {
376
+ params: { mode: "LIVE", language_id: languageId, host_id: siteInfo?.identifier },
377
+ });
378
+ } catch (err) {
379
+ if (!site && /responded 404/.test(err.message)) {
380
+ err.message += " If the page belongs to another site than the instance's default one, pass 'site' (the site's host name).";
381
+ }
382
+ throw err;
383
+ }
384
+ const entity = data.entity || {};
385
+ page = entity.page || {};
386
+ content = entity.urlContentMap || null;
387
+ siteHostname = entity.site?.hostname || siteInfo?.hostname || null;
388
+ kind = content ? "detail-page" : "page";
389
+ sources.push(
390
+ `Page loaded from the dotCMS page API (live version${page.title ? `, "${page.title}"` : ""}${entity.site?.hostname ? `, site ${entity.site.hostname}` : ""})`,
391
+ );
392
+ if (content) {
393
+ const typeVar = content.contentType || content.contentTypeName;
394
+ if (typeVar) {
395
+ try {
396
+ ct = (await api(`/api/v1/contenttype/id/${encodeURIComponent(typeVar)}`)).entity || null;
397
+ sources.push(`Detail page: SEO values read from the ${ct?.variable || typeVar} content, definition from its content type`);
398
+ } catch (err) {
399
+ sources.push(`Detail page: SEO values read from the content; its content type could not be loaded (${err.message})`);
400
+ }
401
+ }
402
+ } else {
403
+ sources.push("Regular page: SEO values read from the page's own fields");
404
+ }
405
+ heading = `SEO analysis: ${urlPath} (${kind === "detail-page" ? `detail page${ct ? ` · ${ct.variable}` : ""}` : "page"})`;
406
+ } else {
407
+ kind = "content";
408
+ ct = (await api(`/api/v1/contenttype/id/${encodeURIComponent(contentType)}`)).entity;
409
+ if (!ct?.variable) throw new Error(`Content type '${contentType}' not found.`);
410
+ const base = `+contentType:${escapeLucene(ct.variable)} +identifier:${escapeLucene(identifier)}${languageId ? ` +languageId:${languageId}` : ""}`;
411
+ let state = "live";
412
+ let found = (await api("/api/content/_search", { method: "POST", body: { query: `${base} +live:true`, limit: 5 } })).entity?.jsonObjectView?.contentlets || [];
413
+ if (!found.length) {
414
+ state = "working";
415
+ found = (await api("/api/content/_search", { method: "POST", body: { query: `${base} +working:true`, limit: 5 } })).entity?.jsonObjectView?.contentlets || [];
416
+ }
417
+ if (!found.length) throw new Error(`No ${ct.variable} content with identifier '${identifier}'${languageId ? ` in language ${languageId}` : ""} was found.`);
418
+ content = found[0];
419
+ siteHostname = content.hostName || null;
420
+ sources.push(`Content loaded from dotCMS (${state} version), definition from content type ${ct.variable}`);
421
+ 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" });
422
+ if (ct.urlMapPattern) urlPath = urlFromPattern(ct.urlMapPattern, content);
423
+ heading = `SEO analysis: ${ct.variable} content ${identifier}${urlPath ? ` (${urlPath})` : ""}`;
424
+ }
425
+
426
+ // The rendered page, when the public site is known.
427
+ let htmlResult = null;
428
+ if (urlPath && SITE_URL) {
429
+ try {
430
+ const { html, finalUrl } = await fetchSiteHtml(urlPath);
431
+ htmlResult = analyzeHtml(html);
432
+ sources.push(`Rendered HTML checked at ${finalUrl}`);
433
+ const urlNote = await siteUrlNote(siteHostname);
434
+ if (urlNote) sources.push(urlNote);
435
+ } catch (err) {
436
+ sources.push(`Rendered HTML not checked: ${err.message}`);
437
+ }
438
+ } else if (!SITE_URL) {
439
+ sources.push("Rendered HTML not checked (set DOTCMS_SITE_URL to the public site URL to include it)");
440
+ } else {
441
+ sources.push("Rendered HTML not checked (this content has no URL of its own)");
442
+ }
443
+
444
+ const fields = analyzeFields({
445
+ kind,
446
+ page,
447
+ content,
448
+ contentType: ct,
449
+ // The rendered page is the truth for a regular page. For content, a field finding is the cause
450
+ // behind a rendered-page finding, so it is only dropped when the page has the value anyway.
451
+ htmlSeen: {
452
+ title: !!htmlResult && (kind === "page" || !!htmlResult.data.title),
453
+ description: !!htmlResult && (kind === "page" || !!htmlResult.data.description),
454
+ },
455
+ });
456
+ const findings = [
457
+ ...extra,
458
+ ...fields.findings,
459
+ ...(htmlResult?.findings || []),
460
+ ...crossCheck(fields.data, htmlResult?.data),
461
+ ...(urlPath ? checkUrl(urlPath) : []),
462
+ ];
463
+ if (kind === "detail-page" && !htmlResult) {
464
+ findings.push({
465
+ severity: "info",
466
+ id: "detail-title-from-template",
467
+ 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.",
468
+ where: "template",
469
+ });
470
+ }
471
+
472
+ return {
473
+ content: [
474
+ { type: "text", text: renderSeoReport({ heading, sources, findings }) },
475
+ {
476
+ type: "text",
477
+ text: JSON.stringify(
478
+ {
479
+ kind,
480
+ path: urlPath || undefined,
481
+ contentType: ct?.variable,
482
+ summary: summarize(findings),
483
+ sources,
484
+ values: fields.data,
485
+ rendered: htmlResult?.data,
486
+ findings,
487
+ },
488
+ null,
489
+ 2,
490
+ ),
491
+ },
492
+ ],
493
+ };
494
+ } catch (err) {
495
+ return fail(err);
496
+ }
497
+ },
498
+ );
499
+
500
+ const AUDIT_HTML_BUDGET_MS = 45_000; // stop fetching rendered pages after this; the rest use page fields only
501
+ const AUDIT_HTML_CONCURRENCY = 4;
502
+
503
+ /** Run fn over items with at most `size` running at once; results keep the order of items. */
504
+ async function mapPool(items, size, fn) {
505
+ const out = new Array(items.length);
506
+ let next = 0;
507
+ await Promise.all(
508
+ Array.from({ length: Math.min(size, items.length) }, async () => {
509
+ while (next < items.length) {
510
+ const i = next++;
511
+ out[i] = await fn(items[i], i);
512
+ }
513
+ }),
514
+ );
515
+ return out;
516
+ }
517
+
518
+ server.registerTool(
519
+ "audit_seo_pages",
520
+ {
521
+ title: "Audit the SEO of all pages in a folder",
522
+ description:
523
+ "Read-only. Check the SEO of every live page under a folder (default: the whole site) and report one line per " +
524
+ "page — errors, warnings and the top problems — most serious first, plus the problems that occur most often. " +
525
+ "Each page gets the same checks as analyze_seo for a regular page: title and description from the page's fields, " +
526
+ "URL shape, and, when the server has DOTCMS_SITE_URL, the rendered HTML. Pages are listed 'limit' at a time; " +
527
+ "ask for the next 'page' to continue. Detail pages (URL-mapped content) are not pages in dotCMS: check one with analyze_seo.",
528
+ inputSchema: {
529
+ folder: z.string().default("/").describe("Folder to audit, including its subfolders, e.g. '/blog' (default: '/', the whole site)"),
530
+ site: z.string().optional().describe("Site host name. Required when pages under the folder exist on several sites"),
531
+ languageId: z.number().int().optional().describe("Language id (default: the lowest language id each page has, usually the default language)"),
532
+ limit: z.number().int().min(1).max(100).default(25).describe("Pages to check per call"),
533
+ page: z.number().int().min(1).default(1).describe("Which batch of pages to check"),
534
+ onlyIssues: z.boolean().default(false).describe("List only pages that have errors or warnings"),
535
+ },
536
+ annotations: READ_ONLY,
537
+ },
538
+ async ({ folder, site, languageId, limit, page, onlyIssues }) => {
539
+ try {
540
+ const folderPath = normalizePagePath(folder);
541
+ const clauses = ["+baseType:5", "+live:true"];
542
+ if (folderPath !== "/") clauses.push(`+path:*${escapeLucene(folderPath.toLowerCase())}/*`);
543
+ // Filter by site inside the search, so totals and batches count only that site's pages.
544
+ const siteInfo = site ? await resolveSite(site) : null;
545
+ if (siteInfo) clauses.push(`+conhost:${siteInfo.identifier}`);
546
+ const offset = (page - 1) * limit;
547
+ const data = await api("/api/content/_search", {
548
+ method: "POST",
549
+ body: { query: clauses.join(" "), sort: "path asc", limit, offset },
550
+ });
551
+ const entity = data.entity || {};
552
+ const total = entity.resultsSize ?? 0;
553
+ let pages = (entity.jsonObjectView?.contentlets || []).filter(
554
+ (p) => typeof p.path === "string" && (folderPath === "/" || p.path.toLowerCase().startsWith(`${folderPath.toLowerCase()}/`)),
555
+ );
556
+
557
+ const sites = [...new Set(pages.map((p) => p.hostName).filter(Boolean))];
558
+ if (siteInfo) pages = pages.filter((p) => p.hostName?.toLowerCase() === siteInfo.hostname.toLowerCase());
559
+ else if (sites.length > 1) throw new Error(`Pages under ${folderPath} exist on several sites (${sites.join(", ")}). Pass 'site'.`);
560
+ const siteName = siteInfo?.hostname || sites[0];
561
+
562
+ if (languageId !== undefined) pages = pages.filter((p) => p.languageId === languageId);
563
+ else {
564
+ const lowest = new Map();
565
+ for (const p of pages) if (!lowest.has(p.identifier) || p.languageId < lowest.get(p.identifier).languageId) lowest.set(p.identifier, p);
566
+ pages = [...lowest.values()];
567
+ }
568
+
569
+ const deadline = Date.now() + AUDIT_HTML_BUDGET_MS;
570
+ let htmlFailures = 0;
571
+ let htmlSkipped = 0;
572
+ const rows = await mapPool(pages, AUDIT_HTML_CONCURRENCY, async (p) => {
573
+ const urlPath = p.path.replace(/\/index$/i, "") || "/";
574
+ let htmlResult = null;
575
+ if (SITE_URL) {
576
+ const segments = urlPath.split("/");
577
+ if (Date.now() >= deadline || segments.some((s) => s === "." || s === "..")) htmlSkipped++;
578
+ else {
579
+ try {
580
+ htmlResult = analyzeHtml((await fetchSiteHtml(segments.map(encodeURIComponent).join("/"))).html);
581
+ } catch {
582
+ htmlFailures++;
583
+ }
584
+ }
585
+ }
586
+ const fields = analyzeFields({ kind: "page", page: p, htmlSeen: { title: !!htmlResult, description: !!htmlResult } });
587
+ const findings = [...fields.findings, ...(htmlResult?.findings || []), ...crossCheck(fields.data, htmlResult?.data), ...checkUrl(urlPath)];
588
+ return auditRow({ path: urlPath, title: fields.data.title || htmlResult?.data.title, findings, htmlChecked: !!htmlResult });
589
+ });
590
+
591
+ const checked = rows.filter((r) => r.htmlChecked).length;
592
+ const sources = [
593
+ `Pages listed from the dotCMS content search (live versions${siteName ? `, site ${siteName}` : ""}); each page's own fields are checked`,
594
+ !SITE_URL
595
+ ? "Rendered HTML not checked (set DOTCMS_SITE_URL to the public site URL to include it)"
596
+ : `Rendered HTML checked for ${checked} of ${rows.length} pages at ${SITE_URL}` +
597
+ (htmlFailures ? `; ${htmlFailures} could not be fetched` : "") +
598
+ (htmlSkipped ? `; ${htmlSkipped} skipped (time limit or unusual path)` : ""),
599
+ ];
600
+ const urlNote = checked ? await siteUrlNote(siteName) : null;
601
+ if (urlNote) sources.push(urlNote);
602
+ const nextPage = offset + limit < total ? page + 1 : null;
603
+ const heading = `SEO audit: ${folderPath}${siteName ? ` on ${siteName}` : ""} (batch ${page})`;
604
+
605
+ return {
606
+ content: [
607
+ { type: "text", text: renderAuditReport({ heading, sources, rows, total, nextPage, onlyIssues }) },
608
+ {
609
+ type: "text",
610
+ text: JSON.stringify(
611
+ {
612
+ folder: folderPath,
613
+ site: siteName,
614
+ batch: page,
615
+ limit,
616
+ matched: total,
617
+ checked: rows.length,
618
+ nextPage,
619
+ sources,
620
+ commonIssues: commonIssues(rows),
621
+ pages: sortRows(onlyIssues ? rows.filter((r) => r.errors || r.warnings) : rows),
622
+ },
623
+ null,
624
+ 2,
625
+ ),
626
+ },
627
+ ],
628
+ };
629
+ } catch (err) {
630
+ return fail(err);
631
+ }
632
+ },
633
+ );
634
+
279
635
  server.registerTool(
280
636
  "list_vtl_files",
281
637
  {
@@ -591,6 +947,67 @@ if (ALLOW_WRITE) {
591
947
  );
592
948
  }
593
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
+
594
1011
  await server.connect(new StdioServerTransport());
595
1012
  console.error(
596
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.2.0",
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", "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": {