@kontent-ai/mcp-server 0.8.0 → 0.8.2

package/README.md

@@ -62,36 +62,36 @@ npx @kontent-ai/mcp-server@latest sse
 
 ### Content Type Management
 
-* **get-type-mapi** – Get a specific content type by codename
+* **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
 
 ### Content Type Snippet Management
 
-* **get-type-snippet-mapi** – Get a specific content type snippet by codename
+* **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
 
 ### Taxonomy Management
 
-* **get-taxonomy-group-mapi** – Get a specific taxonomy group by codename
+* **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
 
 ### Content Item Management
 
-* **get-item-mapi** – Get a specific content item by codename
+* **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
+* **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 codename (name, collection)
-* **delete-content-item-mapi** – Delete a content item by codename
-* **upsert-language-variant-mapi** – Create or update a language variant with content
-* **delete-language-variant-mapi** – Delete a language variant of a content item
+* **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
 
 ### Asset Management
 
-* **get-asset-mapi** – Get a specific asset by codename
+* **get-asset-mapi** – Get a specific asset by internal ID
 * **list-assets-mapi** – List all assets in the environment
 
 ### Language Management

package/build/schemas/contentItemSchemas.js

@@ -1,209 +1,76 @@
 import { z } from "zod";
-// Define a reusable reference object schema
 const referenceObjectSchema = z
     .object({
     id: z.string().optional(),
     codename: z.string().optional(),
     external_id: z.string().optional(),
 })
-    .describe("An object with an id, codename, or external_id property referencing another item. Using codename is preferred for better readability.");
-// Language variant element value schemas
-const textElementValueSchema = z.object({
-    value: z.string().describe("The text content of the element"),
+    .describe("An object with an id, codename, or external_id property referencing another item. Using id is preferred for better performance.");
+const languageVariantElementBaseSchema = z.object({
+    element: referenceObjectSchema,
+    value: z.any(),
 });
-const numberElementValueSchema = z.object({
-    value: z.number().describe("The numeric value of the element"),
+const richTextComponentSchema = z.object({
+    id: z.string(),
+    type: referenceObjectSchema,
+    elements: z.array(languageVariantElementBaseSchema),
 });
-const dateTimeElementValueSchema = z.object({
-    value: z
-        .string()
-        .nullable()
-        .describe("The ISO-8601 formatted date-time string, or null for empty"),
+const assetInVariantElementSchema = z.object({
+    element: referenceObjectSchema,
+    value: z.array(referenceObjectSchema).nullable(),
 });
-const multipleChoiceElementValueSchema = z.object({
-    value: z
-        .array(referenceObjectSchema)
-        .describe("Array of references to the selected options by their codename or id"),
+const customElementInVariantElementSchema = z.object({
+    element: referenceObjectSchema,
+    value: z.string().nullable(),
+    searchable_value: z.string().nullable(),
 });
-const assetElementValueSchema = z.object({
-    value: z
-        .array(referenceObjectSchema)
-        .describe("Array of references to assets by their codename or id"),
+const dateTimeInVariantElementSchema = z.object({
+    element: referenceObjectSchema,
+    value: z.string().nullable(),
+    display_timezone: z.string().nullable(),
 });
-const modularContentElementValueSchema = z.object({
-    value: z
-        .array(referenceObjectSchema)
-        .describe("Array of references to linked content items by their codename or id"),
+const linkedItemsInVariantElementSchema = z.object({
+    element: referenceObjectSchema,
+    value: z.array(referenceObjectSchema).nullable(),
 });
-const taxonomyElementValueSchema = z.object({
-    value: z
-        .array(referenceObjectSchema)
-        .describe("Array of references to taxonomy terms by their codename or id"),
+const multipleChoiceInVariantElementSchema = z.object({
+    element: referenceObjectSchema,
+    value: z.array(referenceObjectSchema).nullable(),
 });
-const richTextElementValueSchema = z.object({
-    value: z
-        .string()
-        .describe("The rich text content as a subset of HTML string format. Only specific HTML5 elements and attributes are supported as defined by Kontent.ai's rich text specification. See: https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#section/HTML5-elements-allowed-in-rich-text"),
+const numberInVariantElementSchema = z.object({
+    element: referenceObjectSchema,
+    value: z.number().nullable(),
 });
-const urlSlugElementValueSchema = z.object({
-    value: z.string().describe("The URL slug value"),
+const richTextInVariantElementSchema = z.object({
+    element: referenceObjectSchema,
+    value: z.string().nullable(),
+    components: z.array(richTextComponentSchema).nullable(),
 });
-const customElementValueSchema = z.object({
-    value: z.string().describe("The JSON string value for custom element"),
+const taxonomyInVariantElementSchema = z.object({
+    element: referenceObjectSchema,
+    value: z.array(referenceObjectSchema).nullable(),
 });
-// Union type for all possible element values
-const _elementValueSchema = z.discriminatedUnion("value", [
-    textElementValueSchema,
-    numberElementValueSchema,
-    dateTimeElementValueSchema,
-    multipleChoiceElementValueSchema,
-    assetElementValueSchema,
-    modularContentElementValueSchema,
-    taxonomyElementValueSchema,
-    richTextElementValueSchema,
-    urlSlugElementValueSchema,
-    customElementValueSchema,
+const textInVariantElementSchema = z.object({
+    element: referenceObjectSchema,
+    value: z.string().nullable(),
+});
+const urlSlugInVariantElementSchema = z.object({
+    element: referenceObjectSchema,
+    mode: z.enum(["autogenerated", "custom"]),
+    value: z.string().nullable(),
+});
+export const languageVariantElementSchema = z.union([
+    // Most specific schemas first (with unique distinguishing fields)
+    urlSlugInVariantElementSchema, // has unique required 'mode' field
+    richTextInVariantElementSchema, // has unique optional 'components' field
+    dateTimeInVariantElementSchema, // has unique nullable 'display_timezone' field
+    customElementInVariantElementSchema, // has unique optional 'searchable_value' field
+    numberInVariantElementSchema, // has unique value type (number)
+    // Medium specificity (array value types)
+    assetInVariantElementSchema, // value: array of references
+    linkedItemsInVariantElementSchema, // value: array of references
+    multipleChoiceInVariantElementSchema, // value: array of references
+    taxonomyInVariantElementSchema, // value: array of references
+    // Least specific (basic string value, no unique fields)
+    textInVariantElementSchema, // value: string, no distinguishing fields
 ]);
-// Language variant element schema
-const languageVariantElementSchema = z
-    .record(z.string().describe("Element codename as key"), z
-    .union([
-    textElementValueSchema,
-    numberElementValueSchema,
-    dateTimeElementValueSchema,
-    multipleChoiceElementValueSchema,
-    assetElementValueSchema,
-    modularContentElementValueSchema,
-    taxonomyElementValueSchema,
-    richTextElementValueSchema,
-    urlSlugElementValueSchema,
-    customElementValueSchema,
-])
-    .describe("Element value object with 'value' property containing the element's content"))
-    .describe("Object where keys are element codenames and values are element value objects");
-// Collection reference schema
-const collectionReferenceSchema = z
-    .object({
-    reference: referenceObjectSchema
-        .nullable()
-        .describe("Reference to a collection by id, codename, or external_id. Use null to remove from collection."),
-})
-    .describe("Collection assignment for the content item");
-// Content item creation schema
-export const contentItemCreateSchema = z
-    .object({
-    name: z
-        .string()
-        .min(1)
-        .max(200)
-        .describe("Display name of the content item (1-200 characters)"),
-    codename: z
-        .string()
-        .optional()
-        .describe("Codename of the content item (optional, will be generated from name if not provided)"),
-    type: referenceObjectSchema.describe("Reference to the content type by id, codename, or external_id"),
-    external_id: z
-        .string()
-        .optional()
-        .describe("External ID for the content item (optional, useful for external system integration)"),
-    collection: collectionReferenceSchema
-        .optional()
-        .describe("Collection assignment for the content item (optional)"),
-})
-    .describe("Schema for creating a new content item");
-// Language variant creation/update schema
-export const languageVariantUpsertSchema = z
-    .object({
-    elements: languageVariantElementSchema.describe("Object containing element values for the language variant. Keys are element codenames, values are element value objects."),
-    workflow_step: referenceObjectSchema
-        .optional()
-        .describe("Reference to workflow step by id or codename (optional)"),
-})
-    .describe("Schema for creating or updating a language variant of a content item");
-// Complete content item with language variant schema for convenience
-export const contentItemWithVariantSchema = z
-    .object({
-    item: contentItemCreateSchema.describe("Content item data"),
-    language_codename: z
-        .string()
-        .default("default")
-        .describe("Codename of the language for the variant (defaults to 'default')"),
-    variant: languageVariantUpsertSchema.describe("Language variant data with element values"),
-})
-    .describe("Schema for creating a content item along with its language variant in one operation");
-// Element value helper schemas for better LLM understanding
-export const elementValueHelpers = {
-    text: z
-        .object({
-        value: z.string().describe("Text content"),
-    })
-        .describe("Text element value - use for simple text fields like titles, descriptions, etc."),
-    richText: z
-        .object({
-        value: z
-            .string()
-            .describe("Rich text content as a subset of HTML string format. See: https://kontent.ai/learn/docs/apis/openapi/management-api-v2/#section/HTML5-elements-allowed-in-rich-text"),
-    })
-        .describe("Rich text element value - use for formatted content with HTML subset (specific HTML5 elements and attributes supported by Kontent.ai)"),
-    number: z
-        .object({
-        value: z.number().describe("Numeric value"),
-    })
-        .describe("Number element value - use for numeric fields like prices, quantities, etc."),
-    dateTime: z
-        .object({
-        value: z
-            .string()
-            .nullable()
-            .describe("ISO-8601 date-time string or null"),
-    })
-        .describe("Date-time element value - use ISO format like '2023-12-25T10:30:00.000Z' or null for empty"),
-    multipleChoice: z
-        .object({
-        value: z
-            .array(z.object({
-            codename: z.string().describe("Codename of the selected option"),
-        }))
-            .describe("Array of selected option references"),
-    })
-        .describe("Multiple choice element value - reference options by their codename"),
-    asset: z
-        .object({
-        value: z
-            .array(z.object({
-            codename: z.string().describe("Codename of the asset"),
-        }))
-            .describe("Array of asset references"),
-    })
-        .describe("Asset element value - reference assets by their codename"),
-    modularContent: z
-        .object({
-        value: z
-            .array(z.object({
-            codename: z
-                .string()
-                .describe("Codename of the linked content item"),
-        }))
-            .describe("Array of content item references"),
-    })
-        .describe("Modular content element value - reference other content items by their codename"),
-    taxonomy: z
-        .object({
-        value: z
-            .array(z.object({
-            codename: z.string().describe("Codename of the taxonomy term"),
-        }))
-            .describe("Array of taxonomy term references"),
-    })
-        .describe("Taxonomy element value - reference taxonomy terms by their codename"),
-    urlSlug: z
-        .object({
-        value: z.string().describe("URL slug value"),
-    })
-        .describe("URL slug element value - use for SEO-friendly URLs"),
-    custom: z
-        .object({
-        value: z.string().describe("JSON string value"),
-    })
-        .describe("Custom element value - depends on the custom element implementation"),
-};

package/build/schemas/contentTypeSchemas.js

@@ -5,7 +5,7 @@ const referenceObjectSchema = z
     id: z.string().optional(),
     codename: z.string().optional(),
 })
-    .describe("An object with an id or codename property referencing another item. Using codename is preferred for better readability.");
+    .describe("An object with an id or codename property referencing another item. Using id is preferred for better performance.");
 // Common property schemas
 const baseElementSchema = {
     codename: z.string().optional(),

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

@@ -0,0 +1,125 @@
+export const initialContext = `
+# Kontent.ai Platform Guide
+
+Kontent.ai is a headless content management system (CMS) that provides two main APIs: the Management API for creating, updating, and deleting content and structure, and the Delivery API for retrieving content for applications.
+
+## Core Entities
+
+### Content Items
+Content items are language-neutral content containers that serve as the foundation for your content structure. Each content item has a unique internal ID and codename, and references a specific content type. The key relationship to understand is that one content item can have multiple language variants.
+
+### Language Variants
+Language variants contain the actual language-specific content data including field values, workflow state, and language reference. Importantly, each variant is managed independently per language.
+
+### Content Types
+Content types define the structure and blueprint for language variants. They specify field definitions, validation rules, and element types that language variants will use. Think of them as templates that determine what fields and data types your language variants will have.
+
+### Content Type Snippets
+Content type snippets are reusable field groups that promote consistency across multiple content types. Following the DRY principle (define once, use everywhere), one snippet can be used across multiple content types. This prevents duplication and ensures consistency when you need the same fields across different content types.
+
+## Understanding Key Relationships
+
+The content structure flows from Content Type → Content Item → Language Variant(s). For reusability, Content Type Snippets can be included in multiple Content Types. For localization, each Content Item can have one Language Variant per language.
+
+## Working with Content Types Containing Snippets
+
+**CRITICAL**: When creating language variants for content types with snippets, you must:
+
+1. **Read the content type** to identify snippet elements (type: "snippet")
+2. **Retrieve each snippet definition** to understand its internal elements
+3. **Include ALL elements** from both the content type AND all snippets in the language variant
+
+**SNIPPET ELEMENT IMPLEMENTATION DETAILS**:
+
+When implementing snippet elements in language variants, follow these rules:
+- **Element Reference Format**: Use {"element": {"id": "internal_id_here"}} format with internal IDs
+- **Codename Convention**: Snippet elements use double underscore format: {snippet_codename}__{element_codename}
+- **Example**: For a "metadata" snippet with a "title" element, the codename becomes metadata__title
+
+**CRITICAL**: Always use internal IDs from snippet definitions, never construct codenames manually.
+
+**Complete Example**:
+Content type has: title, body (direct) + metadata snippet (meta_title, meta_description)
+ALL FOUR elements must be included in language variant using their internal IDs:
+- Direct element: title ("title_internal_id_here")
+- Direct element: body ("body_internal_id_here")  
+- Snippet element: metadata title ("metadata_title_internal_id_here")
+- Snippet element: metadata description ("metadata_description_internal_id_here")
+
+**Failure to include snippet elements or using incorrect references will result in incomplete content creation.**
+
+## Working with Content Types Containing Taxonomy Groups
+
+**CRITICAL**: When creating language variants for content types with taxonomy elements, you must:
+
+1. **Read the content type** to identify ALL taxonomy elements (type: "taxonomy")
+2. **Retrieve EACH taxonomy group definition** to understand the available terms and their hierarchical structure
+3. **Fill ALL taxonomy elements** in the language variant - DO NOT leave any taxonomy elements empty
+4. **Use appropriate term internal IDs** when filling taxonomy elements based on the content being created
+
+**MANDATORY REQUIREMENT**: Every taxonomy element in the content type MUST be filled with at least one appropriate term when creating language variants. Empty taxonomy elements are not acceptable and indicate incomplete content creation.
+
+**Example Process**: If a content type has three taxonomy elements:
+- "article_type" (required) → Must select appropriate type using its internal ID
+- "topics" (optional but must be filled) → Must select relevant topics using their internal IDs
+- "medical_specialties" (optional but must be filled) → Must select relevant specialties using their internal IDs
+
+**Failure to fill ALL taxonomy elements will result in incomplete content creation and poor content organization.**
+
+## Operational Patterns
+
+### Content Creation Workflow
+1. Define content types (structure) - Create the blueprint for your content
+2. Create content items (containers) - Establish the content containers
+3. Add language variants (actual content) - Fill in the language-specific content
+4. Publish variants (make live) - Make content available through the Delivery API
+
+### Content Management Workflow
+- Update language variants with new content or changes
+- Manage workflow states as content progresses through its lifecycle
+- Create new language variants when expanding to additional languages
+- Organize with taxonomies for better content categorization
+
+## Essential Concepts
+
+**Taxonomies** provide hierarchical content categorization, allowing you to organize and tag content systematically.
+
+**Assets** are digital files including images, videos, and documents that can be referenced throughout your content.
+
+**Workflow states** manage the content lifecycle, tracking whether content is being drafted, is live, or has been archived.
+
+**Internal IDs** are unique identifiers that provide fast and reliable access to content entities. **ALWAYS use internal IDs when working with MCP tools for better performance and reliability.**
+
+**Codenames** are human-readable unique identifiers that provide a consistent way to reference content programmatically, but should be used primarily for readability and debugging.
+
+## Best Practices
+
+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.
+
+When working with taxonomy elements, always retrieve and understand the taxonomy group structure and available terms before creating content variants. **NEVER leave taxonomy elements empty - all taxonomy elements must be properly categorized using internal IDs.**
+
+## MCP Tool Usage Guidelines
+
+**CRITICAL**: When using MCP tools, always prefer internal IDs over codenames:
+
+- **Content Items**: Use internal IDs to reference content items
+- **Language Variants**: Use internal IDs for both item and language references
+- **Content Types**: Use internal IDs to reference content types
+- **Taxonomy Terms**: Use internal IDs when referencing taxonomy terms
+- **Assets**: Use internal IDs when referencing assets
+- **Workflow Steps**: Use internal IDs for workflow step references
+
+**Why Internal IDs?** Internal IDs provide:
+- Better performance (faster lookups)
+- Immutability (won't change if names change)
+- Reliability (consistent across environments)
+- API efficiency (direct database lookups)
+
+**When to use codenames?** Codenames are useful for:
+- Human readability during development
+- Debugging and logging
+- Initial content setup when IDs are not yet known
+
+All MCP tools have been optimized to work with internal IDs for maximum efficiency.`;

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

@@ -3,17 +3,17 @@ 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 codename from Management API", {
-        codename: z.string().describe("Codename of the content item to delete"),
-    }, async ({ codename }) => {
+    server.tool("delete-content-item-mapi", "Delete a 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();
         try {
             const response = await client
                 .deleteContentItem()
-                .byItemCodename(codename)
+                .byItemId(id)
                 .toPromise();
             return createMcpToolSuccessResponse({
-                message: `Content item '${codename}' deleted successfully`,
+                message: `Content item '${id}' deleted successfully`,
                 deletedItem: response.data,
             });
         }

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

@@ -4,20 +4,20 @@ 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", {
-        itemCodename: z.string().describe("Codename of the content item"),
-        languageCodename: z
+        itemId: z.string().describe("Internal ID of the content item"),
+        languageId: z
             .string()
-            .describe("Codename of the language variant to delete"),
-    }, async ({ itemCodename, languageCodename }) => {
+            .describe("Internal ID of the language variant to delete"),
+    }, async ({ itemId, languageId }) => {
         const client = createMapiClient();
         try {
             const response = await client
                 .deleteLanguageVariant()
-                .byItemCodename(itemCodename)
-                .byLanguageCodename(languageCodename)
+                .byItemId(itemId)
+                .byLanguageId(languageId)
                 .toPromise();
             return createMcpToolSuccessResponse({
-                message: `Language variant '${languageCodename}' of content item '${itemCodename}' deleted successfully`,
+                message: `Language variant '${languageId}' of content item '${itemId}' deleted successfully`,
                 deletedVariant: response.data,
             });
         }

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

@@ -3,14 +3,14 @@ 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 codename from Management API", {
-        assetCodename: z.string().describe("Codename of the asset to retrieve"),
-    }, async ({ assetCodename }) => {
+    server.tool("get-asset-mapi", "Get a specific asset by internal ID from Management API", {
+        assetId: z.string().describe("Internal ID of the asset to retrieve"),
+    }, async ({ assetId }) => {
         const client = createMapiClient();
         try {
             const response = await client
                 .viewAsset()
-                .byAssetCodename(assetCodename)
+                .byAssetId(assetId)
                 .toPromise();
             return createMcpToolSuccessResponse(response.data);
         }

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

@@ -1,15 +1,9 @@
-import { readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+import { initialContext } from "./context/initial-context.js";
 export const registerTool = (server) => {
     server.tool("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. If you have not called this tool, do so immediately before proceeding with any other operation.", {}, async () => {
         try {
-            const markdownPath = join(__dirname, "./context/get-initial-context.md");
-            const kontentaiInstructions = await readFile(markdownPath, "utf-8");
-            return createMcpToolSuccessResponse(kontentaiInstructions);
+            return createMcpToolSuccessResponse(initialContext);
         }
         catch (error) {
             throw new Error(`Failed to read initial context: ${error instanceof Error ? error.message : "Unknown error"}`);

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

@@ -3,14 +3,14 @@ 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-item-mapi", "Get Kontent.ai item by codename from Management API", {
-        codename: z.string().describe("Codename of the item to get"),
-    }, async ({ codename }) => {
+    server.tool("get-item-mapi", "Get Kontent.ai item by internal ID from Management API", {
+        id: z.string().describe("Internal ID of the item to get"),
+    }, async ({ id }) => {
         const client = createMapiClient();
         try {
             const response = await client
                 .viewContentItem()
-                .byItemCodename(codename)
+                .byItemId(id)
                 .toPromise();
             return createMcpToolSuccessResponse(response.data);
         }

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

@@ -3,14 +3,14 @@ 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 codename from Management API", {
-        codename: z.string().describe("Codename of the taxonomy group to get"),
-    }, async ({ codename }) => {
+    server.tool("get-taxonomy-group-mapi", "Get 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();
         try {
             const response = await client
                 .getTaxonomy()
-                .byTaxonomyCodename(codename)
+                .byTaxonomyId(id)
                 .toPromise();
             return createMcpToolSuccessResponse(response.data);
         }

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

@@ -3,14 +3,14 @@ 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 codename from Management API", {
-        codename: z.string().describe("Codename of the content type to get"),
-    }, async ({ codename }) => {
+    server.tool("get-type-mapi", "Get 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();
         try {
             const response = await client
                 .viewContentType()
-                .byTypeCodename(codename)
+                .byTypeId(id)
                 .toPromise();
             return createMcpToolSuccessResponse(response.data);
         }

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

@@ -3,16 +3,14 @@ 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 codename from Management API", {
-        codename: z
-            .string()
-            .describe("Codename of the content type snippet to get"),
-    }, async ({ codename }) => {
+    server.tool("get-type-snippet-mapi", "Get 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();
         try {
             const response = await client
                 .viewContentTypeSnippet()
-                .byTypeCodename(codename)
+                .byTypeId(id)
                 .toPromise();
             return createMcpToolSuccessResponse(response.data);
         }

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

@@ -4,17 +4,17 @@ 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", {
-        itemCodename: z.string().describe("Codename of the content item"),
-        languageCodename: z
+        itemId: z.string().describe("Internal ID of the content item"),
+        languageId: z
             .string()
-            .describe("Codename of the language variant to get"),
-    }, async ({ itemCodename, languageCodename }) => {
+            .describe("Internal ID of the language variant to get"),
+    }, async ({ itemId, languageId }) => {
         const client = createMapiClient();
         try {
             const response = await client
                 .viewLanguageVariant()
-                .byItemCodename(itemCodename)
-                .byLanguageCodename(languageCodename)
+                .byItemId(itemId)
+                .byLanguageId(languageId)
                 .toPromise();
             return createMcpToolSuccessResponse(response.data);
         }

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

@@ -3,8 +3,8 @@ 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 codename via Management API. The content item must already exist - this tool will not create new items.", {
-        codename: z.string().describe("Codename of the content item to update"),
+    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.", {
+        id: z.string().describe("Internal ID of the content item to update"),
         name: z
             .string()
             .min(1)
@@ -19,11 +19,11 @@ export const registerTool = (server) => {
         })
             .optional()
             .describe("Reference to a collection by id, codename, or external_id (optional)"),
-    }, async ({ codename, name, collection }) => {
+    }, async ({ id, name, collection }) => {
         const client = createMapiClient();
         try {
             // First, verify the item exists by trying to get it
-            await client.viewContentItem().byItemCodename(codename).toPromise();
+            await client.viewContentItem().byItemId(id).toPromise();
             // If we get here, the item exists, so we can update it
             const updateData = {};
             if (name !== undefined) {
@@ -46,11 +46,11 @@ export const registerTool = (server) => {
             }
             const response = await client
                 .upsertContentItem()
-                .byItemCodename(codename)
+                .byItemId(id)
                 .withData(updateData)
                 .toPromise();
             return createMcpToolSuccessResponse({
-                message: `Content item '${codename}' updated successfully`,
+                message: `Content item '${id}' updated successfully`,
                 updatedItem: response.rawData,
             });
         }
@@ -62,7 +62,7 @@ export const registerTool = (server) => {
                     content: [
                         {
                             type: "text",
-                            text: `Update Content Item: Content item with codename '${codename}' does not exist. Use add-content-item-mapi to create new items.`,
+                            text: `Update Content Item: Content item with ID '${id}' does not exist. Use add-content-item-mapi to create new items.`,
                         },
                     ],
                     isError: true,

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

@@ -1,40 +1,32 @@
 import { z } from "zod";
 import { createMapiClient } from "../clients/kontentClients.js";
-import { createValidationErrorResponse, handleMcpToolError, } from "../utils/errorHandler.js";
+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.", {
-        itemCodename: z.string().describe("Codename of the content item"),
-        languageCodename: z
+        itemId: z.string().describe("Internal ID of the content item"),
+        languageId: 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
+            .describe("Internal ID of the language variant (e.g., '00000000-0000-0000-0000-000000000000' for default language)"),
+        elements: z.array(languageVariantElementSchema),
+        workflow_step_id: z
             .string()
             .optional()
-            .describe("Codename of the workflow step (optional)"),
-    }, async ({ itemCodename, languageCodename, elements, workflow_step_codename, }) => {
+            .describe("Internal ID of the workflow step (optional)"),
+    }, async ({ itemId, languageId, elements, workflow_step_id }) => {
         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,
+            elements,
         };
-        if (workflow_step_codename) {
-            data.workflow_step = { codename: workflow_step_codename };
+        if (workflow_step_id) {
+            data.workflow_step = { id: workflow_step_id };
         }
         try {
             const response = await client
                 .upsertLanguageVariant()
-                .byItemCodename(itemCodename)
-                .byLanguageCodename(languageCodename)
+                .byItemId(itemId)
+                .byLanguageId(languageId)
                 .withData(() => data)
                 .toPromise();
             return createMcpToolSuccessResponse(response.rawData);

package/package.json

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