refactor: move mcp adapter helper to wf_sources_mcp

src/wf_sources_mcp/adapters.py

@@ -0,0 +1,62 @@
+"""Canonical adapter lookup for MCP upstream source providers.
+
+``SourceAdapterRef`` and ``LegacyAdapterRef`` document the expected shape of
+source objects passed to ``require_adapter``.  Runtime validation uses
+duck-typing via ``_adapter_key`` because ``McpSourceConnection.server`` is a
+``@property`` that conflicts with Protocol structural typing.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Protocol
+
+from wf_sources_mcp.sdk import BackendAdapter
+
+
+class SourceAdapterRef(Protocol):
+    """Typed source identity used by `McpSourceConnection`."""
+
+    provider: str
+
+
+class LegacyAdapterRef(Protocol):
+    """Legacy broker source identity used by `ConnectionConfig`."""
+
+    server: str
+
+
+type AdapterLookupRef = SourceAdapterRef | LegacyAdapterRef
+
+
+def _adapter_key(source: object) -> str:
+    """Resolve adapter lookup key from a source reference.
+
+    Checks ``server`` first (legacy broker ``ConnectionConfig``), then
+    ``provider`` (typed ``McpSourceConnection``).  The values are identical
+    for ``McpSourceConnection`` (which exposes ``server`` as a property
+    alias), but ``server`` is checked first for legacy compatibility.
+    """
+    server = getattr(source, "server", None)
+    if isinstance(server, str):
+        return server
+    provider = getattr(source, "provider", None)
+    if isinstance(provider, str):
+        return provider
+    raise TypeError("source must expose a string 'server' or 'provider' attribute")
+
+
+def require_adapter(
+    source: object,  # duck-typed, not AdapterLookupRef — McpSourceConnection.server
+    # is a @property which conflicts with Protocol structural typing.
+    adapters: Mapping[str, BackendAdapter],
+) -> BackendAdapter:
+    """Return the adapter for a source or raise a useful lookup error."""
+    key = _adapter_key(source)
+    adapter = adapters.get(key)
+    if adapter is None:
+        raise KeyError(f"no adapter registered for source {key!r}")
+    return adapter
+
+
+__all__ = ["AdapterLookupRef", "LegacyAdapterRef", "SourceAdapterRef", "require_adapter"]