@kontent-ai/mcp-server 0.21.9 → 0.21.11

package/README.md

@@ -23,6 +23,7 @@ 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)
@@ -95,7 +96,7 @@ 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. This adds actual content to the content item elements. When updating an existing variant, only the 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
+* **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
 * **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
@@ -139,6 +140,34 @@ 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/bin.js

@@ -130,6 +130,13 @@ async function startStreamableHTTP() {
             id: null,
         }));
     });
+    app.get("/health", (_, res) => {
+        res.json({
+            status: "ok",
+            timestamp: new Date().toISOString(),
+            currentVersion: version,
+        });
+    });
     app.use((err, _req, _res, next) => {
         trackException(err, "Express Error Handler");
         next(err);

package/build/schemas/contentTypeSchemas.js

@@ -1,11 +1,9 @@
 import { z } from "zod";
-// Define a reusable reference object schema
-export const referenceObjectSchema = z
-    .object({
+// Reference by id or codename (id preferred)
+export const referenceObjectSchema = z.object({
     id: z.string().optional(),
     codename: z.string().optional(),
-})
-    .describe("An object with an id or codename property referencing another item. Using id is preferred for better performance.");
+});
 // Common property schemas
 const baseElementSchema = {
     codename: z.string().optional(),
@@ -13,9 +11,7 @@ const baseElementSchema = {
 };
 // Content group schema for content type elements only
 const contentGroupElementSchema = {
-    content_group: referenceObjectSchema
-        .describe("An object with an id or codename property referencing a content group.")
-        .optional(),
+    content_group: referenceObjectSchema.optional(),
 };
 const namedElementSchema = {
     ...baseElementSchema,
@@ -92,17 +88,14 @@ const assetElementSchema = {
     maximum_file_size: z.number().optional(),
     allowed_file_types: z.enum(["adjustable", "any"]).optional(),
     ...imageLimitSchema,
-    default: arrayDefaultSchema.describe("Default value of the asset element. Reference an existing asset by its id or codename."),
+    default: arrayDefaultSchema,
 };
 const customElementSchema = {
     type: z.literal("custom"),
     ...namedElementSchema,
     source_url: z.string(),
     json_parameters: z.string().optional(),
-    allowed_elements: z
-        .array(referenceObjectSchema.describe("An object with an id or codename property referencing an element."))
-        .optional()
-        .describe("Specifies which elements from the content type can be used within this custom element."),
+    allowed_elements: z.array(referenceObjectSchema).optional(),
 };
 const dateTimeElementSchema = {
     type: z.literal("date_time"),
@@ -112,18 +105,14 @@ const dateTimeElementSchema = {
 const guidelinesElementSchema = {
     type: z.literal("guidelines"),
     ...baseElementSchema,
-    guidelines: z
-        .string()
-        .describe("Value of the guidelines element. This is rich text and can include HTML formatting. Check the documentation here https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#section/HTML5-elements-allowed-in-rich-text for the supported format, but keep in mind that content items and components are not supported in guidelines. Use empty `<p>` tag for empty guidelines."),
+    guidelines: z.string(),
 };
 const modularContentElementSchema = {
     type: z.literal("modular_content"),
     ...namedElementSchema,
-    allowed_content_types: z
-        .array(referenceObjectSchema.describe("An object with an id or codename property referencing a content type. Use an empty array to allow all content types."))
-        .optional(),
+    allowed_content_types: z.array(referenceObjectSchema).optional(),
     item_count_limit: countLimitSchema,
-    default: arrayDefaultSchema.describe("Default value of the modular content element. Reference an existing content item by its id or codename."),
+    default: arrayDefaultSchema,
 };
 const subpagesElementSchema = {
     type: z.literal("subpages"),
@@ -143,7 +132,7 @@ const multipleChoiceElementSchema = {
     ...namedElementSchema,
     mode: z.enum(["single", "multiple"]),
     options: z.array(optionSchema),
-    default: arrayDefaultSchema.describe("Default value of the multiple choice element. Reference one of the options by its codename."),
+    default: arrayDefaultSchema,
 };
 const numberElementSchema = {
     type: z.literal("number"),
@@ -200,38 +189,14 @@ export const allowedTableTextBlockSchema = z.enum([
 const richTextElementSchema = {
     type: z.literal("rich_text"),
     ...namedElementSchema,
-    allowed_blocks: z
-        .array(allowedBlockSchema)
-        .optional()
-        .describe("Specifies allowed blocks. Use an empty array to allow all options."),
-    allowed_formatting: z
-        .array(allowedFormattingSchema)
-        .optional()
-        .describe("Specifies allowed formatting options. Use an empty array to allow all options."),
-    allowed_text_blocks: z
-        .array(allowedTextBlockSchema)
-        .optional()
-        .describe("Specifies allowed text blocks. Use an empty array to allow all options."),
-    allowed_table_blocks: z
-        .array(allowedTableBlockSchema)
-        .optional()
-        .describe("Specifies allowed table blocks. Use an empty array to allow all options."),
-    allowed_table_formatting: z
-        .array(allowedTableFormattingSchema)
-        .optional()
-        .describe("Specifies allowed table formatting options. Use an empty array to allow all options."),
-    allowed_table_text_blocks: z
-        .array(allowedTableTextBlockSchema)
-        .optional()
-        .describe("Specifies allowed table text blocks. Use an empty array to allow all options."),
-    allowed_content_types: z
-        .array(referenceObjectSchema.describe("An object with an id or codename property referencing a content type."))
-        .optional()
-        .describe("Specifies allowed content types. Use an empty array to allow all content types."),
-    allowed_item_link_types: z
-        .array(referenceObjectSchema.describe("An object with an id or codename property referencing a content type."))
-        .optional()
-        .describe("Specifies allowed item link types. Use an empty array to allow all link types."),
+    allowed_blocks: z.array(allowedBlockSchema).optional(),
+    allowed_formatting: z.array(allowedFormattingSchema).optional(),
+    allowed_text_blocks: z.array(allowedTextBlockSchema).optional(),
+    allowed_table_blocks: z.array(allowedTableBlockSchema).optional(),
+    allowed_table_formatting: z.array(allowedTableFormattingSchema).optional(),
+    allowed_table_text_blocks: z.array(allowedTableTextBlockSchema).optional(),
+    allowed_content_types: z.array(referenceObjectSchema).optional(),
+    allowed_item_link_types: z.array(referenceObjectSchema).optional(),
     ...imageLimitSchema,
     allowed_image_types: z.enum(["adjustable", "any"]).optional(),
     maximum_image_size: z.number().optional(),
@@ -239,15 +204,15 @@ const richTextElementSchema = {
 };
 const snippetElement = {
     type: z.literal("snippet"),
-    snippet: referenceObjectSchema.describe("An object with an id or codename property referencing a snippet."),
+    snippet: referenceObjectSchema,
     ...baseElementSchema,
 };
 const taxonomyElementSchema = {
     type: z.literal("taxonomy"),
-    taxonomy_group: referenceObjectSchema.describe("An object with an id or codename property referencing a taxonomy group."),
+    taxonomy_group: referenceObjectSchema,
     ...namedElementSchema,
     term_count_limit: countLimitSchema,
-    default: arrayDefaultSchema.describe("Default value of the taxonomy element. Reference one of the terms from the specified taxonomy group by its codename."),
+    default: arrayDefaultSchema,
 };
 const textElementSchema = {
     type: z.literal("text"),
@@ -257,15 +222,13 @@ const textElementSchema = {
     default: stringDefaultSchema,
 };
 export const dependsOnSchema = z.object({
-    element: referenceObjectSchema.describe("An object with an id or codename property referencing an element."),
-    snippet: referenceObjectSchema
-        .describe("An object with an id or codename property referencing a content type snippet.")
-        .optional(),
+    element: referenceObjectSchema,
+    snippet: referenceObjectSchema.optional(),
 });
 const urlSlugElementSchema = {
     type: z.literal("url_slug"),
     ...namedElementSchema,
-    depends_on: dependsOnSchema.describe("The element the URL slug depends on. If this element is within a snippet, the snippet must also be specified."),
+    depends_on: dependsOnSchema,
     validation_regex: regexValidationSchema,
 };
 // Define a union type of all possible element types for content types

package/build/schemas/filterVariantSchemas.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { continuationTokenField } from "./listSchemas.js";
 import { referenceObjectSchema } from "./referenceObjectSchema.js";
 // UserReferenceDataContract is a union type - either id or email, but not both
 const userReferenceSchema = z
@@ -79,4 +80,5 @@ export const filterVariantsSchema = z.object({
         .boolean()
         .optional()
         .describe("Whether to include the full content of language variants in the response"),
+    continuation_token: continuationTokenField,
 });

package/build/schemas/listSchemas.js

@@ -0,0 +1,26 @@
+import { z } from "zod";
+// Reusable continuation token schema for paginated list operations
+export const continuationTokenField = z
+    .string()
+    .optional()
+    .describe("Continuation token from a previous response to fetch the next page of results. Omit this parameter (or set to null) to fetch the first page. The response will include a continuation_token field - use this value in the next request to fetch the next page. When continuation_token in the response is null, there are no more pages available.");
+// Schema for listing taxonomy groups
+export const listTaxonomyGroupsSchema = z.object({
+    continuation_token: continuationTokenField,
+});
+// Schema for listing languages
+export const listLanguagesSchema = z.object({
+    continuation_token: continuationTokenField,
+});
+// Schema for listing content types
+export const listContentTypesSchema = z.object({
+    continuation_token: continuationTokenField,
+});
+// Schema for listing content type snippets
+export const listContentTypeSnippetsSchema = z.object({
+    continuation_token: continuationTokenField,
+});
+// Schema for listing assets
+export const listAssetsSchema = z.object({
+    continuation_token: continuationTokenField,
+});

package/build/schemas/patchSchemas/contentTypePatchSchemas.js

@@ -5,37 +5,15 @@ import { allowedBlockSchema, allowedFormattingSchema, allowedTableBlockSchema, a
 // Move operation - Move elements within content type
 const moveOperationSchema = z.object({
     op: z.literal("move"),
-    path: z
-        .string()
-        .describe(`Identifies the object you want to move using a path reference. The path reference should be in format 'id:{uuid}'. Examples:
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000' - Move an element
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/options/id:987fcdeb-51a2-43d1-9f4e-123456789abc' - Move a multiple choice option (first reference is element, second is option)
-    • '/content_groups/id:456e7890-a12b-34c5-d678-901234567def' - Move a content group`),
-    before: referenceObjectSchema
-        .describe("A reference to the object before which you want to move the object. For example, to move an element before an existing element with id:uuid 'text', set before to {codename: 'text'}. The before and after properties are mutually exclusive.")
-        .optional(),
-    after: referenceObjectSchema
-        .describe("A reference to the object after which you want to move the object. For example, to move an element after an existing element with id:uuid 'Text', set after to {codename: 'text'}. The before and after properties are mutually exclusive.")
-        .optional(),
+    path: z.string().describe("Path to object (format: id:{uuid})"),
+    before: referenceObjectSchema.optional(),
+    after: referenceObjectSchema.optional(),
 });
 // AddInto operation - Add new elements to content type
 const addIntoOperationSchema = z.object({
     op: z.literal("addInto"),
-    path: z
-        .string()
-        .describe(`JSON Pointer path where to add the item. The path reference should be in format 'id:{uuid}'. Examples:
-    • '/elements' - Add a new element to the content type
-    • '/content_groups' - Add a new content group
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/allowed_content_types' - Add allowed content type to rich text or linked items element
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/allowed_elements' - Add allowed element to custom element
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/options' - Add multiple choice option
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/allowed_blocks' - Add block for rich text element
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/allowed_formatting' - Add formatting option for rich text element
-    (Replace with actual element UUID)
-
-    - CRITICAL: When adding a url slug that references a snippet element, first add the snippet element to the content type if it’s not already included.`),
-    value: z
-        .union([
+    path: z.string().describe("Path where to add item (format: id:{uuid})"),
+    value: z.union([
         elementSchema,
         optionSchema,
         contentGroupSchema,
@@ -51,44 +29,18 @@ const addIntoOperationSchema = z.object({
         z.boolean(),
         z.null(),
         z.any(),
-    ])
-        .describe("The item to add (element, content group, option, etc.)"),
+    ]),
 });
 // Remove operation - Remove elements from content type
 const removeOperationSchema = z.object({
     op: z.literal("remove"),
-    path: z
-        .string()
-        .describe(`JSON Pointer path to the item being removed. The path reference should be in format 'id:{uuid}'. Examples:
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000' - Remove an element
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/allowed_content_types/id:987fcdeb-51a2-43d1-9f4e-123456789abc' - Remove allowed content type from rich text/linked items element
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/allowed_element/id:456e7890-a12b-34c5-d678-901234567def' - Remove allowed element from custom element
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/options/id:321dcba9-87f6-54e3-21b0-fedcba987654' - Remove multiple choice option
-    • '/content_groups/id:456e7890-a12b-34c5-d678-901234567def' - Remove content group (removes all elements within the group)
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/allowed_blocks/images' - Remove rich-text element limitation (where {block} is the limitation type)
-    (Replace with actual UUIDs)`),
+    path: z.string().describe("Path to item to remove (format: id:{uuid})"),
 });
 // Replace operation - Replace/update existing elements in content type
 const replaceOperationSchema = z.object({
     op: z.literal("replace"),
-    path: z
-        .string()
-        .describe(`JSON Pointer path to the item or property being replaced. The path reference should be in format 'id:{uuid}' Examples:
-    • '/name' - Change the content type's name
-    • '/codename' - Change the content type's codename
-    • '/content_groups/id:456e7890-a12b-34c5-d678-901234567def/name' - Change the name of a content group
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/name' - Change an element property (property depends on element type)
-    • '/elements/id:123e4567-e89b-12d3-a456-426614174000/options/id:321dcba9-87f6-54e3-21b0-fedcba987654/name' - Change multiple choice option property (name or codename)
-    (Replace with actual element/group UUIDs)
-    
-    REPLACE OPERATION RULES:
-    • CAN modify: Most element properties based on element type (name, guidelines, validation, etc.)
-    • CANNOT modify: external_id, id, or type of elements
-    • CANNOT replace individual object values - must replace the entire object at once
-    • FOR rich text elements: CANNOT replace individual items in allowed_blocks, allowed_formatting, allowed_text_blocks, allowed_table_blocks, allowed_table_formatting, allowed_table_text_blocks, allowed_content_types, allowed_item_link_types arrays - use addInto/remove operations instead for individual items
-    • FOR multiple choice options: Can modify name and codename properties`),
-    value: z
-        .union([
+    path: z.string().describe("Path to property to replace (format: id:{uuid})"),
+    value: z.union([
         dependsOnSchema,
         regexValidationSchema,
         textLengthLimitSchema,
@@ -100,9 +52,8 @@ const replaceOperationSchema = z.object({
         z.number(),
         z.boolean(),
         z.null(),
-        z.any(), // in Union zod tries to match from top to down. any if there is something missing so agent dont fail on validation.
-    ])
-        .describe("The new value to replace the existing one"),
+        z.any(),
+    ]),
 });
 // Union type for all patch operations
 export const patchOperationSchema = z.discriminatedUnion("op", [
@@ -112,7 +63,4 @@ export const patchOperationSchema = z.discriminatedUnion("op", [
     replaceOperationSchema,
 ]);
 // Schema for array of patch operations
-export const patchOperationsSchema = z
-    .array(patchOperationSchema)
-    .min(1)
-    .describe("Array of patch operations to apply to the content type. Must contain at least one operation.");
+export const patchOperationsSchema = z.array(patchOperationSchema).min(1);

package/build/schemas/referenceObjectSchema.js

@@ -1,9 +1,7 @@
 import z from "zod";
-// Define a reusable reference object schema
-export const referenceObjectSchema = z
-    .object({
+// Reference by id, codename, or external_id (id preferred)
+export const referenceObjectSchema = z.object({
     id: z.string().optional(),
     codename: z.string().optional(),
     external_id: z.string().optional(),
-})
-    .describe("An object with an id, codename, or external_id property referencing another item. Using id is preferred for better performance.");
+});

package/build/schemas/taxonomySchemas.js

@@ -8,16 +8,11 @@ const taxonomyTermSchema = z.object({
 });
 // Schema for a taxonomy group
 export const taxonomyGroupSchemas = {
-    name: z.string().describe("Display name of the taxonomy group"),
+    name: z.string().describe("Taxonomy group name"),
     codename: z
         .string()
         .optional()
-        .describe("Codename of the taxonomy group (optional, will be generated if not provided)"),
-    external_id: z
-        .string()
-        .optional()
-        .describe("External ID of the taxonomy group (optional)"),
-    terms: z
-        .array(taxonomyTermSchema)
-        .describe("Hierarchical structure of taxonomy terms"),
+        .describe("Codename (auto-generated if omitted)"),
+    external_id: z.string().optional().describe("External ID"),
+    terms: z.array(taxonomyTermSchema).describe("Taxonomy terms hierarchy"),
 };