fix: Disable magic MCP server for Gemini CLI compatibility

The @21st-dev/magic package exports tool names starting with '21st_'
(e.g., 21st_magic_component_builder) which violates Gemini's function
naming rules that require names to start with a letter or underscore.

Changes:
- Add gemini_compatible flag to MCP server definitions
- Install incompatible servers to _disabledMcpServers with warning
- Add compatibility warning to MCP_Magic.md documentation
- Add _geminiCompatibility note to magic.json config

The magic server will be automatically installed as DISABLED until
the upstream package is updated with compliant tool names.

Author: mithun50

SuperGemini/MCP/MCP_Magic.md

@@ -2,6 +2,18 @@
 
 **Purpose**: Modern UI component generation from 21st.dev patterns with design system integration
 
+## Gemini CLI Compatibility Warning
+
+**Status**: NOT COMPATIBLE with Gemini CLI (as of December 2025)
+
+**Issue**: The `@21st-dev/magic` package exports tool names that start with `21st_` (e.g., `21st_magic_component_builder`). Gemini's API requires function names to start with a letter or underscore, not a number.
+
+**Error**: `[FIELD_INVALID] Invalid function name. Must start with a letter or an underscore.`
+
+**Workaround**: SuperGemini automatically installs this server as DISABLED. You can enable it once the `@21st-dev/magic` package is updated to use compliant tool names.
+
+**Tracking**: This issue affects Gemini CLI only. The magic server works fine with Claude Code and other MCP clients.
+
 ## Triggers
 - UI component requests: button, form, modal, card, table, nav
 - Design system implementation needs

SuperGemini/MCP/configs/magic.json

@@ -7,6 +7,7 @@
     ],
     "env": {
       "TWENTYFIRST_API_KEY": ""
-    }
+    },
+    "_geminiCompatibility": "NOT_COMPATIBLE - Tool names start with '21st_' which violates Gemini function naming rules"
   }
 }

setup/components/mcp.py

@@ -55,7 +55,9 @@ def __init__(self, install_dir: Optional[Path] = None):
                 "config_file": "magic.json",
                 "npm_package": "@21st-dev/magic",
                 "requires_api_key": True,
-                "api_key_env": "TWENTYFIRST_API_KEY"
+                "api_key_env": "TWENTYFIRST_API_KEY",
+                "gemini_compatible": False,
+                "incompatibility_reason": "Tool names start with '21st_' which violates Gemini's function naming rules (must start with letter/underscore, not number)"
             },
             "playwright": {
                 "name": "playwright",
@@ -727,21 +729,40 @@ def _install(self, config: Dict[str, Any]) -> bool:
                     display_info(f"Server '{server_key}' requires API key: {api_key_env}")
                     display_info("You can set this environment variable later")
 
-            # Always enable newly managed servers by default
-            target_section = "mcpServers"
+            # Check Gemini compatibility - install incompatible servers as disabled
+            is_gemini_compatible = server_info.get("gemini_compatible", True)
 
-            # If the server was previously disabled, remove the stale entry
-            if server_key in gemini_config.get("_disabledMcpServers", {}):
-                try:
-                    del gemini_config["_disabledMcpServers"][server_key]
-                except KeyError:
-                    pass
+            if is_gemini_compatible:
+                # Enable compatible servers by default
+                target_section = "mcpServers"
+
+                # If the server was previously disabled, remove the stale entry
+                if server_key in gemini_config.get("_disabledMcpServers", {}):
+                    try:
+                        del gemini_config["_disabledMcpServers"][server_key]
+                    except KeyError:
+                        pass
+
+                self.logger.debug(f"Server '{server_key}' installed as enabled")
+            else:
+                # Install incompatible servers as disabled with explanation
+                target_section = "_disabledMcpServers"
+                incompatibility_reason = server_info.get("incompatibility_reason", "Not compatible with Gemini CLI")
 
-            # Merge server config into active section
+                # Add disabled reason to the config
+                for server_name in server_config:
+                    server_config[server_name]["_disabledReason"] = incompatibility_reason
+
+                # Warn user about incompatibility
+                display_warning(f"Server '{server_key}' is NOT compatible with Gemini CLI!")
+                display_warning(f"Reason: {incompatibility_reason}")
+                display_info(f"Installing '{server_key}' as DISABLED. You can enable it when the package is updated.")
+
+                self.logger.warning(f"Server '{server_key}' installed as DISABLED due to Gemini incompatibility")
+
+            # Merge server config into appropriate section
             self._merge_mcp_server_config(gemini_config[target_section], server_config, server_key)
             configured_count += 1
-
-            self.logger.debug(f"Server '{server_key}' installed as enabled")
 
         # Save updated configuration
         if configured_count > 0: