refactor: implement code review suggestions for maintainability

Addresses remaining code review feedback from the reviewer agent:

1. CLI Dispatch Refactor (Suggestion #3)
   - Replace if/elif chain with dict-based TOOL_DISPATCH mapping
   - Single source of truth for available tools
   - Lazy initialization of request types to avoid circular imports
   - Easier to maintain and extend

2. Pydantic Validation Error Handling (Edge Case #6)
   - Catch ValidationError in _dispatch_tool()
   - Return user-friendly error messages showing field-level issues
   - Format: "Invalid request payload for {tool}:\n  - field: message"

3. Response Parser Error Context (Suggestion #4)
   - Add content preview to parse_mcp_content() error messages
   - Include first 2 items, max 500 chars for debugging
   - Helps diagnose real-world parsing failures

4. Adapter Response Parsing Edge Case (Edge Case #7)
   - Fix _parse_response() to explicitly construct TaskResult[T]
   - Handle success=False or data=None without type: ignore
   - Provide clear error message when data is missing

Benefits:
- Maintainability: CLI tool list in one place, easier to add new ADCP methods
- User Experience: Clear validation errors instead of Python tracebacks
- Debuggability: Content preview helps diagnose parsing issues
- Type Safety: Proper typed TaskResult construction without suppressions

All tests pass (92/92), linting and type checking clean.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: bokelley

src/adcp/__main__.py

@@ -80,49 +80,99 @@ async def execute_tool(
         print_result(result, json_output)
 
 
+# Tool dispatch mapping - single source of truth for ADCP methods
+# Types are filled at runtime to avoid circular imports
+TOOL_DISPATCH: dict[str, tuple[str, type | None]] = {
+    "get_products": ("get_products", None),
+    "list_creative_formats": ("list_creative_formats", None),
+    "sync_creatives": ("sync_creatives", None),
+    "list_creatives": ("list_creatives", None),
+    "get_media_buy_delivery": ("get_media_buy_delivery", None),
+    "list_authorized_properties": ("list_authorized_properties", None),
+    "get_signals": ("get_signals", None),
+    "activate_signal": ("activate_signal", None),
+    "provide_performance_feedback": ("provide_performance_feedback", None),
+}
+
+
 async def _dispatch_tool(client: ADCPClient, tool_name: str, payload: dict[str, Any]) -> Any:
-    """Dispatch tool call to appropriate client method."""
+    """Dispatch tool call to appropriate client method.
+
+    Args:
+        client: ADCP client instance
+        tool_name: Name of the tool to invoke
+        payload: Request payload as dict
+
+    Returns:
+        TaskResult with typed response or error
+
+    Raises:
+        ValidationError: If payload doesn't match request schema (caught and returned as TaskResult)
+    """
+    from pydantic import ValidationError
+
     from adcp.types import generated as gen
     from adcp.types.core import TaskResult, TaskStatus
 
-    # Dispatch to specific method based on tool name
-    if tool_name == "get_products":
-        return await client.get_products(gen.GetProductsRequest(**payload))
-    elif tool_name == "list_creative_formats":
-        return await client.list_creative_formats(gen.ListCreativeFormatsRequest(**payload))
-    elif tool_name == "sync_creatives":
-        return await client.sync_creatives(gen.SyncCreativesRequest(**payload))
-    elif tool_name == "list_creatives":
-        return await client.list_creatives(gen.ListCreativesRequest(**payload))
-    elif tool_name == "get_media_buy_delivery":
-        return await client.get_media_buy_delivery(gen.GetMediaBuyDeliveryRequest(**payload))
-    elif tool_name == "list_authorized_properties":
-        return await client.list_authorized_properties(
-            gen.ListAuthorizedPropertiesRequest(**payload)
-        )
-    elif tool_name == "get_signals":
-        return await client.get_signals(gen.GetSignalsRequest(**payload))
-    elif tool_name == "activate_signal":
-        return await client.activate_signal(gen.ActivateSignalRequest(**payload))
-    elif tool_name == "provide_performance_feedback":
-        return await client.provide_performance_feedback(
-            gen.ProvidePerformanceFeedbackRequest(**payload)
-        )
-    else:
-        available_tools = [
-            "get_products",
+    # Lazy initialization of request types (avoid circular imports)
+    if TOOL_DISPATCH["get_products"][1] is None:
+        TOOL_DISPATCH["get_products"] = ("get_products", gen.GetProductsRequest)
+        TOOL_DISPATCH["list_creative_formats"] = (
             "list_creative_formats",
-            "sync_creatives",
-            "list_creatives",
+            gen.ListCreativeFormatsRequest,
+        )
+        TOOL_DISPATCH["sync_creatives"] = ("sync_creatives", gen.SyncCreativesRequest)
+        TOOL_DISPATCH["list_creatives"] = ("list_creatives", gen.ListCreativesRequest)
+        TOOL_DISPATCH["get_media_buy_delivery"] = (
             "get_media_buy_delivery",
+            gen.GetMediaBuyDeliveryRequest,
+        )
+        TOOL_DISPATCH["list_authorized_properties"] = (
             "list_authorized_properties",
-            "get_signals",
-            "activate_signal",
+            gen.ListAuthorizedPropertiesRequest,
+        )
+        TOOL_DISPATCH["get_signals"] = ("get_signals", gen.GetSignalsRequest)
+        TOOL_DISPATCH["activate_signal"] = ("activate_signal", gen.ActivateSignalRequest)
+        TOOL_DISPATCH["provide_performance_feedback"] = (
             "provide_performance_feedback",
-        ]
+            gen.ProvidePerformanceFeedbackRequest,
+        )
+
+    # Check if tool exists
+    if tool_name not in TOOL_DISPATCH:
+        available = ", ".join(sorted(TOOL_DISPATCH.keys()))
+        return TaskResult(
+            status=TaskStatus.FAILED,
+            error=f"Unknown tool: {tool_name}. Available tools: {available}",
+        )
+
+    # Get method and request type
+    method_name, request_type = TOOL_DISPATCH[tool_name]
+
+    # Type guard - request_type should be initialized by this point
+    if request_type is None:
+        return TaskResult(
+            status=TaskStatus.FAILED,
+            error=f"Internal error: {tool_name} request type not initialized",
+        )
+
+    method = getattr(client, method_name)
+
+    # Validate and invoke
+    try:
+        request = request_type(**payload)
+        return await method(request)
+    except ValidationError as e:
+        # User-friendly error for invalid payloads
+        error_details = []
+        for error in e.errors():
+            field = ".".join(str(loc) for loc in error["loc"])
+            msg = error["msg"]
+            error_details.append(f"  - {field}: {msg}")
+
         return TaskResult(
             status=TaskStatus.FAILED,
-            error=f"Unknown tool: {tool_name}. Available tools: {', '.join(available_tools)}",
+            error=f"Invalid request payload for {tool_name}:\n" + "\n".join(error_details),
         )
 
 

src/adcp/protocols/base.py

@@ -43,8 +43,17 @@ def _parse_response(self, raw_result: TaskResult[Any], response_type: type[T]) -
         Returns:
             Typed TaskResult
         """
+        # Handle failed results or missing data
         if not raw_result.success or raw_result.data is None:
-            return raw_result
+            # Explicitly construct typed result to satisfy type checker
+            return TaskResult[T](
+                status=raw_result.status,
+                data=None,
+                success=False,
+                error=raw_result.error or "No data returned from adapter",
+                metadata=raw_result.metadata,
+                debug_info=raw_result.debug_info,
+            )
 
         try:
             # Handle MCP content arrays

src/adcp/utils/response_parser.py

@@ -64,9 +64,15 @@ def parse_mcp_content(content: list[dict[str, Any]], response_type: type[T]) ->
                 continue
 
     # If we get here, no content item could be parsed
+    # Include content preview for debugging (first 2 items, max 500 chars each)
+    content_preview = json.dumps(content[:2], indent=2, default=str)
+    if len(content_preview) > 500:
+        content_preview = content_preview[:500] + "..."
+
     raise ValueError(
         f"No valid {response_type.__name__} data found in MCP content. "
-        f"Content types: {[item.get('type') for item in content]}"
+        f"Content types: {[item.get('type') for item in content]}. "
+        f"Content preview:\n{content_preview}"
     )