rpg0-dotcms-mcp 1.1.0 → 1.1.1

package/README.md

@@ -0,0 +1,155 @@
+# 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_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/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.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": {