Class McpEndpoint.Builder

java.lang.Object
com.soklet.McpEndpoint.Builder
Enclosing class:
McpEndpoint
@NotThreadSafe public static final class McpEndpoint.Builder extends Object
Builder for immutable McpEndpoint registrations.

This class is intended for use by a single thread.

Author:
Mark Allen

  • Method Details

    • taskProtocolVersions

      public @NonNull McpEndpoint.Builder taskProtocolVersions(@NonNull Set<@NonNull McpProtocolVersion> protocolVersions)
      Enables Tasks for an explicit subset of endpoint revisions. An empty set disables Tasks. The task manager remains a server dependency.
      Parameters:
      protocolVersions - exact task-enabled revisions
      Returns:
      this builder

    • sessionProtocolVersions

      public @NonNull McpEndpoint.Builder sessionProtocolVersions(@NonNull Set<@NonNull McpProtocolVersion> protocolVersions)
      Enables sessions for an explicit subset of served endpoint revisions. Only 2025-06-18 and 2025-11-25 are eligible; an empty set disables sessions. 2026-07-28 does not use sessions. The server must configure McpSessionConfig. A session-enabled revision requires a session ID after initialization; it never silently falls back to stateless operation. The supplied set is copied.
      Parameters:
      protocolVersions - exact session-enabled revisions
      Returns:
      this builder
      Throws:
      NullPointerException - if the set or an item is null

    • subscriptionProtocolVersions

      public @NonNull McpEndpoint.Builder subscriptionProtocolVersions(@NonNull Set<@NonNull McpProtocolVersion> protocolVersions)
      Enables subscriptions for an explicit subset of endpoint revisions. Modern 2026-07-28 uses subscriptions/listen; the two supported 2025 revisions require matching session revisions, server HTTP admission and effective event sources for GET delivery. An empty set disables subscriptions. URI updates require an explicit URI authorizer; legacy catalog-only delivery does not.
      Parameters:
      protocolVersions - exact subscription-enabled revisions
      Returns:
      this builder

    • serverInfo

      public @NonNull McpEndpoint.Builder serverInfo(@NonNull McpImplementation implementation)
      Sets the required implementation information advertised by this endpoint.
      Parameters:
      implementation - the server implementation information
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the server name or version is blank

    • serverInfoIncluded

      public @NonNull McpEndpoint.Builder serverInfoIncluded(@Nullable Boolean serverInfoIncluded)
      Controls whether Soklet includes the configured server implementation at _meta["io.modelcontextprotocol/serverInfo"] in MCP results. The default is true.
      Parameters:
      serverInfoIncluded - whether MCP result metadata includes server information, or null to restore the default
      Returns:
      this builder

    • instructions

      public @NonNull McpEndpoint.Builder instructions(@Nullable String instructions)
      Sets nonblank human-readable instructions for clients using this endpoint.
      Parameters:
      instructions - the endpoint instructions, or null to clear them
      Returns:
      this builder
      Throws:
      IllegalArgumentException - if the instructions are blank

    • toolRegistrations

      public @NonNull McpEndpoint.Builder toolRegistrations(@Nullable List<@NonNull McpToolRegistration<?>> toolRegistrations)
      Replaces tool registrations in supplied order. Null or empty clears the property. The complete list is validated and snapshotted before replacing the prior value.
      Parameters:
      toolRegistrations - tool registrations, or null to clear
      Returns:
      this builder
      Throws:
      NullPointerException - if a list element is null

    • promptRegistrations

      public @NonNull McpEndpoint.Builder promptRegistrations(@Nullable List<@NonNull McpPromptRegistration> promptRegistrations)
      Replaces prompt registrations in supplied order. Null or empty clears the property. The complete list is validated and snapshotted before replacing the prior value.
      Parameters:
      promptRegistrations - prompt registrations, or null to clear
      Returns:
      this builder
      Throws:
      NullPointerException - if a list element is null

    • resourceRegistrations

      public @NonNull McpEndpoint.Builder resourceRegistrations(@Nullable List<@NonNull McpResourceRegistration> resourceRegistrations)
      Replaces resource registrations in supplied order. Null or empty clears the property. The complete list is validated and snapshotted before replacing the prior value.
      Parameters:
      resourceRegistrations - resource registrations, or null to clear
      Returns:
      this builder
      Throws:
      NullPointerException - if a list element is null

    • skillRegistrations

      public @NonNull McpEndpoint.Builder skillRegistrations(@Nullable List<@NonNull McpSkillRegistration> skillRegistrations)
      Replaces standalone Skills registrations in supplied order. Null or empty clears this property without changing groups. The complete list is snapshotted before replacing the prior value. Endpoint construction checks duplicate identities, listing names, shared files and resource collisions across both sources, independent of setter order.
      Parameters:
      skillRegistrations - standalone Skills registrations, or null to clear
      Returns:
      this builder
      Throws:
      NullPointerException - if a list element is null

    • skillGroups

      public @NonNull McpEndpoint.Builder skillGroups(@Nullable List<@NonNull McpSkillGroup> skillGroups)
      Replaces explicit Skills locale groups in supplied order. Null or empty clears this property without changing standalone registrations. The complete list is snapshotted before replacing the prior value. Empty groups are permitted but contribute no listing name or file owner.
      Parameters:
      skillGroups - Skills groups, or null to clear
      Returns:
      this builder
      Throws:
      NullPointerException - if a list element is null

    • skillListHandler

      public @NonNull McpEndpoint.Builder skillListHandler(@Nullable McpSkillListHandler skillListHandler, @NonNull Set<@NonNull McpProtocolVersion> protocolVersions)
      Installs the application-owned skills/list page handler. Each invocation replaces the prior handler. Null restores bounded automatic single-page listing. The handler owns authenticated cursors and snapshot restoration, while Soklet validates page membership and current access without changing canonical file-read handling.
      Parameters:
      skillListHandler - custom Skills-list handler, or null for automatic listing
      protocolVersions - nonempty handler revisions, or empty when clearing
      Returns:
      this builder

    • skillListCachePolicy

      public @NonNull McpEndpoint.Builder skillListCachePolicy(@Nullable McpCachePolicy skillListCachePolicy)
      Sets fixed cache scope and default freshness for skills/list. The default is private scope with zero time to live. Page overrides affect only freshness and remain subject to localization and security clamps.
      Parameters:
      skillListCachePolicy - Skills-list cache policy, or null to restore the default
      Returns:
      this builder

    • resourceListHandler

      public @NonNull McpEndpoint.Builder resourceListHandler(@Nullable McpResourceListHandler resourceListHandler, @NonNull Set<@NonNull McpProtocolVersion> protocolVersions)
      Installs the custom resources/list handler.

      A custom handler is authoritative for every returned page; exact resource registrations are not merged automatically. Every descriptor with an exact uri must identify either an exact-URI resource registration or a matching URI-template registration on this endpoint. Soklet validates the complete page after the handler returns; a violation rejects the request with JSON-RPC error -32603 and HTTP status 200 on 2026-07-28 (the 2025 profiles also retain in-band operation errors). Null selects the static fallback: a single page on 2026-07-28, or bounded framework pages on 2025-06-18 and 2025-11-25. Sequential calls are last-call-wins.

      Parameters:
      resourceListHandler - custom list handler, or null for the static fallback
      protocolVersions - nonempty handler revisions, or empty when clearing
      Returns:
      this builder

    • resourceListCachePolicy

      public @NonNull McpEndpoint.Builder resourceListCachePolicy(@Nullable McpCachePolicy resourceListCachePolicy)
      Sets the fixed scope and default time to live for every resources/list page. The default is private scope with a zero time to live.
      Parameters:
      resourceListCachePolicy - resources-list cache policy, or null to restore the default
      Returns:
      this builder

    • resourceTemplateListCachePolicy

      public @NonNull McpEndpoint.Builder resourceTemplateListCachePolicy(@Nullable McpCachePolicy resourceTemplateListCachePolicy)
      Sets the fixed scope and default time to live for resources/templates/list. The default is private scope with a zero time to live.
      Parameters:
      resourceTemplateListCachePolicy - resource-template-list cache policy, or null to restore the default
      Returns:
      this builder

    • toolRateLimiterName

      public @NonNull McpEndpoint.Builder toolRateLimiterName(@Nullable String toolRateLimiterName)
      Sets a named tool-limiter override.

      Sequential named and direct setter calls are last-call-wins. This call clears any direct limiter previously configured on this builder.

      Parameters:
      toolRateLimiterName - nonblank name in the server limiter registry, or null to clear the endpoint override
      Returns:
      this builder

    • toolRateLimiter

      public @NonNull McpEndpoint.Builder toolRateLimiter(@Nullable McpRateLimiter toolRateLimiter)
      Sets a direct tool-limiter override.

      Sequential named and direct setter calls are last-call-wins. This call clears any limiter name previously configured on this builder.

      Parameters:
      toolRateLimiter - direct tool limiter, or null to clear the endpoint override
      Returns:
      this builder

    • subscriptionConfig

      public @NonNull McpEndpoint.Builder subscriptionConfig(@Nullable McpSubscriptionConfig subscriptionConfig)
      Sets the endpoint's subscription-change configuration.

      Sequential calls are last-call-wins. The immutable configuration and its application-owned publisher are retained by reference.

      Parameters:
      subscriptionConfig - subscription-change configuration, or null to disable subscriptions
      Returns:
      this builder

    • build

      public @NonNull McpEndpoint build()
      Builds an immutable endpoint.

      No tool, prompt, or resource operation is required. Tool and prompt names must each be unique within the endpoint, as must exact resource URIs and resource URI templates.

      Every Apps tool resource association must identify an exact registration on this endpoint whose declared MIME type is the Apps HTML profile. Templates and custom resource-list descriptors do not establish this eligibility. Validation does not invoke application handlers or fetch resource contents.

      Skills names occupy distinct standalone/group listing slots. Registered descendants must be completely present in every enclosing bundle. Shared files must have identical bytes and representation, have at most 16 owners, and cannot overlap ordinary exact-resource or URI-template routes. Individual Skills responses include endpoint metadata in their output preflight. Without a custom Skills-list handler, the complete unfiltered automatic page must fit the output profile and contain at most 32 slots.

      Returns:
      the endpoint
      Throws:
      IllegalStateException - if a tool name, prompt name, exact resource URI, or resource URI template is duplicated, an Apps association has no eligible resource, or Skills configuration conflicts or is incomplete
      IllegalArgumentException - if a Skills response cannot fit the output profile, or the automatic page requires a custom skillListHandler(...)