@qikdev/mcp 6.6.6 → 6.6.8

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,369 @@ export class QikMCPServer {
     getMinimumArrayLength(field) {
         return this.isFieldArray(field) ? (field.minimum || 0) : 0;
     }
+    /**
+     * Analyzes field placement rules directly from glossary structure
+     * This is the authoritative source for field placement decisions
+     */
+    analyzeFieldPlacementFromGlossary(contentType) {
+        const typeInfo = this.glossary[contentType];
+        if (!typeInfo) {
+            throw new Error(`Content type ${contentType} not found in glossary`);
+        }
+        // Check if this is a custom definition (has definesType)
+        const isCustomDefinition = !!typeInfo.definesType;
+        const baseType = typeInfo.definesType || null;
+        // Extract fields from the glossary structure
+        const fields = typeInfo.fields || [];
+        const definedFields = typeInfo.definedFields || [];
+        // Create widget mapping for enhanced validation
+        const widgetFields = new Map();
+        // Process fields for widget information
+        const processFieldsForWidgets = (fieldList) => {
+            for (const field of fieldList) {
+                if (field.widget) {
+                    widgetFields.set(field.key, field.widget);
+                }
+                // Process nested fields in groups
+                if (field.fields && Array.isArray(field.fields)) {
+                    processFieldsForWidgets(field.fields);
+                }
+            }
+        };
+        processFieldsForWidgets(fields);
+        processFieldsForWidgets(definedFields);
+        return {
+            rootLevelFields: new Set(fields.map(f => f.key)),
+            dataObjectFields: new Set(definedFields.map((f) => f.key)),
+            baseType,
+            isCustomDefinition,
+            allFields: fields,
+            allDefinedFields: definedFields,
+            widgetFields
+        };
+    }
+    /**
+     * Validates field placement based on glossary structure
+     */
+    validateFieldPlacementFromGlossary(args, contentType) {
+        const analysis = this.analyzeFieldPlacementFromGlossary(contentType);
+        const errors = [];
+        const warnings = [];
+        // Check for fields in data object that should be at root level
+        if (args.data && typeof args.data === 'object') {
+            for (const [key, value] of Object.entries(args.data)) {
+                if (analysis.rootLevelFields.has(key)) {
+                    errors.push(`Field "${key}" is defined in glossary "fields" array and must be at ROOT LEVEL, not in data object`);
+                }
+                // Widget validation for data object fields
+                if (analysis.widgetFields.has(key)) {
+                    const widgetValidation = this.validateWidgetValue(key, value, analysis.widgetFields.get(key));
+                    if (!widgetValidation.valid) {
+                        errors.push(...widgetValidation.errors);
+                    }
+                    if (widgetValidation.warnings.length > 0) {
+                        warnings.push(...widgetValidation.warnings);
+                    }
+                }
+            }
+        }
+        // Check for fields at root level that should be in data object
+        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 (analysis.dataObjectFields.has(key)) {
+                    errors.push(`Field "${key}" is defined in glossary "definedFields" array and must be in DATA OBJECT, not at root level`);
+                }
+                // Widget validation for root level fields
+                if (analysis.widgetFields.has(key)) {
+                    const widgetValidation = this.validateWidgetValue(key, value, analysis.widgetFields.get(key));
+                    if (!widgetValidation.valid) {
+                        errors.push(...widgetValidation.errors);
+                    }
+                    if (widgetValidation.warnings.length > 0) {
+                        warnings.push(...widgetValidation.warnings);
+                    }
+                }
+            }
+        }
+        return { valid: errors.length === 0, errors, warnings, analysis };
+    }
+    /**
+     * Automatically restructures payload based on glossary field placement rules
+     */
+    restructurePayloadFromGlossary(args, contentType) {
+        const analysis = this.analyzeFieldPlacementFromGlossary(contentType);
+        const payload = {};
+        // Always include title if provided
+        if (args.title)
+            payload.title = args.title;
+        // Handle meta separately (always root level)
+        if (args.meta)
+            payload.meta = args.meta;
+        // Handle standard root-level fields
+        const standardRootFields = ['reference', 'referenceType', 'body', 'organisation'];
+        for (const fieldKey of standardRootFields) {
+            if (args[fieldKey] !== undefined) {
+                payload[fieldKey] = args[fieldKey];
+            }
+        }
+        // Process provided data and separate into correct locations
+        const rootData = {};
+        const dataObjectData = {};
+        if (args.data && typeof args.data === 'object') {
+            for (const [key, value] of Object.entries(args.data)) {
+                if (analysis.rootLevelFields.has(key)) {
+                    rootData[key] = value; // Move to root level
+                }
+                else {
+                    dataObjectData[key] = value; // Keep in data object
+                }
+            }
+        }
+        // Add any root-level fields that were incorrectly placed at top level
+        for (const [key, value] of Object.entries(args)) {
+            if (key !== 'type' && key !== 'title' && key !== 'meta' && key !== 'data' &&
+                !standardRootFields.includes(key)) {
+                if (analysis.dataObjectFields.has(key)) {
+                    dataObjectData[key] = value; // Move to data object
+                }
+                else if (analysis.rootLevelFields.has(key)) {
+                    rootData[key] = value; // Keep at root level
+                }
+            }
+        }
+        // Add root level fields to payload
+        Object.assign(payload, rootData);
+        // Add data object if there are any data fields
+        if (Object.keys(dataObjectData).length > 0) {
+            payload.data = dataObjectData;
+        }
+        return payload;
+    }
+    /**
+     * Generates comprehensive error message based on glossary structure with widget guidance
+     */
+    generateFieldPlacementErrorFromGlossary(contentType, errors, warnings = []) {
+        const analysis = this.analyzeFieldPlacementFromGlossary(contentType);
+        const rootFieldsList = Array.from(analysis.rootLevelFields).join(', ');
+        const dataFieldsList = Array.from(analysis.dataObjectFields).join(', ');
+        let errorMessage = `🚫 **FIELD PLACEMENT ERRORS for ${contentType.toUpperCase()}**
+
+${errors.join('\n')}`;
+        if (warnings.length > 0) {
+            errorMessage += `\n\n⚠️ **WARNINGS:**\n${warnings.join('\n')}`;
+        }
+        errorMessage += `\n\n**ACCORDING TO GLOSSARY DEFINITION:**
+${analysis.isCustomDefinition ? `- Extends: ${analysis.baseType}` : '- Primitive type'}
+- Total fields in "fields" array: ${analysis.allFields.length}
+- Total fields in "definedFields" array: ${analysis.allDefinedFields.length}`;
+        // Add widget information if present
+        if (analysis.widgetFields.size > 0) {
+            errorMessage += `\n- Widget types detected: ${analysis.widgetFields.size} fields with specific widgets`;
+            const widgetInfo = [];
+            for (const [fieldKey, widgetType] of analysis.widgetFields.entries()) {
+                if (widgetType === 'dateobject') {
+                    widgetInfo.push(`  • ${fieldKey}: dateobject widget (requires {hour, minute, day, month, year} format)`);
+                }
+                else {
+                    widgetInfo.push(`  • ${fieldKey}: ${widgetType} widget`);
+                }
+            }
+            if (widgetInfo.length > 0) {
+                errorMessage += `\n${widgetInfo.join('\n')}`;
+            }
+        }
+        errorMessage += `\n\n**ROOT LEVEL FIELDS (from glossary "fields" array):**
+${rootFieldsList || 'none defined'}
+
+**DATA OBJECT FIELDS (from glossary "definedFields" array):**
+${dataFieldsList || 'none defined'}
+
+**CORRECT STRUCTURE:**
+\`\`\`json
+{
+  "type": "${contentType}",
+  "title": "Your Title Here",`;
+        // Add sample root level fields with widget-aware examples
+        const rootFields = Array.from(analysis.rootLevelFields).filter(f => f !== 'title' && f !== '_id' && f !== 'meta');
+        if (rootFields.length > 0) {
+            rootFields.slice(0, 2).forEach(fieldKey => {
+                const widgetType = analysis.widgetFields.get(fieldKey);
+                let exampleValue = '"value"';
+                if (widgetType === 'dateobject') {
+                    exampleValue = '{"hour": 14, "minute": 30, "day": 15, "month": 1, "year": 2025}';
+                }
+                else if (widgetType === 'date') {
+                    exampleValue = '"2025-01-15"';
+                }
+                else if (widgetType === 'time') {
+                    exampleValue = '"14:30"';
+                }
+                else if (widgetType === 'datetime') {
+                    exampleValue = '"2025-01-15T14:30:00Z"';
+                }
+                errorMessage += `\n  "${fieldKey}": ${exampleValue},`;
+            });
+        }
+        errorMessage += `\n  "meta": { "scopes": ["scope-id-here"] }`;
+        // Add data object with widget-aware examples
+        if (analysis.dataObjectFields.size > 0) {
+            errorMessage += `,\n  "data": {`;
+            const dataFields = Array.from(analysis.dataObjectFields).slice(0, 3);
+            dataFields.forEach((fieldKey, index) => {
+                const widgetType = analysis.widgetFields.get(fieldKey);
+                let exampleValue = '"value"';
+                if (widgetType === 'dateobject') {
+                    exampleValue = '{"hour": 9, "minute": 0, "day": 22, "month": 3, "year": 2024}';
+                }
+                else if (widgetType === 'date') {
+                    exampleValue = '"2024-03-22"';
+                }
+                else if (widgetType === 'time') {
+                    exampleValue = '"09:00"';
+                }
+                else if (widgetType === 'datetime') {
+                    exampleValue = '"2024-03-22T09:00:00Z"';
+                }
+                const comma = index < dataFields.length - 1 ? ',' : '';
+                errorMessage += `\n    "${fieldKey}": ${exampleValue}${comma}`;
+            });
+            errorMessage += `\n  }`;
+        }
+        errorMessage += `\n}
+\`\`\`
+
+**FIELD PLACEMENT RULE:**
+- Fields in glossary "fields" array → ROOT LEVEL
+- Fields in glossary "definedFields" array → DATA OBJECT`;
+        // Add widget-specific guidance
+        if (analysis.widgetFields.size > 0) {
+            errorMessage += `\n\n**WIDGET-SPECIFIC GUIDANCE:**\n`;
+            for (const [fieldKey, widgetType] of analysis.widgetFields.entries()) {
+                if (widgetType === 'dateobject') {
+                    errorMessage += `- **${fieldKey}** (dateobject): Use format {"hour": 14, "minute": 30, "day": 15, "month": 1, "year": 2025}\n`;
+                }
+                else if (widgetType === 'date') {
+                    errorMessage += `- **${fieldKey}** (date): Use ISO date format "2025-01-15"\n`;
+                }
+                else if (widgetType === 'time') {
+                    errorMessage += `- **${fieldKey}** (time): Use time format "14:30"\n`;
+                }
+                else if (widgetType === 'datetime') {
+                    errorMessage += `- **${fieldKey}** (datetime): Use ISO datetime format "2025-01-15T14:30:00Z"\n`;
+                }
+            }
+        }
+        return errorMessage;
+    }
+    /**
+     * 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) {
@@ -1638,6 +2002,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 +2267,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,164 +2532,55 @@ ${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];
+        // Use the new glossary-driven field placement validation
+        try {
+            const fieldValidation = this.validateFieldPlacementFromGlossary(args, args.type);
+            // If there are field placement errors, return detailed guidance
+            if (!fieldValidation.valid) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: this.generateFieldPlacementErrorFromGlossary(args.type, fieldValidation.errors),
+                        }],
+                    isError: true,
+                };
             }
-        }
-        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;
+            // Automatically restructure the payload based on glossary rules
+            const payload = this.restructurePayloadFromGlossary(args, args.type);
+            // Handle scope inheritance for comment types
+            const analysis = fieldValidation.analysis;
+            const isCommentType = analysis.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) {
+                        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:
+The content was created using glossary-driven 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(', ')}
+- Meta fields: ${payload.meta ? Object.keys(payload.meta).join(', ') : 'none'}
+
+**Field Placement Analysis:**
+- Content type: ${analysis.isCustomDefinition ? `Custom definition extending ${analysis.baseType}` : 'Primitive type'}
+- Root level fields from glossary: ${Array.from(analysis.rootLevelFields).join(', ')}
+- Data object fields from glossary: ${Array.from(analysis.dataObjectFields).join(', ')}
 
 **Created Content:**
 ${JSON.stringify(response.data, null, 2)}`,
@@ -2391,6 +2690,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 +3008,395 @@ ${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,
+                };
+            }
+            // Use both the documentation helper and glossary-driven validation
+            const docValidation = QikDocumentationHelper.validateFieldPlacement(args.contentType, args.payload);
+            const glossaryValidation = this.validateFieldPlacementFromGlossary(args.payload, args.contentType);
+            let result = `✅ **FIELD PLACEMENT VALIDATION: ${args.contentType.toUpperCase()}**\n\n`;
+            if (glossaryValidation.valid && docValidation.valid) {
+                result += `🎉 **VALIDATION PASSED**\n\n`;
+                result += `Your payload has correct field placement!\n\n`;
+                const analysis = glossaryValidation.analysis;
+                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`;
+                result += `**Glossary Structure:**\n`;
+                result += `- Expected root fields: ${Array.from(analysis.rootLevelFields).join(', ') || 'none'}\n`;
+                result += `- Expected data fields: ${Array.from(analysis.dataObjectFields).join(', ') || 'none'}\n`;
+            }
+            else {
+                result += `❌ **VALIDATION FAILED**\n\n`;
+                const allErrors = [...(docValidation.errors || []), ...(glossaryValidation.errors || [])];
+                if (allErrors.length > 0) {
+                    result += `**Errors Found:**\n`;
+                    allErrors.forEach(error => {
+                        result += `- ${error}\n`;
+                    });
+                    result += '\n';
+                }
+                if (glossaryValidation.analysis) {
+                    const analysis = glossaryValidation.analysis;
+                    result += `**Correct Structure:**\n`;
+                    result += `\`\`\`json\n`;
+                    result += `{\n`;
+                    result += `  "type": "${args.contentType}",\n`;
+                    result += `  "title": "Your Title Here",\n`;
+                    const rootFields = Array.from(analysis.rootLevelFields).filter(f => f !== 'title' && f !== '_id' && f !== 'meta');
+                    if (rootFields.length > 0) {
+                        rootFields.slice(0, 2).forEach(field => {
+                            result += `  "${field}": "value",\n`;
+                        });
+                    }
+                    result += `  "meta": { "scopes": ["scope-id-here"] }`;
+                    if (analysis.dataObjectFields.size > 0) {
+                        result += `,\n  "data": {\n`;
+                        Array.from(analysis.dataObjectFields).slice(0, 3).forEach((field, index, arr) => {
+                            result += `    "${field}": "value"${index < arr.length - 1 ? ',' : ''}\n`;
+                        });
+                        result += `  }`;
+                    }
+                    result += `\n}\n\`\`\`\n`;
+                }
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: result,
+                    }],
+                isError: !glossaryValidation.valid || !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);