@kontent-ai/mcp-server 0.18.0 → 0.19.0

package/README.md

@@ -91,7 +91,8 @@ npx @kontent-ai/mcp-server@latest shttp
 * **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. When updating an existing variant, only the 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** – Search and filter Kontent.ai language variants of content items using Management API
+* **filter-variants-mapi** – Filter Kontent.ai language variants of content items using Management API. Use for exact keyword matching and finding specific terms in content. Supports full filtering capabilities (content types, workflow steps, taxonomies, etc.)
+* **search-variants-mapi** – AI-powered semantic search for finding content by meaning and concepts in a specific language variant. Use for: conceptual searches when you don't know exact keywords. Limited filtering options (variant ID only)
 
 ### Asset Management
 
@@ -345,4 +346,4 @@ MIT
 [discord-shield]: https://img.shields.io/discord/821885171984891914?color=%237289DA&label=Kontent.ai%20Discord&logo=discord&style=for-the-badge
 [discord-url]: https://discord.com/invite/SKCxwPtevJ
 [npm-url]: https://www.npmjs.com/package/@kontent-ai/mcp-server
-[npm-shield]: https://img.shields.io/npm/v/%40kontent-ai%2Fmcp-server?style=for-the-badge&logo=npm&color=%23CB0000
+[npm-shield]: https://img.shields.io/npm/v/%40kontent-ai%2Fmcp-server?style=for-the-badge&logo=npm&color=%23CB0000

package/build/bin.js

@@ -6,6 +6,7 @@ import express from "express";
 import packageJson from "../package.json" with { type: "json" };
 import { loadAppConfiguration, } from "./config/appConfiguration.js";
 import { createServer } from "./server.js";
+import { initializeApplicationInsights, trackException, trackServerStartup, } from "./telemetry/applicationInsights.js";
 import { extractBearerToken } from "./utils/extractBearerToken.js";
 import { isValidGuid } from "./utils/isValidGuid.js";
 const version = packageJson.version;
@@ -28,6 +29,7 @@ async function startStreamableHTTP(config) {
         }
         catch (error) {
             console.error("Error handling MCP request:", error);
+            trackException(error, "MCP Request Handler");
             if (!res.headersSent) {
                 res.status(500).json({
                     jsonrpc: "2.0",
@@ -96,6 +98,7 @@ async function startStreamableHTTP(config) {
         }
         catch (error) {
             console.error("Error handling MCP request:", error);
+            trackException(error, "MCP Multi-tenant Request Handler");
             if (!res.headersSent) {
                 res.status(500).json({
                     jsonrpc: "2.0",
@@ -128,6 +131,10 @@ async function startStreamableHTTP(config) {
             id: null,
         }));
     });
+    app.use((err, _req, _res, next) => {
+        trackException(err, "Express Error Handler");
+        next(err);
+    });
     const PORT = process.env.PORT || 3001;
     app.listen(PORT, () => {
         console.log(`Kontent.ai MCP Server v${version} (Streamable HTTP) running on port ${PORT}.
@@ -144,6 +151,10 @@ async function startStdio(config) {
 }
 async function main() {
     const config = await loadAppConfiguration();
+    if (config) {
+        initializeApplicationInsights(config);
+        trackServerStartup(version);
+    }
     const args = process.argv.slice(2);
     const transportType = args[0]?.toLowerCase();
     if (!transportType ||
@@ -160,5 +171,6 @@ async function main() {
 }
 main().catch((error) => {
     console.error("Fatal error:", error);
+    trackException(error, "Server Startup");
     process.exit(1);
 });

package/build/clients/kontentClients.js

@@ -7,9 +7,17 @@ const sourceTrackingHeaderName = "X-KC-SOURCE";
  * @param environmentId Optional environment ID (defaults to process.env.KONTENT_ENVIRONMENT_ID)
  * @param apiKey Optional API key (defaults to process.env.KONTENT_API_KEY)
  * @param config Optional configuration object
+ * @param additionalHeaders Optional additional headers to include in requests
  * @returns Management API client instance
  */
-export const createMapiClient = (environmentId, apiKey, config) => {
+export const createMapiClient = (environmentId, apiKey, config, additionalHeaders) => {
+    const allHeaders = [
+        {
+            header: sourceTrackingHeaderName,
+            value: `${packageJson.name};${packageJson.version}`,
+        },
+        ...(additionalHeaders || []),
+    ];
     return createManagementClient({
         apiKey: apiKey ??
             process.env.KONTENT_API_KEY ??
@@ -17,12 +25,7 @@ export const createMapiClient = (environmentId, apiKey, config) => {
         environmentId: environmentId ??
             process.env.KONTENT_ENVIRONMENT_ID ??
             throwError("KONTENT_ENVIRONMENT_ID is not set"),
-        headers: [
-            {
-                header: sourceTrackingHeaderName,
-                value: `${packageJson.name};${packageJson.version}`,
-            },
-        ],
         baseUrl: config ? `${config.manageApiUrl}v2` : undefined,
+        headers: allHeaders,
     });
 };

package/build/config/appConfiguration.js

@@ -30,7 +30,6 @@ export async function loadAppConfiguration() {
             { keyFilter: "ApplicationInsights:*", labelFilter: label },
             { keyFilter: "Global:Runtime:*", labelFilter: label },
             { keyFilter: "Draft:ManageApi:*", labelFilter: label },
-            { keyFilter: "Deliver:ApiClient:Domains:*", labelFilter: label },
         ]);
         const credential = new DefaultAzureCredential();
         const configMap = await load(appConfigEndpoint, credential, {
@@ -40,8 +39,9 @@ export async function loadAppConfiguration() {
             },
         });
         return {
+            applicationInsightsConnectionString: getConfigValue(configMap, "ApplicationInsights:ConnectionString"),
+            projectLocation: getConfigValue(configMap, "Global:Runtime:ProjectLocation"),
             manageApiUrl: getConfigValue(configMap, "Draft:ManageApi:Url"),
-            deliveryApiUrl: getConfigValue(configMap, "Deliver:ApiClient:Domains:LiveContentDomain"),
         };
     }
     catch (error) {

package/build/schemas/searchOperationSchemas.js

@@ -0,0 +1,14 @@
+import { z } from "zod";
+export const searchOperationSchema = z.object({
+    searchPhrase: z
+        .string()
+        .describe("Search phrase for AI-powered semantic search. Uses vector database to find content by meaning and similarity, not just exact keyword matching"),
+    filter: z
+        .object({
+        variantId: z
+            .string()
+            .uuid()
+            .describe("UUID of the language variant to filter by"),
+    })
+        .describe("Mandatory content item variant filter to restrict search scope. Must specify a valid variant UUID"),
+});

package/build/server.js

@@ -12,7 +12,6 @@ import { registerTool as registerDeleteLanguageVariantMapi } from "./tools/delet
 import { registerTool as registerFilterVariantsMapi } from "./tools/filter-variants-mapi.js";
 import { registerTool as registerGetAssetMapi } from "./tools/get-asset-mapi.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";
 import { registerTool as registerGetTaxonomyGroupMapi } from "./tools/get-taxonomy-group-mapi.js";
 import { registerTool as registerGetTypeMapi } from "./tools/get-type-mapi.js";
@@ -26,6 +25,7 @@ import { registerTool as registerListTaxonomyGroupsMapi } from "./tools/list-tax
 import { registerTool as registerListWorkflowsMapi } from "./tools/list-workflows-mapi.js";
 import { registerTool as registerPatchContentTypeMapi } from "./tools/patch-content-type-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";
 import { registerTool as registerUpdateContentItemMapi } from "./tools/update-content-item-mapi.js";
 import { registerTool as registerUpsertLanguageVariantMapi } from "./tools/upsert-language-variant-mapi.js";
@@ -42,7 +42,6 @@ export const createServer = (config) => {
     // Register all tools
     registerGetInitialContext(server);
     registerGetItemMapi(server, config);
-    registerGetItemDapi(server, config);
     registerGetVariantMapi(server, config);
     registerGetTypeMapi(server, config);
     registerListContentTypesMapi(server, config);
@@ -67,6 +66,7 @@ export const createServer = (config) => {
     registerListWorkflowsMapi(server, config);
     registerChangeVariantWorkflowStepMapi(server, config);
     registerFilterVariantsMapi(server, config);
+    registerSearchVariantsMapi(server, config);
     registerPublishVariantMapi(server, config);
     registerUnpublishVariantMapi(server, config);
     return { server };

package/build/telemetry/applicationInsights.js

@@ -0,0 +1,157 @@
+import { SharedModels } from "@kontent-ai/management-sdk";
+import appInsights from "applicationinsights";
+import { AxiosError } from "axios";
+import { sanitizeTelemetry, sanitizeUrl } from "./telemetrySanitizer.js";
+let isInitialized = false;
+function trackKontentApiError(error, context) {
+    const safeError = new Error(error.message);
+    safeError.stack = error.originalError.stack || safeError.stack;
+    appInsights.defaultClient.trackException({
+        exception: safeError,
+        properties: {
+            errorType: "KontentManagementApiError",
+            errorCode: error.errorCode,
+            requestId: error.requestId,
+            context: context,
+        },
+    });
+}
+function trackHttpError(error, context) {
+    let errorMessage;
+    let properties = {
+        errorType: "HttpError",
+        axiosErrorCode: error.code,
+        method: error.config?.method?.toUpperCase(),
+        url: error.config?.url ? sanitizeUrl(error.config.url) : undefined,
+        context: context,
+    };
+    if (error.response) {
+        errorMessage = `HTTP ${error.response.status} ${error.response.statusText || "Error"}`;
+        properties = {
+            ...properties,
+            scenario: "ServerResponseError",
+            status: error.response.status,
+            statusText: error.response.statusText,
+        };
+    }
+    else if (error.request) {
+        errorMessage = "Network Error - No response received";
+        properties = {
+            ...properties,
+            scenario: "NetworkError",
+            timeout: error.config?.timeout,
+        };
+    }
+    else {
+        errorMessage = `Request Setup Error: ${error.message}`;
+        properties = {
+            ...properties,
+            scenario: "RequestSetupError",
+        };
+    }
+    const safeError = new Error(errorMessage);
+    safeError.stack = error.stack || safeError.stack;
+    appInsights.defaultClient.trackException({
+        exception: safeError,
+        properties,
+    });
+}
+function trackGeneralError(error, context) {
+    const safeError = new Error(error.message);
+    safeError.stack = error.stack;
+    appInsights.defaultClient.trackException({
+        exception: safeError,
+        properties: {
+            errorType: "JavaScriptError",
+            name: error.name,
+            context: context,
+        },
+    });
+}
+function trackUnknownError(error, context) {
+    appInsights.defaultClient.trackException({
+        exception: new Error("An error occurred"),
+        properties: {
+            errorType: "UnknownError",
+            actualType: typeof error,
+            context: context,
+        },
+    });
+}
+export function trackException(error, context) {
+    try {
+        if (!isInitialized || !appInsights.defaultClient) {
+            return;
+        }
+        if (error instanceof SharedModels.ContentManagementBaseKontentError) {
+            trackKontentApiError(error, context);
+            return;
+        }
+        if (error instanceof AxiosError) {
+            trackHttpError(error, context);
+            return;
+        }
+        if (error instanceof Error) {
+            trackGeneralError(error, context);
+            return;
+        }
+        trackUnknownError(error, context);
+    }
+    catch {
+        // Silently fail - tracking should never break the application
+    }
+}
+export function trackServerStartup(version) {
+    try {
+        if (isInitialized && appInsights.defaultClient) {
+            appInsights.defaultClient.trackEvent({
+                name: "ServerStartup",
+                properties: {
+                    version: version,
+                    timestamp: new Date().toISOString(),
+                    nodeVersion: process.version,
+                },
+            });
+        }
+    }
+    catch {
+        // Silently fail - tracking should never break the application
+    }
+}
+function createTelemetryProcessor(config) {
+    return (envelope) => {
+        sanitizeTelemetry(envelope);
+        if (envelope.data?.baseData) {
+            envelope.data.baseData.properties =
+                envelope.data.baseData.properties || {};
+            envelope.data.baseData.properties["component.name"] = "mcp-server";
+            envelope.data.baseData.properties["component.location"] =
+                config.projectLocation || "unknown";
+        }
+        return true;
+    };
+}
+export function initializeApplicationInsights(config) {
+    try {
+        if (!config?.applicationInsightsConnectionString) {
+            return;
+        }
+        appInsights
+            .setup(config.applicationInsightsConnectionString)
+            .setAutoCollectExceptions(true)
+            .setAutoCollectRequests(true)
+            .setAutoCollectConsole(false)
+            .setAutoCollectDependencies(false)
+            .setAutoDependencyCorrelation(false)
+            .setAutoCollectHeartbeat(false)
+            .setAutoCollectPerformance(false)
+            .setAutoCollectIncomingRequestAzureFunctions(false)
+            .setAutoCollectPreAggregatedMetrics(false)
+            .start();
+        isInitialized = true;
+        appInsights.defaultClient.addTelemetryProcessor(createTelemetryProcessor(config));
+    }
+    catch (error) {
+        console.log("Failed to initialize Application Insights:", error);
+    }
+}

package/build/telemetry/telemetrySanitizer.js

@@ -0,0 +1,48 @@
+const SENSITIVE_KEYWORDS = [
+    "authorization",
+    "x-authorization",
+    "x-api-key",
+    "bearer",
+    "token",
+    "password",
+    "secret",
+    "key",
+    "pwd",
+    "pass",
+    "credential",
+    "x-kc-",
+    "cookie",
+];
+function isSensitive(key) {
+    const lowerKey = key.toLowerCase();
+    return SENSITIVE_KEYWORDS.some((keyword) => lowerKey.includes(keyword));
+}
+function sanitizeObject(obj) {
+    if (!obj || typeof obj !== "object")
+        return;
+    Object.keys(obj).forEach((key) => {
+        if (isSensitive(key)) {
+            delete obj[key];
+        }
+        else if (typeof obj[key] === "object") {
+            sanitizeObject(obj[key]);
+        }
+    });
+}
+export function sanitizeUrl(url) {
+    return url.split("?")[0];
+}
+export function sanitizeTelemetry(envelope) {
+    if (!envelope.data?.baseData)
+        return;
+    const data = envelope.data.baseData;
+    if (envelope.tags) {
+        sanitizeObject(envelope.tags);
+    }
+    if (data.properties) {
+        sanitizeObject(data.properties);
+    }
+    if (data.url) {
+        data.url = sanitizeUrl(data.url);
+    }
+}

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

@@ -10,7 +10,7 @@ export const registerTool = (server, config) => {
                 .addTaxonomy()
                 .withData(taxonomyGroup)
                 .toPromise();
-            return createMcpToolSuccessResponse(response.data);
+            return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Taxonomy Group Creation");

package/build/tools/change-variant-workflow-step-mapi.js

@@ -38,7 +38,7 @@ export const registerTool = (server, config) => {
                 .toPromise();
             return createMcpToolSuccessResponse({
                 message: `Successfully changed workflow step of language variant '${languageId}' for content item '${itemId}' to workflow step '${workflowStepId}'`,
-                result: response.data,
+                result: response.rawData,
             });
         }
         catch (error) {

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

@@ -123,6 +123,8 @@ When working with taxonomy elements, always retrieve and understand the taxonomy
 
 ## MCP Tool Usage Guidelines
 
+### ID Reference Preferences
+
 **CRITICAL**: When using MCP tools, always prefer internal IDs over codenames:
 
 - **Content Items**: Use internal IDs to reference content items
@@ -143,4 +145,12 @@ When working with taxonomy elements, always retrieve and understand the taxonomy
 - 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.`;
+All MCP tools have been optimized to work with internal IDs for maximum efficiency.
+
+### Content Search Tools
+
+The MCP server provides two search tools with distinct purposes:
+- **filter-variants-mapi**: Exact keyword matching with advanced filtering capabilities
+- **search-variants-mapi**: AI-powered semantic/conceptual search (when available)
+
+See each tool's description for detailed usage guidelines and selection criteria.`;

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

@@ -22,7 +22,7 @@ export const registerTool = (server, config) => {
                 .toPromise();
             return createMcpToolSuccessResponse({
                 message: `Successfully created new version of language variant '${languageId}' for content item '${itemId}'`,
-                result: response.data,
+                result: response.rawData,
             });
         }
         catch (error) {

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

@@ -14,7 +14,7 @@ export const registerTool = (server, config) => {
                 .toPromise();
             return createMcpToolSuccessResponse({
                 message: `Content item '${id}' deleted successfully`,
-                deletedItem: response.data,
+                deletedItem: response.rawData,
             });
         }
         catch (error) {

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

@@ -14,7 +14,7 @@ export const registerTool = (server, config) => {
                 .toPromise();
             return createMcpToolSuccessResponse({
                 message: `Content type '${codename}' deleted successfully`,
-                deletedType: response.data,
+                deletedType: response.rawData,
             });
         }
         catch (error) {

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

@@ -18,7 +18,7 @@ export const registerTool = (server, config) => {
                 .toPromise();
             return createMcpToolSuccessResponse({
                 message: `Language variant '${languageId}' of content item '${itemId}' deleted successfully`,
-                deletedVariant: response.data,
+                deletedVariant: response.rawData,
             });
         }
         catch (error) {

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

@@ -1,10 +1,25 @@
+import { createMapiClient } from "../clients/kontentClients.js";
 import { filterVariantsSchema } from "../schemas/filterVariantSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 import { throwError } from "../utils/throwError.js";
 export const registerTool = (server, config) => {
-    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, has_no_contributors, completion_statuses, language, workflow_steps, taxonomy_groups, order_by, order_direction, continuation_token, }, { authInfo: { token, clientId } = {} }) => {
+    server.tool("filter-variants-mapi", `Filter Kontent.ai language variants of content items using Management API.
+    
+    USE FOR:
+    - EXACT keyword matching: finding specific words, phrases, names, codes, or IDs in content. Example: 'find items containing rabbit' → search 'rabbit'
+    - Advanced filtering by content type, contributors, workflow steps, taxonomies etc
+    - CAN expand concepts to keywords when using filter (e.g., "neurology-related" → "neurology neurological brain nervous system")
+    - Also use as fallback when AI search is unavailable`, filterVariantsSchema.shape, async ({ search_phrase, content_types, contributors, has_no_contributors, completion_statuses, language, workflow_steps, taxonomy_groups, order_by, order_direction, continuation_token, }, { authInfo: { token, clientId } = {} }) => {
         try {
+            const environmentId = clientId ?? process.env.KONTENT_ENVIRONMENT_ID;
+            if (!environmentId) {
+                throwError("Missing required environment ID");
+            }
+            const additionalHeaders = continuation_token
+                ? [{ header: "X-Continuation", value: continuation_token }]
+                : undefined;
+            const client = createMapiClient(environmentId, token, config, additionalHeaders);
             const requestPayload = {
                 filters: {
                     search_phrase,
@@ -23,49 +38,12 @@ export const registerTool = (server, config) => {
                     }
                     : null,
             };
-            const environmentId = clientId ?? process.env.KONTENT_ENVIRONMENT_ID;
-            if (!environmentId) {
-                throwError("Missing required environment ID");
-            }
-            const apiKey = token ?? process.env.KONTENT_API_KEY;
-            if (!apiKey) {
-                throwError("Missing required API key");
-            }
-            const baseUrl = config
-                ? `${config.manageApiUrl}`
-                : `https://manage.kontent.ai/`;
-            const url = `${baseUrl}v2/projects/${environmentId}/early-access/variants/filter`;
-            const headers = {
-                Authorization: `Bearer ${apiKey}`,
-                "Content-Type": "application/json",
-            };
-            if (continuation_token) {
-                headers["X-Continuation"] = continuation_token;
-            }
-            const response = await fetch(url, {
-                method: "POST",
-                headers: headers,
-                body: JSON.stringify(requestPayload),
-            });
-            if (!response.ok) {
-                const responseText = await response.text();
-                let responseData;
-                try {
-                    responseData = JSON.parse(responseText);
-                }
-                catch {
-                    responseData = responseText;
-                }
-                const error = new Error(`HTTP error! status: ${response.status}`);
-                error.response = {
-                    status: response.status,
-                    statusText: response.statusText,
-                    data: responseData,
-                };
-                throw error;
-            }
-            const responseData = await response.json();
-            return createMcpToolSuccessResponse(responseData);
+            const response = await client
+                .post()
+                .withAction(`projects/${environmentId}/early-access/variants/filter`)
+                .withData(requestPayload)
+                .toPromise();
+            return createMcpToolSuccessResponse(response.data);
         }
         catch (error) {
             return handleMcpToolError(error, "Variant Search");

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

@@ -12,7 +12,7 @@ export const registerTool = (server, config) => {
                 .viewAsset()
                 .byAssetId(assetId)
                 .toPromise();
-            return createMcpToolSuccessResponse(response.data);
+            return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Asset Retrieval");

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

@@ -12,7 +12,7 @@ export const registerTool = (server, config) => {
                 .viewContentItem()
                 .byItemId(id)
                 .toPromise();
-            return createMcpToolSuccessResponse(response.data);
+            return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Item Retrieval");

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

@@ -12,7 +12,7 @@ export const registerTool = (server, config) => {
                 .getTaxonomy()
                 .byTaxonomyId(id)
                 .toPromise();
-            return createMcpToolSuccessResponse(response.data);
+            return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Taxonomy Group Retrieval");

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

@@ -12,7 +12,7 @@ export const registerTool = (server, config) => {
                 .viewContentType()
                 .byTypeId(id)
                 .toPromise();
-            return createMcpToolSuccessResponse(response.data);
+            return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Content Type Retrieval");

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

@@ -12,7 +12,7 @@ export const registerTool = (server, config) => {
                 .viewContentTypeSnippet()
                 .byTypeId(id)
                 .toPromise();
-            return createMcpToolSuccessResponse(response.data);
+            return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Content Type Snippet Retrieval");

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

@@ -16,7 +16,7 @@ export const registerTool = (server, config) => {
                 .byItemId(itemId)
                 .byLanguageId(languageId)
                 .toPromise();
-            return createMcpToolSuccessResponse(response.data);
+            return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Language Variant Retrieval");

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

@@ -6,7 +6,8 @@ export const registerTool = (server, config) => {
         const client = createMapiClient(clientId, token, config);
         try {
             const response = await client.listAssets().toAllPromise();
-            return createMcpToolSuccessResponse(response.data);
+            const rawData = response.responses.flatMap((r) => r.rawData.assets);
+            return createMcpToolSuccessResponse(rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Assets Listing");

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

@@ -6,7 +6,8 @@ export const registerTool = (server, config) => {
         const client = createMapiClient(clientId, token, config);
         try {
             const response = await client.listContentTypeSnippets().toAllPromise();
-            return createMcpToolSuccessResponse(response.data);
+            const rawData = response.responses.flatMap((r) => r.rawData.snippets);
+            return createMcpToolSuccessResponse(rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Content Type Snippets Listing");

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

@@ -6,7 +6,8 @@ export const registerTool = (server, config) => {
         const client = createMapiClient(clientId, token, config);
         try {
             const response = await client.listContentTypes().toAllPromise();
-            return createMcpToolSuccessResponse(response.data);
+            const rawData = response.responses.flatMap((r) => r.rawData.types);
+            return createMcpToolSuccessResponse(rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Content Types Listing");

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

@@ -6,7 +6,8 @@ export const registerTool = (server, config) => {
         const client = createMapiClient(clientId, token, config);
         try {
             const response = await client.listLanguages().toAllPromise();
-            return createMcpToolSuccessResponse(response.data);
+            const rawData = response.responses.flatMap((r) => r.rawData.languages);
+            return createMcpToolSuccessResponse(rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Languages Listing");

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

@@ -6,7 +6,8 @@ export const registerTool = (server, config) => {
         const client = createMapiClient(clientId, token, config);
         try {
             const response = await client.listTaxonomies().toAllPromise();
-            return createMcpToolSuccessResponse(response.data);
+            const rawData = response.responses.flatMap((r) => r.rawData.taxonomies);
+            return createMcpToolSuccessResponse(rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Taxonomy Groups Listing");

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

@@ -6,7 +6,7 @@ export const registerTool = (server, config) => {
         const client = createMapiClient(clientId, token, config);
         try {
             const response = await client.listWorkflows().toPromise();
-            return createMcpToolSuccessResponse(response.data);
+            return createMcpToolSuccessResponse(response.rawData);
         }
         catch (error) {
             return handleMcpToolError(error, "Workflows Listing");

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

@@ -0,0 +1,95 @@
+import pRetry from "p-retry";
+import { createMapiClient } from "../clients/kontentClients.js";
+import { searchOperationSchema } from "../schemas/searchOperationSchemas.js";
+import { handleMcpToolError } from "../utils/errorHandler.js";
+import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
+import { throwError } from "../utils/throwError.js";
+export const registerTool = (server, config) => {
+    server.tool("search-variants-mapi", `AI-powered semantic search for finding Kontent.ai content by meaning, concepts, themes, and content similarity in a specific language variant. This tool uses vector database and AI to enable searching by meaning and similarity rather than exact keyword matching.
+    
+    CRITICAL REQUIREMENTS:
+    - The AI search feature may not be available for all Kontent.ai environments
+    - If you receive an "unavailable" status response, DO NOT attempt to use this tool again in the same session
+    - Use filter-variants-mapi for exact text matching when semantic search is unavailable
+    - Requires language variant filter parameter (e.g., default language '00000000-0000-0000-0000-000000000000')
+    - The tool always RETURNS ONLY TOP 50 most relevant items at max
+    - Limited filtering options (only by variant ID) - use filter-variants-mapi for advanced filtering by content types, workflow steps, taxonomies, etc.
+    
+    USE FOR:
+    - Conceptual search: NEVER extract keywords, pass the single concept/theme as-is (e.g., "find content about keeping beverages cold" → searchPhrase: "beverage coolers")
+    - Finding content about topics: Use topic as-is (e.g., "find fairy tales" → searchPhrase: "fairy tales")
+    - Content similarity: Find articles similar to a given topic or story theme (e.g. "<<larger piece of content to search similar items>>" -> searchPhrase: "<<larger piece of content to search similar items>>")
+    - Thematic content discovery based on meaning and context`, searchOperationSchema.shape, async ({ searchPhrase, filter }, { authInfo: { token, clientId } = {} }) => {
+        try {
+            const environmentId = clientId ?? process.env.KONTENT_ENVIRONMENT_ID;
+            if (!environmentId) {
+                throwError("Missing required environment ID");
+            }
+            const client = createMapiClient(environmentId, token, config);
+            // Step 1: Initiate the AI search operation
+            const searchPayload = {
+                actionName: "Search",
+                type: "multiple-inputs-request-v1",
+                inputs: {
+                    searchPhrase: {
+                        type: "string",
+                        value: searchPhrase,
+                    },
+                    filter: {
+                        type: "content-item-variant-filter",
+                        value: filter,
+                    },
+                },
+                trackingData: {
+                    type: "empty-operation-tracking-data-v1",
+                },
+            };
+            let searchResponse;
+            try {
+                searchResponse = await client
+                    .post()
+                    .withAction(`projects/${environmentId}/early-access/ai-operation`)
+                    .withData(searchPayload)
+                    .toPromise();
+            }
+            catch (error) {
+                if (error?.response?.status === 403 &&
+                    error?.response?.data?.message?.includes("AI Feature Not Available")) {
+                    return createMcpToolSuccessResponse({
+                        status: "unavailable",
+                        result: `AI search feature is not available for environment ${clientId}`,
+                    });
+                }
+                throw error;
+            }
+            const operationData = searchResponse.data;
+            const operationId = operationData.operationId;
+            // Step 2: Poll for results with exponential backoff
+            const resultData = await pRetry(async () => {
+                const pollResponse = await client
+                    .get()
+                    .withAction(`projects/${environmentId}/early-access/ai-operation/${operationId}`)
+                    .toPromise();
+                const data = pollResponse.data;
+                if (data.message.includes("still in progress")) {
+                    throw new Error("Operation still in progress");
+                }
+                return data;
+            }, {
+                retries: 10,
+                minTimeout: 1000,
+                maxTimeout: 10000,
+                factor: 1.5,
+            });
+            if (resultData.message.includes("completed successfully")) {
+                return createMcpToolSuccessResponse({
+                    result: resultData.result,
+                });
+            }
+            throw new Error(`Search operation error: ${resultData.message}. Operation ID: ${operationId}`);
+        }
+        catch (error) {
+            return handleMcpToolError(error, "AI-powered Variant Search");
+        }
+    });
+};

package/build/utils/errorHandler.js

@@ -1,6 +1,7 @@
 /**
  * Utility for handling errors in MCP tools and returning standardized error responses
  */
+import { trackException } from "../telemetry/applicationInsights.js";
 /**
  * Handles various types of errors and returns a standardized MCP tool error response
  * @param error The error to handle
@@ -9,7 +10,7 @@
  */
 export const handleMcpToolError = (error, context) => {
     const contextPrefix = context ? `${context}: ` : "";
-    // Handle Kontent.ai Management API specific errors
+    trackException(error, context);
     if (error?.name === "ContentManagementBaseKontentError" || error?.requestId) {
         const errorMessage = [
             `${contextPrefix}Kontent.ai Management API Error:`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontent-ai/mcp-server",
-  "version": "0.18.0",
+  "version": "0.19.0",
   "type": "module",
   "scripts": {
     "build": "rimraf build && tsc",
@@ -24,12 +24,12 @@
     "@azure/app-configuration": "^1.9.0",
     "@azure/app-configuration-provider": "^2.2.0",
     "@azure/identity": "^4.11.1",
-    "@kontent-ai/delivery-sdk": "^16.2.0",
     "@kontent-ai/management-sdk": "^7.9.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "applicationinsights": "^2.9.8",
     "dotenv": "^16.5.0",
     "express": "^5.1.0",
+    "p-retry": "^7.0.0",
     "zod": "^3.25.30"
   },
   "devDependencies": {

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

@@ -1,26 +0,0 @@
-import { createDeliveryClient } from "@kontent-ai/delivery-sdk";
-import { z } from "zod";
-import { handleMcpToolError } from "../utils/errorHandler.js";
-import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
-export const registerTool = (server, config) => {
-    server.tool("get-item-dapi", "Get Kontent.ai item by codename from Delivery API", {
-        codename: z.string().describe("Codename of the item to get"),
-        environmentId: z
-            .string()
-            .describe("Environment ID of the item's environment"),
-    }, async ({ codename, environmentId }) => {
-        const client = createDeliveryClient({
-            environmentId,
-            proxy: {
-                baseUrl: config ? `https://${config.deliveryApiUrl}` : undefined,
-            },
-        });
-        try {
-            const response = await client.item(codename).toPromise();
-            return createMcpToolSuccessResponse(response.data.item);
-        }
-        catch (error) {
-            return handleMcpToolError(error, "Item Retrieval (Delivery API)");
-        }
-    });
-};