fix: resolve pylint warnings and update tests for A2A protocol refactor

- Remove redundant local `from mcpgateway.config import settings`
  re-imports in a2a_service.py (W0404/W0621)
- Add pylint disable for unused `interaction_type` parameter in
  build_a2a_jsonrpc_request (W0613) - part of public API
- Add missing docstrings for interrogate coverage (8 functions)
- Update test patches to target module-level settings binding at
  mcpgateway.services.a2a_service.settings
- Redirect decode_auth/apply_query_param_auth test patches to
  mcpgateway.services.a2a_protocol where prepare_a2a_invocation
  now calls them
- Update admin test assertion for simplified test_params format

Signed-off-by: Jon Spriggs <github@sprig.gs>
Signed-off-by: Jonathan Springer <jps@s390x.com>

Author: jonpspri

mcpgateway/services/a2a_protocol.py

@@ -126,6 +126,7 @@ def normalize_a2a_method(method: Optional[str], protocol_version: Optional[str])
 
 
 def _normalize_role(role: Any, protocol_version: Optional[str]) -> Any:
+    """Normalize an A2A message role between v1 and legacy protocol forms."""
     value = str(role or "").strip()
     if not value:
         return role
@@ -135,6 +136,7 @@ def _normalize_role(role: Any, protocol_version: Optional[str]) -> Any:
 
 
 def _normalize_part(part: Any, protocol_version: Optional[str]) -> Any:
+    """Normalize an A2A message part between v1 and legacy protocol forms."""
     if not isinstance(part, Mapping):
         return part
 
@@ -159,6 +161,7 @@ def _normalize_part(part: Any, protocol_version: Optional[str]) -> Any:
 
 
 def _normalize_task_state(state: Any, protocol_version: Optional[str]) -> Any:
+    """Normalize an A2A task state between v1 and legacy protocol forms."""
     value = str(state or "").strip()
     if not value:
         return state
@@ -168,6 +171,7 @@ def _normalize_task_state(state: Any, protocol_version: Optional[str]) -> Any:
 
 
 def _normalize_message(message: Any, protocol_version: Optional[str]) -> Any:
+    """Normalize an A2A message object for the target protocol version."""
     if not isinstance(message, Mapping):
         return message
 
@@ -184,6 +188,7 @@ def _normalize_message(message: Any, protocol_version: Optional[str]) -> Any:
 
 
 def _normalize_task_status(status: Any, protocol_version: Optional[str]) -> Any:
+    """Normalize an A2A task status for the target protocol version."""
     if isinstance(status, str):
         return _normalize_task_state(status, protocol_version)
     if not isinstance(status, Mapping):
@@ -198,6 +203,7 @@ def _normalize_task_status(status: Any, protocol_version: Optional[str]) -> Any:
 
 
 def _normalize_task(task: Any, protocol_version: Optional[str]) -> Any:
+    """Normalize an A2A task object for the target protocol version."""
     if not isinstance(task, Mapping):
         return task
 
@@ -249,6 +255,7 @@ def normalize_a2a_params(params: Any, protocol_version: Optional[str]) -> Any:
 
 
 def _build_default_message(query: str, protocol_version: Optional[str], message_id: Optional[str] = None) -> Dict[str, Any]:
+    """Build a default user message in the appropriate protocol format."""
     target_message_id = message_id or f"contextforge-{uuid.uuid4().hex}"
     if is_v1_a2a_protocol(protocol_version):
         return {
@@ -264,7 +271,7 @@ def _build_default_message(query: str, protocol_version: Optional[str], message_
     }
 
 
-def build_a2a_jsonrpc_request(parameters: Dict[str, Any], protocol_version: Optional[str], *, interaction_type: str = "query") -> Dict[str, Any]:
+def build_a2a_jsonrpc_request(parameters: Dict[str, Any], protocol_version: Optional[str], *, interaction_type: str = "query") -> Dict[str, Any]:  # pylint: disable=unused-argument
     """Build a JSON-RPC A2A request body for the target protocol version."""
     payload = dict(parameters or {})
     request_id = payload.pop("id", 1)

mcpgateway/services/a2a_service.py

@@ -354,9 +354,6 @@ async def register_agent(
                 # Standard
                 from urllib.parse import urlparse  # pylint: disable=import-outside-toplevel
 
-                # First-Party
-                from mcpgateway.config import settings  # pylint: disable=import-outside-toplevel
-
                 # Service-layer enforcement: Check feature flag
                 if not settings.insecure_allow_queryparam_auth:
                     raise ValueError("Query parameter authentication is disabled. Set INSECURE_ALLOW_QUERYPARAM_AUTH=true to enable.")
@@ -1014,9 +1011,6 @@ async def update_agent(
                 # Standard
                 from urllib.parse import urlparse  # pylint: disable=import-outside-toplevel
 
-                # First-Party
-                from mcpgateway.config import settings  # pylint: disable=import-outside-toplevel
-
                 # Service-layer enforcement: Check feature flag
                 if not settings.insecure_allow_queryparam_auth:
                     # Grandfather clause: Allow updates to existing query_param agents
@@ -1049,9 +1043,6 @@ async def update_agent(
                     is_masked_placeholder = False
                     if param_value and hasattr(param_value, "get_secret_value"):
                         raw_value = param_value.get_secret_value()
-                        # First-Party
-                        from mcpgateway.config import settings  # pylint: disable=import-outside-toplevel
-
                         is_masked_placeholder = raw_value == settings.masked_auth_value
                     elif param_value:
                         raw_value = str(param_value)

mcpgateway/services/rust_a2a_runtime.py

@@ -72,6 +72,7 @@ async def invoke(self, prepared: PreparedA2AInvocation, *, timeout_seconds: Opti
         return payload
 
     async def _get_runtime_client(self) -> httpx.AsyncClient:
+        """Return the httpx client, lazily creating a UDS transport if configured."""
         uds_path = settings.experimental_rust_a2a_runtime_uds
         if not uds_path:
             return await get_http_client()

tests/unit/mcpgateway/services/test_a2a_query_param_auth.py

@@ -80,18 +80,18 @@ def _bypass_a2aagentread_validation(monkeypatch):
 def mock_all_settings():
     """Mock settings in schemas, a2a_service, and config modules."""
     with patch("mcpgateway.schemas.settings") as schema_settings, \
-         patch("mcpgateway.config.settings") as config_settings:
+         patch("mcpgateway.services.a2a_service.settings") as svc_settings:
         # Configure schema settings
         schema_settings.insecure_allow_queryparam_auth = True
         schema_settings.insecure_queryparam_auth_allowed_hosts = ["api.tavily.com", "mcp.tavily.com", "api.example.com"]
         schema_settings.masked_auth_value = "*****"
 
-        # Configure config settings (used by service layer imports)
-        config_settings.insecure_allow_queryparam_auth = True
-        config_settings.insecure_queryparam_auth_allowed_hosts = ["api.tavily.com", "mcp.tavily.com", "api.example.com"]
-        config_settings.masked_auth_value = "*****"
+        # Configure service-layer settings (module-level import in a2a_service)
+        svc_settings.insecure_allow_queryparam_auth = True
+        svc_settings.insecure_queryparam_auth_allowed_hosts = ["api.tavily.com", "mcp.tavily.com", "api.example.com"]
+        svc_settings.masked_auth_value = "*****"
 
-        yield {"schema": schema_settings, "config": config_settings}
+        yield {"schema": schema_settings, "config": svc_settings}
 
 
 @pytest.fixture(autouse=True)

tests/unit/mcpgateway/services/test_a2a_service.py

@@ -1339,7 +1339,7 @@ async def test_register_query_param_disabled(self, service, mock_db, monkeypatch
         """Query param auth disabled raises ValueError."""
         monkeypatch.setattr("mcpgateway.services.a2a_service.get_for_update", lambda *a, **kw: None)
 
-        with patch("mcpgateway.config.settings") as mock_settings:
+        with patch("mcpgateway.services.a2a_service.settings") as mock_settings:
             mock_settings.insecure_allow_queryparam_auth = False
             agent_data = A2AAgentCreate.model_construct(
                 name="qp-agent",
@@ -1361,7 +1361,7 @@ async def test_register_query_param_host_not_allowed(self, service, mock_db, mon
         """Query param auth host not in allowlist raises ValueError."""
         monkeypatch.setattr("mcpgateway.services.a2a_service.get_for_update", lambda *a, **kw: None)
 
-        with patch("mcpgateway.config.settings") as mock_settings:
+        with patch("mcpgateway.services.a2a_service.settings") as mock_settings:
             mock_settings.insecure_allow_queryparam_auth = True
             mock_settings.insecure_queryparam_auth_allowed_hosts = ["safe.host.com"]
             agent_data = A2AAgentCreate.model_construct(
@@ -1397,7 +1397,7 @@ async def test_register_query_param_secretstr_value(self, service, mock_db, monk
         secret_val = MagicMock()
         secret_val.get_secret_value.return_value = "the-secret"
 
-        with patch("mcpgateway.config.settings") as mock_settings:
+        with patch("mcpgateway.services.a2a_service.settings") as mock_settings:
             mock_settings.insecure_allow_queryparam_auth = True
             mock_settings.insecure_queryparam_auth_allowed_hosts = []
 
@@ -1437,7 +1437,7 @@ async def test_register_query_param_non_secret_value_uses_str(self, service, moc
         monkeypatch.setattr("mcpgateway.cache.metrics_cache.metrics_cache", SimpleNamespace(invalidate=MagicMock()))
         monkeypatch.setattr("mcpgateway.services.a2a_service.encode_auth", lambda _val: "encrypted")
 
-        with patch("mcpgateway.config.settings") as mock_settings:
+        with patch("mcpgateway.services.a2a_service.settings") as mock_settings:
             mock_settings.insecure_allow_queryparam_auth = True
             mock_settings.insecure_queryparam_auth_allowed_hosts = []
 
@@ -1474,7 +1474,7 @@ async def test_register_query_param_missing_key_or_value_skips_encryption(self,
         monkeypatch.setattr("mcpgateway.cache.admin_stats_cache.admin_stats_cache", SimpleNamespace(invalidate_tags=AsyncMock()))
         monkeypatch.setattr("mcpgateway.cache.metrics_cache.metrics_cache", SimpleNamespace(invalidate=MagicMock()))
 
-        with patch("mcpgateway.config.settings") as mock_settings:
+        with patch("mcpgateway.services.a2a_service.settings") as mock_settings:
             mock_settings.insecure_allow_queryparam_auth = True
             mock_settings.insecure_queryparam_auth_allowed_hosts = []
 
@@ -1908,7 +1908,7 @@ async def test_queryparam_switching_disabled_grandfather(self, service, mock_db,
         """Switching to query_param when disabled raises ValueError."""
         agent = self._make_agent(auth_type="bearer")
         with patch("mcpgateway.services.a2a_service.get_for_update", return_value=agent):
-            with patch("mcpgateway.config.settings") as mock_settings:
+            with patch("mcpgateway.services.a2a_service.settings") as mock_settings:
                 mock_settings.insecure_allow_queryparam_auth = False
                 mock_settings.insecure_queryparam_auth_allowed_hosts = []
                 update = A2AAgentUpdate.model_construct(
@@ -1923,7 +1923,7 @@ async def test_queryparam_host_not_allowed_on_update(self, service, mock_db, mon
         """Host allowlist is enforced when switching to query_param."""
         agent = self._make_agent(auth_type="bearer", endpoint_url="https://bad.host.com/agent")
         with patch("mcpgateway.services.a2a_service.get_for_update", return_value=agent):
-            with patch("mcpgateway.config.settings") as mock_settings:
+            with patch("mcpgateway.services.a2a_service.settings") as mock_settings:
                 mock_settings.insecure_allow_queryparam_auth = True
                 mock_settings.insecure_queryparam_auth_allowed_hosts = ["safe.host.com"]
                 update = A2AAgentUpdate.model_construct(

tests/unit/mcpgateway/services/test_tool_service_coverage.py

@@ -2149,7 +2149,8 @@ async def test_call_a2a_custom_agent(self, tool_service):
         mock_client = AsyncMock()
         mock_client.post.return_value = mock_response
 
-        with patch("mcpgateway.services.http_client_service.get_http_client", new_callable=AsyncMock, return_value=mock_client):
+        with patch("mcpgateway.services.http_client_service.get_http_client", new_callable=AsyncMock, return_value=mock_client), \
+             patch("mcpgateway.services.a2a_protocol.decode_auth", return_value={"Authorization": "Bearer my-token"}):
             result = await tool_service._call_a2a_agent(agent, {"query": "test"})
         assert result == {"data": "custom"}
         # Verify bearer auth was added
@@ -2748,24 +2749,21 @@ async def test_jsonrpc_with_query_param(self, tool_service):
 
     @pytest.mark.asyncio
     async def test_jsonrpc_request_data_prepare_error_is_logged_and_raised(self, tool_service):
-        """If preparing JSONRPC request data fails, the error is logged and re-raised."""
+        """If preparing request data fails, the error propagates to the caller."""
         agent = self._make_agent(agent_type="jsonrpc")
 
         def _info_side_effect(msg, *args, **kwargs):
-            # Allow the initial "Calling A2A agent..." log, but force an exception for the JSONRPC request_data log.
-            if "JSONRPC request_data prepared" in str(msg):
+            # Allow the initial "Calling A2A agent..." log, but force an exception for the request_data log.
+            if "invoke tool request_data prepared" in str(msg):
                 raise RuntimeError("logger boom")
             return None
 
         with patch("mcpgateway.services.tool_service.logger") as mock_logger:
             mock_logger.info.side_effect = _info_side_effect
-            mock_logger.error = MagicMock()
 
             with pytest.raises(RuntimeError, match="logger boom"):
                 await tool_service._call_a2a_agent(agent, {"query": "hello"})
 
-        mock_logger.error.assert_called_once()
-
     @pytest.mark.asyncio
     async def test_custom_agent_format(self, tool_service):
         agent = self._make_agent(agent_type="custom", endpoint_url="http://custom.test")
@@ -2804,7 +2802,8 @@ async def test_bearer_auth(self, tool_service):
         mock_client = AsyncMock()
         mock_client.post.return_value = mock_resp
 
-        with patch("mcpgateway.services.http_client_service.get_http_client", new_callable=AsyncMock, return_value=mock_client):
+        with patch("mcpgateway.services.http_client_service.get_http_client", new_callable=AsyncMock, return_value=mock_client), \
+             patch("mcpgateway.services.a2a_protocol.decode_auth", return_value={"Authorization": "Bearer bearer-token"}):
             await tool_service._call_a2a_agent(agent, {"query": "test"})
         headers = mock_client.post.call_args[1]["headers"]
         assert headers["Authorization"] == "Bearer bearer-token"
@@ -2820,9 +2819,9 @@ async def test_query_param_auth(self, tool_service):
 
         with (
             patch("mcpgateway.services.http_client_service.get_http_client", new_callable=AsyncMock, return_value=mock_client),
-            patch("mcpgateway.services.tool_service.decode_auth", return_value={"api_key": "real-key"}),
-            patch("mcpgateway.services.tool_service.apply_query_param_auth", return_value="http://agent.test/api?api_key=real-key"),
-            patch("mcpgateway.services.tool_service.sanitize_url_for_logging", return_value="http://agent.test/api?api_key=***"),
+            patch("mcpgateway.services.a2a_protocol.decode_auth", return_value={"api_key": "real-key"}),
+            patch("mcpgateway.services.a2a_protocol.apply_query_param_auth", return_value="http://agent.test/api?api_key=real-key"),
+            patch("mcpgateway.services.a2a_protocol.sanitize_url_for_logging", return_value="http://agent.test/api?api_key=***"),
         ):
             await tool_service._call_a2a_agent(agent, {"query": "test"})
         assert mock_client.post.call_args[0][0] == "http://agent.test/api?api_key=real-key"
@@ -6565,8 +6564,9 @@ async def fake_post(url, json=None, headers=None):
             patch("mcpgateway.services.tool_service.current_trace_id") as mock_trace,
             patch("mcpgateway.services.tool_service.create_span") as mock_span_ctx,
             patch("mcpgateway.services.metrics_buffer_service.get_metrics_buffer_service") as mock_mbuf,
-            patch("mcpgateway.services.tool_service.decode_auth", return_value={"token": "decrypted_val"}),
-            patch("mcpgateway.services.tool_service.apply_query_param_auth", return_value="http://a2a-agent:9000/?token=decrypted_val"),
+            patch("mcpgateway.services.a2a_protocol.decode_auth", return_value={"token": "decrypted_val"}),
+            patch("mcpgateway.services.a2a_protocol.apply_query_param_auth", return_value="http://a2a-agent:9000/?token=decrypted_val"),
+            patch("mcpgateway.services.a2a_protocol.sanitize_url_for_logging", return_value="http://a2a-agent:9000/?token=***"),
             patch("mcpgateway.services.tool_service.compute_passthrough_headers_cached", return_value={}),
         ):
             mock_gcc.get_passthrough_headers = MagicMock(return_value=[])

tests/unit/mcpgateway/test_admin.py

@@ -4898,7 +4898,7 @@ async def test_admin_test_a2a_agent_body_read_exception_uses_default_message(sel
         result = await admin_test_a2a_agent("agent-1", mock_request, mock_db, user={"email": "test-user", "db": mock_db})
         assert result.status_code == 200
         params = service.invoke_agent.call_args.args[2]
-        assert "Hello from ContextForge Admin UI test!" in params["params"]["message"]["parts"][0]["text"]
+        assert params["query"] == "Hello from ContextForge Admin UI test!"
 
     @pytest.mark.asyncio
     async def test_admin_test_a2a_agent_generic_test_params_branch(self, monkeypatch, mock_request, mock_db, allow_permission):