@kontent-ai/mcp-server 0.21.0 → 0.21.2

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

@@ -149,8 +149,8 @@ All MCP tools have been optimized to work with internal IDs for maximum efficien
 
 ### 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)
+**CRITICAL DISTINCTION**:
+- **search-variants-mapi**: Finds content WHERE THE MAIN TOPIC matches a concept (e.g., "articles about wildlife")
+- **filter-variants-mapi**: Finds SPECIFIC WORDS anywhere in content, regardless of topic (e.g., brand compliance, detecting prohibited terms in any content)
 
-See each tool's description for detailed usage guidelines and selection criteria.`;
+See each tool's description for detailed usage guidelines.`;

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

@@ -7,11 +7,16 @@ export const registerTool = (server) => {
     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
+    - EXACT keyword matching: finding specific words, phrases, names, codes, or IDs anywhere in content, regardless of overall topic
+      ✓ Example: 'find items containing rabbit' → search 'rabbit'
+    - Brand guideline compliance: detecting prohibited terms across all content
+      ✓ Example: Search "hunt beast prey" to find content containing ANY of these terms (natural OR operator)
     - CAN expand concepts to keywords when using filter (e.g., "neurology-related" → "neurology neurological brain nervous system")
+    - Advanced filtering by content type, contributors, workflow steps, taxonomies etc
     - Also use as fallback when AI search is unavailable
-    - Optionally includes full content of variants with include_content parameter`, filterVariantsSchema.shape, async ({ search_phrase, content_types, contributors, has_no_contributors, completion_statuses, language, workflow_steps, taxonomy_groups, order_by, order_direction, include_content, }, { authInfo: { token, clientId } = {} }) => {
+    - Optionally includes full content of variants with include_content parameter
+
+    BEST FOR: Finding needles in haystacks - specific words in otherwise unrelated content. Multiple search terms use OR logic.`, filterVariantsSchema.shape, async ({ search_phrase, content_types, contributors, has_no_contributors, completion_statuses, language, workflow_steps, taxonomy_groups, order_by, order_direction, include_content, }, { authInfo: { token, clientId } = {} }) => {
         try {
             const environmentId = clientId ?? process.env.KONTENT_ENVIRONMENT_ID;
             if (!environmentId) {

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

@@ -4,9 +4,15 @@ import { searchOperationSchema } from "../schemas/searchOperationSchemas.js";
 import { handleMcpToolError } from "../utils/errorHandler.js";
 import { createMcpToolSuccessResponse } from "../utils/responseHelper.js";
 import { throwError } from "../utils/throwError.js";
+class OperationResultIncompleteError extends Error {
+    constructor() {
+        super("AI operation result is incomplete");
+        this.name = "OperationResultIncompleteError";
+    }
+}
 export const registerTool = (server) => {
     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
@@ -14,12 +20,24 @@ export const registerTool = (server) => {
     - 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 } = {} }) => {
+    - Finding content WHERE THE OVERALL TOPIC/THEME matches a concept
+      ✓ Example: "fairy tales" → finds articles primarily about fairy tales
+      ✓ Example: "beverage temperature control" → finds content focused on keeping drinks cold/hot
+    - Content similarity: Finding articles with similar overall themes
+    - Thematic content discovery when the main subject matter is what you're looking for
+
+    DO NOT USE FOR:
+    - Finding specific words scattered in otherwise unrelated content
+      ✗ Example: Finding "challenge" term in articles about various topics (use filter-variants-mapi)
+    - Brand guideline violations or prohibited term detection (use filter-variants-mapi)
+    - Compliance audits looking for specific keywords (use filter-variants-mapi)
+    - Finding exhaustive and exact number of results (use filter-variants-mapi)
+
+    CRITICAL: This is SEMANTIC search for topic matching. Pass natural language concepts AS-IS. DO NOT generate keyword lists or concatenate multiple keywords.
+    ✓ CORRECT: "animal predators" or "articles about temperature control"
+    ✗ WRONG: "animal beast creature wild hunt predator prey attack"`, searchOperationSchema.shape, async ({ searchPhrase, filter }, { authInfo: { token, clientId } = {} }) => {
         try {
             const environmentId = clientId ?? process.env.KONTENT_ENVIRONMENT_ID;
             if (!environmentId) {
@@ -71,11 +89,17 @@ export const registerTool = (server) => {
                         .get()
                         .withAction(`projects/${environmentId}/early-access/ai-operation-result/${operationId}`)
                         .toPromise();
-                    return pollResponse.data;
+                    const [response] = pollResponse.data;
+                    if (response.type === "cumulated-result-v1" &&
+                        !response.result?.isFinished) {
+                        throw new OperationResultIncompleteError();
+                    }
+                    return response;
                 }
                 catch (error) {
-                    if (error?.response?.status === 404) {
-                        throw new Error("Operation result not available yet. Retrying.");
+                    if (error?.response?.status === 404 ||
+                        error instanceof OperationResultIncompleteError) {
+                        throw error;
                     }
                     throw new AbortError(error);
                 }

package/package.json

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