Class McpResourceRegistration

java.lang.Object

com.soklet.McpResourceRegistration

@ThreadSafe
public final class McpResourceRegistration
extends Object

Immutable programmatic registration for one MCP resource-read route.

Registration is staged so a handler must be supplied before optional descriptor metadata can be configured. Exact and template registrations intentionally expose different builders: only an exact resource may advertise a size. The registration cache policy owns the fixed scope and default time to live for reads; the default is McpCachePolicy.privateNoCacheInstance().

Registration validates address structure and routing, not deployment safety. The application owns an allowlist based on how each URI is delivered or dereferenced. Direct-client addresses and handler-only custom addresses commonly require different scheme, authority, credential, query, and fragment rules. A filesystem-backed handler additionally owns canonical root containment, symlink policy, authorization, and safe opening; Soklet does not map registered URIs to files.

Author:

Mark Allen

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static final class	McpResourceRegistration.ExactBuilder	Mutable builder for an immutable exact-resource registration.
static final class	McpResourceRegistration.ExactHandlerStage	Required-handler stage for an exact resource.
static final class	McpResourceRegistration.TemplateBuilder	Mutable builder for an immutable URI-template resource registration.
static final class	McpResourceRegistration.TemplateHandlerStage	Required-handler stage for a URI-template resource.

Method Summary

Modifier and Type	Method	Description
@NonNull McpResourceAddressType	getAddressType()
@NonNull Optional<@NonNull McpContentAnnotations>	getAnnotations()
@NonNull McpCachePolicy	getCachePolicy()
@NonNull Optional<@NonNull McpCompletionHandler>	getCompletionHandler()	Returns the template's argument completer, when configured.
@NonNull Set<@NonNull McpProtocolVersion>	getCompletionProtocolVersions()
@NonNull Optional<@NonNull String>	getDescription()
@NonNull McpResourceReadHandler	getHandler()
@NonNull List<@NonNull McpIcon>	getIcons()
@NonNull List<@NonNull McpInputRequestDeclaration>	getInputRequestDeclarations()	Returns the input requests this resource-read operation may emit.
@NonNull McpJsonObject	getMetadata()
@NonNull Optional<@NonNull String>	getMimeType()
@NonNull String	getName()
@NonNull Set<@NonNull McpProtocolVersion>	getProtocolVersions()
@NonNull McpRequestStateMode	getRequestStateMode()	Returns the request-state contract for this resource-read operation.
@NonNull Optional<@NonNull Long>	getSizeInBytes()	Returns the exact resource's advertised size.
@NonNull Optional<@NonNull String>	getTitle()
@NonNull Optional<@NonNull URI>	getUri()
@NonNull Optional<@NonNull String>	getUriTemplate()
static @NonNull McpResourceRegistration.ExactHandlerStage	withUriAndName(@NonNull URI uri, @NonNull String name, @NonNull Set<@NonNull McpProtocolVersion> protocolVersions)	Begins a staged exact-resource registration.
static @NonNull McpResourceRegistration.TemplateHandlerStage	withUriTemplateAndName(@NonNull String uriTemplate, @NonNull String name, @NonNull Set<@NonNull McpProtocolVersion> protocolVersions)	Begins a staged URI-template resource registration.

Methods inherited from class Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Details

withUriAndName

public static @NonNull McpResourceRegistration.ExactHandlerStage withUriAndName(@NonNull URI uri,
 @NonNull String name,
 @NonNull Set<@NonNull McpProtocolVersion> protocolVersions)

Begins a staged exact-resource registration.

Acceptance here does not mean that the URI is safe for direct client loading or for application-side dereference. Apply a deployment policy for the address's intended delivery path.

This method validates the URI's shape. Construction of the enclosing McpServer later applies the 1,048,576-byte ASCII wire limit and complete endpoint route validation. IPv6 zone identifiers are excluded from the RFC 3986 URI contract.

Parameters:

uri - absolute normalized resource URI in ASCII wire form

name - nonblank resource name

protocolVersions - nonempty exact revisions serving this resource

Returns:

required-handler stage

Throws:

IllegalArgumentException - if the URI is relative, not normalized, not in ASCII wire form, contains an IPv6 zone identifier, or the name is blank

withUriTemplateAndName

public static @NonNull McpResourceRegistration.TemplateHandlerStage withUriTemplateAndName(@NonNull String uriTemplate,
 @NonNull String name,
 @NonNull Set<@NonNull McpProtocolVersion> protocolVersions)

Begins a staged URI-template resource registration.

This method performs inexpensive local validation. Construction of the enclosing McpServer performs complete RFC 6570 Level 1 parsing and route validation, including the template-size, variable-name, variable-count, and overlap-work limits documented in the MCP guide. It also enforces the limit of 256 URI templates per endpoint at server construction. IPv6 zone identifiers are excluded from the RFC 3986 URI contract, including identifiers containing template variables.

Level 1 simple variables do not consume a raw slash. For example, file:///{path} matches file:///src%2Fmain.rs with variable value src/main.rs, but does not match file:///src/main.rs. Captured values are UTF-8 percent-decoded exactly once; %252F becomes the literal string %2F. Reserved expansion ({+path}), explode and prefix modifiers are unsupported.

Neither validation step authorizes expanded URIs or establishes that their scheme is safe for the application's delivery intent.

Parameters:

uriTemplate - nonblank URI template containing simple {variable} expressions

name - nonblank resource name

protocolVersions - nonempty exact revisions serving this resource

Returns:

required-handler stage

Throws:

IllegalArgumentException - if the template fails local structural validation or the name is blank

getAddressType

public @NonNull McpResourceAddressType getAddressType()

Returns:

whether this registration uses an exact URI or URI template

getUri

public @NonNull Optional<@NonNull URI> getUri()

Returns:

exact resource URI, or empty for a template registration

getUriTemplate

public @NonNull Optional<@NonNull String> getUriTemplate()

Returns:

resource URI template, or empty for an exact registration

getName

public @NonNull String getName()

Returns:

nonblank resource name

getProtocolVersions

public @NonNull Set<@NonNull McpProtocolVersion> getProtocolVersions()

Returns:

exact protocol revisions on which this resource is available

getTitle

public @NonNull Optional<@NonNull String> getTitle()

Returns:

human-readable title, if configured

getDescription

public @NonNull Optional<@NonNull String> getDescription()

Returns:

human-readable description, if configured

getMimeType

public @NonNull Optional<@NonNull String> getMimeType()

Returns:

resource MIME type, if configured

getIcons

public @NonNull List<@NonNull McpIcon> getIcons()

Returns:

immutable icon list in insertion order

getAnnotations

public @NonNull Optional<@NonNull McpContentAnnotations> getAnnotations()

Returns:

content annotations, if configured

getSizeInBytes

public @NonNull Optional<@NonNull Long> getSizeInBytes()

Returns the exact resource's advertised size.

Returns:

nonnegative byte count, or empty when omitted or templated

getCachePolicy

public @NonNull McpCachePolicy getCachePolicy()

Returns:

fixed scope and default time to live for resource reads

getInputRequestDeclarations

public @NonNull List<@NonNull McpInputRequestDeclaration> getInputRequestDeclarations()

Returns the input requests this resource-read operation may emit.

Returns:

immutable declarations in registration order

getRequestStateMode

public @NonNull McpRequestStateMode getRequestStateMode()

Returns the request-state contract for this resource-read operation.

Returns:

request-state mode

getMetadata

public @NonNull McpJsonObject getMetadata()

Returns:

immutable protocol extension metadata

getHandler

public @NonNull McpResourceReadHandler getHandler()

Returns:

resource-read handler

getCompletionHandler

public @NonNull Optional<@NonNull McpCompletionHandler> getCompletionHandler()

Returns the template's argument completer, when configured.

Returns:

configured completer, or empty for exact resources and templates without one

getCompletionProtocolVersions

public @NonNull Set<@NonNull McpProtocolVersion> getCompletionProtocolVersions()

Returns:

exact revisions on which the completion handler is available