@kontent-ai/mcp-server 0.22.1 → 0.23.1

package/README.md

@@ -61,9 +61,9 @@ npx @kontent-ai/mcp-server@latest shttp
 
 ## 🛠️ Available Tools
 
-### Context and Setup
+### Patch Operations Guide
 
-* **get-initial-context** – 🚨 **MANDATORY FIRST STEP**: This tool MUST be called before using ANY other tools. It provides essential context, configuration, and operational guidelines for Kontent.ai
+* **get-patch-guide** – 🚨 **REQUIRED before any patch operation**. Get JSON Patch operations guide for Kontent.ai Management API
 
 ### Content Type Management
 
@@ -99,7 +99,7 @@ npx @kontent-ai/mcp-server@latest shttp
 * **add-content-item-mapi** – Add new Kontent.ai content item via Management API. This creates the content item structure but does not add content to language variants. Use upsert-language-variant-mapi to add content to the item
 * **update-content-item-mapi** – Update existing Kontent.ai content item by internal ID via Management API. The content item must already exist - this tool will not create new items
 * **delete-content-item-mapi** – Delete Kontent.ai content item by internal ID from Management API
-* **upsert-language-variant-mapi** – Create or update Kontent.ai language variant of a content item via Management API. This adds actual content to the content item elements. When updating an existing variant, only the provided elements will be modified
+* **upsert-language-variant-mapi** – Create or update Kontent.ai language variant of a content item via Management API. Element values must fulfill limitations and guidelines defined in content type. When updating, only provided elements will be modified
 * **create-variant-version-mapi** – Create new version of Kontent.ai language variant via Management API. This operation creates a new version of an existing language variant, useful for content versioning and creating new drafts from published content
 * **delete-language-variant-mapi** – Delete Kontent.ai language variant from Management API
 * **filter-variants-mapi** – Filter Kontent.ai language variants of content items using Management API. Use for exact keyword matching and finding specific terms in content. Supports full filtering capabilities (content types, workflow steps, taxonomies, etc.) and optionally includes full content of variants. Returns paginated results with continuation token for fetching subsequent pages

package/build/schemas/contentItemSchemas.js

@@ -1,14 +1,17 @@
 import { z } from "zod";
 import { referenceObjectSchema } from "./referenceObjectSchema.js";
-const languageVariantElementBaseSchema = z.object({
+// Recursive schema for rich text elements within components
+const richTextElementInComponentSchema = z.lazy(() => z.object({
     element: referenceObjectSchema,
-    value: z.any(),
-});
-const richTextComponentSchema = z.object({
+    value: z.string().nullable(),
+    components: z.array(richTextComponentSchema).nullable().optional(),
+}));
+// Recursive schema for rich text components
+const richTextComponentSchema = z.lazy(() => z.object({
     id: z.string(),
     type: referenceObjectSchema,
-    elements: z.array(languageVariantElementBaseSchema),
-});
+    elements: z.array(richTextElementInComponentSchema),
+}));
 const assetInVariantElementSchema = z.object({
     element: referenceObjectSchema,
     value: z.array(referenceObjectSchema).nullable(),

package/build/schemas/filterVariantSchemas.js

@@ -10,7 +10,7 @@ const userReferenceSchema = z
     }),
     z.object({
         id: z.never().optional(),
-        email: z.string().email().describe("User email address"),
+        email: z.email().describe("User email address"),
     }),
 ])
     .describe("Reference to a user by either their id or email (but not both)");

package/build/schemas/searchOperationSchemas.js

@@ -5,10 +5,7 @@ export const searchOperationSchema = z.object({
         .describe("Search phrase for AI-powered semantic search. Uses vector database to find content by meaning and similarity, not just exact keyword matching"),
     filter: z
         .object({
-        variantId: z
-            .string()
-            .uuid()
-            .describe("UUID of the language variant to filter by"),
+        variantId: z.uuid().describe("UUID of the language variant to filter by"),
     })
         .describe("Mandatory content item variant filter to restrict search scope. Must specify a valid variant UUID"),
 });

package/build/schemas/workflowSchemas.js

@@ -2,7 +2,6 @@ import { z } from "zod";
 // Schema for a workflow step
 const workflowStepSchema = z.object({
     id: z
-        .string()
         .uuid()
         .describe("The unique identifier of the workflow step in UUID format"),
     name: z.string().describe("The human-readable name of the workflow step"),
@@ -10,18 +9,17 @@ const workflowStepSchema = z.object({
         .string()
         .describe("The codename of the workflow step used for API operations"),
     transitions_to: z
-        .array(z.string().uuid())
+        .array(z.uuid())
         .describe("Array of workflow step IDs that this step can transition to")
         .optional(),
     role_ids: z
-        .array(z.string().uuid())
+        .array(z.uuid())
         .describe("Array of role IDs that have permissions for this workflow step")
         .optional(),
 });
 // Schema for the published step
 const publishedStepSchema = z.object({
     id: z
-        .string()
         .uuid()
         .describe("The unique identifier of the published step in UUID format"),
     name: z
@@ -31,18 +29,17 @@ const publishedStepSchema = z.object({
         .string()
         .describe("The codename of the published step - typically 'published'"),
     unpublish_role_ids: z
-        .array(z.string().uuid())
+        .array(z.uuid())
         .describe("Array of role IDs that can unpublish content from this step")
         .optional(),
     create_new_version_role_ids: z
-        .array(z.string().uuid())
+        .array(z.uuid())
         .describe("Array of role IDs that can create new versions of content in this step")
         .optional(),
 });
 // Schema for the scheduled step
 const scheduledStepSchema = z.object({
     id: z
-        .string()
         .uuid()
         .describe("The unique identifier of the scheduled step in UUID format"),
     name: z
@@ -55,7 +52,6 @@ const scheduledStepSchema = z.object({
 // Schema for the archived step
 const archivedStepSchema = z.object({
     id: z
-        .string()
         .uuid()
         .describe("The unique identifier of the archived step in UUID format"),
     name: z
@@ -65,7 +61,7 @@ const archivedStepSchema = z.object({
         .string()
         .describe("The codename of the archived step - typically 'archived'"),
     role_ids: z
-        .array(z.string().uuid())
+        .array(z.uuid())
         .describe("Array of role IDs that can unarchive content from this step")
         .optional(),
 });
@@ -74,7 +70,6 @@ const workflowScopeSchema = z.object({
     content_types: z
         .array(z.object({
         id: z
-            .string()
             .uuid()
             .describe("The unique identifier of the content type in UUID format"),
     }))
@@ -82,10 +77,7 @@ const workflowScopeSchema = z.object({
 });
 // Main workflow schema
 export const workflowSchema = z.object({
-    id: z
-        .string()
-        .uuid()
-        .describe("The unique identifier of the workflow in UUID format"),
+    id: z.uuid().describe("The unique identifier of the workflow in UUID format"),
     name: z.string().describe("The human-readable name of the workflow"),
     codename: z
         .string()

package/build/server.js

@@ -12,9 +12,9 @@ import { registerTool as registerDeleteContentTypeMapi } from "./tools/delete-co
 import { registerTool as registerDeleteLanguageVariantMapi } from "./tools/delete-language-variant-mapi.js";
 import { registerTool as registerFilterVariantsMapi } from "./tools/filter-variants-mapi.js";
 import { registerTool as registerGetAssetMapi } from "./tools/get-asset-mapi.js";
-import { registerTool as registerGetInitialContext } from "./tools/get-initial-context.js";
 import { registerTool as registerGetItemMapi } from "./tools/get-item-mapi.js";
 import { registerTool as registerGetLatestVariantMapi } from "./tools/get-latest-variant-mapi.js";
+import { registerTool as registerGetPatchGuide } from "./tools/get-patch-guide.js";
 import { registerTool as registerGetPublishedVariantMapi } from "./tools/get-published-variant-mapi.js";
 import { registerTool as registerGetTaxonomyGroupMapi } from "./tools/get-taxonomy-group-mapi.js";
 import { registerTool as registerGetTypeMapi } from "./tools/get-type-mapi.js";
@@ -45,13 +45,9 @@ export const createServer = () => {
     const server = new McpServer({
         name: "kontent-ai",
         version: packageJson.version,
-        capabilities: {
-            resources: {},
-            tools: {},
-        },
     });
     // Register all tools
-    registerGetInitialContext(server);
+    registerGetPatchGuide(server);
     registerGetItemMapi(server);
     registerGetLatestVariantMapi(server);
     registerGetPublishedVariantMapi(server);

package/build/telemetry/applicationInsights.js

@@ -148,7 +148,7 @@ export function initializeApplicationInsights() {
             .setAutoCollectDependencies(false)
             .setAutoDependencyCorrelation(false)
             .setAutoCollectHeartbeat(false)
-            .setAutoCollectPerformance(false)
+            .setAutoCollectPerformance(false, false)
             .setAutoCollectIncomingRequestAzureFunctions(false)
             .setAutoCollectPreAggregatedMetrics(false)
             .start();

package/build/test/schemas/contentItemSchemas.spec.js

@@ -0,0 +1,81 @@
+import * as assert from "node:assert";
+import { describe, it } from "mocha";
+import { languageVariantElementSchema } from "../../schemas/contentItemSchemas.js";
+describe("languageVariantElementSchema", () => {
+    describe("nested rich text components", () => {
+        it("validates rich text element with deeply nested components", () => {
+            const nestedRichTextElement = {
+                element: { id: "1fefb369-53b9-4108-9ca3-837c99010c29" },
+                value: '<p>rich1</p>\n<object type="application/kenticocloud" data-type="component" data-id="20a941ec-91bf-4a40-89c8-90b5e31dae27"></object>',
+                components: [
+                    {
+                        id: "20a941ec-91bf-4a40-89c8-90b5e31dae27",
+                        type: { id: "da3871d1-f942-4d8c-b518-f4c6c97c5174" },
+                        elements: [
+                            {
+                                element: { id: "1fefb369-53b9-4108-9ca3-837c99010c29" },
+                                value: '<p>rich2 nested</p>\n<object type="application/kenticocloud" data-type="component" data-id="5dd61cc6-d375-49d7-a8e3-e4dcd029be1a"></object>',
+                                components: [
+                                    {
+                                        id: "5dd61cc6-d375-49d7-a8e3-e4dcd029be1a",
+                                        type: { id: "da3871d1-f942-4d8c-b518-f4c6c97c5174" },
+                                        elements: [
+                                            {
+                                                value: "<p>rich3 nested nested</p>",
+                                                element: { id: "1fefb369-53b9-4108-9ca3-837c99010c29" },
+                                                components: [],
+                                            },
+                                        ],
+                                    },
+                                ],
+                            },
+                        ],
+                    },
+                ],
+            };
+            const result = languageVariantElementSchema.safeParse(nestedRichTextElement);
+            assert.strictEqual(result.success, true, `Schema validation failed: ${result.success ? "" : JSON.stringify(result.error.issues, null, 2)}`);
+            if (result.success) {
+                assert.deepStrictEqual(result.data, nestedRichTextElement, "Parsed data should match input exactly");
+            }
+        });
+        it("validates rich text element with single level components", () => {
+            const richTextElement = {
+                element: { id: "1849f877-cd37-4ed0-8df6-3173748a126f" },
+                value: "<p>Some content</p>",
+                components: [
+                    {
+                        id: "af87f9d1-a448-489b-a5bd-9ab3e5e5f2e2",
+                        type: { id: "924daea8-5d87-4e7c-8c22-7b66044593c3" },
+                        elements: [
+                            {
+                                element: { id: "924daea8-5d87-4e7c-8c22-7b66044593c3" },
+                                value: "Nested value",
+                            },
+                        ],
+                    },
+                ],
+            };
+            const result = languageVariantElementSchema.safeParse(richTextElement);
+            assert.strictEqual(result.success, true);
+        });
+        it("validates rich text element with empty components array", () => {
+            const richTextElement = {
+                element: { id: "c0021332-250b-46d0-a283-c114c85f6062" },
+                value: "<p>Some content</p>",
+                components: [],
+            };
+            const result = languageVariantElementSchema.safeParse(richTextElement);
+            assert.strictEqual(result.success, true);
+        });
+        it("validates rich text element with null components", () => {
+            const richTextElement = {
+                element: { id: "1ae5d294-5861-4555-881c-9279343443a5" },
+                value: "<p>Some content</p>",
+                components: null,
+            };
+            const result = languageVariantElementSchema.safeParse(richTextElement);
+            assert.strictEqual(result.success, true);
+        });
+    });
+});

package/build/tools/change-variant-workflow-step-mapi.js

@@ -4,13 +4,12 @@ import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
     server.tool("change-variant-workflow-step-mapi", "Change Kontent.ai variant workflow step", {
-        itemId: z.string().uuid().describe("Content item UUID"),
+        itemId: z.uuid().describe("Content item UUID"),
         languageId: z
-            .string()
             .uuid()
             .describe("Language variant UUID (default: 00000000-0000-0000-0000-000000000000)"),
-        workflowId: z.string().uuid().describe("Workflow UUID"),
-        workflowStepId: z.string().uuid().describe("Target workflow step UUID"),
+        workflowId: z.uuid().describe("Workflow UUID"),
+        workflowStepId: z.uuid().describe("Target workflow step UUID"),
     }, async ({ itemId, languageId, workflowId, workflowStepId }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

package/build/tools/create-variant-version-mapi.js

@@ -4,9 +4,8 @@ import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
     server.tool("create-variant-version-mapi", "Create new version of Kontent.ai variant", {
-        itemId: z.string().uuid().describe("Content item UUID"),
+        itemId: z.uuid().describe("Content item UUID"),
         languageId: z
-            .string()
             .uuid()
             .describe("Language variant UUID (default: 00000000-0000-0000-0000-000000000000)"),
     }, async ({ itemId, languageId }, { authInfo: { token, clientId } = {} }) => {

package/build/tools/get-asset-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-asset-mapi", "Get Kontent.ai asset by ID", {
+    server.tool("get-asset-mapi", "Get Kontent.ai asset. Assets are digital files (images, videos, documents) referenced in content.", {
         assetId: z.string().describe("Asset ID"),
     }, async ({ assetId }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);

package/build/tools/get-item-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-item-mapi", "Get Kontent.ai item by ID", {
+    server.tool("get-item-mapi", "Get Kontent.ai content item. Items are language-neutral containers; one item has multiple language variants.", {
         id: z.string().describe("Item ID"),
     }, async ({ id }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);

package/build/tools/get-latest-variant-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createVariantMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-latest-variant-mapi", "Get latest version of Kontent.ai language variant from Management API", {
+    server.tool("get-latest-variant-mapi", "Get latest Kontent.ai language variant. Variants hold language-specific content; structure defined by content type and its snippets.", {
         itemId: z.string().describe("Item ID"),
         languageId: z.string().describe("Language variant ID"),
     }, async ({ itemId, languageId }, { authInfo: { token, clientId } = {} }) => {

package/build/tools/get-patch-guide.js

@@ -0,0 +1,12 @@
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+import { patchOperationsGuide } from "./context/patch-operations-guide.js";
+export const registerTool = (server) => {
+    server.tool("get-patch-guide", "REQUIRED before any patch operation. Get JSON Patch operations guide for Kontent.ai Management API.", {}, async () => {
+        try {
+            return createMcpToolSuccessResponse(patchOperationsGuide);
+        }
+        catch (error) {
+            throw new Error(`Failed to read patch guide: ${error instanceof Error ? error.message : "Unknown error"}`);
+        }
+    });
+};

package/build/tools/get-published-variant-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createVariantMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-published-variant-mapi", "Get published version of Kontent.ai language variant from Management API", {
+    server.tool("get-published-variant-mapi", "Get published Kontent.ai language variant. Variants hold language-specific content; structure defined by content type and its snippets.", {
         itemId: z.string().describe("Item ID"),
         languageId: z.string().describe("Language variant ID"),
     }, async ({ itemId, languageId }, { authInfo: { token, clientId } = {} }) => {

package/build/tools/get-taxonomy-group-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-taxonomy-group-mapi", "Get Kontent.ai taxonomy group by ID", {
+    server.tool("get-taxonomy-group-mapi", "Get Kontent.ai taxonomy group. Taxonomies provide hierarchical categorization for organizing and tagging content.", {
         id: z.string().describe("Taxonomy group ID"),
     }, async ({ id }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);

package/build/tools/get-type-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-type-mapi", "Get Kontent.ai content type by ID", {
+    server.tool("get-type-mapi", "Get Kontent.ai content type. Types define variant structure: field definitions, validation rules, and element types.", {
         id: z.string().describe("Content type ID"),
     }, async ({ id }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);

package/build/tools/get-type-snippet-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-type-snippet-mapi", "Get Kontent.ai content type snippet by ID", {
+    server.tool("get-type-snippet-mapi", "Get Kontent.ai content type snippet. Snippets are reusable element sets included in content types via snippet element.", {
         id: z.string().describe("Snippet ID"),
     }, async ({ id }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);

package/build/tools/list-assets-mapi.js

@@ -3,7 +3,7 @@ import { listAssetsSchema } from "../schemas/listSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("list-assets-mapi", "Get all Kontent.ai assets (paginated)", listAssetsSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-assets-mapi", "Get all Kontent.ai assets (paginated). Assets are digital files (images, videos, documents) referenced in content.", listAssetsSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const query = client.listAssets();

package/build/tools/list-collections-mapi.js

@@ -2,7 +2,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("list-collections-mapi", "Get all Kontent.ai collections", {}, async (_, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-collections-mapi", "Get all Kontent.ai collections. Collections organize content items into logical groups by team, brand, or project.", {}, async (_, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const response = await client.listCollections().toPromise();

package/build/tools/list-content-type-snippets-mapi.js

@@ -3,7 +3,7 @@ import { listContentTypeSnippetsSchema } from "../schemas/listSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("list-content-type-snippets-mapi", "Get all Kontent.ai content type snippets (paginated)", listContentTypeSnippetsSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-content-type-snippets-mapi", "Get all Kontent.ai content type snippets (paginated). Snippets are reusable element sets included in content types via snippet element.", listContentTypeSnippetsSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const query = client.listContentTypeSnippets();

package/build/tools/list-content-types-mapi.js

@@ -3,7 +3,7 @@ import { listContentTypesSchema } from "../schemas/listSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("list-content-types-mapi", "Get all Kontent.ai content types (paginated)", listContentTypesSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-content-types-mapi", "Get all Kontent.ai content types (paginated). Types define variant structure: field definitions, validation rules, and element types.", listContentTypesSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const query = client.listContentTypes();

package/build/tools/list-languages-mapi.js

@@ -3,7 +3,7 @@ import { listLanguagesSchema } from "../schemas/listSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("list-languages-mapi", "Get all Kontent.ai languages (paginated)", listLanguagesSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-languages-mapi", "Get all Kontent.ai languages (paginated). Languages define available locales; each can have fallback language for content inheritance.", listLanguagesSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const query = client.listLanguages();

package/build/tools/list-taxonomy-groups-mapi.js

@@ -3,7 +3,7 @@ import { listTaxonomyGroupsSchema } from "../schemas/listSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("list-taxonomy-groups-mapi", "Get all Kontent.ai taxonomy groups (paginated)", listTaxonomyGroupsSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-taxonomy-groups-mapi", "Get all Kontent.ai taxonomy groups (paginated). Taxonomies provide hierarchical categorization for organizing and tagging content.", listTaxonomyGroupsSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const query = client.listTaxonomies();

package/build/tools/list-workflows-mapi.js

@@ -2,7 +2,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("list-workflows-mapi", "Get all Kontent.ai workflows", {}, async (_, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-workflows-mapi", "Get all Kontent.ai workflows. Workflow states manage content lifecycle: drafting, review, published, archived.", {}, async (_, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const response = await client.listWorkflows().toPromise();

package/build/tools/patch-collections-mapi.js

@@ -3,7 +3,7 @@ import { collectionPatchOperationsSchema } from "../schemas/collectionSchemas.js
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("patch-collections-mapi", "Update Kontent.ai collections using patch operations (addInto, move, remove, replace)", {
+    server.tool("patch-collections-mapi", "Update Kontent.ai collections using patch operations. Call get-patch-guide first for operations reference.", {
         operations: collectionPatchOperationsSchema.describe("Patch operations array. Call list-collections-mapi first. Use addInto to add new collections, move to reorder, remove to delete empty collections, replace to rename."),
     }, async ({ operations }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);

package/build/tools/patch-content-type-mapi.js

@@ -4,7 +4,7 @@ import { patchOperationsSchema } from "../schemas/patchSchemas/contentTypePatchS
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("patch-content-type-mapi", "Update Kontent.ai content type using JSON Patch (move, addInto, remove, replace)", {
+    server.tool("patch-content-type-mapi", "Update Kontent.ai content type using JSON Patch. Call get-patch-guide first for operations reference.", {
         codename: z.string().describe("Content type codename"),
         operations: patchOperationsSchema.describe("Patch operations array. CRITICAL: Always call get-type-mapi first. Use addInto/remove for arrays, replace for primitives/objects. See context for details."),
     }, async ({ codename, operations }, { authInfo: { token, clientId } = {} }) => {

package/build/tools/patch-language-mapi.js

@@ -3,7 +3,7 @@ import { patchLanguageSchema } from "../schemas/languageSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("patch-language-mapi", "Update Kontent.ai language using replace operations via Management API. Only active languages can be modified - if deactivated, is_active: true must be first operation.", patchLanguageSchema.shape, async ({ languageId, operations }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("patch-language-mapi", "Update Kontent.ai language using replace operations. Call get-patch-guide first. If deactivated, is_active: true must be first operation.", patchLanguageSchema.shape, async ({ languageId, operations }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const response = await client

package/build/tools/publish-variant-mapi.js

@@ -3,14 +3,12 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("publish-variant-mapi", "Publish or schedule Kontent.ai variant", {
-        itemId: z.string().uuid().describe("Content item UUID"),
+    server.tool("publish-variant-mapi", "Publish or schedule Kontent.ai variant. For scheduling, verify current UTC time before using scheduledTo.", {
+        itemId: z.uuid().describe("Content item UUID"),
         languageId: z
-            .string()
             .uuid()
             .describe("Language variant UUID (default: 00000000-0000-0000-0000-000000000000)"),
-        scheduledTo: z
-            .string()
+        scheduledTo: z.iso
             .datetime({ offset: true })
             .optional()
             .describe("ISO 8601 datetime for scheduled publish (omit for immediate)"),

package/build/tools/unpublish-variant-mapi.js

@@ -3,14 +3,12 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("unpublish-variant-mapi", "Unpublish or schedule unpublishing of Kontent.ai variant", {
-        itemId: z.string().uuid().describe("Content item UUID"),
+    server.tool("unpublish-variant-mapi", "Unpublish or schedule unpublishing Kontent.ai variant. For scheduling, verify current UTC time before using scheduledTo.", {
+        itemId: z.uuid().describe("Content item UUID"),
         languageId: z
-            .string()
             .uuid()
             .describe("Language variant UUID (default: 00000000-0000-0000-0000-000000000000)"),
-        scheduledTo: z
-            .string()
+        scheduledTo: z.iso
             .datetime({ offset: true })
             .optional()
             .describe("ISO 8601 datetime for scheduled unpublish (omit for immediate)"),

package/build/tools/upsert-language-variant-mapi.js

@@ -4,7 +4,7 @@ import { languageVariantElementSchema } from "../schemas/contentItemSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createVariantMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("upsert-language-variant-mapi", "Create or update Kontent.ai variant", {
+    server.tool("upsert-language-variant-mapi", "Create or update Kontent.ai variant. Element values must fulfill limitations and guidelines defined in content type.", {
         itemId: z.string().describe("Content item ID"),
         languageId: z
             .string()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontent-ai/mcp-server",
-  "version": "0.22.1",
+  "version": "0.23.1",
   "type": "module",
   "mcpName": "io.github.kontent-ai/mcp-server",
   "repository": {
@@ -30,22 +30,22 @@
   "license": "MIT",
   "dependencies": {
     "@kontent-ai/management-sdk": "^8.1.0",
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "applicationinsights": "^2.9.8",
-    "dotenv": "^16.5.0",
-    "express": "^5.1.0",
-    "p-retry": "^7.0.0",
-    "zod": "^3.25.30"
+    "@modelcontextprotocol/sdk": "^1.24.3",
+    "applicationinsights": "^3.12.1",
+    "dotenv": "^17.2.3",
+    "express": "^5.2.1",
+    "p-retry": "^7.1.1",
+    "zod": "^4.1.13"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.0.5",
-    "@types/express": "^5.0.2",
+    "@biomejs/biome": "^2.3.8",
+    "@types/express": "^5.0.6",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^22.15.19",
-    "cross-env": "^7.0.3",
+    "@types/node": "^24.10.2",
+    "cross-env": "^10.1.0",
     "mocha": "^11.7.5",
-    "rimraf": "^6.0.1",
-    "tsx": "^4.20.3",
-    "typescript": "^5.8.3"
+    "rimraf": "^6.1.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
   }
 }

package/build/tools/context/initial-context.js

@@ -1,201 +0,0 @@
-export const initialContext = `
-# Kontent.ai Platform Guide
-
-Kontent.ai is a headless content management system (CMS) that provides two main APIs: the Management API for creating, updating, and deleting content and structure, and the Delivery API for retrieving content for applications.
-
-## Core Entities
-
-### Content Items
-Content items are language-neutral content containers that serve as the foundation for your content structure. Each content item has a unique internal ID and codename, and references a specific content type. The key relationship to understand is that one content item can have multiple language variants.
-
-### Language Variants
-Language variants contain the actual language-specific content data including field values, workflow state, and language reference. Importantly, each variant is managed independently per language.
-
-### Content Types
-Content types define the structure and blueprint for language variants. They specify field definitions, validation rules, and element types that language variants will use. Think of them as templates that determine what fields and data types your language variants will have.
-
-### Content Type Snippets
-Content type snippets are reusable field groups that promote consistency across multiple content types. Following the DRY principle (define once, use everywhere), one snippet can be used across multiple content types. This prevents duplication and ensures consistency when you need the same fields across different content types.
-
-### Collections
-Collections organize content items into logical groups by team, brand, or project. Each content item belongs to exactly one collection.
-
-### Languages
-Languages define available locales for content. Each language can have a fallback language for content inheritance and can be activated or deactivated.
-
-## Understanding Key Relationships
-
-The content structure flows from Content Type → Content Item → Language Variant(s). For reusability, Content Type Snippets can be included in multiple Content Types. For localization, each Content Item can have one Language Variant per language.
-
-## Working with Content Types Containing Snippets
-
-**CRITICAL**: When creating language variants for content types with snippets, you must:
-
-1. **Read the content type** to identify snippet elements (type: "snippet")
-2. **Retrieve each snippet definition** to understand its internal elements
-3. **Include ALL elements** from both the content type AND all snippets in the language variant
-
-**SNIPPET ELEMENT IMPLEMENTATION DETAILS**:
-
-When implementing snippet elements in language variants, follow these rules:
-- **Element Reference Format**: Use {"element": {"id": "internal_id_here"}} format with internal IDs
-- **Codename Convention**: Snippet elements use double underscore format: {snippet_codename}__{element_codename}
-- **Example**: For a "metadata" snippet with a "title" element, the codename becomes metadata__title
-
-**CRITICAL**: Always use internal IDs from snippet definitions, never construct codenames manually.
-
-**Complete Example**:
-Content type has: title, body (direct) + metadata snippet (meta_title, meta_description)
-ALL FOUR elements must be included in language variant using their internal IDs:
-- Direct element: title ("title_internal_id_here")
-- Direct element: body ("body_internal_id_here")  
-- Snippet element: metadata title ("metadata_title_internal_id_here")
-- Snippet element: metadata description ("metadata_description_internal_id_here")
-
-**Failure to include snippet elements or using incorrect references will result in incomplete content creation.**
-
-## Working with Content Types Containing Taxonomy Groups
-
-**CRITICAL**: When creating language variants for content types with taxonomy elements, you must:
-
-1. **Read the content type** to identify ALL taxonomy elements (type: "taxonomy")
-2. **Retrieve EACH taxonomy group definition** to understand the available terms and their hierarchical structure
-3. **Fill ALL taxonomy elements** in the language variant - DO NOT leave any taxonomy elements empty
-4. **Use appropriate term internal IDs** when filling taxonomy elements based on the content being created
-
-**MANDATORY REQUIREMENT**: Every taxonomy element in the content type MUST be filled with at least one appropriate term when creating language variants. Empty taxonomy elements are not acceptable and indicate incomplete content creation.
-
-**Example Process**: If a content type has three taxonomy elements:
-- "article_type" (required) → Must select appropriate type using its internal ID
-- "topics" (optional but must be filled) → Must select relevant topics using their internal IDs
-- "medical_specialties" (optional but must be filled) → Must select relevant specialties using their internal IDs
-
-**Failure to fill ALL taxonomy elements will result in incomplete content creation and poor content organization.**
-
-## Operational Patterns
-
-### Content Creation Workflow
-1. Define content types (structure) - Create the blueprint for your content
-2. Create content items (containers) - Establish the content containers
-3. Add language variants (actual content) - Fill in the language-specific content
-4. Publish variants (make live) - Make content available through the Delivery API
-
-### Content Management Workflow
-- Update language variants with new content or changes
-- Manage workflow states as content progresses through its lifecycle
-- Create new language variants when expanding to additional languages
-- Organize with taxonomies for better content categorization
-
-### Workflow Step Management
-
-**CRITICAL**: When changing workflow steps of language variants, you must:
-
-1. **Provide the workflowId parameter** - This is mandatory for all workflow step changes
-2. **Use internal IDs** for itemId, languageId, and workflowStepId parameters
-3. **Ensure the target workflow step exists** in the specified workflow
-
-**WORKFLOW ID REQUIREMENT**: The workflowId parameter identifies which workflow contains the target step. Different content types may use different workflows, so always specify the correct workflow ID when changing workflow steps.
-
-**Example**: To move a language variant to a "review" step:
-- itemId: "content_item_internal_id"
-- languageId: "language_internal_id" 
-- workflowStepId: "review_step_internal_id"
-- workflowId: "workflow_internal_id" (MANDATORY)
-
-**Failure to provide the workflowId parameter will result in workflow step change failures.**
-
-
-## Essential Concepts
-
-**Taxonomies** provide hierarchical content categorization, allowing you to organize and tag content systematically.
-
-**Assets** are digital files including images, videos, and documents that can be referenced throughout your content.
-
-**Workflow states** manage the content lifecycle, tracking whether content is being drafted, is live, or has been archived.
-
-**Internal IDs** are unique identifiers that provide fast and reliable access to content entities. **ALWAYS use internal IDs when working with MCP tools for better performance and reliability.**
-
-**Codenames** are human-readable unique identifiers that provide a consistent way to reference content programmatically, but should be used primarily for readability and debugging.
-
-## Best Practices
-
-**CRITICAL**: Never assume the current time. Always obtain the current date and time when needed for time-sensitive operations like scheduling. If the current date and time in UTC format cannot be decisively obtained by any available tool, force the user to specify the current date and time explicitly.
-
-Use snippets for common field groups to maintain consistency and avoid duplication. Plan your content types before creating content to ensure proper structure. **Always use internal IDs when working with MCP tools** for optimal performance and reliability. Leverage taxonomies for organization to create logical content hierarchies. Consider your multilingual strategy early in the planning process to avoid restructuring later.
-
-When working with snippets, always retrieve and understand the complete element structure before creating content variants.
-
-When working with taxonomy elements, always retrieve and understand the taxonomy group structure and available terms before creating content variants. **NEVER leave taxonomy elements empty - all taxonomy elements must be properly categorized using internal IDs.**
-
-## MCP Tool Usage Guidelines
-
-### ID Reference Preferences
-
-**CRITICAL**: When using MCP tools, always prefer internal IDs over codenames:
-
-- **Content Items**: Use internal IDs to reference content items
-- **Language Variants**: Use internal IDs for both item and language references
-- **Content Types**: Use internal IDs to reference content types
-- **Taxonomy Terms**: Use internal IDs when referencing taxonomy terms
-- **Assets**: Use internal IDs when referencing assets
-- **Workflow Steps**: Use internal IDs for workflow step references
-
-**Why Internal IDs?** Internal IDs provide:
-- Better performance (faster lookups)
-- Immutability (won't change if names change)
-- Reliability (consistent across environments)
-- API efficiency (direct database lookups)
-
-**When to use codenames?** Codenames are useful for:
-- Human readability during development
-- Debugging and logging
-- Initial content setup when IDs are not yet known
-
-All MCP tools have been optimized to work with internal IDs for maximum efficiency.
-
-### Content Search Tools
-
-**CRITICAL DISTINCTION**:
-- **search-variants-mapi**: Finds content WHERE THE MAIN TOPIC matches a concept (e.g., "articles about wildlife")
-- **filter-variants-mapi**: Finds SPECIFIC WORDS anywhere in content, regardless of topic (e.g., brand compliance, detecting prohibited terms in any content)
-
-See each tool's description for detailed usage guidelines.
-
-## Response Optimization
-
-**IMPORTANT**: Empty values are automatically removed from ALL entity responses (content items, variants, content types, assets, taxonomies) to reduce token usage.
-
-### Empty Element Patterns in Variants
-
-Elements with these values are removed entirely from variant responses:
-
-| Element Type | Empty Value | Removed Form |
-|--------------|------------|--------------|
-| text | "" | {"element": {"id": "uuid"}, "value": ""} |
-| rich_text | "<p><br/></p>" | {"element": {"id": "uuid"}, "value": "<p><br/></p>", "components": []} |
-| number | null | {"element": {"id": "uuid"}, "value": null} |
-| date_time | null | {"element": {"id": "uuid"}, "value": null, "display_timezone": null} |
-| asset, modular_content, subpages, multiple_choice, taxonomy | [] | {"element": {"id": "uuid"}, "value": []} |
-| url_slug | "" + autogenerated | {"element": {"id": "uuid"}, "mode": "autogenerated", "value": ""} |
-| custom | null | {"element": {"id": "uuid"}, "value": null, "searchable_value": null} |
-
-### Understanding Missing Properties
-
-**Missing property = has default/empty value across ALL entities:**
-
-**Variants:**
-- Missing element → See table above for defaults
-- Components → Recursively optimized
-
-**Content Types:**
-- content_groups → []
-- allowed_content_types → []
-- allowed_blocks/formatting → []
-- validation_regex → not active
-- default values → null/""
-
-**All Entities:**
-- Empty arrays → []
-- Empty objects → {}
-- Null values → removed
-- Empty strings → ""`;

package/build/tools/get-initial-context.js

@@ -1,13 +0,0 @@
-import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
-import { initialContext } from "./context/initial-context.js";
-import { patchOperationsGuide } from "./context/patch-operations-guide.js";
-export const registerTool = (server) => {
-    server.tool("get-initial-context", "🚨 MANDATORY FIRST STEP: This tool MUST be called before using ANY other tools. It provides essential context, configuration, and operational guidelines for Kontent.ai. If you have not called this tool, do so immediately before proceeding with any other operation.", {}, async () => {
-        try {
-            return createMcpToolSuccessResponse(`${initialContext}\n\n${patchOperationsGuide}`);
-        }
-        catch (error) {
-            throw new Error(`Failed to read initial context: ${error instanceof Error ? error.message : "Unknown error"}`);
-        }
-    });
-};