@kontent-ai/mcp-server 0.24.0 → 0.26.0

package/README.md

@@ -121,9 +121,9 @@ npx @kontent-ai/mcp-server@latest shttp
 
 ### Language Management
 
-* **list-languages-mapi** – Get all Kontent.ai languages from Management API
-* **add-language-mapi** – Add new Kontent.ai language via Management API
-* **patch-language-mapi** – Update Kontent.ai language using replace operations via Management API
+* **list-languages-mapi** – Get all Kontent.ai languages from Management API (includes both active and inactive - check is_active property)
+* **add-language-mapi** – Add new Kontent.ai language via Management API (languages are always created as active)
+* **patch-language-mapi** – Update Kontent.ai language using replace operations via Management API (only active languages can be modified - to activate/deactivate, use the Kontent.ai web UI)
 
 ### Collection Management
 
@@ -137,9 +137,16 @@ npx @kontent-ai/mcp-server@latest shttp
 * **patch-space-mapi** – Patch Kontent.ai space using replace operations
 * **delete-space-mapi** – Delete Kontent.ai space
 
+### Role Management
+
+* **list-roles-mapi** – Get all Kontent.ai roles from Management API. Requires Enterprise or Flex plan with "Manage custom roles" permission
+
 ### Workflow Management
 
 * **list-workflows-mapi** – Get all Kontent.ai workflows from Management API. Workflows define the content lifecycle stages and transitions between them
+* **add-workflow-mapi** – Create a new Kontent.ai workflow via Management API. Define custom workflow steps, transitions, scopes (content types and collections), and role permissions
+* **update-workflow-mapi** – Update an existing Kontent.ai workflow by ID via Management API. Modify steps, transitions, scopes, and role permissions. Cannot remove steps that are in use
+* **delete-workflow-mapi** – Delete a Kontent.ai workflow by ID via Management API. The workflow must not be in use by any content items
 * **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.
 * **publish-variant-mapi** – Publish or schedule a language variant of a content item in Kontent.ai. This operation can either immediately publish the variant or schedule it for publication at a specific future date and time with optional timezone specification
 * **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 with optional timezone specification

package/build/schemas/languageSchemas.js

@@ -3,10 +3,6 @@ import { referenceObjectSchema } from "./referenceObjectSchema.js";
 export const addLanguageSchema = z.object({
     name: z.string().describe("Display name of the language"),
     codename: z.string().describe("Codename identifier for the language"),
-    is_active: z
-        .boolean()
-        .optional()
-        .describe("Whether the language is active (defaults to true)"),
     fallback_language: referenceObjectSchema
         .optional()
         .describe("Reference to fallback language (by id, codename, or external_id)"),
@@ -23,11 +19,6 @@ const languageReplaceOperationSchema = z.discriminatedUnion("property_name", [
         property_name: z.literal("name"),
         value: z.string(),
     }),
-    z.object({
-        op: z.literal("replace"),
-        property_name: z.literal("is_active"),
-        value: z.boolean(),
-    }),
     z.object({
         op: z.literal("replace"),
         property_name: z.literal("fallback_language"),
@@ -39,5 +30,5 @@ export const patchLanguageSchema = z.object({
     operations: z
         .array(languageReplaceOperationSchema)
         .min(1)
-        .describe("Array of replace operations for codename, name, is_active, or fallback_language. Note: Only active languages can be modified - if language is deactivated, is_active: true must be first operation."),
+        .describe("Array of replace operations for codename, name, or fallback_language. Note: Only active languages can be modified. To activate/deactivate languages, use the Kontent.ai web UI."),
 });

package/build/schemas/searchOperationSchemas.js

@@ -3,9 +3,9 @@ export const searchOperationSchema = z.object({
     searchPhrase: z
         .string()
         .describe("Search phrase for AI-powered semantic search. Uses vector database to find content by meaning and similarity, not just exact keyword matching"),
-    filter: z
-        .object({
-        variantId: z.guid().describe("UUID of the language variant to filter by"),
-    })
-        .describe("Mandatory content item variant filter to restrict search scope. Must specify a valid variant UUID"),
+    filter: z.object({
+        variantId: z
+            .guid()
+            .describe("Language ID from list-languages-mapi. Use default language (is_default=true) if not specified by user."),
+    }),
 });

package/build/schemas/workflowSchemas.js

@@ -1,98 +1,96 @@
 import { z } from "zod";
-// Schema for a workflow step
-const workflowStepSchema = z.object({
-    id: z
-        .guid()
-        .describe("The unique identifier of the workflow step in UUID format"),
-    name: z.string().describe("The human-readable name of the workflow step"),
+import { referenceObjectSchema } from "./referenceObjectSchema.js";
+// Step color options (matching SDK WorkflowColor type)
+const workflowStepColorSchema = z
+    .enum([
+    "gray",
+    "red",
+    "rose",
+    "light-purple",
+    "dark-purple",
+    "dark-blue",
+    "light-blue",
+    "sky-blue",
+    "mint-green",
+    "persian-green",
+    "dark-green",
+    "light-green",
+    "yellow",
+    "pink",
+    "orange",
+    "brown",
+])
+    .describe("Color of the workflow step displayed in the UI");
+// Transition reference schema (step codename reference)
+const transitionToStepSchema = z.object({
+    codename: z.string().optional().describe("Target step codename"),
+    id: z.guid().optional().describe("Target step ID (for update operations)"),
+});
+const transitionToSchema = z.object({
+    step: transitionToStepSchema.describe("Reference to the target step"),
+});
+// Workflow step input schema (for creating/updating workflows)
+const workflowStepInputSchema = z.object({
+    name: z.string().describe("Human-readable name of the workflow step"),
     codename: z
         .string()
-        .describe("The codename of the workflow step used for API operations"),
+        .describe("Codename of the workflow step. Must be unique across all workflows - usually prepended with the workflow codename."),
+    id: z
+        .guid()
+        .optional()
+        .readonly()
+        .describe("Read-only workflow step ID (useful to reference a step when updating its codename)"),
+    color: workflowStepColorSchema,
     transitions_to: z
-        .array(z.guid())
-        .describe("Array of workflow step IDs that this step can transition to")
-        .optional(),
+        .array(transitionToSchema)
+        .min(1)
+        .describe("Array of step references this step can transition to."),
     role_ids: z
         .array(z.guid())
-        .describe("Array of role IDs that have permissions for this workflow step")
-        .optional(),
+        .min(1)
+        .describe("Array of role IDs that have permissions for this step."),
 });
-// Schema for the published step
-const publishedStepSchema = z.object({
-    id: z
-        .guid()
-        .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'"),
+// Published step input schema
+const publishedStepInputSchema = z.object({
     unpublish_role_ids: z
         .array(z.guid())
-        .describe("Array of role IDs that can unpublish content from this step")
-        .optional(),
+        .min(1)
+        .describe("Array of role IDs that can unpublish content."),
     create_new_version_role_ids: z
         .array(z.guid())
-        .describe("Array of role IDs that can create new versions of content in this step")
-        .optional(),
+        .min(1)
+        .describe("Array of role IDs that can create new versions."),
 });
-// Schema for the scheduled step
-const scheduledStepSchema = z.object({
-    id: z
-        .guid()
-        .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
-        .guid()
-        .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'"),
+// Archived step input schema
+const archivedStepInputSchema = z.object({
     role_ids: z
         .array(z.guid())
-        .describe("Array of role IDs that can unarchive content from this step")
-        .optional(),
+        .min(1)
+        .describe("Array of role IDs that can restore archived content."),
 });
-// Schema for workflow scope
-const workflowScopeSchema = z.object({
+// Workflow scope input schema
+const workflowScopeInputSchema = z.object({
     content_types: z
-        .array(z.object({
-        id: z
-            .guid()
-            .describe("The unique identifier of the content type in UUID format"),
-    }))
-        .describe("Array of content types that this workflow applies to"),
+        .array(referenceObjectSchema)
+        .describe("Content types this workflow applies to"),
+    collections: z
+        .array(referenceObjectSchema)
+        .optional()
+        .describe("Collections this workflow applies to"),
 });
-// Main workflow schema
-export const workflowSchema = z.object({
-    id: z.guid().describe("The unique identifier of the workflow in UUID format"),
-    name: z.string().describe("The human-readable name of the workflow"),
+// Main add/update workflow schema
+export const workflowInputSchema = z.object({
+    name: z.string().describe("Human-readable name of the workflow"),
     codename: z
         .string()
-        .describe("The codename of the workflow used for API operations"),
+        .optional()
+        .describe("Codename for API operations (auto-generated if omitted)"),
     scopes: z
-        .array(workflowScopeSchema)
-        .describe("Array of scopes defining which content types use this workflow"),
+        .array(workflowScopeInputSchema)
+        .describe("Array of scopes defining which combinations of content types and collections this workflow applies to. If both content types and collections are empty, the workflow can be used for any type of content in collection that isn't limited to any other 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"),
+        .array(workflowStepInputSchema)
+        .describe("Array of custom workflow steps"),
+    published_step: publishedStepInputSchema.describe("Configuration for the published step"),
+    archived_step: archivedStepInputSchema.describe("Configuration for the archived step"),
 });
-// Schema for the list workflows response
-export const listWorkflowsResponseSchema = z
-    .array(workflowSchema)
-    .describe("Array of workflows in the project");

package/build/server.js

@@ -6,6 +6,7 @@ import { registerTool as registerAddContentTypeSnippetMapi } from "./tools/add-c
 import { registerTool as registerAddLanguageMapi } from "./tools/add-language-mapi.js";
 import { registerTool as registerAddSpaceMapi } from "./tools/add-space-mapi.js";
 import { registerTool as registerAddTaxonomyGroupMapi } from "./tools/add-taxonomy-group-mapi.js";
+import { registerTool as registerAddWorkflowMapi } from "./tools/add-workflow-mapi.js";
 import { registerTool as registerChangeVariantWorkflowStepMapi } from "./tools/change-variant-workflow-step-mapi.js";
 import { registerTool as registerCreateVariantVersionMapi } from "./tools/create-variant-version-mapi.js";
 import { registerTool as registerDeleteContentItemMapi } from "./tools/delete-content-item-mapi.js";
@@ -14,6 +15,7 @@ import { registerTool as registerDeleteLanguageVariantMapi } from "./tools/delet
 import { registerTool as registerDeleteSpaceMapi } from "./tools/delete-space-mapi.js";
 import { registerTool as registerDeleteTaxonomyGroupMapi } from "./tools/delete-taxonomy-group-mapi.js";
 import { registerTool as registerDeleteTypeSnippetMapi } from "./tools/delete-type-snippet-mapi.js";
+import { registerTool as registerDeleteWorkflowMapi } from "./tools/delete-workflow-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 registerGetItemMapi } from "./tools/get-item-mapi.js";
@@ -29,6 +31,7 @@ import { registerTool as registerListCollectionsMapi } from "./tools/list-collec
 import { registerTool as registerListContentTypeSnippetsMapi } from "./tools/list-content-type-snippets-mapi.js";
 import { registerTool as registerListContentTypesMapi } from "./tools/list-content-types-mapi.js";
 import { registerTool as registerListLanguagesMapi } from "./tools/list-languages-mapi.js";
+import { registerTool as registerListRolesMapi } from "./tools/list-roles-mapi.js";
 import { registerTool as registerListSpacesMapi } from "./tools/list-spaces-mapi.js";
 import { registerTool as registerListTaxonomyGroupsMapi } from "./tools/list-taxonomy-groups-mapi.js";
 import { registerTool as registerListVariantsCollectionMapi } from "./tools/list-variants-collection-mapi.js";
@@ -49,6 +52,7 @@ import { registerTool as registerSearchVariantsMapi } from "./tools/search-varia
 import { registerTool as registerUnpublishVariantMapi } from "./tools/unpublish-variant-mapi.js";
 import { registerTool as registerUpdateAssetMapi } from "./tools/update-asset-mapi.js";
 import { registerTool as registerUpdateContentItemMapi } from "./tools/update-content-item-mapi.js";
+import { registerTool as registerUpdateWorkflowMapi } from "./tools/update-workflow-mapi.js";
 import { registerTool as registerUpsertLanguageVariantMapi } from "./tools/upsert-language-variant-mapi.js";
 // Create server instance
 export const createServer = () => {
@@ -78,6 +82,7 @@ export const createServer = () => {
     registerAddSpaceMapi(server);
     registerPatchSpaceMapi(server);
     registerDeleteSpaceMapi(server);
+    registerListRolesMapi(server);
     registerGetAssetMapi(server);
     registerListAssetsMapi(server);
     registerUpdateAssetMapi(server);
@@ -102,6 +107,9 @@ export const createServer = () => {
     registerCreateVariantVersionMapi(server);
     registerDeleteLanguageVariantMapi(server);
     registerListWorkflowsMapi(server);
+    registerAddWorkflowMapi(server);
+    registerUpdateWorkflowMapi(server);
+    registerDeleteWorkflowMapi(server);
     registerChangeVariantWorkflowStepMapi(server);
     registerFilterVariantsMapi(server);
     registerSearchVariantsMapi(server);

package/build/tools/add-language-mapi.js

@@ -3,7 +3,7 @@ import { addLanguageSchema } from "../schemas/languageSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("add-language-mapi", "Add new Kontent.ai language via Management API", addLanguageSchema.shape, async ({ name, codename, is_active, fallback_language, external_id }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("add-language-mapi", "Add new Kontent.ai language via Management API. Languages are always created as active.", addLanguageSchema.shape, async ({ name, codename, fallback_language, external_id }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const response = await client
@@ -11,7 +11,7 @@ export const registerTool = (server) => {
                 .withData({
                 name,
                 codename,
-                is_active,
+                is_active: true,
                 fallback_language,
                 external_id,
             })

package/build/tools/add-workflow-mapi.js

@@ -0,0 +1,24 @@
+import { createMapiClient } from "../clients/kontentClients.js";
+import { workflowInputSchema } from "../schemas/workflowSchemas.js";
+import { handleMcpToolError } from "../utils/errorHandler.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+export const registerTool = (server) => {
+    server.tool("add-workflow-mapi", "Add new Kontent.ai workflow", workflowInputSchema.shape, async ({ name, codename, scopes, steps, published_step, archived_step }, { authInfo: { token, clientId } = {} }) => {
+        const client = createMapiClient(clientId, token);
+        const data = {
+            name,
+            codename,
+            scopes,
+            steps,
+            published_step,
+            archived_step,
+        };
+        try {
+            const response = await client.addWorkflow().withData(data).toPromise();
+            return createMcpToolSuccessResponse(response.rawData);
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Workflow Creation");
+        }
+    });
+};

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

@@ -4,12 +4,10 @@ import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
     server.tool("change-variant-workflow-step-mapi", "Change Kontent.ai variant workflow step", {
-        itemId: z.guid().describe("Content item UUID"),
-        languageId: z
-            .guid()
-            .describe("Language variant UUID (default: 00000000-0000-0000-0000-000000000000)"),
-        workflowId: z.guid().describe("Workflow UUID"),
-        workflowStepId: z.guid().describe("Target workflow step UUID"),
+        itemId: z.guid().describe("Content item ID"),
+        languageId: z.guid().describe("Language variant ID"),
+        workflowId: z.guid().describe("Workflow ID"),
+        workflowStepId: z.guid().describe("Target workflow step ID"),
     }, async ({ itemId, languageId, workflowId, workflowStepId }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {

package/build/tools/context/patch-guide-property-based.js

@@ -21,20 +21,16 @@ Available properties: name, codename, collections
 \`\`\`json
 { "op": "replace", "property_name": "name", "value": "New Language Name" }
 { "op": "replace", "property_name": "codename", "value": "new_codename" }
-{ "op": "replace", "property_name": "is_active", "value": true }
 { "op": "replace", "property_name": "fallback_language", "value": { "codename": "en-US" } }
 \`\`\`
 
-Available properties: name, codename, is_active, fallback_language
+Available properties: name, codename, fallback_language
 
 ## Critical Rule for Languages
-If a language is deactivated, you must activate it first before making other changes:
-\`\`\`json
-[
-  { "op": "replace", "property_name": "is_active", "value": true },
-  { "op": "replace", "property_name": "name", "value": "New Name" }
-]
-\`\`\`
+
+**Only active languages can be modified.** To activate or deactivate a language, the user must use the Kontent.ai web UI - this is a critical operation that cannot be performed via API tools.
+
+When user asks to update "all languages": only update active languages (is_active: true). If they need to modify inactive languages, inform them they must first activate those languages in the Kontent.ai web UI.
 
 ## General Rules
 - external_id cannot be modified after creation

package/build/tools/delete-workflow-mapi.js

@@ -0,0 +1,20 @@
+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("delete-workflow-mapi", {
+        id: z.guid().describe("Workflow ID"),
+    }, async ({ id }, { authInfo: { token, clientId } = {} }) => {
+        const client = createMapiClient(clientId, token);
+        try {
+            await client.deleteWorkflow().byWorkflowId(id).toPromise();
+            return createMcpToolSuccessResponse({
+                message: `Workflow '${id}' deleted successfully`,
+            });
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Workflow Deletion");
+        }
+    });
+};

package/build/tools/list-languages-mapi.js

@@ -3,7 +3,7 @@ import { listLanguagesSchema } from "../schemas/listSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("list-languages-mapi", "Get all Kontent.ai languages (paginated). Languages define available locales; each can have fallback language for content inheritance.", listLanguagesSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("list-languages-mapi", "Get all Kontent.ai languages (paginated), including inactive ones - check is_active property. Languages define available locales; each can have fallback language for content inheritance.", listLanguagesSchema.shape, async ({ continuation_token }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const query = client.listLanguages();

package/build/tools/list-roles-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-roles-mapi", "Get all Kontent.ai roles", {}, async (_, { authInfo: { token, clientId } = {} }) => {
+        const client = createMapiClient(clientId, token);
+        try {
+            const response = await client.listRoles().toPromise();
+            return createMcpToolSuccessResponse(response.rawData.roles);
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Roles Listing");
+        }
+    });
+};

package/build/tools/patch-language-mapi.js

@@ -3,7 +3,7 @@ import { patchLanguageSchema } from "../schemas/languageSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("patch-language-mapi", "Update Kontent.ai language using replace operations. Call get-patch-guide first. If deactivated, is_active: true must be first operation.", patchLanguageSchema.shape, async ({ languageId, operations }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("patch-language-mapi", "Update Kontent.ai language using replace operations. Call get-patch-guide first. Only active languages can be modified - to activate/deactivate, use the Kontent.ai web UI.", patchLanguageSchema.shape, async ({ languageId, operations }, { authInfo: { token, clientId } = {} }) => {
         const client = createMapiClient(clientId, token);
         try {
             const response = await client

package/build/tools/update-workflow-mapi.js

@@ -0,0 +1,32 @@
+import { z } from "zod";
+import { createMapiClient } from "../clients/kontentClients.js";
+import { workflowInputSchema } from "../schemas/workflowSchemas.js";
+import { handleMcpToolError } from "../utils/errorHandler.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+export const registerTool = (server) => {
+    server.tool("update-workflow-mapi", "Update Kontent.ai workflow", {
+        id: z.guid().describe("Workflow ID"),
+        ...workflowInputSchema.shape,
+    }, async ({ id, name, codename, scopes, steps, published_step, archived_step }, { authInfo: { token, clientId } = {} }) => {
+        const client = createMapiClient(clientId, token);
+        const data = {
+            name,
+            codename,
+            scopes,
+            steps,
+            published_step,
+            archived_step,
+        };
+        try {
+            const response = await client
+                .updateWorkflow()
+                .byWorkflowId(id)
+                .withData(data)
+                .toPromise();
+            return createMcpToolSuccessResponse(response.rawData);
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Workflow Update");
+        }
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontent-ai/mcp-server",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "type": "module",
   "mcpName": "io.github.kontent-ai/mcp-server",
   "repository": {
@@ -30,7 +30,7 @@
   "license": "MIT",
   "dependencies": {
     "@kontent-ai/management-sdk": "^8.1.0",
-    "@modelcontextprotocol/sdk": "^1.24.3",
+    "@modelcontextprotocol/sdk": "^1.25.2",
     "applicationinsights": "^2.9.8",
     "dotenv": "^17.2.3",
     "express": "^5.2.1",