Interface McpInvocationFeatures

@ThreadSafe public interface McpInvocationFeatures
Immutable lookup for optional features associated with one MCP invocation. The lookup carrier is safe for concurrent access; feature values retain their own lifecycle, mutability, and thread-safety contracts. This type's ThreadSafe annotation does not make feature values thread-safe.

Features are registered and found by their exact public feature-interface class. Assignable supertypes and subtypes are not searched. Feature types are added without changing handler or context signatures.

Soklet supplies one CancelationToken for every selected MCP application handler. Its cancelation reason, when present, is one fixed StreamTerminationReason value; the framework-supplied MCP token does not expose an underlying throwable through CancelationToken.getCancelationCause(). Applications may record the fixed reason under their own logging policy, but should never substitute an untrusted free-form cause or use cancelation details as metric dimensions.

Author:
Mark Allen

  • Method Details

    • fromFeatures

      static @NonNull McpInvocationFeatures fromFeatures(@NonNull Map<@NonNull Class<?>, @NonNull Object> featuresByType)
      Creates an immutable feature lookup, primarily for application tests.

      The map and its entries are defensively copied. Each value must be an instance of its key and retains its own mutability and thread-safety contract.

      Parameters:
      featuresByType - exact feature-interface keys and matching values
      Returns:
      immutable feature lookup
      Throws:
      NullPointerException - if the map, a key, or a value is null
      IllegalArgumentException - if a value is not an instance of its key

    • find

      <T> @NonNull Optional<@NonNull T> find(@NonNull Class<@NonNull T> featureType)
      Finds a feature by its exact registered feature-interface class.

      An empty result means that the feature is unknown, does not apply to this operation, or is unavailable for this request. Repeated lookup of a present feature returns the same instance for the invocation's lifetime.

      Type Parameters:
      T - feature type
      Parameters:
      featureType - exact feature-interface class
      Returns:
      feature instance, if available
      Throws:
      NullPointerException - if featureType is null

    • getCancelationToken

      default @NonNull CancelationToken getCancelationToken()
      Returns the cooperative cancelation signal for this invocation.

      Soklet supplies this built-in feature for every selected MCP application handler. The returned value is the same instance exposed by require(CancelationToken.class).

      Returns:
      invocation cancelation token
      Throws:
      IllegalStateException - if an implementation does not supply the built-in cancelation token

    • getProgressReporter

      default @NonNull Optional<@NonNull McpProgressReporter> getProgressReporter()
      Returns the progress reporter available for this invocation.

      The reporter is present only when the initiating request supplied a valid progress token and Soklet can safely emit request-scoped progress. When present, the returned value is the same instance exposed by find(McpProgressReporter.class).

      Returns:
      invocation progress reporter, if available

    • getTaskCreationContext

      default @NonNull Optional<@NonNull McpTaskCreationContext> getTaskCreationContext()
      Returns the context for durably creating an MCP task from this invocation.

      The context is present only when the current operation supports task augmentation, a task manager is configured, the selected endpoint enables Tasks for this revision, and the client declared the MCP Tasks extension capability on this request. Presence does not mean that the client prefers or requires a task; the server remains the sole per-request decision maker. An absent task creation context requires inline completion. A handler or interceptor that nevertheless returns a task handle fails with the fixed JSON-RPC internal error. Statically task-required tools reject a missing client capability before application execution.

      Returns:
      invocation task creation context, if task creation is permitted

    • require

      default <T> @NonNull T require(@NonNull Class<@NonNull T> featureType)
      Requires a feature using the same exact-class lookup as find(Class).
      Type Parameters:
      T - feature type
      Parameters:
      featureType - exact feature-interface class
      Returns:
      feature instance
      Throws:
      NullPointerException - if featureType is null
      IllegalStateException - if the feature is unavailable