Caravela.MCP.Tool behaviour (Caravela v0.11.0)

Copy Markdown View Source

Behaviour + registry for Caravela MCP tools.

A tool module implements:

  • name/0 — the wire-level tool name, exposed to the MCP client. By convention, prefix with caravela__ so tools show up grouped in host UIs.
  • description/0 — short prose explaining what the tool does.
  • input_schema/0 — JSON Schema for the tool's arguments.
  • call/1 — invoke the tool; returns structured content or an error.

Return shape

call/1 returns either {:ok, content} or {:error, message}.

content is a list of MCP content items. The common case is a single text item containing JSON:

{:ok, [%{"type" => "text", "text" => Jason.encode!(payload)}]}

The server wraps the result into the {content: [...], isError: false} shape MCP clients expect.

Summary

Callbacks

call(args)
description()
input_schema()
name()

Functions

find(name)

Look up a tool module by its wire-level name.

list()

The MCP tools/list response shape — one entry per registered tool with its name, description, and input schema.

plain_text(text)

Helper: wrap a plain string as a single text-content item.

registry()

The list of tool modules the server exposes. Add new tools here; the server picks them up automatically.

text_content(term)

Helper: wrap a JSON-serializable term as a single text-content item. Tools use this to return structured payloads (their JSON shape shows up to the LLM as the text of the content item).

Callbacks

call(args)

@callback call(args :: map()) ::
  {:ok, content :: [map()]} | {:error, message :: String.t()}

description()

@callback description() :: String.t()

input_schema()

@callback input_schema() :: map()

name()

@callback name() :: String.t()

Functions

find(name)

@spec find(String.t()) :: module() | nil

Look up a tool module by its wire-level name.

list()

@spec list() :: [map()]

The MCP tools/list response shape — one entry per registered tool with its name, description, and input schema.

plain_text(text)

@spec plain_text(String.t()) :: [map()]

Helper: wrap a plain string as a single text-content item.

registry()

@spec registry() :: [module()]

The list of tool modules the server exposes. Add new tools here; the server picks them up automatically.

text_content(term)

@spec text_content(term()) :: [map()]

Helper: wrap a JSON-serializable term as a single text-content item. Tools use this to return structured payloads (their JSON shape shows up to the LLM as the text of the content item).