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.
- package/README.md +77 -0
- package/dotcms.js +65 -1
- package/guides.js +277 -0
- package/index.js +418 -1
- package/package.json +2 -2
- package/seo.js +365 -0
- 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
|
@@ -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,9 @@ 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 |
|
|
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 |
|
|
116
120
|
| `list_vtl_files` | Finds VTL files by folder and/or file name, with paging |
|
|
117
121
|
| `read_vtl_file` | Returns the source of a VTL file by path or identifier, optionally for a specific site or language |
|
|
118
122
|
|
|
@@ -139,6 +143,78 @@ Blog (Blog)
|
|
|
139
143
|
|
|
140
144
|
A type that was already shown higher up is not expanded again, so circular relationships don't loop.
|
|
141
145
|
|
|
146
|
+
#### SEO analysis
|
|
147
|
+
|
|
148
|
+
`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`:
|
|
149
|
+
|
|
150
|
+
| You give | It checks |
|
|
151
|
+
| --- | --- |
|
|
152
|
+
| `path` of a regular (drag-and-drop) page | The page's own fields: title and description |
|
|
153
|
+
| `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 |
|
|
154
|
+
| `contentType` + `identifier` | The content item and its content type; the URL is built from the URL map pattern |
|
|
155
|
+
|
|
156
|
+
What it looks for:
|
|
157
|
+
|
|
158
|
+
- title and description present, and within 30–60 and 70–160 characters
|
|
159
|
+
- title identical to the description
|
|
160
|
+
- URL shape: length, uppercase, underscores, spaces, file extensions, depth
|
|
161
|
+
- missing image for social previews
|
|
162
|
+
- content types with no description field, no URL map pattern, or a pattern built from an id
|
|
163
|
+
|
|
164
|
+
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.
|
|
165
|
+
|
|
166
|
+
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.
|
|
167
|
+
|
|
168
|
+
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.
|
|
169
|
+
|
|
170
|
+
**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.
|
|
171
|
+
|
|
172
|
+
#### SEO audit of many pages
|
|
173
|
+
|
|
174
|
+
`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.
|
|
175
|
+
|
|
176
|
+
```
|
|
177
|
+
SEO audit: /blog on demo.dotcms.com (batch 1)
|
|
178
|
+
|
|
179
|
+
3 page(s) checked: 0 with errors · 2 with warnings only · 1 without problems
|
|
180
|
+
|
|
181
|
+
⚠2 /blog/first-post — Title (title) is 2 characters; aim for 30–60. · No description value found.
|
|
182
|
+
⚠1 /blog/second_post — The URL uses underscores; hyphens are read as word separators, underscores are not.
|
|
183
|
+
✓ /blog
|
|
184
|
+
|
|
185
|
+
Most common problems:
|
|
186
|
+
1 page(s) · description-missing (warning)
|
|
187
|
+
1 page(s) · title-short (warning)
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
| Option | Default | Purpose |
|
|
191
|
+
| --- | --- | --- |
|
|
192
|
+
| `folder` | `/` | Folder to audit, including subfolders |
|
|
193
|
+
| `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 |
|
|
194
|
+
| `languageId` | lowest per page | Which language version to check |
|
|
195
|
+
| `limit`, `page` | 25, 1 | Pages per call (up to 100), and which batch. The report says when more pages exist |
|
|
196
|
+
| `onlyIssues` | `false` | List only pages with errors or warnings |
|
|
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`.
|
|
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
|
+
|
|
142
218
|
### Only with `DOTCMS_ALLOW_WRITE=true`
|
|
143
219
|
|
|
144
220
|
| Tool | What it does |
|
|
@@ -187,6 +263,7 @@ The package ships a `PreToolUse` hook that shows the full plan and asks for appr
|
|
|
187
263
|
## Troubleshooting
|
|
188
264
|
|
|
189
265
|
- **`Cannot reach dotCMS at …`** — the instance isn't running or isn't reachable from this machine. Check `DOTCMS_URL`.
|
|
266
|
+
- **`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
267
|
- **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
268
|
- **401 / 403 responses** — the token is missing, expired, or belongs to a different instance. Tokens are per instance.
|
|
192
269
|
- **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/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
|
+
}
|