From d79c3cce0e85acec819710231db74cc517304c33 Mon Sep 17 00:00:00 2001 From: Phil Whittaker Date: Mon, 15 Dec 2025 12:11:22 +0000 Subject: [PATCH 1/5] Add read-only mode and new document tools to MCP documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Document UMBRACO_READONLY environment variable for enabling read-only mode - Add update-document-properties tool for partial document updates - Add update-block-property tool for updating BlockList/BlockGrid/RichText blocks 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- 17/umbraco-cms/reference/developer-mcp/available-tools.md | 2 ++ 17/umbraco-cms/reference/developer-mcp/configuration.md | 3 ++- 2 files changed, 4 insertions(+), 1 deletion(-) diff --git a/17/umbraco-cms/reference/developer-mcp/available-tools.md b/17/umbraco-cms/reference/developer-mcp/available-tools.md index d8e149374d5..9292e72e14a 100644 --- a/17/umbraco-cms/reference/developer-mcp/available-tools.md +++ b/17/umbraco-cms/reference/developer-mcp/available-tools.md @@ -112,6 +112,8 @@ The names shown in parentheses, for example, `(document)` or `(data-type)` refer - `sort-document` — Sort document order - `unpublish-document` — Unpublish a document - `update-document` — Update a document +- `update-document-properties` — Update or add property values on a document without requiring the full document JSON payload +- `update-block-property` — Update or add property values within BlockList, BlockGrid, or RichText block content - `put-document-domains` — Update document domains - `put-document-notifications` — Update document notifications - `put-document-public-access` — Update document public access diff --git a/17/umbraco-cms/reference/developer-mcp/configuration.md b/17/umbraco-cms/reference/developer-mcp/configuration.md index 5d31abb0396..b3946488c7c 100644 --- a/17/umbraco-cms/reference/developer-mcp/configuration.md +++ b/17/umbraco-cms/reference/developer-mcp/configuration.md @@ -61,10 +61,11 @@ UMBRACO_EXCLUDE_TOOLS="document-move,media-delete" | Key | Description | | --- | --- | +| `UMBRACO_READONLY` | *(Optional, security feature)*
Enables readonly mode to prevent any modifications to your Umbraco CMS. When enabled, all create, update, delete, and publish tools are disabled while query and retrieval tools remain available. This is useful for safely exploring content or connecting to production environments.

Default: `false`

Example:
`UMBRACO_READONLY="true"`

CLI: `--umbraco-readonly` | | `UMBRACO_ALLOWED_MEDIA_PATHS` | *(Optional, security feature)*
Defines a comma-separated list of absolute directory paths allowed for media uploads using the `filePath` source type. This prevents unauthorized file system access by restricting uploads to specific, trusted directories.

Required for: Local file path uploads
Default: If not configured, all `filePath` uploads are rejected with an error.

Example:
`UMBRACO_ALLOWED_MEDIA_PATHS="/tmp/uploads,/var/media,/home/user/assets"` | {% hint style="info" %} -URL-based and base64 media uploads work without this configuration. +URL-based and base64 media uploads work without this configuration. {% endhint %} ## Environment Configuration Options From d8d2c1c7fefdc07024be623f51fedd1e04c2bb2c Mon Sep 17 00:00:00 2001 From: Phil Whittaker Date: Wed, 17 Dec 2025 15:07:52 +0000 Subject: [PATCH 2/5] Add tool modes and slices documentation to MCP configuration MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the new UMBRACO_TOOL_MODES environment variable for semantic tool bundling (publisher, developer, admin, full modes). Add comprehensive documentation for tool slices which enable operation-type filtering such as read-only browsing or excluding destructive operations. Include detailed tables for all available modes and slices with usage examples. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../reference/developer-mcp/configuration.md | 229 +++++++++++++++++- 1 file changed, 227 insertions(+), 2 deletions(-) diff --git a/17/umbraco-cms/reference/developer-mcp/configuration.md b/17/umbraco-cms/reference/developer-mcp/configuration.md index b3946488c7c..15ccc976c25 100644 --- a/17/umbraco-cms/reference/developer-mcp/configuration.md +++ b/17/umbraco-cms/reference/developer-mcp/configuration.md @@ -21,6 +21,12 @@ The Developer MCP Server can be configured in multiple ways to manage authentica If you are connecting to the secure endpoint of Umbraco locally then always set the `NODE_TLS_REJECT_UNAUTHORIZED` to `0`. {% endhint %} +### Tool Mode Configuration + +| Key | Description | +| --- | --- | +| `UMBRACO_TOOL_MODES` | Specifies semantic tool modes to enable. Modes bundle related collections together for easier configuration. For example, `publisher`, `developer`, `admin`, or `full`. | + ### Tool and Tool Collection Configuration | Key | Description | @@ -30,11 +36,230 @@ If you are connecting to the secure endpoint of Umbraco locally then always set | `UMBRACO_INCLUDE_TOOL_COLLECTIONS` | Specifies collections by name to include. Only tools from these collections will be available. | | `UMBRACO_EXCLUDE_TOOL_COLLECTIONS` | Specifies collections by name to exclude from the usable tools list. | +### Tool Slice Configuration + +| Key | Description | +| --- | --- | +| `UMBRACO_INCLUDE_SLICES` | Specifies operation types to include. For example, `read,tree,search` for read-only browsing. | +| `UMBRACO_EXCLUDE_SLICES` | Specifies operation types to exclude. For example, `delete,recycle-bin` to prevent destructive operations. | + {% hint style="info" %} Use these keys to fine-tune which tools or tool collections are exposed to your LLM. This improves performance and clarity in your conversations. {% endhint %} -#### Working with Tool Collections +## Tool Modes + +Tool modes provide a higher-level abstraction over collection filtering. Instead of specifying individual collections, you can use semantic modes that bundle related collections together. + +### Why Use Modes? + +- **Simpler configuration**: One mode name instead of listing multiple collections +- **Semantic clarity**: Express intent ("I want content editing tools") rather than technical details +- **Persona-based presets**: Compound modes like `publisher`, `developer`, `admin` match common use cases +- **Reduced errors**: No need to remember exact collection names + +### Base Modes + +Base modes map directly to specific tool collections: + +| Mode | Collections | Description | +| --- | --- | --- | +| `content` | document, document-version, document-blueprint | Content editing, versioning, and blueprints | +| `content-modeling` | document, document-type, data-type, media, media-type | Document and media structure with content output | +| `front-end` | template, partial-view, stylesheet, script, static-file | Templates, views, and assets | +| `media` | media, imaging, temporary-file | Media library and file uploads | +| `search` | indexer, searcher | Examine indexes and search | +| `users` | user, user-group, user-data | Back office user management | +| `members` | member, member-type, member-group | Front-end member management | +| `health` | health, log-viewer | Health checks and diagnostics | +| `translation` | culture, language, dictionary | Localization and translations | +| `system` | server, manifest, models-builder | Server info and code generation | +| `integrations` | webhook, redirect, relation, relation-type, tag | External integrations | + +### Compound Modes + +Compound modes expand to multiple base modes for common personas: + +| Mode | Expands To | Use Case | +| --- | --- | --- | +| `publisher` | content, media, translation | Content publishers working with documents and media | +| `developer` | content-modeling, front-end, system | Developers building templates and schemas | +| `admin` | users, members, health, system | Administrators managing users and monitoring | +| `full` | (all base modes) | Full access to all tools | + +### Mode Usage Examples + +**Single mode:** + +```bash +# Content publisher - document and media tools +UMBRACO_TOOL_MODES="content" +``` + +**Multiple modes:** + +```bash +# Content editing with translation support +UMBRACO_TOOL_MODES="content,media,translation" +``` + +**Compound mode:** + +```bash +# Full publisher preset (content + media + translation) +UMBRACO_TOOL_MODES="publisher" +``` + +**Mode with exclusions:** + +```bash +# Publisher mode but exclude version history +UMBRACO_TOOL_MODES="publisher" +UMBRACO_EXCLUDE_TOOL_COLLECTIONS="document-version" +``` + +**Mode with additional collections:** + +```bash +# Front-end development plus webhooks +UMBRACO_TOOL_MODES="front-end" +UMBRACO_INCLUDE_TOOL_COLLECTIONS="webhook" +``` + +## Tool Slices + +Tool slices provide fine-grained control over which tools are registered based on their **operation type**. Slices work alongside mode and collection filtering to enable precise tool selection. + +### Why Use Slices? + +- **Operation-based filtering**: Include only certain types of operations (for example, read-only browsing) +- **Safety controls**: Exclude destructive operations like `delete` or `recycle-bin` +- **Task-specific toolsets**: Enable only the operations needed for a specific workflow + +### Available Slices + +#### Core CRUD Operations + +| Slice | Description | +| --- | --- | +| `create` | Create entities including folders | +| `read` | Get single or batch items by ID | +| `update` | Update entities including folders | +| `delete` | Delete entities (excluding recycle bin) | + +#### Tree Navigation + +| Slice | Description | +| --- | --- | +| `tree` | All tree navigation (root, children, ancestors, siblings) | +| `folders` | Folder-specific operations | + +#### Query Operations + +| Slice | Description | +| --- | --- | +| `search` | Search and filter operations | +| `list` | List all items | +| `references` | Reference and dependency queries | + +#### Workflow Operations + +| Slice | Description | +| --- | --- | +| `publish` | Publishing and unpublishing | +| `recycle-bin` | Recycle bin operations | +| `move` | Move operations (excluding recycle bin) | +| `copy` | Copy operations | +| `sort` | Sort and reorder operations | +| `validate` | Validation operations | +| `rename` | Rename file-based entities | + +#### Information Operations + +| Slice | Description | +| --- | --- | +| `configuration` | Configuration retrieval | +| `audit` | Audit trail access | +| `urls` | URL and domain management | +| `domains` | Domain configuration | +| `permissions` | User permission queries | +| `user-status` | User account operations (enable, disable, unlock) | +| `current-user` | Current user context | + +#### Entity Management + +| Slice | Description | +| --- | --- | +| `notifications` | Content notification settings | +| `public-access` | Content protection rules | +| `scaffolding` | Content creation helpers | +| `blueprints` | Blueprint specialized operations | + +#### System Operations + +| Slice | Description | +| --- | --- | +| `server-info` | Server status and information | +| `diagnostics` | Health checks, log viewer, indexer operations | +| `templates` | Template and snippet helpers | + +### Slice Usage Examples + +**Read-only content browsing:** + +```bash +UMBRACO_TOOL_MODES="content" +UMBRACO_INCLUDE_SLICES="read,tree,search" +``` + +**Full CRUD without destructive operations:** + +```bash +UMBRACO_EXCLUDE_SLICES="delete,recycle-bin" +``` + +**Content publishers (no system tools):** + +```bash +UMBRACO_INCLUDE_SLICES="create,read,update,tree,search,publish" +``` + +**Admin operations only:** + +```bash +UMBRACO_INCLUDE_SLICES="configuration,audit,user-status,diagnostics" +``` + +{% hint style="info" %} +When `UMBRACO_INCLUDE_SLICES` is set, only tools matching those slices are registered. When `UMBRACO_EXCLUDE_SLICES` is set, matching tools are excluded regardless of other settings. +{% endhint %} + +## Filtering Precedence + +The filtering system applies in the following order: + +1. **Mode expansion**: Tool modes are expanded to their constituent collections +2. **Collection merging**: Mode collections are merged with explicit `UMBRACO_INCLUDE_TOOL_COLLECTIONS` +3. **Collection exclusion**: `UMBRACO_EXCLUDE_TOOL_COLLECTIONS` is applied +4. **Dependency resolution**: Required collections are automatically included +5. **User permissions**: Tools are filtered by Umbraco API user permissions +6. **Slice filtering**: Tools are filtered by operation type (slices) +7. **Tool-level filtering**: Individual tools can be included or excluded + +### Default Behavior + +- If no filtering is specified, all collections and tools are loaded +- Collection dependencies are always resolved automatically +- User permissions are always enforced + +### Include vs Exclude + +- **Include mode**: Only specified collections/tools are loaded (via modes or explicit includes) +- **Exclude mode**: All collections/tools are loaded except those specified +- Tool-level include/exclude can override collection-level decisions +- Modes and explicit collection includes are merged (union) + +## Working with Tool Collections When configuring tools for the Developer MCP Server, you can fine-tune which tools and collections are available by using comma-separated values. @@ -57,7 +282,7 @@ UMBRACO_INCLUDE_TOOL_COLLECTIONS="document,media" UMBRACO_EXCLUDE_TOOLS="document-move,media-delete" ``` -### Security Configuration Keys +## Security Configuration Keys | Key | Description | | --- | --- | From 6e79ed05336b9301f6c6dd0c441382d156ccbf5d Mon Sep 17 00:00:00 2001 From: Phil Whittaker Date: Wed, 17 Dec 2025 16:29:26 +0000 Subject: [PATCH 3/5] Add create-media-folder tool and simplify tool modes documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add the new create-media-folder tool to available tools list. Simplify the tool modes documentation by removing compound modes (publisher, developer, admin, full) in favor of using base modes directly with explicit collection combinations. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../developer-mcp/available-tools.md | 1 + .../reference/developer-mcp/configuration.md | 25 +++---------------- 2 files changed, 4 insertions(+), 22 deletions(-) diff --git a/17/umbraco-cms/reference/developer-mcp/available-tools.md b/17/umbraco-cms/reference/developer-mcp/available-tools.md index 9292e72e14a..a7539bb3ffc 100644 --- a/17/umbraco-cms/reference/developer-mcp/available-tools.md +++ b/17/umbraco-cms/reference/developer-mcp/available-tools.md @@ -249,6 +249,7 @@ The names shown in parentheses, for example, `(document)` or `(data-type)` refer - `get-media-root` — Get root media items - `create-media` — Create new media - `create-media-multiple` — Create multiple media items +- `create-media-folder` — Create a new folder in the media library - `delete-media` — Delete media - `update-media` — Update media - `get-media-configuration` — Get media configuration diff --git a/17/umbraco-cms/reference/developer-mcp/configuration.md b/17/umbraco-cms/reference/developer-mcp/configuration.md index 15ccc976c25..21257391a1a 100644 --- a/17/umbraco-cms/reference/developer-mcp/configuration.md +++ b/17/umbraco-cms/reference/developer-mcp/configuration.md @@ -25,7 +25,7 @@ If you are connecting to the secure endpoint of Umbraco locally then always set | Key | Description | | --- | --- | -| `UMBRACO_TOOL_MODES` | Specifies semantic tool modes to enable. Modes bundle related collections together for easier configuration. For example, `publisher`, `developer`, `admin`, or `full`. | +| `UMBRACO_TOOL_MODES` | Specifies semantic tool modes to enable. Modes bundle related collections together for easier configuration. For example, `content`, `media`, or `translation`. | ### Tool and Tool Collection Configuration @@ -55,7 +55,6 @@ Tool modes provide a higher-level abstraction over collection filtering. Instead - **Simpler configuration**: One mode name instead of listing multiple collections - **Semantic clarity**: Express intent ("I want content editing tools") rather than technical details -- **Persona-based presets**: Compound modes like `publisher`, `developer`, `admin` match common use cases - **Reduced errors**: No need to remember exact collection names ### Base Modes @@ -76,17 +75,6 @@ Base modes map directly to specific tool collections: | `system` | server, manifest, models-builder | Server info and code generation | | `integrations` | webhook, redirect, relation, relation-type, tag | External integrations | -### Compound Modes - -Compound modes expand to multiple base modes for common personas: - -| Mode | Expands To | Use Case | -| --- | --- | --- | -| `publisher` | content, media, translation | Content publishers working with documents and media | -| `developer` | content-modeling, front-end, system | Developers building templates and schemas | -| `admin` | users, members, health, system | Administrators managing users and monitoring | -| `full` | (all base modes) | Full access to all tools | - ### Mode Usage Examples **Single mode:** @@ -103,18 +91,11 @@ UMBRACO_TOOL_MODES="content" UMBRACO_TOOL_MODES="content,media,translation" ``` -**Compound mode:** - -```bash -# Full publisher preset (content + media + translation) -UMBRACO_TOOL_MODES="publisher" -``` - **Mode with exclusions:** ```bash -# Publisher mode but exclude version history -UMBRACO_TOOL_MODES="publisher" +# Content mode but exclude version history +UMBRACO_TOOL_MODES="content" UMBRACO_EXCLUDE_TOOL_COLLECTIONS="document-version" ``` From 6653d5c31d67d742c92b750ca710fd378af5a040 Mon Sep 17 00:00:00 2001 From: Phil Whittaker Date: Wed, 17 Dec 2025 16:55:06 +0000 Subject: [PATCH 4/5] Add composite slices documentation for folder and recycle bin operations MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Simplify CRUD slice descriptions and add new Composite Slices section explaining how slices combine for granular control over folder and recycle bin operations. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude --- .../reference/developer-mcp/configuration.md | 40 ++++++++++++++----- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/17/umbraco-cms/reference/developer-mcp/configuration.md b/17/umbraco-cms/reference/developer-mcp/configuration.md index 21257391a1a..0b7aa813f0e 100644 --- a/17/umbraco-cms/reference/developer-mcp/configuration.md +++ b/17/umbraco-cms/reference/developer-mcp/configuration.md @@ -123,10 +123,10 @@ Tool slices provide fine-grained control over which tools are registered based o | Slice | Description | | --- | --- | -| `create` | Create entities including folders | +| `create` | Create entities | | `read` | Get single or batch items by ID | -| `update` | Update entities including folders | -| `delete` | Delete entities (excluding recycle bin) | +| `update` | Update entities | +| `delete` | Delete entities | #### Tree Navigation @@ -148,8 +148,7 @@ Tool slices provide fine-grained control over which tools are registered based o | Slice | Description | | --- | --- | | `publish` | Publishing and unpublishing | -| `recycle-bin` | Recycle bin operations | -| `move` | Move operations (excluding recycle bin) | +| `move` | Move operations | | `copy` | Copy operations | | `sort` | Sort and reorder operations | | `validate` | Validation operations | @@ -184,6 +183,31 @@ Tool slices provide fine-grained control over which tools are registered based o | `diagnostics` | Health checks, log viewer, indexer operations | | `templates` | Template and snippet helpers | +#### Composite Slices + +Tools can have multiple slices assigned to allow fine-grained filtering. For example, to include folder creation but exclude folder deletion, you can combine slices. + +**Folder operations:** + +| Slices | Description | +| --- | --- | +| `create` + `folders` | Folder creation | +| `read` + `folders` | Folder reading | +| `update` + `folders` | Folder updating | +| `delete` + `folders` | Folder deletion | +| `list` + `folders` | List folders | + +**Recycle bin operations:** + +| Slices | Description | +| --- | --- | +| `delete` + `recycle-bin` | Delete from or empty recycle bin | +| `move` + `recycle-bin` | Move to or restore from recycle bin | +| `read` + `recycle-bin` | Read recycle bin info (original parent) | +| `references` + `recycle-bin` | Get references for recycled items | +| `tree` + `recycle-bin` | Navigate recycle bin (root, children, siblings) | + + ### Slice Usage Examples **Read-only content browsing:** @@ -193,12 +217,6 @@ UMBRACO_TOOL_MODES="content" UMBRACO_INCLUDE_SLICES="read,tree,search" ``` -**Full CRUD without destructive operations:** - -```bash -UMBRACO_EXCLUDE_SLICES="delete,recycle-bin" -``` - **Content publishers (no system tools):** ```bash From 1735440629033a3d47a6a25f67b936b347d5b810 Mon Sep 17 00:00:00 2001 From: Phil Whittaker Date: Thu, 18 Dec 2025 14:40:19 +0000 Subject: [PATCH 5/5] Swap modes --- 17/umbraco-cms/reference/developer-mcp/configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/17/umbraco-cms/reference/developer-mcp/configuration.md b/17/umbraco-cms/reference/developer-mcp/configuration.md index 0b7aa813f0e..14f0468f802 100644 --- a/17/umbraco-cms/reference/developer-mcp/configuration.md +++ b/17/umbraco-cms/reference/developer-mcp/configuration.md @@ -63,8 +63,8 @@ Base modes map directly to specific tool collections: | Mode | Collections | Description | | --- | --- | --- | -| `content` | document, document-version, document-blueprint | Content editing, versioning, and blueprints | -| `content-modeling` | document, document-type, data-type, media, media-type | Document and media structure with content output | +| `content` | document, document-version, document-blueprint, tag | Content editing, versioning, blueprints, and tags | +| `content-modeling` | document-type, data-type, media-type | Document and media type definitions | | `front-end` | template, partial-view, stylesheet, script, static-file | Templates, views, and assets | | `media` | media, imaging, temporary-file | Media library and file uploads | | `search` | indexer, searcher | Examine indexes and search | @@ -73,7 +73,7 @@ Base modes map directly to specific tool collections: | `health` | health, log-viewer | Health checks and diagnostics | | `translation` | culture, language, dictionary | Localization and translations | | `system` | server, manifest, models-builder | Server info and code generation | -| `integrations` | webhook, redirect, relation, relation-type, tag | External integrations | +| `integrations` | webhook, redirect, relation, relation-type | External integrations | ### Mode Usage Examples