Class McpEndpointRegistry

java.lang.Object
com.soklet.McpEndpointRegistry
@ThreadSafe public final class McpEndpointRegistry extends Object
An immutable registry of MCP endpoints and their handlers.

Registry methods preserve endpoint registration order. Every registry contains at least one endpoint, and no two endpoints may have the same normalized path.

Generated endpoints in a named application module require their endpoint package to be open or exported to Soklet. Packages containing non-public typed record arguments or results must be open to Soklet for runtime conversion.

Author:
Mark Allen

  • Method Details

    • getEndpoints

      public @NonNull List<@NonNull McpEndpoint> getEndpoints()
      The endpoints in deterministic registration order.
      Returns:
      an immutable endpoint list

    • withEndpoint

      public @NonNull McpEndpointRegistry withEndpoint(@NonNull McpEndpoint endpoint)
      Returns a registry containing the current endpoints followed by the given endpoint.
      Parameters:
      endpoint - the endpoint to append
      Returns:
      a new immutable registry
      Throws:
      IllegalArgumentException - if the endpoint path is already registered

    • withSubscriptionConfig

      public @NonNull McpEndpointRegistry withSubscriptionConfig(@NonNull Class<?> annotatedEndpointClass, @NonNull McpSubscriptionConfig subscriptionConfig)
      Returns a registry whose generated endpoint for the supplied annotated class carries the given subscription-change configuration.

      Soklet selects the already-generated endpoint by the exact loaded Class identity retained during generated-descriptor discovery. It does not initialize the endpoint class, acquire an endpoint instance, or rediscover handler metadata. Endpoint order and every other endpoint value are preserved.

      Parameters:
      annotatedEndpointClass - annotated endpoint class whose generated endpoint is selected
      subscriptionConfig - subscription-change configuration
      Returns:
      a new immutable registry
      Throws:
      IllegalArgumentException - if this registry did not load a generated endpoint for the exact supplied class
      NullPointerException - if either argument is null

    • withSkillRegistrations

      public @NonNull McpEndpointRegistry withSkillRegistrations(@NonNull Class<?> annotatedEndpointClass, @NonNull List<@NonNull McpSkillRegistration> skillRegistrations)
      Returns a registry whose generated endpoint for the supplied annotated class carries the given standalone Skills registrations.

      The list is snapshotted and replaces the complete standalone registration list; an empty list clears it. Existing Skills groups remain unchanged. Skills identities, ordinary-resource collisions, and output limits are validated against the copied endpoint before the new registry is returned. A failed replacement leaves this registry unchanged.

      Soklet selects the already-generated endpoint by the exact loaded Class identity retained during generated-descriptor discovery. It does not initialize the endpoint class, acquire an endpoint instance, or rediscover handler metadata. Endpoint order, generated handlers, and every other endpoint value are preserved.

      Parameters:
      annotatedEndpointClass - annotated endpoint class whose generated endpoint is selected
      skillRegistrations - complete standalone Skills registration list
      Returns:
      a new immutable registry
      Throws:
      IllegalArgumentException - if this registry did not load a generated endpoint for the exact supplied class, or the resulting Skills output exceeds its limits
      IllegalStateException - if Skills identities or files conflict, or an ordinary resource overlaps a Skills file
      NullPointerException - if either argument or a list member is null

    • withSkillGroups

      public @NonNull McpEndpointRegistry withSkillGroups(@NonNull Class<?> annotatedEndpointClass, @NonNull List<@NonNull McpSkillGroup> skillGroups)
      Returns a registry whose generated endpoint for the supplied annotated class carries the given Skills groups.

      The list is snapshotted and replaces the complete group list; an empty list clears it. Existing standalone Skills registrations remain unchanged. Grouping does not select a locale or grant access. Skills identities, ordinary-resource collisions, and output limits are validated against the copied endpoint before the new registry is returned. A failed replacement leaves this registry unchanged.

      Soklet selects the already-generated endpoint by the exact loaded Class identity retained during generated-descriptor discovery. It does not initialize the endpoint class, acquire an endpoint instance, or rediscover handler metadata. Endpoint order, generated handlers, and every other endpoint value are preserved.

      Parameters:
      annotatedEndpointClass - annotated endpoint class whose generated endpoint is selected
      skillGroups - complete Skills group list
      Returns:
      a new immutable registry
      Throws:
      IllegalArgumentException - if this registry did not load a generated endpoint for the exact supplied class, or the resulting Skills output exceeds its limits
      IllegalStateException - if Skills identities or files conflict, or an ordinary resource overlaps a Skills file
      NullPointerException - if either argument or a list member is null

    • fromClasspathIntrospection

      public static @NonNull McpEndpointRegistry fromClasspathIntrospection()
      Resolves every generated MCP endpoint descriptor visible through the current thread's context class loader.

      Endpoint classes are not initialized and endpoint instances are not acquired during descriptor discovery. When a generated handler is invoked, it acquires its endpoint instance through the instance provider configured on the SokletConfig that owns the MCP server. Soklet does not retain or close the returned endpoint instance. Direct invocation of a generated registration handler outside a Soklet-managed request uses InstanceProvider.defaultInstance().

      Returns:
      an immutable registry ordered by endpoint binary name
      Throws:
      IllegalStateException - if no generated descriptor is found or an index or provider is malformed, conflicting, or cannot be loaded

    • fromClasses

      public static @NonNull McpEndpointRegistry fromClasses(@NonNull Class<?> @NonNull ... endpointClasses)
      Resolves generated descriptors for endpoint classes in the supplied order.

      Endpoint classes are not initialized and endpoint instances are not acquired during descriptor discovery. When a generated handler is invoked, it acquires its endpoint instance through the instance provider configured on the SokletConfig that owns the MCP server. Soklet does not retain or close the returned endpoint instance. Direct invocation of a generated registration handler outside a Soklet-managed request uses InstanceProvider.defaultInstance().

      Parameters:
      endpointClasses - one or more annotated endpoint classes
      Returns:
      an immutable registry in the supplied order
      Throws:
      IllegalArgumentException - if no classes are supplied, a class is duplicated, or a class has no generated descriptor, or two selected endpoints have the same normalized path
      IllegalStateException - if an index or provider is malformed, conflicting, or cannot be loaded
      NullPointerException - if the array or one of its classes is null

    • fromEndpoints

      public static @NonNull McpEndpointRegistry fromEndpoints(@NonNull Collection<@NonNull McpEndpoint> endpoints)
      Creates an immutable registry from endpoints in registration order.
      Parameters:
      endpoints - one or more endpoints
      Returns:
      an immutable endpoint registry
      Throws:
      IllegalArgumentException - if no endpoints are supplied or two endpoints have the same normalized path