@qikdev/mcp 6.6.6 → 6.6.9

package/build/src/index.js

@@ -49,6 +49,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } f
 import axios from 'axios';
 import FormData from 'form-data';
 import { ConfigManager } from './config.js';
+import { QikDocumentationHelper, QIK_DOCUMENTATION } from './documentation.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;
@@ -199,7 +200,7 @@ export class QikMCPServer {
         }
         return { valid: true, info };
     }
-    // Helper methods for field analysis and processing
+    // Enhanced glossary-driven field analysis methods
     isFieldRequired(field) {
         return field.minimum !== undefined && field.minimum > 0;
     }
@@ -209,6 +210,114 @@ export class QikMCPServer {
     getMinimumArrayLength(field) {
         return this.isFieldArray(field) ? (field.minimum || 0) : 0;
     }
+    /**
+     * Validates widget-specific field values
+     */
+    validateWidgetValue(fieldKey, value, widgetType) {
+        const errors = [];
+        const warnings = [];
+        switch (widgetType) {
+            case 'dateobject':
+                return this.validateDateObjectWidget(fieldKey, value);
+            case 'date':
+                if (typeof value === 'string') {
+                    const dateRegex = /^\d{4}-\d{2}-\d{2}$/;
+                    if (!dateRegex.test(value)) {
+                        errors.push(`Field "${fieldKey}" with date widget must use ISO date format (YYYY-MM-DD), got: ${value}`);
+                    }
+                }
+                else {
+                    errors.push(`Field "${fieldKey}" with date widget must be a string in ISO date format (YYYY-MM-DD)`);
+                }
+                break;
+            case 'time':
+                if (typeof value === 'string') {
+                    const timeRegex = /^\d{2}:\d{2}(:\d{2})?$/;
+                    if (!timeRegex.test(value)) {
+                        errors.push(`Field "${fieldKey}" with time widget must use time format (HH:MM or HH:MM:SS), got: ${value}`);
+                    }
+                }
+                else {
+                    errors.push(`Field "${fieldKey}" with time widget must be a string in time format (HH:MM)`);
+                }
+                break;
+            case 'datetime':
+                if (typeof value === 'string') {
+                    try {
+                        new Date(value);
+                    }
+                    catch (e) {
+                        errors.push(`Field "${fieldKey}" with datetime widget must be a valid ISO datetime string, got: ${value}`);
+                    }
+                }
+                else {
+                    errors.push(`Field "${fieldKey}" with datetime widget must be a string in ISO datetime format`);
+                }
+                break;
+            default:
+                // No specific validation for other widget types
+                break;
+        }
+        return { valid: errors.length === 0, errors, warnings };
+    }
+    /**
+     * Validates dateobject widget values
+     */
+    validateDateObjectWidget(fieldKey, value) {
+        const errors = [];
+        const warnings = [];
+        if (!value || typeof value !== 'object') {
+            errors.push(`Field "${fieldKey}" with dateobject widget must be an object with hour, minute, day, month, year properties`);
+            return { valid: false, errors, warnings };
+        }
+        const requiredProps = ['hour', 'minute', 'day', 'month', 'year'];
+        const missingProps = requiredProps.filter(prop => value[prop] === undefined || value[prop] === null);
+        if (missingProps.length > 0) {
+            errors.push(`Field "${fieldKey}" dateobject is missing required properties: ${missingProps.join(', ')}`);
+        }
+        // Validate ranges
+        if (typeof value.hour === 'number') {
+            if (value.hour < 0 || value.hour > 23) {
+                errors.push(`Field "${fieldKey}" dateobject hour must be between 0-23, got: ${value.hour}`);
+            }
+        }
+        else if (value.hour !== undefined) {
+            errors.push(`Field "${fieldKey}" dateobject hour must be a number`);
+        }
+        if (typeof value.minute === 'number') {
+            if (value.minute < 0 || value.minute > 59) {
+                errors.push(`Field "${fieldKey}" dateobject minute must be between 0-59, got: ${value.minute}`);
+            }
+        }
+        else if (value.minute !== undefined) {
+            errors.push(`Field "${fieldKey}" dateobject minute must be a number`);
+        }
+        if (typeof value.day === 'number') {
+            if (value.day < 1 || value.day > 31) {
+                errors.push(`Field "${fieldKey}" dateobject day must be between 1-31, got: ${value.day}`);
+            }
+        }
+        else if (value.day !== undefined) {
+            errors.push(`Field "${fieldKey}" dateobject day must be a number`);
+        }
+        if (typeof value.month === 'number') {
+            if (value.month < 1 || value.month > 12) {
+                errors.push(`Field "${fieldKey}" dateobject month must be between 1-12, got: ${value.month}`);
+            }
+        }
+        else if (value.month !== undefined) {
+            errors.push(`Field "${fieldKey}" dateobject month must be a number`);
+        }
+        if (typeof value.year === 'number') {
+            if (value.year < 1900 || value.year > 2100) {
+                warnings.push(`Field "${fieldKey}" dateobject year ${value.year} seems unusual (expected 1900-2100)`);
+            }
+        }
+        else if (value.year !== undefined) {
+            errors.push(`Field "${fieldKey}" dateobject year must be a number`);
+        }
+        return { valid: errors.length === 0, errors, warnings };
+    }
     generateFieldPath(field, isDefinedField, groupPath = '') {
         let basePath = isDefinedField ? 'data' : '';
         if (groupPath) {
@@ -363,57 +472,83 @@ export class QikMCPServer {
                 return 'string';
         }
     }
+    /**
+     * Generates completely dynamic properties based on the loaded glossary
+     * This creates schema properties for ALL fields from ALL content types
+     */
     generateDynamicContentProperties() {
-        // Generate dynamic properties that show field structure for common content types
         const properties = {};
-        // Add common root-level fields that appear across content types
-        const commonRootFields = ['reference', 'referenceType', 'body', 'organisation'];
-        for (const fieldKey of commonRootFields) {
-            properties[fieldKey] = {
-                type: 'string',
-                description: `${fieldKey} field (ALWAYS goes at ROOT LEVEL, never in data object)`,
-            };
+        // Collect all unique fields from all content types in the glossary
+        const allRootFields = new Set();
+        const allDataFields = new Set();
+        const fieldSchemas = new Map();
+        // Process each content type in the glossary
+        for (const [contentTypeKey, contentType] of Object.entries(this.glossary)) {
+            if (!contentType || typeof contentType !== 'object')
+                continue;
+            // Get fields from the content type (these go at root level)
+            const fields = contentType.fields || [];
+            for (const field of fields) {
+                if (field.key && field.key !== '_id') { // Skip internal ID field
+                    allRootFields.add(field.key);
+                    // Generate schema for this field
+                    if (!fieldSchemas.has(field.key)) {
+                        fieldSchemas.set(field.key, this.generateFieldSchema(field));
+                    }
+                }
+            }
+            // Get definedFields from the content type (these go in data object)
+            const definedFields = contentType.definedFields || [];
+            for (const field of definedFields) {
+                if (field.key) {
+                    allDataFields.add(field.key);
+                    // Generate schema for this field
+                    if (!fieldSchemas.has(field.key)) {
+                        fieldSchemas.set(field.key, this.generateFieldSchema(field));
+                    }
+                }
+            }
         }
-        // Add a data object for definedFields with clear explanation
+        // Add all root-level fields as properties
+        for (const fieldKey of allRootFields) {
+            if (fieldKey !== 'title' && fieldKey !== 'meta') { // These are handled separately
+                const schema = fieldSchemas.get(fieldKey);
+                if (schema) {
+                    properties[fieldKey] = {
+                        ...schema,
+                        description: `${schema.description || fieldKey} (ROOT LEVEL field from glossary)`
+                    };
+                }
+            }
+        }
+        // Create comprehensive data object with all possible data fields
+        const dataProperties = {};
+        for (const fieldKey of allDataFields) {
+            const schema = fieldSchemas.get(fieldKey);
+            if (schema) {
+                dataProperties[fieldKey] = {
+                    ...schema,
+                    description: `${schema.description || fieldKey} (DATA OBJECT field from glossary)`
+                };
+            }
+        }
+        // Add the data object with dynamic properties
         properties.data = {
             type: 'object',
-            description: `CRITICAL FIELD PLACEMENT RULE: 
+            description: `DYNAMIC FIELD PLACEMENT (based on glossary):
       
-**ROOT LEVEL FIELDS (never put these in data object):**
-- title, reference, referenceType, body, organisation, meta
-- These are "fields" in the glossary definition
+**ROOT LEVEL FIELDS (from glossary "fields" array):**
+${Array.from(allRootFields).sort().join(', ')}
 
-**DATA OBJECT FIELDS (always put these in data object):**
-- Custom fields defined as "definedFields" in the glossary
-- Content-type specific fields like wasAnyoneHurt, customField1, etc.
+**DATA OBJECT FIELDS (from glossary "definedFields" array):**
+${Array.from(allDataFields).sort().join(', ')}
 
-**WRONG EXAMPLE:**
-{
-  "data": {
-    "title": "My Title",  // ❌ WRONG - title goes at root level
-    "plural": "My Items", // ❌ WRONG - plural goes at root level
-    "customField": "value"
-  }
-}
+**FIELD PLACEMENT RULE:**
+- Fields in glossary "fields" array → ROOT LEVEL
+- Fields in glossary "definedFields" array → DATA OBJECT
 
-**CORRECT EXAMPLE:**
-{
-  "title": "My Title",     // ✅ CORRECT - at root level
-  "data": {
-    "customField": "value" // ✅ CORRECT - custom fields in data object
-  }
-}`,
-            properties: {
-                wasAnyoneHurt: {
-                    type: 'string',
-                    description: 'For incident reports - whether anyone was hurt (this is a definedField, so it goes in data object)',
-                    enum: ['yes', 'no']
-                },
-                whatTimeDidItHappen: {
-                    type: 'string',
-                    description: 'For incident reports - when the incident occurred (this is a definedField, so it goes in data object)'
-                }
-            }
+The MCP server automatically determines correct placement based on the glossary definition for each content type.`,
+            properties: dataProperties
         };
         return properties;
     }
@@ -1638,6 +1773,46 @@ Use \`qik_get_content_definition\` with any of the type keys above to see their
                         required: ['firstName', 'lastName'],
                     },
                 },
+                {
+                    name: 'qik_get_profile_timeline',
+                    description: this.generateToolDescription('Get a profile timeline with chronological activity data - provides much richer information than basic profile details including recent actions, content created, events attended, workflow activities, and other activity logs', '📅'),
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Profile ID to get timeline for',
+                            },
+                        },
+                        required: ['id'],
+                    },
+                },
+                {
+                    name: 'qik_get_profile_info',
+                    description: this.generateToolDescription('Intelligently get profile information with disambiguation between basic details and activity timeline. Asks clarifying questions when the request is ambiguous to provide the most relevant information', '🤔'),
+                    inputSchema: {
+                        type: 'object',
+                        properties: {
+                            query: {
+                                type: 'string',
+                                description: 'Natural language query about a person (e.g., "Tell me about Jeff", "What has John been up to?", "Get Sarah\'s contact info")',
+                            },
+                            profileId: {
+                                type: 'string',
+                                description: 'Profile ID if known (optional - can search by name if not provided)',
+                            },
+                            profileName: {
+                                type: 'string',
+                                description: 'Person\'s name to search for if ID not provided (optional)',
+                            },
+                            includeTimeline: {
+                                type: 'boolean',
+                                description: 'Whether to include timeline/activity data (optional - will be determined from query if not specified)',
+                            },
+                        },
+                        required: ['query'],
+                    },
+                },
                 // Form Management
                 {
                     name: 'qik_get_form',
@@ -1863,6 +2038,10 @@ Use \`qik_get_content_definition\` with any of the type keys above to see their
                         return await this.getScopes();
                     case 'qik_get_smartlist':
                         return await this.getSmartlist(request.params.arguments);
+                    case 'qik_get_profile_timeline':
+                        return await this.getProfileTimeline(request.params.arguments);
+                    case 'qik_get_profile_info':
+                        return await this.getProfileInfo(request.params.arguments);
                     case 'qik_create_content_intelligent':
                         return await this.intelligentContentCreation(request.params.arguments.description, {
                             title: request.params.arguments.title,
@@ -2124,175 +2303,50 @@ ${JSON.stringify({
                 isError: true,
             };
         }
-        // Get content type info to understand field structure
-        const contentTypeInfo = validation.info;
-        let fields = [];
-        let definedFields = [];
-        let baseType = null;
-        // Extract fields and definedFields from the content type definition
-        if (contentTypeInfo.fields) {
-            fields = contentTypeInfo.fields;
-            definedFields = contentTypeInfo.definedFields || [];
-            baseType = contentTypeInfo.definesType;
-        }
-        else if (contentTypeInfo.definition) {
-            fields = contentTypeInfo.definition.fields || [];
-            definedFields = contentTypeInfo.definition.definedFields || [];
-            baseType = contentTypeInfo.definition.definesType;
-        }
-        else if (contentTypeInfo.type) {
-            fields = contentTypeInfo.type.fields || [];
-            definedFields = contentTypeInfo.type.definedFields || [];
-            baseType = contentTypeInfo.type.definesType;
-        }
-        // ENHANCED FIELD PLACEMENT VALIDATION
-        const fieldPlacementErrors = [];
-        const rootFieldKeys = new Set(fields.map(f => f.key));
-        const dataFieldKeys = new Set(definedFields.map(f => f.key));
-        // Check for common misplaced fields in data object
-        if (args.data && typeof args.data === 'object') {
-            const commonRootFields = ['title', 'plural', 'reference', 'referenceType', 'body', 'organisation'];
-            for (const fieldKey of commonRootFields) {
-                if (args.data[fieldKey] !== undefined) {
-                    fieldPlacementErrors.push(`❌ FIELD PLACEMENT ERROR: "${fieldKey}" should be at ROOT LEVEL, not in data object`);
-                }
-            }
-            // Check for fields that should be at root level but are in data
-            for (const [key, value] of Object.entries(args.data)) {
-                if (rootFieldKeys.has(key)) {
-                    fieldPlacementErrors.push(`❌ FIELD PLACEMENT ERROR: "${key}" is defined as a "field" in the glossary and should be at ROOT LEVEL, not in data object`);
-                }
-            }
-        }
-        // Check for fields that should be in data object but are at root level
-        for (const [key, value] of Object.entries(args)) {
-            if (key !== 'type' && key !== 'title' && key !== 'meta' && key !== 'data' &&
-                key !== 'reference' && key !== 'referenceType' && key !== 'body' && key !== 'organisation') {
-                if (dataFieldKeys.has(key)) {
-                    fieldPlacementErrors.push(`❌ FIELD PLACEMENT ERROR: "${key}" is defined as a "definedField" in the glossary and should be in the DATA OBJECT, not at root level`);
-                }
-            }
-        }
-        // If there are field placement errors, return detailed guidance
-        if (fieldPlacementErrors.length > 0) {
-            const rootFieldsList = Array.from(rootFieldKeys).join(', ');
-            const dataFieldsList = Array.from(dataFieldKeys).join(', ');
-            return {
-                content: [{
-                        type: 'text',
-                        text: `🚫 **FIELD PLACEMENT ERRORS DETECTED**
-
-${fieldPlacementErrors.join('\n')}
-
-**CORRECT FIELD PLACEMENT FOR ${args.type.toUpperCase()}:**
-
-**ROOT LEVEL FIELDS (never put in data object):**
-- Standard fields: title, reference, referenceType, body, organisation, meta
-- Content type "fields": ${rootFieldsList || 'none defined'}
-
-**DATA OBJECT FIELDS (always put in data object):**
-- Content type "definedFields": ${dataFieldsList || 'none defined'}
-
-**CORRECT STRUCTURE EXAMPLE:**
-\`\`\`json
-{
-  "type": "${args.type}",
-  "title": "Your Title Here",
-  "reference": "optional-reference-id",
-  "referenceType": "optional-reference-type",
-  "meta": {
-    "scopes": ["scope-id-here"]
-  },
-  "data": {
-    ${Array.from(dataFieldKeys).map(field => `"${field}": "your-value-here"`).join(',\n    ')}
-  }
-}
-\`\`\`
-
-**WHAT TO FIX:**
-1. Move any fields mentioned in the errors above to their correct location
-2. Use qik_get_content_definition with type "${args.type}" to see the complete field structure
-3. Remember: "fields" go at root level, "definedFields" go in data object`,
-                    }],
-                isError: true,
-            };
-        }
-        // Structure payload correctly based on field definitions
-        const payload = {
-            title: args.title,
-            meta: args.meta || {},
-        };
-        // Separate fields into root level vs data object
-        const rootLevelData = {};
-        const dataObjectData = {};
-        // Handle direct field assignments from args (for fields like reference, referenceType, body)
-        const directFields = ['reference', 'referenceType', 'body', 'organisation'];
-        for (const fieldKey of directFields) {
-            if (args[fieldKey] !== undefined) {
-                rootLevelData[fieldKey] = args[fieldKey];
-            }
-        }
-        if (args.data && typeof args.data === 'object') {
-            // Separate the provided data based on field definitions
-            for (const [key, value] of Object.entries(args.data)) {
-                if (rootFieldKeys.has(key)) {
-                    // This field should go at root level (from 'fields')
-                    rootLevelData[key] = value;
-                }
-                else if (dataFieldKeys.has(key)) {
-                    // This field should go in data object (from 'definedFields')
-                    dataObjectData[key] = value;
+        // Simplified approach - send data as provided and let server handle validation
+        try {
+            // Create payload from args as-is
+            const payload = { ...args };
+            // Handle scope inheritance for comment types
+            const isCommentType = args.type === 'comment' || args.type.includes('Comment');
+            if (isCommentType && payload.reference && (!payload.meta?.scopes || payload.meta.scopes.length === 0)) {
+                try {
+                    // Fetch the referenced item to get its scopes
+                    const referencedItem = await this.axiosInstance.get(`/content/${payload.reference}`);
+                    if (referencedItem.data && referencedItem.data.meta && referencedItem.data.meta.scopes) {
+                        if (!payload.meta)
+                            payload.meta = {};
+                        payload.meta.scopes = referencedItem.data.meta.scopes;
+                        this.log(`Inherited scopes from referenced item ${payload.reference}: ${payload.meta.scopes.join(', ')}`);
+                    }
                 }
-                else {
-                    // Unknown field - put in data object as fallback
-                    dataObjectData[key] = value;
+                catch (error) {
+                    this.log(`Failed to fetch referenced item ${payload.reference} for scope inheritance: ${this.formatError(error)}`);
+                    // Continue without scope inheritance if we can't fetch the referenced item
                 }
             }
-        }
-        // Add root level fields to payload
-        Object.assign(payload, rootLevelData);
-        // Add data object fields if any exist
-        if (Object.keys(dataObjectData).length > 0) {
-            payload.data = dataObjectData;
-        }
-        // Handle scope inheritance for comment types
-        const isCommentType = baseType === 'comment' || args.type === 'comment' || args.type.includes('Comment');
-        if (isCommentType && payload.reference && (!payload.meta.scopes || payload.meta.scopes.length === 0)) {
-            try {
-                // Fetch the referenced item to get its scopes
-                const referencedItem = await this.axiosInstance.get(`/content/${payload.reference}`);
-                if (referencedItem.data && referencedItem.data.meta && referencedItem.data.meta.scopes) {
-                    payload.meta.scopes = referencedItem.data.meta.scopes;
-                    this.log(`Inherited scopes from referenced item ${payload.reference}: ${payload.meta.scopes.join(', ')}`);
-                }
-            }
-            catch (error) {
-                this.log(`Failed to fetch referenced item ${payload.reference} for scope inheritance: ${this.formatError(error)}`);
-                // Continue without scope inheritance if we can't fetch the referenced item
-            }
-        }
-        try {
             const response = await this.axiosInstance.post(`/content/${args.type}/create`, payload);
             return {
                 content: [{
                         type: 'text',
                         text: `✅ **SUCCESSFULLY CREATED ${args.type.toUpperCase()} CONTENT**
 
-The content was created with proper field placement:
-- Root level fields: ${Object.keys(payload).filter(k => k !== 'data' && k !== 'meta').join(', ')}
-- Data object fields: ${payload.data ? Object.keys(payload.data).join(', ') : 'none'}
-- Meta fields: ${Object.keys(payload.meta).join(', ')}
-
 **Created Content:**
 ${JSON.stringify(response.data, null, 2)}`,
                     }],
             };
         }
         catch (error) {
+            // Pass through server errors directly - they contain the authoritative validation messages
             return {
                 content: [{
                         type: 'text',
-                        text: `Failed to create ${args.type}: ${this.formatError(error)}`,
+                        text: `Failed to create ${args.type}: ${this.formatError(error)}
+
+💡 **Field Placement Guidance:**
+- **Root Level**: title, reference, referenceType, body, organisation, meta
+- **Data Object**: Custom fields defined in content type's "definedFields" array
+- Use \`qik_get_content_definition\` to see the exact field structure for this content type`,
                     }],
                 isError: true,
             };
@@ -2391,6 +2445,180 @@ ${JSON.stringify(response.data, null, 2)}`,
             };
         }
     }
+    async getProfileTimeline(args) {
+        try {
+            const response = await this.axiosInstance.get(`/profile/${args.id}/timeline`);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `📅 **PROFILE TIMELINE FOR ${args.id}**
+
+This timeline provides chronological activity data including recent actions, content created, events attended, workflow activities, and other activity logs.
+
+**Timeline Data:**
+${JSON.stringify(response.data, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Failed to get profile timeline for ${args.id}: ${this.formatError(error)}`,
+                    }],
+                isError: true,
+            };
+        }
+    }
+    async getProfileInfo(args) {
+        const normalizedQuery = args.query.toLowerCase().trim();
+        // Analyze the query to determine intent
+        const timelineKeywords = [
+            'activity', 'timeline', 'been up to', 'doing', 'recent', 'lately',
+            'actions', 'history', 'events', 'workflow', 'progress'
+        ];
+        const basicInfoKeywords = [
+            'contact', 'email', 'phone', 'details', 'information', 'about'
+        ];
+        const wantsTimeline = args.includeTimeline !== undefined
+            ? args.includeTimeline
+            : timelineKeywords.some(keyword => normalizedQuery.includes(keyword));
+        const wantsBasicInfo = basicInfoKeywords.some(keyword => normalizedQuery.includes(keyword));
+        // If the intent is ambiguous, ask for clarification
+        if (!wantsTimeline && !wantsBasicInfo && args.includeTimeline === undefined) {
+            const personName = args.profileName || (args.profileId ? `person (ID: ${args.profileId})` : 'this person');
+            return {
+                content: [{
+                        type: 'text',
+                        text: `🤔 **CLARIFICATION NEEDED**
+
+You asked: "${args.query}"
+
+I can provide different types of information about ${personName}:
+
+**OPTION 1: Basic Profile Details** 📋
+- Contact information (email, phone)
+- Basic demographic data
+- Profile fields and custom data
+→ Use: \`qik_get_content\` or \`qik_list_profiles\`
+
+**OPTION 2: Activity Timeline** 📅  
+- Recent actions and activities
+- Content they've created or been involved with
+- Workflow progress and events attended
+- Much richer, more colorful activity data
+→ Use: \`qik_get_profile_timeline\`
+
+**Which would be more helpful for your needs?**
+
+To get both, you can:
+1. First get basic profile info with \`qik_list_profiles\` (search by name)
+2. Then get timeline data with \`qik_get_profile_timeline\` (using the profile ID)`,
+                    }],
+            };
+        }
+        let profileId = args.profileId;
+        // If no profile ID provided, try to find the profile by name
+        if (!profileId && args.profileName) {
+            try {
+                const searchResponse = await this.axiosInstance.post('/content/profile/list', {
+                    search: args.profileName,
+                    page: { size: 5, index: 1 },
+                });
+                if (searchResponse.data.items && searchResponse.data.items.length > 0) {
+                    if (searchResponse.data.items.length === 1) {
+                        profileId = searchResponse.data.items[0]._id;
+                    }
+                    else {
+                        // Multiple matches found
+                        const matches = searchResponse.data.items.map((p) => `- **${p._id}**: ${p.firstName} ${p.lastName} (${p.emails?.[0] || 'no email'})`).join('\n');
+                        return {
+                            content: [{
+                                    type: 'text',
+                                    text: `🔍 **MULTIPLE PROFILES FOUND**
+
+Found ${searchResponse.data.items.length} profiles matching "${args.profileName}":
+
+${matches}
+
+Please specify which profile you want by using the profile ID with \`qik_get_profile_timeline\` or \`qik_get_content\`.`,
+                                }],
+                        };
+                    }
+                }
+                else {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `❌ **PROFILE NOT FOUND**
+
+No profiles found matching "${args.profileName}". 
+
+Try:
+- Using \`qik_list_profiles\` with a broader search
+- Checking the spelling of the name
+- Using the exact profile ID if you have it`,
+                            }],
+                        isError: true,
+                    };
+                }
+            }
+            catch (error) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Failed to search for profile "${args.profileName}": ${this.formatError(error)}`,
+                        }],
+                    isError: true,
+                };
+            }
+        }
+        // Now we have a profile ID, get the appropriate information
+        if (wantsTimeline && profileId) {
+            return await this.getProfileTimeline({ id: profileId });
+        }
+        else if (profileId) {
+            // Get basic profile information
+            try {
+                const response = await this.axiosInstance.get(`/content/${profileId}`);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `👤 **PROFILE INFORMATION**
+
+**Basic Details:**
+${JSON.stringify(response.data, null, 2)}
+
+💡 **Want more activity details?** Use \`qik_get_profile_timeline\` with ID: ${profileId} to see their recent activities, workflow progress, and timeline data.`,
+                        }],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `Failed to get profile information for ${profileId}: ${this.formatError(error)}`,
+                        }],
+                    isError: true,
+                };
+            }
+        }
+        else {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `❌ **MISSING PROFILE IDENTIFIER**
+
+To get profile information, I need either:
+- **profileId**: The exact profile ID
+- **profileName**: The person's name to search for
+
+Please provide one of these and try again.`,
+                    }],
+                isError: true,
+            };
+        }
+    }
     async getForm(args) {
         try {
             const response = await this.axiosInstance.get(`/form/${args.id}`);
@@ -2535,6 +2763,380 @@ ${JSON.stringify(response.data, null, 2)}`,
             };
         }
     }
+    // Documentation-focused tool implementations
+    async getDocumentation(args) {
+        try {
+            const documentation = QikDocumentationHelper.getTopicDocumentation(args.topic);
+            if (!documentation) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `❌ **DOCUMENTATION NOT FOUND**
+
+No documentation found for topic: "${args.topic}"
+
+**Available topics:**
+- authentication (token types, methods, error codes)
+- endpoints (API endpoint documentation)
+- contentTypes (content type specific guidance)
+- filterSyntax (filter operators and comparators)
+- concepts (key concepts like field placement, scopes, workflows)
+- examples (code examples for common use cases)
+- troubleshooting (error resolution guides)
+
+**Example usage:**
+- \`qik_get_documentation\` with topic: "concepts.field_placement"
+- \`qik_get_documentation\` with topic: "authentication.tokenTypes"
+- \`qik_get_documentation\` with topic: "troubleshooting.field_placement_errors"`,
+                        }],
+                    isError: true,
+                };
+            }
+            let result = `📖 **DOCUMENTATION: ${args.topic.toUpperCase()}**\n\n`;
+            if (args.subtopic && documentation[args.subtopic]) {
+                result += `**Subtopic: ${args.subtopic}**\n\n`;
+                result += JSON.stringify(documentation[args.subtopic], null, 2);
+            }
+            else {
+                result += JSON.stringify(documentation, null, 2);
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: result,
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Failed to get documentation for ${args.topic}: ${this.formatError(error)}`,
+                    }],
+                isError: true,
+            };
+        }
+    }
+    async searchDocumentation(args) {
+        try {
+            const results = QikDocumentationHelper.searchDocumentation(args.query);
+            const limit = args.limit || 10;
+            const limitedResults = results.slice(0, limit);
+            if (limitedResults.length === 0) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🔍 **NO DOCUMENTATION FOUND**
+
+No documentation found for query: "${args.query}"
+
+**Try searching for:**
+- "field placement" - for field structure guidance
+- "authentication" - for token and auth help
+- "filter" - for filtering and query syntax
+- "workflow" - for workflow system concepts
+- "birthday" - for anniversary/birthday queries
+- "scope" - for permission and scope guidance
+- "troubleshooting" - for error resolution
+
+**Available documentation sections:**
+- Authentication & Tokens
+- API Endpoints
+- Content Types
+- Filter Syntax
+- Core Concepts
+- Code Examples
+- Troubleshooting Guides`,
+                        }],
+                };
+            }
+            let result = `🔍 **DOCUMENTATION SEARCH RESULTS**\n\n`;
+            result += `Found ${limitedResults.length} results for "${args.query}":\n\n`;
+            limitedResults.forEach((item, index) => {
+                result += `**${index + 1}. ${item.path}** (${item.type})\n`;
+                if (typeof item.content === 'string') {
+                    const preview = item.content.length > 200
+                        ? item.content.substring(0, 200) + '...'
+                        : item.content;
+                    result += `${preview}\n\n`;
+                }
+                else {
+                    result += `${JSON.stringify(item.content).substring(0, 200)}...\n\n`;
+                }
+            });
+            result += `💡 **Need more specific help?** Use \`qik_get_documentation\` with a specific topic for detailed information.`;
+            return {
+                content: [{
+                        type: 'text',
+                        text: result,
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Failed to search documentation: ${this.formatError(error)}`,
+                    }],
+                isError: true,
+            };
+        }
+    }
+    async getTroubleshooting(args) {
+        try {
+            let troubleshootingInfo;
+            if (args.issueType) {
+                // Get specific issue type
+                troubleshootingInfo = QIK_DOCUMENTATION.troubleshooting[args.issueType];
+                if (troubleshootingInfo) {
+                    troubleshootingInfo = { issue: args.issueType, ...troubleshootingInfo };
+                }
+            }
+            else {
+                // Auto-detect issue type from error message
+                troubleshootingInfo = QikDocumentationHelper.getTroubleshootingInfo(args.errorMessage);
+            }
+            if (!troubleshootingInfo) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `🔧 **NO SPECIFIC TROUBLESHOOTING FOUND**
+
+I couldn't find specific troubleshooting information for: "${args.errorMessage}"
+
+**Available troubleshooting categories:**
+- **field_placement_errors**: Field structure and placement issues
+- **authentication_failures**: Token and permission problems
+- **filter_syntax_errors**: Query and filter syntax issues
+- **scope_permission_issues**: Access and permission problems
+- **workflow_confusion**: Workflow definition vs card confusion
+- **date_handling_issues**: Date format and timezone problems
+- **performance_issues**: Slow queries and optimization
+
+**General troubleshooting steps:**
+1. Check the error message for specific field names or codes
+2. Verify your access token and permissions
+3. Ensure proper field placement (root vs data object)
+4. Validate filter syntax and comparators
+5. Check scope permissions and hierarchy
+
+**Need more help?** Try:
+- \`qik_search_documentation\` with keywords from your error
+- \`qik_get_documentation\` with topic: "troubleshooting"
+- \`qik_validate_field_placement\` for content creation issues`,
+                        }],
+                };
+            }
+            let result = `🔧 **TROUBLESHOOTING: ${troubleshootingInfo.issue.toUpperCase().replace(/_/g, ' ')}**\n\n`;
+            result += `**Your Error:** "${args.errorMessage}"\n\n`;
+            if (troubleshootingInfo.symptoms && troubleshootingInfo.symptoms.length > 0) {
+                result += `**Common Symptoms:**\n`;
+                result += troubleshootingInfo.symptoms.map((s) => `- ${s}`).join('\n');
+                result += '\n\n';
+            }
+            if (troubleshootingInfo.causes && troubleshootingInfo.causes.length > 0) {
+                result += `**Likely Causes:**\n`;
+                result += troubleshootingInfo.causes.map((c) => `- ${c}`).join('\n');
+                result += '\n\n';
+            }
+            if (troubleshootingInfo.solutions && troubleshootingInfo.solutions.length > 0) {
+                result += `**Solutions:**\n`;
+                result += troubleshootingInfo.solutions.map((s) => `- ${s}`).join('\n');
+                result += '\n\n';
+            }
+            if (troubleshootingInfo.prevention && troubleshootingInfo.prevention.length > 0) {
+                result += `**Prevention:**\n`;
+                result += troubleshootingInfo.prevention.map((p) => `- ${p}`).join('\n');
+                result += '\n\n';
+            }
+            if (troubleshootingInfo.relatedIssues && troubleshootingInfo.relatedIssues.length > 0) {
+                result += `**Related Issues:**\n`;
+                result += troubleshootingInfo.relatedIssues.map((r) => `- ${r}`).join('\n');
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: result,
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Failed to get troubleshooting information: ${this.formatError(error)}`,
+                    }],
+                isError: true,
+            };
+        }
+    }
+    async getExamples(args) {
+        try {
+            if (args.category === 'all') {
+                let result = `💡 **ALL CODE EXAMPLES**\n\n`;
+                for (const [category, examples] of Object.entries(QIK_DOCUMENTATION.examples)) {
+                    result += `## ${category.toUpperCase()}\n\n`;
+                    for (const [exampleKey, example] of Object.entries(examples)) {
+                        const typedExample = example;
+                        result += `### ${typedExample.title}\n`;
+                        result += `${typedExample.description}\n\n`;
+                        result += `\`\`\`json\n${JSON.stringify(typedExample.code, null, 2)}\n\`\`\`\n\n`;
+                        result += `**Explanation:** ${typedExample.explanation}\n\n`;
+                        if (typedExample.variations && typedExample.variations.length > 0) {
+                            result += `**Variations:**\n`;
+                            typedExample.variations.forEach((variation) => {
+                                result += `- ${variation.description}\n`;
+                                result += `  \`\`\`json\n  ${JSON.stringify(variation.code, null, 2)}\n  \`\`\`\n`;
+                            });
+                            result += '\n';
+                        }
+                    }
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: result,
+                        }],
+                };
+            }
+            const examples = QikDocumentationHelper.getExamples(args.category, args.example);
+            if (!examples) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `💡 **NO EXAMPLES FOUND**
+
+No examples found for category: "${args.category}"
+
+**Available example categories:**
+- **authentication**: Token usage and auth examples
+- **content_creation**: Creating different content types
+- **filtering**: Advanced filtering and search examples
+
+**Example usage:**
+- \`qik_get_examples\` with category: "authentication"
+- \`qik_get_examples\` with category: "filtering" and example: "birthday_search"
+- \`qik_get_examples\` with category: "all" (shows all examples)`,
+                        }],
+                    isError: true,
+                };
+            }
+            let result = `💡 **CODE EXAMPLES: ${args.category.toUpperCase()}**\n\n`;
+            if (args.example && examples[args.example]) {
+                // Show specific example
+                const example = examples[args.example];
+                result += `### ${example.title}\n`;
+                result += `${example.description}\n\n`;
+                result += `\`\`\`json\n${JSON.stringify(example.code, null, 2)}\n\`\`\`\n\n`;
+                result += `**Explanation:** ${example.explanation}\n\n`;
+                if (example.variations && example.variations.length > 0) {
+                    result += `**Variations:**\n`;
+                    example.variations.forEach((variation) => {
+                        result += `- ${variation.description}\n`;
+                        result += `  \`\`\`json\n  ${JSON.stringify(variation.code, null, 2)}\n  \`\`\`\n`;
+                    });
+                }
+            }
+            else {
+                // Show all examples in category
+                for (const [exampleKey, example] of Object.entries(examples)) {
+                    const typedExample = example;
+                    result += `### ${typedExample.title}\n`;
+                    result += `${typedExample.description}\n\n`;
+                    result += `\`\`\`json\n${JSON.stringify(typedExample.code, null, 2)}\n\`\`\`\n\n`;
+                    result += `**Explanation:** ${typedExample.explanation}\n\n`;
+                    if (typedExample.variations && typedExample.variations.length > 0) {
+                        result += `**Variations:**\n`;
+                        typedExample.variations.forEach((variation) => {
+                            result += `- ${variation.description}\n`;
+                            result += `  \`\`\`json\n  ${JSON.stringify(variation.code, null, 2)}\n  \`\`\`\n`;
+                        });
+                        result += '\n';
+                    }
+                }
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: result,
+                    }],
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Failed to get examples: ${this.formatError(error)}`,
+                    }],
+                isError: true,
+            };
+        }
+    }
+    async validateFieldPlacement(args) {
+        try {
+            const validation = this.validateContentType(args.contentType);
+            if (!validation.valid) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: validation.error,
+                        }],
+                    isError: true,
+                };
+            }
+            // Simplified validation using documentation helper only
+            const docValidation = QikDocumentationHelper.validateFieldPlacement(args.contentType, args.payload);
+            let result = `✅ **FIELD PLACEMENT VALIDATION: ${args.contentType.toUpperCase()}**\n\n`;
+            if (docValidation.valid) {
+                result += `🎉 **VALIDATION PASSED**\n\n`;
+                result += `Your payload has correct field placement!\n\n`;
+                result += `**Field Analysis:**\n`;
+                result += `- Root level fields: ${Object.keys(args.payload).filter(k => k !== 'data' && k !== 'meta').join(', ') || 'none'}\n`;
+                result += `- Data object fields: ${args.payload.data ? Object.keys(args.payload.data).join(', ') : 'none'}\n`;
+                result += `- Meta fields: ${args.payload.meta ? Object.keys(args.payload.meta).join(', ') : 'none'}\n\n`;
+            }
+            else {
+                result += `❌ **VALIDATION FAILED**\n\n`;
+                if (docValidation.errors && docValidation.errors.length > 0) {
+                    result += `**Errors Found:**\n`;
+                    docValidation.errors.forEach(error => {
+                        result += `- ${error}\n`;
+                    });
+                    result += '\n';
+                }
+                result += `**General Field Placement Rules:**\n`;
+                result += `- **Root Level**: title, reference, referenceType, body, organisation, meta\n`;
+                result += `- **Data Object**: Custom fields defined in content type's "definedFields" array\n`;
+                result += `- Use \`qik_get_content_definition\` to see the exact field structure for this content type\n\n`;
+                result += `**Correct Structure Example:**\n`;
+                result += `\`\`\`json\n`;
+                result += `{\n`;
+                result += `  "type": "${args.contentType}",\n`;
+                result += `  "title": "Your Title Here",\n`;
+                result += `  "meta": { "scopes": ["scope-id-here"] },\n`;
+                result += `  "data": {\n`;
+                result += `    "customField": "value"\n`;
+                result += `  }\n`;
+                result += `}\n\`\`\`\n`;
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: result,
+                    }],
+                isError: !docValidation.valid,
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Failed to validate field placement: ${this.formatError(error)}`,
+                    }],
+                isError: true,
+            };
+        }
+    }
     async run() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);