Fix for: https://github.com/BeehiveInnovations/zen-mcp-server/issues/101

Fix for: https://github.com/BeehiveInnovations/zen-mcp-server/issues/102

- Removed centralized MODEL_CAPABILITIES_DESC from config.py
- Added model descriptions to individual provider SUPPORTED_MODELS
- Updated _get_available_models() to use ModelProviderRegistry for API key filtering
- Added comprehensive test suite validating bug reproduction and fix

providers/base.py

@@ -175,6 +175,9 @@ class ModelResponse:
 class ModelProvider(ABC):
     """Abstract base class for model providers."""
 
+    # All concrete providers must define their supported models
+    SUPPORTED_MODELS: dict[str, Any] = {}
+
     def __init__(self, api_key: str, **kwargs):
         """Initialize the provider with API key and optional configuration."""
         self.api_key = api_key

providers/gemini.py

@@ -25,6 +25,7 @@ class GeminiModelProvider(ModelProvider):
             "max_thinking_tokens": 24576,  # Flash 2.5 thinking budget limit
             "supports_images": True,  # Vision capability
             "max_image_size_mb": 20.0,  # Conservative 20MB limit for reliability
+            "description": "Ultra-fast (1M context) - Quick analysis, simple queries, rapid iterations",
         },
         "gemini-2.5-pro": {
             "context_window": 1_048_576,  # 1M tokens
@@ -32,6 +33,7 @@ class GeminiModelProvider(ModelProvider):
             "max_thinking_tokens": 32768,  # Pro 2.5 thinking budget limit
             "supports_images": True,  # Vision capability
             "max_image_size_mb": 32.0,  # Higher limit for Pro model
+            "description": "Deep reasoning + thinking mode (1M context) - Complex problems, architecture, deep analysis",
         },
         # Shorthands
         "flash": "gemini-2.5-flash",

providers/openai_provider.py

@@ -26,6 +26,7 @@ class OpenAIModelProvider(OpenAICompatibleProvider):
             "max_image_size_mb": 20.0,  # 20MB per OpenAI docs
             "supports_temperature": False,  # O3 models don't accept temperature parameter
             "temperature_constraint": "fixed",  # Fixed at 1.0
+            "description": "Strong reasoning (200K context) - Logical problems, code generation, systematic analysis",
         },
         "o3-mini": {
             "context_window": 200_000,  # 200K tokens
@@ -34,6 +35,7 @@ class OpenAIModelProvider(OpenAICompatibleProvider):
             "max_image_size_mb": 20.0,  # 20MB per OpenAI docs
             "supports_temperature": False,  # O3 models don't accept temperature parameter
             "temperature_constraint": "fixed",  # Fixed at 1.0
+            "description": "Fast O3 variant (200K context) - Balanced performance/speed, moderate complexity",
         },
         "o3-pro-2025-06-10": {
             "context_window": 200_000,  # 200K tokens
@@ -42,6 +44,7 @@ class OpenAIModelProvider(OpenAICompatibleProvider):
             "max_image_size_mb": 20.0,  # 20MB per OpenAI docs
             "supports_temperature": False,  # O3 models don't accept temperature parameter
             "temperature_constraint": "fixed",  # Fixed at 1.0
+            "description": "Professional-grade reasoning (200K context) - EXTREMELY EXPENSIVE: Only for the most complex problems requiring universe-scale complexity analysis OR when the user explicitly asks for this model. Use sparingly for critical architectural decisions or exceptionally complex debugging that other models cannot handle.",
         },
         # Aliases
         "o3-pro": "o3-pro-2025-06-10",
@@ -52,6 +55,7 @@ class OpenAIModelProvider(OpenAICompatibleProvider):
             "max_image_size_mb": 20.0,  # 20MB per OpenAI docs
             "supports_temperature": False,  # O4 models don't accept temperature parameter
             "temperature_constraint": "fixed",  # Fixed at 1.0
+            "description": "Latest reasoning model (200K context) - Optimized for shorter contexts, rapid reasoning",
         },
         "o4-mini-high": {
             "context_window": 200_000,  # 200K tokens
@@ -60,6 +64,7 @@ class OpenAIModelProvider(OpenAICompatibleProvider):
             "max_image_size_mb": 20.0,  # 20MB per OpenAI docs
             "supports_temperature": False,  # O4 models don't accept temperature parameter
             "temperature_constraint": "fixed",  # Fixed at 1.0
+            "description": "Enhanced O4 mini (200K context) - Higher reasoning effort for complex tasks",
         },
         "gpt-4.1-2025-04-14": {
             "context_window": 1_000_000,  # 1M tokens
@@ -68,6 +73,7 @@ class OpenAIModelProvider(OpenAICompatibleProvider):
             "max_image_size_mb": 20.0,  # 20MB per OpenAI docs
             "supports_temperature": True,  # Regular models accept temperature parameter
             "temperature_constraint": "range",  # 0.0-2.0 range
+            "description": "GPT-4.1 (1M context) - Advanced reasoning model with large context window",
         },
         # Shorthands
         "mini": "o4-mini",  # Default 'mini' to latest mini model

providers/xai.py

@@ -24,10 +24,12 @@ class XAIModelProvider(OpenAICompatibleProvider):
         "grok-3": {
             "context_window": 131_072,  # 131K tokens
             "supports_extended_thinking": False,
+            "description": "GROK-3 (131K context) - Advanced reasoning model from X.AI, excellent for complex analysis",
         },
         "grok-3-fast": {
             "context_window": 131_072,  # 131K tokens
             "supports_extended_thinking": False,
+            "description": "GROK-3 Fast (131K context) - Higher performance variant, faster processing but more expensive",
         },
         # Shorthands for convenience
         "grok": "grok-3",  # Default to grok-3