mcp-prompt-optimizer 3.0.2 → 3.0.4

package/README.md

@@ -1,72 +1,35 @@
-# MCP Prompt Optimizer v3.0.0
+# MCP Prompt Optimizer v3.0.3
 
-🚀 **Professional cloud-based MCP server** for AI-powered prompt optimization with intelligent context detection, template management, team collaboration, enterprise-grade features, and **optional personal model configuration**. Starting at $2.99/month.
-
-⚠️ **v3.0.0 Breaking Changes:** API key is now REQUIRED for all operations. Development mode and offline mode have been removed for security.
+🚀 **Professional cloud-based MCP server** for AI-powered prompt optimization with intelligent context detection, template management, team collaboration, and enterprise-grade reliability. Starting at $2.99/month.
 
 ## ✨ Key Features
 
-🧠 **AI Context Detection** - Automatically detects and optimizes for image generation, LLM interaction, technical automation  
-📁 **Template Management** - Auto-save high-confidence optimizations, search & reuse patterns  
-👥 **Team Collaboration** - Shared quotas, team templates, role-based access  
-📊 **Real-time Analytics** - Confidence scoring, usage tracking, optimization insights (Note: Advanced features like Bayesian Optimization and AG-UI are configurable and may provide mock data if disabled in the backend)  
-☁️ **Cloud Processing** - Always up-to-date AI models, no local setup required  
-🎛️ **Personal Model Choice** - Use your own OpenRouter models via WebUI configuration  
-🔧 **Universal MCP** - Works with Claude Desktop, Cursor, Windsurf, Cline, VS Code, Zed, Replit  
+🧠 **AI Context Detection** — Automatically detects and optimizes for code, creative writing, image generation, communication, and more
+📁 **Template Management** — Auto-save high-confidence optimizations, search & reuse patterns
+👥 **Team Collaboration** — Shared quotas, team templates, role-based access
+📊 **Confidence Scoring** — Honest quality signal with per-tier annotations
+☁️ **Cloud Processing** — Always up-to-date AI models via backend LLM pipeline
+🔧 **Resilient Fallback** — Structured local optimization if the backend is unreachable
+🎛️ **Personal Model Choice** — Use your own OpenRouter models via WebUI configuration
+🔧 **Universal MCP** — Works with Claude Desktop, Cursor, Windsurf, Cline, VS Code, Zed, Replit
 
-## 🚀 Quick Start
+---
 
-**1. Get your API key (REQUIRED):**
+## 🚀 Quick Start
 
-⚠️ **Important:** An API key is REQUIRED to use this package. Choose your tier:
+**1. Get your API key (required):**
 
-- **🆓 FREE Tier** (`sk-local-*`): 5 daily optimizations - Get started at [https://promptoptimizer-blog.vercel.app/pricing](https://promptoptimizer-blog.vercel.app/pricing)
-- **⭐ Paid Tiers** (`sk-opt-*`, `sk-team-*`): More optimizations, team features, advanced capabilities
+- **🆓 Free Tier** (`sk-local-*`): 5 daily optimizations — [promptoptimizer-blog.vercel.app/pricing](https://promptoptimizer-blog.vercel.app/pricing)
+- **⭐ Paid Tiers** (`sk-opt-*`, `sk-team-*`): Higher quotas, team features, advanced capabilities
 
-**2. Install the MCP server:**
+**2. Install:**
 ```bash
 npm install -g mcp-prompt-optimizer
 ```
 
-**3. Configure Claude Desktop:**
-Add to your `~/.claude/claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "prompt-optimizer": {
-      "command": "npx",
-      "args": ["mcp-prompt-optimizer"],
-      "env": {
-        "OPTIMIZER_API_KEY": "sk-local-your-key-here"  // REQUIRED: Use your API key here
-      }
-    }
-  }
-}
-```
-
-> **Note:** All API keys are validated against our backend server. Internet connection required (brief caching for reliability).
-
-**4. Restart Claude Desktop** and start optimizing with AI context awareness!
-
-**5. (Optional) Configure custom models** - See [Advanced Model Configuration](#-advanced-model-configuration-optional) below
-
-## 🎛️ Advanced Model Configuration (Optional)
-
-### WebUI Model Selection & Personal OpenRouter Keys
-
-**Want to use your own AI models?** Configure them in the WebUI first, then the NPM package automatically uses your settings!
-
-#### **Step 1: Configure in WebUI**
-1. **Visit Dashboard:** [https://promptoptimizer-blog.vercel.app/dashboard](https://promptoptimizer-blog.vercel.app/dashboard)
-2. **Go to Settings** → User Settings
-3. **Add OpenRouter API Key:** Get one from [OpenRouter.ai](https://openrouter.ai)
-4. **Select Your Models:**
-   - **Optimization Model:** e.g., `anthropic/claude-3-5-sonnet` (for prompt optimization)
-   - **Evaluation Model:** e.g., `google/gemini-pro-1.5` (for quality assessment)
-
-#### **Step 2: Use NPM Package**
-Your configured models are **automatically used** by the MCP server - no additional setup needed!
+**3. Configure your MCP client:**
 
+Add to `~/.claude/claude_desktop_config.json` (Claude Desktop):
 ```json
 {
   "mcpServers": {
@@ -74,467 +37,352 @@ Your configured models are **automatically used** by the MCP server - no additio
       "command": "npx",
       "args": ["mcp-prompt-optimizer"],
       "env": {
-        "OPTIMIZER_API_KEY": "sk-opt-your-key-here"  // Your service API key
+        "OPTIMIZER_API_KEY": "sk-local-your-key-here"
       }
     }
   }
 }
 ```
 
-### **Model Selection Priority**
-```
-1. 🎯 Your WebUI-configured models (highest priority)
-2. 🔧 Request-specific model (if specified)
-3. ⚙️ System defaults (fallback)
-```
-
-### **Benefits of Personal Model Configuration**
-
-✅ **Cost Control** - Pay for your own OpenRouter usage  
-✅ **Model Choice** - Access 100+ models (Claude, GPT-4, Gemini, Llama, etc.)  
-✅ **Performance** - Choose faster or more capable models  
-✅ **Consistency** - Same models across WebUI and MCP tools  
-✅ **Privacy** - Your data goes through your OpenRouter account  
-
-### **Example Model Recommendations**
-
-**For Creative/Complex Prompts:**
-- Optimization: `anthropic/claude-3-5-sonnet`
-- Evaluation: `google/gemini-pro-1.5`
-
-**For Fast/Simple Optimizations:**
-- Optimization: `openai/gpt-4o-mini`
-- Evaluation: `openai/gpt-3.5-turbo`
-
-**For Technical/Code Prompts:**
-- Optimization: `anthropic/claude-3-5-sonnet`
-- Evaluation: `anthropic/claude-3-haiku`
-
-### **Important Notes**
-
-🔑 **Two Different API Keys:**
-- **Service API Key** (`sk-opt-*`): For the MCP service subscription
-- **OpenRouter API Key**: For your personal model usage (configured in WebUI)
-
-💰 **Cost Structure:**
-- **Service subscription**: Monthly fee for optimization features
-- **OpenRouter usage**: Pay-per-token for your chosen models
+**4. Restart your MCP client** and start optimizing.
 
-🔄 **No NPM Package Changes Needed:**
-When you update models in WebUI, the NPM package automatically uses the new settings!
+> **Note:** API keys are validated against the backend server. An internet connection is required (responses are cached for up to 2 hours for reliability).
 
 ---
 
-## 💰 Cloud Subscription Plans
+## ⚙️ How Optimization Works
 
-> **All plans include the same sophisticated AI optimization quality**
+Prompts are routed through a three-tier pipeline based on complexity and context. Each tier produces a different output format and confidence range.
 
-### 🎯 Explorer - $2.99/month
-- **5,000 optimizations** per month
-- **Individual use** (1 user, 1 API key)
-- **Full AI features** - context detection, template management, insights
-- **Personal model configuration** via WebUI
-- **Community support**
+### Tier 1 — LLM Optimization (backend, confidence 70–95%)
 
-### 🎨 Creator - $25.99/month ⭐ *Popular*
-- **18,000 optimizations** per month  
-- **Team features** (2 members, 3 API keys)
-- **Full AI features** - context detection, template management, insights
-- **Personal model configuration** via WebUI
-- **Priority processing** + email support
+The backend routes complex or high-sophistication prompts through a Gemini Flash LLM pass that genuinely rewrites and enriches the prompt. This is the highest-quality output.
 
-### 🚀 Innovator - $69.99/month
-- **75,000 optimizations** per month
-- **Large teams** (5 members, 10 API keys)
-- **Full AI features** - context detection, template management, insights
-- **Personal model configuration** via WebUI
-- **Advanced analytics** + priority support + dedicated support channel
+```
+# 🎯 Optimized Prompt
 
-🆓 **Free Trial:** 5 optimizations with full feature access
+My Python script crashes with a KeyError on line 47. I need help diagnosing
+the root cause. I am using Python 3.11 with pandas 2.0. The error occurs
+when accessing dictionary keys after a merge operation.
 
-## 🧠 AI Context Detection & Enhancement
+**Confidence:** 82.0%
+**AI Context:** code_generation
+```
 
-The server automatically detects your prompt type and enhances optimization goals:
+### Tier 2 — Backend Rules Optimization (backend, confidence < 25%)
 
-### 🎨 Image Generation Context
-**Detected patterns:** `--ar`, `--v`, `midjourney`, `dall-e`, `photorealistic`, `4k`
-```
-Input: "A beautiful landscape --ar 16:9 --v 6"
-✅ Enhanced goals: parameter_preservation, keyword_density, technical_precision
-✅ Preserves technical parameters (--ar, --v, etc.)
-✅ Optimizes quality keywords and visual descriptors
-```
+For simpler or lower-sophistication prompts the backend applies rules-based optimization without an LLM. When this happens, confidence will be below 25% and a note will appear explaining what to check if you expected full LLM enhancement.
 
-### 🤖 LLM Interaction Context  
-**Detected patterns:** `analyze`, `explain`, `evaluate`, `summary`, `research`, `paper`, `analysis`, `interpret`, `discussion`, `assessment`, `compare`, `contrast`
-```
-Input: "Analyze the pros and cons of this research paper and provide a comprehensive evaluation"
-✅ Enhanced goals: context_specificity, token_efficiency, actionability
-✅ Improves role clarity and instruction precision
-✅ Optimizes for better AI understanding
 ```
+# 🎯 Optimized Prompt
 
-### 💻 Code Generation Context
-**Detected patterns:** `def`, `function`, `code`, `python`, `javascript`, `java`, `c++`, `return`, `import`, `class`, `for`, `while`, `if`, `else`, `elif`
-```
-Input: "def fibonacci(n): return n if n <= 1 else fibonacci(n-1) + fibonacci(n-2)"
-✅ Enhanced goals: technical_accuracy, parameter_preservation, precision
-✅ Protects code elements and technical syntax
-✅ Enhances technical precision and clarity
-```
+My Python script crashes with a KeyError. Please provide the error message
+and relevant code.
 
-### ⚙️ Technical Automation Context
-**Detected patterns:** `automate`, `script`, `api`
-```
-Input: "Create a script to automate deployment process"
-✅ Enhanced goals: technical_accuracy, parameter_preservation, precision
-✅ Protects code elements and technical syntax
-✅ Enhances technical precision and clarity
+> ℹ️ *Low confidence indicates the backend applied rules-based optimization
+> (no LLM). Ensure `OPENROUTER_API_KEY` is configured in the backend for
+> full LLM enhancement.*
+
+**Confidence:** 18.0%
+**AI Context:** code_generation
 ```
 
-### 💬 Human Communication Context (Default)
-**All other prompts** get standard optimization for human readability and clarity.
+### Tier 3 — Local Rules Fallback (npm, confidence 35–55%)
 
-## 📊 Enhanced Optimization Features
+If the backend is unreachable, the npm package applies optimization locally using a library of domain-specific templates. The output is a structured, user-facing prose prompt — no XML scaffolding. The confidence annotation makes the quality tier explicit.
 
-### Professional Optimization (All Users)
 ```
-🎯 Optimized Prompt
+# 🔧 Rules-Based Optimization Applied
 
-Create a comprehensive technical blog post about artificial intelligence that systematically explores current real-world applications, evidence-based benefits, existing limitations and challenges, and data-driven future implications for businesses and society.
+⚠️ *Backend unreachable — your prompt has been structured using local rule
+templates (no LLM). Re-run when the backend is available for full LLM
+optimization.*
 
-Confidence: 87.3%
-Plan: Creator
-AI Context: Human Communication
-Goals Enhanced: Yes (clarity → clarity, specificity, actionability)
+**Template:** `debugging_request`
 
-🧠 AI Context Benefits Applied
-- ✅ Standard optimization rules applied
-- ✅ Human communication optimized
+**Optimized Prompt:**
+```
+My Python script crashes with a KeyError
 
-✅ Auto-saved as template (ID: tmp_abc123)
-*High-confidence optimization automatically saved for future use*
+To address this effectively:
+- Identify the most likely root causes given the error description.
+- Request the full error message and stack trace, plus the relevant code snippet.
+- Ask about expected vs. actual behavior, programming language, and library versions.
 
-📋 Similar Templates Found
-1. AI Article Writing Template (92.1% similarity)
-2. Technical Blog Post Structure (85.6% similarity)
-*Use `search_templates` tool to explore your template library*
+*Response format: Step-by-step debugging walkthrough with a specific fix or next diagnostic steps.*
+```
 
-📊 Optimization Insights
+**Confidence:** 51.0% *(rules-based — LLM optimization typically 70–95%)*
+**AI Context:** code_generation
+```
 
-Performance Analysis:
-- Clarity improvement: +21.9%
-- Specificity boost: +17.3%  
-- Length optimization: +15.2%
+---
 
-Prompt Analysis:
-- Complexity level: intermediate
-- Optimization confidence: 87.3%
+## 🧠 AI Context Detection
 
-AI Recommendations:
-- Optimization achieved 87.3% confidence
-- Template automatically saved for future reference
-- Prompt optimized from 15 to 23 words
+The server automatically detects your prompt type and routes it to the appropriate optimization template. You can also specify `ai_context` manually in the tool call.
 
-*Professional analytics and improvement recommendations*
+| Context | `ai_context` value | Example patterns |
+|---|---|---|
+| Code & debugging | `code_generation` | `debug`, `fix`, `error`, `python`, `sql`, `refactor` |
+| Web development | `code_generation` | `landing page`, `react`, `css`, `html`, `tailwind` |
+| API & integration | `api_automation` | `api`, `rest`, `endpoint`, `oauth`, `webhook` |
+| DevOps & automation | `technical_automation` | `deploy`, `docker`, `ci/cd`, `terraform`, `bash` |
+| Data & schemas | `structured_output` | `json`, `schema`, `csv`, `yaml`, `transform` |
+| Analysis & research | `llm_interaction` | `analyze`, `explain`, `compare`, `research` |
+| Creative writing | `creative_writing` | `story`, `poem`, `script`, `blog`, `copywriting` |
+| Email & communication | `human_communication` | `email`, `letter`, `memo`, `formal`, `reply` |
+| Image generation | `image_generation` | `photorealistic`, `midjourney`, `dall-e`, `portrait` |
+| General | `general_assistant` | Everything else |
 
----
-*Professional cloud-based AI optimization with context awareness*
-💡 Manage account & configure models: https://promptoptimizer-blog.vercel.app/dashboard
-📊 Check quota: Use `get_quota_status` tool
-🔍 Search templates: Use `search_templates` tool
-```
+### Image Generation
 
-## 🔧 Universal MCP Client Support
+Image prompts are handled separately. The local fallback appends style-matched quality boosters directly to the prompt (comma-separated), rather than producing structured bullets. This matches how image generation models consume prompts.
 
-### Claude Desktop
-```json
-{
-  "mcpServers": {
-    "prompt-optimizer": {
-      "command": "npx",
-      "args": ["mcp-prompt-optimizer"],
-      "env": {
-        "OPTIMIZER_API_KEY": "sk-opt-your-key-here"
-      }
-    }
-  }
-}
 ```
-
-### Cursor IDE
-Add to `~/.cursor/mcp.json`:
-```json
-{
-  "mcpServers": {
-    "prompt-optimizer": {
-      "command": "npx", 
-      "args": ["mcp-prompt-optimizer"],
-      "env": {
-        "OPTIMIZER_API_KEY": "sk-opt-your-key-here"
-      }
-    }
-  }
-}
+Input:  "Draw a photorealistic portrait of an astronaut"
+Output: "Draw a photorealistic portrait of an astronaut, ultra realistic,
+         sharp focus, professional photography, dynamic lighting, balanced
+         composition, high quality, 4K"
 ```
 
-### Windsurf
-Configure in IDE settings or add to MCP configuration file.
-
-### Other MCP Clients
-- **Cline:** Standard MCP configuration
-- **VS Code:** MCP extension setup
-- **Zed:** MCP server configuration
-- **Replit:** Environment variable setup
-- **JetBrains IDEs:** MCP plugin configuration
-- **Emacs/Vim/Neovim:** MCP client setup
-
-## 🛠️ Available MCP Tools (for AI Agents & MCP Clients)
+---
 
-These tools are exposed via the Model Context Protocol (MCP) server and are intended for use by AI agents, MCP-compatible clients (like Claude Desktop, Cursor IDE), or custom scripts that interact with the server via stdin/stdout.
+## 🛠️ Available MCP Tools
 
 ### `optimize_prompt`
-**Professional AI optimization with context detection, auto-save, and insights.**
-```javascript
+AI optimization with context detection, auto-save, and insights.
+```json
 {
   "prompt": "Your prompt text",
-  "goals": ["clarity", "specificity"], // Optional: e.g., "clarity", "conciseness", "creativity", "technical_accuracy"
-  "ai_context": "llm_interaction", // Optional: Auto-detected if not specified. e.g., "code_generation", "image_generation"
-  "enable_bayesian": true // Optional: Enable Bayesian optimization features (if available in backend)
+  "goals": ["clarity", "specificity"],
+  "ai_context": "code_generation",
+  "enable_bayesian": true
 }
 ```
 
 ### `detect_ai_context`
-**Detects the AI context for a given prompt using advanced backend analysis.**
-```javascript
+Detect the AI context for a given prompt.
+```json
 {
   "prompt": "The prompt text for which to detect the AI context"
 }
 ```
 
 ### `create_template`
-**Create a new optimization template.**
-```javascript
+Save an optimization as a reusable template.
+```json
 {
-  "title": "Title of the template",
-  "description": "Description of the template", // Optional
-  "original_prompt": "The original prompt text",
-  "optimized_prompt": "The optimized prompt text",
-  "optimization_goals": ["clarity"], // Optional: e.g., ["clarity", "conciseness"]
-  "confidence_score": 0.9, // (0.0-1.0)
-  "model_used": "openai/gpt-4o-mini", // Optional
-  "optimization_tier": "llm", // Optional: e.g., "rules", "llm", "hybrid"
-  "ai_context_detected": "llm_interaction", // Optional: e.g., "code_generation", "image_generation"
-  "is_public": false, // Optional: Whether the template is public
-  "tags": ["marketing", "email"] // Optional
+  "title": "Template title",
+  "description": "Optional description",
+  "original_prompt": "The original prompt",
+  "optimized_prompt": "The optimized prompt",
+  "optimization_goals": ["clarity"],
+  "confidence_score": 0.9,
+  "ai_context_detected": "code_generation",
+  "is_public": false,
+  "tags": ["debugging", "python"]
 }
 ```
 
 ### `get_template`
-**Retrieve a specific template by its ID.**
-```javascript
+Retrieve a saved template by ID.
+```json
 {
   "template_id": "the-template-id"
 }
 ```
 
 ### `update_template`
-**Update an existing optimization template.**
-```javascript
+Update an existing template.
+```json
 {
   "template_id": "the-template-id",
-  "title": "New title for the template", // Optional
-  "description": "New description for the template", // Optional
-  "is_public": true // Optional: Update public status
-  // Other fields from 'create_template' can also be updated
+  "title": "Updated title",
+  "is_public": true
 }
 ```
 
 ### `search_templates`
-**Search your saved template library with AI-aware filtering.**
-```javascript
+Search your saved template library.
+```json
 {
-  "query": "blog post", // Optional: Search term to filter templates by content or title
-  "ai_context": "human_communication", // Optional: Filter templates by AI context type
-  "sophistication_level": "advanced", // Optional: Filter by template sophistication level
-  "complexity_level": "complex", // Optional: Filter by template complexity level
-  "optimization_strategy": "rules_only", // Optional: Filter by optimization strategy used
-  "limit": 5, // Optional: Number of templates to return (1-20)
-  "sort_by": "confidence_score", // Optional: e.g., "created_at", "usage_count", "title"
-  "sort_order": "desc" // Optional: "asc" or "desc"
+  "query": "debugging",
+  "ai_context": "code_generation",
+  "limit": 5,
+  "sort_by": "confidence_score",
+  "sort_order": "desc"
 }
 ```
 
 ### `get_quota_status`
-**Check subscription status, quota usage, and account information.**
-```javascript
-// No parameters needed
-```
+Check subscription status and quota usage. No parameters required.
 
-### `get_optimization_insights` (Conditional)
-**Get advanced Bayesian optimization insights, performance analytics, and parameter tuning recommendations.**
-*Note: This tool provides mock data if Bayesian optimization is disabled in the backend.*
-```javascript
+### `get_optimization_insights` *(conditional)*
+Bayesian optimization insights and parameter tuning recommendations. Requires the feature to be enabled in the backend; returns mock data otherwise.
+```json
 {
-  "analysis_depth": "detailed", // Optional: "basic", "detailed", "comprehensive"
-  "include_recommendations": true // Optional: Include optimization recommendations
+  "analysis_depth": "detailed",
+  "include_recommendations": true
 }
 ```
 
-### `get_real_time_status` (Conditional)
-**Get real-time optimization status and AG-UI capabilities.**
-*Note: This tool provides mock data if AG-UI features are disabled in the backend.*
-```javascript
-// No parameters needed
-```
+### `get_real_time_status` *(conditional)*
+Real-time optimization status and AG-UI capabilities. Requires the feature to be enabled in the backend; returns mock data otherwise. No parameters required.
 
 ---
 
-## 🔧 Professional CLI Commands (Direct Execution)
+## 🎛️ Advanced Model Configuration (Optional)
 
-These are direct command-line tools provided by the `mcp-prompt-optimizer` executable for administrative and diagnostic purposes.
+Configure custom models in the WebUI and the MCP server uses them automatically.
 
-```bash
-# Check API key and quota status
-mcp-prompt-optimizer check-status
+**Step 1 — Configure in WebUI:**
+1. Visit [Dashboard](https://promptoptimizer-blog.vercel.app/dashboard)
+2. Go to Settings → User Settings
+3. Add your OpenRouter API key (from [openrouter.ai](https://openrouter.ai))
+4. Select your preferred models for optimization and evaluation
+
+**Step 2 — Use the npm package as normal.** Your WebUI model settings are applied automatically — no changes to the MCP configuration required.
+
+### Model Selection Priority
+```
+1. Your WebUI-configured models  (highest priority)
+2. Request-specific model override
+3. System default (google/gemini-flash-1.5-8b)
+```
+
+### Example Model Recommendations
+
+| Use case | Optimization model | Evaluation model |
+|---|---|---|
+| Creative / complex | `anthropic/claude-3-5-sonnet` | `google/gemini-pro-1.5` |
+| Fast / simple | `openai/gpt-4o-mini` | `openai/gpt-3.5-turbo` |
+| Code / technical | `anthropic/claude-3-5-sonnet` | `anthropic/claude-3-haiku` |
+
+> **Two different API keys:**
+> - **Service key** (`sk-opt-*`) — your MCP Prompt Optimizer subscription
+> - **OpenRouter key** — your personal OpenRouter account for model usage costs
 
-# Validate API key with backend
-mcp-prompt-optimizer validate-key
+---
+
+## 💰 Subscription Plans
 
-# Test backend integration
-mcp-prompt-optimizer test
+| Plan | Price | Optimizations/month | Team members |
+|---|---|---|---|
+| 🎯 Explorer | $2.99/mo | 5,000 | 1 |
+| 🎨 Creator | $25.99/mo | 18,000 | 2 + 3 keys |
+| 🚀 Innovator | $69.99/mo | 75,000 | 5 + 10 keys |
 
-# Run comprehensive diagnostic
-mcp-prompt-optimizer diagnose
+🆓 **Free trial:** 5 optimizations with full feature access.
 
-# Clear validation cache
-mcp-prompt-optimizer clear-cache
+All plans include AI context detection, template management, personal model configuration, and optimization insights.
 
-# Show help and setup instructions
-mcp-prompt-optimizer help
+---
 
-# Show version information
-mcp-prompt-optimizer version
+## 🔧 CLI Commands
+
+```bash
+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
+mcp-prompt-optimizer version        # Show version information
 ```
 
-## 🏢 Team Collaboration Features
+---
+
+## 🏢 Team Collaboration
 
 ### Team API Keys (`sk-team-*`)
-- **Shared quotas** across team members
-- **Centralized billing** and management
-- **Team template libraries** for consistency
-- **Role-based access** control
-- **Team usage analytics**
+- Shared quotas across team members
+- Centralized billing and management
+- Team template libraries for consistency
+- Role-based access control
 
 ### Individual API Keys (`sk-opt-*`)
-- **Personal quotas** and billing
-- **Individual template libraries**
-- **Personal usage tracking**
-- **Account self-management**
+- Personal quotas and billing
+- Individual template libraries
+- Account self-management
+
+---
 
 ## 🔐 Security & Privacy
 
-- **Enterprise-grade security** with encrypted data transmission
-- **API key validation** with secure backend authentication
-- **Quota enforcement** with real-time usage tracking
-- **Professional uptime** with 99.9% availability SLA
-- **GDPR compliant** data handling and processing
-- **No data retention** - prompts processed and optimized immediately
-
-## 📈 Advanced Features
-
-### Automatic Template Management
-- **Auto-save** high-confidence optimizations (>70% confidence)
-- **Intelligent categorization** by AI context and content type
-- **Similarity search** to find related templates
-- **Template analytics** with usage patterns and effectiveness
-
-### Real-time Optimization Insights
-- **Performance metrics** - clarity, specificity, length improvements
-- **Confidence scoring** with detailed analysis
-- **AI-powered recommendations** for continuous improvement
-- **Usage analytics** and optimization patterns
-*Note: Advanced features like Bayesian Optimization and AG-UI Real-time Features are configurable and may provide mock data if disabled in the backend.*
-
-### Intelligent Context Routing
-- **Automatic detection** of prompt context and intent
-- **Goal enhancement** based on detected context
-- **Parameter preservation** for technical prompts
-- **Context-specific optimizations** for better results
-
-## 🚀 Getting Started
-
-### 🏃‍♂️ Fast Start (System Defaults)
-1. **Sign up** at [promptoptimizer-blog.vercel.app/pricing](https://promptoptimizer-blog.vercel.app/pricing)
-2. **Install** the MCP server: `npm install -g mcp-prompt-optimizer`
-3. **Configure** your MCP client with your API key
-4. **Start optimizing** with intelligent AI context detection!
-
-### 🎛️ Advanced Start (Custom Models)
-1. **Sign up** at [promptoptimizer-blog.vercel.app/pricing](https://promptoptimizer-blog.vercel.app/pricing)
-2. **Configure WebUI** at [dashboard](https://promptoptimizer-blog.vercel.app/dashboard) with your OpenRouter key & models
-3. **Install** the MCP server: `npm install -g mcp-prompt-optimizer`
-4. **Configure** your MCP client with your API key
-5. **Enjoy enhanced optimization** with your chosen models!
-
-## 🔄 Migration to v3.0.0
-
-### ⚠️ Breaking Changes from v2.x
-
-**IMPORTANT:** v3.0.0 includes security enhancements that remove authentication bypasses.
-
-**What Changed:**
-- ❌ `OPTIMIZER_DEV_MODE=true` no longer works
-- ❌ `NODE_ENV=development` no longer enables mock mode
-- ❌ Offline mode has been removed
-- ✅ All API keys must be validated against backend server
-- ✅ Internet connection required (1-2 hour caching for reliability)
-
-**Migration Steps:**
-```bash
-# 1. Ensure you have a valid API key
-export OPTIMIZER_API_KEY="sk-opt-your-key-here"
+- Encrypted data transmission
+- API key validation with secure backend authentication
+- Quota enforcement with real-time usage tracking
+- No prompt data retained — processed and discarded immediately
+- GDPR compliant
 
-# 2. Update to v3.0.0
-npm update -g mcp-prompt-optimizer
+---
 
-# 3. Verify it works
-mcp-prompt-optimizer --version  # Should show 3.0.0
+## 🔧 Universal MCP Client Support
+
+### Claude Desktop
+```json
+{
+  "mcpServers": {
+    "prompt-optimizer": {
+      "command": "npx",
+      "args": ["mcp-prompt-optimizer"],
+      "env": { "OPTIMIZER_API_KEY": "sk-opt-your-key-here" }
+    }
+  }
+}
 ```
 
-**For Developers:**
-- Mock mode removed - use real test API keys from backend database
-- Development keys (`sk-dev-*`) must be real keys, not mocked
-- Offline testing no longer supported - backend connection required
+### Cursor IDE
+Add to `~/.cursor/mcp.json`:
+```json
+{
+  "mcpServers": {
+    "prompt-optimizer": {
+      "command": "npx",
+      "args": ["mcp-prompt-optimizer"],
+      "env": { "OPTIMIZER_API_KEY": "sk-opt-your-key-here" }
+    }
+  }
+}
+```
 
-**Cache Behavior:**
-- Primary cache: 1 hour
-- Network failure fallback: Up to 2 hours
-- After 2 hours: Must reconnect to backend
+### Other clients
+Windsurf, Cline, VS Code, Zed, Replit, JetBrains IDEs, and Neovim are all supported via standard MCP server configuration.
 
-## 📞 Support & Resources
+---
+
+## 📦 Changelog
+
+### v3.0.3
+- **Rules fallback output rewritten** — local optimization now produces user-facing prose prompts instead of raw XML scaffolding. The output is directly usable as a prompt without modification.
+- **All 18 local templates reworded** — template principles are now phrased as user request guidance rather than AI-assistant directives, producing more natural and actionable structured prompts.
+- **`creative_writing` context** now routes correctly to the creative writing template (previously fell through to a generic fallback).
+- **`general_assistant` context** now maps explicitly to the LLM interaction template.
+- **Backend rules-tier detection** — when the backend returns confidence below 25% (indicating it ran its own rules tier without an LLM), a note appears explaining the cause and how to resolve it (`OPENROUTER_API_KEY` configuration).
+- **Confidence scale annotation** — rules-based fallback confidence now shows `*(rules-based — LLM optimization typically 70–95%)*` so users understand where their result sits relative to full LLM optimization.
+
+### v3.0.2
+- Cross-platform binary compatibility improvements
+- Bayesian optimization integration
+- AG-UI feature flag support
 
-- **📚 Documentation:** https://promptoptimizer-blog.vercel.app/docs
-- **💬 Community Support:** GitHub Discussions
-- **📧 Email Support:** support@promptoptimizer.help (Creator/Innovator)
-- **🏢 Enterprise:** enterprise@promptoptimizer.help
-- **📊 Dashboard & Model Config:** https://promptoptimizer-blog.vercel.app/dashboard
-- **🔧 Troubleshooting:** https://promptoptimizer-blog.vercel.app/docs/troubleshooting
-
-## 🌟 Why Choose MCP Prompt Optimizer?
-
-✅ **Professional Quality** - Enterprise-grade optimization with consistent results  
-✅ **Universal Compatibility** - Works with 10+ MCP clients out of the box  
-✅ **AI Context Awareness** - Intelligent optimization based on prompt type  
-✅ **Personal Model Choice** - Use your own OpenRouter models & pay-per-use  
-✅ **Template Management** - Build and reuse optimization patterns  
-✅ **Team Collaboration** - Shared resources and centralized management  
-✅ **Real-time Analytics** - Track performance and improvement over time  
-✅ **Startup Validation** - Comprehensive error handling and troubleshooting  
-✅ **Professional Support** - From community to enterprise-level assistance  
+### v3.0.0
+- API key now required for all operations
+- Development mode and offline mode removed for security
+- All keys validated against backend server
 
 ---
 
-**🚀 Professional MCP Server** - Built for serious AI development with intelligent context detection, comprehensive template management, personal model configuration, and enterprise-grade reliability.
+## 📞 Support & Resources
+
+- **Documentation:** https://promptoptimizer-blog.vercel.app/docs
+- **Dashboard & model config:** https://promptoptimizer-blog.vercel.app/dashboard
+- **Troubleshooting:** https://promptoptimizer-blog.vercel.app/docs/troubleshooting
+- **Community support:** GitHub Discussions
+- **Email support:** support@promptoptimizer.help (Creator/Innovator plans)
+- **Enterprise:** enterprise@promptoptimizer.help
+
+---
 
-*Get started with 5 free optimizations at [promptoptimizer-blog.vercel.app/pricing](https://promptoptimizer-blog.vercel.app/pricing)*
+*Get started with 5 free optimizations at [promptoptimizer-blog.vercel.app/pricing](https://promptoptimizer-blog.vercel.app/pricing)*