rpg0-dotcms-mcp 0.0.0-stage → 1.1.1

package/README.md

@@ -1,3 +1,155 @@
-# Temporary Holding Version
+# rpg0-dotcms-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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_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 |
+
+### 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.
+- A plan is valid for 30 minutes and can be used once.
+- By default a change is saved as a working version; the live file is only replaced when publishing is explicitly requested.
+
+Your AI client's own tool-approval prompt is the final check before `apply_vtl_change` runs, so keep approval enabled for that tool.
+
+### 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`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "mcp__dotcms__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.
+- 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

@@ -0,0 +1,210 @@
+// Shared dotCMS client used by the MCP server (index.js) and the confirmation hook.
+//
+// Config (env):
+//   DOTCMS_URL          base URL of the dotCMS instance
+//   DOTCMS_TOKEN        API token
+//   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/)
+
+export const BASE_URL = (process.env.DOTCMS_URL || "http://localhost:8080").replace(/\/+$/, "");
+export const TOKEN = process.env.DOTCMS_TOKEN || "";
+export const ALLOW_WRITE = /^(true|1|yes)$/i.test(process.env.DOTCMS_ALLOW_WRITE || "");
+export const WRITE_ROOTS = (
+  process.env.DOTCMS_WRITE_ROOTS || "/application/apivtl/,/application/vtl/custom-fields/"
+)
+  .split(",")
+  .map((root) => root.trim().replace(/^\/+|\/+$/g, ""))
+  .filter(Boolean)
+  .map((root) => `/${root}/`);
+
+const authHeaders = (extra = {}) => (TOKEN ? { ...extra, Authorization: `Bearer ${TOKEN}` } : extra);
+
+async function send(path, init = {}) {
+  try {
+    return await fetch(BASE_URL + path, { ...init, signal: AbortSignal.timeout(30_000) });
+  } catch (err) {
+    throw new Error(`Cannot reach dotCMS at ${BASE_URL}: ${err.message}`);
+  }
+}
+
+/** JSON request against the dotCMS REST API. `body` may be an object (sent as JSON) or FormData. */
+export async function api(path, { method = "GET", params = {}, body } = {}) {
+  const query = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== "") query.set(key, String(value));
+  }
+  const url = path + (query.size ? `?${query}` : "");
+
+  const isForm = body instanceof FormData;
+  const headers = authHeaders({ Accept: "application/json" });
+  if (body && !isForm) headers["Content-Type"] = "application/json";
+
+  const res = await send(url, {
+    method,
+    headers,
+    body: body === undefined ? undefined : isForm ? body : JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    const hint =
+      res.status === 401 || res.status === 403
+        ? " Check DOTCMS_TOKEN and the token user's permissions."
+        : res.status === 404
+          ? " Check the name/id and DOTCMS_URL."
+          : "";
+    throw new Error(`dotCMS responded ${res.status} ${res.statusText}.${hint} ${text.slice(0, 400)}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`dotCMS returned a non-JSON response from ${path}`);
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Files
+// ---------------------------------------------------------------------------
+
+// Lucene special characters, except "/" which dotCMS accepts unescaped inside wildcards.
+export const escapeLucene = (s) => s.replace(/[+\-!(){}[\]^"~*?:\\&|]/g, "\\$&");
+
+export async function searchFiles(clauses, { limit = 50, offset = 0 } = {}) {
+  const data = await api("/api/content/_search", {
+    method: "POST",
+    body: { query: ["+baseType:4", ...clauses].join(" "), sort: "path asc", limit, offset },
+  });
+  const entity = data.entity || {};
+  return { total: entity.resultsSize ?? 0, files: entity.jsonObjectView?.contentlets || [] };
+}
+
+export const normalizePath = (path) => "/" + String(path).trim().replace(/^\/+/, "");
+
+/**
+ * All versions (one per site/language) of the file at an exact path, or with an identifier.
+ */
+export async function findFiles({ path, identifier, site }) {
+  let files;
+  if (identifier) {
+    ({ files } = await searchFiles([`+identifier:${escapeLucene(identifier)}`], { limit: 20 }));
+  } else {
+    const wanted = normalizePath(path).toLowerCase();
+    ({ files } = await searchFiles([`+path:*${escapeLucene(wanted)}`], { limit: 50 }));
+    files = files.filter((f) => f.path?.toLowerCase() === wanted);
+  }
+  if (site) files = files.filter((f) => f.hostName?.toLowerCase() === site.toLowerCase());
+  return files;
+}
+
+/** Pick one language version out of findFiles() results; throws a helpful error otherwise. */
+export function pickVersion(files, { what, site, languageId }) {
+  if (!files.length) throw new Error(`File not found: ${what}${site ? ` on site ${site}` : ""}.`);
+  const sites = [...new Set(files.map((f) => f.hostName))];
+  if (sites.length > 1) {
+    throw new Error(`This path exists on several sites (${sites.join(", ")}). Pass 'site'.`);
+  }
+  const languages = [...new Set(files.map((f) => f.languageId))].sort((a, b) => a - b);
+  const file = files.find((f) => f.languageId === (languageId ?? languages[0]));
+  if (!file) {
+    throw new Error(
+      `No version of this file in language ${languageId}. Available language ids: ${languages.join(", ")}.`,
+    );
+  }
+  return { file, languages };
+}
+
+export async function downloadFile(file) {
+  const name = encodeURIComponent(file.fileName || file.name || "file.vtl");
+  // Inode first: it pins the exact language version. The identifier URL
+  // would silently return the default-language version instead.
+  const candidates = [
+    `/dA/${file.inode}/fileAsset/${name}`,
+    `/contentAsset/raw-data/${file.inode}/fileAsset`,
+    `/dA/${file.identifier}/fileAsset/${name}?language_id=${file.languageId ?? ""}`,
+  ];
+  const tried = [];
+  for (const path of candidates) {
+    const res = await send(path, { headers: authHeaders({ Accept: "text/plain, */*" }) });
+    const type = res.headers.get("content-type") || "";
+    // dotCMS answers with its HTML 404 page when the file may not be served.
+    if (res.ok && !(type.includes("text/html") && !/\.html?$/i.test(name))) {
+      return await res.text();
+    }
+    tried.push(`${path} -> ${res.status}`);
+    await res.body?.cancel();
+  }
+  throw new Error(
+    `dotCMS refused to serve the file contents (${tried.join("; ")}). ` +
+      (TOKEN
+        ? "The token user probably has no read permission on this file."
+        : "VTL files are not served to anonymous users: set DOTCMS_TOKEN."),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Writing (API VTL files only)
+// ---------------------------------------------------------------------------
+
+/** Validate a path for the write tools and split it into folder + file name. */
+export function parseWritePath(path) {
+  const full = normalizePath(path);
+  if (!/^[A-Za-z0-9._\-/]+$/.test(full) || full.includes("..") || full.includes("//")) {
+    throw new Error(`Invalid path '${path}': use only letters, digits, '.', '_', '-' and '/'.`);
+  }
+  const root = WRITE_ROOTS.find((r) => full.toLowerCase().startsWith(r.toLowerCase()));
+  if (!root) {
+    throw new Error(`Writing is limited to ${WRITE_ROOTS.join(" and ")} — '${full}' is outside of them.`);
+  }
+  if (!full.toLowerCase().endsWith(".vtl")) {
+    throw new Error(`Only .vtl files can be written, got '${full}'.`);
+  }
+  const cut = full.lastIndexOf("/");
+  const folder = full.slice(0, cut + 1);
+  const fileName = full.slice(cut + 1);
+  if (!fileName.replace(/\.vtl$/i, "")) throw new Error(`Missing file name in '${full}'.`);
+  if (folder.toLowerCase() === root.toLowerCase()) {
+    throw new Error(`Put the file in its own folder, e.g. ${root}my-name/${fileName}.`);
+  }
+  const kind = /\/apivtl\//i.test(root) ? "api" : /\/custom-fields\//i.test(root) ? "custom-field" : "vtl";
+  return { full, folder, fileName, root, kind };
+}
+
+/**
+ * Create a new file asset, or a new version of an existing one (when `identifier` is given),
+ * through the dotCMS workflow API. Not published unless `publish` is true.
+ */
+export async function saveFile({ site, folder, fileName, content, identifier, languageId, publish }) {
+  const contentlet = {
+    contentType: "FileAsset",
+    title: fileName,
+    fileName,
+    hostFolder: `${site}:${folder}`,
+  };
+  if (identifier) contentlet.identifier = identifier;
+  if (languageId) contentlet.languageId = languageId;
+
+  const form = new FormData();
+  form.append("json", JSON.stringify({ contentlet }));
+  form.append("file", new Blob([content], { type: "text/plain" }), fileName);
+
+  const action = publish ? "PUBLISH" : identifier ? "EDIT" : "NEW";
+  const data = await api(`/api/v1/workflow/actions/default/fire/${action}`, {
+    method: "PUT",
+    params: { indexPolicy: "WAIT_FOR" },
+    body: form,
+  });
+  return { action, entity: data.entity || {} };
+}
+
+/** Make sure a folder exists. Returns an error message instead of throwing. */
+export async function ensureFolder(site, folder) {
+  try {
+    await api(`/api/v1/folder/createfolders/${encodeURIComponent(site)}`, {
+      method: "POST",
+      body: [folder],
+    });
+    return null;
+  } catch (err) {
+    return err.message;
+  }
+}

package/hooks/confirm-write.mjs

@@ -0,0 +1,40 @@
+#!/usr/bin/env node
+// Claude Code PreToolUse hook: the human check of the plan -> human check -> write flow.
+//
+// apply_vtl_change is the only dotcms MCP tool that writes. This hook never lets it through
+// on its own: it loads the plan the call refers to and answers "ask", so Claude Code shows
+// the plan (target, publish flag, diff, warnings) and the write only happens if the user
+// approves it. A call without a valid, unexpired plan is denied. Other tools are left alone.
+
+import fs from "node:fs";
+import { loadPlan, renderPlan } from "../plans.js";
+
+const decide = (permissionDecision, reason) => {
+  process.stdout.write(
+    JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision,
+        permissionDecisionReason: reason,
+      },
+    }),
+  );
+  process.exit(0);
+};
+
+let input;
+try {
+  input = JSON.parse(fs.readFileSync(0, "utf8"));
+} 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);
+
+let plan;
+try {
+  plan = loadPlan(input.tool_input?.planId);
+} catch (err) {
+  decide("deny", `dotCMS write blocked: ${err.message}`);
+}
+
+decide("ask", `Approve this dotCMS change?\n\n${renderPlan(plan)}`);

package/index.js

@@ -0,0 +1,446 @@
+#!/usr/bin/env node
+// Local MCP server for dotCMS.
+//
+// Read-only tools (always available):
+//   list_content_types, get_content_type_fields, list_vtl_files, read_vtl_file
+// Write tools (only when DOTCMS_ALLOW_WRITE=true, limited to DOTCMS_WRITE_ROOTS):
+//   plan_vtl_change (plans only, writes nothing) -> apply_vtl_change (writes, human-confirmed)
+//
+// Config: see dotcms.js.
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import {
+  ALLOW_WRITE,
+  BASE_URL,
+  TOKEN,
+  WRITE_ROOTS,
+  api,
+  downloadFile,
+  ensureFolder,
+  escapeLucene,
+  findFiles,
+  parseWritePath,
+  pickVersion,
+  saveFile,
+  searchFiles,
+} from "./dotcms.js";
+import { deletePlan, diffLines, loadPlan, renderPlan, savePlan } from "./plans.js";
+
+const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true };
+const MAX_FILE_CHARS = 200_000;
+
+// Field classes that only describe the edit-form layout, not real data.
+const LAYOUT_FIELDS = new Set([
+  "RowField",
+  "ColumnField",
+  "TabDividerField",
+  "LineDividerField",
+  "ColumnBreakField",
+]);
+
+const shortClass = (clazz = "") => clazz.split(".").pop().replace(/^Immutable/, "");
+
+function mapField(field) {
+  const out = {
+    name: field.name,
+    variable: field.variable,
+    type: field.fieldType || shortClass(field.clazz).replace(/Field$/, ""),
+    class: shortClass(field.clazz),
+    dataType: field.dataType,
+    required: !!field.required,
+    unique: !!field.unique,
+    indexed: !!field.indexed,
+    searchable: !!field.searchable,
+    listed: !!field.listed,
+    system: !!field.fixed,
+  };
+  if (field.hint) out.hint = field.hint;
+  if (field.defaultValue) out.defaultValue = field.defaultValue;
+  if (field.values) out.values = field.values;
+  if (field.regexCheck) out.regexCheck = field.regexCheck;
+  if (field.relationships) out.relationships = field.relationships;
+  if (field.categories) out.categories = field.categories;
+  if (field.fieldVariables?.length) {
+    out.fieldVariables = Object.fromEntries(field.fieldVariables.map((v) => [v.key, v.value]));
+  }
+  return out;
+}
+
+const mapFile = (f) => ({
+  path: f.path,
+  name: f.fileName || f.name,
+  site: f.hostName,
+  identifier: f.identifier,
+  inode: f.inode,
+  languageId: f.languageId,
+  size: f.size,
+  modDate: f.modDate,
+  live: f.live,
+  description: f.description || undefined,
+});
+
+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" });
+
+// ---------------------------------------------------------------------------
+// Read-only tools
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  "list_content_types",
+  {
+    title: "List dotCMS content types",
+    description:
+      "Read-only. List content types in dotCMS (name, variable, base type, number of content entries). " +
+      "Use it to find the variable name of a content type before reading its fields.",
+    inputSchema: {
+      filter: z.string().optional().describe("Filter by name or variable (substring)"),
+      type: z
+        .enum(["CONTENT", "WIDGET", "FORM", "FILEASSET", "HTMLPAGE", "PERSONA", "VANITY_URL", "KEY_VALUE", "DOTASSET"])
+        .optional()
+        .describe("Only content types of this base type"),
+      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"),
+    },
+    annotations: READ_ONLY,
+  },
+  async ({ filter, type, page, perPage }) => {
+    try {
+      const data = await api("/api/v1/contenttype", {
+        params: { filter, type, page, per_page: perPage, orderby: "name", direction: "ASC" },
+      });
+      const types = (data.entity || []).map((ct) => ({
+        name: ct.name,
+        variable: ct.variable,
+        id: ct.id,
+        baseType: ct.baseType,
+        description: ct.description || undefined,
+        entries: ct.nEntries,
+        system: !!ct.system,
+      }));
+      return ok({
+        page,
+        perPage,
+        total: data.pagination?.totalEntries,
+        count: types.length,
+        contentTypes: types,
+      });
+    } catch (err) {
+      return fail(err);
+    }
+  },
+);
+
+server.registerTool(
+  "get_content_type_fields",
+  {
+    title: "Get fields of a dotCMS content type",
+    description:
+      "Read-only. Return the fields of a dotCMS content type: name, variable, field type, data type, " +
+      "required/unique/indexed/searchable/listed flags, hint, default value, allowed values, " +
+      "relationships and field variables.",
+    inputSchema: {
+      contentType: z.string().min(1).describe("Content type variable name (e.g. 'Blog') or its id"),
+      includeLayout: z
+        .boolean()
+        .default(false)
+        .describe("Also include layout-only fields (rows, columns, tab dividers)"),
+    },
+    annotations: READ_ONLY,
+  },
+  async ({ contentType, includeLayout }) => {
+    try {
+      const data = await api(`/api/v1/contenttype/id/${encodeURIComponent(contentType)}`);
+      const ct = data.entity || {};
+      const fields = (ct.fields || [])
+        .filter((f) => includeLayout || !LAYOUT_FIELDS.has(shortClass(f.clazz)))
+        .map(mapField);
+      return ok({
+        name: ct.name,
+        variable: ct.variable,
+        id: ct.id,
+        baseType: ct.baseType,
+        description: ct.description || undefined,
+        urlMapPattern: ct.urlMapPattern || undefined,
+        detailPage: ct.detailPage || undefined,
+        fieldCount: fields.length,
+        fields,
+      });
+    } catch (err) {
+      return fail(err);
+    }
+  },
+);
+
+server.registerTool(
+  "list_vtl_files",
+  {
+    title: "List VTL files in dotCMS",
+    description:
+      "Read-only. Find Velocity (.vtl) files stored in dotCMS as file assets: container, template, " +
+      "theme, custom-field and scripting-API VTL files. Returns path, site, identifier, language, size and modification date.",
+    inputSchema: {
+      folder: z
+        .string()
+        .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')"),
+      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"),
+    },
+    annotations: READ_ONLY,
+  },
+  async ({ folder, name, extension, page, perPage }) => {
+    try {
+      const ext = escapeLucene(extension.replace(/^\./, "").toLowerCase());
+      const clauses = [`+path:*.${ext}`];
+      if (folder) {
+        const f = escapeLucene(folder.toLowerCase().replace(/^\/+|\/+$/g, ""));
+        clauses.push(`+path:*${f}/*`);
+      }
+      if (name) clauses.push(`+title:*${escapeLucene(name.toLowerCase())}*`);
+
+      const { total, files } = await searchFiles(clauses, {
+        limit: perPage,
+        offset: (page - 1) * perPage,
+      });
+      return ok({ page, perPage, total, count: files.length, files: files.map(mapFile) });
+    } catch (err) {
+      return fail(err);
+    }
+  },
+);
+
+server.registerTool(
+  "read_vtl_file",
+  {
+    title: "Read a VTL file from dotCMS",
+    description:
+      "Read-only. Return the source of a Velocity (.vtl) file stored in dotCMS. Pass either the full " +
+      "path (e.g. '/application/containers/banner/banner.vtl') or the file identifier from list_vtl_files.",
+    inputSchema: {
+      path: z.string().optional().describe("Full path of the file inside the site"),
+      identifier: z.string().optional().describe("File identifier (alternative to path)"),
+      site: z.string().optional().describe("Site host name, if the same path exists on several sites"),
+      languageId: z
+        .number()
+        .int()
+        .optional()
+        .describe("Language id, if the file has several language versions (default: the lowest id, usually the default language)"),
+    },
+    annotations: READ_ONLY,
+  },
+  async ({ path, identifier, site, languageId }) => {
+    try {
+      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 });
+
+      const content = await downloadFile(file);
+      const truncated = content.length > MAX_FILE_CHARS;
+      return ok({
+        ...mapFile(file),
+        availableLanguageIds: languages,
+        truncated,
+        content: truncated ? content.slice(0, MAX_FILE_CHARS) : content,
+      });
+    } catch (err) {
+      return fail(err);
+    }
+  },
+);
+
+// ---------------------------------------------------------------------------
+// Write tools — opt-in, limited to WRITE_ROOTS. Plan first, then the
+// human check (hooks/confirm-write.mjs), then the write.
+// ---------------------------------------------------------------------------
+
+if (ALLOW_WRITE) {
+  const roots = WRITE_ROOTS.join(" and ");
+
+  server.registerTool(
+    "plan_vtl_change",
+    {
+      title: "Plan a VTL file change in dotCMS",
+      description:
+        "Step 1 of 2 for every write. Does NOT change dotCMS: it validates the target, compares the new " +
+        "source with the current file and returns a plan (action, target, diff, warnings) with a planId. " +
+        `Writable locations: ${roots} — scripting-API files (e.g. /application/apivtl/my-endpoint/get.vtl, ` +
+        "file name = HTTP method) and custom fields (e.g. /application/vtl/custom-fields/my-field/code.vtl). " +
+        "Whether it is a create or an update is detected from whether the file exists. " +
+        "Show the returned plan to the user, then call apply_vtl_change with the planId.",
+      inputSchema: {
+        path: z.string().min(1).describe(`Full path of the file, inside ${roots}`),
+        site: z
+          .string()
+          .optional()
+          .describe("Site host name. Required for a new file, or when the path exists on several sites"),
+        content: z
+          .string()
+          .min(1)
+          .max(MAX_FILE_CHARS)
+          .describe("Full Velocity source of the file (the whole file, not a patch)"),
+        languageId: z.number().int().optional().describe("Language id (default: the default language)"),
+        publish: z
+          .boolean()
+          .default(false)
+          .describe("Publish immediately. Default false: save a working version only, the live file stays as it is"),
+      },
+      annotations: READ_ONLY,
+    },
+    async ({ path, site, content, languageId, publish }) => {
+      try {
+        const target = parseWritePath(path);
+        const files = await findFiles({ path: target.full, site });
+
+        let action = "CREATE";
+        let base = null;
+        let current = "";
+        if (files.length) {
+          const { file } = pickVersion(files, { what: target.full, site, languageId });
+          action = "UPDATE";
+          base = { identifier: file.identifier, inode: file.inode, live: !!file.live };
+          site = file.hostName;
+          languageId = file.languageId;
+          current = await downloadFile(file);
+        } else if (!site) {
+          throw new Error(`${target.full} does not exist yet. Pass 'site' to plan creating it.`);
+        }
+
+        const changes = diffLines(current, content);
+        if (action === "UPDATE" && !changes.length) {
+          throw new Error("Nothing to do: the new content is identical to the current file.");
+        }
+
+        const warnings = [];
+        if (publish) warnings.push("publish is on — the change goes live as soon as it is applied.");
+        if (/eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\./.test(content)) {
+          warnings.push("the content contains what looks like an API token (JWT).");
+        }
+        const hints = [];
+        if (action === "UPDATE" && !publish && base.live) {
+          hints.push("The file has a live version: it keeps serving the old content until this change is published.");
+        }
+        if (target.kind === "custom-field" && action === "CREATE") {
+          hints.push(`To use it, set the Custom-Field value to: #dotParse("//${site}${target.full}")`);
+        }
+        if (target.kind === "api" && action === "CREATE") {
+          const endpoint = target.folder.slice(target.root.length).replace(/\/$/, "");
+          hints.push(
+            `Once published it answers ${target.fileName.replace(/\.vtl$/i, "").toUpperCase()} ${BASE_URL}/api/vtl/${endpoint}`,
+          );
+        }
+
+        const plan = savePlan({
+          action,
+          kind: target.kind,
+          instance: BASE_URL,
+          site,
+          path: target.full,
+          folder: target.folder,
+          fileName: target.fileName,
+          languageId,
+          publish,
+          content,
+          base,
+          changes,
+          warnings,
+          hints,
+        });
+
+        return {
+          content: [
+            {
+              type: "text",
+              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.",
+            },
+          ],
+        };
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+
+  server.registerTool(
+    "apply_vtl_change",
+    {
+      title: "Apply a planned VTL file change to dotCMS",
+      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; " +
+        "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"),
+      },
+      annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false },
+    },
+    async ({ planId }) => {
+      try {
+        const plan = loadPlan(planId);
+        if (plan.instance !== BASE_URL) {
+          throw new Error(`Plan ${plan.id} was made for ${plan.instance}, but this server is connected to ${BASE_URL}.`);
+        }
+
+        // The plan must still describe reality.
+        const files = (await findFiles({ path: plan.path, site: plan.site })).filter(
+          (f) => plan.action === "CREATE" || f.languageId === plan.languageId,
+        );
+        if (plan.action === "CREATE" && files.length) {
+          throw new Error(`${plan.path} was created on ${plan.site} after the plan was made. Make a new plan.`);
+        }
+        if (plan.action === "UPDATE" && files[0]?.inode !== plan.base.inode) {
+          throw new Error(`${plan.path} changed in dotCMS after the plan was made. Make a new plan.`);
+        }
+
+        const folderError = plan.action === "CREATE" ? await ensureFolder(plan.site, plan.folder) : null;
+        let saved;
+        try {
+          saved = await saveFile({
+            site: plan.site,
+            folder: plan.folder,
+            fileName: plan.fileName,
+            content: plan.content,
+            identifier: plan.base?.identifier,
+            languageId: plan.languageId,
+            publish: plan.publish,
+          });
+        } catch (err) {
+          if (folderError) err.message += ` (creating folder ${plan.folder} also failed: ${folderError})`;
+          throw err;
+        }
+        deletePlan(plan.id);
+
+        return ok({
+          result: `${plan.action === "CREATE" ? "Created" : "Updated"} ${plan.path} on ${plan.site}`,
+          planId: plan.id,
+          workflowAction: saved.action,
+          published: !!plan.publish,
+          note: plan.publish
+            ? "The file is live."
+            : "Saved as a working (unpublished) version. The live file is unchanged until it is published.",
+          identifier: saved.entity.identifier,
+          inode: saved.entity.inode,
+          languageId: saved.entity.languageId,
+        });
+      } catch (err) {
+        return fail(err);
+      }
+    },
+  );
+}
+
+await server.connect(new StdioServerTransport());
+console.error(
+  `dotcms-mcp running (${BASE_URL}${TOKEN ? "" : ", no DOTCMS_TOKEN set"}, ` +
+    `${ALLOW_WRITE ? `writes enabled under ${WRITE_ROOTS.join(", ")}` : "read-only"})`,
+);

package/package.json

@@ -1,6 +1,40 @@
 {
   "name": "rpg0-dotcms-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.1",
+  "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": {
+    "rpg0-dotcms-mcp": "index.js",
+    "rpg0-dotcms-mcp-confirm-write": "hooks/confirm-write.mjs"
+  },
+  "files": ["index.js", "dotcms.js", "plans.js", "hooks/"],
+  "scripts": { "start": "node index.js" },
+  "engines": { "node": ">=18" },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  }
+}

package/plans.js

@@ -0,0 +1,111 @@
+// Change plans: the "plan first" half of the plan -> human check -> write flow.
+//
+// plan_vtl_change stores a plan here; apply_vtl_change can only write what a stored
+// plan contains, and the confirmation hook shows that same plan to the user.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Kept outside the package folder: under npx the package lives in the npm cache, and the
+// server and the confirmation hook must agree on one location however each was started.
+const DIR = process.env.DOTCMS_PLANS_DIR || path.join(os.homedir(), ".dotcms-mcp", "plans");
+export const PLAN_TTL_MS = 30 * 60 * 1000;
+const MAX_SHOWN_LINES = 40;
+
+const splitLines = (s) => (s === "" ? [] : s.replace(/\r\n/g, "\n").split("\n"));
+
+/** Line diff via longest common subsequence; returns only "+ n: text" / "- n: text" lines. */
+export function diffLines(oldText, newText) {
+  const a = splitLines(oldText);
+  const b = splitLines(newText);
+  const lcs = Array.from({ length: a.length + 1 }, () => new Uint32Array(b.length + 1));
+  for (let i = a.length - 1; i >= 0; i--) {
+    for (let j = b.length - 1; j >= 0; j--) {
+      lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    }
+  }
+  const out = [];
+  let i = 0;
+  let j = 0;
+  while (i < a.length || j < b.length) {
+    if (i < a.length && j < b.length && a[i] === b[j]) {
+      i++;
+      j++;
+    } else if (j < b.length && (i === a.length || lcs[i][j + 1] >= lcs[i + 1][j])) {
+      out.push(`+ ${j + 1}: ${b[j++]}`);
+    } else {
+      out.push(`- ${i + 1}: ${a[i++]}`);
+    }
+  }
+  return out;
+}
+
+const planFile = (id) => path.join(DIR, `${id}.json`);
+
+function prune() {
+  if (!fs.existsSync(DIR)) return;
+  for (const name of fs.readdirSync(DIR)) {
+    const file = path.join(DIR, name);
+    try {
+      if (JSON.parse(fs.readFileSync(file, "utf8")).expiresAt < Date.now()) fs.rmSync(file);
+    } catch {
+      fs.rmSync(file, { force: true });
+    }
+  }
+}
+
+export function savePlan(plan) {
+  fs.mkdirSync(DIR, { recursive: true, mode: 0o700 });
+  prune();
+  const id = crypto.randomBytes(6).toString("hex");
+  const stored = { ...plan, id, createdAt: Date.now(), expiresAt: Date.now() + PLAN_TTL_MS };
+  fs.writeFileSync(planFile(id), JSON.stringify(stored, null, 2), { mode: 0o600 });
+  return stored;
+}
+
+export function loadPlan(id) {
+  if (!/^[a-f0-9]{12}$/.test(String(id ?? ""))) {
+    throw new Error("Missing or malformed planId. Create a plan with plan_vtl_change first.");
+  }
+  if (!fs.existsSync(planFile(id))) {
+    throw new Error(`Plan ${id} does not exist (already applied, expired, or never created). Create a new plan with plan_vtl_change.`);
+  }
+  const plan = JSON.parse(fs.readFileSync(planFile(id), "utf8"));
+  if (plan.expiresAt < Date.now()) {
+    fs.rmSync(planFile(id), { force: true });
+    throw new Error(`Plan ${id} has expired (plans are valid for ${PLAN_TTL_MS / 60000} minutes). Create a new plan with plan_vtl_change.`);
+  }
+  return plan;
+}
+
+export const deletePlan = (id) => fs.rmSync(planFile(id), { force: true });
+
+const KIND_LABEL = { api: "API VTL file", "custom-field": "custom field VTL file", vtl: "VTL file" };
+
+/** The human-readable plan: shown by plan_vtl_change and again by the confirmation hook. */
+export function renderPlan(plan) {
+  const added = plan.changes.filter((l) => l.startsWith("+")).length;
+  const shown =
+    plan.changes.length > MAX_SHOWN_LINES
+      ? [...plan.changes.slice(0, MAX_SHOWN_LINES), `… ${plan.changes.length - MAX_SHOWN_LINES} more changed lines`]
+      : plan.changes;
+  const minutesLeft = Math.max(0, Math.round((plan.expiresAt - Date.now()) / 60000));
+
+  return [
+    `PLAN ${plan.id}: ${plan.action} ${KIND_LABEL[plan.kind] || KIND_LABEL.vtl} in dotCMS`,
+    `Instance: ${plan.instance}`,
+    `Site:     ${plan.site}`,
+    `Path:     ${plan.path}`,
+    `Language: ${plan.languageId ?? "default"}`,
+    `Publish:  ${plan.publish ? "YES — goes live immediately" : "no — working version only"}`,
+    `Size:     ${splitLines(plan.content).length} lines, ${Buffer.byteLength(plan.content)} bytes`,
+    `Valid:    ${minutesLeft} more minutes, one use`,
+    ...(plan.warnings.length ? ["", ...plan.warnings.map((w) => `WARNING: ${w}`)] : []),
+    ...(plan.hints.length ? ["", ...plan.hints] : []),
+    "",
+    plan.action === "CREATE" ? "New file:" : `Changes: +${added} / -${plan.changes.length - added} lines`,
+    ...shown,
+  ].join("\n");
+}