@kontent-ai/mcp-server 0.11.0 → 0.12.0

package/README.md

@@ -58,57 +58,53 @@ npx @kontent-ai/mcp-server@latest sse
 
 ### Context and Setup
 
-* **get-initial-context** – 🚨 **MANDATORY FIRST STEP**: Provides essential context, configuration, and operational guidelines for Kontent.ai. This tool MUST be called before using any other tools to understand the platform structure, core entities, relationships, and best practices.
+* **get-initial-context** – 🚨 **MANDATORY FIRST STEP**: This tool MUST be called before using ANY other tools. It provides essential context, configuration, and operational guidelines for Kontent.ai
 
 ### Content Type Management
 
-* **get-type-mapi** – Get a specific content type by internal ID
-* **list-content-types-mapi** – List all content types in the environment
-* **add-content-type-mapi** – Create a new content type with elements
+* **get-type-mapi** – Get Kontent.ai content type by internal ID from Management API
+* **list-content-types-mapi** – Get all Kontent.ai content types from Management API
+* **add-content-type-mapi** – Add new Kontent.ai content type via Management API
 
 ### Content Type Snippet Management
 
-* **get-type-snippet-mapi** – Get a specific content type snippet by internal ID
-* **list-content-type-snippets-mapi** – List all content type snippets
-* **add-content-type-snippet-mapi** – Create a new content type snippet
+* **get-type-snippet-mapi** – Get Kontent.ai content type snippet by internal ID from Management API
+* **list-content-type-snippets-mapi** – Get all Kontent.ai content type snippets from Management API
+* **add-content-type-snippet-mapi** – Add new Kontent.ai content type snippet via Management API
 
 ### Taxonomy Management
 
-* **get-taxonomy-group-mapi** – Get a specific taxonomy group by internal ID
-* **list-taxonomy-groups-mapi** – List all taxonomy groups
-* **add-taxonomy-group-mapi** – Create a new taxonomy group with terms
+* **get-taxonomy-group-mapi** – Get Kontent.ai taxonomy group by internal ID from Management API
+* **list-taxonomy-groups-mapi** – Get all Kontent.ai taxonomy groups from Management API
+* **add-taxonomy-group-mapi** – Add new Kontent.ai taxonomy group via Management API
 
 ### Content Item Management
 
-* **get-item-mapi** – Get a specific content item by internal ID
-* **get-item-dapi** – Get a content item by codename from Delivery API
-* **get-variant-mapi** – Get a language variant of a content item by internal IDs
-* **add-content-item-mapi** – Create a new content item (structure only)
-* **update-content-item-mapi** – Update an existing content item by internal ID (name, collection)
-* **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
+* **get-item-mapi** – Get Kontent.ai item by internal ID from Management API
+* **get-item-dapi** – Get Kontent.ai item by codename from Delivery API
+* **get-variant-mapi** – Get Kontent.ai language variant of content item from Management API
+* **add-content-item-mapi** – Add new Kontent.ai content item via Management API. This creates the content item structure but does not add content to language variants. Use upsert-language-variant-mapi to add content to the item
+* **update-content-item-mapi** – Update existing Kontent.ai content item by internal ID via Management API. The content item must already exist - this tool will not create new items
+* **delete-content-item-mapi** – Delete Kontent.ai content item by internal ID from Management API
+* **upsert-language-variant-mapi** – Create or update Kontent.ai language variant of a content item via Management API. This adds actual content to the content item elements. Elements should be provided as JSON string in the format expected by the SDK
+* **delete-language-variant-mapi** – Delete Kontent.ai language variant from Management API
+* **filter-variants-mapi** – Search and filter Kontent.ai language variants of content items using Management API
 
 ### Asset Management
 
-* **get-asset-mapi** – Get a specific asset by internal ID
-* **list-assets-mapi** – List all assets in the environment
+* **get-asset-mapi** – Get a specific Kontent.ai asset by internal ID from Management API
+* **list-assets-mapi** – Get all Kontent.ai assets from Management API
 
 ### Language Management
 
-* **list-languages-mapi** – List all languages configured in the environment
+* **list-languages-mapi** – Get all Kontent.ai languages from Management API
 
 ### 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)
+* **list-workflows-mapi** – Get all Kontent.ai workflows from Management API. Workflows define the content lifecycle stages and transitions between them
+* **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
 
 ## ⚙️ Configuration
 

package/build/server.js

@@ -9,7 +9,6 @@ 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";
@@ -64,6 +63,5 @@ export const createServer = () => {
     registerFilterVariantsMapi(server);
     registerPublishVariantMapi(server);
     registerUnpublishVariantMapi(server);
-    registerGetCurrentDatetime(server);
     return { server };
 };

package/build/tools/add-content-item-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("add-content-item-mapi", "Add a new content item via Management API. This creates the content item structure but does not add content to language variants. Use upsert-language-variant-mapi to add content to the item.", {
+    server.tool("add-content-item-mapi", "Add new Kontent.ai content item via Management API. This creates the content item structure but does not add content to language variants. Use upsert-language-variant-mapi to add content to the item.", {
         name: z
             .string()
             .min(1)

package/build/tools/add-content-type-mapi.js

@@ -4,7 +4,7 @@ import { contentGroupSchema, elementSchema, } from "../schemas/contentTypeSchema
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("add-content-type-mapi", "Add a new content type via Management API", {
+    server.tool("add-content-type-mapi", "Add new Kontent.ai content type via Management API", {
         name: z.string().describe("Display name of the content type"),
         codename: z
             .string()

package/build/tools/add-content-type-snippet-mapi.js

@@ -4,7 +4,7 @@ import { snippetElementSchema } from "../schemas/contentTypeSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("add-content-type-snippet-mapi", "Add a new content type snippet via Management API", {
+    server.tool("add-content-type-snippet-mapi", "Add new Kontent.ai content type snippet via Management API", {
         name: z.string().describe("Display name of the content type snippet"),
         codename: z
             .string()

package/build/tools/add-taxonomy-group-mapi.js

@@ -3,7 +3,7 @@ import { taxonomyGroupSchemas } from "../schemas/taxonomySchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("add-taxonomy-group-mapi", "Add a new taxonomy group via Management API", taxonomyGroupSchemas, async (taxonomyGroup) => {
+    server.tool("add-taxonomy-group-mapi", "Add new Kontent.ai taxonomy group via Management API", taxonomyGroupSchemas, async (taxonomyGroup) => {
         const client = createMapiClient();
         try {
             const response = await client

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

@@ -98,9 +98,6 @@ 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
 
@@ -116,6 +113,8 @@ ALL FOUR elements must be included in language variant using their internal IDs:
 
 ## Best Practices
 
+**CRITICAL**: Never assume the current time. Always obtain the current date and time when needed for time-sensitive operations like scheduling. If the current date and time in UTC format cannot be decisively obtained by any available tool, force the user to specify the current date and time explicitly.
+
 Use snippets for common field groups to maintain consistency and avoid duplication. Plan your content types before creating content to ensure proper structure. **Always use internal IDs when working with MCP tools** for optimal performance and reliability. Leverage taxonomies for organization to create logical content hierarchies. Consider your multilingual strategy early in the planning process to avoid restructuring later.
 
 When working with snippets, always retrieve and understand the complete element structure before creating content variants.

package/build/tools/delete-content-item-mapi.js

@@ -3,7 +3,7 @@ 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-content-item-mapi", "Delete a content item by internal ID from Management API", {
+    server.tool("delete-content-item-mapi", "Delete Kontent.ai content item by internal ID from Management API", {
         id: z.string().describe("Internal ID of the content item to delete"),
     }, async ({ id }) => {
         const client = createMapiClient();

package/build/tools/delete-language-variant-mapi.js

@@ -3,7 +3,7 @@ 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-language-variant-mapi", "Delete a language variant of a content item from Management API", {
+    server.tool("delete-language-variant-mapi", "Delete Kontent.ai language variant from Management API", {
         itemId: z.string().describe("Internal ID of the content item"),
         languageId: z
             .string()

package/build/tools/filter-variants-mapi.js

@@ -3,7 +3,7 @@ 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, }) => {
+    server.tool("filter-variants-mapi", "Search and filter Kontent.ai language variants of content items using 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: {

package/build/tools/get-asset-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-asset-mapi", "Get a specific asset by internal ID from Management API", {
+    server.tool("get-asset-mapi", "Get a specific Kontent.ai asset by internal ID from Management API", {
         assetId: z.string().describe("Internal ID of the asset to retrieve"),
     }, async ({ assetId }) => {
         const client = createMapiClient();

package/build/tools/get-taxonomy-group-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-taxonomy-group-mapi", "Get taxonomy group by internal ID from Management API", {
+    server.tool("get-taxonomy-group-mapi", "Get Kontent.ai taxonomy group by internal ID from Management API", {
         id: z.string().describe("Internal ID of the taxonomy group to get"),
     }, async ({ id }) => {
         const client = createMapiClient();

package/build/tools/get-type-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-type-mapi", "Get content type by internal ID from Management API", {
+    server.tool("get-type-mapi", "Get Kontent.ai content type by internal ID from Management API", {
         id: z.string().describe("Internal ID of the content type to get"),
     }, async ({ id }) => {
         const client = createMapiClient();

package/build/tools/get-type-snippet-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-type-snippet-mapi", "Get content type snippet by internal ID from Management API", {
+    server.tool("get-type-snippet-mapi", "Get Kontent.ai content type snippet by internal ID from Management API", {
         id: z.string().describe("Internal ID of the content type snippet to get"),
     }, async ({ id }) => {
         const client = createMapiClient();

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

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("get-variant-mapi", "Get language variant of a content item from Management API", {
+    server.tool("get-variant-mapi", "Get Kontent.ai language variant of content item from Management API", {
         itemId: z.string().describe("Internal ID of the content item"),
         languageId: z
             .string()

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

@@ -2,7 +2,7 @@ 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-assets-mapi", "Get all assets from Management API", {}, async () => {
+    server.tool("list-assets-mapi", "Get all Kontent.ai assets from Management API", {}, async () => {
         const client = createMapiClient();
         try {
             const response = await client.listAssets().toAllPromise();

package/build/tools/list-content-type-snippets-mapi.js

@@ -2,7 +2,7 @@ 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-content-type-snippets-mapi", "Get all content type snippets from Management API", {}, async () => {
+    server.tool("list-content-type-snippets-mapi", "Get all Kontent.ai content type snippets from Management API", {}, async () => {
         const client = createMapiClient();
         try {
             const response = await client.listContentTypeSnippets().toAllPromise();

package/build/tools/list-content-types-mapi.js

@@ -2,7 +2,7 @@ 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-content-types-mapi", "Get all content types from Management API", {}, async () => {
+    server.tool("list-content-types-mapi", "Get all Kontent.ai content types from Management API", {}, async () => {
         const client = createMapiClient();
         try {
             const response = await client.listContentTypes().toAllPromise();

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

@@ -2,7 +2,7 @@ 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-languages-mapi", "Get all languages from Management API", {}, async () => {
+    server.tool("list-languages-mapi", "Get all Kontent.ai languages from Management API", {}, async () => {
         const client = createMapiClient();
         try {
             const response = await client.listLanguages().toAllPromise();

package/build/tools/list-taxonomy-groups-mapi.js

@@ -2,7 +2,7 @@ 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-taxonomy-groups-mapi", "Get all taxonomy groups from Management API", {}, async () => {
+    server.tool("list-taxonomy-groups-mapi", "Get all Kontent.ai taxonomy groups from Management API", {}, async () => {
         const client = createMapiClient();
         try {
             const response = await client.listTaxonomies().toAllPromise();

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

@@ -2,7 +2,7 @@ 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 () => {
+    server.tool("list-workflows-mapi", "Get all Kontent.ai 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();

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

@@ -14,7 +14,7 @@ export const registerTool = (server) => {
             .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()
+            .datetime({ offset: true })
             .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

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

@@ -14,7 +14,7 @@ export const registerTool = (server) => {
             .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()
+            .datetime({ offset: true })
             .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

package/build/tools/update-content-item-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("update-content-item-mapi", "Update an existing content item by internal ID via Management API. The content item must already exist - this tool will not create new items.", {
+    server.tool("update-content-item-mapi", "Update existing Kontent.ai content item by internal ID via Management API. The content item must already exist - this tool will not create new items.", {
         id: z.string().describe("Internal ID of the content item to update"),
         name: z
             .string()

package/build/tools/upsert-language-variant-mapi.js

@@ -4,7 +4,7 @@ import { languageVariantElementSchema } from "../schemas/contentItemSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 export const registerTool = (server) => {
-    server.tool("upsert-language-variant-mapi", "Create or update a language variant of a content item via Management API. This adds actual content to the content item elements. Elements should be provided as JSON string in the format expected by the SDK.", {
+    server.tool("upsert-language-variant-mapi", "Create or update Kontent.ai language variant of a content item via Management API. This adds actual content to the content item elements. Elements should be provided as JSON string in the format expected by the SDK.", {
         itemId: z.string().describe("Internal ID of the content item"),
         languageId: z
             .string()

package/package.json

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

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

@@ -1,9 +0,0 @@
-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(),
-        });
-    });
-};