Umb Cms Dev Cli

Umbraco MCP Server — CLI Guide

This MCP server runs as a CLI tool. The CLI handles authentication and configuration, then exposes tools that talk directly to the Umbraco Management API.

Detecting the CLI Command

Determine the CLI command in a single check:

# One command to detect context — check for local build AND .env together
ls dist/index.js .env 2>/dev/null

• If dist/index.js exists: use node dist/index.js
• Otherwise: use npx @umbraco-cms/mcp-dev@latest

All examples below use <cli> as a placeholder — substitute the correct command.

Quick Reference

# List all tools
<cli> --list-tools

# Describe a specific tool's schema
<cli> --describe-tool <tool-name>

# Call a tool directly (requires auth via .env)
<cli> --call <tool-name> --call-args '{"key":"value"}'

# Generate context documentation
<cli> --generate-context > CONTEXT.md

# Debug resolved configuration
<cli> --debug-config

Authentication

Never pass secrets as CLI arguments. Use a .env file.

Create a .env file:

UMBRACO_CLIENT_ID=your-client-id
UMBRACO_CLIENT_SECRET=your-secret
UMBRACO_BASE_URL=https://localhost:44391

Introspection commands (--list-tools, --describe-tool, --generate-context) do not require auth.

Tool Filtering

Available slices: read, list, create, update, delete, search, tree, publish, move, copy.

Exclude takes precedence over include. Filters combine.

Runtime Modes

Readonly mode

<cli> --umbraco-readonly

Mutation tools are completely removed — the LLM won't see them at all.

Dry-run mode

<cli> --umbraco-dry-run

Read tools execute normally. Mutation tools return a preview without calling the API.

Introspection Commands

These print output and exit immediately — they do not start the MCP server.

Introspection respects all filtering. --list-tools with UMBRACO_READONLY=true shows exactly what the LLM would see.

Efficient CLI Usage

Every CLI call costs time and tokens. The CLI has built-in filtering so you don't need to fetch everything and grep locally. Follow these principles:

1. Filter server-side, not locally. Instead of --list-tools | grep document, use the filtering flags:

# Bad — fetches all tools then filters locally
<cli> --list-tools | grep document

# Good — server returns only what you need
<cli> --list-tools --umbraco-include-tool-collections document

You can combine filters to narrow further:

<cli> --list-tools --umbraco-include-tool-collections document --umbraco-include-slices read,search

2. Use search tools before tree traversal. When looking for a specific item by name, prefer search-document over walking the tree with get-document-root → get-document-by-id. Search is one call instead of two.

3. Batch independent shell commands. Combine checks that don't depend on each other:

# Bad — two separate calls
ls dist/index.js
ls .env

# Good — one call
ls dist/index.js .env 2>/dev/null

4. Use `--describe-tool` before guessing parameters. If you're unsure what a tool accepts, describe it first rather than making a call that might fail.

For more workflow examples, read references/workflow-patterns.md.

Input Sanitization

The SDK validates all string inputs before tool handlers run:

• Rejects control characters, path traversal (../), embedded query params, percent-encoded strings
• Validates UUID format where expected
• Returns clear error messages for agent self-correction

CLI Workflow Patterns

Common task patterns showing efficient CLI usage. Each pattern shows the minimum number of calls needed.

Table of Contents

• Finding a document by name
• Exploring available tools for a domain
• Getting full details of an entity
• Creating content
• Filtering combinations

---

Finding a document by name

When the user asks about a specific document (e.g. "what does the Home page look like"):

# 1. Search by name — returns matching documents with IDs
<cli> --call search-document --call-args '{"query":"Home"}'

# 2. Only if search didn't return enough detail, get full document
<cli> --call get-document-by-id --call-args '{"id":"<id-from-search>"}'

Avoid the tree-walking pattern (get-document-root → scan for name → get-document-by-id) — it always takes more calls.

The same pattern applies to other searchable entities:

• search-document-type for document types
• find-dictionary for dictionary items
• find-data-type for data types
• find-member for members

Exploring available tools for a domain

When the user asks "what can I do with media?" or "show me the document tools":

# One call — filter to the collection and optionally slices
<cli> --list-tools --umbraco-include-tool-collections media

To see only read operations:

<cli> --list-tools --umbraco-include-tool-collections media --umbraco-include-slices read,search,list

To see what the LLM would see in readonly mode:

<cli> --list-tools --umbraco-readonly

Getting full details of an entity

When you need to understand a tool's parameters before calling it:

# Describe the tool first — shows full JSON schema
<cli> --describe-tool get-document-by-id

# Then call it with the right parameters
<cli> --call get-document-by-id --call-args '{"id":"..."}'

This is faster than guessing parameters and handling errors.

Creating content

For create operations, describe the tool first to understand required fields:

# 1. Understand what's needed
<cli> --describe-tool create-document

# 2. Create with the right payload
<cli> --call create-document --call-args '{"name":"My Page","documentType":{"id":"..."},"parent":{"id":"..."}}'

If you need to find a document type ID first:

<cli> --call search-document-type --call-args '{"query":"Article"}'

Filtering combinations

Filters combine — use them together to get precisely the tools you need.

Remember: exclude takes precedence over include when both are specified.