@kontent-ai/mcp-server 0.4.2 → 0.6.0

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

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import { createMapiClient } from "../clients/kontentClients.js";
+import { createValidationErrorResponse, 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.", {
+        itemCodename: z.string().describe("Codename of the content item"),
+        languageCodename: z
+            .string()
+            .describe("Codename of the language variant (e.g., 'default', 'en-US', 'es-ES')"),
+        elements: z
+            .string()
+            .describe('JSON string representing an array of element objects. Each element should have an "element" object with "codename" property and a "value" property. Example: \'[{"element": {"codename": "title"}, "value": "My Title"}, {"element": {"codename": "content"}, "value": "<p>My content</p>"}]\''),
+        workflow_step_codename: z
+            .string()
+            .optional()
+            .describe("Codename of the workflow step (optional)"),
+    }, async ({ itemCodename, languageCodename, elements, workflow_step_codename, }) => {
+        const client = createMapiClient();
+        let parsedElements;
+        try {
+            parsedElements = JSON.parse(elements);
+        }
+        catch (error) {
+            return createValidationErrorResponse(`Invalid JSON format in elements parameter. ${error instanceof Error ? error.message : "Unknown JSON parsing error"}`, "JSON Parsing Error");
+        }
+        const data = {
+            elements: parsedElements,
+        };
+        if (workflow_step_codename) {
+            data.workflow_step = { codename: workflow_step_codename };
+        }
+        try {
+            const response = await client
+                .upsertLanguageVariant()
+                .byItemCodename(itemCodename)
+                .byLanguageCodename(languageCodename)
+                .withData(() => data)
+                .toPromise();
+            return createMcpToolSuccessResponse(response.rawData);
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Language Variant Upsert");
+        }
+    });
+};

package/build/utils/errorHandler.js

@@ -0,0 +1,87 @@
+/**
+ * Utility for handling errors in MCP tools and returning standardized error responses
+ */
+/**
+ * Handles various types of errors and returns a standardized MCP tool error response
+ * @param error The error to handle
+ * @param context Optional context string to include in error message
+ * @returns Standardized MCP tool error response
+ */
+export const handleMcpToolError = (error, context) => {
+    const contextPrefix = context ? `${context}: ` : "";
+    // Handle Kontent.ai Management API specific errors
+    if (error?.name === "ContentManagementBaseKontentError" || error?.requestId) {
+        const errorMessage = [
+            `${contextPrefix}Kontent.ai Management API Error:`,
+            `Message: ${error.message || "Unknown API error"}`,
+            error.errorCode ? `Error Code: ${error.errorCode}` : null,
+            error.requestId ? `Request ID: ${error.requestId}` : null,
+        ]
+            .filter(Boolean)
+            .join("\n");
+        // Include validation errors if available
+        if (error.validationErrors && Array.isArray(error.validationErrors)) {
+            const validationDetails = error.validationErrors
+                .map((ve) => `- ${ve.message || JSON.stringify(ve)}`)
+                .join("\n");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${errorMessage}\n\nValidation Errors:\n${validationDetails}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: errorMessage,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Handle network or other HTTP errors
+    if (error?.response) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `${contextPrefix}HTTP Error ${error.response.status}: ${error.response.statusText || "Unknown HTTP error"}\n\nResponse: ${JSON.stringify(error.response.data, null, 2)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+    // Handle generic errors
+    return {
+        content: [
+            {
+                type: "text",
+                text: `${contextPrefix}Unexpected error: ${error instanceof Error ? error.message : "Unknown error occurred"}\n\nFull error: ${JSON.stringify(error, null, 2)}`,
+            },
+        ],
+        isError: true,
+    };
+};
+/**
+ * Creates a standardized MCP tool error response for validation errors
+ * @param message The validation error message
+ * @param context Optional context string
+ * @returns Standardized MCP tool error response
+ */
+export const createValidationErrorResponse = (message, context) => {
+    const contextPrefix = context ? `${context}: ` : "";
+    return {
+        content: [
+            {
+                type: "text",
+                text: `${contextPrefix}${message}`,
+            },
+        ],
+        isError: true,
+    };
+};

package/build/utils/responseHelper.js

@@ -0,0 +1,18 @@
+/**
+ * Utility for creating standardized MCP tool success responses
+ */
+/**
+ * Creates a standardized MCP tool success response
+ * @param data The data to include in the response
+ * @returns Standardized MCP tool success response
+ */
+export const createMcpToolSuccessResponse = (data) => {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+};

package/build/utils/throwError.js

@@ -0,0 +1,3 @@
+export const throwError = (message) => {
+    throw new Error(message);
+};

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@kontent-ai/mcp-server",
-  "version": "0.4.2",
+  "version": "0.6.0",
   "type": "module",
   "scripts": {
-    "build": "tsc",
+    "build": "rimraf build && tsc",
     "start:stdio": "node build/bin.js stdio",
-    "start:sse": "node build/bin.js sse"
+    "start:sse": "node build/bin.js sse",
+    "dev:stdio": "tsx watch src/bin.ts stdio",
+    "dev:sse": "tsx watch src/bin.ts sse",
+    "format": "cross-env node node_modules/@biomejs/biome/bin/biome ci ./ --config-path=./biome.json",
+    "format:fix": "cross-env node node_modules/@biomejs/biome/bin/biome check ./ --fix --unsafe  --config-path=./biome.json"
   },
   "bin": {
     "@kontent-ai/mcp-server": "./build/bin.js"
@@ -19,14 +23,18 @@
   "dependencies": {
     "@kontent-ai/delivery-sdk": "^16.2.0",
     "@kontent-ai/management-sdk": "^7.9.0",
-    "@modelcontextprotocol/sdk": "^1.11.4",
+    "@modelcontextprotocol/sdk": "^1.12.0",
     "dotenv": "^16.5.0",
     "express": "^5.1.0",
-    "zod": "^3.25.7"
+    "zod": "^3.25.30"
   },
   "devDependencies": {
+    "@biomejs/biome": "^2.0.5",
     "@types/express": "^5.0.2",
     "@types/node": "^22.15.19",
+    "cross-env": "^7.0.3",
+    "rimraf": "^6.0.1",
+    "tsx": "^4.20.3",
     "typescript": "^5.8.3"
   }
 }