@kontent-ai/mcp-server 0.9.0 → 0.10.0

package/README.md

@@ -99,6 +99,11 @@ 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)
+
 ## ⚙️ 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,6 +4,7 @@ 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";
@@ -20,6 +21,7 @@ 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 registerUpdateContentItemMapi } from "./tools/update-content-item-mapi.js";
 import { registerTool as registerUpsertLanguageVariantMapi } from "./tools/upsert-language-variant-mapi.js";
 // Create server instance
@@ -54,6 +56,8 @@ export const createServer = () => {
     registerDeleteContentItemMapi(server);
     registerUpsertLanguageVariantMapi(server);
     registerDeleteLanguageVariantMapi(server);
+    registerListWorkflowsMapi(server);
+    registerChangeVariantWorkflowStepMapi(server);
     registerFilterVariantsMapi(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,24 @@ 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.**
+
 ## Essential Concepts
 
 **Taxonomies** provide hierarchical content categorization, allowing you to organize and tag content systematically.

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/package.json

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