Phantom.Resource (phantom_mcp v0.3.2)

View Source

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

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

Summary

Types

blob_content()
list_response()
resource_link()
response()
text_content()

Functions

blob(binary, attrs \\ [])

Resource as binary content

list(resource_links, next_cursor)

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

resource_link(uri, resource_template, attrs \\ %{})

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(results)

Formats the response from an MCP Router to the MCP specification

text(text, attrs \\ %{})

Resource as text content

Types

blob_content()

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

list_response()

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

resource_link()

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

response()

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

text_content()

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

Functions

blob(binary, attrs \\ [])

(macro) 
@spec blob(binary(), Keyword.t() | map()) :: blob_content()

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(resource_links, next_cursor)

@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(uri, resource_template, attrs \\ %{})

@spec resource_link(string_uri :: String.t(), Phantom.ResourceTemplate.t(), map()) ::
  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(results)

Formats the response from an MCP Router to the MCP specification

text(text, attrs \\ %{})

(macro) 
@spec text(String.t() | map(), Keyword.t() | map()) :: text_content()

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
)