@kontent-ai/mcp-server 0.28.1 → 0.30.0

package/README.md

@@ -98,10 +98,11 @@ npx @kontent-ai/mcp-server@latest shttp
 * **list-variants-type-mapi** – List Kontent.ai language variants by content type from Management API (paginated)
 * **list-variants-components-type-mapi** – List Kontent.ai language variants containing components of a specific content type from Management API (paginated)
 * **list-variants-space-mapi** – List Kontent.ai language variants by space from Management API (paginated)
-* **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
+* **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 create-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. Element values must fulfill limitations and guidelines defined in content type. When updating, only provided elements will be modified
+* **create-language-variant-mapi** – Create Kontent.ai variant assigning current user as contributor. Element values must fulfill limitations and guidelines defined in content type
+* **update-language-variant-mapi** – Update Kontent.ai language variant of a content item via Management API. Element values must fulfill limitations and guidelines defined in content type. Only provided elements will be modified
 * **create-variant-version-mapi** – Create new version of Kontent.ai language variant via Management API. This operation creates a new version of an existing language variant, useful for content versioning and creating new drafts from published content
 * **delete-language-variant-mapi** – Delete Kontent.ai language variant from Management API
 * **filter-variants-mapi** – Filter Kontent.ai items with variants returning references (item ID + language ID). Use for exact keyword matching and finding specific terms in content. Supports full filtering capabilities (content types, workflow steps, taxonomies, spaces, collections, publishing states, etc.). Returns paginated results with continuation token for fetching subsequent pages. Use bulk-get-items-variants-mapi to retrieve full content for matched items
@@ -153,28 +154,39 @@ npx @kontent-ai/mcp-server@latest shttp
 
 ## ⚙️ Configuration
 
-The server supports two configuration modes:
+The server supports two modes, each tied to its transport:
 
-### Single-Tenant Mode (Default)
+| Transport | Mode | Authentication | Use Case |
+|-----------|------|----------------|----------|
+| **STDIO** | Single-tenant | Environment variables | Local communication with a single Kontent.ai environment |
+| **Streamable HTTP** | Multi-tenant | Bearer token per request | Remote/shared server handling multiple environments |
 
-For single-tenant mode, configure environment variables:
+### Single-Tenant Mode (STDIO)
+
+Configure credentials via environment variables:
 
 | Variable | Description | Required |
 |----------|-------------|----------|
 | KONTENT_API_KEY | Your Kontent.ai Management API key | ✅ |
 | KONTENT_ENVIRONMENT_ID | Your environment ID | ✅ |
-| PORT | Port for HTTP transport (defaults to 3001) | ❌ |
 | appInsightsConnectionString | Application Insights connection string for telemetry | ❌ |
 | projectLocation | Project location identifier for telemetry tracking | ❌ |
 | manageApiUrl | Custom Management API base URL (for preview environments) | ❌ |
 
-### Multi-Tenant Mode
+### Multi-Tenant Mode (Streamable HTTP)
 
-For multi-tenant mode (Streamable HTTP only), the server accepts:
+For the Streamable HTTP transport, credentials are provided per request:
 - **Environment ID** as a URL path parameter: `/{environmentId}/mcp`
 - **API Key** via Bearer token in the Authorization header: `Authorization: Bearer <api-key>`
 
-This mode allows a single server instance to handle requests for multiple Kontent.ai environments securely without requiring environment variables.
+This allows a single server instance to handle requests for multiple Kontent.ai environments without requiring credential environment variables.
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| PORT | Port for HTTP transport (defaults to 3001) | ❌ |
+| appInsightsConnectionString | Application Insights connection string for telemetry | ❌ |
+| projectLocation | Project location identifier for telemetry tracking | ❌ |
+| manageApiUrl | Custom Management API base URL (for preview environments) | ❌ |
 
 ## 🚀 Transport Options
 
@@ -195,36 +207,16 @@ To run the server with STDIO transport, configure your MCP client with:
 }
 ```
 
-### 🌊 Streamable HTTP Transport
+### 🌊 Streamable HTTP Transport (Multi-Tenant)
 
-For Streamable HTTP transport, first start the server:
+Streamable HTTP transport serves multiple Kontent.ai environments from a single server instance. Each request provides credentials via URL path parameters and Bearer authentication.
+
+First start the server:
 
 ```bash
 npx @kontent-ai/mcp-server@latest shttp
 ```
 
-#### Single-Tenant Mode
-
-With environment variables in a `.env` file, or otherwise accessible to the process:
-```env
-KONTENT_API_KEY=<management-api-key>
-KONTENT_ENVIRONMENT_ID=<environment-id>
-PORT=3001  # optional, defaults to 3001
-```
-
-Then configure your MCP client:
-```json
-{
-  "kontent-ai-http": {
-    "url": "http://localhost:3001/mcp"
-  }
-}
-```
-
-#### Multi-Tenant Mode
-
-No environment variables required. The server accepts requests for multiple environments using URL path parameters and Bearer authentication.
-
 <details>
 <summary><strong>VS Code</strong></summary>
 

package/build/bin.js

@@ -12,55 +12,6 @@ const version = packageJson.version;
 async function startStreamableHTTP() {
     const app = express();
     app.use(express.json());
-    app.post("/mcp", async (req, res) => {
-        try {
-            const { server } = createServer();
-            const transport = new StreamableHTTPServerTransport({
-                sessionIdGenerator: undefined,
-            });
-            res.on("close", () => {
-                console.log("Request closed");
-                transport.close();
-                server.close();
-            });
-            await server.connect(transport);
-            await transport.handleRequest(req, res, req.body);
-        }
-        catch (error) {
-            console.error("Error handling MCP request:", error);
-            trackException(error, "MCP Request Handler");
-            if (!res.headersSent) {
-                res.status(500).json({
-                    jsonrpc: "2.0",
-                    error: {
-                        code: -32603,
-                        message: "Internal server error",
-                    },
-                    id: null,
-                });
-            }
-        }
-    });
-    app.get("/mcp", async (_, res) => {
-        res.writeHead(405).end(JSON.stringify({
-            jsonrpc: "2.0",
-            error: {
-                code: -32000,
-                message: "Method not allowed.",
-            },
-            id: null,
-        }));
-    });
-    app.delete("/mcp", async (_, res) => {
-        res.writeHead(405).end(JSON.stringify({
-            jsonrpc: "2.0",
-            error: {
-                code: -32000,
-                message: "Method not allowed.",
-            },
-            id: null,
-        }));
-    });
     app.post("/:environmentId/mcp", async (req, res) => {
         try {
             const { environmentId } = req.params;
@@ -144,8 +95,7 @@ async function startStreamableHTTP() {
     const PORT = process.env.PORT || 3001;
     app.listen(PORT, () => {
         console.log(`Kontent.ai MCP Server v${version} (Streamable HTTP) running on port ${PORT}.
-Available endpoints:
-/mcp
+Available endpoint:
 /{environmentId}/mcp (requires Bearer authentication)`);
     });
 }

package/build/server.js

@@ -9,6 +9,7 @@ import { registerTool as registerAddTaxonomyGroupMapi } from "./tools/add-taxono
 import { registerTool as registerAddWorkflowMapi } from "./tools/add-workflow-mapi.js";
 import { registerTool as registerBulkGetItemsVariantsMapi } from "./tools/bulk-get-items-variants-mapi.js";
 import { registerTool as registerChangeVariantWorkflowStepMapi } from "./tools/change-variant-workflow-step-mapi.js";
+import { registerTool as registerCreateLanguageVariantMapi } from "./tools/create-language-variant-mapi.js";
 import { registerTool as registerCreateVariantVersionMapi } from "./tools/create-variant-version-mapi.js";
 import { registerTool as registerDeleteContentItemMapi } from "./tools/delete-content-item-mapi.js";
 import { registerTool as registerDeleteContentTypeMapi } from "./tools/delete-content-type-mapi.js";
@@ -53,8 +54,8 @@ 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 registerUpdateLanguageVariantMapi } from "./tools/update-language-variant-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 = () => {
     const server = new McpServer({
@@ -104,7 +105,8 @@ export const createServer = () => {
     registerAddContentItemMapi(server);
     registerUpdateContentItemMapi(server);
     registerDeleteContentItemMapi(server);
-    registerUpsertLanguageVariantMapi(server);
+    registerCreateLanguageVariantMapi(server);
+    registerUpdateLanguageVariantMapi(server);
     registerCreateVariantVersionMapi(server);
     registerDeleteLanguageVariantMapi(server);
     registerListWorkflowsMapi(server);

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

@@ -0,0 +1,44 @@
+import { z } from "zod";
+import { createMapiClient } from "../clients/kontentClients.js";
+import { languageVariantElementSchema } from "../schemas/contentItemSchemas.js";
+import { handleMcpToolError } from "../utils/errorHandler.js";
+import { extractUserIdFromToken } from "../utils/extractUserIdFromToken.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+export const registerTool = (server) => {
+    server.tool("create-language-variant-mapi", "Create Kontent.ai variant. Element values must fulfill limitations and guidelines defined in content type.", {
+        itemId: z.string().describe("Content item ID"),
+        languageId: z
+            .string()
+            .describe("Language variant ID (default: 00000000-0000-0000-0000-000000000000)"),
+        elements: z
+            .array(languageVariantElementSchema)
+            .describe("Content elements array"),
+        workflow_step_id: z.string().optional().describe("Workflow step ID"),
+    }, async ({ itemId, languageId, elements, workflow_step_id }, { authInfo: { token, clientId } = {} }) => {
+        const client = createMapiClient(clientId, token);
+        const data = {
+            elements,
+        };
+        if (workflow_step_id) {
+            data.workflow_step = { id: workflow_step_id };
+        }
+        if (token) {
+            const userId = extractUserIdFromToken(token);
+            if (userId) {
+                data.contributors = [{ id: userId }];
+            }
+        }
+        try {
+            const response = await client
+                .upsertLanguageVariant()
+                .byItemId(itemId)
+                .byLanguageId(languageId)
+                .withData(() => data)
+                .toPromise();
+            return createMcpToolSuccessResponse(response.rawData);
+        }
+        catch (error) {
+            return handleMcpToolError(error, "Language Variant Create");
+        }
+    });
+};

package/build/tools/{upsert-language-variant-mapi.js → update-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 Kontent.ai variant. Element values must fulfill limitations and guidelines defined in content type.", {
+    server.tool("update-language-variant-mapi", "Update Kontent.ai variant. Element values must fulfill limitations and guidelines defined in content type.", {
         itemId: z.string().describe("Content item ID"),
         languageId: z
             .string()
@@ -31,7 +31,7 @@ export const registerTool = (server) => {
             return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
-            return handleMcpToolError(error, "Language Variant Upsert");
+            return handleMcpToolError(error, "Language Variant Update");
         }
     });
 };

package/build/utils/extractUserIdFromToken.js

@@ -0,0 +1,19 @@
+/**
+ * Extracts user ID from JWT token's uid claim.
+ * Decodes the JWT payload using base64url.
+ * @param token JWT token string
+ * @returns User ID string or null if decoding fails
+ */
+export const extractUserIdFromToken = (token) => {
+    try {
+        const parts = token.split(".");
+        if (parts.length !== 3) {
+            return null;
+        }
+        const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf-8"));
+        return typeof payload.uid === "string" ? payload.uid : null;
+    }
+    catch {
+        return null;
+    }
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontent-ai/mcp-server",
-  "version": "0.28.1",
+  "version": "0.30.0",
   "type": "module",
   "mcpName": "io.github.kontent-ai/mcp-server",
   "repository": {
@@ -29,8 +29,8 @@
   "author": "Jiri Lojda",
   "license": "MIT",
   "dependencies": {
-    "@kontent-ai/management-sdk": "^8.3.0",
-    "@modelcontextprotocol/sdk": "^1.25.2",
+    "@kontent-ai/management-sdk": "^8.3.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "applicationinsights": "^2.9.8",
     "dotenv": "^17.2.3",
     "express": "^5.2.1",