Package org.mcpjava.server.resources

Annotation Interface ResourceTemplate

@Target(METHOD) @Retention(RUNTIME) @Documented public @interface ResourceTemplate
Marks a method as providing dynamic MCP resources via URI templates.

Parameters

Resource template methods may have parameters of the following types:

  • String - the method must have one String parameter for each variable in the uriTemplate. In most cases these parameters must be annotated with ResourceTemplateArg with the name attribute set, unless the code was compiled with the -parameters option. ResourceTemplateArg also allows other properties of the argument to be configured.
  • McpRequest - to access information about the request
  • Cancellation - to allow processing to be stopped if the client cancels the tool call
  • Progress - to send progress reports back to the client
  • Implementations may define additional types that can be used as parameters

Return Type Handling

The result of a "resource read" operation is represented as a resource response. The annotated method can return various types that will be converted according to framework-specific rules:

  • String - Converted to text resource contents
  • byte[] - Converted to blob resource contents
  • ResourceContents implementations - Used directly in the response
  • List of ResourceContents - Multiple content items in the response
  • ResourceResponse - Used directly as the response
  • Other types - Encoded according to framework-specific rules (typically as JSON)

Resource templates use Level 1 RFC 6570 URI template syntax to support dynamic resources where parts of the URI are variable. Method parameters can be configured using ResourceTemplateArg annotations.

See Also:

  • Required Element Summary

    Required Elements
    Modifier and Type
    Required Element
    Description
    String
    uriTemplate
    The Level 1 URI template that can be used to construct resource URIs.

  • Optional Element Summary

    Optional Elements
    Modifier and Type
    Optional Element
    Description
    Resource.Annotations
    annotations
    Optional annotations for the client.
    String
    description
    A description of what this resource template represents.
    String
    mimeType
    The MIME type of this resource template.
    String
    name
    The unique name of the resource template.
    String
    title
    A human-readable title for the resource template.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final String
    ELEMENT_NAME
    Constant value for name() indicating that the annotated element's name should be used as-is.

  • Field Details

    • ELEMENT_NAME

      static final String ELEMENT_NAME
      Constant value for name() indicating that the annotated element's name should be used as-is.
      See Also:

  • Element Details

    • name

      String name
      The unique name of the resource template.

      Each resource template bound to the same MCP server configuration must have a unique name. This is intended for programmatic or logical use, but may be used for UI display as a fallback if title() is not present.

      By default, the name is derived from the annotated method name.

      Returns:
      the template name
      Default:
      "<<element name>>"

    • title

      String title
      A human-readable title for the resource template.

      This is a short, user-friendly display name for the template.

      Returns:
      the template title
      Default:
      ""

    • description

      String description
      A description of what this resource template represents.
      Returns:
      the template description
      Default:
      ""

    • uriTemplate

      String uriTemplate
      The Level 1 URI template that can be used to construct resource URIs.

      Examples:

      • "file:///{path}"
      • "db:///{database}/tables/{table}"
      • "api:///{version}/users/{userId}"
      Returns:
      the URI template
      See Also:

    • mimeType

      String mimeType
      The MIME type of this resource template.

      Examples: "text/plain", "application/json", "image/png"

      Returns:
      the MIME type
      Default:
      ""

    • annotations

      Resource.Annotations annotations
      Optional annotations for the client.

      These provide additional hints to clients about the resource template's metadata. Note that annotations must be declared explicitly to be included in resource metadata.

      Returns:
      the template annotations
      Default:
      @org.mcpjava.server.resources.Resource.Annotations