@callback cache_control(arg()) :: {:public | :private, non_neg_integer()}

Returns the cache hint for this repository's resource listing.

This optional callback sets how resources/list results from the repository may be cached. Return {scope, ttl_ms}, where scope is :public or :private and ttl_ms is a non-negative lifetime in milliseconds. When the callback is not implemented, the Suite uses the no-cache default from GenMCP.MCP.V2607.default_cache_control/0.

@impl true
def cache_control(_arg), do: {:public, 60_000}

@callback list(pagination_token :: String.t() | nil, GenMCP.Mux.Channel.t(), arg()) ::
  {[resource_item()], next_cursor :: term() | nil}

Lists the concrete resources this repository advertises for resources/list.

Returns a {resources, next_cursor} tuple. Each element of resources is a resource_item/0 map describing one resource, whose :uri must begin with the repository's prefix/1. next_cursor carries pagination: return nil on the last page, or an opaque token that the Suite hands back as the pagination_token of the next call to fetch the following page.

The pagination_token is nil on the first call. channel is the request-scoped GenMCP.Mux.Channel.t/0, and arg is the configured value.

A single-page repository ignores the token and returns nil as the cursor:

@impl true
def list(_cursor, _channel, _arg) do
  resources = [
    %{uri: "file:///docs/intro.md", name: "intro.md", mimeType: "text/markdown"}
  ]

  {resources, nil}
end

To paginate, return a token on every page but the last, and resume from it on the next call:

@impl true
def list(nil, _channel, _arg), do: {first_page(), "page-2"}
def list("page-2", _channel, _arg), do: {second_page(), nil}

@callback parse_uri(uri :: String.t(), arg()) ::
  {:ok, %{required(String.t()) => term()}}
  | {:ok, String.t()}
  | {:error, String.t()}

Parses a requested URI into the value passed to read/3, for templated resources.

Implement this optional callback to take over URI parsing for a templated repository. When it is not implemented, the Suite matches the URI against the template/1 template and passes the extracted variables to read/3. When it is implemented, the Suite calls it instead and passes its result straight to read/3, so you control exactly what read/3 receives.

Return {:ok, value} to proceed to read/3 with value (a map of variables, a parsed term, or anything read/3 expects), or {:error, message} with a string message to reject the URI before any read happens. arg is the configured value.

@impl true
def parse_uri("file:///users/" <> id, _arg) when id != "" do
  {:ok, %{"id" => id}}
end

def parse_uri(uri, _arg) do
  {:error, "unsupported user URI: #{uri}"}
end

@callback prefix(arg()) :: String.t()

Returns the URI prefix shared by this repository's resources.

Every URI that list/3 returns, and every URI the repository can read, must start with this prefix, because the Suite uses it to route a resources/read to the right repository: it picks the repository whose prefix the requested URI starts with. The prefixes of the configured repositories must therefore be distinct. arg is the value configured alongside the module.

@impl true
def prefix(_arg), do: "file:///docs/"

@callback read(uri_or_template_args, GenMCP.Mux.Channel.t(), arg()) ::
  {:ok, GenMCP.MCP.V2607.ReadResourceResult.t()}
  | {:error, :not_found | String.t()}
when uri_or_template_args: String.t() | %{required(String.t()) => term()}

Reads the resource a URI points to, for resources/read.

The first argument is what the Suite resolved from the requested URI. For a repository without a template it is the URI string itself. For a templated repository (see template/1) it is the map of variables parsed out of the URI, so match the variables you declared.

Return {:ok, result} where result is a GenMCP.MCP.V2607.ReadResourceResult.t/0 built with GenMCP.MCP.V2607.read_resource_result/1. Return {:error, :not_found} when the URI names no resource the repository serves, which the Suite reports to the client as a resource-not-found error, or {:error, message} with a string message to report another problem.

channel is the request-scoped GenMCP.Mux.Channel.t/0, and arg is the configured value.

Reading a direct resource, matching on the URI string:

@impl true
def read("file:///docs/intro.md" = uri, _channel, _arg) do
  {:ok, MCP.read_resource_result(uri: uri, text: "# Introduction", mime_type: "text/markdown")}
end

def read(_uri, _channel, _arg), do: {:error, :not_found}

Reading a templated resource, matching on the parsed variables:

@impl true
def read(%{"id" => id}, _channel, _arg) do
  case MyApp.Accounts.fetch_user(id) do
    {:ok, user} ->
      {:ok, MCP.read_resource_result(uri: "file:///users/#{id}", text: user.bio)}

    :error ->
      {:error, :not_found}
  end
end

@callback template(arg()) :: template_descriptor()

Declares the URI template this repository serves, for templated resources.

Implement this optional callback when the repository answers a family of URIs described by one RFC 6570 template rather than a fixed list. Return a template_descriptor/0 map with at least :uriTemplate (the template string) and :name. The template is advertised through resources/templates/list, and it changes how read/3 is called: the matched URI is parsed into the template variables and those variables are handed to read/3 as a map.

The template string is parsed once when the repository is configured, so an invalid template raises at startup.

@impl true
def template(_arg) do
  %{
    uriTemplate: "file:///users/{id}",
    name: "User record",
    description: "A user's profile",
    mimeType: "application/json"
  }
end