rpg0-dotcms-mcp 1.1.0 → 1.1.2

package/README.md

@@ -0,0 +1,162 @@
+# rpg0-dotcms-mcp
+
+A [Model Context Protocol](https://modelcontextprotocol.io) server for [dotCMS](https://www.dotcms.com). It lets an AI assistant (GitHub Copilot, Claude Code, Claude Desktop, Cursor, …) inspect content types and their fields, and read — and optionally write — Velocity (VTL) files in a dotCMS instance.
+
+- **Read-only by default.** Write tools are only exposed when you opt in.
+- **Writes are plan-first.** A change is planned and shown as a diff before anything is saved, and is limited to folders you allow.
+- **No install step.** Runs over stdio through `npx`.
+
+## Requirements
+
+- Node.js 18 or newer
+- A dotCMS instance reachable from the machine that runs your AI client
+- A dotCMS API token (dotCMS admin → your user → *API Access Tokens*)
+
+## Quick start
+
+```bash
+DOTCMS_URL=https://your-dotcms.example.com DOTCMS_TOKEN=your-token npx -y rpg0-dotcms-mcp
+```
+
+The server speaks MCP over stdio, so you normally don't run it by hand — your AI client starts it using one of the configurations below.
+
+## Configuration
+
+All configuration is through environment variables.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `DOTCMS_URL` | `http://localhost:8080` | Base URL of the dotCMS instance |
+| `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
+
+### GitHub Copilot (VS Code)
+
+Create `.vscode/mcp.json` in your workspace, then start the server from the editor and use Copilot Chat in Agent mode. VS Code prompts for the token once and stores it securely.
+
+```json
+{
+  "inputs": [
+    {
+      "id": "dotcms-token",
+      "type": "promptString",
+      "description": "dotCMS API token",
+      "password": true
+    }
+  ],
+  "servers": {
+    "dotcms": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "rpg0-dotcms-mcp"],
+      "env": {
+        "DOTCMS_URL": "https://your-dotcms.example.com",
+        "DOTCMS_TOKEN": "${input:dotcms-token}"
+      }
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add dotcms --env DOTCMS_URL=https://your-dotcms.example.com --env DOTCMS_TOKEN=your-token -- npx -y rpg0-dotcms-mcp
+```
+
+### Claude Desktop, Cursor and other clients
+
+Add the server to the client's MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "dotcms": {
+      "command": "npx",
+      "args": ["-y", "rpg0-dotcms-mcp"],
+      "env": {
+        "DOTCMS_URL": "https://your-dotcms.example.com",
+        "DOTCMS_TOKEN": "your-token"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### Always available (read-only)
+
+| Tool | What it does |
+| --- | --- |
+| `list_content_types` | Lists content types, with optional name filter, base-type filter and paging |
+| `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 |
+| `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 |
+| --- | --- |
+| `plan_vtl_change` | Prepares a create or update of a VTL file and returns a plan: target, publish flag, line diff and warnings. Writes nothing |
+| `apply_vtl_change` | Applies a previously created plan by its `planId` |
+
+## How writing works
+
+1. The assistant calls `plan_vtl_change` with the full new file content. The server compares it with the current file and stores a plan.
+2. The plan is shown: instance, site, path, language, whether it publishes, and the changed lines.
+3. The assistant calls `apply_vtl_change` with the `planId`. Only what the plan contains can be written.
+
+Safeguards:
+
+- Paths outside `DOTCMS_WRITE_ROOTS` are rejected.
+- 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.
+
+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. 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__.*__apply_vtl_change",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx -y -p rpg0-dotcms-mcp rpg0-dotcms-mcp-confirm-write"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Troubleshooting
+
+- **`Cannot reach dotCMS at …`** — the instance isn't running or isn't reachable from this machine. Check `DOTCMS_URL`.
+- **401 / 403 responses** — the token is missing, expired, or belongs to a different instance. Tokens are per instance.
+- **Write tools are missing** — set `DOTCMS_ALLOW_WRITE=true` and restart the server.
+- **A write is rejected** — the path is outside `DOTCMS_WRITE_ROOTS`, or the plan expired; create a new plan.
+
+## 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,7 +1,29 @@
 {
   "name": "rpg0-dotcms-mcp",
-  "version": "1.1.0",
-  "description": "MCP server for inspecting dotCMS content types and their fields, and reading/writing VTL files",
+  "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",
+    "model-context-protocol",
+    "mcp-server",
+    "dotcms",
+    "cms",
+    "velocity",
+    "vtl",
+    "content-types",
+    "copilot",
+    "claude",
+    "ai"
+  ],
+  "homepage": "https://github.com/DenysDatsiv/dotcms-mcp#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/DenysDatsiv/dotcms-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/DenysDatsiv/dotcms-mcp/issues"
+  },
+  "author": "Denys Datsiv",
   "type": "module",
   "main": "index.js",
   "bin": {
@@ -13,6 +35,6 @@
   "engines": { "node": ">=18" },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.23.8"
+    "zod": "^4.6.6"
   }
 }