@kontent-ai/mcp-server 0.21.11 → 0.23.0

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
 
@@ -89,11 +89,17 @@ npx @kontent-ai/mcp-server@latest shttp
 
 * **get-item-mapi** – Get Kontent.ai item by internal ID from Management API
 * **get-item-dapi** – Get Kontent.ai item by codename from Delivery API
-* **get-variant-mapi** – Get Kontent.ai language variant of content item from Management API
+* **get-latest-variant-mapi** – Get latest version of Kontent.ai language variant from Management API
+* **get-published-variant-mapi** – Get published version of Kontent.ai language variant from Management API
+* **list-variants-item-mapi** – List all Kontent.ai language variants of a content item from Management API
+* **list-variants-collection-mapi** – List Kontent.ai language variants by collection from Management API (paginated)
+* **list-variants-type-mapi** – List Kontent.ai language variants by content type from Management API (paginated)
+* **list-variants-components-type-mapi** – List Kontent.ai language variants containing components of a specific content type from Management API (paginated)
+* **list-variants-space-mapi** – List Kontent.ai language variants by space from Management API (paginated)
 * **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
@@ -107,6 +113,17 @@ npx @kontent-ai/mcp-server@latest shttp
 ### Language Management
 
 * **list-languages-mapi** – Get all Kontent.ai languages from Management API
+* **add-language-mapi** – Add new Kontent.ai language via Management API
+* **patch-language-mapi** – Update Kontent.ai language using replace operations via Management API
+
+### Collection Management
+
+* **list-collections-mapi** – Get all Kontent.ai collections from Management API. Collections set boundaries for content items in your environment and help organize content by team, brand, or project
+* **patch-collections-mapi** – Update Kontent.ai collections using patch operations (addInto to add new collections, move to reorder, remove to delete empty collections, replace to rename)
+
+### Space Management
+
+* **list-spaces-mapi** – Get all Kontent.ai spaces from Management API
 
 ### Workflow Management
 
@@ -217,7 +234,8 @@ Then configure your MCP client:
 
 No environment variables required. The server accepts requests for multiple environments using URL path parameters and Bearer authentication.
 
-##### VS Code Configuration
+<details>
+<summary><strong>VS Code</strong></summary>
 
 Create a `.vscode/mcp.json` file in your workspace:
 
@@ -261,7 +279,10 @@ For secure configuration with input prompts:
 }
 ```
 
-##### Claude Desktop Configuration
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
 
 Update your Claude Desktop configuration file:
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
@@ -286,32 +307,25 @@ Use `mcp-remote` as a proxy to add authentication headers:
 }
 ```
 
-##### Claude Code Configuration
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
 
-For Claude Code (claude.ai/code), add the server configuration:
+Add the server using the CLI:
 
 ```bash
-# Add the multi-tenant server
-claude mcp add \
-  --url "http://localhost:3001/<environment-id>/mcp" \
-  --header "Authorization: Bearer <management-api-key>" \
-  kontent-ai-multi
+claude mcp add --transport http kontent-ai-multi \
+  "http://localhost:3001/<environment-id>/mcp" \
+  --header "Authorization: Bearer <management-api-key>"
 ```
 
-Or configure directly in the settings:
+> **Note**: You can also configure this in your Claude Code settings JSON with the `url` and `headers` properties.
 
-```json
-{
-  "kontent-ai-multi": {
-    "url": "http://localhost:3001/<environment-id>/mcp",
-    "headers": {
-      "Authorization": "Bearer <management-api-key>"
-    }
-  }
-}
-```
+</details>
 
-**Important**: Replace `<environment-id>` with your actual Kontent.ai environment ID (GUID format) and `<management-api-key>` with your Management API key.
+> [!IMPORTANT]
+> Replace `<environment-id>` with your Kontent.ai environment ID (GUID) and `<management-api-key>` with your Management API key.
 
 ## 💻 Development
 

package/build/schemas/collectionSchemas.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { referenceObjectSchema } from "./referenceObjectSchema.js";
+const addIntoOperationSchema = z.object({
+    op: z.literal("addInto"),
+    value: z.object({
+        name: z.string(),
+        codename: z.string().optional(),
+        external_id: z.string().optional(),
+    }),
+    before: referenceObjectSchema.optional(),
+    after: referenceObjectSchema.optional(),
+});
+const moveOperationSchema = z.object({
+    op: z.literal("move"),
+    reference: referenceObjectSchema,
+    before: referenceObjectSchema.optional(),
+    after: referenceObjectSchema.optional(),
+});
+const removeOperationSchema = z.object({
+    op: z.literal("remove"),
+    reference: referenceObjectSchema,
+});
+const replaceOperationSchema = z.object({
+    op: z.literal("replace"),
+    reference: referenceObjectSchema,
+    property_name: z.enum(["name"]),
+    value: z.string(),
+});
+export const collectionPatchOperationSchema = z.discriminatedUnion("op", [
+    addIntoOperationSchema,
+    moveOperationSchema,
+    removeOperationSchema,
+    replaceOperationSchema,
+]);
+export const collectionPatchOperationsSchema = z
+    .array(collectionPatchOperationSchema)
+    .min(1);

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/languageSchemas.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+import { referenceObjectSchema } from "./referenceObjectSchema.js";
+export const addLanguageSchema = z.object({
+    name: z.string().describe("Display name of the language"),
+    codename: z.string().describe("Codename identifier for the language"),
+    is_active: z
+        .boolean()
+        .optional()
+        .describe("Whether the language is active (defaults to true)"),
+    fallback_language: referenceObjectSchema
+        .optional()
+        .describe("Reference to fallback language (by id, codename, or external_id)"),
+    external_id: z.string().optional().describe("External ID for the language"),
+});
+const languageReplaceOperationSchema = z.discriminatedUnion("property_name", [
+    z.object({
+        op: z.literal("replace"),
+        property_name: z.literal("codename"),
+        value: z.string(),
+    }),
+    z.object({
+        op: z.literal("replace"),
+        property_name: z.literal("name"),
+        value: z.string(),
+    }),
+    z.object({
+        op: z.literal("replace"),
+        property_name: z.literal("is_active"),
+        value: z.boolean(),
+    }),
+    z.object({
+        op: z.literal("replace"),
+        property_name: z.literal("fallback_language"),
+        value: referenceObjectSchema,
+    }),
+]);
+export const patchLanguageSchema = z.object({
+    languageId: z.string().describe("Language ID to modify"),
+    operations: z
+        .array(languageReplaceOperationSchema)
+        .min(1)
+        .describe("Array of replace operations for codename, name, is_active, or fallback_language. Note: Only active languages can be modified - if language is deactivated, is_active: true must be first operation."),
+});

package/build/schemas/listSchemas.js

@@ -24,3 +24,19 @@ export const listContentTypeSnippetsSchema = z.object({
 export const listAssetsSchema = z.object({
     continuation_token: continuationTokenField,
 });
+export const listVariantsCollectionSchema = z.object({
+    collectionId: z.string().describe("Collection ID"),
+    continuation_token: continuationTokenField,
+});
+export const listVariantsTypeSchema = z.object({
+    contentTypeId: z.string().describe("Content type ID"),
+    continuation_token: continuationTokenField,
+});
+export const listVariantsComponentsTypeSchema = z.object({
+    contentTypeId: z.string().describe("Content type ID"),
+    continuation_token: continuationTokenField,
+});
+export const listVariantsSpaceSchema = z.object({
+    spaceId: z.string().describe("Space ID"),
+    continuation_token: continuationTokenField,
+});

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/taxonomySchemas.js

@@ -4,7 +4,7 @@ const taxonomyTermSchema = z.object({
     name: z.string(),
     codename: z.string().optional(),
     external_id: z.string().optional(),
-    terms: z.lazy(() => z.array(taxonomyTermSchema)),
+    terms: z.lazy(() => z.array(taxonomyTermSchema)).optional(),
 });
 // Schema for a taxonomy group
 export const taxonomyGroupSchemas = {
@@ -14,5 +14,8 @@ export const taxonomyGroupSchemas = {
         .optional()
         .describe("Codename (auto-generated if omitted)"),
     external_id: z.string().optional().describe("External ID"),
-    terms: z.array(taxonomyTermSchema).describe("Taxonomy terms hierarchy"),
+    terms: z
+        .array(taxonomyTermSchema)
+        .optional()
+        .describe("Taxonomy terms hierarchy"),
 };

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

@@ -3,6 +3,7 @@ import packageJson from "../package.json" with { type: "json" };
 import { registerTool as registerAddContentItemMapi } from "./tools/add-content-item-mapi.js";
 import { registerTool as registerAddContentTypeMapi } from "./tools/add-content-type-mapi.js";
 import { registerTool as registerAddContentTypeSnippetMapi } from "./tools/add-content-type-snippet-mapi.js";
+import { registerTool as registerAddLanguageMapi } from "./tools/add-language-mapi.js";
 import { registerTool as registerAddTaxonomyGroupMapi } from "./tools/add-taxonomy-group-mapi.js";
 import { registerTool as registerChangeVariantWorkflowStepMapi } from "./tools/change-variant-workflow-step-mapi.js";
 import { registerTool as registerCreateVariantVersionMapi } from "./tools/create-variant-version-mapi.js";
@@ -11,19 +12,29 @@ 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";
 import { registerTool as registerGetTypeSnippetMapi } from "./tools/get-type-snippet-mapi.js";
-import { registerTool as registerGetVariantMapi } from "./tools/get-variant-mapi.js";
 import { registerTool as registerListAssetsMapi } from "./tools/list-assets-mapi.js";
+import { registerTool as registerListCollectionsMapi } from "./tools/list-collections-mapi.js";
 import { registerTool as registerListContentTypeSnippetsMapi } from "./tools/list-content-type-snippets-mapi.js";
 import { registerTool as registerListContentTypesMapi } from "./tools/list-content-types-mapi.js";
 import { registerTool as registerListLanguagesMapi } from "./tools/list-languages-mapi.js";
+import { registerTool as registerListSpacesMapi } from "./tools/list-spaces-mapi.js";
 import { registerTool as registerListTaxonomyGroupsMapi } from "./tools/list-taxonomy-groups-mapi.js";
+import { registerTool as registerListVariantsCollectionMapi } from "./tools/list-variants-collection-mapi.js";
+import { registerTool as registerListVariantsComponentsTypeMapi } from "./tools/list-variants-components-type-mapi.js";
+import { registerTool as registerListVariantsItemMapi } from "./tools/list-variants-item-mapi.js";
+import { registerTool as registerListVariantsSpaceMapi } from "./tools/list-variants-space-mapi.js";
+import { registerTool as registerListVariantsTypeMapi } from "./tools/list-variants-type-mapi.js";
 import { registerTool as registerListWorkflowsMapi } from "./tools/list-workflows-mapi.js";
+import { registerTool as registerPatchCollectionsMapi } from "./tools/patch-collections-mapi.js";
 import { registerTool as registerPatchContentTypeMapi } from "./tools/patch-content-type-mapi.js";
+import { registerTool as registerPatchLanguageMapi } from "./tools/patch-language-mapi.js";
 import { registerTool as registerPublishVariantMapi } from "./tools/publish-variant-mapi.js";
 import { registerTool as registerSearchVariantsMapi } from "./tools/search-variants-mapi.js";
 import { registerTool as registerUnpublishVariantMapi } from "./tools/unpublish-variant-mapi.js";
@@ -34,19 +45,26 @@ 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);
-    registerGetVariantMapi(server);
+    registerGetLatestVariantMapi(server);
+    registerGetPublishedVariantMapi(server);
+    registerListVariantsItemMapi(server);
+    registerListVariantsCollectionMapi(server);
+    registerListVariantsTypeMapi(server);
+    registerListVariantsComponentsTypeMapi(server);
+    registerListVariantsSpaceMapi(server);
     registerGetTypeMapi(server);
     registerListContentTypesMapi(server);
     registerDeleteContentTypeMapi(server);
     registerListLanguagesMapi(server);
+    registerAddLanguageMapi(server);
+    registerPatchLanguageMapi(server);
+    registerListCollectionsMapi(server);
+    registerPatchCollectionsMapi(server);
+    registerListSpacesMapi(server);
     registerGetAssetMapi(server);
     registerListAssetsMapi(server);
     registerAddContentTypeMapi(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/utils/responseHelper.spec.js

@@ -53,18 +53,18 @@ describe("isEmptyOrDefault", () => {
     });
 });
 describe("removeEmptyValues", () => {
-    describe("primitive values", () => {
-        it("returns undefined for null", () => {
-            assert.strictEqual(removeEmptyValues(null), undefined);
+    describe("primitive values at root level - preserved as-is", () => {
+        it("returns null for null", () => {
+            assert.strictEqual(removeEmptyValues(null), null);
         });
         it("returns undefined for undefined", () => {
             assert.strictEqual(removeEmptyValues(undefined), undefined);
         });
-        it("returns undefined for empty string", () => {
-            assert.strictEqual(removeEmptyValues(""), undefined);
+        it("preserves empty string at root level", () => {
+            assert.strictEqual(removeEmptyValues(""), "");
         });
-        it("returns undefined for rich text empty paragraph", () => {
-            assert.strictEqual(removeEmptyValues("<p><br/></p>"), undefined);
+        it("preserves rich text empty paragraph at root level", () => {
+            assert.strictEqual(removeEmptyValues("<p><br/></p>"), "<p><br/></p>");
         });
         it("preserves non-empty string", () => {
             assert.strictEqual(removeEmptyValues("hello"), "hello");
@@ -77,14 +77,14 @@ describe("removeEmptyValues", () => {
         });
     });
     describe("arrays", () => {
-        it("returns undefined for empty array", () => {
-            assert.strictEqual(removeEmptyValues([]), undefined);
+        it("returns empty array for empty array at root level", () => {
+            assert.deepStrictEqual(removeEmptyValues([]), []);
         });
         it("removes empty values from array", () => {
             assert.deepStrictEqual(removeEmptyValues([1, null, 2, "", 3]), [1, 2, 3]);
         });
-        it("returns undefined when all array items are empty", () => {
-            assert.strictEqual(removeEmptyValues([null, "", [], {}]), undefined);
+        it("returns empty array when all array items are empty at root level", () => {
+            assert.deepStrictEqual(removeEmptyValues([null, "", [], {}]), []);
         });
         it("recursively cleans nested arrays", () => {
             assert.deepStrictEqual(removeEmptyValues([1, [2, null, 3], [null, ""]]), [
@@ -94,8 +94,8 @@ describe("removeEmptyValues", () => {
         });
     });
     describe("objects", () => {
-        it("returns undefined for empty object", () => {
-            assert.strictEqual(removeEmptyValues({}), undefined);
+        it("returns empty object for empty object at root level", () => {
+            assert.deepStrictEqual(removeEmptyValues({}), {});
         });
         it("removes null properties", () => {
             assert.deepStrictEqual(removeEmptyValues({ a: 1, b: null }), { a: 1 });
@@ -119,8 +119,8 @@ describe("removeEmptyValues", () => {
                 a: 1,
             });
         });
-        it("returns undefined when all properties are empty", () => {
-            assert.strictEqual(removeEmptyValues({ a: null, b: "", c: [], d: {} }), undefined);
+        it("returns empty object when all properties are empty at root level", () => {
+            assert.deepStrictEqual(removeEmptyValues({ a: null, b: "", c: [], d: {} }), {});
         });
     });
     describe("nested structures", () => {
@@ -448,3 +448,137 @@ describe("variant with all empty elements", () => {
         assert.deepStrictEqual(result, {}, "All empty elements should be removed, resulting in an empty object");
     });
 });
+describe("top-level empty value preservation", () => {
+    describe("createMcpToolSuccessResponse", () => {
+        it("returns empty array when input is empty array", () => {
+            const response = createMcpToolSuccessResponse([]);
+            const parsed = JSON.parse(response.content[0].text);
+            assert.deepStrictEqual(parsed, []);
+        });
+        it("returns empty object when input is empty object", () => {
+            const response = createMcpToolSuccessResponse({});
+            const parsed = JSON.parse(response.content[0].text);
+            assert.deepStrictEqual(parsed, {});
+        });
+        it("returns empty object when all properties are removed", () => {
+            const input = { a: null, b: "", c: [] };
+            const response = createMcpToolSuccessResponse(input);
+            const parsed = JSON.parse(response.content[0].text);
+            assert.deepStrictEqual(parsed, {});
+        });
+        it("returns empty array when all array items are removed", () => {
+            const input = [null, "", [], {}];
+            const response = createMcpToolSuccessResponse(input);
+            const parsed = JSON.parse(response.content[0].text);
+            assert.deepStrictEqual(parsed, []);
+        });
+        it("returns valid JSON string (not undefined)", () => {
+            const response = createMcpToolSuccessResponse([]);
+            assert.strictEqual(typeof response.content[0].text, "string");
+            assert.doesNotThrow(() => JSON.parse(response.content[0].text));
+        });
+        it("handles filter-variants-like response with empty data array", () => {
+            const input = {
+                data: [],
+                pagination: {
+                    continuation_token: null,
+                },
+            };
+            const response = createMcpToolSuccessResponse(input);
+            const parsed = JSON.parse(response.content[0].text);
+            assert.deepStrictEqual(parsed, {});
+        });
+    });
+    describe("createVariantMcpToolSuccessResponse", () => {
+        it("returns empty array when input is empty array", () => {
+            const response = createVariantMcpToolSuccessResponse([]);
+            const parsed = JSON.parse(response.content[0].text);
+            assert.deepStrictEqual(parsed, []);
+        });
+        it("returns empty object when input is empty object", () => {
+            const response = createVariantMcpToolSuccessResponse({});
+            const parsed = JSON.parse(response.content[0].text);
+            assert.deepStrictEqual(parsed, {});
+        });
+        it("returns empty object when all properties are removed", () => {
+            const input = { a: null, b: "", c: [] };
+            const response = createVariantMcpToolSuccessResponse(input);
+            const parsed = JSON.parse(response.content[0].text);
+            assert.deepStrictEqual(parsed, {});
+        });
+        it("returns empty array when all array items are removed", () => {
+            const input = [null, "", [], {}];
+            const response = createVariantMcpToolSuccessResponse(input);
+            const parsed = JSON.parse(response.content[0].text);
+            assert.deepStrictEqual(parsed, []);
+        });
+        it("returns valid JSON string (not undefined)", () => {
+            const response = createVariantMcpToolSuccessResponse([]);
+            assert.strictEqual(typeof response.content[0].text, "string");
+            assert.doesNotThrow(() => JSON.parse(response.content[0].text));
+        });
+        it("handles filter-variants-like response with empty data array", () => {
+            const input = {
+                data: [],
+                pagination: {
+                    continuation_token: null,
+                },
+            };
+            const response = createVariantMcpToolSuccessResponse(input);
+            const parsed = JSON.parse(response.content[0].text);
+            assert.deepStrictEqual(parsed, {});
+        });
+        it("handles filter-variants response with variants array becoming empty", () => {
+            const input = {
+                variants: [
+                    {
+                        elements: [
+                            { element: { id: "el-1" }, value: null },
+                            { element: { id: "el-2" }, value: "" },
+                        ],
+                    },
+                ],
+                pagination: {
+                    continuation_token: null,
+                },
+            };
+            const response = createVariantMcpToolSuccessResponse(input);
+            const parsed = JSON.parse(response.content[0].text);
+            // variants array should still be present (with empty variant objects)
+            assert.ok(parsed.variants !== undefined);
+            assert.strictEqual(parsed.variants.length, 1);
+        });
+    });
+});
+describe("undefined input handling - MCP protocol compliance", () => {
+    describe("createMcpToolSuccessResponse", () => {
+        it("returns string when input is undefined", () => {
+            const response = createMcpToolSuccessResponse(undefined);
+            assert.strictEqual(typeof response.content[0].text, "string");
+        });
+        it("returns 'undefined' text when input is undefined", () => {
+            const response = createMcpToolSuccessResponse(undefined);
+            assert.strictEqual(response.content[0].text, "undefined");
+        });
+        it("returns valid JSON string when input is null", () => {
+            const response = createMcpToolSuccessResponse(null);
+            assert.strictEqual(typeof response.content[0].text, "string");
+            assert.doesNotThrow(() => JSON.parse(response.content[0].text));
+        });
+    });
+    describe("createVariantMcpToolSuccessResponse", () => {
+        it("returns string when input is undefined", () => {
+            const response = createVariantMcpToolSuccessResponse(undefined);
+            assert.strictEqual(typeof response.content[0].text, "string");
+        });
+        it("returns 'undefined' text when input is undefined", () => {
+            const response = createVariantMcpToolSuccessResponse(undefined);
+            assert.strictEqual(response.content[0].text, "undefined");
+        });
+        it("returns valid JSON string when input is null", () => {
+            const response = createVariantMcpToolSuccessResponse(null);
+            assert.strictEqual(typeof response.content[0].text, "string");
+            assert.doesNotThrow(() => JSON.parse(response.content[0].text));
+        });
+    });
+});

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

@@ -0,0 +1,25 @@
+import { createMapiClient } from "../clients/kontentClients.js";
+import { addLanguageSchema } from "../schemas/languageSchemas.js";
+import { handleMcpToolError } from "../utils/errorHandler.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+export const registerTool = (server) => {
+    server.tool("add-language-mapi", "Add new Kontent.ai language via Management API", addLanguageSchema.shape, async ({ name, codename, is_active, fallback_language, external_id }, { authInfo: { token, clientId } = {} }) => {
+        const client = createMapiClient(clientId, token);
+        try {
+            const response = await client
+                .addLanguage()
+                .withData({
+                name,
+                codename,
+                is_active,
+                fallback_language,
+                external_id,
+            })
+                .toPromise();
+            return createMcpToolSuccessResponse(response.rawData);
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Language Creation");
+        }
+    });
+};