@kontent-ai/mcp-server 0.21.10 → 0.22.1

package/README.md

@@ -23,6 +23,7 @@ Kontent.ai MCP Server implements the Model Context Protocol to connect your Kont
 - [🔌 Quickstart](#-quickstart)
 - [🛠️ Available Tools](#️-available-tools)
 - [⚙️ Configuration](#️-configuration)
+- [🔧 Response Optimization](#-response-optimization)
 - [🚀 Transport Options](#-transport-options)
 - [💻 Development](#-development)
   - [🛠 Local Installation](#-local-installation)
@@ -88,7 +89,13 @@ npx @kontent-ai/mcp-server@latest shttp
 
 * **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
+* **get-latest-variant-mapi** – Get latest version of Kontent.ai language variant from Management API
+* **get-published-variant-mapi** – Get published version of Kontent.ai language variant from Management API
+* **list-variants-item-mapi** – List all Kontent.ai language variants of a content item from Management API
+* **list-variants-collection-mapi** – List Kontent.ai language variants by collection from Management API (paginated)
+* **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
 * **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
@@ -106,6 +113,17 @@ 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
+
+### Collection Management
+
+* **list-collections-mapi** – Get all Kontent.ai collections from Management API. Collections set boundaries for content items in your environment and help organize content by team, brand, or project
+* **patch-collections-mapi** – Update Kontent.ai collections using patch operations (addInto to add new collections, move to reorder, remove to delete empty collections, replace to rename)
+
+### Space Management
+
+* **list-spaces-mapi** – Get all Kontent.ai spaces from Management API
 
 ### Workflow Management
 
@@ -139,6 +157,34 @@ For multi-tenant mode (Streamable HTTP only), the server accepts:
 
 This mode allows a single server instance to handle requests for multiple Kontent.ai environments securely without requiring environment variables.
 
+## 🔧 Response Optimization
+
+The MCP server implements automatic token optimization to reduce AI model costs and improve performance:
+
+### Token Reduction Strategy
+
+The server automatically removes empty/default values from responses to reduce token usage. This includes:
+
+- Null and undefined values
+- Empty strings (`""`)
+- Empty arrays (`[]`)
+- Empty objects (`{}`)
+- Rich text placeholders (`"<p><br/></p>"`)
+- Elements with only an ID after empty value removal
+
+### Impact on AI Agents
+
+**Important for AI implementations**: When consuming responses from this MCP server:
+
+1. **Missing properties indicate default values**, not missing data
+2. Missing elements in variants have their type-specific defaults:
+   - Text elements: `""` (empty string)
+   - Rich text: `"<p><br/></p>"` (empty placeholder)
+   - Number/Date: `null`
+   - Custom elements: `null` (for value and searchable_value)
+   - Arrays (assets, taxonomy, etc.): `[]`
+3. When creating/updating content, always send complete data
+
 ## 🚀 Transport Options
 
 ### 📟 STDIO Transport
@@ -188,7 +234,8 @@ Then configure your MCP client:
 
 No environment variables required. The server accepts requests for multiple environments using URL path parameters and Bearer authentication.
 
-##### VS Code Configuration
+<details>
+<summary><strong>VS Code</strong></summary>
 
 Create a `.vscode/mcp.json` file in your workspace:
 
@@ -232,7 +279,10 @@ For secure configuration with input prompts:
 }
 ```
 
-##### Claude Desktop Configuration
+</details>
+
+<details>
+<summary><strong>Claude Desktop</strong></summary>
 
 Update your Claude Desktop configuration file:
 - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
@@ -257,32 +307,25 @@ Use `mcp-remote` as a proxy to add authentication headers:
 }
 ```
 
-##### Claude Code Configuration
+</details>
 
-For Claude Code (claude.ai/code), add the server configuration:
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+Add the server using the CLI:
 
 ```bash
-# Add the multi-tenant server
-claude mcp add \
-  --url "http://localhost:3001/<environment-id>/mcp" \
-  --header "Authorization: Bearer <management-api-key>" \
-  kontent-ai-multi
+claude mcp add --transport http kontent-ai-multi \
+  "http://localhost:3001/<environment-id>/mcp" \
+  --header "Authorization: Bearer <management-api-key>"
 ```
 
-Or configure directly in the settings:
+> **Note**: You can also configure this in your Claude Code settings JSON with the `url` and `headers` properties.
 
-```json
-{
-  "kontent-ai-multi": {
-    "url": "http://localhost:3001/<environment-id>/mcp",
-    "headers": {
-      "Authorization": "Bearer <management-api-key>"
-    }
-  }
-}
-```
+</details>
 
-**Important**: Replace `<environment-id>` with your actual Kontent.ai environment ID (GUID format) and `<management-api-key>` with your Management API key.
+> [!IMPORTANT]
+> Replace `<environment-id>` with your Kontent.ai environment ID (GUID) and `<management-api-key>` with your Management API key.
 
 ## 💻 Development
 

package/build/schemas/collectionSchemas.js

@@ -0,0 +1,37 @@
+import { z } from "zod";
+import { referenceObjectSchema } from "./referenceObjectSchema.js";
+const addIntoOperationSchema = z.object({
+    op: z.literal("addInto"),
+    value: z.object({
+        name: z.string(),
+        codename: z.string().optional(),
+        external_id: z.string().optional(),
+    }),
+    before: referenceObjectSchema.optional(),
+    after: referenceObjectSchema.optional(),
+});
+const moveOperationSchema = z.object({
+    op: z.literal("move"),
+    reference: referenceObjectSchema,
+    before: referenceObjectSchema.optional(),
+    after: referenceObjectSchema.optional(),
+});
+const removeOperationSchema = z.object({
+    op: z.literal("remove"),
+    reference: referenceObjectSchema,
+});
+const replaceOperationSchema = z.object({
+    op: z.literal("replace"),
+    reference: referenceObjectSchema,
+    property_name: z.enum(["name"]),
+    value: z.string(),
+});
+export const collectionPatchOperationSchema = z.discriminatedUnion("op", [
+    addIntoOperationSchema,
+    moveOperationSchema,
+    removeOperationSchema,
+    replaceOperationSchema,
+]);
+export const collectionPatchOperationsSchema = z
+    .array(collectionPatchOperationSchema)
+    .min(1);

package/build/schemas/languageSchemas.js

@@ -0,0 +1,43 @@
+import { z } from "zod";
+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)"),
+    external_id: z.string().optional().describe("External ID for the language"),
+});
+const languageReplaceOperationSchema = z.discriminatedUnion("property_name", [
+    z.object({
+        op: z.literal("replace"),
+        property_name: z.literal("codename"),
+        value: z.string(),
+    }),
+    z.object({
+        op: z.literal("replace"),
+        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"),
+        value: referenceObjectSchema,
+    }),
+]);
+export const patchLanguageSchema = z.object({
+    languageId: z.string().describe("Language ID to modify"),
+    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."),
+});

package/build/schemas/listSchemas.js

@@ -24,3 +24,19 @@ export const listContentTypeSnippetsSchema = z.object({
 export const listAssetsSchema = z.object({
     continuation_token: continuationTokenField,
 });
+export const listVariantsCollectionSchema = z.object({
+    collectionId: z.string().describe("Collection ID"),
+    continuation_token: continuationTokenField,
+});
+export const listVariantsTypeSchema = z.object({
+    contentTypeId: z.string().describe("Content type ID"),
+    continuation_token: continuationTokenField,
+});
+export const listVariantsComponentsTypeSchema = z.object({
+    contentTypeId: z.string().describe("Content type ID"),
+    continuation_token: continuationTokenField,
+});
+export const listVariantsSpaceSchema = z.object({
+    spaceId: z.string().describe("Space ID"),
+    continuation_token: continuationTokenField,
+});

package/build/schemas/taxonomySchemas.js

@@ -4,7 +4,7 @@ const taxonomyTermSchema = z.object({
     name: z.string(),
     codename: z.string().optional(),
     external_id: z.string().optional(),
-    terms: z.lazy(() => z.array(taxonomyTermSchema)),
+    terms: z.lazy(() => z.array(taxonomyTermSchema)).optional(),
 });
 // Schema for a taxonomy group
 export const taxonomyGroupSchemas = {
@@ -14,5 +14,8 @@ export const taxonomyGroupSchemas = {
         .optional()
         .describe("Codename (auto-generated if omitted)"),
     external_id: z.string().optional().describe("External ID"),
-    terms: z.array(taxonomyTermSchema).describe("Taxonomy terms hierarchy"),
+    terms: z
+        .array(taxonomyTermSchema)
+        .optional()
+        .describe("Taxonomy terms hierarchy"),
 };

package/build/server.js

@@ -3,6 +3,7 @@ import packageJson from "../package.json" with { type: "json" };
 import { registerTool as registerAddContentItemMapi } from "./tools/add-content-item-mapi.js";
 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 registerAddLanguageMapi } from "./tools/add-language-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 registerCreateVariantVersionMapi } from "./tools/create-variant-version-mapi.js";
@@ -13,17 +14,27 @@ import { registerTool as registerFilterVariantsMapi } from "./tools/filter-varia
 import { registerTool as registerGetAssetMapi } from "./tools/get-asset-mapi.js";
 import { registerTool as registerGetInitialContext } from "./tools/get-initial-context.js";
 import { registerTool as registerGetItemMapi } from "./tools/get-item-mapi.js";
+import { registerTool as registerGetLatestVariantMapi } from "./tools/get-latest-variant-mapi.js";
+import { registerTool as registerGetPublishedVariantMapi } from "./tools/get-published-variant-mapi.js";
 import { registerTool as registerGetTaxonomyGroupMapi } from "./tools/get-taxonomy-group-mapi.js";
 import { registerTool as registerGetTypeMapi } from "./tools/get-type-mapi.js";
 import { registerTool as registerGetTypeSnippetMapi } from "./tools/get-type-snippet-mapi.js";
-import { registerTool as registerGetVariantMapi } from "./tools/get-variant-mapi.js";
 import { registerTool as registerListAssetsMapi } from "./tools/list-assets-mapi.js";
+import { registerTool as registerListCollectionsMapi } from "./tools/list-collections-mapi.js";
 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 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";
+import { registerTool as registerListVariantsComponentsTypeMapi } from "./tools/list-variants-components-type-mapi.js";
+import { registerTool as registerListVariantsItemMapi } from "./tools/list-variants-item-mapi.js";
+import { registerTool as registerListVariantsSpaceMapi } from "./tools/list-variants-space-mapi.js";
+import { registerTool as registerListVariantsTypeMapi } from "./tools/list-variants-type-mapi.js";
 import { registerTool as registerListWorkflowsMapi } from "./tools/list-workflows-mapi.js";
+import { registerTool as registerPatchCollectionsMapi } from "./tools/patch-collections-mapi.js";
 import { registerTool as registerPatchContentTypeMapi } from "./tools/patch-content-type-mapi.js";
+import { registerTool as registerPatchLanguageMapi } from "./tools/patch-language-mapi.js";
 import { registerTool as registerPublishVariantMapi } from "./tools/publish-variant-mapi.js";
 import { registerTool as registerSearchVariantsMapi } from "./tools/search-variants-mapi.js";
 import { registerTool as registerUnpublishVariantMapi } from "./tools/unpublish-variant-mapi.js";
@@ -42,11 +53,22 @@ export const createServer = () => {
     // Register all tools
     registerGetInitialContext(server);
     registerGetItemMapi(server);
-    registerGetVariantMapi(server);
+    registerGetLatestVariantMapi(server);
+    registerGetPublishedVariantMapi(server);
+    registerListVariantsItemMapi(server);
+    registerListVariantsCollectionMapi(server);
+    registerListVariantsTypeMapi(server);
+    registerListVariantsComponentsTypeMapi(server);
+    registerListVariantsSpaceMapi(server);
     registerGetTypeMapi(server);
     registerListContentTypesMapi(server);
     registerDeleteContentTypeMapi(server);
     registerListLanguagesMapi(server);
+    registerAddLanguageMapi(server);
+    registerPatchLanguageMapi(server);
+    registerListCollectionsMapi(server);
+    registerPatchCollectionsMapi(server);
+    registerListSpacesMapi(server);
     registerGetAssetMapi(server);
     registerListAssetsMapi(server);
     registerAddContentTypeMapi(server);