.. index:: single: mcp_server_application
.. _mcp_server_application/0:

.. rst-class:: right

**category**

``mcp_server_application``
==========================

Common predicates for MCP servers: tool/prompt/resource descriptor conversion, completion request handling, schema derivation from ``info/2`` and ``mode/2`` directives, auto-dispatch, canonical complete-result terms, curly-term predicates, and MCP Apps (``_meta.ui``) metadata.

| **Availability:** 
|    ``logtalk_load(mcp_server(loader))``

| **Author:** Paulo Moura
| **Version:** 1:0:0
| **Date:** 2026-09-07

| **Compilation flags:**
|    ``static``


| **Extends:**
|    ``public`` :ref:`options <options/0>`
| **Uses:**
|    :ref:`list <list/0>`
|    :ref:`term_io <term_io/0>`
|    :ref:`uri_template(Representation) <uri_template/1>`
|    :ref:`user <user/0>`

| **Remarks:**
|    (none)

| **Inherited public predicates:**
|     :ref:`options_protocol/0::check_option/1`  :ref:`options_protocol/0::check_options/1`  :ref:`options_protocol/0::default_option/1`  :ref:`options_protocol/0::default_options/1`  :ref:`options_protocol/0::option/2`  :ref:`options_protocol/0::option/3`  :ref:`options_protocol/0::valid_option/1`  :ref:`options_protocol/0::valid_options/1`  

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: tool_descriptors_to_json/3
.. _mcp_server_application/0::tool_descriptors_to_json/3:

``tool_descriptors_to_json/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Converts a list of ``tool(Name, Functor, Arity)`` descriptors into MCP JSON tool definitions, deriving titles, descriptions and input schemas from the application object's ``info/2`` and ``mode/2`` directives.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``tool_descriptors_to_json(ToolDescriptors,Application,JsonTools)``
| **Mode and number of proofs:**
|    ``tool_descriptors_to_json(+list,+object_identifier,-list)`` - ``one``


------------

Protected predicates
--------------------

.. index:: prompt_descriptors_to_json/2
.. _mcp_server_application/0::prompt_descriptors_to_json/2:

``prompt_descriptors_to_json/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Converts prompt descriptors (3-arg or 4-arg) into MCP JSON prompt definitions.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``prompt_descriptors_to_json(PromptDescriptors,JsonPrompts)``
| **Mode and number of proofs:**
|    ``prompt_descriptors_to_json(+list,-list)`` - ``one``


------------

.. index:: resource_descriptors_to_json/3
.. _mcp_server_application/0::resource_descriptors_to_json/3:

``resource_descriptors_to_json/3``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Converts resource descriptors (4-arg or 5-arg) into MCP JSON resource definitions. When the application defines ``resource_ui_meta/2``, attaches ``_meta.ui`` (MCP Apps).

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``resource_descriptors_to_json(Descriptors,Application,Resources)``
| **Mode and number of proofs:**
|    ``resource_descriptors_to_json(+list,+object_identifier,-list)`` - ``one``


------------

.. index:: resource_template_descriptors_to_json/2
.. _mcp_server_application/0::resource_template_descriptors_to_json/2:

``resource_template_descriptors_to_json/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Converts resource template descriptors (4-arg or 5-arg) into MCP JSON resource template definitions. No partial list is returned when a descriptor is invalid.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``resource_template_descriptors_to_json(Descriptors,ResourceTemplates)``
| **Mode and number of proofs:**
|    ``resource_template_descriptors_to_json(+list,-list)`` - ``one_or_error``

| **Exceptions:**
|    A descriptor contains an invalid RFC 6570 URI template ``URITemplate``:
|        ``domain_error(uri_template,URITemplate)``


------------

.. index:: application_resource_template_uri/2
.. _mcp_server_application/0::application_resource_template_uri/2:

``application_resource_template_uri/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Checks that a concrete resource URI matches the literal segments of one of the application resource templates. Full RFC 6570 expression validation and authorization remain application responsibilities.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``application_resource_template_uri(Application,URI)``
| **Mode and number of proofs:**
|    ``application_resource_template_uri(+object_identifier,+atom)`` - ``zero_or_one``


------------

.. index:: completion_request/5
.. _mcp_server_application/0::completion_request/5:

``completion_request/5``
^^^^^^^^^^^^^^^^^^^^^^^^

Validates and normalizes completion request parameters. The normalized reference is ``prompt(Name)`` or ``resource(URI)``, the argument is a ``Name-PartialValue`` pair, and the context is a list of prior argument pairs.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``completion_request(Application,Params,Reference,Argument,Context)``
| **Mode and number of proofs:**
|    ``completion_request(+object_identifier,+compound,-compound,-pair,-list)`` - ``zero_or_one``


------------

.. index:: completion_result_to_json/2
.. _mcp_server_application/0::completion_result_to_json/2:

``completion_result_to_json/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Validates and converts a completion result to its MCP JSON curly-term representation.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``completion_result_to_json(Result,JsonCompletion)``
| **Mode and number of proofs:**
|    ``completion_result_to_json(+compound,-compound)`` - ``zero_or_one``


------------

.. index:: auto_dispatch_tool/5
.. _mcp_server_application/0::auto_dispatch_tool/5:

``auto_dispatch_tool/5``
^^^^^^^^^^^^^^^^^^^^^^^^

Auto-dispatches a tool call by calling the predicate on the application, collecting output-mode arguments, and returning structured output with a backwards-compatible text content item.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``auto_dispatch_tool(Application,Functor,Arity,ToolArguments,Result)``
| **Mode and number of proofs:**
|    ``auto_dispatch_tool(+object_identifier,+atom,+integer,+compound,-compound)`` - ``one``


------------

.. index:: try_tool_call_3/7
.. _mcp_server_application/0::try_tool_call_3/7:

``try_tool_call_3/7``
^^^^^^^^^^^^^^^^^^^^^

Tries ``tool_call/3``. Falls back to auto-dispatch on failure.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``try_tool_call_3(Application,ToolName,Functor,Arity,ArgPairs,ToolArguments,Result)``
| **Mode and number of proofs:**
|    ``try_tool_call_3(+object_identifier,+atom,+atom,+integer,+list,+compound,-compound)`` - ``one``


------------

.. index:: tool_input_schema/4
.. _mcp_server_application/0::tool_input_schema/4:

``tool_input_schema/4``
^^^^^^^^^^^^^^^^^^^^^^^

Derives a JSON Schema curly-term for tool input arguments from the application object's ``info/2`` and ``mode/2`` directives. Used by Streamable HTTP ``x-mcp-header`` / ``Mcp-Param-*`` validation when the application does not define ``input_schema/2``.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``tool_input_schema(Application,Functor,Arity,InputSchema)``
| **Mode and number of proofs:**
|    ``tool_input_schema(+object_identifier,+atom,+integer,-compound)`` - ``one``


------------

.. index:: tool_output_schema/4
.. _mcp_server_application/0::tool_output_schema/4:

``tool_output_schema/4``
^^^^^^^^^^^^^^^^^^^^^^^^

Derives a JSON Schema curly-term for tool output arguments from the application object's ``info/2`` and ``mode/2`` directives.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``tool_output_schema(Application,Functor,Arity,OutputSchema)``
| **Mode and number of proofs:**
|    ``tool_output_schema(+object_identifier,+atom,+integer,-compound)`` - ``one``


------------

.. index:: format_content_items/2
.. _mcp_server_application/0::format_content_items/2:

``format_content_items/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^

Converts canonical content item terms into MCP JSON content array elements.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``format_content_items(Items,Elements)``
| **Mode and number of proofs:**
|    ``format_content_items(+list,-list)`` - ``one``


------------

.. index:: format_prompt_messages/2
.. _mcp_server_application/0::format_prompt_messages/2:

``format_prompt_messages/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Converts message(Role, text(Text)) terms into MCP JSON prompt message objects.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``format_prompt_messages(Messages,JsonMessages)``
| **Mode and number of proofs:**
|    ``format_prompt_messages(+list,-list)`` - ``one``


------------

.. index:: format_resource_contents/2
.. _mcp_server_application/0::format_resource_contents/2:

``format_resource_contents/2``
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Converts text_content/3 and blob_content/3 terms into MCP JSON resource content objects.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``format_resource_contents(Contents,JsonContents)``
| **Mode and number of proofs:**
|    ``format_resource_contents(+list,-list)`` - ``one``


------------

.. index:: has_pair/3
.. _mcp_server_application/0::has_pair/3:

``has_pair/3``
^^^^^^^^^^^^^^

Looks up a Key-Value pair inside a curly-term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``has_pair(Curly,Key,Value)``
| **Mode and number of proofs:**
|    ``has_pair(+compound,+atom,?term)`` - ``zero_or_one``


------------

.. index:: curly_to_pairs/2
.. _mcp_server_application/0::curly_to_pairs/2:

``curly_to_pairs/2``
^^^^^^^^^^^^^^^^^^^^

Converts a curly-term to a list of Key-Value pairs.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``curly_to_pairs(Curly,Pairs)``
| **Mode and number of proofs:**
|    ``curly_to_pairs(+compound,-list)`` - ``one``


------------

.. index:: pairs_to_curly/2
.. _mcp_server_application/0::pairs_to_curly/2:

``pairs_to_curly/2``
^^^^^^^^^^^^^^^^^^^^

Converts a list of Key-Value pairs to a curly-term.

| **Compilation flags:**
|    ``static``

| **Template:**
|    ``pairs_to_curly(Pairs,Curly)``
| **Mode and number of proofs:**
|    ``pairs_to_curly(+list,-compound)`` - ``one``


------------

Private predicates
------------------

(no local declarations; see entity ancestors if any)

Operators
---------

(none)

