@kontent-ai/mcp-server 0.9.0 → 0.11.0

package/README.md

@@ -99,6 +99,17 @@ npx @kontent-ai/mcp-server@latest sse
 
 * **list-languages-mapi** – List all languages configured in the environment
 
+### Workflow Management
+
+* **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
 
 The server requires the following environment variables:

package/build/schemas/workflowSchemas.js

@@ -0,0 +1,106 @@
+import { z } from "zod";
+// Schema for a workflow step
+const workflowStepSchema = z.object({
+    id: z
+        .string()
+        .uuid()
+        .describe("The unique identifier of the workflow step in UUID format"),
+    name: z.string().describe("The human-readable name of the workflow step"),
+    codename: z
+        .string()
+        .describe("The codename of the workflow step used for API operations"),
+    transitions_to: z
+        .array(z.string().uuid())
+        .describe("Array of workflow step IDs that this step can transition to")
+        .optional(),
+    role_ids: z
+        .array(z.string().uuid())
+        .describe("Array of role IDs that have permissions for this workflow step")
+        .optional(),
+});
+// Schema for the published step
+const publishedStepSchema = z.object({
+    id: z
+        .string()
+        .uuid()
+        .describe("The unique identifier of the published step in UUID format"),
+    name: z
+        .string()
+        .describe("The name of the published step - typically 'Published'"),
+    codename: z
+        .string()
+        .describe("The codename of the published step - typically 'published'"),
+    unpublish_role_ids: z
+        .array(z.string().uuid())
+        .describe("Array of role IDs that can unpublish content from this step")
+        .optional(),
+    create_new_version_role_ids: z
+        .array(z.string().uuid())
+        .describe("Array of role IDs that can create new versions of content in this step")
+        .optional(),
+});
+// Schema for the scheduled step
+const scheduledStepSchema = z.object({
+    id: z
+        .string()
+        .uuid()
+        .describe("The unique identifier of the scheduled step in UUID format"),
+    name: z
+        .string()
+        .describe("The name of the scheduled step - typically 'Scheduled'"),
+    codename: z
+        .string()
+        .describe("The codename of the scheduled step - typically 'scheduled'"),
+});
+// Schema for the archived step
+const archivedStepSchema = z.object({
+    id: z
+        .string()
+        .uuid()
+        .describe("The unique identifier of the archived step in UUID format"),
+    name: z
+        .string()
+        .describe("The name of the archived step - typically 'Archived'"),
+    codename: z
+        .string()
+        .describe("The codename of the archived step - typically 'archived'"),
+    role_ids: z
+        .array(z.string().uuid())
+        .describe("Array of role IDs that can unarchive content from this step")
+        .optional(),
+});
+// Schema for workflow scope
+const workflowScopeSchema = z.object({
+    content_types: z
+        .array(z.object({
+        id: z
+            .string()
+            .uuid()
+            .describe("The unique identifier of the content type in UUID format"),
+    }))
+        .describe("Array of content types that this workflow applies to"),
+});
+// Main workflow schema
+export const workflowSchema = z.object({
+    id: z
+        .string()
+        .uuid()
+        .describe("The unique identifier of the workflow in UUID format"),
+    name: z.string().describe("The human-readable name of the workflow"),
+    codename: z
+        .string()
+        .describe("The codename of the workflow used for API operations"),
+    scopes: z
+        .array(workflowScopeSchema)
+        .describe("Array of scopes defining which content types use this workflow"),
+    steps: z
+        .array(workflowStepSchema)
+        .describe("Array of custom workflow steps between draft and published states"),
+    published_step: publishedStepSchema.describe("The published step configuration of the workflow"),
+    scheduled_step: scheduledStepSchema.describe("The scheduled step configuration of the workflow"),
+    archived_step: archivedStepSchema.describe("The archived step configuration of the workflow"),
+});
+// Schema for the list workflows response
+export const listWorkflowsResponseSchema = z
+    .array(workflowSchema)
+    .describe("Array of workflows in the project");

package/build/server.js

@@ -4,10 +4,12 @@ import { registerTool as registerAddContentItemMapi } from "./tools/add-content-
 import { registerTool as registerAddContentTypeMapi } from "./tools/add-content-type-mapi.js";
 import { registerTool as registerAddContentTypeSnippetMapi } from "./tools/add-content-type-snippet-mapi.js";
 import { registerTool as registerAddTaxonomyGroupMapi } from "./tools/add-taxonomy-group-mapi.js";
+import { registerTool as registerChangeVariantWorkflowStepMapi } from "./tools/change-variant-workflow-step-mapi.js";
 import { registerTool as registerDeleteContentItemMapi } from "./tools/delete-content-item-mapi.js";
 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";
@@ -20,6 +22,9 @@ import { registerTool as registerListContentTypeSnippetsMapi } from "./tools/lis
 import { registerTool as registerListContentTypesMapi } from "./tools/list-content-types-mapi.js";
 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
@@ -54,6 +59,11 @@ export const createServer = () => {
     registerDeleteContentItemMapi(server);
     registerUpsertLanguageVariantMapi(server);
     registerDeleteLanguageVariantMapi(server);
+    registerListWorkflowsMapi(server);
+    registerChangeVariantWorkflowStepMapi(server);
     registerFilterVariantsMapi(server);
+    registerPublishVariantMapi(server);
+    registerUnpublishVariantMapi(server);
+    registerGetCurrentDatetime(server);
     return { server };
 };

package/build/tools/change-variant-workflow-step-mapi.js

@@ -0,0 +1,48 @@
+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("change-variant-workflow-step-mapi", "Change the workflow step of a language variant in Kontent.ai. This operation moves a language variant to a different step in the workflow, enabling content lifecycle management such as moving content from draft to review, review to published, etc.", {
+        itemId: z
+            .string()
+            .uuid()
+            .describe("Internal ID (UUID) of the content item whose language variant workflow step you want to change"),
+        languageId: z
+            .string()
+            .uuid()
+            .describe("Internal ID (UUID) of the language variant. Use '00000000-0000-0000-0000-000000000000' for the default language"),
+        workflowId: z
+            .string()
+            .uuid()
+            .describe("Internal ID (UUID) of the workflow. This is the workflow that contains the target step"),
+        workflowStepId: z
+            .string()
+            .uuid()
+            .describe("Internal ID (UUID) of the target workflow step. This must be a valid step ID from the specified workflow. Common steps include Draft, Review, Published, and Archived, but the actual IDs depend on your specific workflow configuration"),
+    }, async ({ itemId, languageId, workflowId, workflowStepId }) => {
+        const client = createMapiClient();
+        try {
+            const response = await client
+                .changeWorkflowOfLanguageVariant()
+                .byItemId(itemId)
+                .byLanguageId(languageId)
+                .withData({
+                workflow_identifier: {
+                    id: workflowId,
+                },
+                step_identifier: {
+                    id: workflowStepId,
+                },
+            })
+                .toPromise();
+            return createMcpToolSuccessResponse({
+                message: `Successfully changed workflow step of language variant '${languageId}' for content item '${itemId}' to workflow step '${workflowStepId}'`,
+                result: response.data,
+            });
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Workflow Step Change");
+        }
+    });
+};

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

@@ -80,6 +80,28 @@ ALL FOUR elements must be included in language variant using their internal IDs:
 - Create new language variants when expanding to additional languages
 - Organize with taxonomies for better content categorization
 
+### Workflow Step Management
+
+**CRITICAL**: When changing workflow steps of language variants, you must:
+
+1. **Provide the workflowId parameter** - This is mandatory for all workflow step changes
+2. **Use internal IDs** for itemId, languageId, and workflowStepId parameters
+3. **Ensure the target workflow step exists** in the specified workflow
+
+**WORKFLOW ID REQUIREMENT**: The workflowId parameter identifies which workflow contains the target step. Different content types may use different workflows, so always specify the correct workflow ID when changing workflow steps.
+
+**Example**: To move a language variant to a "review" step:
+- itemId: "content_item_internal_id"
+- languageId: "language_internal_id" 
+- workflowStepId: "review_step_internal_id"
+- workflowId: "workflow_internal_id" (MANDATORY)
+
+**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/list-workflows-mapi.js

@@ -0,0 +1,15 @@
+import { createMapiClient } from "../clients/kontentClients.js";
+import { handleMcpToolError } from "../utils/errorHandler.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+export const registerTool = (server) => {
+    server.tool("list-workflows-mapi", "Get all workflows from Management API. Workflows define the content lifecycle stages and transitions between them.", {}, async () => {
+        const client = createMapiClient();
+        try {
+            const response = await client.listWorkflows().toPromise();
+            return createMcpToolSuccessResponse(response.data);
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Workflows Listing");
+        }
+    });
+};

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.9.0",
+  "version": "0.11.0",
   "type": "module",
   "scripts": {
     "build": "rimraf build && tsc",