dotcms-custom-mcp 0.0.0-stage → 1.2.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 +199 -2
- package/dotcms.js +258 -0
- package/hooks/confirm-write.mjs +41 -0
- package/index.js +601 -0
- package/package.json +39 -4
- package/plans.js +111 -0
- package/relations.js +171 -0
package/index.js
ADDED
|
@@ -0,0 +1,601 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// Local MCP server for dotCMS.
|
|
3
|
+
//
|
|
4
|
+
// Read-only tools (always available):
|
|
5
|
+
// list_content_types, get_content_type_fields, get_content_type_relations,
|
|
6
|
+
// list_vtl_files, read_vtl_file
|
|
7
|
+
// Write tools (only when DOTCMS_ALLOW_WRITE=true, limited to DOTCMS_WRITE_ROOTS):
|
|
8
|
+
// plan_vtl_change (plans only, writes nothing) -> apply_vtl_change (writes, human-confirmed)
|
|
9
|
+
//
|
|
10
|
+
// Config: see dotcms.js.
|
|
11
|
+
|
|
12
|
+
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
|
13
|
+
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
|
14
|
+
import crypto from "node:crypto";
|
|
15
|
+
import { z } from "zod";
|
|
16
|
+
import {
|
|
17
|
+
ALLOW_WRITE,
|
|
18
|
+
BASE_URL,
|
|
19
|
+
CONFIRM,
|
|
20
|
+
INSECURE_TRANSPORT,
|
|
21
|
+
READ_EXTENSIONS,
|
|
22
|
+
TOKEN,
|
|
23
|
+
WRITE_ROOTS,
|
|
24
|
+
api,
|
|
25
|
+
assertReadable,
|
|
26
|
+
assertSite,
|
|
27
|
+
downloadFile,
|
|
28
|
+
ensureFolder,
|
|
29
|
+
escapeLucene,
|
|
30
|
+
findFiles,
|
|
31
|
+
parseWritePath,
|
|
32
|
+
pickVersion,
|
|
33
|
+
saveFile,
|
|
34
|
+
searchFiles,
|
|
35
|
+
} from "./dotcms.js";
|
|
36
|
+
import { deletePlan, diffLines, loadPlan, renderPlan, savePlan } from "./plans.js";
|
|
37
|
+
import { buildRelationTree, renderRelationTree } from "./relations.js";
|
|
38
|
+
|
|
39
|
+
const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
|
|
40
|
+
const MAX_FILE_CHARS = 200_000;
|
|
41
|
+
|
|
42
|
+
// Field classes that only describe the edit-form layout, not real data.
|
|
43
|
+
const LAYOUT_FIELDS = new Set([
|
|
44
|
+
"RowField",
|
|
45
|
+
"ColumnField",
|
|
46
|
+
"TabDividerField",
|
|
47
|
+
"LineDividerField",
|
|
48
|
+
"ColumnBreakField",
|
|
49
|
+
]);
|
|
50
|
+
|
|
51
|
+
const shortClass = (clazz = "") => clazz.split(".").pop().replace(/^Immutable/, "");
|
|
52
|
+
|
|
53
|
+
function mapField(field) {
|
|
54
|
+
const out = {
|
|
55
|
+
name: field.name,
|
|
56
|
+
variable: field.variable,
|
|
57
|
+
type: field.fieldType || shortClass(field.clazz).replace(/Field$/, ""),
|
|
58
|
+
class: shortClass(field.clazz),
|
|
59
|
+
dataType: field.dataType,
|
|
60
|
+
required: !!field.required,
|
|
61
|
+
unique: !!field.unique,
|
|
62
|
+
indexed: !!field.indexed,
|
|
63
|
+
searchable: !!field.searchable,
|
|
64
|
+
listed: !!field.listed,
|
|
65
|
+
system: !!field.fixed,
|
|
66
|
+
};
|
|
67
|
+
if (field.hint) out.hint = field.hint;
|
|
68
|
+
if (field.defaultValue) out.defaultValue = field.defaultValue;
|
|
69
|
+
if (field.values) out.values = field.values;
|
|
70
|
+
if (field.regexCheck) out.regexCheck = field.regexCheck;
|
|
71
|
+
if (field.relationships) out.relationships = field.relationships;
|
|
72
|
+
if (field.categories) out.categories = field.categories;
|
|
73
|
+
if (field.fieldVariables?.length) {
|
|
74
|
+
out.fieldVariables = Object.fromEntries(field.fieldVariables.map((v) => [v.key, v.value]));
|
|
75
|
+
}
|
|
76
|
+
return out;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
const mapFile = (f) => ({
|
|
80
|
+
path: f.path,
|
|
81
|
+
name: f.fileName || f.name,
|
|
82
|
+
site: f.hostName,
|
|
83
|
+
identifier: f.identifier,
|
|
84
|
+
inode: f.inode,
|
|
85
|
+
languageId: f.languageId,
|
|
86
|
+
size: f.size,
|
|
87
|
+
modDate: f.modDate,
|
|
88
|
+
live: f.live,
|
|
89
|
+
description: f.description || undefined,
|
|
90
|
+
});
|
|
91
|
+
|
|
92
|
+
const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
|
|
93
|
+
const fail = (err) => ({ isError: true, content: [{ type: "text", text: err.message }] });
|
|
94
|
+
|
|
95
|
+
const server = new McpServer({ name: "dotcms", version: "1.2.0" });
|
|
96
|
+
|
|
97
|
+
// ---------------------------------------------------------------------------
|
|
98
|
+
// Read-only tools
|
|
99
|
+
// ---------------------------------------------------------------------------
|
|
100
|
+
|
|
101
|
+
server.registerTool(
|
|
102
|
+
"list_content_types",
|
|
103
|
+
{
|
|
104
|
+
title: "List dotCMS content types",
|
|
105
|
+
description:
|
|
106
|
+
"Read-only. List content types in dotCMS (name, variable, base type, number of content entries). " +
|
|
107
|
+
"Use it to find the variable name of a content type before reading its fields.",
|
|
108
|
+
inputSchema: {
|
|
109
|
+
filter: z.string().optional().describe("Filter by name or variable (substring)"),
|
|
110
|
+
type: z
|
|
111
|
+
.enum(["CONTENT", "WIDGET", "FORM", "FILEASSET", "HTMLPAGE", "PERSONA", "VANITY_URL", "KEY_VALUE", "DOTASSET"])
|
|
112
|
+
.optional()
|
|
113
|
+
.describe("Only content types of this base type"),
|
|
114
|
+
page: z.number().int().min(1).default(1).describe("Page number"),
|
|
115
|
+
perPage: z.number().int().min(1).max(100).default(50).describe("Items per page"),
|
|
116
|
+
},
|
|
117
|
+
annotations: READ_ONLY,
|
|
118
|
+
},
|
|
119
|
+
async ({ filter, type, page, perPage }) => {
|
|
120
|
+
try {
|
|
121
|
+
const data = await api("/api/v1/contenttype", {
|
|
122
|
+
params: { filter, type, page, per_page: perPage, orderby: "name", direction: "ASC" },
|
|
123
|
+
});
|
|
124
|
+
const types = (data.entity || []).map((ct) => ({
|
|
125
|
+
name: ct.name,
|
|
126
|
+
variable: ct.variable,
|
|
127
|
+
id: ct.id,
|
|
128
|
+
baseType: ct.baseType,
|
|
129
|
+
description: ct.description || undefined,
|
|
130
|
+
entries: ct.nEntries,
|
|
131
|
+
system: !!ct.system,
|
|
132
|
+
}));
|
|
133
|
+
return ok({
|
|
134
|
+
page,
|
|
135
|
+
perPage,
|
|
136
|
+
total: data.pagination?.totalEntries,
|
|
137
|
+
count: types.length,
|
|
138
|
+
contentTypes: types,
|
|
139
|
+
});
|
|
140
|
+
} catch (err) {
|
|
141
|
+
return fail(err);
|
|
142
|
+
}
|
|
143
|
+
},
|
|
144
|
+
);
|
|
145
|
+
|
|
146
|
+
server.registerTool(
|
|
147
|
+
"get_content_type_fields",
|
|
148
|
+
{
|
|
149
|
+
title: "Get fields of a dotCMS content type",
|
|
150
|
+
description:
|
|
151
|
+
"Read-only. Return the fields of a dotCMS content type: name, variable, field type, data type, " +
|
|
152
|
+
"required/unique/indexed/searchable/listed flags, hint, default value, allowed values, " +
|
|
153
|
+
"relationships and field variables.",
|
|
154
|
+
inputSchema: {
|
|
155
|
+
contentType: z.string().min(1).describe("Content type variable name (e.g. 'Blog') or its id"),
|
|
156
|
+
includeLayout: z
|
|
157
|
+
.boolean()
|
|
158
|
+
.default(false)
|
|
159
|
+
.describe("Also include layout-only fields (rows, columns, tab dividers)"),
|
|
160
|
+
},
|
|
161
|
+
annotations: READ_ONLY,
|
|
162
|
+
},
|
|
163
|
+
async ({ contentType, includeLayout }) => {
|
|
164
|
+
try {
|
|
165
|
+
const data = await api(`/api/v1/contenttype/id/${encodeURIComponent(contentType)}`);
|
|
166
|
+
const ct = data.entity || {};
|
|
167
|
+
const fields = (ct.fields || [])
|
|
168
|
+
.filter((f) => includeLayout || !LAYOUT_FIELDS.has(shortClass(f.clazz)))
|
|
169
|
+
.map(mapField);
|
|
170
|
+
return ok({
|
|
171
|
+
name: ct.name,
|
|
172
|
+
variable: ct.variable,
|
|
173
|
+
id: ct.id,
|
|
174
|
+
baseType: ct.baseType,
|
|
175
|
+
description: ct.description || undefined,
|
|
176
|
+
urlMapPattern: ct.urlMapPattern || undefined,
|
|
177
|
+
detailPage: ct.detailPage || undefined,
|
|
178
|
+
fieldCount: fields.length,
|
|
179
|
+
fields,
|
|
180
|
+
});
|
|
181
|
+
} catch (err) {
|
|
182
|
+
return fail(err);
|
|
183
|
+
}
|
|
184
|
+
},
|
|
185
|
+
);
|
|
186
|
+
|
|
187
|
+
const MAX_TYPES_SCANNED = 500;
|
|
188
|
+
|
|
189
|
+
/** Every content type with its fields, for finding relationships declared on other types. */
|
|
190
|
+
async function getAllContentTypes() {
|
|
191
|
+
const all = [];
|
|
192
|
+
for (let page = 1; ; page++) {
|
|
193
|
+
const data = await api("/api/v1/contenttype", { params: { page, per_page: 100, orderby: "name", direction: "ASC" } });
|
|
194
|
+
const batch = data.entity || [];
|
|
195
|
+
all.push(...batch);
|
|
196
|
+
const total = data.pagination?.totalEntries ?? all.length;
|
|
197
|
+
if (!batch.length || all.length >= total) break;
|
|
198
|
+
if (all.length >= MAX_TYPES_SCANNED) {
|
|
199
|
+
throw new Error(`more than ${MAX_TYPES_SCANNED} content types`);
|
|
200
|
+
}
|
|
201
|
+
}
|
|
202
|
+
// Older dotCMS versions list content types without their fields: fetch those one by one.
|
|
203
|
+
const missing = all.filter((ct) => !Array.isArray(ct.fields));
|
|
204
|
+
for (let i = 0; i < missing.length; i += 8) {
|
|
205
|
+
await Promise.all(
|
|
206
|
+
missing.slice(i, i + 8).map(async (ct) => {
|
|
207
|
+
try {
|
|
208
|
+
ct.fields = (await api(`/api/v1/contenttype/id/${encodeURIComponent(ct.variable)}`)).entity?.fields || [];
|
|
209
|
+
} catch {
|
|
210
|
+
ct.fields = [];
|
|
211
|
+
}
|
|
212
|
+
}),
|
|
213
|
+
);
|
|
214
|
+
}
|
|
215
|
+
return all;
|
|
216
|
+
}
|
|
217
|
+
|
|
218
|
+
server.registerTool(
|
|
219
|
+
"get_content_type_relations",
|
|
220
|
+
{
|
|
221
|
+
title: "Get the relationship tree of a dotCMS content type",
|
|
222
|
+
description:
|
|
223
|
+
"Read-only. Show everything a content type is connected to: its relationship fields, the related " +
|
|
224
|
+
"content types, and their relationships in turn, as a tree (text drawing plus JSON). For each " +
|
|
225
|
+
"connection it gives the field, the related type, the cardinality (ONE_TO_MANY, MANY_TO_MANY, " +
|
|
226
|
+
"ONE_TO_ONE, MANY_TO_ONE), which side this type is on, and the field on the other side. " +
|
|
227
|
+
"Also lists category fields, and relationships that only the other content type declares.",
|
|
228
|
+
inputSchema: {
|
|
229
|
+
contentType: z.string().min(1).describe("Content type variable name (e.g. 'Blog') or its id"),
|
|
230
|
+
depth: z
|
|
231
|
+
.number()
|
|
232
|
+
.int()
|
|
233
|
+
.min(1)
|
|
234
|
+
.max(5)
|
|
235
|
+
.default(2)
|
|
236
|
+
.describe("How many levels of related content types to follow (1 = direct relations only)"),
|
|
237
|
+
includeIncoming: z
|
|
238
|
+
.boolean()
|
|
239
|
+
.default(true)
|
|
240
|
+
.describe("Also find relationships declared only on other content types that point at this one (scans all content types)"),
|
|
241
|
+
includeFields: z
|
|
242
|
+
.boolean()
|
|
243
|
+
.default(false)
|
|
244
|
+
.describe("Also list the non-relationship fields (variable, type, required) of every content type in the tree"),
|
|
245
|
+
},
|
|
246
|
+
annotations: READ_ONLY,
|
|
247
|
+
},
|
|
248
|
+
async ({ contentType, depth, includeIncoming, includeFields }) => {
|
|
249
|
+
try {
|
|
250
|
+
const { tree, warnings, contentTypes } = await buildRelationTree({
|
|
251
|
+
root: contentType,
|
|
252
|
+
depth,
|
|
253
|
+
includeIncoming,
|
|
254
|
+
includeFields,
|
|
255
|
+
getType: async (variable) => {
|
|
256
|
+
const ct = (await api(`/api/v1/contenttype/id/${encodeURIComponent(variable)}`)).entity;
|
|
257
|
+
if (!ct?.variable) throw new Error(`Content type '${variable}' not found.`);
|
|
258
|
+
return ct;
|
|
259
|
+
},
|
|
260
|
+
getAllTypes: getAllContentTypes,
|
|
261
|
+
describeField: (f) => {
|
|
262
|
+
if (LAYOUT_FIELDS.has(shortClass(f.clazz))) return null;
|
|
263
|
+
const m = mapField(f);
|
|
264
|
+
return { variable: m.variable, name: m.name, type: m.type, required: m.required };
|
|
265
|
+
},
|
|
266
|
+
});
|
|
267
|
+
return {
|
|
268
|
+
content: [
|
|
269
|
+
{ type: "text", text: renderRelationTree(tree) + (warnings.length ? `\n\n${warnings.map((w) => `Note: ${w}`).join("\n")}` : "") },
|
|
270
|
+
{ type: "text", text: JSON.stringify({ root: tree.variable, depth, contentTypes, warnings, tree }, null, 2) },
|
|
271
|
+
],
|
|
272
|
+
};
|
|
273
|
+
} catch (err) {
|
|
274
|
+
return fail(err);
|
|
275
|
+
}
|
|
276
|
+
},
|
|
277
|
+
);
|
|
278
|
+
|
|
279
|
+
server.registerTool(
|
|
280
|
+
"list_vtl_files",
|
|
281
|
+
{
|
|
282
|
+
title: "List VTL files in dotCMS",
|
|
283
|
+
description:
|
|
284
|
+
"Read-only. Find Velocity (.vtl) files stored in dotCMS as file assets: container, template, " +
|
|
285
|
+
"theme, custom-field and scripting-API VTL files. Returns path, site, identifier, language, size and modification date.",
|
|
286
|
+
inputSchema: {
|
|
287
|
+
folder: z
|
|
288
|
+
.string()
|
|
289
|
+
.optional()
|
|
290
|
+
.describe("Only files whose path contains this folder, e.g. '/application/vtl' or 'containers/banner'"),
|
|
291
|
+
name: z.string().optional().describe("Only files whose file name contains this text, e.g. 'banner'"),
|
|
292
|
+
extension: z.string().default("vtl").describe(`File extension to look for (default 'vtl'; allowed: ${READ_EXTENSIONS.join(", ")})`),
|
|
293
|
+
page: z.number().int().min(1).default(1).describe("Page number"),
|
|
294
|
+
perPage: z.number().int().min(1).max(100).default(50).describe("Items per page"),
|
|
295
|
+
},
|
|
296
|
+
annotations: READ_ONLY,
|
|
297
|
+
},
|
|
298
|
+
async ({ folder, name, extension, page, perPage }) => {
|
|
299
|
+
try {
|
|
300
|
+
assertReadable(`x.${extension.replace(/^\./, "")}`);
|
|
301
|
+
const ext = escapeLucene(extension.replace(/^\./, "").toLowerCase());
|
|
302
|
+
const clauses = [`+path:*.${ext}`];
|
|
303
|
+
if (folder) {
|
|
304
|
+
const f = escapeLucene(folder.toLowerCase().replace(/^\/+|\/+$/g, ""));
|
|
305
|
+
clauses.push(`+path:*${f}/*`);
|
|
306
|
+
}
|
|
307
|
+
if (name) clauses.push(`+title:*${escapeLucene(name.toLowerCase())}*`);
|
|
308
|
+
|
|
309
|
+
const { total, files } = await searchFiles(clauses, {
|
|
310
|
+
limit: perPage,
|
|
311
|
+
offset: (page - 1) * perPage,
|
|
312
|
+
});
|
|
313
|
+
return ok({ page, perPage, total, count: files.length, files: files.map(mapFile) });
|
|
314
|
+
} catch (err) {
|
|
315
|
+
return fail(err);
|
|
316
|
+
}
|
|
317
|
+
},
|
|
318
|
+
);
|
|
319
|
+
|
|
320
|
+
server.registerTool(
|
|
321
|
+
"read_vtl_file",
|
|
322
|
+
{
|
|
323
|
+
title: "Read a VTL file from dotCMS",
|
|
324
|
+
description:
|
|
325
|
+
"Read-only. Return the source of a Velocity (.vtl) file stored in dotCMS. Pass either the full " +
|
|
326
|
+
"path (e.g. '/application/containers/banner/banner.vtl') or the file identifier from list_vtl_files.",
|
|
327
|
+
inputSchema: {
|
|
328
|
+
path: z.string().optional().describe("Full path of the file inside the site"),
|
|
329
|
+
identifier: z.string().optional().describe("File identifier (alternative to path)"),
|
|
330
|
+
site: z.string().optional().describe("Site host name, if the same path exists on several sites"),
|
|
331
|
+
languageId: z
|
|
332
|
+
.number()
|
|
333
|
+
.int()
|
|
334
|
+
.optional()
|
|
335
|
+
.describe("Language id, if the file has several language versions (default: the lowest id, usually the default language)"),
|
|
336
|
+
},
|
|
337
|
+
annotations: READ_ONLY,
|
|
338
|
+
},
|
|
339
|
+
async ({ path, identifier, site, languageId }) => {
|
|
340
|
+
try {
|
|
341
|
+
if (!path && !identifier) throw new Error("Pass either 'path' or 'identifier'.");
|
|
342
|
+
const files = await findFiles({ path, identifier, site });
|
|
343
|
+
const { file, languages } = pickVersion(files, { what: identifier || path, site, languageId });
|
|
344
|
+
assertReadable(file.fileName || file.name || file.path);
|
|
345
|
+
|
|
346
|
+
const content = await downloadFile(file);
|
|
347
|
+
const truncated = content.length > MAX_FILE_CHARS;
|
|
348
|
+
return ok({
|
|
349
|
+
...mapFile(file),
|
|
350
|
+
availableLanguageIds: languages,
|
|
351
|
+
truncated,
|
|
352
|
+
content: truncated ? content.slice(0, MAX_FILE_CHARS) : content,
|
|
353
|
+
});
|
|
354
|
+
} catch (err) {
|
|
355
|
+
return fail(err);
|
|
356
|
+
}
|
|
357
|
+
},
|
|
358
|
+
);
|
|
359
|
+
|
|
360
|
+
// ---------------------------------------------------------------------------
|
|
361
|
+
// Write tools — opt-in, limited to WRITE_ROOTS. Plan first, then the
|
|
362
|
+
// human check (hooks/confirm-write.mjs), then the write.
|
|
363
|
+
// ---------------------------------------------------------------------------
|
|
364
|
+
|
|
365
|
+
if (ALLOW_WRITE) {
|
|
366
|
+
const roots = WRITE_ROOTS.join(" and ");
|
|
367
|
+
|
|
368
|
+
// Fingerprints of the plans this process created. apply_vtl_change refuses a plan whose
|
|
369
|
+
// file on disk no longer matches, so editing a plan file cannot change what gets written.
|
|
370
|
+
const planFingerprints = new Map();
|
|
371
|
+
const fingerprint = (plan) => crypto.createHash("sha256").update(JSON.stringify(plan)).digest("hex");
|
|
372
|
+
|
|
373
|
+
/**
|
|
374
|
+
* Ask the user through the client (MCP elicitation) when it can. Returns "confirmed",
|
|
375
|
+
* "declined", or "unsupported" when the client cannot ask — its own tool approval is then
|
|
376
|
+
* the only check.
|
|
377
|
+
*/
|
|
378
|
+
async function confirmWithUser(plan) {
|
|
379
|
+
if (!CONFIRM || !server.server.getClientCapabilities()?.elicitation) return "unsupported";
|
|
380
|
+
let answer;
|
|
381
|
+
try {
|
|
382
|
+
answer = await server.server.elicitInput({
|
|
383
|
+
message: `Apply this change to dotCMS?\n\n${renderPlan(plan)}`,
|
|
384
|
+
requestedSchema: {
|
|
385
|
+
type: "object",
|
|
386
|
+
properties: {
|
|
387
|
+
apply: { type: "boolean", title: "Apply this change", description: `${plan.action} ${plan.path} on ${plan.site}` },
|
|
388
|
+
},
|
|
389
|
+
required: ["apply"],
|
|
390
|
+
},
|
|
391
|
+
}, { timeout: 10 * 60 * 1000 }); // give the user time to read the diff
|
|
392
|
+
} catch (err) {
|
|
393
|
+
if (/does not support/i.test(err.message)) return "unsupported";
|
|
394
|
+
throw err;
|
|
395
|
+
}
|
|
396
|
+
return answer.action === "accept" && answer.content?.apply === true ? "confirmed" : "declined";
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
server.registerTool(
|
|
400
|
+
"plan_vtl_change",
|
|
401
|
+
{
|
|
402
|
+
title: "Plan a VTL file change in dotCMS",
|
|
403
|
+
description:
|
|
404
|
+
"Step 1 of 2 for every write. Does NOT change dotCMS: it validates the target, compares the new " +
|
|
405
|
+
"source with the current file and returns a plan (action, target, diff, warnings) with a planId. " +
|
|
406
|
+
`Writable locations: ${roots} — scripting-API files (e.g. /application/apivtl/my-endpoint/get.vtl, ` +
|
|
407
|
+
"file name = HTTP method) and custom fields (e.g. /application/vtl/custom-fields/my-field/code.vtl). " +
|
|
408
|
+
"Whether it is a create or an update is detected from whether the file exists. " +
|
|
409
|
+
"Show the returned plan to the user, then call apply_vtl_change with the planId.",
|
|
410
|
+
inputSchema: {
|
|
411
|
+
path: z.string().min(1).describe(`Full path of the file, inside ${roots}`),
|
|
412
|
+
site: z
|
|
413
|
+
.string()
|
|
414
|
+
.optional()
|
|
415
|
+
.describe("Site host name. Required for a new file, or when the path exists on several sites"),
|
|
416
|
+
content: z
|
|
417
|
+
.string()
|
|
418
|
+
.min(1)
|
|
419
|
+
.max(MAX_FILE_CHARS)
|
|
420
|
+
.describe("Full Velocity source of the file (the whole file, not a patch)"),
|
|
421
|
+
languageId: z.number().int().optional().describe("Language id (default: the default language)"),
|
|
422
|
+
publish: z
|
|
423
|
+
.boolean()
|
|
424
|
+
.default(false)
|
|
425
|
+
.describe("Publish immediately. Default false: save a working version only, the live file stays as it is"),
|
|
426
|
+
},
|
|
427
|
+
annotations: READ_ONLY,
|
|
428
|
+
},
|
|
429
|
+
async ({ path, site, content, languageId, publish }) => {
|
|
430
|
+
try {
|
|
431
|
+
const target = parseWritePath(path);
|
|
432
|
+
if (site !== undefined) assertSite(site);
|
|
433
|
+
const files = await findFiles({ path: target.full, site });
|
|
434
|
+
|
|
435
|
+
let action = "CREATE";
|
|
436
|
+
let base = null;
|
|
437
|
+
let current = "";
|
|
438
|
+
if (files.length) {
|
|
439
|
+
const { file } = pickVersion(files, { what: target.full, site, languageId });
|
|
440
|
+
action = "UPDATE";
|
|
441
|
+
base = { identifier: file.identifier, inode: file.inode, live: !!file.live };
|
|
442
|
+
site = file.hostName;
|
|
443
|
+
languageId = file.languageId;
|
|
444
|
+
current = await downloadFile(file);
|
|
445
|
+
} else if (!site) {
|
|
446
|
+
throw new Error(`${target.full} does not exist yet. Pass 'site' to plan creating it.`);
|
|
447
|
+
}
|
|
448
|
+
|
|
449
|
+
const changes = diffLines(current, content);
|
|
450
|
+
if (action === "UPDATE" && !changes.length) {
|
|
451
|
+
throw new Error("Nothing to do: the new content is identical to the current file.");
|
|
452
|
+
}
|
|
453
|
+
|
|
454
|
+
const warnings = [];
|
|
455
|
+
if (publish) warnings.push("publish is on — the change goes live as soon as it is applied.");
|
|
456
|
+
if (/eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\./.test(content)) {
|
|
457
|
+
warnings.push("the content contains what looks like an API token (JWT).");
|
|
458
|
+
}
|
|
459
|
+
const hints = [];
|
|
460
|
+
if (action === "UPDATE" && !publish && base.live) {
|
|
461
|
+
hints.push("The file has a live version: it keeps serving the old content until this change is published.");
|
|
462
|
+
}
|
|
463
|
+
if (target.kind === "custom-field" && action === "CREATE") {
|
|
464
|
+
hints.push(`To use it, set the Custom-Field value to: #dotParse("//${site}${target.full}")`);
|
|
465
|
+
}
|
|
466
|
+
if (target.kind === "api" && action === "CREATE") {
|
|
467
|
+
const endpoint = target.folder.slice(target.root.length).replace(/\/$/, "");
|
|
468
|
+
hints.push(
|
|
469
|
+
`Once published it answers ${target.fileName.replace(/\.vtl$/i, "").toUpperCase()} ${BASE_URL}/api/vtl/${endpoint}`,
|
|
470
|
+
);
|
|
471
|
+
}
|
|
472
|
+
|
|
473
|
+
const plan = savePlan({
|
|
474
|
+
action,
|
|
475
|
+
kind: target.kind,
|
|
476
|
+
instance: BASE_URL,
|
|
477
|
+
site,
|
|
478
|
+
path: target.full,
|
|
479
|
+
folder: target.folder,
|
|
480
|
+
fileName: target.fileName,
|
|
481
|
+
languageId,
|
|
482
|
+
publish,
|
|
483
|
+
content,
|
|
484
|
+
base,
|
|
485
|
+
changes,
|
|
486
|
+
warnings,
|
|
487
|
+
hints,
|
|
488
|
+
});
|
|
489
|
+
planFingerprints.set(plan.id, fingerprint(plan));
|
|
490
|
+
|
|
491
|
+
return {
|
|
492
|
+
content: [
|
|
493
|
+
{
|
|
494
|
+
type: "text",
|
|
495
|
+
text:
|
|
496
|
+
renderPlan(plan) +
|
|
497
|
+
`\n\nplanId: ${plan.id}\nNothing has been written. Show this plan to the user; to carry it out call ` +
|
|
498
|
+
"apply_vtl_change with this planId.",
|
|
499
|
+
},
|
|
500
|
+
],
|
|
501
|
+
};
|
|
502
|
+
} catch (err) {
|
|
503
|
+
return fail(err);
|
|
504
|
+
}
|
|
505
|
+
},
|
|
506
|
+
);
|
|
507
|
+
|
|
508
|
+
server.registerTool(
|
|
509
|
+
"apply_vtl_change",
|
|
510
|
+
{
|
|
511
|
+
title: "Apply a planned VTL file change to dotCMS",
|
|
512
|
+
description:
|
|
513
|
+
"Step 2 of 2. WRITES to dotCMS: creates or updates the VTL file exactly as described by a plan from " +
|
|
514
|
+
"plan_vtl_change. Takes only the planId, so nothing but the planned content can be written. " +
|
|
515
|
+
"Only call it after the user has seen the plan and agreed to it. When the client supports it, the server " +
|
|
516
|
+
"also asks the user to confirm. A plan works once, only in the server session that made it, and expires after 30 minutes; " +
|
|
517
|
+
"it is rejected if the file changed in dotCMS after the plan was made.",
|
|
518
|
+
inputSchema: {
|
|
519
|
+
planId: z.string().min(1).describe("planId returned by plan_vtl_change"),
|
|
520
|
+
},
|
|
521
|
+
annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
|
|
522
|
+
},
|
|
523
|
+
async ({ planId }) => {
|
|
524
|
+
try {
|
|
525
|
+
const plan = loadPlan(planId);
|
|
526
|
+
if (planFingerprints.get(plan.id) !== fingerprint(plan)) {
|
|
527
|
+
throw new Error(
|
|
528
|
+
`Plan ${plan.id} was not made by this server session, or its file was changed afterwards. Make a new plan with plan_vtl_change.`,
|
|
529
|
+
);
|
|
530
|
+
}
|
|
531
|
+
if (plan.instance !== BASE_URL) {
|
|
532
|
+
throw new Error(`Plan ${plan.id} was made for ${plan.instance}, but this server is connected to ${BASE_URL}.`);
|
|
533
|
+
}
|
|
534
|
+
// Never trust the stored plan for where it may write: check it again.
|
|
535
|
+
const target = parseWritePath(plan.path);
|
|
536
|
+
if (target.folder !== plan.folder || target.fileName !== plan.fileName) {
|
|
537
|
+
throw new Error(`Plan ${plan.id} is inconsistent. Make a new plan with plan_vtl_change.`);
|
|
538
|
+
}
|
|
539
|
+
assertSite(plan.site);
|
|
540
|
+
|
|
541
|
+
if ((await confirmWithUser(plan)) === "declined") {
|
|
542
|
+
throw new Error(`The user declined plan ${plan.id}. Nothing was written.`);
|
|
543
|
+
}
|
|
544
|
+
|
|
545
|
+
// The plan must still describe reality.
|
|
546
|
+
const files = (await findFiles({ path: plan.path, site: plan.site })).filter(
|
|
547
|
+
(f) => plan.action === "CREATE" || f.languageId === plan.languageId,
|
|
548
|
+
);
|
|
549
|
+
if (plan.action === "CREATE" && files.length) {
|
|
550
|
+
throw new Error(`${plan.path} was created on ${plan.site} after the plan was made. Make a new plan.`);
|
|
551
|
+
}
|
|
552
|
+
if (plan.action === "UPDATE" && files[0]?.inode !== plan.base.inode) {
|
|
553
|
+
throw new Error(`${plan.path} changed in dotCMS after the plan was made. Make a new plan.`);
|
|
554
|
+
}
|
|
555
|
+
|
|
556
|
+
const folderError = plan.action === "CREATE" ? await ensureFolder(plan.site, plan.folder) : null;
|
|
557
|
+
let saved;
|
|
558
|
+
try {
|
|
559
|
+
saved = await saveFile({
|
|
560
|
+
site: plan.site,
|
|
561
|
+
folder: plan.folder,
|
|
562
|
+
fileName: plan.fileName,
|
|
563
|
+
content: plan.content,
|
|
564
|
+
identifier: plan.base?.identifier,
|
|
565
|
+
languageId: plan.languageId,
|
|
566
|
+
publish: plan.publish,
|
|
567
|
+
});
|
|
568
|
+
} catch (err) {
|
|
569
|
+
if (folderError) err.message += ` (creating folder ${plan.folder} also failed: ${folderError})`;
|
|
570
|
+
throw err;
|
|
571
|
+
}
|
|
572
|
+
deletePlan(plan.id);
|
|
573
|
+
planFingerprints.delete(plan.id);
|
|
574
|
+
|
|
575
|
+
return ok({
|
|
576
|
+
result: `${plan.action === "CREATE" ? "Created" : "Updated"} ${plan.path} on ${plan.site}`,
|
|
577
|
+
planId: plan.id,
|
|
578
|
+
workflowAction: saved.action,
|
|
579
|
+
published: !!plan.publish,
|
|
580
|
+
note: plan.publish
|
|
581
|
+
? "The file is live."
|
|
582
|
+
: "Saved as a working (unpublished) version. The live file is unchanged until it is published.",
|
|
583
|
+
identifier: saved.entity.identifier,
|
|
584
|
+
inode: saved.entity.inode,
|
|
585
|
+
languageId: saved.entity.languageId,
|
|
586
|
+
});
|
|
587
|
+
} catch (err) {
|
|
588
|
+
return fail(err);
|
|
589
|
+
}
|
|
590
|
+
},
|
|
591
|
+
);
|
|
592
|
+
}
|
|
593
|
+
|
|
594
|
+
await server.connect(new StdioServerTransport());
|
|
595
|
+
console.error(
|
|
596
|
+
`dotcms-mcp running (${BASE_URL}${TOKEN ? "" : ", no DOTCMS_TOKEN set"}, ` +
|
|
597
|
+
`${ALLOW_WRITE ? `writes enabled under ${WRITE_ROOTS.join(", ")}` : "read-only"})`,
|
|
598
|
+
);
|
|
599
|
+
if (INSECURE_TRANSPORT) {
|
|
600
|
+
console.error("WARNING: DOTCMS_URL is plain http on a remote host — the API token is sent unencrypted. Use https.");
|
|
601
|
+
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,41 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "dotcms-custom-mcp",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.2.0",
|
|
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
|
+
"keywords": [
|
|
6
|
+
"mcp",
|
|
7
|
+
"model-context-protocol",
|
|
8
|
+
"mcp-server",
|
|
9
|
+
"dotcms",
|
|
10
|
+
"cms",
|
|
11
|
+
"velocity",
|
|
12
|
+
"vtl",
|
|
13
|
+
"content-types",
|
|
14
|
+
"copilot",
|
|
15
|
+
"claude",
|
|
16
|
+
"ai"
|
|
17
|
+
],
|
|
18
|
+
"homepage": "https://github.com/DenysDatsiv/dotcms-mcp#readme",
|
|
19
|
+
"repository": {
|
|
20
|
+
"type": "git",
|
|
21
|
+
"url": "git+https://github.com/DenysDatsiv/dotcms-mcp.git"
|
|
22
|
+
},
|
|
23
|
+
"bugs": {
|
|
24
|
+
"url": "https://github.com/DenysDatsiv/dotcms-mcp/issues"
|
|
25
|
+
},
|
|
26
|
+
"author": "Denys Datsiv",
|
|
27
|
+
"type": "module",
|
|
28
|
+
"main": "index.js",
|
|
29
|
+
"bin": {
|
|
30
|
+
"dotcms-custom-mcp": "index.js",
|
|
31
|
+
"dotcms-custom-mcp-confirm-write": "hooks/confirm-write.mjs"
|
|
32
|
+
},
|
|
33
|
+
"files": ["index.js", "dotcms.js", "plans.js", "relations.js", "hooks/"],
|
|
34
|
+
"scripts": { "start": "node index.js" },
|
|
35
|
+
"engines": { "node": ">=20.18.1" },
|
|
36
|
+
"dependencies": {
|
|
37
|
+
"@modelcontextprotocol/sdk": "^1.12.0",
|
|
38
|
+
"undici": "^7.30.2",
|
|
39
|
+
"zod": "^4.6.6"
|
|
40
|
+
}
|
|
41
|
+
}
|