fix: walk MRO for tool filtering, add tool name validation

- get_tools_for_handler now accepts instance or class, walks MRO to find
  the matching handler base class. Fixes filtering for user subclasses
  (e.g. MyGovernanceAgent(GovernanceHandler) now correctly gets only
  governance tools).
- Add module-level assertion that all tool names in _HANDLER_TOOLS
  reference real tools in ADCP_TOOL_DEFINITIONS.
- Add test for subclass MRO-based filtering.

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

Author: bokelley

src/adcp/server/mcp_tools.py

@@ -6,14 +6,10 @@
 from __future__ import annotations
 
 from collections.abc import Callable
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 from adcp.server.base import ADCPHandler, ToolContext
 
-if TYPE_CHECKING:
-    pass
-
-
 # Tool definitions for all ADCP operations
 ADCP_TOOL_DEFINITIONS: list[dict[str, Any]] = [
     # Core Catalog Operations
@@ -589,25 +585,34 @@
     "ADCPHandler": {tool["name"] for tool in ADCP_TOOL_DEFINITIONS},
 }
 
+# Validate that all handler tool names reference real tools
+_ALL_TOOL_NAMES = {t["name"] for t in ADCP_TOOL_DEFINITIONS}
+for _handler_name, _tools in _HANDLER_TOOLS.items():
+    _unknown = _tools - _ALL_TOOL_NAMES
+    assert not _unknown, f"{_handler_name} references unknown tools: {_unknown}"
+
 
-def get_tools_for_handler(handler_class_name: str) -> list[dict[str, Any]]:
+def get_tools_for_handler(handler: ADCPHandler | type[ADCPHandler]) -> list[dict[str, Any]]:
     """Return tool definitions filtered by handler type.
 
-    Specialized handlers only get their own tools plus protocol discovery.
+    Walks the MRO to find the matching handler base class, so subclasses
+    (e.g. MyGovernanceAgent(GovernanceHandler)) get the correct tool set.
     ADCPHandler gets all tools. Unknown handlers get only protocol discovery
     (minimum privilege).
 
     Args:
-        handler_class_name: The handler class name (e.g. "GovernanceHandler")
+        handler: The handler instance or class
 
     Returns:
         Filtered list of tool definitions
     """
-    if handler_class_name not in _HANDLER_TOOLS:
-        return [tool for tool in ADCP_TOOL_DEFINITIONS if tool["name"] in _PROTOCOL_TOOLS]
+    cls = handler if isinstance(handler, type) else type(handler)
+    for base in cls.__mro__:
+        if base.__name__ in _HANDLER_TOOLS:
+            allowed = _HANDLER_TOOLS[base.__name__] | _PROTOCOL_TOOLS
+            return [tool for tool in ADCP_TOOL_DEFINITIONS if tool["name"] in allowed]
 
-    allowed = _HANDLER_TOOLS[handler_class_name] | _PROTOCOL_TOOLS
-    return [tool for tool in ADCP_TOOL_DEFINITIONS if tool["name"] in allowed]
+    return [tool for tool in ADCP_TOOL_DEFINITIONS if tool["name"] in _PROTOCOL_TOOLS]
 
 
 def create_tool_caller(
@@ -649,7 +654,7 @@ def __init__(self, handler: ADCPHandler):
             handler: ADCP handler instance
         """
         self.handler = handler
-        self._filtered_definitions = get_tools_for_handler(type(handler).__name__)
+        self._filtered_definitions = get_tools_for_handler(handler)
         self._tools: dict[str, Callable[[dict[str, Any]], Any]] = {}
 
         # Create tool callers only for filtered tools

tests/test_spec_coverage.py

@@ -77,7 +77,12 @@ def test_tool_filtering_by_handler_type():
     all_tool_names = {tool["name"] for tool in ADCP_TOOL_DEFINITIONS}
 
     # GovernanceHandler: governance tools + protocol discovery
-    gov_tools = {t["name"] for t in get_tools_for_handler("GovernanceHandler")}
+    from adcp.server.base import ADCPHandler
+    from adcp.server.content_standards import ContentStandardsHandler
+    from adcp.server.governance import GovernanceHandler
+    from adcp.server.sponsored_intelligence import SponsoredIntelligenceHandler
+
+    gov_tools = {t["name"] for t in get_tools_for_handler(GovernanceHandler)}
     assert gov_tools == {
         "get_creative_features", "sync_plans", "check_governance",
         "report_plan_outcome", "get_plan_audit_logs",
@@ -87,7 +92,7 @@ def test_tool_filtering_by_handler_type():
     }
 
     # ContentStandardsHandler: content standards tools + protocol discovery
-    cs_tools = {t["name"] for t in get_tools_for_handler("ContentStandardsHandler")}
+    cs_tools = {t["name"] for t in get_tools_for_handler(ContentStandardsHandler)}
     assert cs_tools == {
         "create_content_standards", "get_content_standards",
         "list_content_standards", "update_content_standards",
@@ -97,20 +102,23 @@ def test_tool_filtering_by_handler_type():
     }
 
     # SponsoredIntelligenceHandler: SI tools + protocol discovery
-    si_tools = {t["name"] for t in get_tools_for_handler("SponsoredIntelligenceHandler")}
+    si_tools = {t["name"] for t in get_tools_for_handler(SponsoredIntelligenceHandler)}
     assert si_tools == {
         "si_get_offering", "si_initiate_session",
         "si_send_message", "si_terminate_session",
         "get_adcp_capabilities",
     }
 
     # ADCPHandler: all tools (no filtering)
-    adcp_tools = {t["name"] for t in get_tools_for_handler("ADCPHandler")}
+    adcp_tools = {t["name"] for t in get_tools_for_handler(ADCPHandler)}
     assert adcp_tools == all_tool_names
 
-    # Unknown handler: protocol-only tools (minimum privilege)
-    unknown_tools = {t["name"] for t in get_tools_for_handler("SomeCustomHandler")}
-    assert unknown_tools == {"get_adcp_capabilities"}
+    # Subclass of GovernanceHandler gets governance tools (MRO walk)
+    class MyGovernanceAgent(GovernanceHandler):
+        pass
+
+    subclass_tools = {t["name"] for t in get_tools_for_handler(MyGovernanceAgent)}
+    assert subclass_tools == gov_tools
 
 
 def _collect_all_properties(schema: dict[str, Any]) -> set[str]: