Optimizely DXP MCP Server

Instructions

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;
  }

• lib/tools/ai-guidance-tools.ts:83-132 (helper)

  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);
          }
      }

• lib/tools/ai-guidance-tools.ts:137-180 (helper)

  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'
  },