.. index:: single: mcp_tool_protocol .. _mcp_tool_protocol/0: .. rst-class:: right **protocol** ``mcp_tool_protocol`` ===================== Protocol for Logtalk objects that provide tools to be exposed via an MCP (Model Context Protocol) server. Implements the MCP 2025-06-18 specification. Implementing objects must define the set of tools available and handle tool calls. Tool metadata (names, titles, descriptions, parameter schemas) can be derived automatically from ``info/2`` and ``mode/2`` directives on the tool predicates, or can be specified explicitly via the ``tool/1`` predicate. | **Availability:** | ``logtalk_load(mcp_server(loader))`` | **Author:** Paulo Moura | **Version:** 0:3:0 | **Date:** 2026-02-24 | **Compilation flags:** | ``static`` | **Dependencies:** | (none) | **Remarks:** - Capabilities: Objects can optionally define ``capabilities/1`` to declare which MCP capabilities they require. Currently supported: ``elicitation`` (allows the server to ask the user questions during tool execution via MCP elicitation). If ``capabilities/1`` is not defined, only the ``tools`` capability is advertised. - Tool title: The tool title (human-friendly display name) is derived from a ``title`` key in the predicate ``info/2`` directive. If not specified, the predicate name (functor) is used as the title. - Structured output: Tools can declare an output schema via ``output_schema/2`` and return ``structured(StructuredContent)`` or ``structured(ContentItems, StructuredContent)`` results. The structured content is included in the ``structuredContent`` field of the tool call response alongside the ``content`` array. - Resource links: Tool results can include ``resource_link(URI, Name)`` or ``resource_link(URI, Name, Description, MimeType)`` content items in ``results/1`` lists. - Elicitation: Tools that need user interaction during execution should define ``tool_call/4`` instead of ``tool_call/3``. The extra argument is an elicitation closure that can be called as ``call(Elicit, Message, Schema, Answer)`` where ``Message`` is the prompt text (an atom), ``Schema`` is a JSON Schema curly-term for the requested input, and ``Answer`` is unified with ``accept(Content)``, ``decline``, or ``cancel``. | **Inherited public predicates:** | (none) .. contents:: :local: :backlinks: top Public predicates ----------------- .. index:: capabilities/1 .. _mcp_tool_protocol/0::capabilities/1: ``capabilities/1`` ^^^^^^^^^^^^^^^^^^ Returns a list of MCP capabilities required by this tool provider. Currently supported capabilities: ``elicitation`` (server can ask the user questions during tool execution). If not defined, only the ``tools`` capability is advertised. The server uses this to build the ``capabilities`` field in the ``initialize`` response. | **Compilation flags:** | ``static`` | **Template:** | ``capabilities(Capabilities)`` | **Mode and number of proofs:** | ``capabilities(-list(atom))`` - ``one`` ------------ .. index:: tools/1 .. _mcp_tool_protocol/0::tools/1: ``tools/1`` ^^^^^^^^^^^ Returns a list of tool descriptors available from this object. Each descriptor is a compound term ``tool(Name, Functor, Arity)`` where ``Name`` is the MCP tool name (an atom), ``Functor`` is the predicate functor, and ``Arity`` is the predicate arity. By default, the tool name is the predicate functor. Tool titles are derived from ``info/2`` ``title`` keys (falling back to the predicate name). Tool descriptions and parameter schemas are derived from the ``info/2`` and ``mode/2`` directives of the corresponding predicates. | **Compilation flags:** | ``static`` | **Template:** | ``tools(Tools)`` | **Mode and number of proofs:** | ``tools(-list(compound))`` - ``one`` ------------ .. index:: tool_call/3 .. _mcp_tool_protocol/0::tool_call/3: ``tool_call/3`` ^^^^^^^^^^^^^^^ Handles a tool call. ``Name`` is the MCP tool name (as declared in ``tools/1``), ``Arguments`` is a list of ``ArgumentName-Value`` pairs, and ``Result`` is unified with the tool result. The result must be one of: ``text(Atom)`` for a text result, ``error(Atom)`` for an error result, ``results(List)`` for a list of content items where each item is ``text(Atom)``, ``error(Atom)``, ``resource_link(URI, Name)``, or ``resource_link(URI, Name, Description, MimeType)``, ``structured(StructuredContent)`` for structured output with auto-generated text, or ``structured(ContentItems, StructuredContent)`` for structured output with explicit content items. If this predicate is not defined for a tool, the MCP server will use auto-dispatch: it calls the tool predicate as a message to the implementing object, collects output arguments, and returns them as a text result. | **Compilation flags:** | ``static`` | **Template:** | ``tool_call(Name,Arguments,Result)`` | **Mode and number of proofs:** | ``tool_call(+atom,+list(pair),--compound)`` - ``one`` ------------ .. index:: tool_call/4 .. _mcp_tool_protocol/0::tool_call/4: ``tool_call/4`` ^^^^^^^^^^^^^^^ Handles a tool call with elicitation support. Same as ``tool_call/3`` but receives an ``Elicit`` closure as the third argument. The closure can be called as ``call(Elicit, Message, Schema, Answer)`` where ``Message`` is a prompt text (an atom), ``Schema`` is a curly-term JSON Schema describing the requested input (e.g., ``{type-object, properties-{answer-{type-string, enum-[yes, no]}}, required-[answer]}``), and ``Answer`` is unified with ``accept(Content)`` (where ``Content`` is the user response as a curly-term), ``decline``, or ``cancel``. Only available when the application declares ``elicitation`` in its ``capabilities/1``. Falls back to ``tool_call/3`` and then auto-dispatch if not defined. | **Compilation flags:** | ``static`` | **Template:** | ``tool_call(Name,Arguments,Elicit,Result)`` | **Mode and number of proofs:** | ``tool_call(+atom,+list(pair),+callable,--compound)`` - ``one`` ------------ .. index:: output_schema/2 .. _mcp_tool_protocol/0::output_schema/2: ``output_schema/2`` ^^^^^^^^^^^^^^^^^^^ Returns the JSON output schema for the given tool name. Optional; when defined, the schema is included in the tool descriptor as ``outputSchema`` and the tool can return ``structured(StructuredContent)`` or ``structured(ContentItems, StructuredContent)`` results. The schema must be a curly-term following JSON Schema format (e.g. ``{type-object, properties-{temperature-{type-number}}, required-[temperature]}``). | **Compilation flags:** | ``static`` | **Template:** | ``output_schema(Name,Schema)`` | **Mode and number of proofs:** | ``output_schema(+atom,-compound)`` - ``zero_or_one`` ------------ Protected predicates -------------------- (none) Private predicates ------------------ (none) Operators --------- (none)