get_ai_guidance
Analyzes natural language tasks to recommend appropriate Optimizely DXP MCP tools with suggested parameters, helping users select the right tool for their workflow.
Instructions
🤖 Get AI-powered tool recommendations for natural language tasks. ANALYSIS: <1s. Analyzes task description and suggests which MCP tool to use with recommended parameters. Use when uncertain which tool fits your workflow. Returns recommended tool name, suggested parameters, and reasoning. Required: taskDescription (natural language).
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| topic | No | Specific topic to get guidance on (e.g., "confirmation", "downloads", "errors", "parameters") |
Implementation Reference
- lib/tools/ai-guidance-tools.ts:44-78 (handler)The core handler function for the 'get_ai_guidance' MCP tool. Handles requests for AI guidance by topic, reading from AI_CLIENT_GUIDE.md or falling back to inline guidance, with special handling for database export workflows.static async getAIGuidance(args: AIGuidanceArgs = {}): Promise<any> { try { const { topic } = args; // Check for database export workflow request if (topic && topic.toLowerCase().includes('database') && topic.toLowerCase().includes('export')) { return await this.getDatabaseExportWorkflow(args); } // Read the AI_CLIENT_GUIDE.md file const guidePath = path.join(__dirname, '..', '..', 'AI_CLIENT_GUIDE.md'); let guideContent = ''; try { guideContent = fs.readFileSync(guidePath, 'utf8'); } catch (error) { // If file doesn't exist, provide inline guidance guideContent = this.getInlineGuidance(); } // If specific topic requested, extract relevant section if (topic) { const section = this.extractSection(guideContent, topic); if (section) { return ResponseBuilder.success(section); } } // Return full guide return ResponseBuilder.success(guideContent); } catch (error: any) { return ResponseBuilder.error('Failed to retrieve AI guidance', error.message); } }
- lib/tools/ai-guidance-tools.ts:14-20 (schema)TypeScript interface defining the input schema/arguments for the get_ai_guidance tool.interface AIGuidanceArgs { topic?: string; stage?: string; exportId?: string; environment?: string; databaseName?: string; }
- Helper method invoked by the handler for database export-specific AI guidance, using prompt messages from DatabaseExportPrompts.static async getDatabaseExportWorkflow(args: AIGuidanceArgs = {}): Promise<any> { try { const { exportId, environment = 'Production', databaseName = 'epicms' } = args; // Use the new unified prompt system try { // Get the prompt messages based on stage const promptArgs: any = { environment, databaseName }; if (exportId) { promptArgs.exportId = exportId; } const messages = DatabaseExportPrompts.getPromptMessages('export-database', promptArgs) as PromptMessage[]; // Extract the assistant's guidance message const assistantMessage = messages.find(m => m.role === 'assistant'); const workflowGuide = assistantMessage ? assistantMessage.content.text : 'Failed to get workflow guidance'; return ResponseBuilder.success(`${workflowGuide} --- ## 🔗 RELATED GUIDANCE For additional context: - Use \`get_ai_guidance\` for general AI interaction rules - Use \`get_ai_guidance({ topic: "confirmation" })\` for confirmation patterns - Use \`get_ai_guidance({ topic: "errors" })\` for error handling guidance ## 🎯 WORKFLOW STAGES You can get stage-specific guidance: - \`get_ai_guidance({ topic: "database export", stage: "start" })\` - Initial preview phase - \`get_ai_guidance({ topic: "database export", stage: "monitoring", exportId: "xxx" })\` - Monitoring phase - \`get_ai_guidance({ topic: "database export", stage: "completed", exportId: "xxx" })\` - Download phase - \`get_ai_guidance({ topic: "database export", stage: "error" })\` - Error handling **This is your complete guide to transparent database export workflows!**`); } catch (promptError: any) { throw new Error(promptError.message || 'Failed to get database export workflow'); } } catch (error: any) { return ResponseBuilder.error('Failed to retrieve database export workflow', error.message); } }
- Static helper providing comprehensive inline markdown guidance for AI clients when external guide file is unavailable.static getInlineGuidance(): string { return `# AI Client Integration Guide - Quick Reference ## 🚨 CRITICAL RULES - VIOLATIONS WILL BE REPORTED ### 🛑 ABSOLUTE PROHIBITION: Auto-Confirming Operations - **NEVER** automatically set \`skipConfirmation: true\` after seeing a preview - **NEVER** proceed with download after seeing "AWAITING USER CONFIRMATION" - **ALWAYS** STOP and wait when you see "WAITING FOR USER CONFIRMATION" - **VIOLATION**: If you call download with skipConfirmation after preview = PROTOCOL VIOLATION ### 🛑 DATABASE EXPORT RULES - NEVER AUTO-ACCEPT - **NEVER** set \`autoDownload: true\` unless user explicitly requests - **ALWAYS** use \`previewOnly: true\` FIRST to show what will happen - **ALWAYS** wait for explicit user confirmation before actual export - **IMPORTANT**: When user chooses "Option 2" or "create fresh export" after seeing existing backup, USE \`forceNew: true\` - **CRITICAL**: After export completes, NEVER call db_export again to download - that creates a NEW export! - **PREFERRED**: Use \`monitor: false\` to disable automatic monitoring - makes debugging easier - **VIOLATION**: Auto-adding autoDownload without user request = PROTOCOL VIOLATION - **VIOLATION**: Calling db_export without previewOnly first = PROTOCOL VIOLATION - **VIOLATION**: Calling db_export to download completed export = CREATES DUPLICATE! ### ⚠️ When You See "AWAITING USER CONFIRMATION" **YOU MUST:** 1. STOP immediately 2. DO NOT call the download tool again 3. DO NOT add skipConfirmation: true 4. WAIT for the human to explicitly say "yes", "proceed", "confirm", etc. ### Confirmation Flow (MANDATORY) 1. User requests download 2. AI calls tool with previewOnly: true OR without skipConfirmation 3. MCP shows preview with "AWAITING USER CONFIRMATION" 4. **AI MUST STOP HERE** ← CRITICAL 5. User explicitly confirms (e.g., "yes", "proceed", "download") 6. ONLY THEN: AI calls tool WITH skipConfirmation: true ### Common Mistakes to Avoid - ❌ Auto-confirming after CONFIRMATION_REQUIRED error - ❌ Setting skipConfirmation: true without user confirmation - ❌ Ignoring time parameters (using days when user said hours) - ❌ Downloading without showing preview first Remember: Always prioritize user control over automation speed.`;
- lib/utils/tool-availability-matrix.ts:63-67 (registration)Registration of the 'get_ai_guidance' tool in the availability matrix, marking it available across all hosting types in the 'Help & Support' category.'get_ai_guidance': { hostingTypes: ['dxp-paas', 'dxp-saas', 'self-hosted', 'unknown'], category: 'Help & Support', description: 'Get AI-specific guidance for using this MCP server' },