mcp-prompt-optimizer 1.4.2 → 2.2.3

package/CHANGELOG.md

@@ -1,71 +1,96 @@
 # Changelog
 
-All notable changes to the MCP Prompt Optimizer will be documented in this file.
+All notable changes to this project will be documented in this file.
 
-## [1.4.0] - 2025-07-28 - ✨ Backend Alignment & Feature Completion
+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).
 
-### ✨ Features & Alignment
-- **ALIGNED**: Fully aligned request payloads and response handling with the latest backend API for enhanced reliability.
-- **ENHANCED**: AI Context Detection now correctly recognizes `structured_output`, `code_generation`, and `api_automation`, providing more accurate, context-aware optimizations.
-- **ADDED**: `search_templates` and `get_quota_status` tools are now fully implemented and validated.
-- **IMPROVED**: Response formatting for all tools provides a richer, more detailed, and user-friendly experience.
-- **VALIDATED**: The comprehensive startup validation and CLI command suite (`diagnose`, `test`, `check-status`) are now fully functional and tested.
-- **FIXED**: Corrected all version inconsistencies across the package for stable dependency management.
+## [1.5.0] - 2025-09-25
 
----
+### Added
+- 🧠 **Bayesian Optimization Support**: Advanced parameter tuning and performance prediction
+- ⚡ **AG-UI Real-Time Features**: Streaming optimization and WebSocket support
+- 🎯 **Enhanced AI Context Detection**: Improved weighted scoring system with 7 contexts
+- 📊 **Advanced Analytics**: New `get_optimization_insights` tool for Bayesian metrics
+- 🚀 **Real-Time Status**: New `get_real_time_status` tool for live optimization monitoring
+- 🔧 **Feature Flags**: `ENABLE_BAYESIAN_OPTIMIZATION` and `ENABLE_AGUI_FEATURES` environment variables
+- 📋 **Enhanced Template Search**: AI-aware filtering by sophistication, complexity, and strategy
+- 🎨 **Rich Formatting**: Improved output formatting with better visual organization
+
+### Changed
+- 🔄 **Backend API Alignment**: Updated to align with FastAPI Backend production-v2.1.0-bayesian
+- 🎯 **Context Detection**: Upgraded algorithm with weighted scoring and negative patterns
+- 📊 **Quota Display**: Enhanced quota status with visual indicators and feature breakdown
+- 🔍 **Template Search**: Expanded search parameters and improved result formatting
+- 🚀 **Startup Process**: Enhanced validation with feature status reporting
+
+### Fixed
+- ✅ **API Endpoints**: Corrected backend endpoint URLs for full compatibility
+- 🛡️ **Error Handling**: Improved fallback mechanisms for network issues
+- 📝 **Template Display**: Fixed template preview and confidence score formatting
+- 🔧 **Environment Variables**: Better handling of feature flag defaults
 
-## [1.1.0] - 2025-07-05
+### Technical
+- 📦 **Dependencies**: Updated to latest MCP SDK version
+- 🏗️ **Architecture**: Modular feature system with conditional tool loading
+- 🧪 **Testing**: Enhanced mock responses for development mode
+- 📖 **Documentation**: Updated tool descriptions and parameter schemas
 
-### 🎯 Smart Tier-Aware Features
-- **NEW**: Smart tier detection and feature delivery
-- **NEW**: Auto-save templates for high-confidence optimizations (Creator/Innovator)
-- **NEW**: Similar template search and discovery (Creator/Innovator)
-- **NEW**: Advanced optimization insights and analytics (Innovator)
-- **NEW**: Performance improvement metrics (Innovator)
-- **NEW**: AI-powered optimization recommendations (Innovator)
+### Backend Compatibility
+- ✅ **API Version**: v1 (aligned with FastAPI backend)
+- ✅ **Endpoint Mapping**: `/api/v1/mcp/*` endpoints fully supported
+- ✅ **Feature Parity**: All backend features now accessible via MCP
+- ✅ **Error Codes**: Proper HTTP status code handling and user-friendly messages
 
-### ✨ Enhanced User Experience
-- **IMPROVED**: Tier-aware response formatting
-- **NEW**: Upgrade prompts and value progression
-- **IMPROVED**: Error messages with tier-specific guidance
-- **NEW**: Professional messaging for each tier level
+## [2.2.3] - 2025-11-01
 
-### 🔧 Technical Improvements
-- **UPDATED**: Backend integration for smart endpoint
-- **IMPROVED**: Response parsing and formatting
-- **NEW**: Graceful handling of template save failures
-- **UPDATED**: Tool descriptions to reflect smart features
+### Fixed
+- ✅ **API Key Validation**: Corrected `sk-local-*` API key validation, ensuring they are properly validated against the backend instead of being treated as mock keys.
+- ✅ **Context Detection Error**: Resolved `Cannot read properties of undefined (reading 'name')` error in `generateMockContextDetection` by adding robust checks for `detected_parameters`.
+- ✅ **Quick Test Failures**: Updated `quick-test.js` to align with current API, fixing `AI Context detection` and removing `Goal enhancement` test.
 
-### 📚 Documentation
-- **UPDATED**: README with tier-specific examples
-- **NEW**: Complete feature matrix by tier
-- **UPDATED**: Setup instructions for smart features
-- **NEW**: Example responses for all tier levels
+### Changed
+- 🔄 **Endpoint Management**: Centralized all backend API endpoints into a new `ENDPOINTS` object for improved maintainability and consistency.
+- 🧠 **Mock Context Detection**: Enhanced `generateMockContextDetection` logic with more accurate keyword matching for `code_generation`, `image_generation`, and `llm_interaction` contexts.
+- 🔧 **CLI Flag Defaults**: Clarified default behavior for `ENABLE_BAYESIAN_OPTIMIZATION` and `ENABLE_AGUI_FEATURES` environment variables.
+- ⏱️ **Timeout Handling**: Removed redundant `req.setTimeout` call in `callBackendAPI` for cleaner and more consistent timeout management.
+- 🛡️ **Defensive Checks**: Added defensive checks for blindly accessed metrics in `formatOptimizationResult` to prevent errors from slim backend responses.
+- 📝 **Logging**: Improved `startValidatedMCPServer` logging by using `console.log` for informational messages.
+- 📖 **Documentation**: Updated `README.md` to reflect changes in API key usage and context detection patterns.
 
-### 🐛 Bug Fixes
-- **FIXED**: Response formatting for complex nested data
-- **FIXED**: Error handling for backend communication
-- **IMPROVED**: Fallback behavior for missing features
+### Removed
+- 📦 **Test Scripts from Package**: Excluded `tests/` directory from the published npm package to reduce package size and focus on core functionality.
 
----
+## [2.2.0] - 2025-10-31
 
-## [1.0.2] - 2024-12-17
+### Changed
+- 🔄 **Backend API Alignment**: Updated to align with FastAPI Backend production-v2.2.0-stable
+- 🛠️ **Tool Refinement**: Refined `create_template`, `get_template`, `update_template`, and `detect_ai_context` tools for enhanced functionality and robustness.
 
 ### Fixed
-- Package installation issues
-- Binary execution permissions
-- Configuration file handling
+- ✅ **API Endpoints**: Ensured all backend endpoint URLs are fully compatible and robust.
+
+### Technical
+- 📦 **Dependencies**: Updated to latest MCP SDK version for improved stability.
+- 🧪 **Testing**: Comprehensive internal testing to ensure full alignment between NPM package and FastAPI backend.
 
-## [1.0.1] - 2024-12-17
+## [1.4.1] - 2025-09-15
+
+### Fixed
+- API key format validation
+- Template auto-save threshold
+
+## [1.4.0] - 2025-09-10
 
 ### Added
-- Initial MCP server implementation
-- Basic prompt optimization via remote API
-- Claude Desktop integration
-- Setup wizard for API key configuration
-
-### Features
-- Remote optimization using AI-Enhanced Prompt Optimizer API
-- MCP protocol compliance
-- Cross-platform support (Windows, macOS, Linux)
-- Global npm installation support
+- Template auto-save feature
+- Basic optimization insights
+- Cross-platform support improvements
+
+### Changed
+- Improved context detection
+- Enhanced error messages
+
+## [1.3.x] - Previous Versions
+
+Historical versions with basic prompt optimization functionality.

package/CROSS-PLATFORM.md

@@ -38,7 +38,7 @@ $env:OPTIMIZER_API_KEY = "sk-opt-your-key-here"
 mcp-prompt-optimizer
 
 # Command Prompt
-set OPTIMIZER_API_KEY=sk-opt-your-key-here
+set OPTIMIZER_API_KEY=sk-local-your-key-here
 mcp-prompt-optimizer
 
 # Or use the Windows-specific development script
@@ -49,7 +49,7 @@ npm run dev:windows
 
 ```bash
 # Bash/Zsh
-export OPTIMIZER_API_KEY="sk-opt-your-key-here"
+export OPTIMIZER_API_KEY="sk-local-your-key-here"
 mcp-prompt-optimizer
 
 # Or use the Unix-specific development script
@@ -116,7 +116,7 @@ All environment variables work consistently across platforms:
 
 ```bash
 # Core configuration
-OPTIMIZER_API_KEY=sk-opt-your-key-here
+OPTIMIZER_API_KEY=sk-local-your-key-here
 OPTIMIZER_BACKEND_URL=https://custom-backend.com
 OPTIMIZER_DEV_MODE=true
 NODE_ENV=development

package/README.md

@@ -1,4 +1,4 @@
-# MCP Prompt Optimizer
+# MCP Prompt Optimizer v2.2.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.
 
@@ -7,7 +7,7 @@
 🧠 **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  
+📊 **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  
@@ -20,7 +20,7 @@ npm install -g mcp-prompt-optimizer
 ```
 
 **2. Get your API key:**
-Visit [https://promptoptimizer-blog.vercel.app/pricing](https://promptoptimizer-blog.vercel.app/pricing) for your free trial (5 optimizations)
+Visit [https://promptoptimizer-blog.vercel.app/pricing](https://promptoptimizer-blog.vercel.app/pricing) for your free tier (`sk-local-*` key, 5 optimizations per day)
 
 **3. Configure Claude Desktop:**
 Add to your `~/.claude/claude_desktop_config.json`:
@@ -31,7 +31,7 @@ Add to your `~/.claude/claude_desktop_config.json`:
       "command": "npx",
       "args": ["mcp-prompt-optimizer"],
       "env": {
-        "OPTIMIZER_API_KEY": "sk-opt-your-key-here"
+        "OPTIMIZER_API_KEY": "sk-local-your-key-here"  // Use sk-local-* for free tier, sk-opt-* for paid subscriptions
       }
     }
   }
@@ -158,16 +158,25 @@ Input: "A beautiful landscape --ar 16:9 --v 6"
 ```
 
 ### 🤖 LLM Interaction Context  
-**Detected patterns:** `act as`, `you are a`, `role:`, `persona:`, `behave like`
+**Detected patterns:** `analyze`, `explain`, `evaluate`, `summary`, `research`, `paper`, `analysis`, `interpret`, `discussion`, `assessment`, `compare`, `contrast`
 ```
-Input: "Act as a professional writer and help me with..."
+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
 ```
 
+### 💻 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
+```
+
 ### ⚙️ Technical Automation Context
-**Detected patterns:** `def`, `function`, `execute`, `script`, `automation`
+**Detected patterns:** `automate`, `script`, `api`
 ```
 Input: "Create a script to automate deployment process"
 ✅ Enhanced goals: technical_accuracy, parameter_preservation, precision
@@ -272,60 +281,110 @@ Configure in IDE settings or add to MCP configuration file.
 - **JetBrains IDEs:** MCP plugin configuration
 - **Emacs/Vim/Neovim:** MCP client setup
 
-## 🛠️ Available Tools
+## 🛠️ 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.
 
 ### `optimize_prompt`
-**Professional AI optimization with context detection**
+**Professional AI optimization with context detection, auto-save, and insights.**
 ```javascript
 {
   "prompt": "Your prompt text",
-  "goals": ["clarity", "specificity"], // Optional
-  "ai_context": "llm_interaction" // Auto-detected if not specified
+  "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)
 }
 ```
 
-### `get_quota_status`
-**Check subscription status and usage**
+### `detect_ai_context`
+**Detects the AI context for a given prompt using advanced backend analysis.**
 ```javascript
-// No parameters needed
+{
+  "prompt": "The prompt text for which to detect the AI context"
+}
+```
+
+### `create_template`
+**Create a new optimization template.**
+```javascript
+{
+  "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
+}
+```
+
+### `get_template`
+**Retrieve a specific template by its ID.**
+```javascript
+{
+  "template_id": "the-template-id"
+}
+```
+
+### `update_template`
+**Update an existing optimization template.**
+```javascript
+{
+  "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
+}
 ```
 
 ### `search_templates`
-**Search your saved template library**
+**Search your saved template library with AI-aware filtering.**
 ```javascript
 {
-  "query": "blog post", // Optional
-  "ai_context": "human_communication", // Optional filter
-  "limit": 5 // Max results
+  "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"
 }
 ```
 
-## 🎯 Optimization Goals
+### `get_quota_status`
+**Check subscription status, quota usage, and account information.**
+```javascript
+// No parameters needed
+```
 
-- **clarity** - Make prompts clearer and more understandable
-- **conciseness** - Remove unnecessary words while preserving meaning
-- **creativity** - Enhance creative and imaginative aspects
-- **specificity** - Add specific details and concrete examples
-- **actionability** - Make prompts more directive and actionable
-- **technical_accuracy** - Improve technical precision and terminology
-- **keyword_density** - Optimize keyword placement and density
-- **parameter_preservation** - Preserve technical parameters (for image gen/code)
-- **context_specificity** - Enhance context-specific clarity
-- **token_efficiency** - Optimize for AI token usage
+### `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
+{
+  "analysis_depth": "detailed", // Optional: "basic", "detailed", "comprehensive"
+  "include_recommendations": true // Optional: Include optimization recommendations
+}
+```
 
-## 🤖 AI Context Types
+### `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
+```
 
-- **human_communication** - Emails, letters, social content
-- **llm_interaction** - AI conversations, role-playing prompts
-- **image_generation** - Image/art generation prompts (Midjourney, DALL-E)
-- **technical_automation** - DevOps, system administration, scripts
-- **structured_output** - JSON, data formats, templates
-- **code_generation** - Programming and development prompts
-- **api_automation** - API calls, integrations, workflows
+---
 
-## 🔧 Professional CLI Tools
+## 🔧 Professional CLI Commands (Direct Execution)
 
-Enhanced command-line tools for power users:
+These are direct command-line tools provided by the `mcp-prompt-optimizer` executable for administrative and diagnostic purposes.
 
 ```bash
 # Check API key and quota status
@@ -387,6 +446,7 @@ mcp-prompt-optimizer version
 - **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