See prompt/3

Define a prompt that can be retrieved by the MCP client.

Examples

prompt :summarize,
  description: "A text prompt",
  completion_function: :summarize_complete,
  arguments: [
    %{
      name: "text",
      description: "The text to summarize",
    },
    %{
      name: "resource",
      description: "The resource to summarize",
    }
  ]
)

# ...

require Phantom.Prompt, as: Prompt
def summarize(args, _request, session) do
  {:reply, Prompt.response([
    assistant: Prompt.text("You're great"),
    user: Prompt.text("No you're great!")
  ], session}
end

def summarize_complete("text", _typed_value, session) do
  {:reply, ["many values"], session}
end

def summarize_complete("resource", _typed_value, session) do
  # list of IDs
  {:reply, ["123"], session}
end

@spec read_resource(Phantom.Session.t(), module(), URI.t()) ::
  {:ok, uri_string :: String.t(),
   Phantom.Resource.blob_content() | Phantom.Resource.text_content()}
  | {:error, error_response :: map()}

Reads the resource given its URI, primarily for embedded resources.

This is available on your router as: MyApp.MCP.Router.read_resource(session, name, params)

For example:

iex> MyApp.MCP.Router.read_resource(session, :my_resource, id: 321)
#=> {:ok, "myapp:///resources/123", %{
#   blob: "abc123"
#   uri: "myapp:///resources/123",
#   mimeType: "audio/wav",
#   name: "Some audio",
#   title: "Super audio"
# }

See resource/4

Define a resource that can be read by the MCP client.

Examples

resource "app:///studies/:id", MyApp.MCP, :read_study,
  description: "A study",
  mime_type: "application/json"

# ...

require Phantom.Resource, as: Resource
def read_study(%{"id" => id}, _request, session) do
  {:reply, Response.response(
    Response.text("IO.puts "Hi"")
  ), session}
end

Constructs a response map for the given resource with the provided parameters. This function is provided to your MCP Router that accepts the session instead.

For example

iex> MyApp.MCP.Router.resource_uri(session, :my_resource, id: 123)
{:ok, "myapp:///my-resource/123"}

iex> MyApp.MCP.Router.resource_uri(session, :my_resource, foo: "error")
{:error, "Parameters don't match resource."}

iex> MyApp.MCP.Router.resource_uri(session, :unknown, id: 123)
{:error, "Router not found for resource"}

See tool/3

Define a tool that can be called by the MCP client.

Examples

tool :local_echo,
  description: "A test that echos your message",
  # or supply a `@description` before defining the tool
  input_schema: %{
    required: [:message],
    properties: %{
      message: %{
        type: "string",
        description: "message to echo"
      }
    }
  }

### handled by your function syncronously:

def local_echo(params, session) do
  # Maps will be JSON-encoded and also provided
  # as structured content.
  {:reply, Phantom.Tool.text(params), session}
end

# Or asyncronously:

def local_echo(params, session) do
  Task.async(fn ->
    Process.sleep(1000)
    Session.respond(session, Phantom.Tool.text(params))
  end)

  {:noreply, session}
end