mcp_kit

defmodule MCPKit.Resource do
  @moduledoc """
  Behaviour for MCP resources.

  Resource modules expose concrete resource entries, URI templates, and reading
  logic for concrete URIs. They may optionally implement `complete/3` for URI
  template variable suggestions.
  """

  @doc """
  Returns the description for the resource module.
  """
  @callback description() :: String.t() | nil

  @doc """
  Returns concrete resources shown in `resources/list`.
  """
  @callback resources() :: [map()]

  @doc """
  Returns URI templates shown in `resources/templates/list`.
  """
  @callback templates() :: [map()]

  @doc """
  Returns URI template variable completion suggestions.

  Return `:unsupported` when the resource does not expose completions for the
  given variable.
  """
  @callback complete(String.t(), map(), map()) :: {:ok, [String.t()]} | :unsupported

  @doc """
  Reads a concrete resource URI.

  Return `{:error, :not_found}` when the resource does not handle the URI.
  """
  @callback read(uri :: String.t(), context :: map()) ::
              {:reply, [map()], map()}
              | {:error, :not_found | {:forbidden, String.t()} | {:internal_error, String.t()}}

  defmacro __using__(_opts) do
    quote do
      @behaviour MCPKit.Resource

      def description, do: MCPKit.Tool.module_description(@moduledoc)
      def resources, do: []
      def templates, do: []
      def complete(_variable_name, _arguments, _context), do: :unsupported

      defoverridable description: 0, resources: 0, templates: 0, complete: 3
    end
  end
end