@kontent-ai/mcp-server 0.26.0 → 0.28.0

package/README.md

@@ -23,7 +23,6 @@ Kontent.ai MCP Server implements the Model Context Protocol to connect your Kont
 - [🔌 Quickstart](#-quickstart)
 - [🛠️ Available Tools](#️-available-tools)
 - [⚙️ Configuration](#️-configuration)
-- [🔧 Response Optimization](#-response-optimization)
 - [🚀 Transport Options](#-transport-options)
 - [💻 Development](#-development)
   - [🛠 Local Installation](#-local-installation)
@@ -105,7 +104,8 @@ npx @kontent-ai/mcp-server@latest shttp
 * **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
+* **filter-variants-mapi** – Filter Kontent.ai items with variants returning references (item ID + language ID). Use for exact keyword matching and finding specific terms in content. Supports full filtering capabilities (content types, workflow steps, taxonomies, spaces, collections, publishing states, etc.). Returns paginated results with continuation token for fetching subsequent pages. Use bulk-get-items-variants-mapi to retrieve full content for matched items
+* **bulk-get-items-variants-mapi** – Bulk get Kontent.ai content items with their language variants by item and language reference pairs. Use after filter-variants-mapi to retrieve full content data for specific item+language pairs. Items without a variant in the requested language return the item without the variant property. Returns paginated results with continuation token
 * **search-variants-mapi** – AI-powered semantic search for finding content by meaning and concepts in a specific language variant. Use for: conceptual searches when you don't know exact keywords. Limited filtering options (variant ID only)
 
 ### Asset Management
@@ -176,34 +176,6 @@ For multi-tenant mode (Streamable HTTP only), the server accepts:
 
 This mode allows a single server instance to handle requests for multiple Kontent.ai environments securely without requiring environment variables.
 
-## 🔧 Response Optimization
-
-The MCP server implements automatic token optimization to reduce AI model costs and improve performance:
-
-### Token Reduction Strategy
-
-The server automatically removes empty/default values from responses to reduce token usage. This includes:
-
-- Null and undefined values
-- Empty strings (`""`)
-- Empty arrays (`[]`)
-- Empty objects (`{}`)
-- Rich text placeholders (`"<p><br/></p>"`)
-- Elements with only an ID after empty value removal
-
-### Impact on AI Agents
-
-**Important for AI implementations**: When consuming responses from this MCP server:
-
-1. **Missing properties indicate default values**, not missing data
-2. Missing elements in variants have their type-specific defaults:
-   - Text elements: `""` (empty string)
-   - Rich text: `"<p><br/></p>"` (empty placeholder)
-   - Number/Date: `null`
-   - Custom elements: `null` (for value and searchable_value)
-   - Arrays (assets, taxonomy, etc.): `[]`
-3. When creating/updating content, always send complete data
-
 ## 🚀 Transport Options
 
 ### 📟 STDIO Transport

package/build/schemas/bulkGetItemsWithVariantsSchemas.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { continuationTokenField } from "./listSchemas.js";
+import { referenceObjectSchema } from "./referenceObjectSchema.js";
+export const bulkGetItemsWithVariantsSchema = z.object({
+    variants: z
+        .array(z.object({
+        item: referenceObjectSchema.describe("Reference to a content item by its id, codename, or external id"),
+        language: referenceObjectSchema.describe("Reference to a language by its id, codename, or external id"),
+    }))
+        .min(1)
+        .max(100)
+        .describe("Array of item and language reference pairs to retrieve (max 100). Use filter-variants-mapi to get item and language references first."),
+    continuation_token: continuationTokenField,
+});

package/build/schemas/contentItemSchemas.js

@@ -1,67 +1,128 @@
 import { z } from "zod";
 import { referenceObjectSchema } from "./referenceObjectSchema.js";
-// Recursive schema for rich text elements within components
-const richTextElementInComponentSchema = z.lazy(() => z.object({
+// Element schemas with descriptions based on Kontent.ai Management API documentation
+const assetInVariantElementSchema = z
+    .object({
     element: referenceObjectSchema,
-    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(richTextElementInComponentSchema),
-}));
-const assetInVariantElementSchema = z.object({
+    value: z
+        .array(referenceObjectSchema)
+        .nullable()
+        .describe("Array of Reference objects, each representing a single asset. Every asset can be referenced only once."),
+})
+    .describe("Asset element - references to assets (images, documents). Supports renditions for image-specific editions.");
+const customElementInVariantElementSchema = z
+    .object({
     element: referenceObjectSchema,
-    value: z.array(referenceObjectSchema).nullable(),
-});
-const customElementInVariantElementSchema = z.object({
+    value: z
+        .string()
+        .max(200000)
+        .nullable()
+        .describe("Custom-formatted data depending on the specific custom element implementation."),
+    searchable_value: z
+        .string()
+        .max(200000)
+        .nullable()
+        .describe("Plain text for search functionality in content item lists."),
+})
+    .describe("Custom element - stores custom-formatted data with optional searchable plain text representation.");
+const dateTimeInVariantElementSchema = z
+    .object({
     element: referenceObjectSchema,
-    value: z.string().nullable(),
-    searchable_value: z.string().nullable(),
-});
-const dateTimeInVariantElementSchema = z.object({
+    value: z.iso.datetime().nullable(),
+    display_timezone: z
+        .string()
+        .nullable()
+        .describe("IANA time zone name affecting UI display without modifying stored value. Defaults to null (local time zone)."),
+})
+    .describe("Date & time element - stores date and time values in UTC with optional display timezone.");
+const linkedItemsInVariantElementSchema = z
+    .object({
     element: referenceObjectSchema,
-    value: z.string().nullable(),
-    display_timezone: z.string().nullable(),
-});
-const linkedItemsInVariantElementSchema = z.object({
+    value: z
+        .array(referenceObjectSchema)
+        .nullable()
+        .describe("Array of Reference objects. Each reference represents a single content item (each item referenced only once)."),
+})
+    .describe("Linked items element - references to other content items for modular content.");
+const multipleChoiceInVariantElementSchema = z
+    .object({
     element: referenceObjectSchema,
-    value: z.array(referenceObjectSchema).nullable(),
-});
-const multipleChoiceInVariantElementSchema = z.object({
+    value: z
+        .array(referenceObjectSchema)
+        .nullable()
+        .describe("Array of Reference objects. Each reference represents one of the multiple choice options defined in content type."),
+})
+    .describe("Multiple choice element - references to selected choice options. Single-option mode requires exactly one reference.");
+const numberInVariantElementSchema = z
+    .object({
     element: referenceObjectSchema,
-    value: z.array(referenceObjectSchema).nullable(),
-});
-const numberInVariantElementSchema = z.object({
+    value: z.number().nullable().describe("Floating-point number."),
+})
+    .describe("Number element - stores numeric floating-point values.");
+const taxonomyInVariantElementSchema = z
+    .object({
     element: referenceObjectSchema,
-    value: z.number().nullable(),
-});
-const richTextInVariantElementSchema = z.object({
+    value: z
+        .array(referenceObjectSchema)
+        .nullable()
+        .describe("Array of Reference objects. Each reference represents a taxonomy term (each term referenced only once)."),
+})
+    .describe("Taxonomy element - references to taxonomy terms from a taxonomy group.");
+const textInVariantElementSchema = z
+    .object({
     element: referenceObjectSchema,
-    value: z.string().nullable(),
-    components: z.array(richTextComponentSchema).nullable(),
-});
-const taxonomyInVariantElementSchema = z.object({
+    value: z.string().max(100000).nullable().describe("Plain text content."),
+})
+    .describe("Text element - stores plain text content.");
+const urlSlugInVariantElementSchema = z
+    .object({
     element: referenceObjectSchema,
-    value: z.array(referenceObjectSchema).nullable(),
-});
-const textInVariantElementSchema = z.object({
+    mode: z
+        .enum(["autogenerated", "custom"])
+        .describe("'autogenerated' (system-generated based on dependent text element) or 'custom' (manual). Switches to custom when value is directly modified."),
+    value: z.string().nullable().describe("URL-friendly slug value for SEO."),
+})
+    .describe("URL slug element - URL-friendly slug for SEO. Can be auto-generated from dependent text element or custom.");
+// Rich text component schema - uses lazy to handle circular reference
+const richTextComponentSchema = z.lazy(() => z
+    .object({
+    id: z
+        .string()
+        .describe("Unique identifier of the component within the rich text element."),
+    type: referenceObjectSchema.describe("Reference to the content type defining the component structure."),
+    elements: z
+        .array(elementInComponentSchema)
+        .nullable()
+        .describe("Array of element values within the component (supports up to 6 levels deep nesting)."),
+})
+    .describe("Component embedded in rich text - a reusable content block defined by a content type."));
+// Rich text element schema - references components which can contain any element type
+const richTextInVariantElementSchema = z
+    .object({
     element: referenceObjectSchema,
-    value: z.string().nullable(),
-});
-const urlSlugInVariantElementSchema = z.object({
-    element: referenceObjectSchema,
-    mode: z.enum(["autogenerated", "custom"]),
-    value: z.string().nullable(),
-});
+    value: z
+        .string()
+        .max(100000)
+        .nullable()
+        .describe("Valid HTML5 fragment. Defaults to '<p><br/></p>' if empty."),
+    components: z
+        .array(richTextComponentSchema)
+        .nullable()
+        .describe("Array of nested component objects that can be embedded in the rich text content."),
+})
+    .describe("Rich text element - formatted HTML content that can include embedded assets, components, content items, and links.");
+// Union schema for elements within components
+// Uses z.lazy() to handle circular reference with richTextComponentSchema
+const elementInComponentSchema = z
+    .lazy(() => languageVariantElementSchema)
+    .describe("Element value within a component - same structure as top-level variant elements.");
+// Top-level language variant element schema - discriminated by unique fields
 export const languageVariantElementSchema = z.union([
     // Most specific schemas first (with unique distinguishing fields)
     urlSlugInVariantElementSchema, // has unique required 'mode' field
-    richTextInVariantElementSchema, // has unique optional 'components' field
+    richTextInVariantElementSchema, // has unique 'components' field
     dateTimeInVariantElementSchema, // has unique nullable 'display_timezone' field
-    customElementInVariantElementSchema, // has unique optional 'searchable_value' field
+    customElementInVariantElementSchema, // has unique 'searchable_value' field
     numberInVariantElementSchema, // has unique value type (number)
     // Medium specificity (array value types)
     assetInVariantElementSchema, // value: array of references

package/build/schemas/filterVariantSchemas.js

@@ -68,6 +68,21 @@ export const filterVariantsSchema = z.object({
         .min(1)
         .optional()
         .describe("Array of taxonomy groups with taxonomy terms"),
+    spaces: z
+        .array(referenceObjectSchema)
+        .min(1)
+        .optional()
+        .describe("Array of references to spaces by their id or codename (external_id is not supported for spaces)"),
+    collections: z
+        .array(referenceObjectSchema)
+        .min(1)
+        .optional()
+        .describe("Array of references to collections by their id, codename, or external id"),
+    publishing_states: z
+        .array(z.enum(["published", "unpublished", "not_published_yet"]))
+        .min(1)
+        .optional()
+        .describe("Array of publishing states to filter by. 'published' - variant is currently published, 'unpublished' - variant was published but is now unpublished, 'not_published_yet' - variant has never been published"),
     order_by: z
         .enum(["name", "due_date", "last_modified"])
         .optional()
@@ -76,9 +91,5 @@ export const filterVariantsSchema = z.object({
         .enum(["asc", "desc"])
         .optional()
         .describe("Order direction"),
-    include_content: z
-        .boolean()
-        .optional()
-        .describe("Whether to include the full content of language variants in the response"),
     continuation_token: continuationTokenField,
 });

package/build/server.js

@@ -7,6 +7,7 @@ import { registerTool as registerAddLanguageMapi } from "./tools/add-language-ma
 import { registerTool as registerAddSpaceMapi } from "./tools/add-space-mapi.js";
 import { registerTool as registerAddTaxonomyGroupMapi } from "./tools/add-taxonomy-group-mapi.js";
 import { registerTool as registerAddWorkflowMapi } from "./tools/add-workflow-mapi.js";
+import { registerTool as registerBulkGetItemsVariantsMapi } from "./tools/bulk-get-items-variants-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";
 import { registerTool as registerDeleteContentItemMapi } from "./tools/delete-content-item-mapi.js";
@@ -112,6 +113,7 @@ export const createServer = () => {
     registerDeleteWorkflowMapi(server);
     registerChangeVariantWorkflowStepMapi(server);
     registerFilterVariantsMapi(server);
+    registerBulkGetItemsVariantsMapi(server);
     registerSearchVariantsMapi(server);
     registerPublishVariantMapi(server);
     registerUnpublishVariantMapi(server);

package/build/test/utils/responseHelper.spec.js

@@ -1,320 +1,20 @@
 import * as assert from "node:assert";
 import { describe, it } from "mocha";
-import { createMcpToolSuccessResponse, createVariantMcpToolSuccessResponse, isEmptyOrDefault, removeEmptyElementsFromVariant, removeEmptyValues, } from "../../utils/responseHelper.js";
-describe("isEmptyOrDefault", () => {
-    describe("should return true for empty/default values", () => {
-        it("returns true for null", () => {
-            assert.strictEqual(isEmptyOrDefault(null), true);
-        });
-        it("returns true for undefined", () => {
-            assert.strictEqual(isEmptyOrDefault(undefined), true);
-        });
-        it("returns true for empty string", () => {
-            assert.strictEqual(isEmptyOrDefault(""), true);
-        });
-        it("returns true for rich text empty paragraph", () => {
-            assert.strictEqual(isEmptyOrDefault("<p><br/></p>"), true);
-        });
-        it("returns true for empty array", () => {
-            assert.strictEqual(isEmptyOrDefault([]), true);
-        });
-        it("returns true for empty object", () => {
-            assert.strictEqual(isEmptyOrDefault({}), true);
-        });
-    });
-    describe("should return false for non-empty values", () => {
-        it("returns false for non-empty string", () => {
-            assert.strictEqual(isEmptyOrDefault("hello"), false);
-        });
-        it("returns false for number zero", () => {
-            assert.strictEqual(isEmptyOrDefault(0), false);
-        });
-        it("returns false for positive number", () => {
-            assert.strictEqual(isEmptyOrDefault(42), false);
-        });
-        it("returns false for boolean false", () => {
-            assert.strictEqual(isEmptyOrDefault(false), false);
-        });
-        it("returns false for boolean true", () => {
-            assert.strictEqual(isEmptyOrDefault(true), false);
-        });
-        it("returns false for non-empty array", () => {
-            assert.strictEqual(isEmptyOrDefault([1, 2, 3]), false);
-        });
-        it("returns false for non-empty object", () => {
-            assert.strictEqual(isEmptyOrDefault({ key: "value" }), false);
-        });
-        it("returns false for Date object", () => {
-            assert.strictEqual(isEmptyOrDefault(new Date()), false);
-        });
-        it("returns false for rich text with actual content", () => {
-            assert.strictEqual(isEmptyOrDefault("<p>Hello world</p>"), false);
-        });
-    });
-});
-describe("removeEmptyValues", () => {
-    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("preserves empty string at root level", () => {
-            assert.strictEqual(removeEmptyValues(""), "");
-        });
-        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");
-        });
-        it("preserves number zero", () => {
-            assert.strictEqual(removeEmptyValues(0), 0);
-        });
-        it("preserves boolean false", () => {
-            assert.strictEqual(removeEmptyValues(false), false);
-        });
-    });
-    describe("arrays", () => {
-        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 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, ""]]), [
-                1,
-                [2, 3],
-            ]);
-        });
-    });
-    describe("objects", () => {
-        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 });
-        });
-        it("removes undefined properties", () => {
-            assert.deepStrictEqual(removeEmptyValues({ a: 1, b: undefined }), {
-                a: 1,
-            });
-        });
-        it("removes empty string properties", () => {
-            assert.deepStrictEqual(removeEmptyValues({ a: 1, b: "" }), { a: 1 });
-        });
-        it("removes empty array properties", () => {
-            assert.deepStrictEqual(removeEmptyValues({ a: 1, b: [] }), { a: 1 });
-        });
-        it("removes empty object properties", () => {
-            assert.deepStrictEqual(removeEmptyValues({ a: 1, b: {} }), { a: 1 });
-        });
-        it("removes rich text empty paragraph properties", () => {
-            assert.deepStrictEqual(removeEmptyValues({ a: 1, b: "<p><br/></p>" }), {
-                a: 1,
-            });
-        });
-        it("returns empty object when all properties are empty at root level", () => {
-            assert.deepStrictEqual(removeEmptyValues({ a: null, b: "", c: [], d: {} }), {});
-        });
-    });
-    describe("nested structures", () => {
-        it("recursively cleans nested objects", () => {
-            const input = {
-                level1: {
-                    level2: {
-                        value: "keep",
-                        empty: null,
-                    },
-                    emptyObj: {},
-                },
-            };
-            const expected = {
-                level1: {
-                    level2: {
-                        value: "keep",
-                    },
-                },
-            };
-            assert.deepStrictEqual(removeEmptyValues(input), expected);
-        });
-        it("removes nested objects that become empty after cleaning", () => {
-            const input = {
-                keep: "value",
-                remove: {
-                    nested: {
-                        empty: null,
-                    },
-                },
-            };
-            const expected = { keep: "value" };
-            assert.deepStrictEqual(removeEmptyValues(input), expected);
-        });
-        it("handles deeply nested structures", () => {
-            const input = {
-                a: {
-                    b: {
-                        c: {
-                            d: {
-                                value: "deep",
-                                empty: "",
-                            },
-                        },
-                    },
-                },
-            };
-            const expected = {
-                a: {
-                    b: {
-                        c: {
-                            d: {
-                                value: "deep",
-                            },
-                        },
-                    },
-                },
-            };
-            assert.deepStrictEqual(removeEmptyValues(input), expected);
-        });
-    });
-});
-describe("removeEmptyElementsFromVariant", () => {
-    describe("non-object inputs", () => {
-        it("returns null for null", () => {
-            assert.strictEqual(removeEmptyElementsFromVariant(null), null);
-        });
-        it("returns undefined for undefined", () => {
-            assert.strictEqual(removeEmptyElementsFromVariant(undefined), undefined);
-        });
-        it("returns primitive values unchanged", () => {
-            assert.strictEqual(removeEmptyElementsFromVariant("string"), "string");
-            assert.strictEqual(removeEmptyElementsFromVariant(42), 42);
-            assert.strictEqual(removeEmptyElementsFromVariant(true), true);
-        });
-    });
-    describe("elements array filtering", () => {
-        it("removes elements with only element property", () => {
-            const input = {
-                elements: [{ element: { id: "id1" } }, { element: { id: "id2" } }],
-            };
-            const expected = {};
-            assert.deepStrictEqual(removeEmptyElementsFromVariant(input), expected);
-        });
-        it("keeps elements with value property", () => {
-            const input = {
-                elements: [{ element: { id: "id1" }, value: "content" }],
-            };
-            const expected = {
-                elements: [{ element: { id: "id1" }, value: "content" }],
-            };
-            assert.deepStrictEqual(removeEmptyElementsFromVariant(input), expected);
-        });
-        it("filters mixed elements array", () => {
-            const input = {
-                elements: [
-                    { element: { id: "id1" } },
-                    { element: { id: "id2" }, value: "keep" },
-                    { element: { id: "id3" } },
-                    { element: { id: "id4" }, components: [] },
-                ],
-            };
-            const expected = {
-                elements: [
-                    { element: { id: "id2" }, value: "keep" },
-                    { element: { id: "id4" }, components: [] },
-                ],
-            };
-            assert.deepStrictEqual(removeEmptyElementsFromVariant(input), expected);
-        });
-        it("keeps non-object elements in elements array", () => {
-            const input = {
-                elements: ["string", 42, { element: { id: "id1" } }],
-            };
-            const expected = {
-                elements: ["string", 42],
-            };
-            assert.deepStrictEqual(removeEmptyElementsFromVariant(input), expected);
-        });
-    });
-    describe("nested structures", () => {
-        it("processes nested objects with elements arrays", () => {
-            const input = {
-                item: {
-                    elements: [{ element: { id: "id1" } }],
-                },
-            };
-            const expected = {
-                item: {},
-            };
-            assert.deepStrictEqual(removeEmptyElementsFromVariant(input), expected);
-        });
-        it("processes arrays of objects with elements", () => {
-            const input = {
-                variants: [
-                    { elements: [{ element: { id: "id1" } }] },
-                    { elements: [{ element: { id: "id2" }, value: "keep" }] },
-                ],
-            };
-            const expected = {
-                variants: [
-                    {},
-                    { elements: [{ element: { id: "id2" }, value: "keep" }] },
-                ],
-            };
-            assert.deepStrictEqual(removeEmptyElementsFromVariant(input), expected);
-        });
-    });
-    describe("preserves other properties", () => {
-        it("keeps non-elements properties unchanged", () => {
-            const input = {
-                id: "123",
-                name: "Test",
-                elements: [{ element: { id: "id1" } }],
-            };
-            const expected = {
-                id: "123",
-                name: "Test",
-            };
-            assert.deepStrictEqual(removeEmptyElementsFromVariant(input), expected);
-        });
-    });
-});
+import { createMcpToolSuccessResponse } from "../../utils/responseHelper.js";
 describe("createMcpToolSuccessResponse", () => {
-    it("returns correct structure", () => {
+    it("returns correct structure with text content", () => {
         const response = createMcpToolSuccessResponse({ key: "value" });
         assert.strictEqual(response.content.length, 1);
         assert.strictEqual(response.content[0].type, "text");
     });
-    it("removes empty values from response data", () => {
-        const input = {
-            id: "123",
-            name: null,
-            value: "",
-            items: [],
-        };
+    it("serializes object data as JSON string", () => {
+        const input = { id: "123", name: "Test" };
         const response = createMcpToolSuccessResponse(input);
         const parsed = JSON.parse(response.content[0].text);
-        assert.deepStrictEqual(parsed, { id: "123" });
+        assert.deepStrictEqual(parsed, input);
     });
-    it("handles complex nested data", () => {
+    it("serializes nested data as JSON string", () => {
         const input = {
-            contentType: {
-                id: "type-1",
-                name: "Article",
-                elements: [
-                    { id: "el-1", name: "Title", codename: "" },
-                    { id: "el-2", name: null, codename: "body" },
-                ],
-            },
-        };
-        const response = createMcpToolSuccessResponse(input);
-        const parsed = JSON.parse(response.content[0].text);
-        assert.deepStrictEqual(parsed, {
             contentType: {
                 id: "type-1",
                 name: "Article",
@@ -323,262 +23,28 @@ describe("createMcpToolSuccessResponse", () => {
                     { id: "el-2", codename: "body" },
                 ],
             },
-        });
-    });
-});
-describe("createVariantMcpToolSuccessResponse", () => {
-    it("returns correct structure", () => {
-        const response = createVariantMcpToolSuccessResponse({ key: "value" });
-        assert.strictEqual(response.content.length, 1);
-        assert.strictEqual(response.content[0].type, "text");
-    });
-    it("removes empty values and empty elements", () => {
-        const input = {
-            item: { id: "item-1" },
-            language: { id: "lang-1" },
-            elements: [
-                { element: { id: "el-1" }, value: "" },
-                { element: { id: "el-2" }, value: "content" },
-                { element: { id: "el-3" }, value: null },
-            ],
-        };
-        const response = createVariantMcpToolSuccessResponse(input);
-        const parsed = JSON.parse(response.content[0].text);
-        assert.deepStrictEqual(parsed, {
-            item: { id: "item-1" },
-            language: { id: "lang-1" },
-            elements: [{ element: { id: "el-2" }, value: "content" }],
-        });
-    });
-    it("removes elements array when all elements become empty", () => {
-        const input = {
-            item: { id: "item-1" },
-            elements: [
-                { element: { id: "el-1" }, value: "" },
-                { element: { id: "el-2" }, value: null },
-                { element: { id: "el-3" }, value: "<p><br/></p>" },
-            ],
-        };
-        const response = createVariantMcpToolSuccessResponse(input);
-        const parsed = JSON.parse(response.content[0].text);
-        assert.deepStrictEqual(parsed, {
-            item: { id: "item-1" },
-        });
-    });
-    it("handles real-world variant response", () => {
-        const input = {
-            item: { id: "f4b3fc05-e988-4dae-9ac1-a94aba566474" },
-            language: { id: "d1f95fde-af02-b3b5-bd9e-f232311ccab8" },
-            last_modified: "2018-02-27T19:08:25.404Z",
-            workflow: {
-                workflow_identifier: { id: "00000000-0000-0000-0000-000000000000" },
-                step_identifier: { id: "c199950d-99f0-4983-b711-6c4c91624b22" },
-            },
-            elements: [
-                { element: { id: "text-id" }, value: "Article Title" },
-                { element: { id: "rich-id" }, value: "<p><br/></p>", components: [] },
-                { element: { id: "number-id" }, value: null },
-                { element: { id: "assets-id" }, value: [] },
-                { element: { id: "taxonomy-id" }, value: [] },
-            ],
         };
-        const response = createVariantMcpToolSuccessResponse(input);
+        const response = createMcpToolSuccessResponse(input);
         const parsed = JSON.parse(response.content[0].text);
-        assert.deepStrictEqual(parsed, {
-            item: { id: "f4b3fc05-e988-4dae-9ac1-a94aba566474" },
-            language: { id: "d1f95fde-af02-b3b5-bd9e-f232311ccab8" },
-            last_modified: "2018-02-27T19:08:25.404Z",
-            workflow: {
-                workflow_identifier: { id: "00000000-0000-0000-0000-000000000000" },
-                step_identifier: { id: "c199950d-99f0-4983-b711-6c4c91624b22" },
-            },
-            elements: [{ element: { id: "text-id" }, value: "Article Title" }],
-        });
+        assert.deepStrictEqual(parsed, input);
     });
-    it("handles variant with multiple variants (filter-variants response)", () => {
-        const input = {
-            variants: [
-                {
-                    item: { id: "item-1" },
-                    elements: [
-                        { element: { id: "el-1" }, value: "" },
-                        { element: { id: "el-2" }, value: "content" },
-                    ],
-                },
-                {
-                    item: { id: "item-2" },
-                    elements: [
-                        { element: { id: "el-1" }, value: null },
-                        { element: { id: "el-2" }, value: [] },
-                    ],
-                },
-            ],
-            pagination: {
-                continuation_token: null,
-                next_page: "",
-            },
-        };
-        const response = createVariantMcpToolSuccessResponse(input);
+    it("serializes arrays as JSON string", () => {
+        const input = [{ id: "1" }, { id: "2" }];
+        const response = createMcpToolSuccessResponse(input);
         const parsed = JSON.parse(response.content[0].text);
-        assert.deepStrictEqual(parsed, {
-            variants: [
-                {
-                    item: { id: "item-1" },
-                    elements: [{ element: { id: "el-2" }, value: "content" }],
-                },
-                {
-                    item: { id: "item-2" },
-                },
-            ],
-        });
-    });
-});
-describe("variant with all empty elements", () => {
-    it("removes elements array entirely when all elements become empty", () => {
-        const input = {
-            elements: [
-                { element: { id: "text-id" }, value: "" },
-                { element: { id: "rich-id" }, value: "<p><br/></p>", components: [] },
-                { element: { id: "number-id" }, value: null },
-                { element: { id: "assets-id" }, value: [] },
-            ],
-        };
-        const response = createVariantMcpToolSuccessResponse(input);
-        const result = JSON.parse(response.content[0].text);
-        assert.deepStrictEqual(result, {}, "All empty elements should be removed, resulting in an empty object");
+        assert.deepStrictEqual(parsed, input);
     });
-});
-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, {});
-        });
+    it("passes through string values without JSON encoding", () => {
+        const response = createMcpToolSuccessResponse("plain text");
+        assert.strictEqual(response.content[0].text, "plain text");
     });
-    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));
-        });
+    it("returns 'undefined' text when input is undefined", () => {
+        const response = createMcpToolSuccessResponse(undefined);
+        assert.strictEqual(response.content[0].text, "undefined");
     });
-    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));
-        });
+    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));
     });
 });

package/build/tools/bulk-get-items-variants-mapi.js

@@ -0,0 +1,31 @@
+import { createMapiClient } from "../clients/kontentClients.js";
+import { bulkGetItemsWithVariantsSchema } from "../schemas/bulkGetItemsWithVariantsSchemas.js";
+import { handleMcpToolError } from "../utils/errorHandler.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+import { throwError } from "../utils/throwError.js";
+export const registerTool = (server) => {
+    server.tool("bulk-get-items-variants-mapi", "Bulk get Kontent.ai content items with their language variants by item and language reference pairs. Items without a variant in the requested language return the item without the variant property.", bulkGetItemsWithVariantsSchema.shape, async ({ variants, 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 query = client.bulkGetItemsWithVariants().withData({
+                variants,
+            });
+            const response = await (continuation_token
+                ? query.xContinuationToken(continuation_token)
+                : query).toPromise();
+            return createMcpToolSuccessResponse({
+                data: response.rawData.data,
+                pagination: {
+                    continuation_token: response.data.pagination.continuationToken,
+                },
+            });
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Bulk Get Items With Variants");
+        }
+    });
+};

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

@@ -1,17 +1,17 @@
 import { createMapiClient } from "../clients/kontentClients.js";
 import { filterVariantsSchema } from "../schemas/filterVariantSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
-import { createVariantMcpToolSuccessResponse } from "../utils/responseHelper.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 import { throwError } from "../utils/throwError.js";
 export const registerTool = (server) => {
-    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 } = {} }) => {
+    server.tool("filter-variants-mapi", "Filter Kontent.ai items with variants returning references (item ID + language ID). For EXACT keyword matching and compliance (terms use OR). Use bulk-get-items-variants-mapi to retrieve full content for matched items. 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, spaces, collections, publishing_states, order_by, order_direction, 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 query = client.earlyAccess.filterLanguageVariants().withData({
+            const query = client.filterItemsWithVariants().withData({
                 filters: {
                     search_phrase,
                     content_types,
@@ -21,6 +21,9 @@ export const registerTool = (server) => {
                     language,
                     workflow_steps,
                     taxonomy_groups,
+                    spaces,
+                    collections,
+                    publishing_states,
                 },
                 order: order_by
                     ? {
@@ -28,13 +31,12 @@ export const registerTool = (server) => {
                         direction: order_direction || "asc",
                     }
                     : undefined,
-                include_content: include_content ?? false,
             });
             const response = await (continuation_token
                 ? query.xContinuationToken(continuation_token)
                 : query).toPromise();
-            return createVariantMcpToolSuccessResponse({
-                data: response.rawData.data,
+            return createMcpToolSuccessResponse({
+                variants: response.rawData.variants,
                 pagination: {
                     continuation_token: response.data.pagination.continuationToken,
                 },

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

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
-import { createVariantMcpToolSuccessResponse } from "../utils/responseHelper.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
     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"),
@@ -14,7 +14,7 @@ export const registerTool = (server) => {
                 .byItemId(itemId)
                 .byLanguageId(languageId)
                 .toPromise();
-            return createVariantMcpToolSuccessResponse(response.rawData);
+            return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Latest Language Variant Retrieval");

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

@@ -1,7 +1,7 @@
 import { z } from "zod";
 import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
-import { createVariantMcpToolSuccessResponse } from "../utils/responseHelper.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
     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"),
@@ -15,7 +15,7 @@ export const registerTool = (server) => {
                 .byLanguageId(languageId)
                 .published()
                 .toPromise();
-            return createVariantMcpToolSuccessResponse(response.rawData);
+            return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Published Language Variant Retrieval");

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, createVariantMcpToolSuccessResponse, } from "../utils/responseHelper.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 import { throwError } from "../utils/throwError.js";
 class OperationResultIncompleteError extends Error {
     constructor() {
@@ -84,7 +84,7 @@ export const registerTool = (server) => {
                 maxTimeout: 10000,
                 factor: 1.5,
             });
-            return createVariantMcpToolSuccessResponse({
+            return createMcpToolSuccessResponse({
                 result: resultData,
             });
         }

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

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { createMapiClient } from "../clients/kontentClients.js";
 import { languageVariantElementSchema } from "../schemas/contentItemSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
-import { createVariantMcpToolSuccessResponse } from "../utils/responseHelper.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
     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"),
@@ -28,7 +28,7 @@ export const registerTool = (server) => {
                 .byLanguageId(languageId)
                 .withData(() => data)
                 .toPromise();
-            return createVariantMcpToolSuccessResponse(response.rawData);
+            return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Language Variant Upsert");

package/build/utils/responseHelper.js

@@ -1,108 +1,13 @@
 /**
- * Utility for creating standardized MCP tool success responses
+ * Utility for creating standardized MCP tool success responses.
+ * Passes API data through to MCP response format without transformation.
  */
-export function isEmptyOrDefault(value) {
-    if (value === null || value === undefined) {
-        return true;
-    }
-    if (typeof value === "string" && value === "") {
-        return true;
-    }
-    if (typeof value === "string" && value === "<p><br/></p>") {
-        return true;
-    }
-    if (Array.isArray(value) && value.length === 0) {
-        return true;
-    }
-    if (typeof value === "object" &&
-        !Array.isArray(value) &&
-        !(value instanceof Date) &&
-        !(value instanceof Function) &&
-        Object.keys(value).length === 0) {
-        return true;
-    }
-    return false;
-}
-export function removeEmptyElementsFromVariant(obj) {
-    if (obj === null || obj === undefined || typeof obj !== "object") {
-        return obj;
-    }
-    if (Array.isArray(obj)) {
-        return obj.map((item) => removeEmptyElementsFromVariant(item));
-    }
-    const result = {};
-    for (const [key, value] of Object.entries(obj)) {
-        if (key === "elements" && Array.isArray(value)) {
-            const filteredElements = value
-                .filter((element) => {
-                if (typeof element !== "object" || element === null) {
-                    return true;
-                }
-                const keys = Object.keys(element);
-                return !(keys.length === 1 && keys[0] === "element");
-            })
-                .map((element) => removeEmptyElementsFromVariant(element));
-            if (filteredElements.length > 0) {
-                result[key] = filteredElements;
-            }
-        }
-        else {
-            const processedValue = removeEmptyElementsFromVariant(value);
-            if (processedValue !== undefined) {
-                result[key] = processedValue;
-            }
-        }
-    }
-    return result;
-}
-function removeEmptyValuesRecursive(obj) {
-    if (obj === null || obj === undefined) {
-        return undefined;
-    }
-    if (typeof obj !== "object") {
-        return isEmptyOrDefault(obj) ? undefined : obj;
-    }
-    if (Array.isArray(obj)) {
-        const cleaned = obj
-            .map((item) => removeEmptyValuesRecursive(item))
-            .filter((item) => item !== undefined);
-        return cleaned.length === 0 ? undefined : cleaned;
-    }
-    const cleaned = {};
-    for (const [key, value] of Object.entries(obj)) {
-        const cleanedValue = removeEmptyValuesRecursive(value);
-        if (cleanedValue !== undefined) {
-            cleaned[key] = cleanedValue;
-        }
-    }
-    const keys = Object.keys(cleaned);
-    return keys.length === 0 ? undefined : cleaned;
-}
-export function removeEmptyValues(obj) {
-    // At root level, preserve the structure even if empty
-    if (typeof obj !== "object" || obj === null) {
-        return obj;
-    }
-    if (Array.isArray(obj)) {
-        return obj
-            .map((item) => removeEmptyValuesRecursive(item))
-            .filter((item) => item !== undefined);
-    }
-    const cleaned = {};
-    for (const [key, value] of Object.entries(obj)) {
-        const cleanedValue = removeEmptyValuesRecursive(value);
-        if (cleanedValue !== undefined) {
-            cleaned[key] = cleanedValue;
-        }
-    }
-    return cleaned;
-}
 /**
  * Converts data to MCP tool success response format.
  * Handles undefined separately as JSON.stringify(undefined) returns undefined (not a string).
  * Skips stringify for strings as they don't need JSON encoding for MCP text response.
  */
-const toMcpSuccessResponse = (data) => {
+export const createMcpToolSuccessResponse = (data) => {
     const text = data === undefined
         ? "undefined"
         : typeof data === "string"
@@ -117,12 +22,3 @@ const toMcpSuccessResponse = (data) => {
         ],
     };
 };
-export const createMcpToolSuccessResponse = (data) => {
-    const cleaned = removeEmptyValues(data);
-    return toMcpSuccessResponse(cleaned);
-};
-export const createVariantMcpToolSuccessResponse = (data) => {
-    const cleaned = removeEmptyValues(data);
-    const optimized = removeEmptyElementsFromVariant(cleaned);
-    return toMcpSuccessResponse(optimized);
-};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontent-ai/mcp-server",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "type": "module",
   "mcpName": "io.github.kontent-ai/mcp-server",
   "repository": {
@@ -29,7 +29,7 @@
   "author": "Jiri Lojda",
   "license": "MIT",
   "dependencies": {
-    "@kontent-ai/management-sdk": "^8.1.0",
+    "@kontent-ai/management-sdk": "^8.3.0",
     "@modelcontextprotocol/sdk": "^1.25.2",
     "applicationinsights": "^2.9.8",
     "dotenv": "^17.2.3",