mcp-prompt-optimizer 3.0.2 → 3.0.4

package/index.js

@@ -5,7 +5,7 @@
  * Production-grade with Bayesian optimization, AG-UI real-time features, enhanced network resilience, 
  * development mode, and complete backend alignment
  * 
- * Version: 2.2.0 - Aligned with FastAPI Backend production-v2.2.0-stable
+ * Version: 3.0.2 - Aligned with FastAPI Backend production-v2.2.0-stable
  */
 
 const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
@@ -14,6 +14,7 @@ const { CallToolRequestSchema, ListToolsRequestSchema } = require('@modelcontext
 const https = require('https');
 const CloudApiKeyManager = require('./lib/api-key-manager');
 const packageJson = require('./package.json');
+const OPTIMIZATION_TEMPLATES = require('./lib/optimization-templates.json');
 
 const API_KEYS_PREFIX = '/api/v1/api-keys';
 const MCP_PREFIX = '/api/v1/mcp';
@@ -35,9 +36,6 @@ const ENDPOINTS = {
 
     /** Update (PATCH) */
     UPDATE:            (id) => `${MCP_PREFIX}/templates/${id}`,
-
-    /** Delete (DELETE) */
-    DELETE:            (id) => `${MCP_PREFIX}/templates/${id}`,
   },
 
   /** Search templates (GET) — MCP endpoint, API-key auth */
@@ -77,9 +75,9 @@ class MCPPromptOptimizer {
     this.developmentMode = false;
     this.requestTimeout = parseInt(process.env.OPTIMIZER_REQUEST_TIMEOUT) || 30000;
     
-    // NEW: Feature flags aligned with backend
-    this.bayesianOptimizationEnabled = process.env.ENABLE_BAYESIAN_OPTIMIZATION === 'true';
-    this.aguiFeatures = process.env.ENABLE_AGUI_FEATURES === 'true';
+    // Feature flags: enabled by default, set to 'false' to disable
+    this.bayesianOptimizationEnabled = process.env.ENABLE_BAYESIAN_OPTIMIZATION !== 'false';
+    this.aguiFeatures = process.env.ENABLE_AGUI_FEATURES !== 'false';
     
     this.setupMCPHandlers();
   }
@@ -208,11 +206,16 @@ class MCPPromptOptimizer {
                 type: "string",
                 description: "Filter by optimization strategy used"
               },
-              limit: { 
-                type: "number", 
+              limit: {
+                type: "number",
                 default: 5,
                 description: "Number of templates to return (1-20)"
               },
+              page: {
+                type: "number",
+                default: 1,
+                description: "Page number for pagination (use with limit to access results beyond the first page)"
+              },
               sort_by: {
                 type: "string",
                 enum: ["created_at", "confidence_score", "usage_count", "title"],
@@ -228,6 +231,20 @@ class MCPPromptOptimizer {
             }
           }
         },
+        {
+          name: "list_recent_templates",
+          description: "📋 List your most recently saved optimization templates, sorted by creation date.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              limit: {
+                type: "number",
+                default: 10,
+                description: "Number of recent templates to return (1-20)"
+              }
+            }
+          }
+        },
         {
           name: "detect_ai_context",
           description: "🧠 Detects the AI context for a given prompt using advanced backend analysis.",
@@ -287,6 +304,7 @@ class MCPPromptOptimizer {
           case "optimize_prompt": return await this.handleOptimizePrompt(args);
           case "get_quota_status": return await this.handleGetQuotaStatus();
           case "search_templates": return await this.handleSearchTemplates(args);
+          case "list_recent_templates": return await this.handleListRecentTemplates(args);
           case "detect_ai_context": return await this.handleDetectAIContext(args);
           case "create_template": return await this.handleCreateTemplate(args);
           case "get_template": return await this.handleGetTemplate(args);
@@ -301,11 +319,185 @@ class MCPPromptOptimizer {
     });
   }
 
+  // ─── Rules-Based Optimization (offline / fallback tier) ─────────────────────
+
+  /**
+   * Select the best-matching template for a prompt using pattern scoring.
+   * Mirrors the backend's pattern-based fallback (no LLM required).
+   */
+  _matchTemplate(prompt, backendContext) {
+    const lc = prompt.toLowerCase();
+    let bestTemplate = null;
+    let bestScore = 0;
+    let fallbackName = null;
+
+    for (const [name, template] of Object.entries(OPTIMIZATION_TEMPLATES)) {
+      if (template.context !== backendContext) continue;
+      if (name.startsWith('fallback_')) { fallbackName = name; continue; }
+
+      let hits = 0;
+      for (const pattern of template.patterns) {
+        if (pattern === '.*') continue;
+        if (lc.includes(pattern.toLowerCase())) hits++;
+      }
+      if (hits === 0) continue;
+
+      // Confidence: 1 hit → 0.6, 2 hits → 0.75, 3+ hits → 0.9 (mirrors backend)
+      const patternConf = hits === 1 ? 0.6 : hits === 2 ? 0.75 : 0.9;
+      const score = patternConf + (template.priority || 1) / 100;
+
+      if (score > bestScore) { bestScore = score; bestTemplate = name; }
+    }
+
+    if (!bestTemplate) {
+      return { templateName: fallbackName || `fallback_${backendContext.toLowerCase()}`, matchConfidence: 0.3 };
+    }
+    return { templateName: bestTemplate, matchConfidence: bestScore };
+  }
+
+  /** Extract a user-defined role from the start of a prompt (e.g. "As a doctor, …"). */
+  _extractUserRole(request) {
+    const rolePatterns = [
+      /^['"]?(?:As a|You are a|My role is)\s+([a-zA-Z0-9\s\-/()]+?)(?:,|(?=\s*\.))/i,
+      /^['"]?(?:I am a|I'm a)\s+([a-zA-Z0-9\s\-/()]+?)(?:,|(?=\s*\.))/i,
+    ];
+    for (const re of rolePatterns) {
+      const m = request.match(re);
+      if (m) return m[1].trim();
+    }
+    return null;
+  }
+
+  /**
+   * Compile a template playbook into a user-facing prose prompt.
+   * Produces readable output instead of XML scaffolding, matching the
+   * result a backend LLM pass would generate from the same playbook.
+   */
+  _compilePlaybook(playbook, originalRequest) {
+    const parts = [];
+
+    parts.push(originalRequest.trim());
+    parts.push('');
+
+    const userFacingPrinciples = (playbook.principles || []).filter(p => {
+      const lc = p.toLowerCase();
+      return !lc.includes('scratchpad') &&
+             !lc.startsWith('first, think') &&
+             !/<[a-z]/i.test(p);
+    });
+
+    if (userFacingPrinciples.length > 0) {
+      parts.push('To address this effectively:');
+      for (const p of userFacingPrinciples) parts.push(`- ${p}`);
+      parts.push('');
+    }
+
+    if (playbook.output_format) {
+      parts.push(`*Response format: ${playbook.output_format}*`);
+    }
+
+    return parts.join('\n');
+  }
+
+  /**
+   * Enhance an image generation prompt by appending style-appropriate
+   * quality/composition boosters (mirrors backend _compile_image_prompt_fallback).
+   */
+  _compileImagePrompt(originalRequest) {
+    const text = originalRequest.trim();
+    const lc = text.toLowerCase();
+
+    const styles = {
+      photorealistic: ['photorealistic','realistic','photo','photograph','photography'],
+      '3d_render':    ['3d','render','octane','unreal engine','blender','cinema 4d','ray tracing'],
+      cinematic:      ['cinematic','movie','film','dramatic','epic'],
+      digital_art:    ['digital art','concept art','digital illustration','cg','cgi'],
+      artistic:       ['artistic','painting','watercolor','oil painting','impressionist'],
+      anime:          ['anime','manga'],
+      vintage:        ['vintage','retro','nostalgic'],
+      minimalist:     ['minimalist','minimal','simple','clean'],
+    };
+
+    let detectedStyle = null;
+    for (const [style, kws] of Object.entries(styles)) {
+      if (kws.some(kw => lc.includes(kw))) { detectedStyle = style; break; }
+    }
+
+    const enhancements = [];
+    const hasQuality = ['high quality','8k','4k','hd','highly detailed','detailed'].some(t => lc.includes(t));
+    const hasLighting = ['lighting','light','shadow','illuminated','lit'].some(t => lc.includes(t));
+    const hasComposition = ['composition','rule of thirds','centered','framed'].some(t => lc.includes(t));
+
+    if (detectedStyle === 'photorealistic' && !hasQuality) {
+      enhancements.push('ultra realistic, sharp focus, professional photography');
+    } else if (detectedStyle === '3d_render' && !['octane','render'].some(t => lc.includes(t))) {
+      enhancements.push('high quality 3D render, volumetric lighting, ray traced shadows');
+    } else if (detectedStyle === 'cinematic' && !hasLighting) {
+      enhancements.push('cinematic lighting, dramatic atmosphere, film grain');
+    } else if (detectedStyle === 'digital_art' && !hasQuality) {
+      enhancements.push('highly detailed digital art, professional illustration');
+    } else if (detectedStyle === 'artistic' && !lc.includes('masterpiece')) {
+      enhancements.push('masterful technique, rich colors, artistic composition');
+    }
+
+    if (!hasLighting && detectedStyle !== 'minimalist') enhancements.push('dynamic lighting');
+    if (!hasComposition) enhancements.push('balanced composition');
+    if (!hasQuality) enhancements.push('high quality, 4K');
+
+    return enhancements.length > 0 ? `${text}, ${enhancements.join(', ')}` : text;
+  }
+
+  /**
+   * Core rules-based optimizer — no network, no LLM.
+   * Selects the best template by pattern matching, then compiles
+   * the playbook into a structured prompt. Confidence range: 0.35–0.55.
+   */
+  rulesBasedOptimize(prompt, aiContext, goals = []) {
+    const contextMap = {
+      code_generation:      'CODE_GENERATION',
+      llm_interaction:      'LLM_INTERACTION',
+      image_generation:     'IMAGE_GENERATION',
+      human_communication:  'HUMAN_COMMUNICATION',
+      api_automation:       'API_AUTOMATION',
+      technical_automation: 'TECHNICAL_AUTOMATION',
+      structured_output:    'STRUCTURED_OUTPUT',
+      creative_enhancement: 'CREATIVE_ENHANCEMENT',
+      creative_writing:     'CREATIVE_ENHANCEMENT',
+      general_assistant:    'LLM_INTERACTION',
+    };
+    const backendContext = contextMap[aiContext] || 'LLM_INTERACTION';
+
+    const { templateName, matchConfidence } = this._matchTemplate(prompt, backendContext);
+    const template = OPTIMIZATION_TEMPLATES[templateName];
+
+    const optimizedPrompt = backendContext === 'IMAGE_GENERATION'
+      ? this._compileImagePrompt(prompt)
+      : this._compilePlaybook(template.playbook, prompt);
+
+    // Honest confidence: rules-based tops out around 0.55
+    const confidence = parseFloat(Math.min(0.35 + matchConfidence * 0.2, 0.55).toFixed(2));
+
+    return {
+      optimized_prompt: optimizedPrompt,
+      confidence_score: confidence,
+      tier: 'rules',
+      template_used: templateName,
+      rules_based: true,
+      template_saved: false,
+      templates_found: [],
+      optimization_insights: null,
+      bayesian_insights: null,
+    };
+  }
+
+  // ─── End Rules-Based Optimization ────────────────────────────────────────────
+
   generateMockOptimization(prompt, goals, aiContext, enableBayesian = false) {
-    const optimized_prompt = `Enhanced for ${aiContext}: ${prompt}`;
+    // Use real rules-based optimization instead of fake placeholder output
+    const rulesResult = this.rulesBasedOptimize(prompt, aiContext, goals);
     const baseResult = {
-      optimized_prompt,
-      confidence_score: 0.87,
+      ...rulesResult,
+      rules_based: false,  // Show as normal optimized output in mock mode
       tier: 'explorer',
       mock_mode: true,
       template_saved: true,
@@ -381,7 +573,7 @@ class MCPPromptOptimizer {
       secondary_contexts: ['llm_interaction'],
       detected_parameters: [],
       mock_mode: true,
-      reason: 'Running in development/fallback mode.'
+      reason: 'Backend unavailable — using local pattern matching as fallback.'
     };
   }
 
@@ -432,7 +624,7 @@ class MCPPromptOptimizer {
       if (error.message.includes('Network') || error.message.includes('DNS') || error.message.includes('timeout') || error.message.includes('Connection')) {
         const fallbackContext = args.ai_context || 'human_communication';
         const fallbackEnableBayesian = args.enable_bayesian !== false && this.bayesianOptimizationEnabled;
-        const fallbackResult = this.generateMockOptimization(args.prompt, args.goals || ['clarity'], fallbackContext, fallbackEnableBayesian);
+        const fallbackResult = this.rulesBasedOptimize(args.prompt, fallbackContext, args.goals || ['clarity']);
         fallbackResult.fallback_mode = true;
         fallbackResult.error_reason = error.message;
         const formatted = this.formatOptimizationResult(fallbackResult, { detectedContext: fallbackContext, enableBayesian: fallbackEnableBayesian });
@@ -451,7 +643,7 @@ class MCPPromptOptimizer {
   async handleSearchTemplates(args) {
     try {
       const params = new URLSearchParams({
-        page: '1',
+        page: (args.page || 1).toString(),
         per_page: Math.min(args.limit || 5, 20).toString(),
         sort_by: args.sort_by || 'confidence_score',
         sort_order: args.sort_order || 'desc'
@@ -492,6 +684,49 @@ class MCPPromptOptimizer {
     }
   }
 
+  async handleListRecentTemplates(args) {
+    try {
+      const limit = Math.min(Math.max(args.limit || 10, 1), 20);
+      const params = new URLSearchParams({
+        page: '1',
+        per_page: limit.toString(),
+        sort_by: 'created_at',
+        sort_order: 'desc'
+      });
+
+      const endpoint = `${ENDPOINTS.SEARCH_TEMPLATES}?${params.toString()}`;
+      const result = await this.callBackendAPI(endpoint, null, 'GET');
+
+      const templates = result.templates || [];
+      let output = `# 📋 Recent Templates\n\n`;
+      output += `Showing **${templates.length}** most recently saved template(s).\n\n`;
+
+      if (templates.length === 0) {
+        output += `📭 No templates found yet.\nRun \`optimize_prompt\` to start building your template library.\n`;
+      } else {
+        output += `## 📋 **Template Results**\n`;
+        templates.forEach((t, index) => {
+          const confidence = t.confidence_score ? `${(t.confidence_score * 100).toFixed(1)}%` : 'N/A';
+          const preview = t.optimized_prompt ? t.optimized_prompt.substring(0, 60) + '...' : 'Preview unavailable';
+          output += `### ${index + 1}. ${t.title}\n`;
+          output += `- **Confidence:** ${confidence}\n`;
+          output += `- **ID:** \`${t.id}\`\n`;
+          output += `- **Preview:** ${preview}\n`;
+          if (t.ai_context) output += `- **Context:** ${t.ai_context}\n`;
+          if (t.optimization_goals && t.optimization_goals.length) {
+            output += `- **Goals:** ${t.optimization_goals.join(', ')}\n`;
+          }
+          output += `\n`;
+        });
+        output += `💡 Use \`get_template\` with an ID above to view the full optimized prompt.\n`;
+      }
+
+      return { content: [{ type: "text", text: output }] };
+    } catch (error) {
+      return { content: [{ type: "text", text: `❌ Could not retrieve recent templates: ${error.message}` }] };
+    }
+  }
+
   async handleGetOptimizationInsights(args) {
     if (!this.bayesianOptimizationEnabled) {
       return { content: [{ type: "text", text: "🧠 Bayesian optimization features are not enabled. Set ENABLE_BAYESIAN_OPTIMIZATION=true to access advanced insights." }] };
@@ -607,6 +842,18 @@ class MCPPromptOptimizer {
   }
 
   async handleCreateTemplate(args) {
+    // Client-side validation before network call
+    const requiredStrings = ['title', 'original_prompt', 'optimized_prompt'];
+    for (const field of requiredStrings) {
+      if (!args[field] || typeof args[field] !== 'string' || args[field].trim() === '') {
+        return { content: [{ type: "text", text: `❌ Missing required field: '${field}'. Required fields: title, original_prompt, optimized_prompt, confidence_score (0.0–1.0)` }] };
+      }
+    }
+    if (args.confidence_score === undefined || args.confidence_score === null ||
+        typeof args.confidence_score !== 'number' || args.confidence_score < 0 || args.confidence_score > 1) {
+      return { content: [{ type: "text", text: `❌ Missing required field: 'confidence_score'. Required fields: title, original_prompt, optimized_prompt, confidence_score (0.0–1.0)` }] };
+    }
+
     try {
       const result = await this.callBackendAPI(ENDPOINTS.TEMPLATE.CREATE, args);
       let output = `# ✅ Template Created Successfully!\n\n`;
@@ -638,6 +885,10 @@ class MCPPromptOptimizer {
       output += `**Optimized Prompt:**\n\`\`\`\n${result.optimized_prompt}\n\`\`\`\n`;
       return { content: [{ type: "text", text: output }] };
     } catch (error) {
+      const msg = error.message || '';
+      if (msg.includes('404') || msg.toLowerCase().includes('not found')) {
+        throw new Error(`Template \`${args.template_id}\` not found. It may have been deleted or the ID is incorrect. Use \`search_templates\` to find available templates.`);
+      }
       throw new Error(`Failed to retrieve template: ${error.message}`);
     }
   }
@@ -736,8 +987,37 @@ class MCPPromptOptimizer {
   }
 
   formatOptimizationResult(result, context) {
-    let output = `# 🎯 Optimized Prompt\n\n${result.optimized_prompt}\n\n`;
-    output += `**Confidence:** ${(result.confidence_score * 100).toFixed(1)}%\n`;
+    let output;
+    if (result.rules_based) {
+      if (result.fallback_mode) {
+        output = `# 🔧 Rules-Based Optimization Applied\n\n`;
+        output += `⚠️ *Backend unreachable — your prompt has been structured using local rule templates (no LLM). `;
+        output += `Re-run when the backend is available for full LLM optimization.*\n\n`;
+      } else {
+        output = `# 🔧 Rules-Based Optimization Applied\n\n`;
+        output += `*API key not validated — optimized using local rule templates. `;
+        output += `Set \`MCP_API_KEY\` for full LLM optimization.*\n\n`;
+      }
+      output += `**Template:** \`${result.template_used || 'general'}\`\n\n`;
+      output += `**Optimized Prompt:**\n\`\`\`\n${result.optimized_prompt}\n\`\`\`\n\n`;
+    } else if (result.fallback_mode) {
+      // Legacy path — should no longer be reached
+      output = `# ⚠️ Backend Unavailable — Prompt Not Optimized\n\n`;
+      output += `**Issue:** ${result.error_reason}\n`;
+      output += `The backend could not be reached. Your original prompt is returned below unmodified.\n\n`;
+      output += `**Original Prompt:**\n\`\`\`\n${result.optimized_prompt}\n\`\`\`\n\n`;
+    } else {
+      output = `# 🎯 Optimized Prompt\n\n${result.optimized_prompt}\n\n`;
+      if (result.confidence_score < 0.25) {
+        output += `> ℹ️ *Low confidence indicates the backend applied rules-based optimization (no LLM). `;
+        output += `Ensure \`OPENROUTER_API_KEY\` is configured in the backend for full LLM enhancement.*\n\n`;
+      }
+    }
+    if (result.rules_based) {
+      output += `**Confidence:** ${(result.confidence_score * 100).toFixed(1)}% *(rules-based — LLM optimization typically 70–95%)*\n`;
+    } else {
+      output += `**Confidence:** ${(result.confidence_score * 100).toFixed(1)}%\n`;
+    }
     output += `**AI Context:** ${context.detectedContext}\n`;
     
     if (result.template_saved) {
@@ -747,8 +1027,9 @@ class MCPPromptOptimizer {
     if (result.templates_found?.length) {
       output += `\n📋 **Similar Templates Found**\nFound **${result.templates_found.length}** similar template(s):\n`;
       result.templates_found.slice(0, 3).forEach(t => {
-        output += `- ${t.title} (${(t.confidence_score * 100).toFixed(1)}% match)\n`;
+        output += `- ${t.title} (${(t.confidence_score * 100).toFixed(1)}% match) — ID: \`${t.id}\`\n`;
       });
+      output += `\n💡 Use \`get_template\` with any ID above to view the full optimized prompt.\n`;
     }
     
     if (result.optimization_insights) {
@@ -796,12 +1077,10 @@ class MCPPromptOptimizer {
       }
     }
     
-    if (result.fallback_mode) {
-      output += `\n⚠️ **Fallback Mode Active**\n**Issue:** ${result.error_reason}\n`;
+    if (!result.fallback_mode) {
+      output += `\n🔗 **Quick Actions**\n- Dashboard: https://promptoptimizer-blog.vercel.app/dashboard\n- Analytics: https://promptoptimizer-blog.vercel.app/analytics\n`;
     }
     
-    output += `\n🔗 **Quick Actions**\n- Dashboard: https://promptoptimizer-blog.vercel.app/dashboard\n- Analytics: https://promptoptimizer-blog.vercel.app/analytics\n`;
-    
     return output;
   }
 
@@ -821,6 +1100,17 @@ class MCPPromptOptimizer {
       else if (percentage >= 75) statusIcon = '🟡';
       
       output += `**Usage:** ${statusIcon} ${used}/${limit} (${percentage}%)\n`;
+
+      const remaining = limit - used;
+      if (remaining <= 0) {
+        output += `\n❌ **Quota Exhausted** — You have no optimizations remaining this month.\n`;
+        output += `Upgrade at https://promptoptimizer-blog.vercel.app/pricing\n`;
+        output += `*(Quota resets at the start of your next billing cycle)*\n`;
+      } else if (percentage >= 90) {
+        output += `\n⚠️ **Critical** — ${remaining} optimization${remaining === 1 ? '' : 's'} remaining. Upgrade at https://promptoptimizer-blog.vercel.app/pricing\n`;
+      } else if (percentage >= 75) {
+        output += `\n⚠️ **Warning** — Approaching your monthly limit.\n`;
+      }
     }
 
     output += `\n## ✨ **Available Features**\n`;
@@ -865,10 +1155,12 @@ class MCPPromptOptimizer {
     
     if (!result.templates || result.templates.length === 0) {
       output += `📭 **No Templates Found**\n`;
-      if (originalArgs.query) {
-        output += `Try searching with different keywords or remove filters.\n`;
+      const hasActiveFilters = originalArgs.query || originalArgs.ai_context || originalArgs.sophistication_level || originalArgs.complexity_level;
+      if (hasActiveFilters) {
+        output += `No templates matched your filters. Try removing \`ai_context\` or \`query\` filters.\n`;
       } else {
         output += `You don't have any saved templates yet. Templates are automatically saved when optimization confidence is >70%.\n`;
+        output += `Run \`optimize_prompt\` to start building your template library.\n`;
       }
     } else {
       output += `## 📋 **Template Results**\n`;

package/lib/api-key-manager.js

@@ -488,7 +488,7 @@ class CloudApiKeyManager {
 
         try {
             // Step 1: Validate API key
-            const validation = await this.validateApiKey();
+            let validation = await this.validateApiKey();
             
             // Step 2: Get comprehensive quota status
             const info = await this.getApiKeyInfo();