@kontent-ai/mcp-server 0.10.0 → 0.11.0

package/README.md

@@ -103,6 +103,12 @@ npx @kontent-ai/mcp-server@latest sse
 
 * **list-workflows-mapi** – List all workflows in the environment with their lifecycle stages and transitions
 * **change-variant-workflow-step-mapi** – Change the workflow step of a language variant (move content through workflow stages)
+* **publish-variant-mapi** – Publish or schedule a language variant for publication. Supports immediate publishing (happens right now) or scheduled publishing at a specific future date and time with optional timezone specification
+* **unpublish-variant-mapi** – Unpublish or schedule unpublishing of a language variant. Supports immediate unpublishing (removes content from Delivery API right now) or scheduled unpublishing at a specific future date and time with optional timezone specification
+
+### Utility
+
+* **get-current-datetime** – Get the current date and time in UTC (ISO-8601 format)
 
 ## ⚙️ Configuration
 

package/build/server.js

@@ -9,6 +9,7 @@ import { registerTool as registerDeleteContentItemMapi } from "./tools/delete-co
 import { registerTool as registerDeleteLanguageVariantMapi } from "./tools/delete-language-variant-mapi.js";
 import { registerTool as registerFilterVariantsMapi } from "./tools/filter-variants-mapi.js";
 import { registerTool as registerGetAssetMapi } from "./tools/get-asset-mapi.js";
+import { registerTool as registerGetCurrentDatetime } from "./tools/get-current-datetime.js";
 import { registerTool as registerGetInitialContext } from "./tools/get-initial-context.js";
 import { registerTool as registerGetItemDapi } from "./tools/get-item-dapi.js";
 import { registerTool as registerGetItemMapi } from "./tools/get-item-mapi.js";
@@ -22,6 +23,8 @@ import { registerTool as registerListContentTypesMapi } from "./tools/list-conte
 import { registerTool as registerListLanguagesMapi } from "./tools/list-languages-mapi.js";
 import { registerTool as registerListTaxonomyGroupsMapi } from "./tools/list-taxonomy-groups-mapi.js";
 import { registerTool as registerListWorkflowsMapi } from "./tools/list-workflows-mapi.js";
+import { registerTool as registerPublishVariantMapi } from "./tools/publish-variant-mapi.js";
+import { registerTool as registerUnpublishVariantMapi } from "./tools/unpublish-variant-mapi.js";
 import { registerTool as registerUpdateContentItemMapi } from "./tools/update-content-item-mapi.js";
 import { registerTool as registerUpsertLanguageVariantMapi } from "./tools/upsert-language-variant-mapi.js";
 // Create server instance
@@ -59,5 +62,8 @@ export const createServer = () => {
     registerListWorkflowsMapi(server);
     registerChangeVariantWorkflowStepMapi(server);
     registerFilterVariantsMapi(server);
+    registerPublishVariantMapi(server);
+    registerUnpublishVariantMapi(server);
+    registerGetCurrentDatetime(server);
     return { server };
 };

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

@@ -98,6 +98,10 @@ ALL FOUR elements must be included in language variant using their internal IDs:
 
 **Failure to provide the workflowId parameter will result in workflow step change failures.**
 
+### Current date and time
+
+**CRITICAL**: Always use the **get-current-datetime tool** to obtain the current UTC time. Never assume the current time.
+
 ## Essential Concepts
 
 **Taxonomies** provide hierarchical content categorization, allowing you to organize and tag content systematically.

package/build/tools/get-current-datetime.js

@@ -0,0 +1,9 @@
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+export const registerTool = (server) => {
+    server.tool("get-current-datetime", "Get the current date and time in UTC (ISO-8601 format)", {}, async () => {
+        const now = new Date();
+        return createMcpToolSuccessResponse({
+            datetime: now.toISOString(),
+        });
+    });
+};

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

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { createMapiClient } from "../clients/kontentClients.js";
+import { handleMcpToolError } from "../utils/errorHandler.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+export const registerTool = (server) => {
+    server.tool("publish-variant-mapi", "Publish or schedule a language variant of a content item in Kontent.ai. This operation can either immediately publish the variant (publishing happens right now) or schedule it for publication at a specific future date and time. For immediate publishing: the variant is published immediately and becomes available through the Delivery API. For scheduled publishing: the variant moves to a 'Scheduled' workflow state and will automatically transition to 'Published' at the specified time. The variant must be in a valid state with all required fields filled and validation rules satisfied. A variant can only be published if a transition is defined between the variant's current workflow step and the Published workflow step.", {
+        itemId: z
+            .string()
+            .uuid()
+            .describe("Internal ID (UUID) of the content item whose language variant you want to publish or schedule. This identifies the content item container that holds all language variants."),
+        languageId: z
+            .string()
+            .uuid()
+            .describe("Internal ID (UUID) of the language variant to publish or schedule. Use '00000000-0000-0000-0000-000000000000' for the default language. Each language in your project has a unique ID that identifies the specific variant."),
+        scheduledTo: z
+            .string()
+            .datetime()
+            .optional()
+            .describe("ISO 8601 formatted date and time when the publish action should occur (e.g., '2024-12-25T10:00:00Z' for UTC or '2024-12-25T10:00:00+02:00' for specific timezone). If not provided, the variant will be published immediately. If provided, must be a future date/time. The actual execution may have up to 5 minutes delay from the specified time."),
+        displayTimezone: z
+            .string()
+            .optional()
+            .describe("The timezone identifier for displaying the scheduled time in the Kontent.ai UI (e.g., 'America/New_York', 'Europe/London', 'UTC'). This parameter is used for scheduled publishing to specify the timezone context for the scheduled_to parameter. If not provided, the system will use the default timezone. This helps content creators understand when content will be published in their local context."),
+    }, async ({ itemId, languageId, scheduledTo, displayTimezone }) => {
+        const client = createMapiClient();
+        try {
+            // Validate that displayTimezone can only be used with scheduledTo
+            if (displayTimezone && !scheduledTo) {
+                throw new Error("The 'displayTimezone' parameter can only be used in combination with 'scheduledTo' parameter for scheduled publishing.");
+            }
+            let action;
+            let message;
+            if (scheduledTo) {
+                // Scheduled publishing
+                const requestData = {
+                    scheduled_to: scheduledTo,
+                };
+                // Add display_timezone if provided
+                if (displayTimezone) {
+                    requestData.display_timezone = displayTimezone;
+                }
+                await client
+                    .publishLanguageVariant()
+                    .byItemId(itemId)
+                    .byLanguageId(languageId)
+                    .withData(requestData)
+                    .toPromise();
+                action = "scheduled";
+                message = `Successfully scheduled language variant '${languageId}' for content item '${itemId}' to be published at '${scheduledTo}'${displayTimezone ? ` (timezone: ${displayTimezone})` : ""}.`;
+            }
+            else {
+                // Immediate publishing
+                await client
+                    .publishLanguageVariant()
+                    .byItemId(itemId)
+                    .byLanguageId(languageId)
+                    .withoutData()
+                    .toPromise();
+                action = "published";
+                message = `Successfully published language variant '${languageId}' for content item '${itemId}'. The content is now live and available through Delivery API.`;
+            }
+            return createMcpToolSuccessResponse({
+                message,
+                result: {
+                    itemId,
+                    languageId,
+                    scheduledTo: scheduledTo || null,
+                    displayTimezone: displayTimezone || null,
+                    action,
+                    timestamp: new Date().toISOString(),
+                },
+            });
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Publish/Schedule Language Variant");
+        }
+    });
+};

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

@@ -0,0 +1,78 @@
+import { z } from "zod";
+import { createMapiClient } from "../clients/kontentClients.js";
+import { handleMcpToolError } from "../utils/errorHandler.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+export const registerTool = (server) => {
+    server.tool("unpublish-variant-mapi", "Unpublish or schedule unpublishing of a language variant of a content item in Kontent.ai. This operation can either immediately unpublish the variant (making it unavailable through the Delivery API) or schedule it for unpublishing at a specific future date and time. For immediate unpublishing: the variant is unpublished right away and moves to the 'Archived' workflow step, becoming unavailable through the Delivery API. For scheduled unpublishing: the variant remains published but is scheduled to be automatically unpublished at the specified time. The variant must currently be in the 'Published' state for this operation to succeed.", {
+        itemId: z
+            .string()
+            .uuid()
+            .describe("Internal ID (UUID) of the content item whose language variant you want to unpublish or schedule for unpublishing. This identifies the content item container that holds all language variants."),
+        languageId: z
+            .string()
+            .uuid()
+            .describe("Internal ID (UUID) of the language variant to unpublish or schedule for unpublishing. Use '00000000-0000-0000-0000-000000000000' for the default language. Each language in your project has a unique ID that identifies the specific variant."),
+        scheduledTo: z
+            .string()
+            .datetime()
+            .optional()
+            .describe("ISO 8601 formatted date and time when the unpublish action should occur (e.g., '2024-12-25T10:00:00Z' for UTC or '2024-12-25T10:00:00+02:00' for specific timezone). If not provided, the variant will be unpublished immediately. If provided, must be a future date/time. The actual execution may have up to 5 minutes delay from the specified time. When unpublished, the content will no longer be available through the Delivery API."),
+        displayTimezone: z
+            .string()
+            .optional()
+            .describe("The timezone identifier for displaying the scheduled time in the Kontent.ai UI (e.g., 'America/New_York', 'Europe/London', 'UTC'). This parameter is used for scheduled unpublishing to specify the timezone context for the scheduled_to parameter. If not provided, the system will use the default timezone. This helps content creators understand when content will be unpublished in their local context."),
+    }, async ({ itemId, languageId, scheduledTo, displayTimezone }) => {
+        const client = createMapiClient();
+        try {
+            // Validate that displayTimezone can only be used with scheduledTo
+            if (displayTimezone && !scheduledTo) {
+                throw new Error("The 'displayTimezone' parameter can only be used in combination with 'scheduledTo' parameter for scheduled unpublishing.");
+            }
+            let action;
+            let message;
+            if (scheduledTo) {
+                // Scheduled unpublishing
+                const requestData = {
+                    scheduled_to: scheduledTo,
+                };
+                // Add display_timezone if provided
+                if (displayTimezone) {
+                    requestData.display_timezone = displayTimezone;
+                }
+                await client
+                    .unpublishLanguageVariant()
+                    .byItemId(itemId)
+                    .byLanguageId(languageId)
+                    .withData(requestData)
+                    .toPromise();
+                action = "scheduled for unpublishing";
+                message = `Successfully scheduled language variant '${languageId}' for content item '${itemId}' to be unpublished at '${scheduledTo}'${displayTimezone ? ` (timezone: ${displayTimezone})` : ""}. The content will be removed from Delivery API at the scheduled time.`;
+            }
+            else {
+                // Immediate unpublishing
+                await client
+                    .unpublishLanguageVariant()
+                    .byItemId(itemId)
+                    .byLanguageId(languageId)
+                    .withoutData()
+                    .toPromise();
+                action = "unpublished";
+                message = `Successfully unpublished language variant '${languageId}' for content item '${itemId}'. The content has been moved to Archived and is no longer available through Delivery API.`;
+            }
+            return createMcpToolSuccessResponse({
+                message,
+                result: {
+                    itemId,
+                    languageId,
+                    scheduledTo: scheduledTo || null,
+                    displayTimezone: displayTimezone || null,
+                    action,
+                    timestamp: new Date().toISOString(),
+                },
+            });
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Unpublish/Schedule Unpublishing Language Variant");
+        }
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontent-ai/mcp-server",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "type": "module",
   "scripts": {
     "build": "rimraf build && tsc",