AshAi.McpResource (ash_ai v1.5.6)

Copy Markdown View Source

An MCP resource to expose via the Model Context Protocol (MCP).

MCP resources provide LLMs with access to static or dynamic content like UI components, data files, or images. Unlike tools which perform actions, resources return content that the LLM can read and reference.

Example

defmodule MyApp.Blog do
  use Ash.Domain, extensions: [AshAi]

  mcp_resources do
    # Description inherited from :render_card action
    mcp_resource :post_card, "file://ui/post_card.html", Post, :render_card,
      mime_type: "text/html"

    # Custom description overrides action description
    mcp_resource :post_data, "file://data/post.json", Post, :to_json,
      description: "JSON metadata including author, tags, and timestamps",
      mime_type: "application/json"
  end
end

The action is called when an MCP client reads the resource. An action that returns :string is sent as text and one that returns :binary as a base64 blob, with the resource's MIME type. To choose per read, such as a photo's MIME type, set contents (see AshAi.McpResource.Contents). An action that returns nil or fails with Ash.Error.Query.NotFound is sent as resource not found.

URI templates

A URI containing {...} is an RFC 6570 URI template. It is listed by resources/templates/list instead of resources/list, and each variable is passed to the action as the argument of the same name, percent-decoded:

mcp_resource :photo, "photos://{id}{?size}", Photo, :get do
  title "Photo"
  contents &MyAppWeb.McpViews.photo/2
end

Supported are {var} (one path segment), {+var} (may span segments) and a trailing {?var,...} (optional query variables; a query naming any other key doesn't match). A URI matching a resource exactly is read from that resource; otherwise templates are tried in the order they're declared. Validate template variables like any other input: a client can put anything in them.

Description Behavior

Resource descriptions default to the action's description. You can provide a custom description option in the DSL which takes precedence over the action description. This helps LLMs understand when to use each resource.

Summary

Types

t()

@type t() :: %AshAi.McpResource{
  __spark_metadata__: term(),
  action: atom() | Ash.Resource.Actions.Action.t(),
  contents: {module(), Keyword.t()} | nil,
  description: String.t(),
  domain: module() | nil,
  mime_type: String.t() | nil,
  name: atom(),
  resource: Ash.Resource.t(),
  title: String.t(),
  uri: String.t(),
  uri_template: AshAi.Mcp.UriTemplate.t() | nil
}