@qikdev/mcp 6.6.3 → 6.6.5

package/build/src/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Qik Platform MCP Server - Enhanced Version
+ * Qik Platform MCP Server - Enhanced Version with Comprehensive Documentation
  *
  * This MCP server provides comprehensive integration with the Qik platform,
  * enabling AI assistants to interact with Qik's content management system,
@@ -13,12 +13,42 @@
  * - Dynamic tool schema generation
  * - Comprehensive API coverage
  * - Intelligent request building and field validation
+ * - Advanced disambiguation logic for definitions vs instances
+ * - Workflow system documentation and automation
+ * - Comprehensive scope and permission management
+ *
+ * IMPORTANT QIK CONCEPTS:
+ *
+ * 1. DEFINITIONS vs INSTANCES:
+ *    - Definitions: Templates that define structure (e.g., "workflow definition", "content type definition")
+ *    - Instances: Actual content items created from definitions (e.g., "workflow card", "article instance")
+ *    - When user says "create a workflow" they usually mean create a workflow DEFINITION
+ *    - When user says "add Jim to workflow X" they mean create a workflow CARD instance
+ *
+ * 2. WORKFLOW SYSTEM:
+ *    - Workflow Definitions: Define the structure with columns, steps, automation
+ *    - Workflow Cards: Individual items that move through the workflow
+ *    - Columns: Represent stages in the workflow (e.g., "To Do", "In Progress", "Done")
+ *    - Steps: Specific positions within columns where cards can be placed
+ *    - Automation: Entry/exit/success/fail functions that run when cards move
+ *
+ * 3. SCOPE SYSTEM:
+ *    - Hierarchical permission structure (like folders)
+ *    - Every content item must belong to at least one scope
+ *    - Users need appropriate permissions within scopes to perform actions
+ *    - Scopes can inherit permissions from parent scopes
+ *
+ * 4. CONTENT TYPE SYSTEM:
+ *    - Base types: Core Qik types (article, profile, event, etc.)
+ *    - Extended types: Custom types that extend base types with additional fields
+ *    - Fields vs DefinedFields: Fields go at root level, definedFields go in data object
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
 import axios from 'axios';
 import FormData from 'form-data';
+import { ConfigManager } from './config.js';
 // Environment variables
 const QIK_API_URL = process.env.QIK_API_URL || 'https://api.qik.dev';
 const QIK_ACCESS_TOKEN = process.env.QIK_ACCESS_TOKEN;
@@ -29,6 +59,7 @@ export class QikMCPServer {
     userSession = null;
     lastGlossaryUpdate = 0;
     GLOSSARY_CACHE_TTL = 5 * 60 * 1000; // 5 minutes
+    serverName = 'Qik'; // Default fallback
     constructor() {
         if (!QIK_ACCESS_TOKEN) {
             throw new Error('QIK_ACCESS_TOKEN environment variable is required. Run "qik-mcp-server setup" to configure.');
@@ -68,7 +99,9 @@ export class QikMCPServer {
     }
     async initializeServer() {
         try {
-            // Load user session first
+            // Load server name from config first
+            await this.loadServerName();
+            // Load user session
             await this.loadUserSession();
             // Then load glossary
             await this.loadGlossary();
@@ -78,6 +111,23 @@ export class QikMCPServer {
             this.log(`Failed to initialize server: ${this.formatError(error)}`);
         }
     }
+    async loadServerName() {
+        try {
+            const configManager = new ConfigManager();
+            const config = await configManager.loadConfig();
+            if (config && config.serverName) {
+                this.serverName = config.serverName;
+                this.log(`Loaded server name: ${this.serverName}`);
+            }
+            else {
+                this.log(`No server name found in config, using default: ${this.serverName}`);
+            }
+        }
+        catch (error) {
+            this.log(`Failed to load server name from config: ${this.formatError(error)}`);
+            // Keep default fallback value
+        }
+    }
     async loadUserSession() {
         try {
             const response = await this.axiosInstance.get('/user');
@@ -710,161 +760,541 @@ EXAMPLES:
             }
         };
     }
+    /**
+     * Enhanced intelligent content creation with advanced disambiguation logic
+     *
+     * This method provides sophisticated analysis of user intent to distinguish between:
+     * - Creating workflow DEFINITIONS vs workflow CARD instances
+     * - Creating content type DEFINITIONS vs content INSTANCES
+     * - Understanding context clues like "add person to workflow" vs "create new workflow"
+     */
     async intelligentContentCreation(description, additionalData) {
-        // First, try to find content types that match
+        // STEP 1: Advanced Intent Analysis with Disambiguation Logic
+        const intentAnalysis = this.analyzeUserIntent(description, additionalData);
+        // Handle workflow-specific disambiguation
+        if (intentAnalysis.isWorkflowRelated) {
+            return await this.handleWorkflowDisambiguation(description, additionalData, intentAnalysis);
+        }
+        // STEP 2: Standard content type matching
         const contentTypeMatches = this.findContentTypesByDescription(description);
         if (contentTypeMatches.length === 0) {
-            // If we can't find any matches, provide helpful suggestions
-            const availableTypes = Object.entries(this.glossary).map(([key, type]) => {
-                let title = 'Unknown';
-                let plural = 'Unknown';
-                if (type && typeof type === 'object') {
-                    if (type.definition) {
-                        title = type.definition.title || title;
-                        plural = type.definition.plural || plural;
-                    }
-                    else if (type.type) {
-                        title = type.type.title || title;
-                        plural = type.type.plural || plural;
-                    }
-                    else if (type.title) {
-                        title = type.title || title;
-                        plural = type.plural || plural;
-                    }
-                }
-                return { key, title, plural };
-            });
+            return await this.handleNoContentTypeMatches(description);
+        }
+        if (contentTypeMatches.length > 1) {
+            return await this.handleMultipleContentTypeMatches(description, contentTypeMatches);
+        }
+        // STEP 3: Single match found - provide comprehensive guidance
+        const contentType = contentTypeMatches[0];
+        return await this.handleSingleContentTypeMatch(contentType, description, additionalData);
+    }
+    /**
+     * Analyzes user intent to distinguish between different types of content creation
+     */
+    analyzeUserIntent(description, additionalData) {
+        const normalizedDesc = description.toLowerCase().trim();
+        const contextClues = [];
+        // Workflow-related keywords
+        const workflowKeywords = ['workflow', 'kanban', 'board', 'column', 'step', 'process', 'pipeline'];
+        const isWorkflowRelated = workflowKeywords.some(keyword => normalizedDesc.includes(keyword));
+        // Definition creation indicators
+        const definitionIndicators = [
+            'create a new', 'create new', 'make a new', 'design a', 'set up a', 'build a',
+            'define a', 'establish a', 'configure a'
+        ];
+        const isDefinitionCreation = definitionIndicators.some(indicator => normalizedDesc.includes(indicator));
+        // Instance creation indicators
+        const instanceIndicators = [
+            'add', 'assign', 'put', 'move', 'place', 'insert', 'include'
+        ];
+        const isInstanceCreation = instanceIndicators.some(indicator => normalizedDesc.includes(indicator));
+        // Person assignment indicators
+        const personIndicators = [
+            'add person', 'assign person', 'add user', 'assign user', 'add someone', 'assign someone',
+            'add jim', 'add john', 'add sarah', 'put person', 'move person'
+        ];
+        const isPersonAssignment = personIndicators.some(indicator => normalizedDesc.includes(indicator));
+        // Collect context clues
+        if (isWorkflowRelated)
+            contextClues.push('workflow-related');
+        if (isDefinitionCreation)
+            contextClues.push('definition-creation');
+        if (isInstanceCreation)
+            contextClues.push('instance-creation');
+        if (isPersonAssignment)
+            contextClues.push('person-assignment');
+        // Calculate confidence based on clarity of intent
+        let confidence = 0.5; // Base confidence
+        if (isDefinitionCreation && !isInstanceCreation)
+            confidence = 0.9;
+        if (isInstanceCreation && !isDefinitionCreation)
+            confidence = 0.9;
+        if (isPersonAssignment)
+            confidence = 0.95;
+        return {
+            isWorkflowRelated,
+            isDefinitionCreation,
+            isInstanceCreation,
+            isPersonAssignment,
+            confidence,
+            contextClues
+        };
+    }
+    /**
+     * Handles workflow-specific disambiguation with comprehensive guidance
+     */
+    async handleWorkflowDisambiguation(description, additionalData, intentAnalysis) {
+        const normalizedDesc = description.toLowerCase().trim();
+        // Check if user wants to create a workflow DEFINITION
+        if (intentAnalysis.isDefinitionCreation ||
+            normalizedDesc.includes('create a workflow') ||
+            normalizedDesc.includes('new workflow') ||
+            normalizedDesc.includes('design workflow')) {
             return {
                 content: [{
                         type: 'text',
-                        text: `I couldn't find a content type for "${description}". Here are the available content types:\n\n${availableTypes.map(t => `- ${t.key}: ${t.title} (${t.plural})`).join('\n')}\n\nPlease specify which content type you'd like to create, or I can help you create content using one of these types.`,
+                        text: `🔧 **WORKFLOW DEFINITION CREATION**
+
+You want to create a new workflow definition (template). This defines the structure, columns, steps, and automation rules.
+
+**WORKFLOW DEFINITION STRUCTURE:**
+
+A workflow definition includes:
+- **Columns**: Stages like "To Do", "In Progress", "Review", "Done"
+- **Steps**: Specific positions within columns where cards can be placed
+- **Automation**: Functions that run when cards enter/exit steps
+- **Due Date Behavior**: How due dates are calculated and managed
+- **Completion Criteria**: Rules that determine when workflow is complete
+
+**EXAMPLE WORKFLOW DEFINITION:**
+\`\`\`json
+{
+  "type": "definition",
+  "title": "New Student Induction Workflow",
+  "definesType": "workflowcard",
+  "workflow": [
+    {
+      "title": "Enrollment",
+      "description": "Initial enrollment and documentation",
+      "steps": [
+        {
+          "title": "Application Received",
+          "type": "step",
+          "description": "Student application has been received",
+          "duration": 1440,
+          "assignees": [],
+          "entryFunction": "// Code to run when card enters this step",
+          "exitFunction": "// Code to run when card exits this step"
+        }
+      ]
+    },
+    {
+      "title": "Processing",
+      "description": "Review and approval process",
+      "steps": [
+        {
+          "title": "Document Review",
+          "type": "step",
+          "description": "Review all submitted documents"
+        }
+      ]
+    }
+  ]
+}
+\`\`\`
+
+To create this workflow definition, use:
+\`qik_create_content\` with type: "definition" and the workflow structure in the data field.
+
+Would you like me to help you create a specific workflow definition?`,
                     }],
-                isError: true,
             };
         }
-        if (contentTypeMatches.length > 1) {
-            // Multiple matches found - ask for clarification
-            const matchDetails = contentTypeMatches.map(key => {
-                const type = this.glossary[key];
-                let title = 'Unknown';
-                let plural = 'Unknown';
-                if (type && typeof type === 'object') {
-                    if (type.definition) {
-                        title = type.definition.title || title;
-                        plural = type.definition.plural || plural;
-                    }
-                    else if (type.type) {
-                        title = type.type.title || title;
-                        plural = type.type.plural || plural;
-                    }
-                    else if (type.title) {
-                        title = type.title || title;
-                        plural = type.plural || plural;
-                    }
-                }
-                return { key, title, plural };
-            });
+        // Check if user wants to add someone to an existing workflow (create workflow CARD)
+        if (intentAnalysis.isPersonAssignment ||
+            normalizedDesc.includes('add') && normalizedDesc.includes('to workflow') ||
+            normalizedDesc.includes('assign') && normalizedDesc.includes('workflow')) {
             return {
                 content: [{
                         type: 'text',
-                        text: `I found multiple content types that match "${description}". Please clarify which one you'd like to create:\n\n${matchDetails.map(t => `- ${t.key}: ${t.title} (${t.plural})`).join('\n')}\n\nPlease specify the exact content type key you'd like to use.`,
+                        text: `👤 **WORKFLOW CARD CREATION (Person Assignment)**
+
+You want to add a person to an existing workflow by creating a workflow card instance.
+
+**WORKFLOW CARD vs WORKFLOW DEFINITION:**
+- **Workflow Definition**: The template/structure (columns, steps, rules)
+- **Workflow Card**: Individual items that move through the workflow
+
+**TO ADD SOMEONE TO A WORKFLOW:**
+
+1. **Find the workflow definition ID** first using:
+   \`qik_list_content\` with type: "definition" and search for your workflow name
+
+2. **Create a workflow card** using:
+   \`qik_create_content\` with type: "workflowcard"
+
+**EXAMPLE WORKFLOW CARD:**
+\`\`\`json
+{
+  "type": "workflowcard",
+  "title": "John Smith - Student Induction",
+  "reference": "PROFILE_ID_HERE",
+  "referenceType": "profile",
+  "data": {
+    "workflowDefinition": "WORKFLOW_DEFINITION_ID_HERE",
+    "currentStep": "application-received",
+    "assignedTo": ["USER_ID_HERE"],
+    "dueDate": "2024-01-15T09:00:00.000Z"
+  }
+}
+\`\`\`
+
+**NEED MORE HELP?**
+- What's the name of the workflow you want to add someone to?
+- Who do you want to add to the workflow?
+- Do you have the workflow definition ID?`,
                     }],
-                isError: true,
             };
         }
-        // Single match found
-        const contentType = contentTypeMatches[0];
+        // General workflow guidance
+        return {
+            content: [{
+                    type: 'text',
+                    text: `🔄 **WORKFLOW SYSTEM GUIDANCE**
+
+I detected you're working with workflows. Please clarify your intent:
+
+**OPTION 1: Create Workflow Definition (Template)**
+- "Create a new workflow"
+- "Design a student onboarding workflow"
+- "Set up a project management workflow"
+→ Creates the structure, columns, steps, and rules
+
+**OPTION 2: Add Person to Existing Workflow**
+- "Add Jim to the student workflow"
+- "Assign Sarah to project workflow"
+- "Put John in the onboarding process"
+→ Creates a workflow card instance for a person
+
+**WORKFLOW CONCEPTS:**
+- **Definition**: The template (like a Kanban board layout)
+- **Card**: Individual items moving through the workflow
+- **Columns**: Stages (To Do, In Progress, Done)
+- **Steps**: Specific positions within columns
+- **Automation**: Code that runs when cards move
+
+**AVAILABLE WORKFLOW CONTENT TYPES:**
+- \`definition\`: For creating workflow templates
+- \`workflowcard\`: For individual workflow instances
+- \`object\`: For custom workflow-related objects
+
+Please specify: Are you creating a new workflow template, or adding someone to an existing workflow?`,
+                }],
+        };
+    }
+    /**
+     * Handles cases where no content types match the description
+     */
+    async handleNoContentTypeMatches(description) {
+        const availableTypes = Object.entries(this.glossary).map(([key, type]) => {
+            let title = 'Unknown';
+            let plural = 'Unknown';
+            if (type && typeof type === 'object') {
+                if (type.definition) {
+                    title = type.definition.title || title;
+                    plural = type.definition.plural || plural;
+                }
+                else if (type.type) {
+                    title = type.type.title || title;
+                    plural = type.type.plural || plural;
+                }
+                else if (type.title) {
+                    title = type.title || title;
+                    plural = type.plural || plural;
+                }
+            }
+            return { key, title, plural };
+        });
+        // Group types by category for better organization
+        const categorizedTypes = this.categorizeContentTypes(availableTypes);
+        return {
+            content: [{
+                    type: 'text',
+                    text: `❌ **NO MATCHING CONTENT TYPE FOUND**
+
+I couldn't find a content type for "${description}".
+
+**AVAILABLE CONTENT TYPES BY CATEGORY:**
+
+${categorizedTypes}
+
+**SUGGESTIONS:**
+- Try using more specific terms (e.g., "incident report" instead of "report")
+- Check if you meant to create a workflow definition or workflow card
+- Use the exact content type key from the list above
+
+**NEED HELP?**
+- Use \`qik_get_glossary\` to see all available types with descriptions
+- Use \`qik_get_content_definition\` with a specific type to see its fields`,
+                }],
+            isError: true,
+        };
+    }
+    /**
+     * Categorizes content types for better organization in help text
+     */
+    categorizeContentTypes(types) {
+        const categories = {
+            'Core Content': [],
+            'People & Profiles': [],
+            'Workflows & Processes': [],
+            'Communication': [],
+            'Media & Files': [],
+            'System & Admin': [],
+            'Other': []
+        };
+        for (const type of types) {
+            const key = type.key.toLowerCase();
+            const title = type.title.toLowerCase();
+            if (key.includes('profile') || key.includes('person') || key.includes('user')) {
+                categories['People & Profiles'].push(type);
+            }
+            else if (key.includes('workflow') || key.includes('definition') || key.includes('process')) {
+                categories['Workflows & Processes'].push(type);
+            }
+            else if (key.includes('comment') || key.includes('message') || key.includes('notification') || key.includes('email')) {
+                categories['Communication'].push(type);
+            }
+            else if (key.includes('file') || key.includes('image') || key.includes('video') || key.includes('audio')) {
+                categories['Media & Files'].push(type);
+            }
+            else if (key.includes('scope') || key.includes('role') || key.includes('policy') || key.includes('variable')) {
+                categories['System & Admin'].push(type);
+            }
+            else if (['article', 'event', 'object'].includes(key)) {
+                categories['Core Content'].push(type);
+            }
+            else {
+                categories['Other'].push(type);
+            }
+        }
+        let result = '';
+        for (const [category, categoryTypes] of Object.entries(categories)) {
+            if (categoryTypes.length > 0) {
+                result += `\n**${category}:**\n`;
+                result += categoryTypes.map(t => `- ${t.key}: ${t.title} (${t.plural})`).join('\n');
+                result += '\n';
+            }
+        }
+        return result;
+    }
+    /**
+     * Handles cases where multiple content types match
+     */
+    async handleMultipleContentTypeMatches(description, contentTypeMatches) {
+        const matchDetails = contentTypeMatches.map(key => {
+            const type = this.glossary[key];
+            let title = 'Unknown';
+            let plural = 'Unknown';
+            let baseType = '';
+            if (type && typeof type === 'object') {
+                if (type.definition) {
+                    title = type.definition.title || title;
+                    plural = type.definition.plural || plural;
+                    baseType = type.definition.definesType || '';
+                }
+                else if (type.type) {
+                    title = type.type.title || title;
+                    plural = type.type.plural || plural;
+                }
+                else if (type.title) {
+                    title = type.title || title;
+                    plural = type.plural || plural;
+                    baseType = type.definesType || '';
+                }
+            }
+            return { key, title, plural, baseType };
+        });
+        return {
+            content: [{
+                    type: 'text',
+                    text: `🔍 **MULTIPLE CONTENT TYPES FOUND**
+
+I found multiple content types that match "${description}". Please clarify which one you'd like to create:
+
+${matchDetails.map(t => {
+                        let description = `- **${t.key}**: ${t.title} (${t.plural})`;
+                        if (t.baseType) {
+                            description += ` - extends ${t.baseType}`;
+                        }
+                        return description;
+                    }).join('\n')}
+
+**TO PROCEED:**
+1. Choose the exact content type key from above
+2. Use \`qik_create_content\` with your chosen type
+3. Or use \`qik_get_content_definition\` to see field details first
+
+**NEED MORE INFO?**
+Use \`qik_get_content_definition\` with any of the type keys above to see their specific fields and requirements.`,
+                }],
+            isError: true,
+        };
+    }
+    /**
+     * Handles single content type match with comprehensive guidance
+     */
+    async handleSingleContentTypeMatch(contentType, description, additionalData) {
         const typeInfo = this.getContentTypeInfo(contentType);
         if (!typeInfo) {
             return {
                 content: [{
                         type: 'text',
-                        text: `Found content type "${contentType}" but couldn't load its definition.`,
+                        text: `❌ Found content type "${contentType}" but couldn't load its definition.`,
                     }],
                 isError: true,
             };
         }
-        // Analyze the fields to provide guidance
+        // Extract comprehensive type information
+        const typeAnalysis = this.analyzeContentTypeStructure(typeInfo);
+        let guidance = `✅ **CONTENT TYPE FOUND: ${contentType.toUpperCase()}**\n\n`;
+        guidance += `**Type**: ${typeAnalysis.title}\n`;
+        guidance += `**Description**: ${typeAnalysis.description || 'No description available'}\n`;
+        if (typeAnalysis.baseType) {
+            guidance += `**Extends**: ${typeAnalysis.baseType}\n`;
+        }
+        guidance += `\n**FIELD STRUCTURE:**\n`;
+        if (typeAnalysis.requiredFields.length > 0) {
+            guidance += `\n**Required Fields:**\n`;
+            guidance += typeAnalysis.requiredFields.map(f => `- **${f.key}** (${f.title}): ${f.description || 'No description'}`).join('\n');
+        }
+        if (typeAnalysis.optionalFields.length > 0) {
+            guidance += `\n\n**Optional Fields:**\n`;
+            guidance += typeAnalysis.optionalFields.map(f => `- **${f.key}** (${f.title}): ${f.description || 'No description'}`).join('\n');
+        }
+        // Handle creation if data provided
+        if (additionalData && typeof additionalData === 'object' && additionalData.title) {
+            return await this.handleContentCreationWithData(contentType, additionalData, typeAnalysis);
+        }
+        // Provide creation guidance
+        guidance += await this.generateCreationGuidance(contentType, typeAnalysis);
+        return {
+            content: [{
+                    type: 'text',
+                    text: guidance,
+                }],
+        };
+    }
+    /**
+     * Analyzes content type structure for comprehensive information
+     */
+    analyzeContentTypeStructure(typeInfo) {
         let fields = [];
-        let typeTitle = 'Unknown';
+        let title = 'Unknown';
+        let description = '';
+        let baseType = '';
         if (typeInfo.definition) {
             fields = typeInfo.definition.fields || [];
-            typeTitle = typeInfo.definition.title || typeTitle;
+            title = typeInfo.definition.title || title;
+            description = typeInfo.definition.description || '';
+            baseType = typeInfo.definition.definesType || '';
         }
         else if (typeInfo.type) {
             fields = typeInfo.type.fields || [];
-            typeTitle = typeInfo.type.title || typeTitle;
+            title = typeInfo.type.title || title;
+            description = typeInfo.type.description || '';
         }
         else if (typeInfo.fields) {
             fields = typeInfo.fields || [];
-            typeTitle = typeInfo.title || typeTitle;
+            title = typeInfo.title || title;
+            description = typeInfo.description || '';
+            baseType = typeInfo.definesType || '';
         }
         const requiredFields = fields.filter((f) => f.minimum && f.minimum > 0);
         const optionalFields = fields.filter((f) => !f.minimum || f.minimum === 0);
-        let guidance = `I found the content type "${contentType}" (${typeTitle}) for "${description}".\n\n`;
-        if (requiredFields.length > 0) {
-            guidance += `Required fields:\n${requiredFields.map(f => `- ${f.key} (${f.title}): ${f.description || 'No description'}`).join('\n')}\n\n`;
-        }
-        if (optionalFields.length > 0) {
-            guidance += `Optional fields:\n${optionalFields.map(f => `- ${f.key} (${f.title}): ${f.description || 'No description'}`).join('\n')}\n\n`;
-        }
-        // If additional data was provided, check if we have scopes and try to create the content
-        if (additionalData && typeof additionalData === 'object' && additionalData.title) {
-            // Check if scopes are provided
-            if (!additionalData.meta || !additionalData.meta.scopes || !Array.isArray(additionalData.meta.scopes) || additionalData.meta.scopes.length === 0) {
-                // Get available scopes
-                const scopeTree = await this.getAvailableScopes();
-                if (scopeTree) {
-                    const availableScopes = this.extractScopesWithPermissions(scopeTree, 'create');
-                    if (availableScopes.length === 0) {
-                        return {
-                            content: [{
-                                    type: 'text',
-                                    text: `You don't have permission to create content in any scopes. Please contact your administrator.`,
-                                }],
-                            isError: true,
-                        };
-                    }
+        return {
+            title,
+            description,
+            baseType,
+            fields,
+            requiredFields,
+            optionalFields,
+            fieldCount: fields.length
+        };
+    }
+    /**
+     * Handles content creation when data is provided
+     */
+    async handleContentCreationWithData(contentType, additionalData, typeAnalysis) {
+        // Check if scopes are provided
+        if (!additionalData.meta || !additionalData.meta.scopes || !Array.isArray(additionalData.meta.scopes) || additionalData.meta.scopes.length === 0) {
+            const scopeTree = await this.getAvailableScopes();
+            if (scopeTree) {
+                const availableScopes = this.extractScopesWithPermissions(scopeTree, 'create');
+                if (availableScopes.length === 0) {
                     return {
                         content: [{
                                 type: 'text',
-                                text: `To create "${additionalData.title}" as a ${typeTitle}, you need to specify which scope to create it in. You have permission to create content in these scopes:\n\n${availableScopes.map(s => `- ${s.id}: ${s.path}`).join('\n')}\n\nPlease use the qik_create_content tool with:\n- type: "${contentType}"\n- title: "${additionalData.title}"\n- meta: { "scopes": ["scope_id_here"] }\n- data: { /* your field values */ }`,
+                                text: `🚫 **PERMISSION DENIED**\n\nYou don't have permission to create content in any scopes. Please contact your administrator.`,
                             }],
+                        isError: true,
                     };
                 }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `📍 **SCOPE SELECTION REQUIRED**\n\nTo create "${additionalData.title}" as a ${typeAnalysis.title}, you need to specify which scope to create it in.\n\n**Available Scopes:**\n${availableScopes.map(s => `- **${s.id}**: ${s.path}`).join('\n')}\n\n**TO CREATE:**\nUse \`qik_create_content\` with:\n- type: "${contentType}"\n- title: "${additionalData.title}"\n- meta: { "scopes": ["scope_id_here"] }\n- data: { /* your field values */ }`,
+                        }],
+                };
             }
-            // Scopes are provided, proceed with creation
-            const title = additionalData.title || `New ${typeTitle}`;
-            const data = additionalData.data || {};
-            const meta = additionalData.meta || {};
-            return await this.createContent({
-                type: contentType,
-                title,
-                data,
-                meta,
-            });
         }
-        // Get available scopes for guidance
+        // Proceed with creation
+        const title = additionalData.title || `New ${typeAnalysis.title}`;
+        const data = additionalData.data || {};
+        const meta = additionalData.meta || {};
+        return await this.createContent({
+            type: contentType,
+            title,
+            data,
+            meta,
+        });
+    }
+    /**
+     * Generates comprehensive creation guidance
+     */
+    async generateCreationGuidance(contentType, typeAnalysis) {
+        let guidance = `\n\n**CREATION GUIDANCE:**\n`;
+        // Get available scopes
         const scopeTree = await this.getAvailableScopes();
         let scopeGuidance = '';
         if (scopeTree) {
             const availableScopes = this.extractScopesWithPermissions(scopeTree, 'create');
             if (availableScopes.length > 0) {
-                scopeGuidance = `\n\nAvailable scopes you can create content in:\n${availableScopes.map(s => `- ${s.id}: ${s.path}`).join('\n')}\n`;
+                scopeGuidance = `\n**Available Scopes:**\n${availableScopes.map(s => `- **${s.id}**: ${s.path}`).join('\n')}\n`;
             }
         }
-        guidance += `To create this content, use the qik_create_content tool with:\n`;
-        guidance += `- type: "${contentType}"\n`;
-        guidance += `- title: "Your title here"\n`;
-        guidance += `- meta: { "scopes": ["scope_id_here"] } (required)\n`;
-        guidance += `- data: { /* field values */ }\n`;
+        guidance += `\n**TO CREATE THIS CONTENT:**\n`;
+        guidance += `Use \`qik_create_content\` with:\n`;
+        guidance += `- **type**: "${contentType}"\n`;
+        guidance += `- **title**: "Your title here"\n`;
+        guidance += `- **meta**: { "scopes": ["scope_id_here"] } *(required)*\n`;
+        guidance += `- **data**: { /* field values based on structure above */ }\n`;
         guidance += scopeGuidance;
-        return {
-            content: [{
-                    type: 'text',
-                    text: guidance,
-                }],
-        };
+        // Add specific guidance for common types
+        if (contentType === 'definition') {
+            guidance += `\n**WORKFLOW DEFINITION EXAMPLE:**\n`;
+            guidance += `For workflow definitions, include the workflow structure in the data field with columns, steps, and automation rules.\n`;
+        }
+        if (contentType.includes('comment') || contentType.includes('Comment')) {
+            guidance += `\n**COMMENT CREATION:**\n`;
+            guidance += `Comments require a reference to the item being commented on. Include:\n`;
+            guidance += `- **reference**: ID of the item to comment on\n`;
+            guidance += `- **referenceType**: Type of the referenced item\n`;
+        }
+        return guidance;
+    }
+    generateToolDescription(baseDescription, emoji = '') {
+        const prefix = emoji ? `${emoji} ` : '';
+        return `${prefix}${baseDescription.replace(/Qik/g, this.serverName)}`;
     }
     setupToolHandlers() {
         this.server.setRequestHandler(ListToolsRequestSchema, async () => {
@@ -874,7 +1304,7 @@ EXAMPLES:
                 // Authentication & Session
                 {
                     name: 'qik_get_user_session',
-                    description: 'Get current user session information',
+                    description: this.generateToolDescription('Get current user session information', '👤'),
                     inputSchema: {
                         type: 'object',
                         properties: {},
@@ -883,7 +1313,7 @@ EXAMPLES:
                 // Content Type Discovery
                 {
                     name: 'qik_get_glossary',
-                    description: 'Get all available content types and their definitions',
+                    description: this.generateToolDescription('Get all available content types and their definitions', '📚'),
                     inputSchema: {
                         type: 'object',
                         properties: {},
@@ -891,7 +1321,7 @@ EXAMPLES:
                 },
                 {
                     name: 'qik_get_content_definition',
-                    description: 'Get definition for a specific content type',
+                    description: this.generateToolDescription('Get definition for a specific content type', '🔍'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -907,7 +1337,7 @@ EXAMPLES:
                 // Content Management
                 {
                     name: 'qik_get_content',
-                    description: 'Get content item by ID or slug',
+                    description: this.generateToolDescription('Get content item by ID or slug', '📄'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -928,7 +1358,27 @@ EXAMPLES:
                 },
                 {
                     name: 'qik_list_content',
-                    description: 'List content items with advanced filtering and search capabilities. Supports complex queries like birthdays, date ranges, and sophisticated business logic.',
+                    description: this.generateToolDescription(`List content items with advanced filtering and search capabilities. Supports complex queries like birthdays, date ranges, and sophisticated business logic.
+
+**ENHANCED FILTER CAPABILITIES:**
+- 40+ comparators for dates, strings, numbers, and arrays
+- Hierarchical filters with 'and', 'or', 'nor' operators
+- Anniversary and birthday queries (anniversarynext, anniversarypast)
+- Date range filtering (datebetween, datepast, datenext)
+- String matching (contains, startswith, endswith, equal)
+- Numeric comparisons (greater, lesser, between)
+- Array operations (in, notin, valuesgreater)
+
+**COMMON USE CASES:**
+- Find birthdays in next 10 days: {"operator":"and","filters":[{"key":"dob","comparator":"anniversarynext","value":10,"value2":"days"}]}
+- Recent content: {"operator":"and","filters":[{"key":"meta.created","comparator":"datepast","value":30,"value2":"days"}]}
+- Gender filtering: {"operator":"and","filters":[{"key":"gender","comparator":"equal","value":"male"}]}
+- Complex queries with OR logic for multiple conditions
+
+**FIELD TARGETING:**
+- Use dot notation for nested fields: "meta.created", "data.customField"
+- Target specific profile fields: "firstName", "lastName", "emails"
+- Filter by metadata: "meta.scopes", "meta.tags", "meta.security"`, '📋'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -939,28 +1389,50 @@ EXAMPLES:
                             },
                             search: {
                                 type: 'string',
-                                description: 'Search keywords',
+                                description: 'Search keywords - searches within title, tags, and text areas',
                             },
                             filter: this.generateEnhancedFilterSchema(),
                             sort: {
                                 type: 'object',
+                                description: 'Sorting configuration for results',
                                 properties: {
-                                    key: { type: 'string' },
-                                    direction: { type: 'string', enum: ['asc', 'desc'] },
-                                    type: { type: 'string', enum: ['string', 'number', 'date'] },
+                                    key: {
+                                        type: 'string',
+                                        description: 'Field to sort by (e.g., "title", "meta.created", "data.customField")'
+                                    },
+                                    direction: {
+                                        type: 'string',
+                                        enum: ['asc', 'desc'],
+                                        description: 'Sort direction: ascending or descending'
+                                    },
+                                    type: {
+                                        type: 'string',
+                                        enum: ['string', 'number', 'date'],
+                                        description: 'Data type for proper sorting behavior'
+                                    },
                                 },
                             },
                             page: {
                                 type: 'object',
+                                description: 'Pagination settings',
                                 properties: {
-                                    size: { type: 'number', minimum: 1, maximum: 100 },
-                                    index: { type: 'number', minimum: 1 },
+                                    size: {
+                                        type: 'number',
+                                        minimum: 1,
+                                        maximum: 100,
+                                        description: 'Number of items per page (1-100)'
+                                    },
+                                    index: {
+                                        type: 'number',
+                                        minimum: 1,
+                                        description: 'Page number to retrieve (starts at 1)'
+                                    },
                                 },
                             },
                             select: {
                                 type: 'array',
                                 items: { type: 'string' },
-                                description: 'Fields to include in response',
+                                description: 'Specific fields to include in response (e.g., ["title", "data.make", "meta.created"])',
                             },
                         },
                         required: ['type'],
@@ -968,39 +1440,67 @@ EXAMPLES:
                 },
                 {
                     name: 'qik_create_content',
-                    description: 'Create new content item. IMPORTANT: Fields are structured based on content type - some go at root level, others in data object.',
+                    description: this.generateToolDescription(`Create new content item with intelligent field structure handling.
+
+**FIELD STRUCTURE INTELLIGENCE:**
+- Automatically separates root-level fields from data object fields
+- Handles comment inheritance (comments inherit scopes from referenced items)
+- Validates field requirements based on content type definitions
+- Supports workflow definitions, workflow cards, and all content types
+
+**FIELD PLACEMENT RULES:**
+- **Root Level**: reference, referenceType, body, organisation, title, meta
+- **Data Object**: Custom fields defined in content type definitions (definedFields)
+- **Meta Object**: scopes (required), tags, security, personaAuthor, etc.
+
+**CONTENT TYPE EXAMPLES:**
+- **Comments**: Require reference + referenceType, inherit scopes automatically
+- **Workflow Definitions**: Use data object for workflow structure (columns, steps, automation)
+- **Workflow Cards**: Reference profiles, link to workflow definitions
+- **Profiles**: firstName, lastName at root, custom fields in data object
+- **Articles**: body at root level, custom article fields in data object
+
+**SCOPE INHERITANCE:**
+- Comments automatically inherit scopes from referenced items
+- Other content types require explicit scope assignment
+- Use qik_get_scopes to find available scopes with permissions
+
+**VALIDATION:**
+- Checks content type exists and user has access
+- Validates required fields based on content type definition
+- Ensures proper field placement (root vs data object)`, '✨'),
                     inputSchema: {
                         type: 'object',
                         properties: {
                             type: {
                                 type: 'string',
-                                description: 'Content type to create',
+                                description: 'Content type to create (use qik_get_glossary to see all available types)',
                                 enum: Object.keys(this.glossary),
                             },
                             title: {
                                 type: 'string',
-                                description: 'Content title',
+                                description: 'Content title (required for all content types)',
                             },
                             // Generate dynamic properties based on content types
                             ...this.generateDynamicContentProperties(),
                             meta: {
                                 type: 'object',
-                                description: 'Meta information (scopes, tags, etc.)',
+                                description: 'Meta information (scopes required for most content types)',
                                 properties: {
                                     scopes: {
                                         type: 'array',
                                         items: { type: 'string' },
-                                        description: 'Scope IDs where this content should be stored',
+                                        description: 'Scope IDs where this content should be stored (REQUIRED - use qik_get_scopes to find available)',
                                     },
                                     tags: {
                                         type: 'array',
                                         items: { type: 'string' },
-                                        description: 'Tag IDs for this content',
+                                        description: 'Tag IDs for categorization and search',
                                     },
                                     security: {
                                         type: 'string',
                                         enum: ['public', 'secure', 'private'],
-                                        description: 'Security level for this content',
+                                        description: 'Security level: public (everyone), secure (authenticated), private (restricted)',
                                     },
                                 },
                             },
@@ -1010,7 +1510,7 @@ EXAMPLES:
                 },
                 {
                     name: 'qik_update_content',
-                    description: 'Update existing content item',
+                    description: this.generateToolDescription('Update existing content item', '✏️'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -1033,7 +1533,7 @@ EXAMPLES:
                 },
                 {
                     name: 'qik_delete_content',
-                    description: 'Delete content item',
+                    description: this.generateToolDescription('Delete content item', '🗑️'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -1048,7 +1548,7 @@ EXAMPLES:
                 // Profile Management
                 {
                     name: 'qik_list_profiles',
-                    description: 'Search and list profiles/people',
+                    description: this.generateToolDescription('Search and list profiles/people', '👥'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -1072,7 +1572,7 @@ EXAMPLES:
                 },
                 {
                     name: 'qik_create_profile',
-                    description: 'Create new profile/person',
+                    description: this.generateToolDescription('Create new profile/person', '👤'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -1116,7 +1616,7 @@ EXAMPLES:
                 // Form Management
                 {
                     name: 'qik_get_form',
-                    description: 'Get form definition',
+                    description: this.generateToolDescription('Get form definition', '📝'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -1130,7 +1630,7 @@ EXAMPLES:
                 },
                 {
                     name: 'qik_submit_form',
-                    description: 'Submit form data',
+                    description: this.generateToolDescription('Submit form data', '📤'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -1149,7 +1649,7 @@ EXAMPLES:
                 // File Management
                 {
                     name: 'qik_upload_file',
-                    description: 'Upload file to Qik',
+                    description: this.generateToolDescription('Upload file to platform', '📁'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -1180,7 +1680,7 @@ EXAMPLES:
                 // Search & Discovery
                 {
                     name: 'qik_search_content',
-                    description: 'Global content search across all types',
+                    description: this.generateToolDescription('Global content search across all types', '🔎'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -1208,7 +1708,7 @@ EXAMPLES:
                 },
                 {
                     name: 'qik_get_scopes',
-                    description: 'Get available scopes/permissions tree',
+                    description: this.generateToolDescription('Get available scopes/permissions tree', '🔐'),
                     inputSchema: {
                         type: 'object',
                         properties: {},
@@ -1217,7 +1717,7 @@ EXAMPLES:
                 // Utility Tools
                 {
                     name: 'qik_get_smartlist',
-                    description: 'Execute a smartlist query',
+                    description: this.generateToolDescription('Execute a smartlist query', '📊'),
                     inputSchema: {
                         type: 'object',
                         properties: {
@@ -1229,28 +1729,70 @@ EXAMPLES:
                         required: ['id'],
                     },
                 },
-                // Intelligent Content Creation
+                // Intelligent Content Creation with Advanced Disambiguation
                 {
                     name: 'qik_create_content_intelligent',
-                    description: 'Intelligently create content by description (e.g., "create an incident report", "make a new event")',
+                    description: this.generateToolDescription(`Intelligently create content with advanced disambiguation logic. 
+
+**WORKFLOW DISAMBIGUATION:**
+- "create a workflow" → Creates workflow DEFINITION (template)
+- "add Jim to workflow X" → Creates workflow CARD (instance)
+- "design student onboarding workflow" → Creates workflow DEFINITION
+- "assign Sarah to project workflow" → Creates workflow CARD
+
+**CONTENT TYPE DISAMBIGUATION:**
+- Automatically detects intent between definitions vs instances
+- Provides comprehensive guidance for workflow systems
+- Categorizes content types for better organization
+- Handles scope permissions and requirements
+
+**EXAMPLES:**
+- "create an incident report" → Finds incident report content type
+- "make a new workflow" → Guides through workflow definition creation
+- "add person to existing workflow" → Guides through workflow card creation
+- "design a student induction process" → Creates workflow definition
+
+**WORKFLOW CONCEPTS EXPLAINED:**
+- **Workflow Definition**: Template with columns, steps, automation rules
+- **Workflow Card**: Individual items that move through the workflow
+- **Columns**: Stages like "To Do", "In Progress", "Done"
+- **Steps**: Specific positions within columns
+- **Automation**: Entry/exit/success/fail functions`, '🧠'),
                     inputSchema: {
                         type: 'object',
                         properties: {
                             description: {
                                 type: 'string',
-                                description: 'Natural language description of what to create (e.g., "incident report", "event", "article")',
+                                description: 'Natural language description of what to create. Examples: "create an incident report", "make a new workflow", "add Jim to student workflow", "design onboarding process"',
                             },
                             title: {
                                 type: 'string',
-                                description: 'Title for the content',
+                                description: 'Title for the content (optional - will be requested if needed)',
                             },
                             data: {
                                 type: 'object',
-                                description: 'Content data fields',
+                                description: 'Content data fields (optional - will be guided through structure)',
                             },
                             meta: {
                                 type: 'object',
-                                description: 'Meta information (scopes, tags, etc.)',
+                                description: 'Meta information including scopes, tags, security level (will be guided through requirements)',
+                                properties: {
+                                    scopes: {
+                                        type: 'array',
+                                        items: { type: 'string' },
+                                        description: 'Scope IDs where content should be created'
+                                    },
+                                    tags: {
+                                        type: 'array',
+                                        items: { type: 'string' },
+                                        description: 'Tag IDs for categorization'
+                                    },
+                                    security: {
+                                        type: 'string',
+                                        enum: ['public', 'secure', 'private'],
+                                        description: 'Security level for the content'
+                                    }
+                                }
                             },
                         },
                         required: ['description'],