mcp-prompt-optimizer 3.7.2 → 3.7.4

package/CHANGELOG.md

@@ -5,6 +5,18 @@ 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.7.4] - 2026-07-16
+
+### Fixed
+- **CLI commands were mostly non-functional**: the README documented 8 `mcp-prompt-optimizer <command>` subcommands, but the argv dispatcher only ever recognized `connect`. Running any of `check-status`, `validate-key`, `diagnose`, `clear-cache`, `help`, or `version` silently started the blocking stdio MCP server instead, hanging the terminal. All six are now wired to their existing `lib/*.js` implementations.
+- **Unrecognized commands no longer fall through to the server.** Any argument that isn't a known command now prints an error and usage to stderr and exits 1, instead of silently starting the MCP server. This closes the bug class for future commands too, not just the six fixed here.
+- **Dropped `test` from the documented CLI commands.** It mapped to `tests/test-runner.js`, a maintainer-only pre-publish validation script that isn't included in the published npm package (`tests/` is not in `files`), so it could never have worked for an end user.
+
+## [3.7.3] - 2026-07-16
+
+### Fixed
+- **Stale free-tier quota in README**: docs said 7 optimizations/month, live enforcement is 20. Docs-only fix, no code change.
+
 ## [3.7.2] - 2026-07-05
 
 ### Fixed

package/README.md

@@ -26,7 +26,7 @@
 
 **1. Get your API key:**
 
-- **🆓 Free Tier** (`sk-opt-*`): 7 LLM optimizations/month, 1 API key — no credit card required
+- **🆓 Free Tier** (`sk-opt-*`): 20 LLM optimizations/month, 1 API key — no credit card required
 - **⭐ Pro** (`sk-opt-*`): 500 optimizations/month, full model config, Context Engineer
 - **🏢 Enterprise** (`sk-team-*`): Unlimited optimizations, team keys, shared quotas
 
@@ -352,7 +352,7 @@ Configure custom models in the WebUI and the MCP server uses them automatically.
 
 | Plan | Price | Optimizations/month | CE Credits | API Keys |
 |---|---|---|---|---|
-| 🆓 Free | $0 | 7 LLM | — | 1 |
+| 🆓 Free | $0 | 20 LLM | — | 1 |
 | ⭐ Pro | $19/mo | 500 | 5 | 1 |
 | 🏢 Enterprise | Custom | Unlimited | 50 | 10 (shared) |
 
@@ -368,7 +368,6 @@ All plans include AI context detection, template management, personal model conf
 npx mcp-prompt-optimizer connect        # Interactive wizard: add API key to Claude Desktop config
 mcp-prompt-optimizer check-status       # Check API key and quota status
 mcp-prompt-optimizer validate-key       # Validate API key with backend
-mcp-prompt-optimizer test               # Test backend integration
 mcp-prompt-optimizer diagnose           # Run comprehensive diagnostic
 mcp-prompt-optimizer clear-cache        # Clear validation cache
 mcp-prompt-optimizer help               # Show help and setup instructions
@@ -501,4 +500,4 @@ Windsurf, Cline, VS Code, Zed, Replit, JetBrains IDEs, and Neovim are all suppor
 
 ---
 
-*Start free at [promptoptimizer.xyz](https://promptoptimizer.xyz) — 7 LLM optimizations/month, no credit card required.*
+*Start free at [promptoptimizer.xyz](https://promptoptimizer.xyz) — 20 LLM optimizations/month, no credit card required.*

package/index.js

@@ -57,6 +57,18 @@ const ENDPOINTS = {
   /** AG‑UI status (GET) */
   AGUI_STATUS:         '/api/status',
 
+  /** Prompt delivery by slug */
+  GET_PROMPT_BY_SLUG:      (slug) => `/api/v1/prompts/${slug}`,
+  COMPILE_PROMPT:          (slug) => `/api/v1/prompts/${slug}/compiled`,
+
+  /** Template governance (versioning, publish) */
+  TEMPLATE_VERSIONS:       (id) => `/api/v1/templates/${id}/versions`,
+  ROLLBACK_TEMPLATE:       (id, n) => `/api/v1/templates/${id}/rollback/${n}`,
+  PUBLISH_TEMPLATE:        (id) => `/api/v1/templates/${id}/publish`,
+
+  /** Quick evaluation (stateless) */
+  QUICK_EVALUATE:          '/api/v1/evaluations/quick-evaluate',
+
   /** Context Engineer (CE) endpoints */
   CE: {
     SOP:                     '/api/v1/context-engineer/sop',
@@ -73,7 +85,8 @@ const ENDPOINTS = {
 const DEPLOY_TARGET_ENUM = [
   "claude_code", "claude_desktop", "cursor", "copilot",
   "windsurf", "cline", "zed", "replit", "openai_agents", "ollama",
-  "amazon_q", "aider", "continue_dev", "crewai"
+  "amazon_q", "aider", "continue_dev", "crewai",
+  "codex_cli",
 ];
 
 class MCPPromptOptimizer {
@@ -465,6 +478,79 @@ class MCPPromptOptimizer {
             additionalProperties: false
           }
         },
+        {
+          name: "get_prompt_by_slug",
+          description: "Fetch your latest published prompt template by slug for runtime use — decouple prompts from deploys.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              slug: { type: "string", description: "The URL-safe slug of the prompt template (e.g., product-writer-a3f9c21b)" }
+            },
+            required: ["slug"]
+          }
+        },
+        {
+          name: "compile_prompt",
+          description: "Compile a prompt template with variable interpolation for runtime delivery — returns the fully interpolated prompt string ready for use.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              slug: { type: "string", description: "The URL-safe slug of the prompt template" },
+              variables: {
+                type: "object",
+                description: "Variable values to interpolate (e.g. {\"user_name\": \"Alex\", \"plan\": \"Pro\"})",
+                additionalProperties: { type: "string" }
+              }
+            },
+            required: ["slug"]
+          }
+        },
+        {
+          name: "list_template_versions",
+          description: "List all version snapshots of a saved template — every update creates a snapshot you can inspect or restore.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              template_id: { type: "string", description: "The ID of the template" }
+            },
+            required: ["template_id"]
+          }
+        },
+        {
+          name: "rollback_template",
+          description: "Restore a template to a previous version snapshot — undo unwanted changes instantly.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              template_id: { type: "string", description: "The ID of the template" },
+              version_number: { type: "number", description: "The version number to roll back to (use list_template_versions to find available versions)" }
+            },
+            required: ["template_id", "version_number"]
+          }
+        },
+        {
+          name: "publish_template",
+          description: "Publish a template — makes it available for runtime delivery via get_prompt_by_slug.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              template_id: { type: "string", description: "The ID of the template to publish" }
+            },
+            required: ["template_id"]
+          }
+        },
+        {
+          name: "run_quick_evaluation",
+          description: "Run a stateless one-shot evaluation of an optimized prompt using LLM judges — get actionable quality scoring without creating a dataset.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              prompt: { type: "string", description: "The optimized prompt to evaluate" },
+              original_prompt: { type: "string", description: "The original prompt for comparison scoring" }
+            },
+            required: ["prompt", "original_prompt"]
+          }
+        },
       ];
 
       // Add advanced tools if Bayesian optimization is enabled
@@ -524,6 +610,12 @@ class MCPPromptOptimizer {
           case "get_ce_quota_status": return await this.handleGetCEQuotaStatus();
           case "generate_harness_bundle": return await this.handleGenerateHarnessBundle(args);
           case "explore_sop_approaches": return await this.handleExploreSopApproaches(args);
+          case "get_prompt_by_slug": return await this.handleGetPromptBySlug(args);
+          case "compile_prompt": return await this.handleCompilePrompt(args);
+          case "list_template_versions": return await this.handleListTemplateVersions(args);
+          case "rollback_template": return await this.handleRollbackTemplate(args);
+          case "publish_template": return await this.handlePublishTemplate(args);
+          case "run_quick_evaluation": return await this.handleRunQuickEvaluation(args);
           default: throw new Error(`Unknown tool: ${name}`);
         }
       } catch (error) {
@@ -1349,6 +1441,129 @@ class MCPPromptOptimizer {
     }
   }
 
+  async handleGetPromptBySlug(args) {
+    if (!args.slug) throw new Error('Slug is required');
+    try {
+      const result = await this.callBackendAPI(ENDPOINTS.GET_PROMPT_BY_SLUG(args.slug), null, 'GET');
+      let output = `# 📦 Prompt by Slug: \`${args.slug}\`\n\n`;
+      output += `**Title:** ${result.title || 'N/A'}\n`;
+      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}` }] };
+      }
+      throw new Error(`Failed to fetch prompt by slug: ${error.message}`);
+    }
+  }
+
+  async handleCompilePrompt(args) {
+    if (!args.slug) throw new Error('Slug is required');
+    try {
+      const result = await this.callBackendAPI(ENDPOINTS.COMPILE_PROMPT(args.slug), { variables: args.variables || {} });
+      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}` }] };
+      }
+      throw new Error(`Failed to compile prompt: ${error.message}`);
+    }
+  }
+
+  async handleListTemplateVersions(args) {
+    if (!args.template_id) throw new Error('Template ID is required');
+    try {
+      const result = await this.callBackendAPI(ENDPOINTS.TEMPLATE_VERSIONS(args.template_id), null, 'GET');
+      const versions = result.versions || result.data || [];
+      let output = `# 📋 Template Versions\n\n`;
+      output += `**Template ID:** \`${args.template_id}\`\n\n`;
+      if (versions.length === 0) {
+        output += 'No version history found for this template.';
+      } else {
+        versions.forEach((v, i) => {
+          output += `**${i + 1}.** Version ${v.version_number || 'N/A'}`;
+          if (v.created_at) output += ` — ${v.created_at}`;
+          if (v.change_summary) output += `\n   _${v.change_summary}_`;
+          output += `\n`;
+        });
+        output += `\nUse \`rollback_template\` with a version number to restore.`;
+      }
+      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}` }] };
+      }
+      throw new Error(`Failed to list template versions: ${error.message}`);
+    }
+  }
+
+  async handleRollbackTemplate(args) {
+    if (!args.template_id) throw new Error('Template ID is required');
+    if (args.version_number === undefined || args.version_number === null) throw new Error('version_number is required');
+    try {
+      const result = await this.callBackendAPI(ENDPOINTS.ROLLBACK_TEMPLATE(args.template_id, args.version_number), {});
+      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}` }] };
+      }
+      throw new Error(`Failed to rollback template: ${error.message}`);
+    }
+  }
+
+  async handlePublishTemplate(args) {
+    if (!args.template_id) throw new Error('Template ID is required');
+    try {
+      const result = await this.callBackendAPI(ENDPOINTS.PUBLISH_TEMPLATE(args.template_id), {});
+      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}` }] };
+      }
+      throw new Error(`Failed to publish template: ${error.message}`);
+    }
+  }
+
+  async handleRunQuickEvaluation(args) {
+    if (!args.prompt) throw new Error('prompt is required');
+    if (!args.original_prompt) throw new Error('original_prompt is required');
+    try {
+      const result = await this.callBackendAPI(ENDPOINTS.QUICK_EVALUATE, {
+        prompt: args.prompt,
+        original_prompt: args.original_prompt,
+        assertions: [
+          {
+            type: "llm-rubric",
+            value: "The optimized prompt is clearer, more specific, and better achieves the original intent than the input prompt.",
+            weight: 1.0
+          }
+        ]
+      });
+      let output = `# 📊 Quick Evaluation Result\n\n`;
+      output += `**Score:** ${result.overall_score != null ? (result.overall_score * 100).toFixed(1) + '%' : 'N/A'}\n`;
+      output += `**Passed:** ${result.passed ? '✅ Yes' : '❌ No'}\n`;
+      if (result.context_detected) output += `**Context:** ${result.context_detected}\n`;
+      if (result.actionable_feedback && result.actionable_feedback.length) {
+        output += `\n**Feedback:**\n${result.actionable_feedback.map(f => `- ${f}`).join('\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: evaluations require Pro tier or higher. Upgrade at /pricing.\n\nBackend error: ${msg}` }] };
+      }
+      throw new Error(`Failed to run quick evaluation: ${error.message}`);
+    }
+  }
+
   _formatSkillPackage(result) {
     const sections = ['# Skill Package Generated'];
     const artifacts = result.artifacts || result.steps || {};
@@ -1983,12 +2198,50 @@ async function runConnectWizard() {
   });
 }
 
+function printCliHelp() {
+  console.log(`MCP Prompt Optimizer v${packageJson.version}
+
+Usage:
+  mcp-prompt-optimizer                    Start the MCP server (used by MCP clients)
+  mcp-prompt-optimizer connect            Interactive wizard: add API key to Claude Desktop config
+  mcp-prompt-optimizer check-status       Check API key and quota status
+  mcp-prompt-optimizer validate-key       Validate API key with backend
+  mcp-prompt-optimizer diagnose           Run comprehensive diagnostic
+  mcp-prompt-optimizer clear-cache        Clear validation cache
+  mcp-prompt-optimizer help               Show this help
+  mcp-prompt-optimizer version            Show version information`);
+}
+
+function printCliVersion() {
+  console.log(packageJson.version);
+}
+
+const CLI_COMMANDS = {
+  connect: runConnectWizard,
+  'check-status': () => require('./lib/check-status')().then(() => process.exit(0)),
+  'validate-key': () => require('./lib/validate-key')().then(() => process.exit(0)),
+  'clear-cache': () => require('./lib/clear-cache')().then(() => process.exit(0)),
+  diagnose: () => require('./lib/diagnose')().then(() => process.exit(0)),
+  help: printCliHelp,
+  '--help': printCliHelp,
+  '-h': printCliHelp,
+  version: printCliVersion,
+  '--version': printCliVersion,
+  '-v': printCliVersion,
+};
+
 if (require.main === module) {
   const args = process.argv.slice(2);
-  if (args[0] === 'connect') {
-    runConnectWizard();
-  } else {
+  const cmd = args[0];
+
+  if (!cmd) {
     startValidatedMCPServer();
+  } else if (CLI_COMMANDS[cmd]) {
+    CLI_COMMANDS[cmd]();
+  } else {
+    console.error(`❌ Unknown command: ${cmd}\n`);
+    printCliHelp();
+    process.exit(1);
   }
 }
 

package/lib/api-key-manager.js

@@ -241,7 +241,11 @@ class CloudApiKeyManager {
             // SECURITY: Offline mode removed - backend validation required
             // No cache fallback beyond 2 hours
 
-            throw new Error(`API key validation failed: ${error.message}. Please check your internet connection.`);
+            // 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;
+            const hint = isClientError ? '' : ' Please check your internet connection.';
+            throw new Error(`API key validation failed: ${error.message}.${hint}`);
         }
     }
 
@@ -268,7 +272,17 @@ class CloudApiKeyManager {
             } catch (error) {
                 lastError = error;
                 this.log(`Attempt ${attempt} failed: ${error.message}`, 'warn');
-                
+
+                // A 4xx means the backend definitively rejected the request (bad/expired
+                // key, malformed request) — retrying with the same key can't change that.
+                // Only network errors and 5xx (transient/server-side) are worth retrying.
+                // 429 is the exception: rate limits are exactly what backoff is for.
+                const isClientError = error.statusCode >= 400 && error.statusCode < 500 && error.statusCode !== 429;
+                if (isClientError) {
+                    this.log('Non-retryable client error — not retrying', 'error');
+                    break;
+                }
+
                 if (attempt < this.maxRetries) {
                     const delay = this.calculateRetryDelay(attempt);
                     this.log(`Retrying in ${delay}ms...`);
@@ -690,7 +704,9 @@ class CloudApiKeyManager {
                             } 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}`));

package/lib/check-status.js

@@ -25,7 +25,13 @@ async function checkStatus() {
         console.log('='.repeat(50));
         console.log(`🎯 Subscription Tier: ${apiKeyInfo.tier}`);
         console.log(`🔑 API Key Type: ${apiKeyInfo.keyType}`);
-        console.log(`✅ Key Status: ${apiKeyInfo.isValid ? 'Valid' : 'Invalid'}`);
+        console.log(`${apiKeyInfo.isValid ? '✅' : '❌'} Key Status: ${apiKeyInfo.isValid ? 'Valid' : 'Invalid'}`);
+        if (!apiKeyInfo.isValid) {
+            // getApiKeyInfo() reports failure via isValid:false rather than throwing,
+            // so this catch block never sees it — exit(1) has to happen here instead.
+            if (apiKeyInfo.error) console.log(`   ${apiKeyInfo.error}`);
+            process.exit(1);
+        }
     } catch (error) {
         console.error(`❌ Status check failed: ${error.message}\n`);
         process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-prompt-optimizer",
-  "version": "3.7.2",
+  "version": "3.7.4",
   "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": {
@@ -195,6 +195,22 @@
     "last_sync": "2026-06-01T00:00:00Z"
   },
   "release_notes": {
+    "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.",
+        "Fixed: unrecognized CLI arguments now print an error + usage to stderr and exit(1), instead of silently falling through to server startup. Removes the entire hung-terminal bug class, not just the known commands.",
+        "Removed 'test' from documented CLI commands: it mapped to a maintainer-only pre-publish script (tests/test-runner.js) that isn't included in the published package."
+      ],
+      "breaking_changes": [],
+      "migration_guide": "No migration required. Only affects users who ran documented CLI subcommands other than 'connect', which previously hung."
+    },
+    "v3.7.3": {
+      "major_features": [
+        "Docs only: corrected stale free-tier quota in README (7 optimizations/month -> 20), matching the backend enforcement fix"
+      ],
+      "breaking_changes": [],
+      "migration_guide": "No migration required."
+    },
     "v3.7.2": {
       "major_features": [
         "MCP server startup logs (banner, status lines, mode indicators, key validation messages) now write to stderr so stdout stays a clean JSON-RPC channel for stdio MCP clients"