rpg0-dotcms-mcp 1.1.1 → 1.1.2

package/README.md

@@ -30,6 +30,8 @@ All configuration is through environment variables.
 | `DOTCMS_TOKEN` | *(none)* | API token, sent as a `Bearer` token |
 | `DOTCMS_ALLOW_WRITE` | `false` | Set to `true` to expose the write tools |
 | `DOTCMS_WRITE_ROOTS` | `/application/apivtl/,/application/vtl/custom-fields/` | Comma-separated folders the write tools are limited to |
+| `DOTCMS_READ_EXTENSIONS` | `vtl` | Comma-separated file extensions the read tools may return |
+| `DOTCMS_CONFIRM` | *(on)* | Set to `off` to skip the server's own confirmation prompt before a write |
 | `DOTCMS_PLANS_DIR` | `~/.dotcms-mcp/plans` | Where pending change plans are stored |
 
 ## Client setup
@@ -98,6 +100,8 @@ Add the server to the client's MCP configuration:
 | `list_vtl_files` | Finds VTL files by folder and/or file name, with paging |
 | `read_vtl_file` | Returns the source of a VTL file by path or identifier, optionally for a specific site or language |
 
+The two file tools only return files whose extension is listed in `DOTCMS_READ_EXTENSIONS`.
+
 ### Only with `DOTCMS_ALLOW_WRITE=true`
 
 | Tool | What it does |
@@ -114,21 +118,23 @@ Add the server to the client's MCP configuration:
 Safeguards:
 
 - Paths outside `DOTCMS_WRITE_ROOTS` are rejected.
-- A plan is valid for 30 minutes and can be used once.
+- The site must be a plain host name.
+- A plan is valid for 30 minutes, can be used once, and only in the server session that created it. A plan file that was edited on disk is refused.
 - By default a change is saved as a working version; the live file is only replaced when publishing is explicitly requested.
+- Before writing, the server asks you to confirm through your client when the client supports MCP elicitation (VS Code does). Declining writes nothing. Set `DOTCMS_CONFIRM=off` to turn this prompt off.
 
-Your AI client's own tool-approval prompt is the final check before `apply_vtl_change` runs, so keep approval enabled for that tool.
+If your client does not support elicitation, its own tool-approval prompt is the only check before `apply_vtl_change` runs, so keep approval enabled for that tool and do not auto-approve it.
 
 ### Optional: confirmation hook for Claude Code
 
-The package ships a `PreToolUse` hook that shows the full plan and asks for approval every time `apply_vtl_change` is called, and denies calls without a valid plan. It expects the server to be registered under the name `dotcms`. Add it to your Claude Code `settings.json`:
+The package ships a `PreToolUse` hook that shows the full plan and asks for approval every time `apply_vtl_change` is called, and denies calls without a valid plan. If you use it, you can set `DOTCMS_CONFIRM=off` to avoid being asked twice. Add it to your Claude Code `settings.json`:
 
 ```json
 {
   "hooks": {
     "PreToolUse": [
       {
-        "matcher": "mcp__dotcms__apply_vtl_change",
+        "matcher": "mcp__.*__apply_vtl_change",
         "hooks": [
           {
             "type": "command",
@@ -151,5 +157,6 @@ The package ships a `PreToolUse` hook that shows the full plan and asks for appr
 ## Security notes
 
 - Give the token only the permissions the assistant needs; use a read-only user if you don't need writes.
+- Use `https` for any dotCMS that isn't on your own machine; the server warns at startup when the token would travel over plain `http`.
 - Never commit the token. Prefer your client's secret prompt or an environment variable.
 - The server sends requests only to `DOTCMS_URL`.

package/dotcms.js

@@ -6,6 +6,9 @@
 //   DOTCMS_ALLOW_WRITE  "true" to expose the create/update tools (default: read-only)
 //   DOTCMS_WRITE_ROOTS  comma-separated folders the write tools are limited to
 //                       (default: /application/apivtl/,/application/vtl/custom-fields/)
+//   DOTCMS_READ_EXTENSIONS  comma-separated file extensions the read tools may return (default: vtl)
+//   DOTCMS_CONFIRM      "off" to skip the server's own confirmation prompt before a write
+//                       (default: ask through the client when it supports MCP elicitation)
 
 export const BASE_URL = (process.env.DOTCMS_URL || "http://localhost:8080").replace(/\/+$/, "");
 export const TOKEN = process.env.DOTCMS_TOKEN || "";
@@ -18,6 +21,42 @@ export const WRITE_ROOTS = (
   .filter(Boolean)
   .map((root) => `/${root}/`);
 
+export const READ_EXTENSIONS = (process.env.DOTCMS_READ_EXTENSIONS || "vtl")
+  .split(",")
+  .map((ext) => ext.trim().replace(/^\./, "").toLowerCase())
+  .filter((ext) => /^[a-z0-9]+$/.test(ext));
+export const CONFIRM = !/^(off|false|0|no)$/i.test(process.env.DOTCMS_CONFIRM || "");
+
+/** True when the token would travel unencrypted to another machine. */
+export const INSECURE_TRANSPORT = (() => {
+  try {
+    const { protocol, hostname } = new URL(BASE_URL);
+    const local = hostname === "localhost" || hostname === "127.0.0.1" || hostname === "[::1]" || hostname.endsWith(".localhost");
+    return !!TOKEN && protocol === "http:" && !local;
+  } catch {
+    return false;
+  }
+})();
+
+/** A site is a host name; anything else could change where `site:folder` points. */
+export function assertSite(site) {
+  if (!/^[A-Za-z0-9]([A-Za-z0-9._-]{0,251}[A-Za-z0-9])?$/.test(String(site ?? ""))) {
+    throw new Error(`Invalid site '${site}': pass the site host name, e.g. 'demo.dotcms.com'.`);
+  }
+  return site;
+}
+
+/** Throws unless the file name ends in one of DOTCMS_READ_EXTENSIONS. */
+export function assertReadable(fileName) {
+  const ext = String(fileName ?? "").split(".").pop().toLowerCase();
+  if (!String(fileName ?? "").includes(".") || !READ_EXTENSIONS.includes(ext)) {
+    throw new Error(
+      `'${fileName}' is not a ${READ_EXTENSIONS.map((e) => `.${e}`).join(" / ")} file. ` +
+        "This server only reads the extensions listed in DOTCMS_READ_EXTENSIONS.",
+    );
+  }
+}
+
 const authHeaders = (extra = {}) => (TOKEN ? { ...extra, Authorization: `Bearer ${TOKEN}` } : extra);
 
 async function send(path, init = {}) {
@@ -174,6 +213,7 @@ export function parseWritePath(path) {
  * through the dotCMS workflow API. Not published unless `publish` is true.
  */
 export async function saveFile({ site, folder, fileName, content, identifier, languageId, publish }) {
+  assertSite(site);
   const contentlet = {
     contentType: "FileAsset",
     title: fileName,
@@ -199,6 +239,7 @@ export async function saveFile({ site, folder, fileName, content, identifier, la
 /** Make sure a folder exists. Returns an error message instead of throwing. */
 export async function ensureFolder(site, folder) {
   try {
+    assertSite(site);
     await api(`/api/v1/folder/createfolders/${encodeURIComponent(site)}`, {
       method: "POST",
       body: [folder],

package/hooks/confirm-write.mjs

@@ -28,7 +28,8 @@ try {
 } catch {
   process.exit(0); // not a hook payload: stay out of the way
 }
-if (input.tool_name !== "mcp__dotcms__apply_vtl_change") process.exit(0);
+// Whatever name the server was registered under.
+if (!/^mcp__.+__apply_vtl_change$/.test(String(input.tool_name ?? ""))) process.exit(0);
 
 let plan;
 try {

package/index.js

@@ -10,13 +10,19 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import crypto from "node:crypto";
 import { z } from "zod";
 import {
   ALLOW_WRITE,
   BASE_URL,
+  CONFIRM,
+  INSECURE_TRANSPORT,
+  READ_EXTENSIONS,
   TOKEN,
   WRITE_ROOTS,
   api,
+  assertReadable,
+  assertSite,
   downloadFile,
   ensureFolder,
   escapeLucene,
@@ -84,7 +90,7 @@ const mapFile = (f) => ({
 const ok = (data) => ({ content: [{ type: "text", text: JSON.stringify(data, null, 2) }] });
 const fail = (err) => ({ isError: true, content: [{ type: "text", text: err.message }] });
 
-const server = new McpServer({ name: "dotcms", version: "1.1.0" });
+const server = new McpServer({ name: "dotcms", version: "1.1.2" });
 
 // ---------------------------------------------------------------------------
 // Read-only tools
@@ -189,7 +195,7 @@ server.registerTool(
         .optional()
         .describe("Only files whose path contains this folder, e.g. '/application/vtl' or 'containers/banner'"),
       name: z.string().optional().describe("Only files whose file name contains this text, e.g. 'banner'"),
-      extension: z.string().default("vtl").describe("File extension to look for (default 'vtl')"),
+      extension: z.string().default("vtl").describe(`File extension to look for (default 'vtl'; allowed: ${READ_EXTENSIONS.join(", ")})`),
       page: z.number().int().min(1).default(1).describe("Page number"),
       perPage: z.number().int().min(1).max(100).default(50).describe("Items per page"),
     },
@@ -197,6 +203,7 @@ server.registerTool(
   },
   async ({ folder, name, extension, page, perPage }) => {
     try {
+      assertReadable(`x.${extension.replace(/^\./, "")}`);
       const ext = escapeLucene(extension.replace(/^\./, "").toLowerCase());
       const clauses = [`+path:*.${ext}`];
       if (folder) {
@@ -240,6 +247,7 @@ server.registerTool(
       if (!path && !identifier) throw new Error("Pass either 'path' or 'identifier'.");
       const files = await findFiles({ path, identifier, site });
       const { file, languages } = pickVersion(files, { what: identifier || path, site, languageId });
+      assertReadable(file.fileName || file.name || file.path);
 
       const content = await downloadFile(file);
       const truncated = content.length > MAX_FILE_CHARS;
@@ -263,6 +271,37 @@ server.registerTool(
 if (ALLOW_WRITE) {
   const roots = WRITE_ROOTS.join(" and ");
 
+  // Fingerprints of the plans this process created. apply_vtl_change refuses a plan whose
+  // file on disk no longer matches, so editing a plan file cannot change what gets written.
+  const planFingerprints = new Map();
+  const fingerprint = (plan) => crypto.createHash("sha256").update(JSON.stringify(plan)).digest("hex");
+
+  /**
+   * Ask the user through the client (MCP elicitation) when it can. Returns "confirmed",
+   * "declined", or "unsupported" when the client cannot ask — its own tool approval is then
+   * the only check.
+   */
+  async function confirmWithUser(plan) {
+    if (!CONFIRM || !server.server.getClientCapabilities()?.elicitation) return "unsupported";
+    let answer;
+    try {
+      answer = await server.server.elicitInput({
+        message: `Apply this change to dotCMS?\n\n${renderPlan(plan)}`,
+        requestedSchema: {
+          type: "object",
+          properties: {
+            apply: { type: "boolean", title: "Apply this change", description: `${plan.action} ${plan.path} on ${plan.site}` },
+          },
+          required: ["apply"],
+        },
+      }, { timeout: 10 * 60 * 1000 }); // give the user time to read the diff
+    } catch (err) {
+      if (/does not support/i.test(err.message)) return "unsupported";
+      throw err;
+    }
+    return answer.action === "accept" && answer.content?.apply === true ? "confirmed" : "declined";
+  }
+
   server.registerTool(
     "plan_vtl_change",
     {
@@ -296,6 +335,7 @@ if (ALLOW_WRITE) {
     async ({ path, site, content, languageId, publish }) => {
       try {
         const target = parseWritePath(path);
+        if (site !== undefined) assertSite(site);
         const files = await findFiles({ path: target.full, site });
 
         let action = "CREATE";
@@ -352,6 +392,7 @@ if (ALLOW_WRITE) {
           warnings,
           hints,
         });
+        planFingerprints.set(plan.id, fingerprint(plan));
 
         return {
           content: [
@@ -360,7 +401,7 @@ if (ALLOW_WRITE) {
               text:
                 renderPlan(plan) +
                 `\n\nplanId: ${plan.id}\nNothing has been written. Show this plan to the user; to carry it out call ` +
-                "apply_vtl_change with this planId — the user will be asked to confirm.",
+                "apply_vtl_change with this planId.",
             },
           ],
         };
@@ -377,7 +418,8 @@ if (ALLOW_WRITE) {
       description:
         "Step 2 of 2. WRITES to dotCMS: creates or updates the VTL file exactly as described by a plan from " +
         "plan_vtl_change. Takes only the planId, so nothing but the planned content can be written. " +
-        "The user is shown the plan and asked to confirm every call. A plan works once and expires after 30 minutes; " +
+        "Only call it after the user has seen the plan and agreed to it. When the client supports it, the server " +
+        "also asks the user to confirm. A plan works once, only in the server session that made it, and expires after 30 minutes; " +
         "it is rejected if the file changed in dotCMS after the plan was made.",
       inputSchema: {
         planId: z.string().min(1).describe("planId returned by plan_vtl_change"),
@@ -387,9 +429,24 @@ if (ALLOW_WRITE) {
     async ({ planId }) => {
       try {
         const plan = loadPlan(planId);
+        if (planFingerprints.get(plan.id) !== fingerprint(plan)) {
+          throw new Error(
+            `Plan ${plan.id} was not made by this server session, or its file was changed afterwards. Make a new plan with plan_vtl_change.`,
+          );
+        }
         if (plan.instance !== BASE_URL) {
           throw new Error(`Plan ${plan.id} was made for ${plan.instance}, but this server is connected to ${BASE_URL}.`);
         }
+        // Never trust the stored plan for where it may write: check it again.
+        const target = parseWritePath(plan.path);
+        if (target.folder !== plan.folder || target.fileName !== plan.fileName) {
+          throw new Error(`Plan ${plan.id} is inconsistent. Make a new plan with plan_vtl_change.`);
+        }
+        assertSite(plan.site);
+
+        if ((await confirmWithUser(plan)) === "declined") {
+          throw new Error(`The user declined plan ${plan.id}. Nothing was written.`);
+        }
 
         // The plan must still describe reality.
         const files = (await findFiles({ path: plan.path, site: plan.site })).filter(
@@ -419,6 +476,7 @@ if (ALLOW_WRITE) {
           throw err;
         }
         deletePlan(plan.id);
+        planFingerprints.delete(plan.id);
 
         return ok({
           result: `${plan.action === "CREATE" ? "Created" : "Updated"} ${plan.path} on ${plan.site}`,
@@ -444,3 +502,6 @@ console.error(
   `dotcms-mcp running (${BASE_URL}${TOKEN ? "" : ", no DOTCMS_TOKEN set"}, ` +
     `${ALLOW_WRITE ? `writes enabled under ${WRITE_ROOTS.join(", ")}` : "read-only"})`,
 );
+if (INSECURE_TRANSPORT) {
+  console.error("WARNING: DOTCMS_URL is plain http on a remote host — the API token is sent unencrypted. Use https.");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rpg0-dotcms-mcp",
-  "version": "1.1.1",
+  "version": "1.1.2",
   "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",
   "keywords": [
     "mcp",
@@ -35,6 +35,6 @@
   "engines": { "node": ">=18" },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.23.8"
+    "zod": "^4.6.6"
   }
 }