mcp-prompt-optimizer 3.7.4 → 3.8.1

package/CHANGELOG.md

@@ -5,6 +5,76 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.8.1] - 2026-07-29
+
+### Fixed
+- **Security: the validation cache let any API key inherit a different key's cached identity.**
+  `~/.mcp-cloud-api-cache.json` is a single file per machine, not namespaced per key. Found live
+  while testing against a real registered key: validating key A succeeds and caches its result;
+  minutes later, validating a completely different, invalid key B gets a clean 401 from the
+  backend — but the client's fallback logic didn't check *which* key the cached entry belonged to,
+  and didn't check whether the error was a definitive rejection versus a network outage. It
+  silently returned key A's cached "valid" data and started the server authenticated as A's
+  account, having never actually validated B. Any string passed as `OPTIMIZER_API_KEY` within the
+  cache's 1-hour window (2 hours via the short-term fallback tier) would have worked, as long as
+  *some* real key had been validated on that machine recently.
+  Fixed two ways: (1) a cached entry is only used if its stored `apiKeyPrefix` matches the key
+  currently being validated, and (2) cache fallback is skipped entirely on a 4xx rejection —
+  it's reserved for genuine network/5xx outages of the *same* already-cached key, which was
+  always the intent (the surrounding code already distinguished 4xx from network errors for its
+  error-message hint text; the fallback branch above it just never used that distinction).
+  Added a network-free regression test (`tests/quick-test.js`) that seeds the cache with one
+  key's data, forces a 401 for a different key, and asserts the second key never inherits the
+  first's identity — and a second check confirming the legitimate same-key network-outage
+  fallback still works unchanged.
+
+## [3.8.0] - 2026-07-29
+
+### Added
+- **`optimize_prompt` gains `reasoning_effort` and `execution_shape`**, the two Track C1 controls
+  that previously only reached `/api/v1/optimize` (the WebUI's endpoint) — `/api/v1/mcp/optimize`
+  (what this tool actually calls) never had them wired in at all, a pre-existing architectural
+  gap, not a regression. These matter *more* for a programmatic/agentic caller than a WebUI user:
+  there's no human watching each call to decide whether a prompt is worth paying for deeper
+  reasoning, or to notice a `multi_agent` request quietly running the LLM engine regardless of
+  the prompt's complexity. `multi_agent` is gated the same way on this endpoint as it is on
+  `/optimize` (`_gate_execution_shape`, downgraded to `direct` on tiers without repair access);
+  the response echoes back the *effective* shape that ran, and the formatter now surfaces a
+  downgrade when one happens. `stop_rule` (the third Track C1 control) is deliberately **not**
+  exposed here: this endpoint never runs the quick-eval-then-repair flow that gives `stop_rule`
+  any effect, so accepting it would advertise a guardrail that does nothing. Backend change
+  landed alongside this (`app/api/mcp_router.py`), verified with new endpoint tests covering the
+  free-tier downgrade, the pro-tier non-downgrade, and the team/enterprise-default non-downgrade
+  path (the last one guards against team keys getting silently capped if their tier lookup ever
+  comes back empty) — full backend suite (1740 passed) confirmed no regressions.
+- **`generate_harness_bundle` gains `agent_read_only` and `agent_harness`**, mirroring the two
+  optional fields the backend's `HarnessBundleRequest` already accepts. `agent_harness` lets the
+  caller pick the generated agent.yaml's execution backend (`claude-sdk`/`codex`/`pi`) to match
+  whichever API key they actually have available wherever the bundle runs — without it, the
+  bundle silently defaults per-deploy-target (usually `claude-sdk`) and fails at runtime with a
+  missing-credential error if that's not the key the user holds. `agent_read_only` narrows the
+  generated subagent's tools to Read/Grep/Glob, for audit/review workflows that should never be
+  able to edit or execute anything. Both optional, both already validated server-side (a bad
+  `agent_harness` value gets a clear 422 listing valid choices).
+- **`tests/e2e-stdio-smoke.js`**: black-box test that spawns the published binary as a real
+  subprocess and speaks JSON-RPC over stdio, exactly as an external MCP client would. Confirms
+  clean startup/shutdown behavior for missing/malformed/unregistered keys, including a live round
+  trip to the deployed backend. Full `tools/call` coverage requires `OPTIMIZER_API_KEY` set to a
+  real, backend-registered key — this package has no reachable mock/dev bypass (`developmentMode`
+  is hardcoded `false` in `index.js`; see the `dev`/`dev:mock` npm scripts, which are currently
+  dead for the same reason).
+
+## [3.7.5] - 2026-07-18
+
+### Fixed
+- **10 MCP tools were unconditionally broken**: `generate_agent_sop`, `transform_for_framework`, `generate_harness_bundle`, `explore_sop_approaches`, `get_prompt_by_slug`, `compile_prompt`, `list_template_versions`, `rollback_template`, `publish_template`, and `run_quick_evaluation` all called backend routes that only accepted a JWT — a credential this stdio client can never obtain (no browser, no login flow). Every call to these tools failed with an auth error, always. Backend now accepts API-key auth on these routes; verified the fix doesn't expand what a key is authorized to do (every route is scoped to the calling account's own data, same as routes that already worked).
+- **Tier-upgrade messages never fired**: the 403-detection check looked for the literal string `'403'` inside the error body, which never appears there — only the HTTP status code carries it. Now checks the real status code, so upgrade prompts actually show up when a real tier gate is hit.
+- **Fabricated fallback data**: `get_optimization_insights` and `get_real_time_status` silently returned hardcoded fake numbers (fake optimization counts, fake AG-UI metrics) on any backend error, indistinguishable from real account data. Both now say the data is unavailable instead of inventing it.
+- **`formatRealTimeStatus` read the wrong fields**: it never matched the AG-UI status endpoint's actual response shape, even when the call succeeded.
+- **`formatQuotaStatus` invented a fake `5000` quota limit** when the backend didn't report one.
+- **Free-tier quota text said 7/month**; the real limit is 20.
+- **Dead domain and wrong key-format references**: `promptoptimizer-blog.vercel.app` no longer resolves; some messages also claimed `sk-local-*` was a valid key format for this package (that's the sibling local package's prefix, not this one's).
+
 ## [3.7.4] - 2026-07-16
 
 ### Fixed

package/index.js

@@ -187,6 +187,16 @@ class MCPPromptOptimizer {
                     description: "Narrative description of what a successful optimized output achieves (e.g. 'reader understands why churn drives flat revenue even with user growth')."
                   }
                 }
+              },
+              reasoning_effort: {
+                type: "string",
+                enum: ["minimal", "standard", "deep"],
+                description: "How much reasoning to apply: 'minimal' biases toward faster/cheaper routing, 'standard' is the default, 'deep' biases toward the LLM tier for maximum analysis. Most useful when calling this tool programmatically in a loop or pipeline, where there's no human watching each call to decide whether it's worth paying for more depth."
+              },
+              execution_shape: {
+                type: "string",
+                enum: ["direct", "hybrid", "multi_agent"],
+                description: "Execution style, independent of the tier the prompt would normally route to: 'direct' is single-pass, 'hybrid' adds rules+LLM verification, 'multi_agent' forces plan-and-execute with sub-agents regardless of the prompt's complexity. 'multi_agent' is downgraded to 'direct' on tiers without repair access — the response echoes back whichever one actually ran, so you can detect a downgrade."
               }
             },
             required: ["prompt"]
@@ -442,6 +452,24 @@ class MCPPromptOptimizer {
               sop_content: {
                 type: "string",
                 description: "The SOP content to base the harness on (required if no session_id)."
+              },
+              agent_read_only: {
+                type: "boolean",
+                description: (
+                  "Narrow the generated Claude Code subagent's tools to Read/Grep/Glob only. "
+                  + "Set this for audit/review workflows that should never edit or execute anything. "
+                  + "Default: false (full capability)."
+                )
+              },
+              agent_harness: {
+                type: "string",
+                enum: ["claude-sdk", "codex", "pi"],
+                description: (
+                  "Execution backend for the generated agent.yaml: 'claude-sdk' (needs ANTHROPIC_API_KEY), "
+                  + "'codex' (needs OPENROUTER_API_KEY or OPENAI_API_KEY), or 'pi' (needs PI_API_KEY). "
+                  + "Set this to match the API key available wherever the bundle will actually run — "
+                  + "the default is per-deploy-target (usually claude-sdk) and won't know which key you have."
+                )
               }
             },
             required: ["goal"]
@@ -931,10 +959,17 @@ class MCPPromptOptimizer {
         }
       }
 
+      if (args.reasoning_effort) {
+        optimizationPayload.reasoning_effort = args.reasoning_effort;
+      }
+      if (args.execution_shape) {
+        optimizationPayload.execution_shape = args.execution_shape;
+      }
+
       const result = await this.callBackendAPI(ENDPOINTS.OPTIMIZE, optimizationPayload);
-      
+
       const enableBayesian = args.enable_bayesian !== false && this.bayesianOptimizationEnabled;
-      return { content: [{ type: "text", text: this.formatOptimizationResult(result, { detectedContext, enableBayesian }) }] };
+      return { content: [{ type: "text", text: this.formatOptimizationResult(result, { detectedContext, enableBayesian, requestedExecutionShape: args.execution_shape }) }] };
       
     } catch (error) {
       if (error.message.includes('Network') || error.message.includes('DNS') || error.message.includes('timeout') || error.message.includes('Connection')) {
@@ -1056,31 +1091,7 @@ class MCPPromptOptimizer {
       return { content: [{ type: "text", text: this.formatOptimizationInsights(result) }] };
       
     } catch (error) {
-      // Fallback to mock insights
-      const mockInsights = {
-        bayesian_status: {
-          optimization_active: true,
-          total_optimizations: 47,
-          improvement_rate: '23.5%',
-          confidence_score: 0.89
-        },
-        parameter_insights: {
-          most_effective_goals: ['clarity', 'technical_accuracy', 'analytical_depth'],
-          context_performance: {
-            'code_generation': 0.92,
-            'llm_interaction': 0.87,
-            'technical_automation': 0.84
-          },
-          optimization_trends: 'Steady improvement in technical contexts'
-        },
-        recommendations: args.include_recommendations !== false ? [
-          'Focus on technical_accuracy for code generation prompts',
-          'Combine clarity with analytical_depth for best results',
-          'Consider using structured_output context for data tasks'
-        ] : []
-      };
-
-      return { content: [{ type: "text", text: this.formatOptimizationInsights(mockInsights) }] };
+      return { content: [{ type: "text", text: `🧠 Optimization insights are unavailable right now (${error.message}). This is not your data — no insights were generated.` }] };
     }
   }
 
@@ -1095,22 +1106,7 @@ class MCPPromptOptimizer {
       return { content: [{ type: "text", text: this.formatRealTimeStatus(result) }] };
       
     } catch (error) {
-      const mockStatus = {
-        agui_status: 'available',
-        streaming_optimization: true,
-        websocket_support: true,
-        real_time_analytics: true,
-        active_optimizations: 3,
-        average_response_time: '1.2s',
-        features: {
-          live_optimization: true,
-          collaborative_editing: true,
-          instant_feedback: true,
-          performance_monitoring: true
-        }
-      };
-
-      return { content: [{ type: "text", text: this.formatRealTimeStatus(mockStatus) }] };
+      return { content: [{ type: "text", text: `⚡ AG-UI real-time status is unavailable right now (${error.message}).` }] };
     }
   }
 
@@ -1346,6 +1342,8 @@ class MCPPromptOptimizer {
       user_goal: args.goal,
       sop_content: args.sop_content || "",
     };
+    if (args.agent_read_only) payload.agent_read_only = true;
+    if (args.agent_harness) payload.agent_harness = args.agent_harness;
 
     // If session_id provided, first fetch session artifacts for sop_content
     if (args.session_id) {
@@ -1434,8 +1432,8 @@ class MCPPromptOptimizer {
         }]
       };
     } catch (error) {
-      if (error.message && error.message.includes('403')) {
-        return { content: [{ type: "text", text: "Error: SOP exploration requires Innovator tier. Upgrade at /pricing." }] };
+      if (error.statusCode === 403) {
+        return { content: [{ type: "text", text: `Error: SOP exploration requires Innovator tier. Upgrade at /pricing.\n\nBackend error: ${error.message}` }] };
       }
       throw new Error(`Failed to explore SOP approaches: ${error.message}`);
     }
@@ -1450,9 +1448,8 @@ class MCPPromptOptimizer {
       output += `**Body:**\n\`\`\`\n${result.optimized_prompt || result.body || ''}\n\`\`\`\n`;
       return { content: [{ type: "text", text: output }] };
     } catch (error) {
-      const msg = error.message || '';
-      if (msg.includes('403') || msg.includes('TIER')) {
-        return { content: [{ type: "text", text: `Upgrade required: runtime prompt delivery requires Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${msg}` }] };
+      if (error.statusCode === 403) {
+        return { content: [{ type: "text", text: `Upgrade required: runtime prompt delivery requires Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${error.message}` }] };
       }
       throw new Error(`Failed to fetch prompt by slug: ${error.message}`);
     }
@@ -1465,9 +1462,8 @@ class MCPPromptOptimizer {
       const compiled = result.compiled_prompt || result.body || JSON.stringify(result, null, 2);
       return { content: [{ type: "text", text: `# Compiled Prompt\n\n\`\`\`\n${compiled}\n\`\`\`\n` }] };
     } catch (error) {
-      const msg = error.message || '';
-      if (msg.includes('403') || msg.includes('TIER')) {
-        return { content: [{ type: "text", text: `Upgrade required: prompt compilation requires Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${msg}` }] };
+      if (error.statusCode === 403) {
+        return { content: [{ type: "text", text: `Upgrade required: prompt compilation requires Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${error.message}` }] };
       }
       throw new Error(`Failed to compile prompt: ${error.message}`);
     }
@@ -1493,9 +1489,8 @@ class MCPPromptOptimizer {
       }
       return { content: [{ type: "text", text: output }] };
     } catch (error) {
-      const msg = error.message || '';
-      if (msg.includes('403') || msg.includes('TIER')) {
-        return { content: [{ type: "text", text: `Upgrade required: template versioning requires Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${msg}` }] };
+      if (error.statusCode === 403) {
+        return { content: [{ type: "text", text: `Upgrade required: template versioning requires Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${error.message}` }] };
       }
       throw new Error(`Failed to list template versions: ${error.message}`);
     }
@@ -1509,9 +1504,8 @@ class MCPPromptOptimizer {
       const msg = result.message || `Template rolled back to version ${args.version_number}`;
       return { content: [{ type: "text", text: `# ✅ Rollback Complete\n\n${msg}\n\n**Template ID:** \`${args.template_id}\`\n**Version:** ${args.version_number}` }] };
     } catch (error) {
-      const msg = error.message || '';
-      if (msg.includes('403') || msg.includes('TIER')) {
-        return { content: [{ type: "text", text: `Upgrade required: template rollback requires Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${msg}` }] };
+      if (error.statusCode === 403) {
+        return { content: [{ type: "text", text: `Upgrade required: template rollback requires Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${error.message}` }] };
       }
       throw new Error(`Failed to rollback template: ${error.message}`);
     }
@@ -1524,9 +1518,8 @@ class MCPPromptOptimizer {
       const msg = result.message || `Template ${args.template_id} published successfully`;
       return { content: [{ type: "text", text: `# ✅ Template Published\n\n${msg}\n\nThe template is now available for runtime delivery via \`get_prompt_by_slug\`.` }] };
     } catch (error) {
-      const msg = error.message || '';
-      if (msg.includes('403') || msg.includes('TIER')) {
-        return { content: [{ type: "text", text: `Upgrade required: template publishing requires Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${msg}` }] };
+      if (error.statusCode === 403) {
+        return { content: [{ type: "text", text: `Upgrade required: template publishing requires Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${error.message}` }] };
       }
       throw new Error(`Failed to publish template: ${error.message}`);
     }
@@ -1556,9 +1549,8 @@ class MCPPromptOptimizer {
       }
       return { content: [{ type: "text", text: output }] };
     } catch (error) {
-      const msg = error.message || '';
-      if (msg.includes('403') || msg.includes('TIER')) {
-        return { content: [{ type: "text", text: `Upgrade required: evaluations require Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${msg}` }] };
+      if (error.statusCode === 403) {
+        return { content: [{ type: "text", text: `Upgrade required: evaluations require Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${error.message}` }] };
       }
       throw new Error(`Failed to run quick evaluation: ${error.message}`);
     }
@@ -1631,7 +1623,9 @@ class MCPPromptOptimizer {
               } catch {
                 errorMessage = `HTTP ${res.statusCode}: ${responseData}`;
               }
-              reject(new Error(errorMessage));
+              const httpError = new Error(errorMessage);
+              httpError.statusCode = res.statusCode;
+              reject(httpError);
             }
           } catch (parseError) {
             reject(new Error(`Invalid response format: ${parseError.message}`));
@@ -1698,6 +1692,11 @@ class MCPPromptOptimizer {
     if (result.metadata?.routing_score != null) {
       output += `**Routing Score:** ${result.metadata.routing_score.toFixed(3)} (${result.metadata?.routing_tier || 'unknown'})\n`;
     }
+    if (result.execution_shape && context.requestedExecutionShape && result.execution_shape !== context.requestedExecutionShape) {
+      output += `**Execution Shape:** \`${result.execution_shape}\` *(requested \`${context.requestedExecutionShape}\`, downgraded — your tier doesn't have repair access)*\n`;
+    } else if (result.reasoning_effort && result.reasoning_effort !== 'standard') {
+      output += `**Reasoning Effort:** \`${result.reasoning_effort}\`\n`;
+    }
     if (!result.rules_based && !result.fallback_mode && result.metadata?.model_used) {
       output += `**Model:** ${result.metadata.model_used}\n`;
     }
@@ -1787,7 +1786,7 @@ class MCPPromptOptimizer {
       output += `2. Generate your API key at https://promptoptimizer.xyz/dashboard\n`;
       output += `3. Run in your terminal:\n\n`;
       output += `\`\`\`\nnpx mcp-prompt-optimizer connect\n\`\`\`\n\n`;
-      output += `You get **7 LLM optimizations/month free**. Upgrade anytime for more.\n`;
+      output += `You get **20 LLM optimizations/month free**. Upgrade anytime for more.\n`;
     }
 
     return output;
@@ -1801,25 +1800,30 @@ class MCPPromptOptimizer {
       output += `**Usage:** 🟢 Unlimited\n`;
     } else {
       const used = quota.used || 0;
-      const limit = quota.limit || 5000;
+      const limit = quota.limit;
+
+      if (limit === undefined || limit === null) {
+        output += `**Usage:** ${used} used (limit unavailable — backend did not report a quota limit)\n`;
+      } else {
       const percentage = limit > 0 ? ((used / limit) * 100).toFixed(1) : 0;
-      
+
       let statusIcon = '🟢';
       if (percentage >= 90) statusIcon = '🔴';
       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.xyz/local-license\n`;
+        output += `Upgrade at https://promptoptimizer.xyz/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.xyz/local-license\n`;
+        output += `\n⚠️ **Critical** — ${remaining} optimization${remaining === 1 ? '' : 's'} remaining. Upgrade at https://promptoptimizer.xyz/pricing\n`;
       } else if (percentage >= 75) {
         output += `\n⚠️ **Warning** — Approaching your monthly limit.\n`;
       }
+      }
     }
 
     output += `\n## ✨ **Available Features**\n`;
@@ -1841,9 +1845,9 @@ class MCPPromptOptimizer {
     }
 
     output += `\n## 🔗 **Account Management**\n`;
-    output += `- Dashboard: https://promptoptimizer-blog.vercel.app/dashboard\n`;
-    output += `- Analytics: https://promptoptimizer-blog.vercel.app/analytics\n`;
-    output += `- Upgrade: https://promptoptimizer.xyz/local-license\n`;
+    output += `- Dashboard: https://promptoptimizer.xyz/dashboard\n`;
+    output += `- Analytics: https://promptoptimizer.xyz/analytics\n`;
+    output += `- Upgrade: https://promptoptimizer.xyz/pricing\n`;
 
     return output;
   }
@@ -1949,41 +1953,40 @@ class MCPPromptOptimizer {
     }
     
     output += `## 🔗 **Advanced Analytics**\n`;
-    output += `- Full Analytics: https://promptoptimizer-blog.vercel.app/analytics\n`;
-    output += `- Performance Dashboard: https://promptoptimizer-blog.vercel.app/dashboard\n`;
+    output += `- Full Analytics: https://promptoptimizer.xyz/analytics\n`;
+    output += `- Performance Dashboard: https://promptoptimizer.xyz/dashboard\n`;
     
     return output;
   }
 
   formatRealTimeStatus(status) {
     let output = `# ⚡ AG-UI Real-Time Status\n\n`;
-    
+    const metrics = status.metrics || {};
+
     output += `## 🚀 **Service Status**\n`;
-    output += `- **AG-UI Status:** ${status.agui_status === 'available' ? '🟢 Available' : '🔴 Unavailable'}\n`;
-    output += `- **Streaming Optimization:** ${status.streaming_optimization ? '✅ Enabled' : '❌ Disabled'}\n`;
-    output += `- **WebSocket Support:** ${status.websocket_support ? '✅ Enabled' : '❌ Disabled'}\n`;
-    output += `- **Real-time Analytics:** ${status.real_time_analytics ? '✅ Enabled' : '❌ Disabled'}\n\n`;
-    
-    if (status.active_optimizations !== undefined) {
-      output += `## 📈 **Current Activity**\n`;
-      output += `- **Active Optimizations:** ${status.active_optimizations}\n`;
-      output += `- **Average Response Time:** ${status.average_response_time}\n\n`;
+    output += `- **AG-UI Status:** ${status.status === 'healthy' ? '🟢 Healthy' : '🔴 Degraded'}\n\n`;
+
+    output += `## 📈 **Current Activity**\n`;
+    output += `- **Active Sessions:** ${metrics.active_sessions ?? 'unknown'}\n`;
+    output += `- **Total Connections:** ${metrics.total_connections ?? 'unknown'}\n`;
+    output += `- **Total Optimizations:** ${metrics.total_optimizations ?? 'unknown'}\n`;
+    if (metrics.uptime_seconds !== undefined) {
+      output += `- **Uptime:** ${Math.round(metrics.uptime_seconds)}s\n`;
     }
-    
-    if (status.features) {
-      const features = status.features;
+    output += `\n`;
+
+    if (metrics.features_enabled) {
       output += `## ⚡ **Available Features**\n`;
-      if (features.live_optimization) output += `✅ Live Optimization\n`;
-      if (features.collaborative_editing) output += `✅ Collaborative Editing\n`;
-      if (features.instant_feedback) output += `✅ Instant Feedback\n`;
-      if (features.performance_monitoring) output += `✅ Performance Monitoring\n`;
+      for (const [feature, enabled] of Object.entries(metrics.features_enabled)) {
+        if (enabled) output += `✅ ${feature}\n`;
+      }
       output += `\n`;
     }
-    
+
     output += `## 🔗 **Real-Time Access**\n`;
-    output += `- Live Dashboard: https://promptoptimizer-blog.vercel.app/live\n`;
+    output += `- Live Dashboard: https://promptoptimizer.xyz/live\n`;
     output += `- WebSocket Endpoint: Available via API\n`;
-    
+
     return output;
   }
 
@@ -2001,7 +2004,7 @@ async function startValidatedMCPServer() {
   try {
     const apiKey = process.env.OPTIMIZER_API_KEY;
     if (!apiKey) {
-      console.error('❌ API key required. Get one at https://promptoptimizer.xyz/local-license');
+      console.error('❌ API key required. Get one free at https://promptoptimizer.xyz/dashboard');
       process.exit(1);
     }
     
@@ -2179,7 +2182,7 @@ async function runConnectWizard() {
     }
     if (ok > 0) {
       console.log('\n👉 Restart your MCP client(s) to activate LLM optimization.');
-      console.log('   Free plan: 7 LLM optimizations/month.');
+      console.log('   Free plan: 20 LLM optimizations/month.');
       console.log('   Upgrade at https://promptoptimizer.xyz/pricing\n');
     }
   }

package/lib/api-key-manager.js

@@ -220,30 +220,38 @@ class CloudApiKeyManager {
             this.log(`Backend validation failed: ${error.message}`, 'warn');
             await this.updateNetworkHealth(false, error.message);
             
-            // Enhanced fallback strategy
-            const cachedValidation = await this.getCachedValidation();
-            
-            if (cachedValidation && !this.isCacheExpired(cachedValidation)) {
-                this.log('Using cached API key validation', 'warn');
-                return cachedValidation.data;
-            }
-            
-            // SECURITY: Limited fallback for brief network issues only (2 hours max)
-            if (cachedValidation && !this.isFallbackCacheExpired(cachedValidation)) {
-                this.log('Using short-term fallback cache due to network issues', 'warn');
-                const fallbackData = cachedValidation.data;
-                fallbackData.fallback_mode = true;
-                fallbackData.network_issue = error.message;
-                fallbackData.expires_soon = true;
-                return fallbackData;
+            // A 4xx means the backend rejected THIS key itself — not a connectivity
+            // problem. Falling back to a cache entry here would mean any key,
+            // valid or not, silently inherits whatever key was last cached on this
+            // machine (cacheFile is a single global file, not namespaced per key).
+            // Cache fallback exists only for genuine network/5xx outages of the
+            // SAME key that was already validated and cached — never for a
+            // definitive rejection, and never for a cache entry from a different key.
+            const isClientError = error.statusCode >= 400 && error.statusCode < 500;
+
+            if (!isClientError) {
+                const cachedValidation = await this.getCachedValidation();
+                const cacheMatchesThisKey = cachedValidation
+                    && cachedValidation.apiKeyPrefix === this.apiKey.substring(0, 20) + '...';
+
+                if (cacheMatchesThisKey && !this.isCacheExpired(cachedValidation)) {
+                    this.log('Using cached API key validation', 'warn');
+                    return cachedValidation.data;
+                }
+
+                // SECURITY: Limited fallback for brief network issues only (2 hours max)
+                if (cacheMatchesThisKey && !this.isFallbackCacheExpired(cachedValidation)) {
+                    this.log('Using short-term fallback cache due to network issues', 'warn');
+                    const fallbackData = cachedValidation.data;
+                    fallbackData.fallback_mode = true;
+                    fallbackData.network_issue = error.message;
+                    fallbackData.expires_soon = true;
+                    return fallbackData;
+                }
             }
 
             // SECURITY: Offline mode removed - backend validation required
-            // No cache fallback beyond 2 hours
-
-            // A 4xx means the backend rejected the key itself, not a connectivity
-            // problem — telling the user to check their internet is wrong there.
-            const isClientError = error.statusCode >= 400 && error.statusCode < 500;
+            // No cache fallback beyond 2 hours, and none at all for a 4xx rejection.
             const hint = isClientError ? '' : ' Please check your internet connection.';
             throw new Error(`API key validation failed: ${error.message}.${hint}`);
         }
@@ -593,7 +601,7 @@ class CloudApiKeyManager {
 
         throw new Error(
             'API key required. Set the OPTIMIZER_API_KEY environment variable.\n' +
-            'Get your API key at: https://promptoptimizer.xyz/local-license'
+            'Get your API key at: https://promptoptimizer.xyz/dashboard'
         );
     }
 

package/lib/check-status.js

@@ -10,7 +10,7 @@ async function checkStatus() {
         if (!apiKey) {
             console.error('❌ No API key found');
             console.log('\n📝 Set your API key to check status:');
-            console.log('   export OPTIMIZER_API_KEY=sk-local-your-key-here'); // Aligned with free tier/development
+            console.log('   export OPTIMIZER_API_KEY=sk-opt-your-key-here');
             if (developmentMode) {
                 console.log('\n🧪 Development Mode Options:');
                 console.log('   export OPTIMIZER_API_KEY=sk-dev-test-key');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-prompt-optimizer",
-  "version": "3.7.4",
+  "version": "3.8.1",
   "description": "Professional cloud-based MCP server for AI-powered prompt optimization with intelligent context detection, Bayesian optimization, AG-UI real-time optimization, template auto-save, optimization insights, personal model configuration via WebUI, team collaboration, enterprise-grade features, production resilience, and startup validation. Universal compatibility with Claude Desktop, Cursor, Windsurf, and 17+ MCP clients.",
   "main": "index.js",
   "bin": {
@@ -25,6 +25,7 @@
     "test:runner": "node tests/test-runner.js",
     "test:simple": "node tests/simple-test.js",
     "test:contract": "node tests/contract-check.js",
+    "test:e2e": "node tests/e2e-stdio-smoke.js",
     "pretest": "npm run health-check",
     "prepublishOnly": "npm run test:quick",
     "version": "echo 'Updating version...' && npm run test:quick"
@@ -124,8 +125,8 @@
     "required_keys": [
       {
         "name": "OPTIMIZER_API_KEY",
-        "format": "sk-opt-*, sk-team-*, sk-dev-*, or sk-local-*",
-        "description": "Cloud API key from promptoptimizer.xyz/local-license or development key for testing",
+        "format": "sk-opt-*, sk-team-*, or sk-dev-*",
+        "description": "Cloud API key from promptoptimizer.xyz/dashboard or development key for testing",
         "required": true
       }
     ],
@@ -195,6 +196,19 @@
     "last_sync": "2026-06-01T00:00:00Z"
   },
   "release_notes": {
+    "v3.7.5": {
+      "major_features": [
+        "Fixed: 10 MCP tools (generate_agent_sop, transform_for_framework, generate_harness_bundle, explore_sop_approaches, get_prompt_by_slug, compile_prompt, list_template_versions, rollback_template, publish_template, run_quick_evaluation) called backend routes that only accepted a JWT, which this stdio client can never obtain — every call failed unconditionally. Backend now accepts API-key auth on these routes too.",
+        "Fixed: the tier-upgrade message for these tools never fired because the code checked for the literal string '403' inside the error body, which never appears there (that's the HTTP status code, not body text). Now checks the real status code.",
+        "Fixed: get_optimization_insights and get_real_time_status fell back to hardcoded fake data (fabricated optimization counts, fake AG-UI metrics) on any backend error, presented as real account data. Both now report unavailability honestly instead.",
+        "Fixed: formatRealTimeStatus was never reading the AG-UI status endpoint's actual response shape, even on success.",
+        "Fixed: formatQuotaStatus invented a fake 5000 quota limit when the backend didn't report one.",
+        "Fixed: free-tier quota text said 7/month; actual limit is 20.",
+        "Fixed: dead promptoptimizer-blog.vercel.app domain and wrong sk-local-* key-format claims (that's the sibling local package's prefix, not this one's) across index.js, check-status.js, and package.json."
+      ],
+      "breaking_changes": [],
+      "migration_guide": "No migration required. Users who called any of the 10 previously-broken MCP tools will now get real results instead of an auth error."
+    },
     "v3.7.4": {
       "major_features": [
         "Fixed: 6 of 8 documented CLI commands (check-status, validate-key, diagnose, clear-cache, help, version) were not implemented in the argv dispatcher and silently started the blocking MCP server instead, hanging the terminal. Now wired to their lib/*.js implementations.",