refactor(phase-1): abstract protocol version negotiation

Author: zoedsoupe

lib/anubis/client/state.ex

@@ -14,13 +14,13 @@ defmodule Anubis.Client.State do
           server_capabilities: map() | nil,
           server_info: map() | nil,
           protocol_version: String.t(),
+          protocol_module: module() | nil,
           timeout: pos_integer(),
           transport: map(),
           pending_requests: %{String.t() => Request.t()},
           progress_callbacks: %{String.t() => Base.progress_callback()},
           log_callback: Base.log_callback() | nil,
           sampling_callback: (map() -> {:ok, map()} | {:error, String.t()}) | nil,
-          # Use a map with URI as key for faster access
           roots: %{String.t() => Base.root()}
         }
 
@@ -31,6 +31,7 @@ defmodule Anubis.Client.State do
     :server_info,
     :timeout,
     :protocol_version,
+    :protocol_module,
     :transport,
     pending_requests: %{},
     progress_callbacks: %{},
@@ -41,10 +42,17 @@ defmodule Anubis.Client.State do
 
   @spec new(map()) :: t()
   def new(opts) do
+    protocol_module =
+      case Anubis.Protocol.Registry.get(opts.protocol_version) do
+        {:ok, mod} -> mod
+        :error -> nil
+      end
+
     %__MODULE__{
       client_info: opts.client_info,
       capabilities: opts.capabilities,
       protocol_version: opts.protocol_version,
+      protocol_module: protocol_module,
       transport: opts.transport,
       timeout: opts.timeout
     }

lib/anubis/mcp/message.ex

@@ -632,6 +632,24 @@ defmodule Anubis.MCP.Message do
   """
   def progress_params_schema, do: @progress_notif_params_schema
 
+  @doc """
+  Returns the progress notification parameters schema for a given protocol version.
+
+  Delegates to the version module via `Anubis.Protocol.Registry`.
+
+  ## Examples
+
+      iex> Message.progress_params_schema_for("2024-11-05")
+      %{"progressToken" => {:required, {:either, {:string, :integer}}}, ...}
+
+      iex> Message.progress_params_schema_for("2025-03-26")
+      %{"progressToken" => ..., "message" => :string}
+  """
+  @spec progress_params_schema_for(String.t()) :: {:ok, map()} | :error
+  def progress_params_schema_for(version) do
+    Anubis.Protocol.Registry.progress_params_schema(version)
+  end
+
   @doc """
   Builds a response message map without encoding to JSON.
 

lib/anubis/protocol.ex

@@ -1,77 +1,55 @@
 defmodule Anubis.Protocol do
-  @moduledoc false
+  @moduledoc """
+  MCP protocol version management.
+
+  Provides version validation, negotiation, feature detection, and transport
+  compatibility checking. Delegates version-specific logic to modules under
+  `Anubis.Protocol.*` via `Anubis.Protocol.Registry`.
+
+  ## Adding a new protocol version
+
+  1. Create a new module under `lib/anubis/protocol/` implementing `Anubis.Protocol.Behaviour`
+  2. Register it in `Anubis.Protocol.Registry`
+  """
 
   alias Anubis.MCP.Error
+  alias Anubis.Protocol.Registry
 
   @type version :: String.t()
   @type feature :: atom()
 
-  @supported_versions ["2024-11-05", "2025-03-26", "2025-06-18"]
-  @latest_version "2025-06-18"
-  @fallback_version "2025-03-26"
-
-  @features_2024_11_05 [
-    :basic_messaging,
-    :resources,
-    :tools,
-    :prompts,
-    :logging,
-    :progress,
-    :cancellation,
-    :ping,
-    :roots,
-    :sampling
-  ]
-
-  @features_2025_03_26 [
-    :authorization,
-    :audio_content,
-    :tool_annotations,
-    :progress_messages,
-    :completion_capability
-    | @features_2024_11_05
-  ]
-
-  @features_2025_06_18 [
-    :elicitation,
-    :structured_tool_results,
-    :tool_output_schemas,
-    :model_preferences,
-    :embedded_resources_in_prompts,
-    :embedded_resources_in_tools
-    | @features_2025_03_26
-  ]
-
   @doc """
   Returns all supported protocol versions.
   """
   @spec supported_versions() :: [version()]
-  def supported_versions, do: @supported_versions
+  defdelegate supported_versions(), to: Registry
 
   @doc """
   Returns the latest supported protocol version.
   """
   @spec latest_version() :: version()
-  def latest_version, do: @latest_version
+  defdelegate latest_version(), to: Registry
 
   @doc """
   Returns the fallback protocol version for compatibility.
   """
   @spec fallback_version() :: version()
-  def fallback_version, do: @fallback_version
+  defdelegate fallback_version(), to: Registry
 
   @doc """
   Validates if a protocol version is supported.
   """
   @spec validate_version(version()) :: :ok | {:error, Error.t()}
-  def validate_version(version) when version in @supported_versions, do: :ok
-
   def validate_version(version) do
-    {:error,
-     Error.protocol(:invalid_params, %{
-       version: version,
-       supported: @supported_versions
-     })}
+    if Registry.supported?(version) do
+      :ok
+    else
+      {:error,
+       Error.protocol(:invalid_params, %{
+         version: version,
+         supported: supported_versions()
+       })}
+    end
   end
 
   @doc """
@@ -95,28 +73,29 @@ defmodule Anubis.Protocol do
 
   defp supported_transport_versions(transport) do
     case transport.supported_protocol_versions() do
-      :all -> @supported_versions
+      :all -> supported_versions()
       [_ | _] = versions -> versions
     end
   end
 
   @doc """
   Returns the set of features supported by a protocol version.
+
+  Delegates to the version module's `supported_features/0` callback.
   """
   @spec get_features(version()) :: list(feature())
-  def get_features("2024-11-05"), do: @features_2024_11_05
-  def get_features("2025-03-26"), do: @features_2025_03_26
-  def get_features("2025-06-18"), do: @features_2025_06_18
+  def get_features(version) do
+    case Registry.get_features(version) do
+      {:ok, features} -> features
+      :error -> []
+    end
+  end
 
   @doc """
   Checks if a feature is supported by a protocol version.
   """
   @spec supports_feature?(version(), feature()) :: boolean()
-  def supports_feature?(version, feature) when is_binary(version) and is_atom(feature) do
-    version
-    |> get_features()
-    |> Enum.member?(feature)
-  end
+  defdelegate supports_feature?(version, feature), to: Registry
 
   @doc """
   Negotiates protocol version between client and server versions.
@@ -127,25 +106,36 @@ defmodule Anubis.Protocol do
           {:ok, version()} | {:error, Error.t()}
   def negotiate_version(client_version, server_version) do
     cond do
-      client_version == server_version and client_version in @supported_versions ->
+      client_version == server_version and Registry.supported?(client_version) ->
         {:ok, client_version}
 
-      server_version in @supported_versions ->
+      Registry.supported?(server_version) ->
         {:ok, server_version}
 
-      client_version in @supported_versions ->
+      Registry.supported?(client_version) ->
         {:ok, client_version}
 
       true ->
         {:error,
          Error.protocol(:invalid_params, %{
            client_version: client_version,
            server_version: server_version,
-           supported: @supported_versions
+           supported: supported_versions()
          })}
     end
   end
 
+  @doc """
+  Returns the protocol module for a given version string.
+
+  ## Examples
+
+      iex> Anubis.Protocol.get_module("2025-06-18")
+      {:ok, Anubis.Protocol.V2025_06_18}
+  """
+  @spec get_module(version()) :: {:ok, module()} | :error
+  defdelegate get_module(version), to: Registry, as: :get
+
   @doc """
   Returns transport modules that support a protocol version.
   """

lib/anubis/protocol/behaviour.ex

@@ -0,0 +1,42 @@
+defmodule Anubis.Protocol.Behaviour do
+  @moduledoc """
+  Behaviour that each MCP protocol version module must implement.
+
+  Each protocol version (e.g., 2024-11-05, 2025-03-26, 2025-06-18) implements
+  this behaviour to isolate version-specific logic. This makes it trivial to add
+  support for new MCP spec versions without scattering conditionals across the codebase.
+
+  ## Version differences
+
+  - **2024-11-05**: Initial spec, SSE transport, basic tools/resources/prompts
+  - **2025-03-26**: Added Streamable HTTP, JSON-RPC batching, authorization framework, tool annotations
+  - **2025-06-18**: Removed batching, added structured tool output, elicitation, resource_link type
+  """
+
+  @type version :: String.t()
+  @type method :: String.t()
+  @type params :: map()
+  @type message :: map()
+  @type feature :: atom()
+
+  @doc "Returns the version string this module implements (e.g., '2025-03-26')."
+  @callback version() :: version()
+
+  @doc "List of features/capabilities this protocol version supports."
+  @callback supported_features() :: [feature()]
+
+  @doc "Peri schema for validating request params by method for this version."
+  @callback request_params_schema(method()) :: term()
+
+  @doc "Peri schema for validating notification params by method for this version."
+  @callback notification_params_schema(method()) :: term()
+
+  @doc "Progress notification params schema for this version."
+  @callback progress_params_schema() :: map()
+
+  @doc "All request methods supported by this version."
+  @callback request_methods() :: [method()]
+
+  @doc "All notification methods supported by this version."
+  @callback notification_methods() :: [method()]
+end