@callback handle_call(
  request :: term(),
  from :: GenServer.from(),
  Anubis.Server.Frame.t()
) ::
  {:reply, reply :: term(), Anubis.Server.Frame.t()}
  | {:reply, reply :: term(), Anubis.Server.Frame.t(),
     timeout() | :hibernate | {:continue, arg :: term()}}
  | {:noreply, Anubis.Server.Frame.t()}
  | {:noreply, Anubis.Server.Frame.t(),
     timeout() | :hibernate | {:continue, arg :: term()}}
  | {:stop, reason :: term(), reply :: term(), Anubis.Server.Frame.t()}
  | {:stop, reason :: term(), Anubis.Server.Frame.t()}

Handles synchronous calls to the server process.

This optional callback allows you to handle custom synchronous calls made to your MCP server process using GenServer.call/2. This is useful for implementing administrative functions, status queries, or any synchronous operations that need to interact with the server's internal state.

The callback follows standard GenServer semantics and should return appropriate reply tuples. If not implemented, the Base module provides a default implementation that handles standard MCP operations.

@callback handle_cast(request :: term(), Anubis.Server.Frame.t()) ::
  {:noreply, Anubis.Server.Frame.t()}
  | {:noreply, Anubis.Server.Frame.t(),
     timeout() | :hibernate | {:continue, arg :: term()}}
  | {:stop, reason :: term(), Anubis.Server.Frame.t()}

Handles asynchronous casts to the server process.

This optional callback allows you to handle custom asynchronous messages sent to your MCP server process using GenServer.cast/2. This is useful for fire-and-forget operations, background tasks, or any asynchronous operations that don't require an immediate response.

The callback follows standard GenServer semantics. If not implemented, the Base module provides a default implementation that handles standard MCP operations.

@callback handle_completion(ref :: String.t(), argument :: map(), Anubis.Server.Frame.t()) ::
  {:reply, Anubis.Server.Response.t() | map(), Anubis.Server.Frame.t()}
  | {:error, mcp_error(), Anubis.Server.Frame.t()}

Handles completion requests from the client.

This callback is invoked when a client requests completions for a reference. The reference indicates what type of completion is being requested.

Note: This callback will only be invoked if user declared the completion capability on server definition

@callback handle_info(event :: term(), Anubis.Server.Frame.t()) ::
  {:noreply, Anubis.Server.Frame.t()}
  | {:noreply, Anubis.Server.Frame.t(),
     timeout() | :hibernate | {:continue, arg :: term()}}
  | {:stop, reason :: term(), Anubis.Server.Frame.t()}

Handles non-MCP messages sent to the server process.

While handle_request and handle_notification deal with MCP protocol messages, this callback handles everything else - timer events, messages from other processes, system signals, and any custom inter-process communication your server needs.

This is particularly useful for servers that need to react to external events (like file system changes or database updates) and notify connected clients through MCP notifications. Think of it as the bridge between your Elixir application's internal events and the MCP protocol's notification system.

@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.

Notifications are one-way messages in the MCP protocol - the client informs the server about events or state changes without expecting a response. This fire-and-forget pattern is perfect for status updates, progress tracking, and lifecycle events.

Standard MCP Notifications from Clients:

• notifications/initialized - Client signals it's ready after successful initialization
• notifications/cancelled - Client requests cancellation of an in-progress operation
• notifications/progress - Client reports progress on a long-running operation
• notifications/roots/list_changed - Client's available filesystem roots have changed

Unlike requests, notifications never receive responses. Any errors during processing are typically logged but not communicated back to the client. This makes notifications ideal for optional features like progress tracking where delivery isn't guaranteed.

The server processes these notifications to update its internal state, trigger side effects, or coordinate with other parts of the system. When using use Anubis.Server, basic notification handling is provided, but you'll often want to override this callback to handle progress updates or cancellations specific to your server's operations.

@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.

This callback is invoked when a client requests a specific prompt template. It receives the prompt name, any arguments to fill into the template, and the current frame.

This callback handles both module-based components (registered with component) and runtime components (registered with Frame.register_prompt/3). For module-based prompts, the framework automatically generates pattern-matched clauses during compilation.

@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.

This is an advanced callback that gives you complete control over request handling. When implemented, it bypasses the automatic routing to handle_tool_call/3, handle_resource_read/2, and handle_prompt_get/3 and all other requests that are handled internally, like tools/list and logging/setLevel.

Use this when you need to:

• Implement custom request methods beyond the standard MCP protocol
• Add middleware-like processing before requests reach specific handlers
• Override the framework's default request routing behavior

Note: If you implement this callback, you become responsible for handling ALL MCP requests, including standard protocol methods like tools/list, resources/list, etc. Consider using the specific callbacks instead unless you need this level of control.

@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.

This callback is invoked when a client requests to read a specific resource. It receives the resource URI and the current frame. Developer's implementation should retrieve and return the resource content.

This callback handles both module-based components (registered with component) and runtime components (registered with Frame.register_resource/3). For module-based resources, the framework automatically generates pattern-matched clauses during compilation.

@callback handle_roots(
  roots :: [map()],
  request_id :: String.t(),
  Anubis.Server.Frame.t()
) ::
  {:noreply, Anubis.Server.Frame.t()}
  | {:stop, reason :: term(), Anubis.Server.Frame.t()}

Handles the response from a roots/list request sent to the client.

This callback is invoked when the client responds to a roots list request initiated by the server. The response contains the available root URIs.

@callback handle_sampling(
  response :: map(),
  request_id :: String.t(),
  Anubis.Server.Frame.t()
) ::
  {:noreply, Anubis.Server.Frame.t()}
  | {:stop, reason :: term(), Anubis.Server.Frame.t()}

Handles the response from a sampling/createMessage request sent to the client.

This callback is invoked when the client responds to a sampling request initiated by the server. The response contains the generated message from the client's LLM.

Parameters

• response - The response from the client containing:
  • "role" - The role of the generated message (typically "assistant")
  • "content" - The content object with type and data
  • "model" - The model used for generation
  • "stopReason" - Why generation stopped (e.g., "endTurn")
• request_id - The ID of the original request for correlation
• frame - The current server frame

Returns

• {:noreply, frame} - Continue processing
• {:stop, reason, frame} - Stop the server

Examples

def handle_sampling(response, request_id, frame) do
  %{"content" => %{"text" => text}} = response
  # Process the generated text...
  {:noreply, frame}
end

@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. Developers's implementation should execute the tool's logic and return the result.

This callback handles both module-based components (registered with component) and runtime components (registered with Frame.register_tool/3). For module-based tools, the framework automatically generates pattern-matched clauses during compilation.

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

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 handshare was successfully completed, you can call the initialized?/1 function.

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.

The client_info parameter contains details about the connected client including its name, version, and any additional metadata. Use this to tailor your server's behavior to specific client implementations or versions.

@callback server_capabilities() :: server_capabilities()

Declares the server's capabilities during initialization.

This callback tells clients what features your server supports - which types of resources it can provide, what tools it can execute, whether it supports logging configuration, etc. The capabilities you declare here directly impact which requests the client will send.

When using use Anubis.Server with the capabilities option, this callback is automatically implemented based on your configuration. The macro analyzes your registered components and builds the appropriate capability map, so you rarely need to implement this manually.

@callback server_info() :: server_info()

Provides the server's identity information during initialization.

This callback is called during the MCP handshake to identify your server to connecting clients. The information returned here helps clients understand which server they're talking to and ensures version compatibility.

When using use Anubis.Server, this callback is automatically implemented using the name and version options you provide. You only need to implement this manually if you require dynamic server information based on runtime conditions.

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

Specifies which MCP protocol versions this server can speak.

Protocol version negotiation ensures client and server can communicate effectively. During initialization, the client and server agree on a mutually supported version. This callback returns the list of versions your server understands, typically in order of preference from newest to oldest.

When using use Anubis.Server, this is automatically implemented with sensible defaults covering current and recent protocol versions. Override only if you need to restrict or extend version support for specific compatibility requirements.

@callback terminate(reason :: term(), Anubis.Server.Frame.t()) :: term()

Cleans up when the server process terminates.

This optional callback is invoked when the server process is about to terminate. It allows you to perform cleanup operations, close connections, save state, or release resources before the process exits.

The callback receives the termination reason and the current frame. Any return value is ignored. If not implemented, the Base module provides a default implementation that logs the termination event.