用途
本资料是 Umbraco MCP Server 的 CLI 使用指南，用于指导如何通过命令行运行和调试该 MCP 服务器。该 MCP 服务器以 CLI 工具形式运行，CLI 负责认证与配置，并暴露一组直接与 Umbraco Management API 通信的工具。适合需要列出工具、调用工具、配置过滤、试运行或只读运行等场景。
检测 CLI 命令
通过一次检查确定 CLI 命令：
ls dist/index.js .env 2>/dev/null
- 如果 dist/index.js 存在：使用 node dist/index.js
- 否则：使用 npx @umbraco-cms/mcp-dev@latest
文档中所有示例用 <cli> 作为占位符，替换为正确的命令即可。
主要能力（命令）
快速参考：
# 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
内省命令会打印输出后立即退出，不会启动 MCP 服务器：
| Flag | 说明 |
|---|---|
| --list-tools | 打印所有工具的 ASCII 表格 |
| --describe-tool <name> | 打印某个工具的完整 JSON schema |
| --generate-context | 输出记录所有工具的 CONTEXT.md |
| --debug-config | 打印解析后的配置（密钥已遮蔽） |
| --call <name> | 直接调用工具并打印 JSON 结果 |
| --call-args <json> | 为 --call 提供 JSON 参数（默认：{}） |
内省命令同样遵循所有过滤设置。使用 UMBRACO_READONLY=true 的 --list-tools 会显示 LLM 实际能看到的内容。
认证
永远不要把密钥作为 CLI 参数传入，应使用 .env 文件。
| 环境变量 | 必需 | 说明 |
|---|---|---|
| UMBRACO_CLIENT_ID | 是 | 来自 Umbraco API 用户的 OAuth 客户端 ID |
| UMBRACO_CLIENT_SECRET | 是 | OAuth 客户端密钥 |
| UMBRACO_BASE_URL | 是 | Umbraco 实例 URL |
创建 .env 文件示例：
UMBRACO_CLIENT_ID=your-client-id
UMBRACO_CLIENT_SECRET=your-secret
UMBRACO_BASE_URL=https://localhost:44391
内省命令（--list-tools、--describe-tool、--generate-context）不需要认证。
工具过滤
| 标志 | 环境变量 | 说明 |
|---|---|---|
| --umbraco-tool-modes | UMBRACO_TOOL_MODES | 启用命名的集合分组 |
| --umbraco-include-slices | UMBRACO_INCLUDE_SLICES | 仅暴露带有这些切片的工具 |
| --umbraco-exclude-slices | UMBRACO_EXCLUDE_SLICES | 隐藏带有这些切片的工具 |
| --umbraco-include-tool-collections | UMBRACO_INCLUDE_TOOL_COLLECTIONS | 仅暴露这些集合 |
| --umbraco-exclude-tool-collections | UMBRACO_EXCLUDE_TOOL_COLLECTIONS | 隐藏这些集合 |
| --umbraco-include-tools | UMBRACO_INCLUDE_TOOLS | 仅暴露这些具体工具 |
| --umbraco-exclude-tools | UMBRACO_EXCLUDE_TOOLS | 隐藏这些具体工具 |
切片定义在 src/config/slice-registry.ts 中，是唯一的真实来源。应查看该文件获取当前列表，而不是信任此处副本，因为它会随工具增加而增长（示例：create、read、update、delete、search、publish）。未分配切片的工具回退为 other。
排除优先于包含。过滤条件可以组合。
运行模式
只读模式：
<cli> --umbraco-readonly
变更类工具会被完全移除——LLM 完全看不到它们。
试运行模式：
<cli> --umbraco-dry-run
读取类工具正常执行。变更类工具返回预览而不调用 API。
高效使用 CLI 的建议
每次 CLI 调用都消耗时间和 token。CLI 内置过滤，因此无需拉取所有内容后在本地 grep。原则如下：
- 在服务端过滤，而不是本地过滤。例如不要用 --list-tools | grep document，而应使用过滤标志：
# Good — server returns only what you need
<cli> --list-tools --umbraco-include-tool-collections document
可以组合过滤器进一步缩小范围：
<cli> --list-tools --umbraco-include-tool-collections document --umbraco-include-slices read,search
-
在遍历树之前使用搜索工具。按名称查找特定项时，优先使用 search-document，而不是用 get-document-root → get-document-by-id 遍历树。一次搜索调用即可完成，而不是两次。
-
批量执行相互独立的 shell 命令，合并不相互依赖的检查：
# Good — one call
ls dist/index.js .env 2>/dev/null
- 在猜测参数前使用 --describe-tool。如果不确定工具接受什么参数，先描述它，而不是发起可能失败的调用。
更多工作流示例可阅读 references/workflow-patterns.md。
输入净化
SDK 在工具处理器运行前校验所有字符串输入：
- 拒绝控制字符、路径遍历（../）、内嵌查询参数、百分号编码字符串
- 在预期位置校验 UUID 格式
- 返回清晰的错误信息，便于智能体自我纠正
限制
资料未提供收费、价格、平台或效果方面的信息。