@kontent-ai/mcp-server 0.25.0 → 0.27.0

package/README.md

@@ -105,7 +105,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
@@ -121,9 +122,9 @@ 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
+* **list-languages-mapi** – Get all Kontent.ai languages from Management API (includes both active and inactive - check is_active property)
+* **add-language-mapi** – Add new Kontent.ai language via Management API (languages are always created as active)
+* **patch-language-mapi** – Update Kontent.ai language using replace operations via Management API (only active languages can be modified - to activate/deactivate, use the Kontent.ai web UI)
 
 ### Collection Management
 

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

@@ -3,10 +3,6 @@ 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)"),
@@ -23,11 +19,6 @@ const languageReplaceOperationSchema = z.discriminatedUnion("property_name", [
         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"),
@@ -39,5 +30,5 @@ export const patchLanguageSchema = z.object({
     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."),
+        .describe("Array of replace operations for codename, name, or fallback_language. Note: Only active languages can be modified. To activate/deactivate languages, use the Kontent.ai web UI."),
 });

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/tools/add-language-mapi.js

@@ -3,7 +3,7 @@ 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 } = {} }) => {
+    server.tool("add-language-mapi", "Add new Kontent.ai language via Management API. Languages are always created as active.", addLanguageSchema.shape, async ({ name, codename, fallback_language, external_id }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const response = await client
@@ -11,7 +11,7 @@ export const registerTool = (server) => {
                 .withData({
                 name,
                 codename,
-                is_active,
+                is_active: true,
                 fallback_language,
                 external_id,
             })

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 { createVariantMcpToolSuccessResponse } 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 createVariantMcpToolSuccessResponse({
+                data: response.rawData.data,
+                pagination: {
+                    continuation_token: response.data.pagination.continuationToken,
+                },
+            });
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Bulk Get Items With Variants");
+        }
+    });
+};

package/build/tools/context/patch-guide-property-based.js

@@ -21,20 +21,16 @@ Available properties: name, codename, collections
 \`\`\`json
 { "op": "replace", "property_name": "name", "value": "New Language Name" }
 { "op": "replace", "property_name": "codename", "value": "new_codename" }
-{ "op": "replace", "property_name": "is_active", "value": true }
 { "op": "replace", "property_name": "fallback_language", "value": { "codename": "en-US" } }
 \`\`\`
 
-Available properties: name, codename, is_active, fallback_language
+Available properties: name, codename, fallback_language
 
 ## Critical Rule for Languages
-If a language is deactivated, you must activate it first before making other changes:
-\`\`\`json
-[
-  { "op": "replace", "property_name": "is_active", "value": true },
-  { "op": "replace", "property_name": "name", "value": "New Name" }
-]
-\`\`\`
+
+**Only active languages can be modified.** To activate or deactivate a language, the user must use the Kontent.ai web UI - this is a critical operation that cannot be performed via API tools.
+
+When user asks to update "all languages": only update active languages (is_active: true). If they need to modify inactive languages, inform them they must first activate those languages in the Kontent.ai web UI.
 
 ## General Rules
 - external_id cannot be modified after creation

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/list-languages-mapi.js

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

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

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

package/package.json

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