@kontent-ai/mcp-server 0.21.9 → 0.21.11

package/build/tools/context/patch-operations-guide.js

@@ -0,0 +1,58 @@
+export const patchOperationsGuide = `
+# Content Type Patch Operations Guide
+
+## Overview
+Modify content types using RFC 6902 JSON Patch operations: move, addInto, remove, replace.
+
+## Critical Requirements
+- **Always call get-type-mapi first** to get current schema
+- **Use addInto/remove for arrays** (elements, allowed_content_types, allowed_blocks, etc.)
+- **Never use replace for array properties** - use addInto/remove instead
+- **Use replace for primitives/objects** (name, maximum_text_length, validation_regex)
+- **external_id and type cannot be modified** after creation
+- **When adding allowed_formatting/allowed_table_formatting**, 'unstyled' must be first
+
+## Operation Types
+
+### move
+Reorganize elements, options, or content groups using 'before' or 'after' reference.
+
+### addInto
+Add new items to arrays. Use for all array operations (elements, options, allowed_blocks, etc.).
+
+### remove
+Delete items from arrays or remove elements/groups.
+
+### replace
+Update primitives and objects. Cannot modify external_id, id, or type.
+
+## Path Formats
+Use JSON Pointer with id:{uuid} format:
+- Element: /elements/id:{uuid}
+- Element property: /elements/id:{uuid}/name
+- Option: /elements/id:{uuid}/options/id:{uuid}
+- Content group: /content_groups/id:{uuid}
+- Array item: /elements/id:{uuid}/allowed_content_types/id:{uuid}
+
+## Rich Text Properties
+- **allowed_content_types**: Content types for components/linked items (empty=all)
+- **allowed_item_link_types**: Content types for text links (empty=all)
+- **allowed_blocks**: "images", "text", "tables", "components-and-items" (empty=all)
+- **allowed_image_types**: "adjustable" or "any"
+- **allowed_text_blocks**: "paragraph", "heading-one" through "heading-six", "ordered-list", "unordered-list" (empty=all)
+- **allowed_formatting**: "unstyled", "bold", "italic", "code", "link", "subscript", "superscript" (empty=all, unstyled must be first)
+- **allowed_table_blocks**: "images", "text" (empty=both)
+- **allowed_table_text_blocks**: Same as allowed_text_blocks (empty=all)
+- **allowed_table_formatting**: Same as allowed_formatting (empty=all, unstyled must be first)
+
+## Special Techniques
+- **Remove content groups**: Set ALL elements' content_group to null AND remove ALL groups in one request
+- **URL Slug with snippet**: Add snippet element first, then URL slug with depends_on reference
+
+## Best Practices
+- Use descriptive codenames
+- Group related operations in single request
+- Use id:{uuid} format in paths
+- Validate dependencies before adding URL slugs
+- Consider element ordering for move operations
+`;

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

@@ -3,15 +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("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.", {
-        itemId: z
-            .string()
-            .uuid()
-            .describe("Internal ID (UUID) of the content item whose language variant you want to create a new version of"),
+    server.tool("create-variant-version-mapi", "Create new version of Kontent.ai variant", {
+        itemId: z.string().uuid().describe("Content item UUID"),
         languageId: z
             .string()
             .uuid()
-            .describe("Internal ID (UUID) of the language variant to create a new version of. Use '00000000-0000-0000-0000-000000000000' for the default language"),
+            .describe("Language variant UUID (default: 00000000-0000-0000-0000-000000000000)"),
     }, async ({ itemId, languageId }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

package/build/tools/delete-content-item-mapi.js

@@ -3,8 +3,8 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("delete-content-item-mapi", "Delete Kontent.ai content item by internal ID from Management API", {
-        id: z.string().describe("Internal ID of the content item to delete"),
+    server.tool("delete-content-item-mapi", "Delete Kontent.ai content item", {
+        id: z.string().describe("Item ID"),
     }, async ({ id }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

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

@@ -3,8 +3,8 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("delete-content-type-mapi", "Delete a content type by codename from Management API", {
-        codename: z.string().describe("Codename of the content type to delete"),
+    server.tool("delete-content-type-mapi", "Delete Kontent.ai content type by codename", {
+        codename: z.string().describe("Content type codename"),
     }, async ({ codename }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

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

@@ -3,11 +3,9 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("delete-language-variant-mapi", "Delete Kontent.ai language variant from Management API", {
-        itemId: z.string().describe("Internal ID of the content item"),
-        languageId: z
-            .string()
-            .describe("Internal ID of the language variant to delete"),
+    server.tool("delete-language-variant-mapi", "Delete Kontent.ai variant", {
+        itemId: z.string().describe("Item ID"),
+        languageId: z.string().describe("Language variant ID"),
     }, async ({ itemId, languageId }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

package/build/tools/filter-variants-mapi.js

@@ -1,31 +1,17 @@
 import { createMapiClient } from "../clients/kontentClients.js";
 import { filterVariantsSchema } from "../schemas/filterVariantSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
-import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+import { createVariantMcpToolSuccessResponse } from "../utils/responseHelper.js";
 import { throwError } from "../utils/throwError.js";
 export const registerTool = (server) => {
-    server.tool("filter-variants-mapi", `Filter Kontent.ai language variants of content items using Management API.
-
-    USE FOR:
-    - EXACT keyword matching: finding specific words, phrases, names, codes, or IDs anywhere in content, regardless of overall topic
-      ✓ Example: 'find items containing rabbit' → search 'rabbit'
-    - Brand guideline compliance: detecting prohibited terms across all content
-      ✓ Example: Search "hunt beast prey" to find content containing ANY of these terms (natural OR operator)
-    - CAN expand concepts to keywords when using filter (e.g., "neurology-related" → "neurology neurological brain nervous system")
-    - Advanced filtering by content type, contributors, workflow steps, taxonomies etc
-    - Also use as fallback when AI search is unavailable
-    - Optionally includes full content of variants with include_content parameter
-
-    BEST FOR: Finding needles in haystacks - specific words in otherwise unrelated content. Multiple search terms use OR logic.`, filterVariantsSchema.shape, async ({ search_phrase, content_types, contributors, has_no_contributors, completion_statuses, language, workflow_steps, taxonomy_groups, order_by, order_direction, include_content, }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("filter-variants-mapi", "Filter Kontent.ai variants. For EXACT keyword matching and compliance (terms use OR). Use search-variants-mapi for semantic/topic search.", filterVariantsSchema.shape, async ({ search_phrase, content_types, contributors, has_no_contributors, completion_statuses, language, workflow_steps, taxonomy_groups, order_by, order_direction, include_content, continuation_token, }, { authInfo: { token, clientId } = {} }) => {
         try {
             const environmentId = clientId ?? process.env.KONTENT_ENVIRONMENT_ID;
             if (!environmentId) {
                 throwError("Missing required environment ID");
             }
             const client = createMapiClient(environmentId, token);
-            const response = await client.earlyAccess
-                .filterLanguageVariants()
-                .withData({
+            const query = client.earlyAccess.filterLanguageVariants().withData({
                 filters: {
                     search_phrase,
                     content_types,
@@ -43,9 +29,16 @@ export const registerTool = (server) => {
                     }
                     : undefined,
                 include_content: include_content ?? false,
-            })
-                .toAllPromise();
-            return createMcpToolSuccessResponse(response.responses.flatMap((r) => r.rawData.data));
+            });
+            const response = await (continuation_token
+                ? query.xContinuationToken(continuation_token)
+                : query).toPromise();
+            return createVariantMcpToolSuccessResponse({
+                data: response.rawData.data,
+                pagination: {
+                    continuation_token: response.data.pagination.continuationToken,
+                },
+            });
         }
         catch (error) {
             return handleMcpToolError(error, "Variant Filter");

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

@@ -3,8 +3,8 @@ 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 a specific Kontent.ai asset by internal ID from Management API", {
-        assetId: z.string().describe("Internal ID of the asset to retrieve"),
+    server.tool("get-asset-mapi", "Get Kontent.ai asset by ID", {
+        assetId: z.string().describe("Asset ID"),
     }, async ({ assetId }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

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

@@ -1,9 +1,10 @@
 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);
+            return createMcpToolSuccessResponse(`${initialContext}\n\n${patchOperationsGuide}`);
         }
         catch (error) {
             throw new Error(`Failed to read initial context: ${error instanceof Error ? error.message : "Unknown error"}`);

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

@@ -3,8 +3,8 @@ 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 internal ID from Management API", {
-        id: z.string().describe("Internal ID of the item to get"),
+    server.tool("get-item-mapi", "Get Kontent.ai item by ID", {
+        id: z.string().describe("Item ID"),
     }, async ({ id }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

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

@@ -3,8 +3,8 @@ 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 internal ID from Management API", {
-        id: z.string().describe("Internal ID of the taxonomy group to get"),
+    server.tool("get-taxonomy-group-mapi", "Get Kontent.ai taxonomy group by ID", {
+        id: z.string().describe("Taxonomy group ID"),
     }, async ({ id }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

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

@@ -3,8 +3,8 @@ 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 internal ID from Management API", {
-        id: z.string().describe("Internal ID of the content type to get"),
+    server.tool("get-type-mapi", "Get Kontent.ai content type by ID", {
+        id: z.string().describe("Content type ID"),
     }, async ({ id }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

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

@@ -3,8 +3,8 @@ 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 internal ID from Management API", {
-        id: z.string().describe("Internal ID of the content type snippet to get"),
+    server.tool("get-type-snippet-mapi", "Get Kontent.ai content type snippet by ID", {
+        id: z.string().describe("Snippet ID"),
     }, async ({ id }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

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

@@ -1,13 +1,11 @@
 import { z } from "zod";
 import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
-import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+import { createVariantMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-variant-mapi", "Get Kontent.ai language variant of content item from Management API", {
-        itemId: z.string().describe("Internal ID of the content item"),
-        languageId: z
-            .string()
-            .describe("Internal ID of the language variant to get"),
+    server.tool("get-variant-mapi", "Get Kontent.ai variant", {
+        itemId: z.string().describe("Item ID"),
+        languageId: z.string().describe("Language variant ID"),
     }, async ({ itemId, languageId }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
@@ -16,7 +14,7 @@ export const registerTool = (server) => {
                 .byItemId(itemId)
                 .byLanguageId(languageId)
                 .toPromise();
-            return createMcpToolSuccessResponse(response.rawData);
+            return createVariantMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Language Variant Retrieval");

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

@@ -1,13 +1,21 @@
 import { createMapiClient } from "../clients/kontentClients.js";
+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 from Management API", {}, async (_, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-assets-mapi", "Get all Kontent.ai assets (paginated)", listAssetsSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
-            const response = await client.listAssets().toAllPromise();
-            const rawData = response.responses.flatMap((r) => r.rawData.assets);
-            return createMcpToolSuccessResponse(rawData);
+            const query = client.listAssets();
+            const response = await (continuation_token
+                ? query.xContinuationToken(continuation_token)
+                : query).toPromise();
+            return createMcpToolSuccessResponse({
+                data: response.rawData.assets,
+                pagination: {
+                    continuation_token: response.data.pagination.continuationToken,
+                },
+            });
         }
         catch (error) {
             return handleMcpToolError(error, "Assets Listing");

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

@@ -1,13 +1,21 @@
 import { createMapiClient } from "../clients/kontentClients.js";
+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 from Management API", {}, async (_, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-content-type-snippets-mapi", "Get all Kontent.ai content type snippets (paginated)", listContentTypeSnippetsSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
-            const response = await client.listContentTypeSnippets().toAllPromise();
-            const rawData = response.responses.flatMap((r) => r.rawData.snippets);
-            return createMcpToolSuccessResponse(rawData);
+            const query = client.listContentTypeSnippets();
+            const response = await (continuation_token
+                ? query.xContinuationToken(continuation_token)
+                : query).toPromise();
+            return createMcpToolSuccessResponse({
+                data: response.rawData.snippets,
+                pagination: {
+                    continuation_token: response.data.pagination.continuationToken,
+                },
+            });
         }
         catch (error) {
             return handleMcpToolError(error, "Content Type Snippets Listing");

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

@@ -1,13 +1,21 @@
 import { createMapiClient } from "../clients/kontentClients.js";
+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 from Management API", {}, async (_, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-content-types-mapi", "Get all Kontent.ai content types (paginated)", listContentTypesSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
-            const response = await client.listContentTypes().toAllPromise();
-            const rawData = response.responses.flatMap((r) => r.rawData.types);
-            return createMcpToolSuccessResponse(rawData);
+            const query = client.listContentTypes();
+            const response = await (continuation_token
+                ? query.xContinuationToken(continuation_token)
+                : query).toPromise();
+            return createMcpToolSuccessResponse({
+                data: response.rawData.types,
+                pagination: {
+                    continuation_token: response.data.pagination.continuationToken,
+                },
+            });
         }
         catch (error) {
             return handleMcpToolError(error, "Content Types Listing");

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

@@ -1,13 +1,21 @@
 import { createMapiClient } from "../clients/kontentClients.js";
+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 from Management API", {}, async (_, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-languages-mapi", "Get all Kontent.ai languages (paginated)", listLanguagesSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
-            const response = await client.listLanguages().toAllPromise();
-            const rawData = response.responses.flatMap((r) => r.rawData.languages);
-            return createMcpToolSuccessResponse(rawData);
+            const query = client.listLanguages();
+            const response = await (continuation_token
+                ? query.xContinuationToken(continuation_token)
+                : query).toPromise();
+            return createMcpToolSuccessResponse({
+                data: response.rawData.languages,
+                pagination: {
+                    continuation_token: response.data.pagination.continuationToken,
+                },
+            });
         }
         catch (error) {
             return handleMcpToolError(error, "Languages Listing");

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

@@ -1,13 +1,21 @@
 import { createMapiClient } from "../clients/kontentClients.js";
+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 from Management API", {}, async (_, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-taxonomy-groups-mapi", "Get all Kontent.ai taxonomy groups (paginated)", listTaxonomyGroupsSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
-            const response = await client.listTaxonomies().toAllPromise();
-            const rawData = response.responses.flatMap((r) => r.rawData.taxonomies);
-            return createMcpToolSuccessResponse(rawData);
+            const query = client.listTaxonomies();
+            const response = await (continuation_token
+                ? query.xContinuationToken(continuation_token)
+                : query).toPromise();
+            return createMcpToolSuccessResponse({
+                data: response.rawData.taxonomies,
+                pagination: {
+                    continuation_token: response.data.pagination.continuationToken,
+                },
+            });
         }
         catch (error) {
             return handleMcpToolError(error, "Taxonomy Groups Listing");

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 from Management API. Workflows define the content lifecycle stages and transitions between them.", {}, async (_, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-workflows-mapi", "Get all Kontent.ai workflows", {}, async (_, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const response = await client.listWorkflows().toPromise();

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

@@ -4,56 +4,9 @@ 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 an existing Kontent.ai content type by codename via Management API. Supports move, addInto, remove, and replace operations following RFC 6902 JSON Patch specification.", {
-        codename: z.string().describe("Codename of the content type to update"),
-        operations: patchOperationsSchema.describe(`Array of patch operations to apply. Supports: 'move' (reorganize elements), 'addInto' (add new elements), 'remove' (delete elements), 'replace' (update existing elements/properties).
-        
-        CRITICAL REQUIREMENTS:
-        - ALWAYS call get-type-mapi tool before patching to get the latest content type schema
-        - Use addInto/remove for array operations (adding/removing items from arrays like elements and element's array properties - allowed_content_types, allowed_item_link_types, allowed_blocks, allowed_text_blocks, allowed_formatting, allowed_table_blocks, allowed_table_text_blocks, allowed_table_formatting)
-        - Never ever use replace for element's array properties - use addInto/remove instead
-        - Use replace for element's primitive data types and object properties (maximum_text_length, validation_regex, etc.)
-        - External_id and type cannot be modified after creation
-        - Patch operations with URL Slug elements referencing snippet elements MUST ensure snippet is present first
-        - When adding to allowed_formatting or allowed_table_formatting, 'unstyled' must be the first item in the array. If it is not present, then add it as first operation.
-        
-        RICH TEXT ELEMENT PROPERTIES:
-        - allowed_content_types: Array of content type references. Specifies allowed content types for components and linked items. Empty array allows all.
-        - allowed_item_link_types: Array of content type references. Specifies content types allowed in text links (applies to text and tables). Empty array allows all.
-        - allowed_blocks: Available options: "images", "text", "tables", "components-and-items". Empty array allows all blocks.
-        - allowed_image_types: Available options: "adjustable" (only transformable images), "any" (all image files).
-        - allowed_text_blocks: Available options: "paragraph", "heading-one", "heading-two", "heading-three", "heading-four", "heading-five", "heading-six", "ordered-list", "unordered-list". Empty array allows all.
-        - allowed_formatting: Available options: "unstyled", "bold", "italic", "code", "link", "subscript", "superscript". "unstyled" must be first if used. Empty array allows all.
-        - allowed_table_blocks: Available options: "images", "text". Use ["text"] for text-only or empty array for both text and images.
-        - allowed_table_text_blocks: Available options: "paragraph", "heading-one", "heading-two", "heading-three", "heading-four", "heading-five", "heading-six", "ordered-list", "unordered-list". Empty array allows all.
-        - allowed_table_formatting: Available options: "unstyled", "bold", "italic", "code", "link", "subscript", "superscript". "unstyled" must be first if used. Empty array allows all.
-        
-        OPERATION TYPES:
-        1. move: Reorganize elements, options, or content groups. Uses 'before' or 'after' reference.
-        2. addInto: Add new elements, options, content groups, or array items. Use for all array operations.
-        3. remove: Remove elements, options, content groups, or array items. Use for all array removals.
-        4. replace: Update existing properties of primitive data types and objects. Cannot modify external_id, id, or type.
-        
-        PATH FORMATS:
-        - Use JSON Pointer paths with id:{uuid} format for referencing objects
-        - Element: /elements/id:123e4567-e89b-12d3-a456-426614174000
-        - Element property: /elements/id:123e4567-e89b-12d3-a456-426614174000/name
-        - Multiple choice option: /elements/id:123e4567-e89b-12d3-a456-426614174000/options/id:987fcdeb-51a2-43d1-9f4e-123456789abc
-        - Content group: /content_groups/id:456e7890-a12b-34c5-d678-901234567def
-        - Rich text array property: /elements/id:123e4567-e89b-12d3-a456-426614174000/allowed_content_types/id:987fcdeb-51a2-43d1-9f4e-123456789abc
-        
-        SPECIAL TECHNIQUES:
-        - To remove content groups while keeping elements: Set ALL elements' content_group to null AND remove ALL content groups in ONE request (atomic operation)
-        - URL Slug with snippet dependency: First add snippet element, then add URL slug with depends_on reference
-        
-        BEST PRACTICES:
-        - Use descriptive codenames following naming conventions
-        - Group related operations in a single patch request when possible
-        - Use proper reference formats (id:{uuid}) in paths
-        - Validate element dependencies before adding URL slug elements
-        - Consider element ordering when using move operations
-        - Use atomic operations for complex changes like removing content groups
-        - When adding to allowed_formatting or allowed_table_formatting, always ensure 'unstyled' is the first item in the array`),
+    server.tool("patch-content-type-mapi", "Update Kontent.ai content type using JSON Patch (move, addInto, remove, replace)", {
+        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 } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

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

@@ -3,24 +3,21 @@ 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 a language variant of a content item in Kontent.ai. This operation can either immediately publish the variant (publishing happens right now) or schedule it for publication at a specific future date and time. For immediate publishing: the variant is published immediately and becomes available through the Delivery API. For scheduled publishing: the variant moves to a 'Scheduled' workflow state and will automatically transition to 'Published' at the specified time. The variant must be in a valid state with all required fields filled and validation rules satisfied. A variant can only be published if a transition is defined between the variant's current workflow step and the Published workflow step.", {
-        itemId: z
-            .string()
-            .uuid()
-            .describe("Internal ID (UUID) of the content item whose language variant you want to publish or schedule. This identifies the content item container that holds all language variants."),
+    server.tool("publish-variant-mapi", "Publish or schedule Kontent.ai variant", {
+        itemId: z.string().uuid().describe("Content item UUID"),
         languageId: z
             .string()
             .uuid()
-            .describe("Internal ID (UUID) of the language variant to publish or schedule. Use '00000000-0000-0000-0000-000000000000' for the default language. Each language in your project has a unique ID that identifies the specific variant."),
+            .describe("Language variant UUID (default: 00000000-0000-0000-0000-000000000000)"),
         scheduledTo: z
             .string()
             .datetime({ offset: true })
             .optional()
-            .describe("ISO 8601 formatted date and time when the publish action should occur (e.g., '2024-12-25T10:00:00Z' for UTC or '2024-12-25T10:00:00+02:00' for specific timezone). If not provided, the variant will be published immediately. If provided, must be a future date/time. The actual execution may have up to 5 minutes delay from the specified time."),
+            .describe("ISO 8601 datetime for scheduled publish (omit for immediate)"),
         displayTimezone: z
             .string()
             .optional()
-            .describe("The timezone identifier for displaying the scheduled time in the Kontent.ai UI (e.g., 'America/New_York', 'Europe/London', 'UTC'). This parameter is used for scheduled publishing to specify the timezone context for the scheduled_to parameter. If not provided, the system will use the default timezone. This helps content creators understand when content will be published in their local context."),
+            .describe("Timezone for UI display (e.g., America/New_York, UTC)"),
     }, async ({ itemId, languageId, scheduledTo, displayTimezone }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

package/build/tools/search-variants-mapi.js

@@ -2,7 +2,7 @@ import pRetry, { AbortError } from "p-retry";
 import { createMapiClient } from "../clients/kontentClients.js";
 import { searchOperationSchema } from "../schemas/searchOperationSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
-import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+import { createMcpToolSuccessResponse, createVariantMcpToolSuccessResponse, } from "../utils/responseHelper.js";
 import { throwError } from "../utils/throwError.js";
 class OperationResultIncompleteError extends Error {
     constructor() {
@@ -11,33 +11,7 @@ class OperationResultIncompleteError extends Error {
     }
 }
 export const registerTool = (server) => {
-    server.tool("search-variants-mapi", `AI-powered semantic search for finding Kontent.ai content by meaning, concepts, themes, and content similarity in a specific language variant. This tool uses vector database and AI to enable searching by meaning and similarity rather than exact keyword matching.
-
-    CRITICAL REQUIREMENTS:
-    - The AI search feature may not be available for all Kontent.ai environments
-    - If you receive an "unavailable" status response, DO NOT attempt to use this tool again in the same session
-    - Use filter-variants-mapi for exact text matching when semantic search is unavailable
-    - Requires language variant filter parameter (e.g., default language '00000000-0000-0000-0000-000000000000')
-    - The tool always RETURNS ONLY TOP 50 most relevant items at max
-    - Limited filtering options (only by variant ID) - use filter-variants-mapi for advanced filtering by content types, workflow steps, taxonomies, etc.
-
-    USE FOR:
-    - Finding content WHERE THE OVERALL TOPIC/THEME matches a concept
-      ✓ Example: "fairy tales" → finds articles primarily about fairy tales
-      ✓ Example: "beverage temperature control" → finds content focused on keeping drinks cold/hot
-    - Content similarity: Finding articles with similar overall themes
-    - Thematic content discovery when the main subject matter is what you're looking for
-
-    DO NOT USE FOR:
-    - Finding specific words scattered in otherwise unrelated content
-      ✗ Example: Finding "challenge" term in articles about various topics (use filter-variants-mapi)
-    - Brand guideline violations or prohibited term detection (use filter-variants-mapi)
-    - Compliance audits looking for specific keywords (use filter-variants-mapi)
-    - Finding exhaustive and exact number of results (use filter-variants-mapi)
-
-    CRITICAL: This is SEMANTIC search for topic matching. Pass natural language concepts AS-IS. DO NOT generate keyword lists or concatenate multiple keywords.
-    ✓ CORRECT: "animal predators" or "articles about temperature control"
-    ✗ WRONG: "animal beast creature wild hunt predator prey attack"`, searchOperationSchema.shape, async ({ searchPhrase, filter }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("search-variants-mapi", "AI semantic search for Kontent.ai content by topic/theme (max 50 results). Use filter-variants-mapi for exact keywords. May be unavailable.", searchOperationSchema.shape, async ({ searchPhrase, filter }, { authInfo: { token, clientId } = {} }) => {
         try {
             const environmentId = clientId ?? process.env.KONTENT_ENVIRONMENT_ID;
             if (!environmentId) {
@@ -110,7 +84,7 @@ export const registerTool = (server) => {
                 maxTimeout: 10000,
                 factor: 1.5,
             });
-            return createMcpToolSuccessResponse({
+            return createVariantMcpToolSuccessResponse({
                 result: resultData,
             });
         }

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

@@ -3,24 +3,21 @@ 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 a language variant of a content item in Kontent.ai. This operation can either immediately unpublish the variant (making it unavailable through the Delivery API) or schedule it for unpublishing at a specific future date and time. For immediate unpublishing: the variant is unpublished right away and moves to the 'Archived' workflow step, becoming unavailable through the Delivery API. For scheduled unpublishing: the variant remains published but is scheduled to be automatically unpublished at the specified time. The variant must currently be in the 'Published' state for this operation to succeed.", {
-        itemId: z
-            .string()
-            .uuid()
-            .describe("Internal ID (UUID) of the content item whose language variant you want to unpublish or schedule for unpublishing. This identifies the content item container that holds all language variants."),
+    server.tool("unpublish-variant-mapi", "Unpublish or schedule unpublishing of Kontent.ai variant", {
+        itemId: z.string().uuid().describe("Content item UUID"),
         languageId: z
             .string()
             .uuid()
-            .describe("Internal ID (UUID) of the language variant to unpublish or schedule for unpublishing. Use '00000000-0000-0000-0000-000000000000' for the default language. Each language in your project has a unique ID that identifies the specific variant."),
+            .describe("Language variant UUID (default: 00000000-0000-0000-0000-000000000000)"),
         scheduledTo: z
             .string()
             .datetime({ offset: true })
             .optional()
-            .describe("ISO 8601 formatted date and time when the unpublish action should occur (e.g., '2024-12-25T10:00:00Z' for UTC or '2024-12-25T10:00:00+02:00' for specific timezone). If not provided, the variant will be unpublished immediately. If provided, must be a future date/time. The actual execution may have up to 5 minutes delay from the specified time. When unpublished, the content will no longer be available through the Delivery API."),
+            .describe("ISO 8601 datetime for scheduled unpublish (omit for immediate)"),
         displayTimezone: z
             .string()
             .optional()
-            .describe("The timezone identifier for displaying the scheduled time in the Kontent.ai UI (e.g., 'America/New_York', 'Europe/London', 'UTC'). This parameter is used for scheduled unpublishing to specify the timezone context for the scheduled_to parameter. If not provided, the system will use the default timezone. This helps content creators understand when content will be unpublished in their local context."),
+            .describe("Timezone for UI display (e.g., America/New_York, UTC)"),
     }, async ({ itemId, languageId, scheduledTo, displayTimezone }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {