barrel_mcp_tool_format (barrel_mcp v2.0.2)

View Source

Translators between MCP tool shapes and LLM provider tool shapes (Anthropic Messages API, OpenAI Chat Completions / Responses).

Use this module to bridge an MCP server's tools/list response into the tool definitions a provider expects, and to translate a provider's tool-call back into the (Name, Arguments) pair you feed to barrel_mcp_client:call_tool/4.

The MCP shape (one entry from tools/list) is:

   #{
     <<"name">>        := binary(),
     <<"description">> => binary(),
     <<"inputSchema">> => map(),
     <<"title">>       => binary(),     %% optional
     <<"annotations">> => map(),        %% optional
     ...                                 %% other MCP keys ignored
   }

The Anthropic shape (Messages API tools array entry) is:

   #{
     <<"name">>         := binary(),
     <<"description">>  := binary(),
     <<"input_schema">> := map()
   }

The OpenAI shape (Chat Completions tools array entry) is:

   #{
     <<"type">>     := <<"function">>,
     <<"function">> := #{
       <<"name">>        := binary(),
       <<"description">> := binary(),
       <<"parameters">>  := map()
     }
   }

Summary

Functions

Translate a single Anthropic tool_use content block into the (Name, Arguments) pair you can feed to barrel_mcp_client:call_tool/4. Accepts both the canonical binary-keyed map and the camelCase variant some clients emit.

Translate a single OpenAI tool_call object into the (Name, Arguments) pair. Accepts both the parsed-arguments shape (arguments is already a map) and the wire shape (arguments is a JSON string that needs decoding).

Translate one MCP tool, or a list of MCP tools, into the Anthropic Messages API tool format. Unknown MCP keys are ignored; missing description becomes an empty binary.

Translate one MCP tool, or a list of MCP tools, into the OpenAI Chat Completions tool format. Wraps each tool in the {type: "function", function: {...}} envelope OpenAI requires.

Types

mcp_tool/0

-type mcp_tool() :: map().

provider_tool/0

-type provider_tool() :: map().

tool_call/0

-type tool_call() :: {Name :: binary(), Args :: map()}.

Functions

from_anthropic_call(_)

-spec from_anthropic_call(map()) -> tool_call().

Translate a single Anthropic tool_use content block into the (Name, Arguments) pair you can feed to barrel_mcp_client:call_tool/4. Accepts both the canonical binary-keyed map and the camelCase variant some clients emit.

from_openai_call(_)

-spec from_openai_call(map()) -> tool_call().

Translate a single OpenAI tool_call object into the (Name, Arguments) pair. Accepts both the parsed-arguments shape (arguments is already a map) and the wire shape (arguments is a JSON string that needs decoding).

to_anthropic(Tools)

-spec to_anthropic(mcp_tool() | [mcp_tool()]) -> provider_tool() | [provider_tool()].

Translate one MCP tool, or a list of MCP tools, into the Anthropic Messages API tool format. Unknown MCP keys are ignored; missing description becomes an empty binary.

to_openai(Tools)

-spec to_openai(mcp_tool() | [mcp_tool()]) -> provider_tool() | [provider_tool()].

Translate one MCP tool, or a list of MCP tools, into the OpenAI Chat Completions tool format. Wraps each tool in the {type: "function", function: {...}} envelope OpenAI requires.