# `Phantom.Resource`
[🔗](https://github.com/dbernheisel/phantom_mcp/blob/main/lib/phantom/resource.ex#L1)

The Model Context Protocol (MCP) provides a standardized way for
servers to expose resources to clients. Resources allow servers to
share data that provides context to language models, such as files,
database schemas, or application-specific information. Each resource
is uniquely identified by a URI.

https://modelcontextprotocol.io/specification/2025-03-26/server/resources

```mermaid
sequenceDiagram
    participant Client
    participant Server

    Note over Client,Server: Resource Discovery
    Client->>Server: resources/list
    Server-->>Client: List of resources

    Note over Client,Server: Resource Access
    Client->>Server: resources/read
    Server-->>Client: Resource contents

    Note over Client,Server: Subscriptions
    Client->>Server: resources/subscribe
    Server-->>Client: Subscription confirmed

    Note over Client,Server: Updates
    Server--)Client: notifications/resources/updated
    Client->>Server: resources/read
    Server-->>Client: Updated contents
```

# `blob_content`

```elixir
@type blob_content() :: %{
  :blob => binary(),
  :uri => String.t(),
  optional(:mimeType) => String.t(),
  optional(:name) => String.t(),
  optional(:title) => String.t()
}
```

# `list_response`

```elixir
@type list_response() :: %{nextCursor: String.t() | nil, resources: [resource_link()]}
```

# `resource_link`

```elixir
@type resource_link() :: %{
  uri: String.t(),
  name: String.t(),
  description: String.t(),
  mimeType: String.t()
}
```

# `response`

```elixir
@type response() :: %{contents: [blob_content() | text_content()]}
```

# `text_content`

```elixir
@type text_content() :: %{
  :text => binary(),
  :uri => String.t(),
  optional(:mimeType) => String.t(),
  optional(:name) => String.t(),
  optional(:title) => String.t()
}
```

# `blob`
*macro* 

Resource as binary content

The `:uri` and `:mime_type` will be fetched from the current resource template
within the scope of the request if not provided, but you will need to provide
the rest.

- `binary` - Binary data. This will be base64-encoded by Phantom.
- `:uri` (required) Unique identifier for the resource
- `:name` (optional) The name of the resource.
- `:title` (optional) human-readable name of the resource for display purposes.
- `:description` (optional) Description
- `:mime_type` (optional) MIME type
- `:size` (optional) Size in bytes

For example:

    Phantom.Resource.blob(
      File.read!("foo.png"),
      uri: "test://my-foos/123",
      mime_type: "image/png"
    )

# `list`

```elixir
@spec list([resource_link()], cursor :: String.t() | nil) :: list_response()
```

Formats the response from the MCP Router to the MCP specification for listing resources

# `resource_link`

```elixir
@spec resource_link(
  string_uri :: String.t(),
  Phantom.ResourceTemplate.t(),
  Access.t()
) ::
  resource_link()
```

Formats a resource_template and the provided attributes as a resource link. This is
typicaly used when listing resources or when tools embed a resource_link within its result.

# `response`

Formats the response from an MCP Router to the MCP specification

# `text`
*macro* 

Resource as text content

The `:uri` and `:mime_type` will be fetched from the current resource template
within the scope of the request if not provided, but you will need to provide
the rest.

- `text` - Text data. If a map, then it will be encoded into JSON and `:mime_type` will be set accordingly unless provided.
- `:uri` (required) Unique identifier for the resource
- `:name` (optional) The name of the resource.
- `:title` (optional) human-readable name of the resource for display purposes.
- `:description` (optional) Description
- `:mime_type` (optional) MIME type. Defaults to `"text/plain"`
- `:size` (optional) Size in bytes

For example:

    Phantom.ResourceTemplate.text(
      "## Why hello there",
      uri: "test://obi-wan-quotes/hello-there",
      mime_type: "text/markdown"
    )

    Phantom.ResourceTemplate.text(
      %{why: "hello there"},
      uri: "test://my-foos/json",
      # mime_type: "application/json"  # set by Phantom
    )

---

*Consult [api-reference.md](api-reference.md) for complete listing*