@callback cache_hints(method :: String.t()) :: %{
  ttl_ms: non_neg_integer(),
  scope: :public | :private
}

Returns the caching hints for a cacheable stateless-era result.

Revision 2026-07-28 requires ttlMs and cacheScope on the complete results of server/discover, tools/list, prompts/list, resources/list, resources/templates/list and resources/read. Optional; without it every such result says ttl_ms: 0 (stale at once) and scope: :private.

:public means the result is the same for every caller, so a shared cache may serve it to anyone; answer :private for anything that varies with the caller, such as a tool list filtered per user. A handler that puts "ttlMs" or "cacheScope" in its own result keeps them. Results of a multi round-trip retry, which carry client input, always say ttl_ms: 0.

Examples

@impl Anubis.Server
def cache_hints("tools/list"), do: %{ttl_ms: to_timeout(minute: 5), scope: :private}
def cache_hints(_method), do: %{ttl_ms: 0, scope: :private}

@callback handle_notification(
  notification :: notification(),
  state :: Anubis.Server.Frame.t()
) ::
  {:noreply, new_state :: Anubis.Server.Frame.t()}
  | {:error, error :: mcp_error(), new_state :: Anubis.Server.Frame.t()}

Handles incoming MCP notifications from clients.

@callback handle_prompt_get(
  name :: String.t(),
  arguments :: map(),
  Anubis.Server.Frame.t()
) ::
  {:reply, messages :: list(), Anubis.Server.Frame.t()}
  | {:error, mcp_error(), Anubis.Server.Frame.t()}

Handles a prompt get request.

@callback handle_request(request :: request(), state :: Anubis.Server.Frame.t()) ::
  {:reply, response :: response(), new_state :: Anubis.Server.Frame.t()}
  | {:noreply, new_state :: Anubis.Server.Frame.t()}
  | {:error, error :: mcp_error(), new_state :: Anubis.Server.Frame.t()}

Low-level handler for any MCP request.

When implemented, it bypasses automatic routing to specific handlers. Return {:reply, response, frame} to answer, {:error, error, frame} to report a failure, or {:noreply, frame} to complete without a response body. A no-reply completion is not deferred work: stateless HTTP returns 202 if headers have not been sent, or closes an open SSE response without a final event.

@callback handle_resource_read(uri :: String.t(), Anubis.Server.Frame.t()) ::
  {:reply, content :: map(), Anubis.Server.Frame.t()}
  | {:error, mcp_error(), Anubis.Server.Frame.t()}

Handles a resource read request.

@callback handle_session_expired(session_id :: String.t(), Anubis.Server.Frame.t()) ::
  {:ok, Anubis.Server.Frame.t()}
  | {:ok, client_info :: map(), Anubis.Server.Frame.t()}
  | {:error, reason :: term()}

Called when a session is being auto-recovered after expiry.

Invoked during auto_initialize/1 instead of the normal client handshake. Receives the session ID and the current frame (pre-populated from the session store if one is configured).

Return values:

• {:ok, frame} — accept recovery using synthetic client info
• {:ok, client_info, frame} — accept recovery and supply real client info
• {:error, reason} — reject recovery; the client receives an internal error

If this callback is not implemented, the default behavior is unchanged: synthetic client info is used and init/2 is called normally.

@callback handle_tool_call(
  name :: String.t(),
  arguments :: map(),
  Anubis.Server.Frame.t()
) ::
  {:reply, result :: term(), Anubis.Server.Frame.t()}
  | {:error, mcp_error(), Anubis.Server.Frame.t()}

Handles a tool call request.

This callback is invoked when a client calls a specific tool. It receives the tool name, the arguments provided by the client, and the current frame.

@callback init(client_info :: map(), Anubis.Server.Frame.t()) ::
  {:ok, Anubis.Server.Frame.t()} | {:error, term()}

Called after a client requests a initialize request.

This callback is invoked while the MCP handshake starts and so the client may not sent the notifications/initialized message yet. For checking if the notification was already sent and the MCP handshake was successfully completed, you can check the context.initialized field in the frame.

It receives the client's information and the current frame, allowing you to perform client-specific setup, validate capabilities, or prepare resources based on the connected client.

Returning {:error, reason} rejects the session: the transport answers the request with an encodable JSON-RPC error. Return an Anubis.MCP.Error struct to control the error code sent to the client; any other term is wrapped as an internal error with a stringified message.

Requests of the stateless era (2026-07-28 onward) have no handshake. Over Streamable HTTP each one is served by a session of its own, and init/2 runs for every such request, with the client info that request carries, before it is handled; clientInfo is optional in that era, and a request without it passes an empty map. The frame it returns lives only as long as the request.

@callback serialize_assigns(assigns :: map()) :: map()

Transforms frame.assigns into a JSON-safe map before session persistence.

frame.assigns is copied verbatim into the session store. Runtime values that are not JSON-encodable (Ecto structs, MapSet, PIDs, functions, etc.) make persistence fail. Implement this callback to project assigns down to the JSON-safe subset you actually need persisted (e.g. %{"user_id" => id}), avoiding storing full domain structs or PII.

On recovery, the restored frame is handed back to handle_session_expired/2, where the host rehydrates runtime state from these persisted values.

Defaults to the identity function when not implemented.

@callback server_instructions() :: String.t() | nil

Returns optional instructions describing how to use the server and its features.

This can be used by clients to improve the LLM's understanding of available tools, resources, etc. It can be thought of like a "hint" to the model. For example, this information MAY be added to the system prompt.

Return nil to omit the instructions field from the initialize response.

@callback server_instructions(frame :: Anubis.Server.Frame.t()) :: String.t() | nil

Returns the instructions for this connection, given the frame the handshake will answer with.

Optional, and takes precedence over server_instructions/0 when defined. The frame carries the transport's assigns — whatever a Plug put on the connection before the request reached the server — so a server whose guidance depends on who is asking can vary it here.

init/2 cannot serve this purpose: it runs when the client acknowledges the handshake, after the initialize result carrying the instructions has already been sent.

Examples

@impl Anubis.Server
def server_instructions(frame) do
  case frame.assigns[:plan] do
    :enterprise -> "You may call `bulk_export`. Confirm the range before exporting."
    _ -> "Exports run one record at a time."
  end
end

Return nil to omit the field from the initialize result.

@callback server_tools(
  tools :: [Anubis.Server.Component.Tool.t()],
  frame :: Anubis.Server.Frame.t()
) :: [
  Anubis.Server.Component.Tool.t()
]

Returns the tools this connection may list and call, given its frame.

Optional. It is applied to the compile-time components concatenated with the frame's runtime tools, every time the list is built — which is both tools/list and the lookup tools/call does, so a tool withheld here cannot be reached by name either.

The frame carries the transport's assigns, so a server whose surface depends on who is asking resolves it here rather than at registration. init/2 cannot serve this purpose: it runs once per session, and on a session restored from a store it runs before the request's assigns are attached.

Return the tools unchanged to serve everyone the same surface. A tool may also be returned rewritten — a description or a schema that names something one caller may not be shown is a connection-level decision, and the struct is the place to make it.

Examples

@impl Anubis.Server
def server_tools(tools, frame) do
  if frame.assigns[:plan] == :enterprise do
    tools
  else
    Enum.reject(tools, &(&1.name == "bulk_export"))
  end
end

@callback supported_protocol_versions() :: [String.t()]

Returns the protocol versions served by this server.

Defaults to all registered versions, including the stateless era. Set the :protocol_versions use option or implement this callback to restrict them. The initialize handshake only negotiates legacy versions.