@kontent-ai/mcp-server 0.17.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

@@ -4,16 +4,18 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 import "dotenv/config";
 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;
-async function startStreamableHTTP() {
+async function startStreamableHTTP(config) {
     const app = express();
     app.use(express.json());
     app.post("/mcp", async (req, res) => {
         try {
-            const { server } = createServer();
+            const { server } = createServer(config);
             const transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: undefined,
             });
@@ -27,6 +29,7 @@ async function startStreamableHTTP() {
         }
         catch (error) {
             console.error("Error handling MCP request:", error);
+            trackException(error, "MCP Request Handler");
             if (!res.headersSent) {
                 res.status(500).json({
                     jsonrpc: "2.0",
@@ -68,7 +71,7 @@ async function startStreamableHTTP() {
                 });
                 return;
             }
-            const { server } = createServer();
+            const { server } = createServer(config);
             const transport = new StreamableHTTPServerTransport({
                 sessionIdGenerator: undefined,
             });
@@ -95,6 +98,7 @@ async function startStreamableHTTP() {
         }
         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",
@@ -127,6 +131,10 @@ async function startStreamableHTTP() {
             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}.
@@ -135,13 +143,18 @@ Available endpoints:
 /{environmentId}/mcp (requires Bearer authentication)`);
     });
 }
-async function startStdio() {
-    const { server } = createServer();
+async function startStdio(config) {
+    const { server } = createServer(config);
     const transport = new StdioServerTransport();
     console.log(`Kontent.ai MCP Server v${version} (stdio) starting`);
     await server.connect(transport);
 }
 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 ||
@@ -150,13 +163,14 @@ async function main() {
         process.exit(1);
     }
     if (transportType === "stdio") {
-        await startStdio();
+        await startStdio(config);
     }
     else if (transportType === "shttp") {
-        await startStreamableHTTP();
+        await startStreamableHTTP(config);
     }
 }
 main().catch((error) => {
     console.error("Fatal error:", error);
+    trackException(error, "Server Startup");
     process.exit(1);
 });

package/build/clients/kontentClients.js

@@ -6,9 +6,18 @@ const sourceTrackingHeaderName = "X-KC-SOURCE";
  * Creates a Kontent.ai Management API client
  * @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) => {
+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 ??
@@ -16,11 +25,7 @@ export const createMapiClient = (environmentId, apiKey) => {
         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

@@ -0,0 +1,51 @@
+import { load } from "@azure/app-configuration-provider";
+import { DefaultAzureCredential } from "@azure/identity";
+function loadIndexedEnvVars(prefix) {
+    const values = [];
+    let index = 0;
+    while (true) {
+        const envVar = process.env[`${prefix}__${index}`];
+        if (!envVar)
+            break;
+        const trimmed = envVar.trim();
+        if (trimmed) {
+            values.push(trimmed);
+        }
+        index++;
+    }
+    return values;
+}
+function getConfigValue(configMap, key) {
+    const value = configMap.get(key);
+    return value && typeof value === "string" ? value : undefined;
+}
+export async function loadAppConfiguration() {
+    try {
+        const appConfigEndpoint = process.env.ConfigStore__Endpoints__0;
+        const labels = loadIndexedEnvVars("ConfigStore__Labels");
+        if (!appConfigEndpoint || labels.length === 0) {
+            return null;
+        }
+        const selectors = labels.flatMap((label) => [
+            { keyFilter: "ApplicationInsights:*", labelFilter: label },
+            { keyFilter: "Global:Runtime:*", labelFilter: label },
+            { keyFilter: "Draft:ManageApi:*", labelFilter: label },
+        ]);
+        const credential = new DefaultAzureCredential();
+        const configMap = await load(appConfigEndpoint, credential, {
+            selectors: selectors,
+            keyVaultOptions: {
+                credential: credential,
+            },
+        });
+        return {
+            applicationInsightsConnectionString: getConfigValue(configMap, "ApplicationInsights:ConnectionString"),
+            projectLocation: getConfigValue(configMap, "Global:Runtime:ProjectLocation"),
+            manageApiUrl: getConfigValue(configMap, "Draft:ManageApi:Url"),
+        };
+    }
+    catch (error) {
+        console.log("Failed to load App Configuration:", error);
+        return null;
+    }
+}

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,11 +25,12 @@ 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";
 // Create server instance
-export const createServer = () => {
+export const createServer = (config) => {
     const server = new McpServer({
         name: "kontent-ai",
         version: packageJson.version,
@@ -41,33 +41,33 @@ export const createServer = () => {
     });
     // Register all tools
     registerGetInitialContext(server);
-    registerGetItemMapi(server);
-    registerGetItemDapi(server);
-    registerGetVariantMapi(server);
-    registerGetTypeMapi(server);
-    registerListContentTypesMapi(server);
-    registerDeleteContentTypeMapi(server);
-    registerListLanguagesMapi(server);
-    registerGetAssetMapi(server);
-    registerListAssetsMapi(server);
-    registerAddContentTypeMapi(server);
-    registerPatchContentTypeMapi(server);
-    registerAddContentTypeSnippetMapi(server);
-    registerGetTypeSnippetMapi(server);
-    registerListContentTypeSnippetsMapi(server);
-    registerAddTaxonomyGroupMapi(server);
-    registerListTaxonomyGroupsMapi(server);
-    registerGetTaxonomyGroupMapi(server);
-    registerAddContentItemMapi(server);
-    registerUpdateContentItemMapi(server);
-    registerDeleteContentItemMapi(server);
-    registerUpsertLanguageVariantMapi(server);
-    registerCreateVariantVersionMapi(server);
-    registerDeleteLanguageVariantMapi(server);
-    registerListWorkflowsMapi(server);
-    registerChangeVariantWorkflowStepMapi(server);
-    registerFilterVariantsMapi(server);
-    registerPublishVariantMapi(server);
-    registerUnpublishVariantMapi(server);
+    registerGetItemMapi(server, config);
+    registerGetVariantMapi(server, config);
+    registerGetTypeMapi(server, config);
+    registerListContentTypesMapi(server, config);
+    registerDeleteContentTypeMapi(server, config);
+    registerListLanguagesMapi(server, config);
+    registerGetAssetMapi(server, config);
+    registerListAssetsMapi(server, config);
+    registerAddContentTypeMapi(server, config);
+    registerPatchContentTypeMapi(server, config);
+    registerAddContentTypeSnippetMapi(server, config);
+    registerGetTypeSnippetMapi(server, config);
+    registerListContentTypeSnippetsMapi(server, config);
+    registerAddTaxonomyGroupMapi(server, config);
+    registerListTaxonomyGroupsMapi(server, config);
+    registerGetTaxonomyGroupMapi(server, config);
+    registerAddContentItemMapi(server, config);
+    registerUpdateContentItemMapi(server, config);
+    registerDeleteContentItemMapi(server, config);
+    registerUpsertLanguageVariantMapi(server, config);
+    registerCreateVariantVersionMapi(server, config);
+    registerDeleteLanguageVariantMapi(server, 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-content-item-mapi.js

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
-export const registerTool = (server) => {
+export const registerTool = (server, config) => {
     server.tool("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.", {
         name: z
             .string()
@@ -33,7 +33,7 @@ export const registerTool = (server) => {
             .optional()
             .describe("Reference to a collection by id, codename, or external_id (optional)"),
     }, async ({ name, type, codename, external_id, collection }, { authInfo: { token, clientId } = {} }) => {
-        const client = createMapiClient(clientId, token);
+        const client = createMapiClient(clientId, token, config);
         try {
             const response = await client
                 .addContentItem()

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

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { contentGroupSchema, elementSchema, } from "../schemas/contentTypeSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
-export const registerTool = (server) => {
+export const registerTool = (server, config) => {
     server.tool("add-content-type-mapi", "Add new Kontent.ai content type via Management API", {
         name: z.string().describe("Display name of the content type"),
         codename: z
@@ -22,7 +22,7 @@ export const registerTool = (server) => {
             .optional()
             .describe("Array of content groups (optional)"),
     }, async ({ name, codename, external_id, elements, content_groups }, { authInfo: { token, clientId } = {} }) => {
-        const client = createMapiClient(clientId, token);
+        const client = createMapiClient(clientId, token, config);
         try {
             const response = await client
                 .addContentType()

package/build/tools/add-content-type-snippet-mapi.js

@@ -3,7 +3,7 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { snippetElementSchema } from "../schemas/contentTypeSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
-export const registerTool = (server) => {
+export const registerTool = (server, config) => {
     server.tool("add-content-type-snippet-mapi", "Add new Kontent.ai content type snippet via Management API", {
         name: z.string().describe("Display name of the content type snippet"),
         codename: z
@@ -18,7 +18,7 @@ export const registerTool = (server) => {
             .array(snippetElementSchema)
             .describe("Array of elements that define the structure of the content type snippet"),
     }, async ({ name, codename, external_id, elements }, { authInfo: { token, clientId } = {} }) => {
-        const client = createMapiClient(clientId, token);
+        const client = createMapiClient(clientId, token, config);
         try {
             const response = await client
                 .addContentTypeSnippet()

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

@@ -2,15 +2,15 @@ import { createMapiClient } from "../clients/kontentClients.js";
 import { taxonomyGroupSchemas } from "../schemas/taxonomySchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
-export const registerTool = (server) => {
+export const registerTool = (server, config) => {
     server.tool("add-taxonomy-group-mapi", "Add new Kontent.ai taxonomy group via Management API", taxonomyGroupSchemas, async (taxonomyGroup, { authInfo: { token, clientId } = {} }) => {
-        const client = createMapiClient(clientId, token);
+        const client = createMapiClient(clientId, token, config);
         try {
             const response = await client
                 .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

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
-export const registerTool = (server) => {
+export const registerTool = (server, config) => {
     server.tool("change-variant-workflow-step-mapi", "Change the workflow step of a language variant in Kontent.ai. This operation moves a language variant to a different step in the workflow, enabling content lifecycle management such as moving content from draft to review, review to published, etc.", {
         itemId: z
             .string()
@@ -21,7 +21,7 @@ export const registerTool = (server) => {
             .uuid()
             .describe("Internal ID (UUID) of the target workflow step. This must be a valid step ID from the specified workflow. Common steps include Draft, Review, Published, and Archived, but the actual IDs depend on your specific workflow configuration"),
     }, async ({ itemId, languageId, workflowId, workflowStepId }, { authInfo: { token, clientId } = {} }) => {
-        const client = createMapiClient(clientId, token);
+        const client = createMapiClient(clientId, token, config);
         try {
             const response = await client
                 .changeWorkflowOfLanguageVariant()
@@ -38,7 +38,7 @@ export const registerTool = (server) => {
                 .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

@@ -2,7 +2,7 @@ import { z } from "zod";
 import { createMapiClient } from "../clients/kontentClients.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
-export const registerTool = (server) => {
+export const registerTool = (server, config) => {
     server.tool("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.", {
         itemId: z
             .string()
@@ -13,7 +13,7 @@ export const registerTool = (server) => {
             .uuid()
             .describe("Internal ID (UUID) of the language variant to create a new version of. Use '00000000-0000-0000-0000-000000000000' for the default language"),
     }, async ({ itemId, languageId }, { authInfo: { token, clientId } = {} }) => {
-        const client = createMapiClient(clientId, token);
+        const client = createMapiClient(clientId, token, config);
         try {
             const response = await client
                 .createNewVersionOfLanguageVariant()
@@ -22,7 +22,7 @@ export const registerTool = (server) => {
                 .toPromise();
             return createMcpToolSuccessResponse({
                 message: `Successfully created new version of language variant '${languageId}' for content item '${itemId}'`,
-                result: response.data,
+                result: response.rawData,
             });
         }
         catch (error) {