refactor: code review cleanup — remove dead code, factor helpers, fix tests

- Remove duplicate meta-server sections in CREATE and EDIT modals (admin.html)
- Remove dead imports: ToolEmbedding, top-level or_ (service.py)
- Fix docstring: meta-server exposes 12 tools, not 6 (service.py)
- Factor _resolve_effective_email() helper for JWT extraction (service.py)
- Factor _apply_scope_header() helper for X-Scope processing (meta_router.py)
- Move inline 'import json' to module level (meta_router.py)
- Fix test assertion: len(defs) == 12, add new meta-tool assertions (test_meta_server.py)

Signed-off-by: Olivier Gintrand <olivier.gintrand@forterro.com>

Author: Olivier Gintrand

mcpgateway/meta_server/service.py

@@ -35,11 +35,8 @@
 import time
 from typing import Any, Dict, List, Optional, Set
 
-# Third-Party
-from sqlalchemy import or_
-
 # First-Party
-from mcpgateway.db import fresh_db_session, get_db, Tool, ToolEmbedding
+from mcpgateway.db import fresh_db_session, get_db, Tool
 from mcpgateway.meta_server.schemas import (
     AuthorizeAllGatewaysResponse,
     AuthorizeGatewayResponse,
@@ -84,7 +81,7 @@ class MetaServerService:
         >>> defs = service.get_meta_tool_definitions()
         >>> isinstance(defs, list)
         True
-        >>> len(defs) == 6
+        >>> len(defs) == 12
         True
     """
 
@@ -96,12 +93,6 @@ def get_meta_tool_definitions(self) -> List[Dict[str, Any]]:
 
         Returns:
             List of meta-tool definition dicts with keys: name, description, inputSchema.
-
-        Examples:
-            >>> service = MetaServerService()
-            >>> tools = service.get_meta_tool_definitions()
-            >>> {t["name"] for t in tools} == {"search_tools", "list_tools", "describe_tool", "execute_tool", "get_tool_categories", "get_similar_tools"}
-            True
         """
         return [{"name": name, "description": defn["description"], "inputSchema": defn["input_schema"]} for name, defn in META_TOOL_DEFINITIONS.items()]
 
@@ -282,6 +273,34 @@ def _extract_user_context(kwargs: Dict[str, Any]) -> tuple:
             kwargs.get("request_headers"),
         )
 
+    @staticmethod
+    def _resolve_effective_email(
+        user_email: Optional[str],
+        request_headers: Optional[Dict[str, str]],
+    ) -> Optional[str]:
+        """Resolve effective user email from explicit param or JWT in Authorization header.
+
+        Prefers the explicit ``user_email`` parameter. Falls back to extracting
+        the email claim from the Bearer JWT in the Authorization header.
+        The JWT signature is NOT verified here — upstream middleware is responsible
+        for authentication. This is only used for user identity resolution.
+        """
+        if user_email:
+            return user_email.strip().lower() if isinstance(user_email, str) else None
+        if not request_headers:
+            return None
+        auth_header = request_headers.get("authorization", "")
+        if not auth_header.startswith("Bearer "):
+            return None
+        try:
+            import jwt as pyjwt  # pylint: disable=import-outside-toplevel
+            token = auth_header[7:]
+            payload = pyjwt.decode(token, options={"verify_signature": False})
+            email = payload.get("email") or payload.get("sub")
+            return email.strip().lower() if email else None
+        except Exception:
+            return None
+
     # ------------------------------------------------------------------
     # Implemented handlers
     # ------------------------------------------------------------------
@@ -1085,19 +1104,7 @@ async def _authorize_gateway(
         from mcpgateway.services.token_storage_service import TokenStorageService
 
         # Resolve user_email: prefer explicit param, fall back to JWT in request_headers
-        effective_email = user_email
-        if not effective_email and request_headers:
-            auth_header = request_headers.get("authorization", "")
-            if auth_header.startswith("Bearer "):
-                try:
-                    import jwt as pyjwt  # pylint: disable=import-outside-toplevel
-                    token = auth_header[7:]
-                    payload = pyjwt.decode(token, options={"verify_signature": False})
-                    effective_email = payload.get("email") or payload.get("sub")
-                    if effective_email:
-                        effective_email = effective_email.strip().lower()
-                except Exception:
-                    pass
+        effective_email = self._resolve_effective_email(user_email, request_headers)
 
         gateway_name = arguments.get("gateway_name", "")
         if not gateway_name:
@@ -1210,19 +1217,7 @@ async def _authorize_all_gateways(
         from mcpgateway.services.token_storage_service import TokenStorageService
 
         # Resolve user_email from JWT if not provided
-        effective_email = user_email
-        if not effective_email and request_headers:
-            auth_header = request_headers.get("authorization", "")
-            if auth_header.startswith("Bearer "):
-                try:
-                    import jwt as pyjwt  # pylint: disable=import-outside-toplevel
-                    token = auth_header[7:]
-                    payload = pyjwt.decode(token, options={"verify_signature": False})
-                    effective_email = payload.get("email") or payload.get("sub")
-                    if effective_email:
-                        effective_email = effective_email.strip().lower()
-                except Exception:
-                    pass
+        effective_email = self._resolve_effective_email(user_email, request_headers)
 
         try:
             db_gen = get_db()

mcpgateway/routers/meta_router.py

@@ -16,6 +16,7 @@
 """
 
 # Standard
+import json
 import time
 from typing import Any, Dict, Optional
 
@@ -60,6 +61,16 @@
 router = APIRouter(prefix="/meta", tags=["Meta Tools"])
 
 
+def _apply_scope_header(arguments: Dict[str, Any], x_scope: Optional[str]) -> Dict[str, Any]:
+    """Apply X-Scope header to arguments dict, parsing JSON if provided."""
+    if x_scope:
+        try:
+            arguments["scope"] = json.loads(x_scope)
+        except (json.JSONDecodeError, ValueError):
+            logger.warning(f"Invalid X-Scope header: {x_scope}")
+    return arguments
+
+
 @router.post("/describe_tool", response_model=DescribeToolResponse)
 async def describe_tool(
     req: DescribeToolRequest,
@@ -198,13 +209,7 @@ async def search_tools(
         meta_service = get_meta_server_service()
 
         # Build arguments dict with scope from header if provided
-        arguments = req.model_dump()
-        if x_scope:
-            try:
-                import json
-                arguments["scope"] = json.loads(x_scope)
-            except json.JSONDecodeError:
-                logger.warning(f"Invalid X-Scope header: {x_scope}")
+        arguments = _apply_scope_header(req.model_dump(), x_scope)
 
         # Call the service handler
         result = await meta_service._search_tools(arguments)
@@ -241,13 +246,7 @@ async def list_tools(
         meta_service = get_meta_server_service()
 
         # Build arguments dict with scope from header if provided
-        arguments = req.model_dump()
-        if x_scope:
-            try:
-                import json
-                arguments["scope"] = json.loads(x_scope)
-            except json.JSONDecodeError:
-                logger.warning(f"Invalid X-Scope header: {x_scope}")
+        arguments = _apply_scope_header(req.model_dump(), x_scope)
 
         # Call the service handler
         result = await meta_service._list_tools(arguments)
@@ -284,13 +283,7 @@ async def get_similar_tools(
         meta_service = get_meta_server_service()
 
         # Build arguments dict with scope from header if provided
-        arguments = req.model_dump()
-        if x_scope:
-            try:
-                import json
-                arguments["scope"] = json.loads(x_scope)
-            except json.JSONDecodeError:
-                logger.warning(f"Invalid X-Scope header: {x_scope}")
+        arguments = _apply_scope_header(req.model_dump(), x_scope)
 
         # Call the service handler
         result = await meta_service._get_similar_tools(arguments)

mcpgateway/templates/admin.html

@@ -3478,48 +3478,6 @@ <h3 class="text-lg font-bold mb-4 dark:text-gray-200">
               </div>
             </div>
 
-            <!-- Meta-Server Configuration Section -->
-            <div class="mt-6 border-t border-gray-200 dark:border-gray-700 pt-4">
-              <div class="flex items-center mb-4">
-                <input
-                  type="checkbox"
-                  name="meta_server_enabled"
-                  id="server-meta-enabled"
-                  class="form-checkbox h-5 w-5 text-indigo-600 dark:bg-gray-800 dark:border-gray-600"
-                  onchange="document.getElementById('server-meta-config-section').classList.toggle('hidden', !this.checked)"
-                />
-                <label
-                  for="server-meta-enabled"
-                  class="ml-2 text-sm font-medium text-gray-700 dark:text-gray-400"
-                  >Enable as Meta-Server (Tool Router)</label
-                >
-              </div>
-              <p class="text-xs text-gray-500 dark:text-gray-400 mb-3">
-                When enabled, this server exposes meta-tools (search, list, describe, execute) instead of individual underlying tools.
-              </p>
-
-              <!-- Meta-Server Configuration Fields (hidden by default) -->
-              <div id="server-meta-config-section" class="hidden space-y-4 pl-6 border-l-2 border-indigo-200 dark:border-indigo-800">
-                <div class="flex items-center">
-                  <input
-                    type="checkbox"
-                    name="hide_underlying_tools"
-                    id="server-hide-underlying-tools"
-                    class="form-checkbox h-5 w-5 text-indigo-600 dark:bg-gray-800 dark:border-gray-600"
-                    checked
-                  />
-                  <label
-                    for="server-hide-underlying-tools"
-                    class="ml-2 text-sm font-medium text-gray-700 dark:text-gray-400"
-                    >Hide underlying tools from tool listing</label
-                  >
-                  <p class="ml-2 text-xs text-gray-500 dark:text-gray-400">
-                    Clients will only see the meta-tools, not the individual backend tools.
-                  </p>
-                </div>
-              </div>
-            </div>
-
             <div class="mt-6">
               <button
                 type="submit"
@@ -11951,48 +11909,6 @@ <h3 class="text-lg font-medium text-gray-900 dark:text-gray-100">
                   </div>
                 </div>
 
-                <!-- Meta-Server Configuration Section -->
-                <div class="mt-6 border-t border-gray-200 dark:border-gray-700 pt-4">
-                  <div class="flex items-center mb-4">
-                    <input
-                      type="checkbox"
-                      name="meta_server_enabled"
-                      id="edit-server-meta-enabled"
-                      class="form-checkbox h-5 w-5 text-indigo-600 dark:bg-gray-800 dark:border-gray-600"
-                      onchange="document.getElementById('edit-server-meta-config-section').classList.toggle('hidden', !this.checked)"
-                    />
-                    <label
-                      for="edit-server-meta-enabled"
-                      class="ml-2 text-sm font-medium text-gray-700 dark:text-gray-400"
-                      >Enable as Meta-Server (Tool Router)</label
-                    >
-                  </div>
-                  <p class="text-xs text-gray-500 dark:text-gray-400 mb-3">
-                    When enabled, this server exposes meta-tools (search, list, describe, execute) instead of individual underlying tools.
-                  </p>
-
-                  <!-- Meta-Server Configuration Fields (hidden by default) -->
-                  <div id="edit-server-meta-config-section" class="hidden space-y-4 pl-6 border-l-2 border-indigo-200 dark:border-indigo-800">
-                    <div class="flex items-center">
-                      <input
-                        type="checkbox"
-                        name="hide_underlying_tools"
-                        id="edit-server-hide-underlying-tools"
-                        class="form-checkbox h-5 w-5 text-indigo-600 dark:bg-gray-800 dark:border-gray-600"
-                        checked
-                      />
-                      <label
-                        for="edit-server-hide-underlying-tools"
-                        class="ml-2 text-sm font-medium text-gray-700 dark:text-gray-400"
-                        >Hide underlying tools from tool listing</label
-                      >
-                      <p class="ml-2 text-xs text-gray-500 dark:text-gray-400">
-                        Clients will only see the meta-tools, not the individual backend tools.
-                      </p>
-                    </div>
-                  </div>
-                </div>
-
                   <div
                     class="mt-6 flex justify-end space-x-3 bg-white dark:bg-gray-900 dark:text-gray-100"
                   >

tests/unit/mcpgateway/test_meta_server.py

@@ -350,10 +350,12 @@ def test_get_meta_tool_definitions(self):
         """Test that meta-tool definitions are returned correctly."""
         service = MetaServerService()
         defs = service.get_meta_tool_definitions()
-        assert len(defs) == 6
+        assert len(defs) == 12
         names = {d["name"] for d in defs}
         assert "search_tools" in names
         assert "execute_tool" in names
+        assert "list_resources" in names
+        assert "authorize_gateway" in names
 
     def test_is_meta_server(self):
         """Test is_meta_server check."""