.. index:: single: mcp_resource_protocol
.. _mcp_resource_protocol/0:

.. rst-class:: right

**protocol**

``mcp_resource_protocol``
=========================

Protocol for Logtalk objects that provide resources to be exposed via an MCP (Model Context Protocol) server. Implementing objects must define the set of resources available and handle resource read requests. Applications may also expose parameterized resources using URI templates. Resources expose data and content from the application that MCP clients can access. Used by both the 2025-06-18 and 2026-07-28 adapters.

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

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

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


| **Dependencies:**
|   (none)


| **Remarks:**

   - Capabilities: Objects providing resources must declare ``resources`` in their ``capabilities/1`` predicate (from the ``mcp_tool_protocol`` protocol). The server will then advertise the ``resources`` capability and handle ``resources/list``, ``resources/templates/list``, and ``resources/read`` requests.
   - Resource descriptors: Each resource is described by a ``resource(URI, Name, Description, MimeType)`` or ``resource(URI, Name, Title, Description, MimeType)`` term where ``URI`` is the resource identifier (an atom), ``Name`` is a human-readable name (an atom), ``Title`` is an optional human-friendly display name (an atom), ``Description`` is a human-readable description (an atom), and ``MimeType`` is the MIME type of the resource content (an atom, e.g. ``'text/plain'``).
   - Resource template descriptors: Parameterized resources are optionally described by ``resource_template(URITemplate, Name, Description, MimeType)`` or ``resource_template(URITemplate, Name, Title, Description, MimeType)`` terms. ``URITemplate`` is an RFC 6570 URI template atom. Template listing is validated as a whole: an invalid template raises a ``domain_error(uri_template, URITemplate)`` error and no partial list is advertised. The server advertises valid templates without expanding them; applications validate, authorize, and read concrete expanded URIs using ``resource_read/3``.
   - Resource contents: The ``resource_read/3`` predicate must return a result term. The result must be ``contents(ContentList)`` where each item is ``text_content(URI, MimeType, Text)`` for text resources or ``blob_content(URI, MimeType, Base64Data)`` for binary resources encoded as base64.
   - Multi-round (2026-07-28): For the 2026-07-28 adapter, applications that need additional input during a resource read implement ``resource_read_round/4`` from the ``mcp_multiround_protocol``. Existing ``resource_read/3`` remains valid and is wrapped as a ``complete`` result when the round hook is absent.
   - Caching (2026-07-28): Complete ``resources/read`` results may include cache fields (``ttlMs``, ``cacheScope``) derived from ``mcp_cache_protocol`` or server options. Cache fields are never attached to ``input_required`` results.

| **Inherited public predicates:**
|    (none)

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

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

.. index:: resources/1
.. _mcp_resource_protocol/0::resources/1:

``resources/1``
^^^^^^^^^^^^^^^

Returns a list of resource descriptors available from this object. Each descriptor is a compound term ``resource(URI, Name, Description, MimeType)`` or ``resource(URI, Name, Title, Description, MimeType)`` where ``URI`` is the resource identifier (an atom, typically a URI like ``logtalk://my-app/data``), ``Name`` is a human-readable name (an atom), ``Title`` is an optional human-friendly display name (an atom), ``Description`` is a human-readable description (an atom), and ``MimeType`` is the MIME type (an atom, e.g. ``'text/plain'``, ``'application/json'``).

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

| **Template:**
|    ``resources(Resources)``
| **Mode and number of proofs:**
|    ``resources(-list(compound))`` - ``one``


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

.. index:: resource_templates/1
.. _mcp_resource_protocol/0::resource_templates/1:

``resource_templates/1``
^^^^^^^^^^^^^^^^^^^^^^^^

Optional. Returns a list of parameterized resource descriptors. Each descriptor is a ``resource_template(URITemplate, Name, Description, MimeType)`` or ``resource_template(URITemplate, Name, Title, Description, MimeType)`` term. ``URITemplate`` is an RFC 6570 URI template atom. Concrete expanded URIs are handled by ``resource_read/3``.

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

| **Template:**
|    ``resource_templates(ResourceTemplates)``
| **Mode and number of proofs:**
|    ``resource_templates(-list(compound))`` - ``zero_or_one``


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

.. index:: resource_read/3
.. _mcp_resource_protocol/0::resource_read/3:

``resource_read/3``
^^^^^^^^^^^^^^^^^^^

Handles a resource read request. ``URI`` is the resource identifier (as declared in ``resources/1``), ``Arguments`` is a list of ``ArgumentName-Value`` pairs (currently unused but reserved for future use), and ``Result`` is unified with the resource result. The result must be ``contents(ContentList)`` where each content item is either ``text_content(URI, MimeType, Text)`` for text resources or ``blob_content(URI, MimeType, Base64Data)`` for binary resources encoded as base64. ``Text`` and ``Base64Data`` must be atoms.

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

| **Template:**
|    ``resource_read(URI,Arguments,Result)``
| **Mode and number of proofs:**
|    ``resource_read(+atom,+list(pair),--compound)`` - ``one``


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

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

(none)

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

(none)

Operators
---------

(none)

