diff --git a/.github/styles/UmbracoDocs/Acronyms.yml b/.github/styles/UmbracoDocs/Acronyms.yml index 06de01a95d3..a7dc4ddbfe5 100644 --- a/.github/styles/UmbracoDocs/Acronyms.yml +++ b/.github/styles/UmbracoDocs/Acronyms.yml @@ -30,7 +30,10 @@ exceptions: - CMD # Command (Windows shell) - CMS # Content Management System - CPU # Central Processing Unit + - CRM # Customer Relationship Management + - CRUD # Create, Read, Update, Delete - CSS # Cascading Style Sheets + - CSV # Comma Separated Values - CTRL # Control (Keyboard key) - CURL # Client URL - DELETE # HTTP DELETE method @@ -68,6 +71,9 @@ exceptions: - KUDU # Azure deployment engine - LDAP # Lightweight Directory Access Protocol - LINK # + - LINQ # Language Integrated Query + - LLM # Large Language Model + - MCP # Mode Context Protocol - MIT # Open-source software license developed at the Massachusetts Institute of Technology (MIT) - MDN # Mozilla Developer Network - MFA # Multi-factor Authentication @@ -110,6 +116,7 @@ exceptions: - UI # User Interface - URI # Uniform Resource Identifier - URL # Uniform Resource Locator + - USB # Universal Serial Bus - UTC # Coordinated Universal Time - UUID # Universally Unique Identifier - UWP # Universal Windows Platform diff --git a/16/umbraco-cms/SUMMARY.md b/16/umbraco-cms/SUMMARY.md index 9b1169da554..8dd434b620a 100644 --- a/16/umbraco-cms/SUMMARY.md +++ b/16/umbraco-cms/SUMMARY.md @@ -358,6 +358,22 @@ * [Additional preview environments support](reference/content-delivery-api/additional-preview-environments-support.md) * [Webhooks](reference/webhooks/README.md) * [Expanding Webhook Events](reference/webhooks/expanding-webhook-events.md) +* [Developer MCP](reference/developer-mcp/README.md) + * [Key Concepts](reference/developer-mcp/concepts/README.md) + * [Model Context Protocol](reference/developer-mcp/concepts/model-context-protocol.md) + * [Context Engineering](reference/developer-mcp/concepts/context-enginerring.md) + * [Host Setup](reference/developer-mcp/host-setup/README.md) + * [Claude Desktop](reference/developer-mcp/host-setup/claude-desktop.md) + * [Claude Code](reference/developer-mcp/host-setup/claude-code.md) + * [Cursor](reference/developer-mcp/host-setup/cursor.md) + * [GitHub Copilot](reference/developer-mcp/host-setup/github-copilot.md) + * [Best Practice](reference/developer-mcp/best-practice/README.md) + * [Example Instruction File](reference/developer-mcp/best-practice/example-instructions.md) + * [Creating Media](reference/developer-mcp/best-practice/creating-media.md) + * [Configuration](reference/developer-mcp/configuration.md) + * [Available Tools](reference/developer-mcp/available-tools.md) + * [Excluded Tools](reference/developer-mcp/excluded-tools.md) + * [Use Cases and Scenarios](reference/developer-mcp/scenarios.md) * [API versioning and OpenAPI](reference/api-versioning-and-openapi.md) * [Searching](reference/searching/README.md) * [Examine](reference/searching/examine/README.md) diff --git a/16/umbraco-cms/reference/developer-mcp/README.md b/16/umbraco-cms/reference/developer-mcp/README.md new file mode 100644 index 00000000000..bf46932e0c8 --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/README.md @@ -0,0 +1,201 @@ +--- +description: Get started with the CMS developer MCP. +--- + +# Developer Model Context Protocol (MCP) server + +The Developer [MCP Server](./concepts/model-context-protocol.md#mcp-servers) makes it straightforward for developers to connect AI tools with Umbraco. It allows you to harness large language models (LLMs) to perform almost any task that can be achieved within the Umbraco backoffice. This includes generating and editing content, managing media, automating workflows, and assisting with complex development tasks. + +This MCP Server acts as a secure gateway between your Umbraco installation and MCP-compatible AI environments. These include Claude (Desktop or Code), Cursor, or GitHub Copilot and many more. + +Through this bridge, your AI assistant can interact directly with Umbraco's Management API. This enables a more natural, conversational way to develop and maintain your sites. + +{% hint style="info" %} +Think of it as giving your AI tools a secure, structured way to “speak to Umbraco.” +{% endhint %} + +## How does it work + +Unlike most Umbraco integrations, the Developer CMS MCP Server is not a plugin that you install into your Umbraco site. +Instead, it runs as a standalone Node.js application that acts as an MCP server. + +[MCP clients](./concepts/model-context-protocol.md#mcp-clients) are implemented inside compatible [host applications](./concepts/model-context-protocol.md#host-applications) such as Claude Desktop, Cursor, or Windsurf. These clients connect to this server. When you interact with your chat-based development environment, the client communicates with the MCP Server using the Model Context Protocol (MCP). + +Learn more about [Model Context Protocol (MCP)](./concepts/model-context-protocol.md) + +The MCP Server, in turn, talks directly to Umbraco through the Management API. This is the same API layer that powers the Umbraco backoffice and allows the server to directly read from and modify the CMS. + +By exposing these endpoints as MCP tools, the Developer MCP Server enables you to perform almost any backoffice action. You can do this through natural language interaction with your LLM-powered chat environment. + +{% hint style="info" %} +The MCP Server acts as the bridge between your Umbraco instance and your AI assistant. It translates and adapts your tasks into Management API calls. +{% endhint %} + +## Who is this for? + +**The Developer MCP Server is designed specifically to be used by Umbraco developers.** + +While the Model Context Protocol (MCP) can be used for many types of solution, automation, and workflow integrations. This particular MCP Server focuses on developer-oriented tasks and productivity enhancements within Umbraco projects. + +Example use cases: + +- **Automation of content, media and schema** +Automate repetitive actions through conversational commands. This includes creating or updating content or media, generating content models, or performing large-scale operations. + +- **Developer quality-of-life improvements** +Speed up tasks that would otherwise take time or require numerous clicks in the backoffice UI. Examples include batch-moving Document Types or Data Types, cleaning up unused entities, or synchronising content structures. + +- **Integration into modern development workflows** +Use the Developer MCP Server alongside other MCP servers such as Playwright MCP, Figma MCP, or GitHub MCP. This streamlines your end-to-end site development process. + +- **Leveraging LLM reasoning** +Use your LLM to understand, debug, or make better decisions. For example, ask it to interpret entries from Umbraco Logs, suggest schema changes, or explain configuration errors. + +- [**Plus many, many more**](./scenarios.md) + +**Not recommended for non-developers** + +While it’s technically feasible for non-developers to connect to Umbraco using this MCP server, we do not recommend it for the following reasons: + +- **Complex setup requirements** +This MCP server must be run locally, and it requires a configured Umbraco user account with appropriate permissions. + +- **Powerful tool access** +Even for users with limited permissions, the MCP Server exposes many management-level tools. Incorrect commands could unintentionally alter or damage your Umbraco instance. + +{% hint style="warning" %} +Do not connect the Developer MCP Server to a production Umbraco environment. +Always use a local or isolated development instance. +{% endhint %} + +We are actively working on additional MCP servers tailored to other roles such as editors and content managers. These will provide safer, simplified toolsets and workflows. + +## Getting started + +### Umbraco Setup + +Before connecting the MCP Server, you need to create an [API User](../../fundamentals/data/users/api-users.md) in Umbraco. This user allows the MCP Server to communicate securely with the Management API. + +The level of access you assign to this API user determines what actions your AI agent can perform. +For example: + +- A user with Editor permissions can manage and update content but cannot modify Document Types or perform administrative tasks. +- A user with Administrator permissions grants full access to all capabilities. This includes the ability to create, edit, or delete document types, data types, and more within Umbraco. + +{% hint style="warning" %} +Only use a dedicated API user for MCP connections. +Do not share or reuse credentials from an existing backoffice user. +{% endhint %} + +### Host Setup + +Each MCP-compatible host application has its own setup process. For this reason, we provide dedicated setup guides for the main developer environments we see most often: + +[Claude Desktop](./host-setup/claude-desktop.md) +[Claude Code](./host-setup/claude-code.md) +[GitHub Copilot](./host-setup/github-copilot.md) +[Cursor](./host-setup/cursor.md) + +Although the details vary slightly, the general pattern is the same across all hosts: + +``` json +{ + "umbraco-mcp": { + "command": "npx", + "args": ["@umbraco-cms/mcp-dev@beta"], + "env": { + "NODE_TLS_REJECT_UNAUTHORIZED": "0", + "UMBRACO_CLIENT_ID": "umbraco-back-office-mcp", + "UMBRACO_CLIENT_SECRET": "1234567890", + "UMBRACO_BASE_URL": "https://localhost:12345", + "UMBRACO_INCLUDE_TOOL_COLLECTIONS": "document,media,document-type,data-type" + } + } +} + +``` + +Add your Umbraco MCP configuration values (Client ID, Client Secret, URL of Umbraco) in the appropriate section of your host setup. Then restart the MCP Server or, in some cases, restart the host application itself. + +Once restarted, you’ll have access to the full suite of tools available through the Umbraco CMS Developer MCP Server. + +{% hint style="info" %} +This Developer MCP Server requires Node.js version 22 or higher to be installed. +You can check your current Node.js version by running node -v in your terminal. +{% endhint %} + +#### Never Use Against Production Environments + +{% hint style="danger" %} +**Critical: Do not connect the Developer MCP Server to a production Umbraco environment.** + +The Developer MCP Server provides powerful, direct access to your Umbraco Management API. While this makes it a good tool for development and testing, mistakes can have serious consequences. Misconfigurations or misunderstood commands can cause immediate and potentially destructive damage. + +**Always use the Developer MCP Server with:** +- Local development instances only +- Isolated staging or test environments +- Environments where data loss or corruption would not impact live users or business operations + +**Never connect to:** +- Production websites +- Live client sites +- Any environment where content, media, or configuration changes could affect real users + +Even with limited user permissions, the scope and power of LLM-driven actions make this tool unsuitable for production use. +{% endhint %} + +### Choosing Your Tools + +Your first step after setup should be deciding which tools you want to enable. +All tools are grouped into collections for easier management and isolation. + +[Learn more about Tool Collections](./available-tools.md) + +Choosing the right tools improves how efficiently the AI communicates with Umbraco, making each conversation faster and more context-aware. + +[Learn more about Context Engineering](./concepts/context-enginerring.md) + +### Why Use npx? + +We recommend launching the Developer MCP Server using npx. +This allows you to run the Node.js application without needing to install anything globally. +npx will temporarily download the package, execute it, and clean up automatically — ensuring you’re always using the latest version. + +If you prefer, you can also install it globally with: + +``` bash + +npm install -g @umbraco/mcp-server + +``` + +For advanced configuration options and environment variable settings, see the [Configuration guide](./configuration.md). + +## Working with the MCP Server + +Once your MCP server is configured and connected, explore these guides to get the most out of your setup: + +- [Creating Media](./creating-media.md) - Learn how to upload and manage media items programmatically +- [Available Tools](./available-tools.md) - Complete reference of all available tools and collections +- [Scenarios](./scenarios.md) - Real-world examples and use cases +- [Best Practices](./best-practice/README.md) - Tips for effective MCP usage + +## Version Compatibility + +The Umbraco MCP Server is designed to work with specific major versions of Umbraco CMS: + +| MCP Server Version | Compatible Umbraco Version | NPM Package Name | +|--------------------|----------------------------|--------------------------------------| +| 15.x.x | alpha | @umbraco-mcp/umbraco-mcp-cms@alpha | +| 16.x.x | all betas, 16.x | @umbraco-cms/mcp-dev@beta | + +### Version Checking + +The MCP server automatically checks version compatibility on startup: + +- **✅ Version Match**: No message displayed, server functions normally +- **⚠️ Version Mismatch**: The first tool request will fail with an error message asking you to retry if you want to proceed. After you retry, the warning displays once more. It is then never shown again for that session. +- **⚠️ API Error**: If the version check API call fails, a warning is displayed once but does not block tool execution. + +The version check uses the Umbraco Management API endpoint `/umbraco/management/api/v1/server/information` to detect the connected Umbraco version and compares the major version number. + diff --git a/16/umbraco-cms/reference/developer-mcp/available-tools.md b/16/umbraco-cms/reference/developer-mcp/available-tools.md new file mode 100644 index 00000000000..4a632fe7122 --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/available-tools.md @@ -0,0 +1,446 @@ +--- +description: The tools that have been enabled in the Developer MCP +--- + +# Available tools + +This document lists all available tools grouped according to the categories defined in the **Umbraco Open API definition**. +Each section represents a functional area of the API, following the same grouping and naming conventions used within Umbraco’s backend services. + +The names shown in parentheses — for example, `(document)` or `(data-type)` — refer to the **Tool Collection names**, which are used for configuration via environment variables; UMBRACO_INCLUDE_TOOL_COLLECTIONS or UMBRACO_EXCLUDE_TOOL_COLLECTIONS. + + +## Table of Contents +- [Culture (`culture`)](#culture-culture) +- [Data Type (`data-type`)](#data-type-data-type) +- [Dictionary (`dictionary`)](#dictionary-dictionary) +- [Document (`document`)](#document-document) +- [Document Blueprint (`document-blueprint`)](#document-blueprint-document-blueprint) +- [Document Version (`document-version`)](#document-version-document-version) +- [Document Type (`document-type`)](#document-type-document-type) +- [Health (`health`)](#health-health) +- [Imaging (`imaging`)](#imaging-imaging) +- [Indexer (`indexer`)](#indexer-indexer) +- [Language (`language`)](#language-language) +- [Log Viewer (`log-viewer`)](#log-viewer-log-viewer) +- [Manifest (`manifest`)](#manifest-manifest) +- [Media (`media`)](#media-media) +- [Media Type (`media-type`)](#media-type-media-type) +- [Member (`member`)](#member-member) +- [Member Group (`member-group`)](#member-group-member-group) +- [Member Type (`member-type`)](#member-type-member-type) +- [Models Builder (`models-builder`)](#models-builder-models-builder) +- [Partial View (`partial-view`)](#partial-view-partial-view) +- [Property Type (`property-type`)](#property-type-property-type) +- [Redirect (`redirect`)](#redirect-redirect) +- [Relation (`relation`)](#relation-relation) +- [Relation Type (`relation-type`)](#relation-type-relation-type) +- [Script (`script`)](#script-script) +- [Searcher (`searcher`)](#searcher-searcher) +- [Server (`server`)](#server-server) +- [Static File (`static-file`)](#static-file-static-file) +- [Stylesheet (`stylesheet`)](#stylesheet-stylesheet) +- [Tag (`tag`)](#tag-tag) +- [Template (`template`)](#template-template) +- [Temporary File (`temporary-file`)](#temporary-file-temporary-file) +- [User (`user`)](#user-user) +- [User Data (`user-data`)](#user-data-user-data) +- [User Group (`user-group`)](#user-group-user-group) +- [Webhook (`webhook`)](#webhook-webhook) + +--- + +## Culture (`culture`) +- `get-culture` — Get all cultures available to Umbraco + +## Data Type (`data-type`) +- `get-data-type-search` — Search for Data Types +- `get-references-data-type` — Get references to a Data Type +- `is-used-data-type` — Check if a Data Type is in use +- `get-data-type` — Get a specific Data Type by ID +- `get-data-type-configuration` — Get Data Type configuration +- `get-property-editor-template` — Get property editor template +- `get-data-type-root` — Get root level Data Types +- `get-data-type-children` — Get child Data Types +- `get-data-type-ancestors` — Get ancestor Data Types +- `get-all-data-types` — Get all Data Types +- `delete-data-type` — Delete a Data Type +- `create-data-type` — Create a new Data Type +- `update-data-type` — Update an existing Data Type +- `copy-data-type` — Copy a Data Type +- `move-data-type` — Move a Data Type to a different location +- `find-data-type` — Find Data Types by criteria +- `create-data-type-folder` — Create a folder for organizing Data Types +- `delete-data-type-folder` — Delete a Data Type folder +- `get-data-type-folder` — Get information about a Data Type folder +- `update-data-type-folder` — Update a Data Type folder's details + +## Dictionary (`dictionary`) +- `find-dictionary-item` — Search for dictionary items +- `create-dictionary-item` — Create a new dictionary item +- `get-dictionary-item` — Get a dictionary item by key +- `delete-dictionary-item` — Delete a dictionary item +- `update-dictionary-item` — Update a dictionary item +- `move-dictionary-item` — Move a dictionary item +- `get-dictionary-root` — Get root dictionary items +- `get-dictionary-children` — Get child dictionary items +- `get-dictionary-ancestors` — Get ancestor dictionary items + +## Document (`document`) +- `get-document-by-id` — Get a document by ID +- `get-document-publish` — Get document publish status +- `get-document-configuration` — Get document configuration +- `copy-document` — Copy a document +- `create-document` — Create a new document +- `post-document-public-access` — Set document public access +- `delete-document` — Delete a document +- `delete-document-public-access` — Remove public access from a document +- `get-document-urls` — Get document URLs +- `get-document-domains` — Get document domains +- `get-document-audit-log` — Get document audit log +- `get-document-public-access` — Get document public access settings +- `move-document` — Move a document +- `move-to-recycle-bin` — Move document to recycle bin +- `get-document-notifications` — Get document notifications +- `publish-document` — Publish a document +- `publish-document-with-descendants` — Publish a document and its descendants +- `sort-document` — Sort document order +- `unpublish-document` — Unpublish a document +- `update-document` — Update a document +- `put-document-domains` — Update document domains +- `put-document-notifications` — Update document notifications +- `put-document-public-access` — Update document public access +- `delete-from-recycle-bin` — Delete document from recycle bin +- `empty-recycle-bin` — Empty the recycle bin +- `restore-document-from-recycle-bin` — Restore a document from the recycle bin +- `get-recycle-bin-root` — Get root items in recycle bin +- `get-recycle-bin-children` — Get child items in recycle bin +- `search-document` — Search for documents +- `validate-document` — Validate a document +- `get-collection-document-by-id` — Get document collection by ID +- `get-document-are-referenced` — Check if documents are referenced +- `get-document-by-id-referenced-by` — Get documents referencing this document +- `get-document-by-id-referenced-descendants` — Get referenced descendants of a document +- `get-recycle-bin-document-original-parent` — Get original parent of recycled document +- `get-recycle-bin-document-referenced-by` — Get documents referencing recycled document +- `get-document-root` — Get root documents +- `get-document-children` — Get child documents +- `get-document-ancestors` — Get document ancestors + +## Document Blueprint (`document-blueprint`) +- `get-document-blueprint` — Get a document blueprint +- `create-document-blueprint` — Create a new document blueprint +- `update-document-blueprint` — Update a document blueprint +- `delete-document-blueprint` — Delete a document blueprint +- `move-document-blueprint` — Move a document blueprint +- `get-document-blueprint-by-id-array` — Get document blueprints by IDs +- `get-document-blueprint-scaffold` — Get scaffold for creating a blueprint +- `create-document-blueprint-from-document` — Create a blueprint from an existing document +- `get-document-blueprint-ancestors` — Get blueprint ancestors +- `get-document-blueprint-children` — Get blueprint children +- `get-document-blueprint-root` — Get root blueprints +- `create-document-blueprint-folder` — Create a blueprint folder +- `get-document-blueprint-folder` — Get blueprint folder information +- `update-document-blueprint-folder` — Update a blueprint folder +- `delete-document-blueprint-folder` — Delete a blueprint folder + +## Document Version (`document-version`) +- `get-document-version` — Get document versions with pagination +- `get-document-version-by-id` — Get a specific document version by ID +- `update-document-version-prevent-cleanup` — Prevent or allow cleanup of a document version +- `create-document-version-rollback` — Roll back a document to a specific version + +## Document Type (`document-type`) +- `get-document-type` — Get a Document Type +- `get-document-type-configuration` — Get Document Type configuration +- `get-document-type-blueprint` — Get Document Type blueprint +- `get-document-types-by-id-array` — Get Document Types by IDs +- `get-document-type-available-compositions` — Get available compositions +- `get-document-type-composition-references` — Get composition references +- `update-document-type` — Update a Document Type +- `copy-document-type` — Copy a Document Type +- `move-document-type` — Move a Document Type +- `create-document-type` — Create a new Document Type +- `delete-document-type` — Delete a Document Type +- `create-element-type` — Create an element type +- `get-icons` — Get available icons +- `get-document-type-allowed-children` — Get allowed child types +- `get-all-document-types` — Get all Document Types +- `create-document-type-folder` — Create a folder +- `delete-document-type-folder` — Delete a folder +- `get-document-type-folder` — Get folder info +- `update-document-type-folder` — Update folder details +- `get-document-type-root` — Get root Document Types +- `get-document-type-ancestors` — Get Document Type ancestors +- `get-document-type-children` — Get Document Type children + +## Health (`health`) +- `get-health-check-groups` — Get all health check groups +- `get-health-check-group-by-name` — Get health check group by name +- `run-health-check-group` — Run health checks for a specific group +- `execute-health-check-action` — Execute a health check action + +## Imaging (`imaging`) +- `get-imaging-resize-urls` — Generate image resize URLs with processing options + +## Indexer (`indexer`) +- `get-indexer` — Get all indexers +- `get-indexer-by-index-name` — Get indexer by index name +- `post-indexer-by-index-name-rebuild` — Rebuild an index by name + +## Language (`language`) +- `get-language-items` — Get all languages +- `get-default-language` — Get default language +- `create-language` — Create a new language +- `update-language` — Update a language +- `delete-language` — Delete a language +- `get-language-by-iso-code` — Get language by ISO code + +## Log Viewer (`log-viewer`) +- `get-log-viewer-saved-search-by-name` — Get saved search by name +- `get-log-viewer-level-count` — Get log level counts +- `post-log-viewer-saved-search` — Save a log search +- `delete-log-viewer-saved-search-by-name` — Delete saved search +- `get-log-viewer` — Get logs +- `get-log-viewer-level` — Get log levels +- `get-log-viewer-search` — Search logs +- `get-log-viewer-validate-logs` — Validate logs +- `get-log-viewer-message-template` — Get message template + +## Manifest (`manifest`) +- `get-manifest-manifest` — Get all system manifests +- `get-manifest-manifest-private` — Get private manifests +- `get-manifest-manifest-public` — Get public manifests + +## Media (`media`) +- `get-media-by-id` — Get media by ID +- `get-media-ancestors` — Get media ancestors +- `get-media-children` — Get media children +- `get-media-root` — Get root media items +- `create-media` — Create new media +- `create-media-multiple` — Create multiple media items +- `delete-media` — Delete media +- `update-media` — Update media +- `get-media-configuration` — Get media configuration +- `get-media-urls` — Get media URLs +- `validate-media` — Validate media +- `sort-media` — Sort media items +- `get-media-by-id-array` — Get media by IDs +- `move-media` — Move media +- `get-media-audit-log` — Get media audit log +- `get-media-recycle-bin-root` — Get recycle bin root +- `get-media-recycle-bin-children` — Get recycle bin children +- `empty-recycle-bin` — Empty recycle bin +- `restore-media-from-recycle-bin` — Restore from recycle bin +- `move-media-to-recycle-bin` — Move to recycle bin +- `delete-from-recycle-bin` — Delete from recycle bin +- `get-media-are-referenced` — Check if media items are referenced +- `get-media-by-id-referenced-by` — Get media items referencing this media +- `get-media-by-id-referenced-descendants` — Get referenced descendants of media +- `get-collection-media` — Get media collection +- `get-recycle-bin-media-referenced-by` — Get media items referencing recycled media +- `get-recycle-bin-media-original-parent` — Get original parent of recycled media + +## Media Type (`media-type`) +- `get-media-type-folder` — Get folder information +- `create-media-type-folder` — Create a new folder +- `delete-media-type-folder` — Delete a folder +- `update-media-type-folder` — Update folder details +- `create-media-type` — Create a new media type +- `copy-media-type` — Copy a media type +- `get-media-type-available-compositions` — Get available compositions +- `update-media-type` — Update a media type +- `move-media-type` — Move a media type +- `delete-media-type` — Delete a media type +- `get-media-type-root` — Get root media types +- `get-media-type-children` — Get child media types +- `get-media-type-ancestors` — Get ancestor media types +- `get-media-type-folders` — Get media type folders +- `get-media-type-by-id` — Get media type by ID +- `get-media-type-by-ids` — Get media types by IDs +- `get-media-type-configuration` — Get media type configuration +- `get-allowed-media-type` — Get allowed media types +- `get-media-type-allowed-at-root` — Get types allowed at root +- `get-media-type-allowed-children` — Get allowed child types +- `get-media-type-composition-references` — Get composition references + +## Member (`member`) +- `get-member` — Get member by ID +- `create-member` — Create a new member +- `validate-member` — Validate member creation data +- `delete-member` — Delete a member +- `update-member` — Update a member +- `validate-member-update` — Validate member update data +- `get-member-are-referenced` — Check if members are referenced +- `get-member-by-id-referenced-by` — Get items referencing this member +- `get-member-by-id-referenced-descendants` — Get referenced descendants of member +- `find-member` — Find members + +## Member Group (`member-group`) +- `get-member-group` — Get member group +- `get-member-group-by-id-array` — Get member groups by IDs +- `create-member-group` — Create a new member group +- `update-member-group` — Update a member group +- `delete-member-group` — Delete a member group +- `get-member-group-root` — Get root member groups + +## Member Type (`member-type`) +- `get-member-type-by-id` — Get member type by ID +- `create-member-type` — Create a new member type +- `get-member-types-by-id-array` — Get member types by IDs +- `delete-member-type` — Delete a member type +- `update-member-type` — Update a member type +- `copy-member-type` — Copy a member type +- `get-member-type-available-compositions` — Get available compositions +- `get-member-type-composition-references` — Get composition references +- `get-member-type-configuration` — Get member type configuration +- `get-member-type-root` — Get root member types + +## Models Builder (`models-builder`) +- `get-models-builder-dashboard` — Get Models Builder dashboard information +- `get-models-builder-status` — Get Models Builder status +- `post-models-builder-build` — Trigger Models Builder code generation + +## Partial View (`partial-view`) +- `get-partial-view-by-path` — Get partial view by path +- `get-partial-view-folder-by-path` — Get partial view folder by path +- `get-partial-view-snippet-by-id` — Get partial view snippet by ID +- `get-partial-view-snippet` — Get partial view snippet +- `create-partial-view` — Create a new partial view +- `create-partial-view-folder` — Create a partial view folder +- `update-partial-view` — Update a partial view +- `rename-partial-view` — Rename a partial view +- `delete-partial-view` — Delete a partial view +- `delete-partial-view-folder` — Delete a partial view folder +- `get-partial-view-root` — Get root partial views +- `get-partial-view-children` — Get child partial views +- `get-partial-view-ancestors` — Get partial view ancestors +- `get-partial-view-search` — Search partial views + +## Property Type (`property-type`) +- `get-property-type-is-used` — Check if a property type is in use + +## Redirect (`redirect`) +- `get-all-redirects` — Get all redirects +- `get-redirect-by-id` — Get redirect by ID +- `delete-redirect` — Delete a redirect +- `get-redirect-status` — Get redirect status +- `update-redirect-status` — Update redirect status + +## Relation (`relation`) +- `get-relation-by-relation-type-id` — Get relations by relation type ID + +## Relation Type (`relation-type`) +- `get-relation-type` — Get all relation types +- `get-relation-type-by-id` — Get relation type by ID + +## Script (`script`) +- `get-script-by-path` — Get script by path +- `get-script-folder-by-path` — Get script folder by path +- `get-script-items` — Get script items +- `create-script` — Create a new script +- `create-script-folder` — Create a script folder +- `update-script` — Update a script +- `rename-script` — Rename a script +- `delete-script` — Delete a script +- `delete-script-folder` — Delete a script folder +- `get-script-tree-root` — Get root script items +- `get-script-tree-children` — Get child script items +- `get-script-tree-ancestors` — Get script ancestors + +## Searcher (`searcher`) +- `get-searcher` — Get all searchers +- `get-searcher-by-searcher-name-query` — Query a specific searcher by name + +## Server (`server`) +- `get-server-status` — Get server status +- `get-server-configuration` — Get server configuration +- `get-server-information` — Get server information +- `get-server-troubleshooting` — Get server troubleshooting data +- `get-server-upgrade-check` — Check for server upgrades + +## Static File (`static-file`) +- `get-static-files` — Get static files with filtering +- `get-static-file-root` — Get root static files +- `get-static-file-children` — Get child static files +- `get-static-file-ancestors` — Get static file ancestors + +## Stylesheet (`stylesheet`) +- `get-stylesheet-by-path` — Get stylesheet by path +- `get-stylesheet-folder-by-path` — Get stylesheet folder by path +- `create-stylesheet` — Create a new stylesheet +- `create-stylesheet-folder` — Create a stylesheet folder +- `update-stylesheet` — Update a stylesheet +- `rename-stylesheet` — Rename a stylesheet +- `delete-stylesheet` — Delete a stylesheet +- `delete-stylesheet-folder` — Delete a stylesheet folder +- `get-stylesheet-root` — Get root stylesheets +- `get-stylesheet-children` — Get child stylesheets +- `get-stylesheet-ancestors` — Get stylesheet ancestors +- `get-stylesheet-search` — Search stylesheets + +## Tag (`tag`) +- `get-tags` — Get all tags + +## Template (`template`) +- `get-template` — Get a template by ID +- `get-template-configuration` — Get template configuration +- `get-templates-by-id-array` — Get templates by IDs +- `create-template` — Create a new template +- `update-template` — Update a template by ID +- `delete-template` — Delete a template by ID +- `execute-template-query` — Execute template queries and return generated LINQ code +- `get-template-query-settings` — Get schema for template queries (document types, properties, operators) +- `get-template-ancestors` — Get ancestors of a template by ID +- `get-template-children` — Get child templates or template folders by parent ID +- `get-template-root` — Get root template items +- `get-template-search` — Search for templates by name + +## Temporary File (`temporary-file`) +- `create-temporary-file` — Create a temporary file +- `get-temporary-file` — Get a temporary file +- `delete-temporary-file` — Delete a temporary file +- `get-temporary-file-configuration` — Get temporary file configuration + +## User (`user`) +- `get-user` — Get users with pagination +- `get-user-by-id` — Get user by ID +- `find-user` — Find users by search criteria +- `get-item-user` — Get user item information +- `get-user-current` — Get current authenticated user +- `get-user-configuration` — Get user configuration +- `get-user-current-configuration` — Get current user configuration +- `get-user-current-login-providers` — Get current user login providers +- `get-user-current-permissions` — Get current user permissions +- `get-user-current-permissions-document` — Get current user document permissions +- `get-user-current-permissions-media` — Get current user media permissions +- `get-user-by-id-calculate-start-nodes` — Calculate start nodes for a user +- `upload-user-avatar-by-id` — Upload avatar for a user +- `upload-user-current-avatar` — Upload avatar for current user +- `delete-user-avatar-by-id` — Delete user avatar + +## User Data (`user-data`) +- `create-user-data` — Create user data key-value pair +- `update-user-data` — Update user data value +- `get-user-data` — Get all user data for current user +- `get-user-data-by-id` — Get user data by key + +## User Group (`user-group`) +- `get-user-group` — Get user group +- `get-user-group-by-id-array` — Get user groups by IDs +- `get-user-groups` — Get all user groups +- `get-filter-user-group` — Filter user groups +- `create-user-group` — Create a new user group +- `update-user-group` — Update a user group +- `delete-user-group` — Delete a user group +- `delete-user-groups` — Delete multiple user groups + +## Webhook (`webhook`) +- `get-webhook-by-id` — Get webhook by ID +- `get-webhook-by-id-array` — Get webhooks by IDs +- `delete-webhook` — Delete a webhook +- `update-webhook` — Update a webhook +- `get-webhook-events` — Get webhook events +- `get-all-webhook-logs` — Get all webhook logs +- `create-webhook` — Create a new webhook + diff --git a/16/umbraco-cms/reference/developer-mcp/best-practice/README.md b/16/umbraco-cms/reference/developer-mcp/best-practice/README.md new file mode 100644 index 00000000000..ac6cc32e9f8 --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/best-practice/README.md @@ -0,0 +1,117 @@ +--- +description: Get the most out of the Umbraco CMS developer MCP server +--- + +# Best Practice + +This page details the recommended way to use the Umbraco CMS Developer MCP Server for maximum effectiveness and reliability. + +The Developer MCP Server gives you powerful fine-grained control over what the LLM can do. To get good results, you must be deliberate about how you configure and manage each session. + +## Use Only the Tools You Need + +{% hint style="warning" %} +**Do not enable** all tools at once. This will make requests inefficient and may cause the LLM to fail or hallucinate. +{% endhint %} + +Each tool you add increases the amount of information (context) that gets sent to the model. This competes for limited space and can cause the model to lose focus, hallucinate or produce unreliable results. + +Always enable only the tools (or tool collection) needed for the current task. + +### Keep It Lean: Cost and Sustainability + +Every time you interact with the LLM, the entire context is sent to the model to generate a response. This includes the system prompt, tools, instruction files, and chat history. The smaller and more focused your context, the better. + +Large prompts and bloated toolsets not only lead to slower and less accurate results — they also increase cost and environmental impact. The more tokens you send and receive, the higher the: + +- Monetary cost (especially on usage-based APIs) +- Compute usage, which has a direct carbon footprint + +Being intentional with your prompts and tool selection isn’t only a technical best practice — it’s a sustainable one. + +{% hint style="info" %} +Optimising your context makes your work faster, cheaper, and greener. +{% endhint %} + +## Recommended Workflow + +1. Start with a clean session +Open a new session in your LLM client (e.g., Claude Desktop, Cursor or others). This ensures there’s no leftover context from a previous task. + +2. Decide on the tools or tool collection +Identify which MCP tools you'll need for the specific task. Avoid loading unnecessary functionality. + +3. Update the environment variables +Use .env or launch-time environment variables to switch tool configs. + +4. Run your prompt or workflow +Ask the model to perform the task. Keep it focused on the tools you've enabled. + +5. Complete the task, then reset +Once the task is done, clear the session. Start afresh before beginning another to avoid context bleed. + +{% hint style="info" %} +For fast, flexible configuration changes, manage tool settings using environment variables, not hardcoded secrets or source-controlled files. +{% endhint %} + +## Context Condensing + +Large Language Models have a limited context window, and every active tool, message, and instruction contributes to that total. If you're working on a complex or long-running task, you can quickly hit the limit — especially when multiple tools are enabled. + +To help manage this, you can condense context to keep the model focused and free up space. + +**Strategies for Condensing Context** + +- **Use built-in compression tools (if available)** +Some clients (e.g., Claude Code) include options to automatically compress or summarise earlier parts of the conversation. Use these to reduce noise while keeping relevant information accessible. + +- **Checkpoint progress into a file** +If you find the context filling up too quickly or you need to pause and resume later, ask the model to generate a **Markdown summary** file containing: + + - What it's working on + - How far along it is + - Any critical information or design decisions so far + +You can then start a new session and reintroduce this file at the beginning. This restores continuity without needing the full conversation history. + +{% hint style="info" %} +When using Claude Code or other editor-based tools, save progress as .md or .txt files in your repo. These files can serve as lightweight session memory between interactions. +{% endhint %} + +## Use Instruction Files to Guide the Model + +In some cases, it’s helpful to include a rules or instruction file that explains: + +- What the enabled tools do +- When and how to use them +- Any naming conventions or API-specific considerations +- Expected sequences or common workflows + +This helps the LLM reason more effectively about how to use the Developer MCP Server — especially when multiple tools are involved. + +View an example [instruction file](./example-instructions.md). + +## Crafting Good Prompts + +While the Developer MCP Server provides structured access to tools, your results still depend heavily on **how well you prompt the model**. A good prompt sets clear intent, scope, and expectations — and helps the LLM make the most of the tools available to it. + +Tips for Better Prompting + +- **Be specific about the goal** +Instead of: +Fix this content model. +Use: +Update the Document Type to include a new "SEO Description" property and apply it to all "Blog Post" nodes. + +- **Mention tools or entities by name** +If you've enabled tools like ```document-type, media, or data-type```, refer to them directly in your prompt. This helps the model understand what it can access. + +- **Use system instructions or context files for background** +Offload rules, terminology, or structural constraints into a dedicated instruction file. This keeps prompts cleaner and context more focused. + +-- **Break up complex workflows** +Don’t try to do everything in one prompt. Sequence multi-step operations (e.g., create types → add content → apply relations) across multiple turns for better results. + +{% hint style="info" %} +If a prompt fails or produces a weak result, try these approaches. Simplify it, restate it with clearer intent, or reduce the number of active tools. +{% endhint %} \ No newline at end of file diff --git a/16/umbraco-cms/reference/developer-mcp/best-practice/creating-media.md b/16/umbraco-cms/reference/developer-mcp/best-practice/creating-media.md new file mode 100644 index 00000000000..259f0171f7c --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/best-practice/creating-media.md @@ -0,0 +1,218 @@ +--- +description: Learn how to create media items in Umbraco using the Developer MCP server +--- + +# Creating Media + +The Developer MCP server provides powerful tools for creating media items with AI agents. You can upload media from local files, remote URLs, or base64-encoded data, making it sinple to automate media management tasks. + +## Available Media Creation Tools + +The MCP server provides two primary tools for creating media: + +- **`create-media`** - Create a single media item +- **`create-media-multiple`** - Batch create up to 20 media items at once + +These tools are available when the `media` tool collection is enabled. + +## Supported Media Types + +The Developer MCP server supports all standard Umbraco media types, plus any custom media types you've defined: + +| Media Type | Description | +|-------------------|--------------------------------------------------| +| Image | Standard images with focal point and cropping | +| File | Generic file storage | +| Article | Document files | +| Audio | Audio files | +| Video | Video files | +| SVG | Vector graphics (.svg) | + +Custom media types created in your Umbraco installation are also supported and can be referenced by name. + +## Source Types + +You can create media from three different sources: + +### File Path + +Upload media from files on your local filesystem. This is the most efficient method for local files. + +**Requirements:** +- The `UMBRACO_ALLOWED_MEDIA_PATHS` environment variable must be configured with allowed directories +- File paths must be absolute paths +- Files must exist within the allowed directories + +**Example prompt:** +``` +Upload the product image bicycle.jpg as "Product Photo" +to the Products media folder +``` + +**Security Note:** The MCP server validates all file paths to prevent directory traversal attacks and ensures files are only accessed from explicitly allowed directories. + +### URL + +Download and upload media from web URLs. The MCP server fetches the content and creates the media item. + +**Requirements:** +- Valid HTTP/HTTPS URL +- Accessible resource (30-second timeout) +- Appropriate file extension or Content-Type header + +**Example prompt:** +``` +Download the image from https://example.com/images/hero.jpg and create +a media item called "Homepage Hero" +``` + +### Base64 + +Upload media from base64-encoded data. This method is suitable for small files (e.g svg) but should be used sparingly due to increased token usage. + +**Best Practices:** +- Use only for small files (under 5KB recommended) +- Prefer file path or URL methods when possible +- Base64 encoding increases the size of data sent + +**Example prompt:** +``` +Create an svg media item of a unicorn +``` + +## Configuration + +### Environment Variables + +To use file path uploads, configure the allowed directories in your MCP server environment: + +```json +{ + "umbraco-mcp": { + "command": "npx", + "args": ["@umbraco-cms/mcp-dev@beta"], + "env": { + "UMBRACO_CLIENT_ID": "your-client-id", + "UMBRACO_CLIENT_SECRET": "your-client-secret", + "UMBRACO_BASE_URL": "https://localhost:12345", + "UMBRACO_ALLOWED_MEDIA_PATHS": "/users/username/downloads", + "UMBRACO_INCLUDE_TOOL_COLLECTIONS": "media" + } + } +} +``` + +Multiple paths can be specified by separating them with commas. + +## Advanced Features + +### Automatic SVG Detection + +The MCP server automatically detects SVG files and corrects the media type from "Image" to "SVG" if needed: + +**Prompt:** +``` +Upload /Users/username/icons/logo.svg as "Company Logo" +``` + +Even if you specify "Image" as the media type, the server will automatically use "SVG" for .svg files. + +### Focal Point for Images + +Image media items are automatically created with a center focal point (0.5, 0.5). Use the update media tool to change the focal point after creation. + +### Missing File Extensions from URLs + +When downloading from URLs without file extensions, the MCP server detects the file type from the Content-Type header: + +**Prompt:** +``` +Download the image from https://api.example.com/image/123 and create +a media item +``` + +The server adds the appropriate extension based on the response headers. + + +## Usage Examples & Common Scenarios + +### Creating a Single Image + +Upload a local image file to a specific media folder: + +**Prompt:** +``` +Upload the file team-photo as "Team Photo 2024" +to the Team Photos media folder +``` + +The MCP server will: +1. Validate the file path is allowed +2. Determine the appropriate media type (Image) +3. Upload the file to Umbraco's temporary storage +4. Create the media item with correct properties +5. Clean up temporary files + +### Batch Creating Media + +Upload multiple files at once (up to 20 files per batch): + +**Prompt:** +``` +Upload all images from the product-photos folder to the +Products media folder +``` + +The MCP server processes files sequentially and provides a summary of successes and failures. Individual file errors don't stop the batch processing. + +### Creating Media from URLs + +Download and upload media from remote sources: + +**Prompt:** +``` +Download these product images and upload them to the Products folder: +- https://cdn.example.com/products/item1.jpg as "Product 1" +- https://cdn.example.com/products/item2.jpg as "Product 2" +- https://cdn.example.com/products/item3.jpg as "Product 3" +``` + +### Creating Media with Specific Types + +Explicitly specify the media type: + +**Prompt:** +``` +Upload the PDF from manual.pdf as "User Manual" +with media type "Bespoke Article" to the Documentation folder +``` + +### Migrating Media from External Sources + +Import media files from an external system: + +**Prompt:** +``` +Download all images listed in this CSV file and upload them to Umbraco with +the specified names and folder structure +``` + +### Organizing Existing Downloads + +Process files from your downloads folder: + +**Prompt:** +``` +Upload all PDF files from downloads to the Documents +media folder, using their filenames as media names +``` + +### Creating Product Media + +Set up a new product catalog with images: + +**Prompt:** +``` +Create a "Product Catalog 2024" folder and upload all images from +/Users/username/products/ into it, organizing by subfolder names +``' \ No newline at end of file diff --git a/16/umbraco-cms/reference/developer-mcp/best-practice/example-instructions.md b/16/umbraco-cms/reference/developer-mcp/best-practice/example-instructions.md new file mode 100644 index 00000000000..502c6b87281 --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/best-practice/example-instructions.md @@ -0,0 +1,72 @@ +--- +description: Get the most out of the Umbraco CMS developer MCP server +--- + +# Example instructions file + +Custom instructions help guide your AI assistant to follow your specific Umbraco development practices and conventions. By creating a instructions file in your project, you can ensure consistent behavior across all interactions with the MCP server. + +The example below demonstrates a comprehensive instruction file that covers tool usage, content structure, templates, and other best practices. The version of Umbraco (v16.2.0) is explicitly specified in the title. This helps AI assistants use version-specific documentation sources like Context7 to provide accurate guidance for your Umbraco installation. + +Created by [Tom Madden](https://github.com/TwoMoreThings) + +## Example Instruction File + +```markdown +# Umbraco Development Guidelines (v16.2.0) + +## Tool Usage + +- Use Context7 to retrieve Umbraco v16.2.0 documentation +- Use the Umbraco MCP tool for ALL Umbraco interactions - make multiple calls as needed, never try to optimize with bulk operations +- Use create-media MCP tool for media items, referencing files in wwwroot/media/my-folder + +## Content Structure + +- Always use Block List over Block Grid for composable pages +- All navigable content pages must be nested under the Home page +- All Content Type properties must belong to either a tab or a group + +## Block List Configuration + +- Items require a contentKey in UUID/GUID format + - Define labels using the Umbraco Flavored Markdown format, e.g. {umbValue: propertyAlias} (NOT {{$propertyAlias}}) + +## Templates & Content Types + +- For web page content types (non-element types): + - Create corresponding template via Management API first + - Assign template to content type + - Set as default template + +## Data Types + +- Save new Data Types in 'Custom Data Types' folder +- Use 'Rich Text Editor [Tiptap]' for formatted text content +- Use Link Picker instead of multiple TextString properties for links + +## File Handling + +- Never modify file metadata/dates (preserves Git change tracking) +- Add static assets to wwwroot subdirectories +- When downloading images, exclude favicon.png and apple-icon.png +- Look for CSS/inline style images, not just src attributes + +## Models & Publishing + +- STOP and prompt user to generate models and restart site (never generate manually) +- Verify the node Layout is set correctly when saving/publishing pages + + +## Adding New Blocks + +1. Create the content type in Umbraco backoffice (requires user interaction or the umbraco-mcp tool) +2. Models auto-generate in `Website.Core/Models/` +3. Create rendering partial in `Website.Web/Views/Partials/blockgrid/Components/` +4. Add SCSS styling in `Website.Web.Assets/Client/src/scss/blocks/` +5. Import SCSS in `Client/src/scss/blocks/_blocks.scss` +6. Add the new block to the "grid main" Block Grid Editor data type in Umbraco with appropriate label and setup for areas and resizing + +``` + +This example demonstrates how you can create project-specific guidelines that your AI assistant will follow consistently throughout your development workflow. \ No newline at end of file diff --git a/16/umbraco-cms/reference/developer-mcp/concepts/README.md b/16/umbraco-cms/reference/developer-mcp/concepts/README.md new file mode 100644 index 00000000000..3ad872f867a --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/concepts/README.md @@ -0,0 +1,13 @@ +--- +description: "Key Concepts for Getting the Most Out of AI with Umbracoo" +--- + +# Key Concepts + +## [Model Context Protocol](./concepts/model-context-protocol.md) + +What is model context protocol? + +## [Context Engineering](./concepts/context-enginerring.md) + +Introduction to context engineering. \ No newline at end of file diff --git a/16/umbraco-cms/reference/developer-mcp/concepts/context-enginerring.md b/16/umbraco-cms/reference/developer-mcp/concepts/context-enginerring.md new file mode 100644 index 00000000000..afd9fa68cff --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/concepts/context-enginerring.md @@ -0,0 +1,75 @@ +--- +description: Effective and optimal communication with LLMs +--- + +# Context engineering + +Context Engineering is the foundation of any interaction with large language models (LLMs). This practice controls how the Umbraco Developer MCP Server delivers precise, reliable, and efficient results. It shapes what the LLM sees and understands about your request to produce the best possible responses. + +## What is Context + +At its most basic level, context is the conversation between you and a tool like ChatGPT. It includes: + +- The entire message history (your inputs and the model’s outputs). + +- The most recent system and user instructions that define the current topic or task. + +![Conversation window in ChatGPT](../images/chat-gpt-conversation.png) + +LLMs are stateless — they don't support retaining information between individual requests. Each time you send a message, the entire context is sent to the model. This includes conversation history and any injected system data. + +**You can never fully control what an LLM with return. +You can influence the outcome — and context is the only way that you do that.** + +{% hint style="info" %} +The more intentional and relevant your context, the more predictable and useful the model’s output becomes. +{% endhint %} + +## What is Context Engineering + +**Context engineering** is the practice of providing the LLM with only the information it needs to produce accurate and reliable results. + +It’s about curating and managing what gets sent to the model: + +- Ensuring the context is **correct, concise, and relevant** for the current task. + +- **Avoiding information overload** — sending too much or contradictory context can confuse the model and lead to poor-quality responses or hallucinations. + +## Why Context Engineering Is So Important + +In the early days of large language models (LLMs), the context of a conversation was straightforward — only your messages and the model's responses. +Conversations were short and straightforward to follow, but even then, you could see context drift. As earlier parts of the discussion faded, the model's memory weakened and response quality declined. + +Today, however, the landscape has changed dramatically. + +Modern AI systems rely on increasingly **complex and layered context**, which include far more than only the user conversation. A single MCP-driven interaction may now contain: + +- A **system prompt** (the invisible instructions defining the model’s role and tone). +- **Rules or instruction** files that constrain or enhance model behavior. +- **MCP definitions**, which describe how external tools and data sources can be used during a conversation. + +All of these elements must fit inside the model’s **context window** — the limited amount of information the model can “see” at once. +The most advanced models today have larger but still finite context windows, so how you fill that space still matters. + +![Claude Code Context Window](../images/claude-code-context-window.png) + +If too much irrelevant, poorly structured, or contradictory information is included, useful parts of the context may get pushed out or forgotten. This leads to confusion, incomplete answers, or hallucinations. +That’s why **context engineering is more important now than ever** — it’s about managing this limited space carefully and intentionally. + +{% hint style="info" %} +Be mindful of which MCP tools you’ve added and why. Each one adds new context data that competes for space and affects how effectively the model can respond. +{% endhint %} + +## How this affects the Umbraco CMS developer MCP + +In the Umbraco CMS Developer MCP (Model Context Protocol), context engineering is applied through structured tool contexts and well-defined prompts. +This makes requests more effective, efficient, and more likely to succeed. It also makes prompts easier to write, reuse, and maintain. + +{% hint style="info" %} +Think of context engineering as the art of precision storytelling. Every piece of information you include should help the model stay on track and deliver value. +{% endhint %} + +Your choice of enabled tools directly shapes the quality of your context. +By managing which tools and tool collections are active, you control how much information is sent to the model. This improves both performance and response reliability. + +For more information, see [Tool Collections](../available-tools.md) \ No newline at end of file diff --git a/16/umbraco-cms/reference/developer-mcp/concepts/model-context-protocol.md b/16/umbraco-cms/reference/developer-mcp/concepts/model-context-protocol.md new file mode 100644 index 00000000000..5200cc02683 --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/concepts/model-context-protocol.md @@ -0,0 +1,112 @@ +--- +description: Effective and optimal communication with LLMs +--- + +# Model Context Protocol (MCP) + +**Model Context Protocol (MCP)** is a standardised way to connect Large Language Models (LLMs) with external tools, APIs, and data sources. It brings order and consistency to how LLMs interact with the outside world. This transforms complex, manual integrations into something modular and predictable. + +## The History of MCP + +MCP was developed by Anthropic and released publicly in November 2024. + +Anthropic describes it as “the USB-C of connecting to LLMs.” +Before MCP, connecting an LLM to external systems such as APIs, files, or databases was a complex and manual process. Each integration required custom glue code and inconsistent communication patterns. + +With MCP, this has changed. The protocol provides a standardised, declarative way to describe and expose capabilities. This makes it much easier for developers to connect logic and data to an LLM in a reliable, repeatable way. + +## What Is MCP + +MCP defines a structured relationship between hosts, clients, and servers. + +### Host Applications + +These are applications that implement MCP support — for example: + +- Claude Desktop and Claude Code +- Cursor +- Windsurf +- GitHub Copilot +- And many others + +The host application is where you interact with the model and manage MCP connections. It coordinates between your input, the LLM, and any connected MCP tools via the client. + +--- + +### MCP Clients + +An MCP client represents a single connection between the LLM and an MCP server. It routes information between the MCP servers and the model. It makes each MCP capability visible to the LLM. The client passes calls from the model to the correct server and returns the results back. + +In short, the client acts as the traffic controller between the model and the external systems it can interact with. + +--- + +### MCP Servers + +An MCP server defines and exposes the elements that allow the LLM to interact with external systems. + +Servers can represent: + +- APIs +- Databases +- Filesystems +- Any other external system + +A single client can connect to multiple servers, each running in parallel. For example, one server might expose Umbraco's Management API, another might provide access to a local file system. A third could connect to an external data source such as a CRM or analytics database. This allows the LLM to draw from and interact with many systems at once. All of this happens through a single, unified MCP connection. + +Each exposed element has a name, a description, and an input schema. The model uses these to understand what the MCP server element does and when to use it. + +## The Core Elements of MCP + +MCP defines three primary element types: + +**Tools** +These act like API calls, enabling the model to perform actions or trigger operations. + +**Resources** +These are read-only, parameterised calls that retrieve data to add to the LLM’s context. +They are triggered by user interaction or as part of a larger process. + +**Prompts** +These are predefined, parameterised conversations that define complex interactions with the model. +Prompts are ideal for multi-step tasks or for standardising a common process. + +## What This Means for Umbraco + +The Developer MCP Server builds on top of Umbraco's Management API (introduced in v14). This API exposes everything the Backoffice can do through consistent, structured endpoints. This includes content, media, document types, and data types. + +These APIs follow predictable patterns for CRUD operations, listings etc, making them an ideal foundation for the Model Context Protocol (MCP). + +However, the Backoffice UI can only ever expose a fraction of the functionality that the Management API makes possible. It’s designed for day-to-day content management — not for executing complex, multi-step operations that span across entities or require dynamic logic. Many advanced or edge case workflows are often too specialised, too costly, or too confusing to implement in the UI. + +By giving an LLM or AI agent access to these APIs through MCP, you can now ask it to perform powerful, compound tasks. These tasks would be impossible in the Backoffice and impractical to achieve manually. + +MCP turns Umbraco's structured API surface into something the model can read from, reason about, and automate. This unlocks the full depth of Umbraco's capabilities, not only the parts surfaced through the UI. + +{% hint style="info" %} +MCP is not a replacement for the Umbraco Backoffice. Many actions are best completed using the UI. This includes visual content design, layout composition, and structured editing. +Instead, the Developer MCP Server augments the Backoffice. It empowers you to run complex, technical operations that are better expressed as goals or workflows rather than manual clicks. +{% endhint %} + +MCP exposes the Management API as composable tools. This means the model can chain endpoints in an unlimited number of combinations to solve real-world tasks. You describe the outcome you want, and the model figures out how to get there. + +For example: + +- **Bulk content operations** – Identify, update, and republish hundreds of nodes programmatically. +- **Media automation** – Rename, categorise, and relocate assets based on metadata or folder structure. +- **Schema scaffolding** – Generate or manage document types and data types directly from a prompt. +- **Maintenance** – Reorganise into folders, standardise naming conventions or tidy up accumulated technical debt. +- **Reporting** – Extract and analyze content patterns, audit site structure, or generate usage reports across your entire site. +- [**Plus many, many more**](../scenarios.md) + +This represents a fundamental shift in how you build with Umbraco. + +You’ve always had access to the Management API — but using it directly meant writing custom scripts or tooling. Now, with MCP, the model (or an agent) can dynamically plan and execute API calls on your behalf. + +It looks like magic — but it's really purely tool orchestration. The LLM figures out what to call, when, and why. It bases this on the tools it's been given and the goal you've described. + +The only limit is your imagination. If you can explain what you want, an LLM that understands Umbraco can figure out how to make it happen. This assumes it has the right MCP tools available. + +## The LLM as a Collaborator + +Beyond automation, MCP enables you to leverage the expertise of the LLM as an intelligent contributor to your Umbraco project. Instead of merely executing tasks, the model can assist in planning schema changes, refactoring document types, improving naming conventions, and proposing best practices. All of this is based on a deep understanding of the CMS. It can help you migrate, restructure, and optimise your setup, reducing manual effort while increasing technical quality. With the Developer MCP Server, the LLM becomes more than a command executor — it becomes a **collaborative development partner**. \ No newline at end of file diff --git a/16/umbraco-cms/reference/developer-mcp/configuration.md b/16/umbraco-cms/reference/developer-mcp/configuration.md new file mode 100644 index 00000000000..2d51d4182e8 --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/configuration.md @@ -0,0 +1,107 @@ +--- +description: Configuration options for the Developer MCP server +--- + +# Configration Options + +The Developer MCP Server can be configured in mutliple ways to manage authentication, tool access, and security settings. These settings control how the server connects to Umbraco and how it operates within your development environment. Configuration can be applied using configuration keys, environment variables, or CLI arguments, depending on your workflow. + +## Configuration Keys + +### Authentication Configuration Keys + +| Key | Description | +| --- | --- | +| `UMBRACO_CLIENT_ID` | The username of the Umbraco API user. | +| `UMBRACO_CLIENT_SECRET` | The client secret for the Umbraco API user. | +| `UMBRACO_BASE_URL` | The base URL of your Umbraco instance (e.g. `https://localhost:44391`). | +| `NODE_TLS_REJECT_UNAUTHORIZED` | Set to `"0"` to disable TLS certificate validation when connecting to HTTP URLs or self-signed certificates. | + +{% hint style="warning" %} +If you are connecting to the secure endpoint of Umbraco locally then **always** set the NODE_TLS_REJECT_UNAUTHORIZED to 0 +{% endhint %} + +### Tool and Tool Collection configuration + +| Key | Description | +| --- | --- | +| `UMBRACO_EXCLUDE_TOOLS` | Specifies tool names to **exclude** from the usable tools list. Useful when certain agents cannot handle a large number of tools. | +| `UMBRACO_INCLUDE_TOOLS` | Specifies tool names to **include** in the usable tools list. When defined, **only** these tools will be available. | +| `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. | + +{% 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 + +When configuring tools for the Developer MCP Server, you can fine-tune which tools and collections are available by using comma-separated values. + +- **Comma-delimited configuration** +Tools and tool collections are specified using a comma-separated list. +For example: +```bash +UMBRACO_INCLUDE_TOOL_COLLECTIONS="document,document-type,data-type" +``` + +- **Combining tool configurations** +You can combine configuration options to include entire tool collections while excluding specific tools. +For example, you might enable the document and media collections but exclude a single tool within them. + +```bash +UMBRACO_INCLUDE_TOOL_COLLECTIONS="document,media" +UMBRACO_EXCLUDE_TOOLS="document-move,media-delete" +``` + +### Security Configuration Keys + +| Key | Description | +| --- | --- | +| `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. +{% endhint %} + + +## Environment Configuration Options + +The **Umbraco Developer MCP Server** supports configuration through multiple methods, allowing flexibility across different environments and workflows: + +1. **Environment variables** defined in the MCP client configuration (e.g., Claude Desktop, Visual Studio Code, Cursor) +2. A local **`.env` file** for development +3. **CLI arguments** when running the MCP Server directly + +**Configuration precedence:** +`CLI arguments` → `Environment variables` → `.env` file + +--- + +### Using a `.env` File (Recommended for Development) + +For local development, create a `.env` file in your project root directory and set your connection details: + +```bash +# Example .env configuration +UMBRACO_CLIENT_ID=your-api-user-id +UMBRACO_CLIENT_SECRET=your-api-secret +UMBRACO_BASE_URL=http://localhost:56472 +UMBRACO_INCLUDE_TOOL_COLLECTIONS=document,media,document-type,data-type +``` + +{% hint style="info" %} +The .env file is included in .gitignore by default to prevent sensitive credentials from being committed to source control. +{% endhint %} + +### Using CLI Arguments + +You can also provide configuration values directly via CLI arguments, which override any .env or environment variable settings: + +```bash +npx @umbraco-cms/mcp-dev@beta \ + --umbraco-client-id="your-id" \ + --umbraco-client-secret="your-secret" \ + --umbraco-base-url="http://localhost:56472" \ + --env="/path/to/custom/.env" +``` \ No newline at end of file diff --git a/16/umbraco-cms/reference/developer-mcp/excluded-tools.md b/16/umbraco-cms/reference/developer-mcp/excluded-tools.md new file mode 100644 index 00000000000..c3197f801c9 --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/excluded-tools.md @@ -0,0 +1,131 @@ +--- +description: The tools that have been excluded from the Developer MCP +--- + +# Excluded tools + +Certain endpoints are intentionally not implemented due to security, complexity, or contextual concerns. + +### Excluded Groups Summary + +- **User Management (22 endpoints)** - User creation/deletion, password operations, 2FA management, and client credentials pose significant security risks +- **User Group Membership (3 endpoints)** - Permission escalation risks from AI-driven group membership changes +- **Security Operations (4 endpoints)** - Password reset workflows require email verification and user interaction +- **Import/Export (9 endpoints)** - Complex file operations better handled through the Umbraco UI +- **Package Management (9 endpoints)** - Package creation and migration involve system-wide changes +- **Cache Operations (3 endpoints)** - Cache rebuild can impact system performance +- **Telemetry (3 endpoints)** - System telemetry configuration and data collection +- **Install/Upgrade (5 endpoints)** - One-time system setup and upgrade operations +- **Preview/Profiling (4 endpoints)** - Frontend-specific debugging functionality +- **Other (7 endpoints)** - Internal system functionality, oEmbed, dynamic roots, object types + + +## Ignored Endpoints + +These endpoints are intentionally not implemented in the MCP server, typically because they: +- Are related to import/export functionality that may not be suitable for MCP operations +- Have security implications +- Are not applicable in the MCP context + +## Ignored by Category + +### DocumentType (3 endpoints) +- `getDocumentTypeByIdExport` - Export functionality +- `postDocumentTypeImport` - Import functionality +- `putDocumentTypeByIdImport` - Import functionality + +### Dictionary (2 endpoints) +- `getDictionaryByIdExport` - Export functionality +- `postDictionaryImport` - Import functionality + +### MediaType (3 endpoints) +- `getMediaTypeByIdExport` - Export functionality +- `postMediaTypeImport` - Import functionality +- `putMediaTypeByIdImport` - Import functionality + +### Import (1 endpoint) +- `getImportAnalyze` - Import analysis functionality + +### Install (3 endpoints) +- `getInstallSettings` - Installation configuration settings (system setup concerns) +- `postInstallSetup` - System installation functionality (system modification risk) +- `postInstallValidateDatabase` - Database validation during installation (system setup concerns) + +### Package (9 endpoints) +- `deletePackageCreatedById` - Delete created package functionality +- `getPackageConfiguration` - Package configuration settings +- `getPackageCreated` - List created packages functionality +- `getPackageCreatedById` - Get created package by ID functionality +- `getPackageCreatedByIdDownload` - Download package functionality +- `getPackageMigrationStatus` - Package migration status functionality +- `postPackageByNameRunMigration` - Run package migration functionality +- `postPackageCreated` - Create package functionality +- `putPackageCreatedById` - Update created package functionality + +### Security (4 endpoints) +- `getSecurityConfiguration` - Security configuration settings +- `postSecurityForgotPassword` - Password reset functionality +- `postSecurityForgotPasswordReset` - Password reset confirmation functionality +- `postSecurityForgotPasswordVerify` - Password reset verification functionality + +### User Group (3 endpoints) +- `deleteUserGroupByIdUsers` - Remove users from groups (permission escalation risk) +- `postUserGroupByIdUsers` - Add users to groups (permission escalation risk) +- `postUserSetUserGroups` - Set user's group memberships (permission escalation risk) + +### Telemetry (3 endpoints) +- `getTelemetry` - System telemetry data collection (privacy concerns) +- `getTelemetryLevel` - Telemetry configuration exposure (privacy concerns) +- `postTelemetryLevel` - Telemetry settings modification (privacy concerns) + +### PublishedCache (3 endpoints) +- `getPublishedCacheRebuildStatus` - Cache rebuild status monitoring (system performance concerns) +- `postPublishedCacheRebuild` - Cache rebuild operations (system performance/stability risk) +- `postPublishedCacheReload` - Cache reload operations (system performance/stability risk) + +### Upgrade (2 endpoints) +- `getUpgradeSettings` - System upgrade configuration settings (system setup concerns) +- `postUpgradeAuthorize` - System upgrade authorization functionality (system modification risk) + +### User (22 endpoints) +- `postUser` - User creation functionality (account proliferation/privilege escalation risk) +- `deleteUser` - User deletion functionality (denial of service/data loss risk) +- `deleteUserById` - User deletion by ID functionality (denial of service/data loss risk) +- `putUserById` - User update functionality (permission escalation/authentication bypass risk) +- `postUserByIdChangePassword` - Password change functionality (security risk) +- `postUserByIdResetPassword` - Password reset functionality (security risk) +- `postUserCurrentChangePassword` - Current user password change (security risk) +- `postUserByIdClientCredentials` - Client credentials management (security risk) +- `getUserByIdClientCredentials` - Client credentials exposure (security risk) +- `deleteUserByIdClientCredentialsByClientId` - Client credentials manipulation (security risk) +- `getUserById2fa` - 2FA management (security risk) +- `deleteUserById2faByProviderName` - 2FA bypass risk (security risk) +- `getUserCurrent2fa` - 2FA exposure (security risk) +- `deleteUserCurrent2faByProviderName` - 2FA bypass risk (security risk) +- `postUserCurrent2faByProviderName` - 2FA manipulation (security risk) +- `getUserCurrent2faByProviderName` - 2FA exposure (security risk) +- `postUserInvite` - User invitation abuse potential (security risk) +- `postUserInviteCreatePassword` - Invitation hijacking risk (security risk) +- `postUserInviteResend` - Spam/abuse potential (security risk) +- `postUserInviteVerify` - Invitation manipulation (security risk) +- `postUserDisable` - User account lockout risk (security risk) +- `postUserEnable` - Compromised account activation risk (security risk) +- `postUserUnlock` - Account security bypass risk (security risk) + +### Profiling (2 endpoints) +- `getProfilingStatus` - System profiling status monitoring (system performance/debugging concerns) +- `putProfilingStatus` - System profiling configuration changes (system performance/stability risk) + +### Preview (2 endpoints) +- `deletePreview` - Content preview deletion (frontend-specific functionality) +- `postPreview` - Content preview creation (frontend-specific functionality) + +### Oembed (1 endpoint) +- `getOembedQuery` - oEmbed media embedding functionality (frontend-specific functionality) + +### Object (1 endpoint) +- `getObjectTypes` - System object type enumeration (internal system functionality) + +### Dynamic (2 endpoints) +- `getDynamicRootSteps` - Dynamic root configuration steps (advanced configuration functionality) +- `postDynamicRootQuery` - Dynamic root query processing (advanced configuration functionality) \ No newline at end of file diff --git a/16/umbraco-cms/reference/developer-mcp/host-setup/README.md b/16/umbraco-cms/reference/developer-mcp/host-setup/README.md new file mode 100644 index 00000000000..97d74cbe31b --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/host-setup/README.md @@ -0,0 +1,21 @@ +--- +description: "Specific setup for different AI applications" +--- + +# Current Hosts + +## [Claude Desktop](./claude-desktop.md) + +Getting started with Claude Desktop + +## [Claude Code](./claude-code.md) + +Getting started with Claude Code + +## [Cursor](./cursor.md) + +Getting started with Cursor + +## [GitHub Copilot](./github-copilot.md) + +Getting started with GitHub Copilot diff --git a/16/umbraco-cms/reference/developer-mcp/host-setup/claude-code.md b/16/umbraco-cms/reference/developer-mcp/host-setup/claude-code.md new file mode 100644 index 00000000000..cc54bc6d98d --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/host-setup/claude-code.md @@ -0,0 +1,94 @@ +--- +description: "Host set up for Claude Code" +--- + +# Claude Code Setup + +[Claude Code](https://www.claude.com/product/claude-code) is a developer-focused agentic CLI (command line interface) tool from Anthropic. It integrates Claude's large language models (LLMs) directly into your terminal window. This allows you to explore, refactor, and generate code within your projects. + +## Getting started + +Install Claude Code globally + +```bash +npm install -g @anthropic-ai/claude-code +``` + +### Configuration using the CLI tool + +Basic install + +```bash +claude mcp add umbraco-mcp npx @umbraco-cms/mcp-dev@beta +``` + +If you prefer to define configuration values directly, use the following pattern: + +```bash + +# Add with environment variables +claude mcp add umbraco-mcp --env UMBRACO_CLIENT_ID="your-id" --env UMBRACO_CLIENT_SECRET="your-secret" --env UMBRACO_BASE_URL="https://your-domain.com" --env NODE_TLS_REJECT_UNAUTHORIZED="0" --env UMBRACO_INCLUDE_TOOL_COLLECTIONS="document,media,document-type,data-type" -- npx @umbraco-cms/mcp-dev@beta +``` + +Replace the UMBRACO_CLIENT_ID, UMBRACO_CLIENT_SECRET, UMBRACO_BASE_URL and UMBRACO_INCLUDE_TOOL_COLLECTIONS values with your local connection details. + +This will add the MCP server as umbraco-mcp in your project’s claude.json configuration file. + +{% hint style="info" %} +Use the command + +``` +claude mcp list +``` + +anytime to confirm which MCP servers are active in your Claude Code environment. +{% endhint %} + +### Configuration via .mcp.json (Project-specific) + +This is the perferred configuration for Claude Code. +As project-level configuration, create a .mcp.json file in your project root. + +Using the `.mcp.json` file allows you to: +- Configure MCP servers per project +- Share configuration safely with team members +- Override global Claude Code MCP settings +- Use an .env file to prevent secrets being added to source + +Example .env file + +```bash +UMBRACO_CLIENT_ID=umbraco-back-office-mcp +UMBRACO_CLIENT_SECRET=1234567890 +UMBRACO_BASE_URL=http://localhost:123456 +UMBRACO_INCLUDE_TOOL_COLLECTIONS=document,media,document-type,data-type +``` + +Replace the UMBRACO_CLIENT_ID, UMBRACO_CLIENT_SECRET, UMBRACO_BASE_URL and UMBRACO_INCLUDE_TOOL_COLLECTIONS values with your local connection details. + +Example .mcp.json file + +```json +{ + "mcpServers": { + "umbraco-mcp": { + "command": "npx", + "args": ["@umbraco-cms/mcp-dev@beta"], + } + } +} +``` + +For details on .env format and supported configuration keys, see the [Configuration guide](../configuration.md). + +{% hint style="warning" %} +Never commit live credentials to source control. Always use environment variables or a .env file. +{% endhint %} + +## Easier tool and tool collection management + +Another benefit of using a .env file for configuration is that it makes it much easier to adjust tool configurations for different tasks. +Claude Code lets you quickly reconnect to an MCP server using its slash commands. This allows you to switch environments or update settings without editing your main configuration files. + +- Update the .env file with the new tools set +- In Claude Code CLI use **/mcp reconnect umbraco-mcp** to restart the mcp server diff --git a/16/umbraco-cms/reference/developer-mcp/host-setup/claude-desktop.md b/16/umbraco-cms/reference/developer-mcp/host-setup/claude-desktop.md new file mode 100644 index 00000000000..837a47235c8 --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/host-setup/claude-desktop.md @@ -0,0 +1,59 @@ +--- +description: "Host set up for Claude Desktop" +--- + +# Claude Desktop Setup + +[Claude Desktop](https://www.anthropic.com/claude/desktop) is Anthropic's AI-powered assistant for macOS and Windows. It is designed to help you work conversationally across all kinds of tasks — from writing and brainstorming to coding and automation. + +## Getting started + +First download and install the [Claude.ai desktop app](https://claude.ai/download). + +To edit the MCP settings, go to Settings → Developer → Edit Config. + +![MCP Panel](../images/Claude%20Desktop.png) + +Open the JSON configuration file in your preferred text editor and add the following snippet. + +```bash +{ + "mcpServers": + { + "umbraco-mcp": + { + "command": "npx", + "args": ["@umbraco-cms/mcp-dev@beta"], + "env": + { + "NODE_TLS_REJECT_UNAUTHORIZED": "0", + "UMBRACO_CLIENT_ID": "umbraco-back-office-mcp", + "UMBRACO_CLIENT_SECRET": "1234567890", + "UMBRACO_BASE_URL": "https://localhost:12345", + "UMBRACO_INCLUDE_TOOL_COLLECTIONS": "document,media,document-type,data-type" + } + } + } +} +``` + +Replace the UMBRACO_CLIENT_ID, UMBRACO_CLIENT_SECRET, and UMBRACO_BASE_URL values with your local connection details. + +Restart Claude to activate the new configuration. + +If you encounter a connection error, open the logs and review the file named mcp-server-umbraco-mcp.log. This file contains details on how to resolve the issue. + +{% hint style="info" %} +A paid version of Claude.ai will have a higher token limit and will be able to run more complex prompts. +{% endhint %} + +From here, you should [choose which tools or tool collections](../available-tools.md) you want to enable for your first task. +You will need to restart Claude Desktop every time you make a change to the tools you are using. + +## Node version mismatch + +Occasionally, Claude Desktop may choose to use the wrong version of Node.js when running the MCP Server. +A minimum of Node.js version 22 is required. This issue most commonly occurs when using a Node.js version manager such as nvm. Claude Desktop can sometimes default to the lowest installed version rather than the active one set by nvm. + +The only reliable fix for this is to remove all older Node.js versions, leaving only version 22 or higher installed. +This behaviour appears to be specific to Claude Desktop and does not affect any other AI hosts. diff --git a/16/umbraco-cms/reference/developer-mcp/host-setup/cursor.md b/16/umbraco-cms/reference/developer-mcp/host-setup/cursor.md new file mode 100644 index 00000000000..ebb068acd82 --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/host-setup/cursor.md @@ -0,0 +1,44 @@ +--- +description: "Host set up for Cursor" +--- + +# Cursor Setup + +[Cursor](https://cursor.com/) is an AI-powered code editor built as a fork of Visual Studio Code. It enhances the familiar Visual Studio Code experience with conversational AI features that help you write, refactor, and understand code more efficiently. + +## Getting started + +Go to `Cursor Settings` -> `Tools & MCP` -> `Add Custom MCP`. + +![MCP Panel](../images/Cursor-MCP.png) + +Add the following to the config file. + +```json +{ + "mcpServers": { + "umbraco-mcp": { + "command": "npx", + "args": ["@umbraco-cms/mcp-dev@beta"], + "env": { + "NODE_TLS_REJECT_UNAUTHORIZED": "0", + "UMBRACO_CLIENT_ID": "umbraco-back-office-mcp", + "UMBRACO_CLIENT_SECRET": "1234567890", + "UMBRACO_BASE_URL": "https://localhost:12345", + "UMBRACO_INCLUDE_TOOL_COLLECTIONS": "document,media,document-type,data-type" + } + } + } +} +``` + +Replace the UMBRACO_CLIENT_ID, UMBRACO_CLIENT_SECRET, and UMBRACO_BASE_URL values with your local connection details. + +![MCP Panel Added](../images/Cursor-MCP-Added.png) + +The warning above indicating that the number of tools exceeds the limit is expected behaviour. +From here, you should [choose which tools or tool collections](../mcp-toolkit.md) you want to enable for your first task. + +{% hint style="info" %} +Selecting only the tools you need helps keep your setup efficient and conversations with your AI assistant more focused. +{% endhint %} \ No newline at end of file diff --git a/16/umbraco-cms/reference/developer-mcp/host-setup/github-copilot.md b/16/umbraco-cms/reference/developer-mcp/host-setup/github-copilot.md new file mode 100644 index 00000000000..ad02b58bedb --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/host-setup/github-copilot.md @@ -0,0 +1,31 @@ +--- +description: "Host set up for GitHub Copilot" +--- + +# GitHub Copilot Setup + +[GitHub Copilot](https://github.com/features/copilot) is an AI-powered coding assistant developed by GitHub and OpenAI. It works as an extension to Visual Studio Code, enhancing your editor with intelligent code suggestions and natural language capabilities. + +## Getting started + +#### Click the button to install +[Install in Visual Studio Code](https://insiders.vscode.dev/redirect?url=vscode%3Amcp%2Finstall%3F%7B%22name%22%3A%22umbraco-mcp%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22%40umbraco-cms%2Fmcp-dev%40beta%22%5D%2C%22env%22%3A%7B%22NODE_TLS_REJECT_UNAUTHORIZED%22%3A%220%22%2C%22UMBRACO_CLIENT_ID%22%3A%22%3CAPI%20user%20name%3E%22%2C%22UMBRACO_CLIENT_SECRET%22%3A%22%3CAPI%20client%20secert%3E%22%2C%22UMBRACO_BASE_URL%22%3A%22https%3A%2F%2F%3Cdomain%3E%22%2C%22UMBRACO_INCLUDE_TOOL_COLLECTIONS%22%3A%22document%2Cmedia%2Cdocument-type%2Cdata-type%22%7D%7D) + +**Requirements:** Visual Studio Code 1.101+ with GitHub Copilot Chat extension installed. + +Or install manually: +Follow the MCP [install guide](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_add-an-mcp-server), use this config. + +Don't forget to replace the UMBRACO_CLIENT_ID, UMBRACO_CLIENT_SECRET, and UMBRACO_BASE_URL values with your local connection details. + +## Getting started + +Once you’ve added your MCP Server and updated the JSON configuration, restarting and managing the server is straightforward. + +![MCP Control](../images/GitHub%20Coplot.png) + +{% hint style="info" %} +Restarting the MCP Server applies any configuration or tool changes immediately without needing to reinstall or re-add the server. +{% endhint %} + +From here, you should [choose which tools or tool collections](../mcp-toolkit.md) you want to enable for your first task. \ No newline at end of file diff --git a/16/umbraco-cms/reference/developer-mcp/images/Claude Desktop.png b/16/umbraco-cms/reference/developer-mcp/images/Claude Desktop.png new file mode 100644 index 00000000000..c204e6a6943 Binary files /dev/null and b/16/umbraco-cms/reference/developer-mcp/images/Claude Desktop.png differ diff --git a/16/umbraco-cms/reference/developer-mcp/images/Cursor-MCP-Added.png b/16/umbraco-cms/reference/developer-mcp/images/Cursor-MCP-Added.png new file mode 100644 index 00000000000..74feed19024 Binary files /dev/null and b/16/umbraco-cms/reference/developer-mcp/images/Cursor-MCP-Added.png differ diff --git a/16/umbraco-cms/reference/developer-mcp/images/Cursor-MCP.png b/16/umbraco-cms/reference/developer-mcp/images/Cursor-MCP.png new file mode 100644 index 00000000000..9e2a93734b3 Binary files /dev/null and b/16/umbraco-cms/reference/developer-mcp/images/Cursor-MCP.png differ diff --git a/16/umbraco-cms/reference/developer-mcp/images/GitHub Coplot.png b/16/umbraco-cms/reference/developer-mcp/images/GitHub Coplot.png new file mode 100644 index 00000000000..90d6e47bf83 Binary files /dev/null and b/16/umbraco-cms/reference/developer-mcp/images/GitHub Coplot.png differ diff --git a/16/umbraco-cms/reference/developer-mcp/images/chat-gpt-conversation.png b/16/umbraco-cms/reference/developer-mcp/images/chat-gpt-conversation.png new file mode 100644 index 00000000000..d7691cf3028 Binary files /dev/null and b/16/umbraco-cms/reference/developer-mcp/images/chat-gpt-conversation.png differ diff --git a/16/umbraco-cms/reference/developer-mcp/images/claude-code-context-window.png b/16/umbraco-cms/reference/developer-mcp/images/claude-code-context-window.png new file mode 100644 index 00000000000..ca446de7dee Binary files /dev/null and b/16/umbraco-cms/reference/developer-mcp/images/claude-code-context-window.png differ diff --git a/16/umbraco-cms/reference/developer-mcp/scenarios.md b/16/umbraco-cms/reference/developer-mcp/scenarios.md new file mode 100644 index 00000000000..072eeb7ddb2 --- /dev/null +++ b/16/umbraco-cms/reference/developer-mcp/scenarios.md @@ -0,0 +1,580 @@ +--- +description: Common useful scenarios for the developer MCP +--- + +# Use cases + +This document provides practical examples of how to use the Developer MCP for common Umbraco tasks. +Each scenario includes example prompts that demonstrate how to accomplish real-world operations using the available MCP tools. + +## Table of Contents + +- [Content Management Automation](#content-management-automation) +- [Media Management](#media-management) +- [Site Structure & Configuration](#site-structure--configuration) +- [Development & DevOps](#development--devops) +- [Monitoring & Maintenance](#monitoring--maintenance) +- [User & Permissions Management](#user--permissions-management) +- [Content Analysis & Reporting](#content-analysis--reporting) +- [Multi-language & Localization](#multi-language--localization) +- [Advanced Workflows](#advanced-workflows) +- [API & Integration Use Cases](#api--integration-use-cases) +--- + +## Content Management Automation + +1. **Bulk Content Creation** + - Automatically create multiple documents from CSV/JSON/MD data together with the Filesystem MCP + + **Example Prompt:** "Read blog-posts.csv and create a Blog Post document for each row under /blog" + + **Required Tool Collections:** `document`, `document-type` + + - Generate landing pages from templates with dynamic content + + **Example Prompt:** "Read cities.csv and create city landing pages using the City Landing Page Document Type for each UK city" + + **Required Tool Collections:** `document`, `document-type` + + - Import product catalogs into Umbraco document structure + + **Example Prompt:** "Import the product catalog from catalog.json and create the appropriate document hierarchy" + + **Required Tool Collections:** `document`, `document-type` + + - Create multi-language content variants programmatically + + **Example Prompt:** "For all documents under /news, create German and French language variants with placeholder content" + + **Required Tool Collections:** `document`, `language` + +2. **Content Migration & Synchronization** + - Migrate content from external CMS to Umbraco + + **Example Prompt:** "Import all blog posts from the WordPress export file and create them as Blog Post documents" + + **Required Tool Collections:** `document`, `document-type` + + - Sync content between staging and production environments + + **Example Prompt:** "Compare the /products section between staging and production and show me what's different" + + **Required Tool Collections:** `document` + + - Create document blueprints from existing successful pages + + **Example Prompt:** "Analyze the top 10 performing blog posts and create blueprints based on their structure and content patterns" + + **Required Tool Collections:** `document`, `document-blueprint` + + - Copy and adapt content structures across sites + + **Example Prompt:** "Copy the entire /services structure to /solutions, but update all 'service' terminology to 'solution', fix internal links, and update the navigation metadata" + + **Required Tool Collections:** `document` + +3. **Publishing Workflows** + - Schedule bulk publishing of seasonal content + + **Example Prompt:** "Find all documents tagged 'Christmas Campaign' and publish them all at once" + + **Required Tool Collections:** `document`, `tag` + + - Publish document hierarchies with descendants + + **Example Prompt:** "Publish all pages under /summer-2025 that have a publishDate in the past and are still in draft, including all their child pages" + + **Required Tool Collections:** `document` + + - Auto-publish time-sensitive content (events, promotions) + + **Example Prompt:** "Find all Event documents where eventDate is in the next 48 hours and publish them if they're in draft" + + **Required Tool Collections:** `document` + + - Content Review Reminders: Identify stale content needing updates + + **Example Prompt:** "List all published documents that haven't been updated in over 12 months" + + **Required Tool Collections:** `document` + +4. **Content Quality Validation Pipeline** + - Run automated content checks (spell check, SEO validation, broken links) + + **Example Prompt:** "Check all Blog Post documents and report any with titles over 60 characters or missing meta descriptions" + + **Required Tool Collections:** `document`, `document-type` + + - Validate required fields and metadata completeness + + **Example Prompt:** "Audit all Product documents and show me which ones are missing required fields like price or category" + + **Required Tool Collections:** `document`, `document-type` + + - Check content against brand guidelines and style rules + + **Example Prompt:** "Find all pages where the main heading doesn't follow our title case convention" + + **Required Tool Collections:** `document` + + - Ensure all media references are valid and optimized + + **Example Prompt:** "Check all documents for broken media references and list any images over 2MB" + + **Required Tool Collections:** `document`, `media` + +## Media Management + +5. **Asset Management** + - Batch upload media files from local directories + + **Example Prompt:** "Upload all images from the /downloads/product-photos folder to the Product Images media folder" + + **Required Tool Collections:** `media`, `temporary-file` + + - Organize media into folder structures programmatically + + **Example Prompt:** "Move all media items tagged 'press-kit-2024' into a new folder called Press/2024" + + **Required Tool Collections:** `media` + + - Audit and optimize media file sizes + + **Example Prompt:** "Find all images in the Team Photos folder and create a report showing their dimensions, file sizes, and which pages use them" + + **Required Tool Collections:** `media` + + - Track and audit media usage across content + + **Example Prompt:** "Show me which documents are using the hero-banner.jpg image" + + **Required Tool Collections:** `media` + + - Identify and clean up unused media assets + + **Example Prompt:** "Find all media items that aren't referenced by any published content" + + **Required Tool Collections:** `media` + +6. **Media Integration** + - Upload media from web URLs + + **Example Prompt:** "Download all the product images from these URLs and upload them to the Products media folder with appropriate naming" + + **Required Tool Collections:** `media`, `temporary-file` + + - Process and upload user-generated content + + **Example Prompt:** "Upload the submitted testimonial photos and link them to the corresponding Testimonial documents" + + **Required Tool Collections:** `media`, `temporary-file` + + - Create media with proper metadata and tags + + **Example Prompt:** "Upload these images and automatically tag them based on their filenames" + + **Required Tool Collections:** `media` + + - Manage media references and dependencies + + **Example Prompt:** "Update all references to old-logo.png to use new-logo.png instead" + + **Required Tool Collections:** `media` + +## Site Structure & Configuration + +7. **Document Type Management** + - Create document types from JSON schemas + + **Example Prompt:** "Create a new FAQ Page Document Type with a title, rich text intro, and repeatable FAQ items block list" + + **Required Tool Collections:** `document-type` + + - Update property configurations across multiple types + + **Example Prompt:** "Add a 'Last Reviewed Date' property to all document types that have the SEO composition" + + **Required Tool Collections:** `document-type` + + - Manage compositions and inheritance structures + + **Example Prompt:** "Create a Social Media composition with Open Graph properties and apply it to all page types" + + **Required Tool Collections:** `document-type` + + - Generate element types for Block List/Grid configurations + + **Example Prompt:** "Create element types for Call To Action, Image Gallery, and Video blocks" + + **Required Tool Collections:** `document-type` + +8. **Data Type Administration** + - Create custom Data Types with specific property editors + + **Example Prompt:** "Create a color picker Data Type limited to our brand colors: #FF0000, #00FF00, #0000FF" + + **Required Tool Collections:** `data-type` + + - Update Data Type configurations globally + + **Example Prompt:** "Update the Rich Text Editor Data Type to enable the source code button" + + **Required Tool Collections:** `data-type` + + - Find and manage Data Type references + + **Example Prompt:** "Show me all document types using the 'Legacy Rich Text' Data Type" + + **Required Tool Collections:** `data-type`, `document-type` + + - Migrate between different property editor configurations + + **Example Prompt:** "Update all properties using the old Media Picker to use the new Media Picker 3" + + **Required Tool Collections:** `data-type` + + - Standardize property appearance settings + + **Example Prompt:** "Update all Rich Text Editor properties across all document types to use 'Label above' appearance" + + **Required Tool Collections:** `document-type` + +9. **Template Management** + - Execute template queries to test content rendering + + **Example Prompt:** "Test render the /products/widget-pro page using the Product Detail template" + + **Required Tool Collections:** `template`, `document` + + - Search and update template code + + **Example Prompt:** "Find all templates that reference the old ViewHelper and update them to use the new one" + + **Required Tool Collections:** `template` + +## Development & DevOps + +10. **CI/CD Integration** + - Export/import Document Type definitions for version control + + **Example Prompt:** "Export all Document Type definitions to JSON files for commit to our repo" + + **Required Tool Collections:** `document-type` + + - Automate environment setup and configuration + + **Example Prompt:** "Set up the Document Type structure from our schema files in this fresh Umbraco instance" + + **Required Tool Collections:** `document-type` + + - Deploy content structure changes across environments + + **Example Prompt:** "Compare Document Types between dev and staging and generate a migration plan" + + **Required Tool Collections:** `document-type` + + - Validate content before deployment + + **Example Prompt:** "Check that all required Document Types exist before deploying content" + + **Required Tool Collections:** `document-type` + +11. **Code Generation** + - Trigger Models Builder to generate strongly-typed models + + **Example Prompt:** "Regenerate all ModelsBuilder models after the Document Type changes" + + **Required Tool Collections:** `models-builder` + + - Create scripts and stylesheets programmatically + + **Example Prompt:** "Create a new stylesheet called ```landing-page.css``` with our standard structure" + + **Required Tool Collections:** `stylesheet`, `script` + + - Generate partial views from templates + + **Example Prompt:** "Create partial views for each of our navigation components" + + **Required Tool Collections:** `partial-view` + + - Automate boilerplate code creation + + **Example Prompt:** "Generate a surface controller template for handling form submissions" + + **Required Tool Collections:** `template` + +## Monitoring & Maintenance + +12. **Health Monitoring** + - Run system health checks programmatically + + **Example Prompt:** "Run all health checks and report any that are in warning or error state" + + **Required Tool Collections:** `health` + + - Monitor server status and performance + + **Example Prompt:** "Check the server status and tell me if there are any performance issues" + + **Required Tool Collections:** `server` + + - Execute remedial actions for issues + + **Example Prompt:** "If the HTTPS check fails, show me the current configuration and suggest fixes" + + **Required Tool Collections:** `health` + + - Track system diagnostics and troubleshooting data + + **Example Prompt:** "Generate a diagnostic report for our support ticket including all health check results" + + **Required Tool Collections:** `health`, `server` + +13. **Log Analysis** + - Search and filter log entries + + **Example Prompt:** "Show me all error log entries from the last 24 hours" + + **Required Tool Collections:** `log-viewer` + + - Create saved searches for common issues + + **Example Prompt:** "Create a saved search for all SQL timeout errors" + + **Required Tool Collections:** `log-viewer` + + - Monitor error patterns and trends + + **Example Prompt:** "Find the most common error messages in the past week" + + **Required Tool Collections:** `log-viewer` + + - Generate reports from log data + + **Example Prompt:** "Create a summary report of all errors grouped by message type" + + **Required Tool Collections:** `log-viewer` + +14. **Search & Indexing** + - Rebuild search indexes automatically + + **Example Prompt:** "Rebuild the external search index" + + **Required Tool Collections:** `indexer` + + - Query content using custom searchers + + **Example Prompt:** "Search for all documents containing 'sustainability' using the external index" + + **Required Tool Collections:** `searcher` + + - Monitor index status and health + + **Example Prompt:** "Check if all Examine indexes are healthy and report any issues" + + **Required Tool Collections:** `indexer` + + - Optimize search performance + + **Example Prompt:** "Show me which indexes are largest and might need optimization" + + **Required Tool Collections:** `indexer` + +## User & Permissions Management + +15. **User Group Administration** + - Create and configure user groups + + **Example Prompt:** "Create a 'Content Reviewer' user group with read access to all content but no publish rights" + + **Required Tool Collections:** `user-group` + + - Audit user group configurations + + **Example Prompt:** "Show me all user groups and their permission levels" + + **Required Tool Collections:** `user-group` + + - Update user group settings + + **Example Prompt:** "Update the Marketing user group to allow access to the Media section" + + **Required Tool Collections:** `user-group` + + - Clean up unused user groups + + **Example Prompt:** "Find and delete any user groups that have no users assigned to them" + + **Required Tool Collections:** `user-group`, `user` + +16. **Member Management** + - Create member accounts programmatically + + **Example Prompt:** "Create member accounts for all email addresses in the subscribers.csv file" + + **Required Tool Collections:** `member`, `member-type` + + - Manage member groups and properties + + **Example Prompt:** "Add all members with 'premium' status to the Premium Members group" + + **Required Tool Collections:** `member`, `member-group` + + - Update member type configurations + + **Example Prompt:** "Add a 'Subscription Expiry Date' property to the Member type" + + **Required Tool Collections:** `member-type` + + - Track member engagement and access + + **Example Prompt:** "Find all members who haven't logged in for 6 months" + + **Required Tool Collections:** `member` + +## Content Analysis & Reporting + +17. **Content Auditing** + - Audit content relationships and dependencies + + **Example Prompt:** "Show me all relations of type 'Related Links' for documents under /products" + + **Required Tool Collections:** `relation`, `relation-type`, `document` + + - Analyze content tree structure for impact + + **Example Prompt:** "List all descendant pages under /products/legacy so I can understand the impact of deletion" + + **Required Tool Collections:** `document` + + - Identify content without required metadata + + **Example Prompt:** "Find all published pages that are missing SEO metadata like meta descriptions or Open Graph tags" + + **Required Tool Collections:** `document` + + - Generate content dependency reports + + **Example Prompt:** "Create a report showing the content hierarchy and dependencies for the /services section" + + **Required Tool Collections:** `document` + +18. **Version Control** + - Manage document versions programmatically + + **Example Prompt:** "Show me all versions of the homepage from the last 30 days" + + **Required Tool Collections:** `document-version` + + - Rollback to previous versions + + **Example Prompt:** "Rollback the /pricing page to the version from last Friday" + + **Required Tool Collections:** `document-version` + + - Prevent cleanup of important versions + + **Example Prompt:** "Mark the current version of all legal pages as 'keep forever'" + + **Required Tool Collections:** `document-version` + + - Audit content changes over time + + **Example Prompt:** "Show me who made changes to documents under /products in the last week" + + **Required Tool Collections:** `document-version` + +## Multi-language & Localization + +19. **Language Management** + - Configure languages and fallback chains + + **Example Prompt:** "Add Spanish as a new language with English as the fallback" + + **Required Tool Collections:** `language` + + - Create multi-language content variants + + **Example Prompt:** "Create French variants for all pages under /products that don't have them yet" + + **Required Tool Collections:** `document`, `language` + + - Manage dictionary items for translations + + **Example Prompt:** "Add dictionary items for all our standard UI labels with English and German translations" + + **Required Tool Collections:** `dictionary`, `language` + + - Bulk update culture-specific content + + **Example Prompt:** "Update all German content to use the formal 'Sie' instead of informal 'du'" + + **Required Tool Collections:** `document`, `language` + +## Advanced Workflows + +20. **Custom Webhooks** + - Set up webhooks for content events + + **Example Prompt:** "Find the publish event, then create a webhook that posts to our Slack webhook URL whenever a page is published" + + **Required Tool Collections:** `webhook` + + - Monitor webhook execution logs + + **Example Prompt:** "Use get-all-webhook-logs to show me the last 50 webhook events and any that failed" + + **Required Tool Collections:** `webhook` + + - Integrate with external systems on content changes + + **Example Prompt:** "Use create-webhook to set up a webhook that calls https://api.example.com/sync when Product documents are published, triggering on the Content.Published event" + + **Required Tool Collections:** `webhook` + + - Automate notifications and integrations + + **Example Prompt:** "Create webhooks to notify our CDN purge at ```https://cloudflare/``` something endpoint whenever content in /news is published" + + **Required Tool Collections:** `webhook` + +21. **Redirect Management** + - Create and manage URL redirects + + **Example Prompt:** "Create a 301 redirect from /old-services to /services" + + **Required Tool Collections:** `redirect` + + - Import bulk redirect rules + + **Example Prompt:** "Import all the redirects from redirects.csv" + + **Required Tool Collections:** `redirect` + + - Monitor redirect usage + + **Example Prompt:** "Show me which redirects have been hit in the last 30 days" + + **Required Tool Collections:** `redirect` + + - Maintain SEO during content restructuring + + **Example Prompt:** "When I move /products/widget to /solutions/widget, create the appropriate redirects" + + **Required Tool Collections:** `redirect` + +## API & Integration Use Cases + +22. **AI-Powered Content Management** + - Generate content using AI and publish to Umbraco + + **Example Prompt:** "Generate product descriptions for all products missing them and save as drafts for review" + + **Required Tool Collections:** `document` + + - Automatically tag and categorize content + + **Example Prompt:** "Analyze all blog posts and suggest appropriate category tags based on content" + + **Required Tool Collections:** `document`, `tag` \ No newline at end of file