From umbraco-mcp-skills
Load MCP development patterns and best practices for building tools with the @umbraco-cms/mcp-server-sdk. Use when starting tool development or needing pattern reference.
npx claudepluginhub umbraco/umbraco-mcp-base --plugin umbraco-mcp-skillsThis skill uses the workspace's default tool permissions.
This skill loads comprehensive patterns for building MCP tools using the `@umbraco-cms/mcp-server-sdk`.
Applies Acme Corporation brand guidelines including colors, fonts, layouts, and messaging to generated PowerPoint, Excel, and PDF documents.
Builds DCF models with sensitivity analysis, Monte Carlo simulations, and scenario planning for investment valuation and risk assessment.
Calculates profitability (ROE, margins), liquidity (current ratio), leverage, efficiency, and valuation (P/E, EV/EBITDA) ratios from financial statements in CSV, JSON, text, or Excel for investment analysis.
This skill loads comprehensive patterns for building MCP tools using the @umbraco-cms/mcp-server-sdk.
Use this skill when:
All tools follow this structure:
import {
withStandardDecorators,
executeGetApiCall,
executeVoidApiCall,
createToolResult,
CAPTURE_RAW_HTTP_RESPONSE,
ToolDefinition,
} from "@umbraco-cms/mcp-server-sdk";
const MyTool = {
name: "tool-name",
description: "What the tool does",
inputSchema: zodSchema.shape,
outputSchema: responseSchema, // For GET operations
slices: ["read"], // Categorization
annotations: {
readOnlyHint: true, // For GET
destructiveHint: true, // For DELETE
idempotentHint: true, // For PUT
},
handler: async (params) => {
// Implementation
},
} satisfies ToolDefinition<...>;
export default withStandardDecorators(MyTool);
Configure once at server startup:
import { configureApiClient } from "@umbraco-cms/mcp-server-sdk";
import { getMyAPI } from "./api/generated/myApi.js";
configureApiClient(() => getMyAPI());
For GET operations that return data:
return executeGetApiCall<ReturnType<Client["method"]>, Client>(
(client) => client.method(params, CAPTURE_RAW_HTTP_RESPONSE)
);
For DELETE/PUT operations that return void:
return executeVoidApiCall<Client>(
(client) => client.deleteItem(id, CAPTURE_RAW_HTTP_RESPONSE)
);
For custom responses (typically CREATE operations):
if (response.status === 201) {
return createToolResult({ success: true, id: extractedId });
} else {
return createToolResultError(response.data);
}
Tools are categorized by operation type:
read - GET operationscreate - POST create operationsupdate - PUT operationsdelete - DELETE operationssearch - Search/filter operations| Operation | readOnlyHint | destructiveHint | idempotentHint |
|---|---|---|---|
| GET | ✅ | ❌ | ❌ |
| DELETE | ❌ | ✅ | ❌ |
| POST | ❌ | ❌ | ❌ |
| PUT | ❌ | ❌ | ✅ |
Important: DELETE is NOT idempotent (2nd call returns 404).
src/
├── api/
│ ├── client.ts # Axios client with mock support
│ ├── openapi.yaml # OpenAPI spec
│ └── generated/ # Orval-generated client + Zod schemas
├── tools/
│ └── {entity}/
│ ├── get/
│ ├── post/
│ ├── put/
│ ├── delete/
│ └── index.ts # Collection export
└── index.ts # MCP server entry
Generate client and Zod schemas from OpenAPI:
npm run generate
Configuration in orval.config.ts:
{action}-{entity} patternwithStandardDecorators handles errors automatically