Trait ResourceHandler 

pub trait ResourceHandler: Send + Sync {
    // Required methods
    fn definition(&self) -> Resource;
    fn read(&self, ctx: &McpContext) -> McpResult<Vec<ResourceContent>>;

    // Provided methods
    fn final_client_direct_https(&self) -> bool { ... }
    fn declares_final_mrtr(&self) -> bool { ... }
    fn template(&self) -> Option<ResourceTemplate> { ... }
    fn on_subscribe(&self, _ctx: &McpContext, _uri: &str) -> McpResult<()> { ... }
    fn on_unsubscribe(&self, _ctx: &McpContext, _uri: &str) -> McpResult<()> { ... }
    fn final_definition(&self) -> Option<FinalResource> { ... }
    fn final_template_definition(&self) -> Option<FinalResourceTemplate> { ... }
    fn final_title(&self) -> Option<&str> { ... }
    fn final_icons(&self) -> Option<&[RawIcon]> { ... }
    fn final_annotations(&self) -> Option<&Annotations> { ... }
    fn final_metadata(&self) -> Option<&OpenMetadata> { ... }
    fn final_template_title(&self) -> Option<&str> { ... }
    fn final_template_icons(&self) -> Option<&[RawIcon]> { ... }
    fn final_template_annotations(&self) -> Option<&Annotations> { ... }
    fn final_template_metadata(&self) -> Option<&OpenMetadata> { ... }
    fn icon(&self) -> Option<&Icon> { ... }
    fn version(&self) -> Option<&str> { ... }
    fn tags(&self) -> &[String] { ... }
    fn timeout(&self) -> Option<Duration> { ... }
    fn read_with_uri(
        &self,
        ctx: &McpContext,
        _uri: &str,
        _params: &HashMap<String, String>,
    ) -> McpResult<Vec<ResourceContent>> { ... }
    fn read_async_with_uri<'a>(
        &'a self,
        ctx: &'a McpContext,
        uri: &'a str,
        params: &'a HashMap<String, String>,
    ) -> BoxFuture<'a, McpOutcome<Vec<ResourceContent>>> { ... }
    fn read_async<'a>(
        &'a self,
        ctx: &'a McpContext,
    ) -> BoxFuture<'a, McpOutcome<Vec<ResourceContent>>> { ... }
    fn read_final(
        &self,
        ctx: &McpContext,
    ) -> McpResult<CompleteResult<FinalReadResourceResult>> { ... }
    fn final_resource_read_cache_hint_provenance(
        &self,
    ) -> FinalResourceReadCacheHintProvenance { ... }
    fn read_final_with_uri(
        &self,
        ctx: &McpContext,
        uri: &str,
        params: &HashMap<String, String>,
    ) -> McpResult<CompleteResult<FinalReadResourceResult>> { ... }
    fn read_final_outcome(
        &self,
        ctx: &McpContext,
    ) -> McpResult<FinalMethodOutcome<FinalReadResourceResult>> { ... }
    fn read_final_outcome_with_uri(
        &self,
        ctx: &McpContext,
        uri: &str,
        params: &HashMap<String, String>,
    ) -> McpResult<FinalMethodOutcome<FinalReadResourceResult>> { ... }
    fn read_final_async<'a>(
        &'a self,
        ctx: &'a McpContext,
    ) -> BoxFuture<'a, McpOutcome<CompleteResult<FinalReadResourceResult>>> { ... }
    fn read_final_async_with_uri<'a>(
        &'a self,
        ctx: &'a McpContext,
        uri: &'a str,
        params: &'a HashMap<String, String>,
    ) -> BoxFuture<'a, McpOutcome<CompleteResult<FinalReadResourceResult>>> { ... }
    fn read_final_outcome_async<'a>(
        &'a self,
        ctx: &'a McpContext,
    ) -> BoxFuture<'a, McpOutcome<FinalMethodOutcome<FinalReadResourceResult>>> { ... }
    fn read_final_outcome_async_with_uri<'a>(
        &'a self,
        ctx: &'a McpContext,
        uri: &'a str,
        params: &'a HashMap<String, String>,
    ) -> BoxFuture<'a, McpOutcome<FinalMethodOutcome<FinalReadResourceResult>>> { ... }
    fn read_async_with_uri_in_request<'a>(
        &'a self,
        ctx: &'a McpContext,
        _request_cx: &'a Cx,
        uri: &'a str,
        params: &'a HashMap<String, String>,
    ) -> BoxFuture<'a, McpOutcome<Vec<ResourceContent>>> { ... }
    fn read_final_async_with_uri_in_request<'a>(
        &'a self,
        ctx: &'a McpContext,
        _request_cx: &'a Cx,
        uri: &'a str,
        params: &'a HashMap<String, String>,
    ) -> BoxFuture<'a, McpOutcome<CompleteResult<FinalReadResourceResult>>> { ... }
    fn read_final_outcome_async_with_uri_in_request<'a>(
        &'a self,
        ctx: &'a McpContext,
        _request_cx: &'a Cx,
        uri: &'a str,
        params: &'a HashMap<String, String>,
    ) -> BoxFuture<'a, McpOutcome<FinalMethodOutcome<FinalReadResourceResult>>> { ... }
    fn read_final_outcome_async_with_uri_resuming_in_request<'a>(
        &'a self,
        ctx: &'a McpContext,
        request_cx: &'a Cx,
        uri: &'a str,
        params: &'a HashMap<String, String>,
        _resume_inputs: Option<&'a MrtrCompletedInputs>,
    ) -> BoxFuture<'a, McpOutcome<FinalMethodOutcome<FinalReadResourceResult>>> { ... }
}

Handler for a resource.

This trait is typically implemented via the #[resource] macro.

Sync vs Async

By default, implement read() for synchronous execution. For async resources, override read_async() instead. The router uses read_async_with_uri() so implementations can access matched URI parameters when needed; its default implementation delegates to read_async() or read_with_uri().

Return Type

Async handlers return McpOutcome<Vec<ResourceContent>>, a 4-valued type.

Required Methods

fn definition(&self) -> Resource

Returns the resource definition.

fn read(&self, ctx: &McpContext) -> McpResult<Vec<ResourceContent>>

Reads the resource content synchronously.

This is the default implementation point. Override this for simple synchronous resources. Returns McpResult which is converted to McpOutcome by the async wrapper.

Provided Methods

fn final_client_direct_https(&self) -> bool

Returns whether locally authored final resource identities may use HTTPS at client-direct use sites. Exact MCP 2024-11-05 dispatch never consults this declaration.

fn declares_final_mrtr(&self) -> bool

Declares whether this handler can use final MRTR continuations.

The router consults this immutable capability before invoking a final resource handler on a context that has no durable modern session partition.

fn template(&self) -> Option<ResourceTemplate>

Returns the resource template definition, if this resource uses a URI template.

fn on_subscribe(&self, _ctx: &McpContext, _uri: &str) -> McpResult<()>

Called after a session admits resources/subscribe for this URI.

Prefixed as_proxy handlers rewrite the inbound URI and subscribe the upstream so later notify_resource_updated is not silent.

fn on_unsubscribe(&self, _ctx: &McpContext, _uri: &str) -> McpResult<()>

Called after a session removes resources/subscribe for this URI.

fn final_definition(&self) -> Option<FinalResource>

Returns an exact final resource catalog definition, when this handler owns one. This bypasses lossy projection through Resource, retaining final-only fields such as size, full icons, annotations, and _meta.

fn final_template_definition(&self) -> Option<FinalResourceTemplate>

Returns an exact final resource-template catalog definition, when this handler owns a template. This keeps final metadata immutable at router registration rather than reconstructing it from the legacy template.

fn final_title(&self) -> Option<&str>

Returns the final display title for this concrete resource.

fn final_icons(&self) -> Option<&[RawIcon]>

Returns the final icon set for this concrete resource.

fn final_annotations(&self) -> Option<&Annotations>

Returns the final annotations for this concrete resource.

fn final_metadata(&self) -> Option<&OpenMetadata>

Returns final open metadata for this concrete resource.

fn final_template_title(&self) -> Option<&str>

Returns the final display title for this resource template.

This is used only when Self::template returns Some.

fn final_template_icons(&self) -> Option<&[RawIcon]>

Returns the final icon set for this resource template.

This is used only when Self::template returns Some.

fn final_template_annotations(&self) -> Option<&Annotations>

Returns the final annotations for this resource template.

This is used only when Self::template returns Some.

fn final_template_metadata(&self) -> Option<&OpenMetadata>

Returns final open metadata for this resource template.

This is used only when Self::template returns Some.

fn icon(&self) -> Option<&Icon>

Returns the resource’s icon, if any.

Default implementation returns None. Override to provide an icon. Note: Icons can also be set directly in definition().

fn version(&self) -> Option<&str>

Returns the resource’s version, if any.

Default implementation returns None. Override to provide a version. Note: Version can also be set directly in definition().

fn tags(&self) -> &[String]

Returns the resource’s tags for filtering and organization.

Default implementation returns an empty slice. Override to provide tags. Note: Tags can also be set directly in definition().

fn timeout(&self) -> Option<Duration>

Returns the resource’s custom timeout duration.

Default implementation returns None, meaning no additional handler ceiling is added. A non-zero value only tightens outer budgets; zero cannot disable an ambient, request, or server deadline. A blocking synchronous read() cannot be preempted; if it returns after the deadline, its result is rejected.

fn read_with_uri( &self, ctx: &McpContext, _uri: &str, _params: &HashMap<String, String>, ) -> McpResult<Vec<ResourceContent>>

Reads the resource content synchronously with the matched URI and parameters.

Default implementation ignores URI params and delegates to read().

fn read_async_with_uri<'a>( &'a self, ctx: &'a McpContext, uri: &'a str, params: &'a HashMap<String, String>, ) -> BoxFuture<'a, McpOutcome<Vec<ResourceContent>>>

Reads the resource content asynchronously with the matched URI and parameters.

Default implementation delegates to the sync read_with_uri() method.

fn read_async<'a>( &'a self, ctx: &'a McpContext, ) -> BoxFuture<'a, McpOutcome<Vec<ResourceContent>>>

Reads the resource content asynchronously.

Override this for resources that need true async execution (e.g., file I/O, database queries, remote fetches).

Returns McpOutcome to properly represent all four states.

The default implementation delegates to the sync read() method.

fn read_final( &self, ctx: &McpContext, ) -> McpResult<CompleteResult<FinalReadResourceResult>>

Reads the resource through the final MCP 2026-07-28 result surface.

Legacy-only handlers retain their exact Self::read behavior and receive the standard private one-hour final cache policy. Handlers that author final embedded-resource metadata or a different cache policy should override this method (or its async counterpart).

fn final_resource_read_cache_hint_provenance( &self, ) -> FinalResourceReadCacheHintProvenance

Returns the provenance of complete final resource-read cache hints.

The default is the legacy bridge, whose fixed wire values are only a temporary projection until the router applies its configured policy. Handlers that override Self::read_final to author a final result, including exact proxies, must return FinalResourceReadCacheHintProvenance::Explicit.

fn read_final_with_uri( &self, ctx: &McpContext, uri: &str, params: &HashMap<String, String>, ) -> McpResult<CompleteResult<FinalReadResourceResult>>

Reads the resource through the final result surface with URI parameters.

fn read_final_outcome( &self, ctx: &McpContext, ) -> McpResult<FinalMethodOutcome<FinalReadResourceResult>>

Reads the resource through the complete-or-input-required final algebra.

The default preserves the exact legacy projection by promoting Self::read_final into the complete branch. A final-only handler may override this method to return input_required without coercing that state into a legacy resource result.

fn read_final_outcome_with_uri( &self, ctx: &McpContext, uri: &str, params: &HashMap<String, String>, ) -> McpResult<FinalMethodOutcome<FinalReadResourceResult>>

Reads the resource through the complete-or-input-required final algebra with URI parameters.

fn read_final_async<'a>( &'a self, ctx: &'a McpContext, ) -> BoxFuture<'a, McpOutcome<CompleteResult<FinalReadResourceResult>>>

Asynchronously reads the resource through the final result surface.

fn read_final_async_with_uri<'a>( &'a self, ctx: &'a McpContext, uri: &'a str, params: &'a HashMap<String, String>, ) -> BoxFuture<'a, McpOutcome<CompleteResult<FinalReadResourceResult>>>

Asynchronously reads the resource through the final result surface with URI parameters.

fn read_final_outcome_async<'a>( &'a self, ctx: &'a McpContext, ) -> BoxFuture<'a, McpOutcome<FinalMethodOutcome<FinalReadResourceResult>>>

Asynchronously reads the resource through the complete-or-input-required final algebra.

fn read_final_outcome_async_with_uri<'a>( &'a self, ctx: &'a McpContext, uri: &'a str, params: &'a HashMap<String, String>, ) -> BoxFuture<'a, McpOutcome<FinalMethodOutcome<FinalReadResourceResult>>>

Asynchronously reads the resource through the complete-or-input-required final algebra with URI parameters.

fn read_async_with_uri_in_request<'a>( &'a self, ctx: &'a McpContext, _request_cx: &'a Cx, uri: &'a str, params: &'a HashMap<String, String>, ) -> BoxFuture<'a, McpOutcome<Vec<ResourceContent>>>

Reads the resource from a request-owned structured child.

Modern router dispatch supplies the child Cx that owns this read. Implementations with nested asynchronous work must retain this context rather than creating detached work. Existing handlers preserve their exact behavior through the default delegation.

fn read_final_async_with_uri_in_request<'a>( &'a self, ctx: &'a McpContext, _request_cx: &'a Cx, uri: &'a str, params: &'a HashMap<String, String>, ) -> BoxFuture<'a, McpOutcome<CompleteResult<FinalReadResourceResult>>>

Reads the resource’s final result from a request-owned structured child.

fn read_final_outcome_async_with_uri_in_request<'a>( &'a self, ctx: &'a McpContext, _request_cx: &'a Cx, uri: &'a str, params: &'a HashMap<String, String>, ) -> BoxFuture<'a, McpOutcome<FinalMethodOutcome<FinalReadResourceResult>>>

Reads the resource’s complete-or-input-required final outcome from a request-owned structured child.

fn read_final_outcome_async_with_uri_resuming_in_request<'a>( &'a self, ctx: &'a McpContext, request_cx: &'a Cx, uri: &'a str, params: &'a HashMap<String, String>, _resume_inputs: Option<&'a MrtrCompletedInputs>, ) -> BoxFuture<'a, McpOutcome<FinalMethodOutcome<FinalReadResourceResult>>>

Resumes a final resource read after framework-admitted MRTR input.

#[resource] maps an Option<&MrtrCompletedInputs> user-function parameter to this hook, keeping it out of URI-template parameters.

Dyn Compatibility

This trait is dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety".

Implementors

impl ResourceHandler for FilesystemResourceHandler