@kontent-ai/mcp-server 0.8.2 → 0.10.0

package/README.md

@@ -88,6 +88,7 @@ npx @kontent-ai/mcp-server@latest sse
 * **delete-content-item-mapi** – Delete a content item by internal ID
 * **upsert-language-variant-mapi** – Create or update a language variant with content using internal IDs
 * **delete-language-variant-mapi** – Delete a language variant of a content item by internal IDs
+* **filter-variants-mapi** – Search and filter language variants using filters and search phrases
 
 ### Asset Management
 
@@ -98,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/contentItemSchemas.js

@@ -1,11 +1,5 @@
 import { z } from "zod";
-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.");
+import { referenceObjectSchema } from "./referenceObjectSchema.js";
 const languageVariantElementBaseSchema = z.object({
     element: referenceObjectSchema,
     value: z.any(),

package/build/schemas/filterVariantSchemas.js

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { referenceObjectSchema } from "./referenceObjectSchema.js";
+const userReferenceSchema = z.object({
+    id: z.string().optional().describe("User identifier"),
+    email: z.string().email().optional().describe("User email address"),
+});
+// Search variants tool input schema
+export const filterVariantsSchema = z.object({
+    search_phrase: z
+        .string()
+        .optional()
+        .describe("Search phrase to look for in content"),
+    content_types: z
+        .array(referenceObjectSchema)
+        .min(1)
+        .optional()
+        .describe("Array of references to content types by their id, codename, or external id"),
+    contributors: z
+        .array(userReferenceSchema)
+        .min(1)
+        .optional()
+        .describe("Array of references to users by their id or email"),
+    completion_statuses: z
+        .array(z.enum(["unfinished", "completed", "not_translated", "all_done"]))
+        .min(1)
+        .optional()
+        .describe("Array of completion statuses to filter by. It is not the same thing as workflow steps, it reflects e.g. not filled in required elements"),
+    language: referenceObjectSchema
+        .optional()
+        .describe("Reference to a language by its id, codename, or external id (defaults to default language)"),
+    workflow_steps: z
+        .array(z.object({
+        workflow_identifier: referenceObjectSchema.describe("Reference to a workflow by its id, codename, or external id"),
+        step_identifiers: z
+            .array(referenceObjectSchema)
+            .min(1)
+            .describe("Array of references to workflow steps by their id, codename, or external id"),
+    }))
+        .min(1)
+        .optional()
+        .describe("Array of workflows with workflow steps"),
+    order_by: z
+        .enum(["name", "due", "last_modified"])
+        .optional()
+        .describe("Field to order by"),
+    order_direction: z
+        .enum(["asc", "desc"])
+        .optional()
+        .describe("Order direction"),
+    continuation_token: z
+        .string()
+        .optional()
+        .describe("Continuation token for pagination"),
+});

package/build/schemas/referenceObjectSchema.js

@@ -0,0 +1,9 @@
+import z from "zod";
+// Define a reusable reference object schema
+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/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,8 +4,10 @@ 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 registerGetInitialContext } from "./tools/get-initial-context.js";
 import { registerTool as registerGetItemDapi } from "./tools/get-item-dapi.js";
@@ -19,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
@@ -53,5 +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/filter-variants-mapi.js

@@ -0,0 +1,66 @@
+import { filterVariantsSchema } from "../schemas/filterVariantSchemas.js";
+import { handleMcpToolError } from "../utils/errorHandler.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+import { throwError } from "../utils/throwError.js";
+export const registerTool = (server) => {
+    server.tool("filter-variants-mapi", "Search and filter language variants of content items using the Management API.", filterVariantsSchema.shape, async ({ search_phrase, content_types, contributors, completion_statuses, language, workflow_steps, order_by, order_direction, continuation_token, }) => {
+        try {
+            const requestPayload = {
+                filters: {
+                    search_phrase,
+                    content_types,
+                    contributors,
+                    completion_statuses,
+                    language,
+                    workflow_steps,
+                },
+                order: order_by
+                    ? {
+                        by: order_by,
+                        direction: order_direction === "desc" ? "Descending" : "Ascending",
+                    }
+                    : null,
+            };
+            const environmentId = process.env.KONTENT_ENVIRONMENT_ID;
+            const apiKey = process.env.KONTENT_API_KEY;
+            if (!environmentId || !apiKey) {
+                throwError("Missing required environment variables");
+            }
+            const url = `https://manage.kontent.ai/v2/projects/${environmentId}/early-access/variants/filter`;
+            const headers = {
+                Authorization: `Bearer ${apiKey}`,
+                "Content-Type": "application/json",
+            };
+            if (continuation_token) {
+                headers["X-Continuation"] = continuation_token;
+            }
+            const response = await fetch(url, {
+                method: "POST",
+                headers: headers,
+                body: JSON.stringify(requestPayload),
+            });
+            if (!response.ok) {
+                const responseText = await response.text();
+                let responseData;
+                try {
+                    responseData = JSON.parse(responseText);
+                }
+                catch {
+                    responseData = responseText;
+                }
+                const error = new Error(`HTTP error! status: ${response.status}`);
+                error.response = {
+                    status: response.status,
+                    statusText: response.statusText,
+                    data: responseData,
+                };
+                throw error;
+            }
+            const responseData = await response.json();
+            return createMcpToolSuccessResponse(responseData);
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Variant Search");
+        }
+    });
+};

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