Optimizely DXP MCP Server

Instructions

Implementation Reference

• lib/tools/project-switch-tool.ts:127-261 (handler)

  Main handler function that executes the switch_project tool logic: validates input, lists projects, calls ProjectTools.switchProject, handles errors with fuzzy matching suggestions, and returns structured success/error responses.
  static async handleSwitchProject(args: ProjectSwitchArgs): Promise<any> { const { projectName } = args; if (!projectName) { return ResponseBuilder.error( '❌ Project name is required', { error: 'Missing projectName parameter' } ); } try { // DXP-36: Improved error handling for project switching // First, try to get available projects with error handling let projects; try { projects = ProjectTools.getConfiguredProjects(); } catch (configError: any) { return ResponseBuilder.error( '❌ **Configuration Error**\n\n' + 'Unable to load project configurations. This might be due to:\n' + '• Malformed environment variables\n' + '• Invalid project configuration format\n' + '• Missing required configuration fields\n\n' + `**Error details**: ${configError.message}\n\n` + '💡 **Next steps**:\n' + '1. Check your environment variables for proper format\n' + '2. Use `list_projects` to see current configuration status\n' + '3. Refer to setup documentation for correct format', { error: 'Configuration load failed', details: configError.message, requestedProject: projectName } ); } if (!projects || projects.length === 0) { return ResponseBuilder.error( '❌ **No Projects Configured**\n\n' + 'No projects are currently configured in your environment.\n\n' + '💡 **To configure a project**, add an environment variable like:\n' + '```\n' + 'MYPROJECT="id=your-project-id;key=your-api-key;secret=your-secret"\n' + '```\n\n' + 'Or see the setup guide for detailed instructions.', { error: 'No projects configured', requestedProject: projectName, availableProjects: [] } ); } // Attempt to switch project const result = ProjectTools.switchProject(projectName); if (!result.success) { // DXP-36: Enhanced error message with fuzzy matching and better suggestions const projectNames = projects.map((p: any) => p.name).filter(Boolean); // Find closest matches using simple string similarity const closeMatches = this.findSimilarProjectNames(projectName, projectNames); let errorMessage = `❌ **Project "${projectName}" not found**\n\n`; if (closeMatches.length > 0) { errorMessage += `🔍 **Did you mean?**\n${closeMatches.map(name => ` • ${name}`).join('\n')}\n\n`; } errorMessage += `📋 **Available projects** (${projectNames.length}):\n`; if (projectNames.length <= 10) { errorMessage += `${projectNames.map((n: string) => ` • ${n}`).join('\n')}\n\n`; } else { errorMessage += `${projectNames.slice(0, 8).map((n: string) => ` • ${n}`).join('\n')}\n • ... and ${projectNames.length - 8} more\n\n`; errorMessage += `💡 Use \`list_projects\` to see all projects\n\n`; } errorMessage += `💡 **Tips**:\n`; errorMessage += `• Project names are case-insensitive\n`; errorMessage += `• You can use partial names if unique\n`; errorMessage += `• Check for typos in the project name`; return ResponseBuilder.error( errorMessage, { requestedProject: projectName, availableProjects: projectNames, suggestions: closeMatches, totalProjects: projectNames.length } ); } // Success! Set as last used project for session persistence ProjectTools.setLastUsedProject(projectName); // Get project details for confirmation const project = result.project!; return ResponseBuilder.successWithStructuredData( { projectName: project.name, projectId: project.projectId, isDefault: project.isDefault || false }, `✅ **Switched to ${project.name}**\n\n` + `**Project Details**:\n` + `• Project ID: ${project.projectId}\n` + `• Environments: ${project.environments!.join(', ')}\n` + `• Status: Active\n\n` + `📌 All subsequent commands will use this project until you switch again.\n\n` + `💡 **Tip**: You can also include the project name in any command:\n` + ` Example: \`list_deployments --project "${project.name}"\`` ); } catch (switchError: any) { // DXP-36: Handle unexpected errors during project switching return ResponseBuilder.error( '❌ **Unexpected Error During Project Switch**\n\n' + `An unexpected error occurred while switching to project "${projectName}".\n\n` + `**Error details**: ${switchError.message}\n\n` + '💡 **Troubleshooting**:\n' + '1. Check if the project configuration is valid\n' + '2. Verify environment variables are properly set\n' + '3. Try switching to a different project first\n' + '4. Contact support if the issue persists', { error: 'Unexpected switch error', details: switchError.message, requestedProject: projectName } ); } }
• lib/tools/project-switch-tool.ts:20-22 (schema)

  TypeScript interface defining the input arguments for the switch_project tool.
  interface ProjectSwitchArgs { projectName?: string; }
• lib/tools/project-tools.ts:1232-1272 (helper)

  Core helper method that performs the actual project switching: finds project by name/ID (case-insensitive), returns credentials and project info, or error if not found. Used by the handler.
  static switchProject(projectIdentifier: string | { projectName?: string; project?: string; projectId?: string }): SwitchResult { // Handle both string and object input const identifier = typeof projectIdentifier === 'object' ? (projectIdentifier.projectName || projectIdentifier.project || projectIdentifier.projectId) : projectIdentifier; if (!identifier) { return { success: false, message: 'No project identifier provided', credentials: null }; } const projects = this.getConfiguredProjects(); const project = projects.find(p => p.projectId === identifier || p.name === identifier || p.name.toLowerCase() === identifier.toLowerCase() ); if (!project) { return { success: false, message: `Project '${projectIdentifier}' not found`, credentials: null }; } return { success: true, message: `Switched to project: ${project.name}`, credentials: { projectId: project.projectId, apiKey: project.apiKey, apiSecret: project.apiSecret }, project: project }; }
• lib/tools/project-switch-tool.ts:28-94 (helper)

  Fuzzy matching helper for suggesting similar project names when exact match fails, used in error handling.
  static findSimilarProjectNames(input: string, projectNames: string[], maxSuggestions: number = 3): string[] { if (!input || !projectNames || projectNames.length === 0) { return []; } const inputLower = input.toLowerCase(); const suggestions: SimilaritySuggestion[] = []; for (const name of projectNames) { const nameLower = name.toLowerCase(); let score = 0; // Exact match (shouldn't happen, but just in case) if (nameLower === inputLower) { continue; } // Starts with input if (nameLower.startsWith(inputLower)) { score = 90; } // Contains input else if (nameLower.includes(inputLower)) { score = 70; } // Input contains project name (partial) else if (inputLower.includes(nameLower)) { score = 60; } // Check if input is close to start of project name (abbreviation-like) else if (inputLower.length <= 4 && nameLower.length >= inputLower.length) { // Check if most characters of input match start of name let matches = 0; for (let i = 0; i < Math.min(inputLower.length, nameLower.length); i++) { if (inputLower[i] === nameLower[i]) { matches++; } } if (matches >= inputLower.length - 1) { // Allow 1 mismatch score = 50; } } // Levenshtein-like simple distance else { const distance = this.simpleEditDistance(inputLower, nameLower); const maxLen = Math.max(inputLower.length, nameLower.length); const similarity = Math.max(0, (maxLen - distance) / maxLen); // Be more lenient with shorter inputs - they often are abbreviations const threshold = inputLower.length <= 4 ? 0.4 : 0.5; if (similarity > threshold) { score = Math.floor(similarity * 50); } } if (score > 0) { suggestions.push({ name, score }); } } // Sort by score (highest first) and return top suggestions return suggestions .sort((a, b) => b.score - a.score) .slice(0, maxSuggestions) .map(s => s.name); }
• lib/nlp-parser.ts:179-179 (registration)

  NLP pattern registration that maps natural language like 'switch to project X' to the 'switch_project' tool.
  { pattern: /^(switch|change|use).*(project|client|api)/i, tool: 'switch_project', category: 'setup' },