Package org.apache.juneau.rest.server.mcp.v20260728

Class McpOptions

java.lang.Object
org.apache.juneau.rest.server.mcp.v20260728.McpOptions
public class McpOptions extends Object
Binding-owned behavior configuration ("how" a 2026-07-28 MCP endpoint behaves) — the single v2-only aggregate consolidating every per-binding tunable McpEndpoint/McpRestServlet previously exposed as six separate hooks: capabilities, instructions, cache, mrtr, subscriptions, and subscriptionBroker.

Mutable during setup, effectively immutable once published. Same builder-less mutable-setup idiom as McpCacheConfig/McpMrtrConfig/McpSubscriptionsConfig and the neutral org.apache.juneau.rest.server.mcp.McpServerConfig it sits next to: configure fully via the single createMcpOptions() (servlet-subclass path) / getMcpOptions() (mixin path) override, then never mutate it afterward. The framework memoizes exactly one instance per binding (see McpRestServlet.getMcpOptions() and McpEndpoint.getMcpOptions()), so a request-time reader sees a stable, request-independent snapshot.

The three nested configs (cache, mrtr, subscriptions) are framework-owned instances created once, here, at construction time. Use the cache(Consumer)/mrtr(Consumer)/subscriptions(Consumer) configure-blocks to mutate them in place — callers never new a replacement nested config, so the "must return a stable instance" footgun the pre-consolidation hooks warned about cannot recur.

The subscription broker default:

getSubscriptionBroker() defaults to null, meaning "framework-derived": the binding lazily derives a BasicMcpSubscriptionBroker sized from getSubscriptions()'s queueSize the first time a broker is needed, and memoizes that one derived instance for the lifetime of the binding (a fresh broker per call would silently split live subscribers and publishers across unrelated registries). Call setSubscriptionBroker(McpSubscriptionBroker) to supply a custom broker instead (for example one shared across multiple bindings on purpose).

The idleTimeoutMs / heartbeatIntervalMs caveat:

When configuring subscriptions(Consumer), keep heartbeatIntervalMs below idleTimeoutMs (see that method's Javadoc) — otherwise the idle-timeout watchdog can reap a perfectly healthy connection between two heartbeats.

Example:
 McpOptions options = new McpOptions()
     .setInstructions("Use tool 'echo' to test.")
     .cache(c -> c.setToolsList(new McpCacheHint().setTtlMs(60_000)))
     .subscriptions(s -> s.setQueueSize(2048));

  • Constructor Details

  • Method Details

    • getCapabilities

      public ServerCapabilities getCapabilities()
      Optional explicit capabilities advertisement for server/discover.
      Returns:
      The explicit capabilities, or null to auto-derive from the registered tool / prompt / resource lists (the default).

    • setCapabilities

      public McpOptions setCapabilities(ServerCapabilities value)
      Sets the explicit server/discover capabilities advertisement.

      A non-null value bypasses auto-derivation entirely and advertises exactly what is supplied.

      Parameters:
      value - The new value. Can be null to auto-derive.
      Returns:
      This object (for method chaining).

    • getInstructions

      public String getInstructions()
      Optional free-form server/discover usage instructions advertised to clients.
      Returns:
      The instructions, or null to omit them from the discovery result (the default).

    • setInstructions

      public McpOptions setInstructions(String value)
      Sets the server/discover usage instructions.
      Parameters:
      value - The new value. Can be null to omit them.
      Returns:
      This object (for method chaining).

    • getCache

      public McpCacheConfig getCache()
      This binding's cache-hint configuration.
      Returns:
      The framework-owned cache configuration. Never null.

    • setCache

      public McpOptions setCache(McpCacheConfig value)
      Replaces this binding's cache configuration outright.
      Parameters:
      value - The new value. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null.

    • cache

      public McpOptions cache(Consumer<McpCacheConfig> consumer)
      Mutates this binding's cache configuration in place.

      Preferred over setCache(McpCacheConfig) for incremental configuration since it operates on the framework-owned instance rather than requiring the caller to construct a replacement.

      Parameters:
      consumer - Callback invoked with the framework-owned McpCacheConfig. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If consumer is null.

    • getMrtr

      public McpMrtrConfig getMrtr()
      This binding's MRTR (Multi-Round-Trip Request) configuration.
      Returns:
      The framework-owned MRTR configuration. Never null.

    • setMrtr

      public McpOptions setMrtr(McpMrtrConfig value)
      Replaces this binding's MRTR configuration outright.
      Parameters:
      value - The new value. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null.

    • mrtr

      public McpOptions mrtr(Consumer<McpMrtrConfig> consumer)
      Mutates this binding's MRTR configuration in place.
      Parameters:
      consumer - Callback invoked with the framework-owned McpMrtrConfig. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If consumer is null.

    • getResourceServer

      public McpResourceServerConfig getResourceServer()
      This binding's OAuth 2.1 resource-server (RS) configuration.
      Returns:
      The framework-owned RS configuration. Never null. Disabled by default.

    • setResourceServer

      public McpOptions setResourceServer(McpResourceServerConfig value)
      Replaces this binding's resource-server configuration outright.
      Parameters:
      value - The new value. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null.

    • resourceServer

      public McpOptions resourceServer(Consumer<McpResourceServerConfig> consumer)
      Mutates this binding's resource-server configuration in place.
      Parameters:
      consumer - Callback invoked with the framework-owned McpResourceServerConfig. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If consumer is null.

    • getSubscriptions

      public McpSubscriptionsConfig getSubscriptions()
      This binding's subscriptions/listen configuration.
      Returns:
      The framework-owned subscriptions configuration. Never null.

    • setSubscriptions

      public McpOptions setSubscriptions(McpSubscriptionsConfig value)
      Replaces this binding's subscriptions configuration outright.
      Parameters:
      value - The new value. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If value is null.

    • subscriptions

      public McpOptions subscriptions(Consumer<McpSubscriptionsConfig> consumer)
      Mutates this binding's subscriptions configuration in place.
      Parameters:
      consumer - Callback invoked with the framework-owned McpSubscriptionsConfig. Must not be null.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If consumer is null.

    • getSubscriptionBroker

      public McpSubscriptionBroker getSubscriptionBroker()
      The explicit subscription broker for this binding, if one was supplied.
      Returns:
      The explicit broker, or null if none was supplied (the default) — in which case the binding lazily derives and memoizes one (see resolveSubscriptionBroker()).

    • setSubscriptionBroker

      public McpOptions setSubscriptionBroker(McpSubscriptionBroker value)
      Sets an explicit subscription broker, bypassing the framework-derived default.

      Setting this after resolveSubscriptionBroker() has already derived and published a default broker for this instance does not retroactively clear or replace that already-published derived broker — resolveSubscriptionBroker() always prefers an explicit value set here over a previously-derived one, but under the never-mutate-after-setup contract this method should only be called during configuration, before the binding is handed to the framework.

      Parameters:
      value - The new value. Can be null to revert to the framework-derived default.
      Returns:
      This object (for method chaining).

    • resolveSubscriptionBroker

      public McpSubscriptionBroker resolveSubscriptionBroker()
      Returns getSubscriptionBroker() if explicitly set, otherwise lazily derives and memoizes a BasicMcpSubscriptionBroker sized from getSubscriptions()'s queue bound.

      This is the effective broker accessor: unlike getSubscriptionBroker() (which returns null by default), this method never returns null, deriving a default the first time one is needed. Internal plumbing for McpEndpoint.subscriptionBroker() / McpRestServlet.getSubscriptionBroker(). Since this McpOptions instance is itself memoized once per binding, the derived broker this method publishes is likewise stable for the binding's lifetime — publication uses double-checked locking (not a plain lazy read) because two BasicMcpSubscriptionBroker instances are not equivalent: each holds distinct live per-connection subscription state, so a benign publication race would silently split subscribers and publishers across two unrelated registries.

      Returns:
      The subscription broker to use. Never null.