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

Class McpServerConfig

java.lang.Object
org.apache.juneau.rest.server.mcp.McpServerConfig
public class McpServerConfig extends Object
Aggregate configuration consumed by the bound McpRevision.

Applications register a single McpServerConfig (typically as a bean in their RestContext bean store) listing the tools, prompts, resources, and resource templates to expose, plus optional server metadata and a pagination strategy.

This type is revision-neutral: it holds no field typed with any protocol revision's wire beans, and in particular holds no capabilities field in any form. The protocol version is owned by McpRevision.protocolVersion(), and an explicit capabilities advertisement is owned by a revision-specific hook on that revision's servlet or endpoint mixin.

  • Constructor Details

  • Method Details

    • getName

      public String getName()
      Server name reported in initialize.

      When both this and getVersion() are null, the bound revision substitutes its own default server identity.

      Returns:
      The name, or null if not set.

    • setName

      public McpServerConfig setName(String value)
      Sets the server name.
      Parameters:
      value - The new value. Can be null to unset the property.
      Returns:
      This object.

    • getVersion

      public String getVersion()
      Server version reported in initialize.
      Returns:
      The version, or null if not set.

    • setVersion

      public McpServerConfig setVersion(String value)
      Sets the server version.
      Parameters:
      value - The new value. Can be null to unset the property.
      Returns:
      This object.

    • getInstructions

      public String getInstructions()
      Optional instructions surfaced via initialize.
      Returns:
      The instructions, or null if not set.

    • setInstructions

      public McpServerConfig setInstructions(String instructions)
      Sets initialize instructions.
      Parameters:
      instructions - The new value.
      Returns:
      This object (for method chaining).

    • getTools

      public List<McpToolHandler> getTools()
      Registered tool handlers.
      Returns:
      Mutable list of handlers. Never null.

    • setTools

      public McpServerConfig setTools(List<McpToolHandler> tools)
      Sets the tool handler list.
      Parameters:
      tools - The new value (or null to clear).
      Returns:
      This object (for method chaining).

    • addTool

      public McpServerConfig addTool(McpToolHandler... handlers)
      Convenience: append one or more tool handlers.
      Parameters:
      handlers - Handlers to add.
      Returns:
      This object (for method chaining).

    • addTool

      public McpServerConfig addTool(McpTypedToolHandler<?,?> handler)
      Convenience: adapt and append a single typed tool handler.

      The handler is bridged into a raw McpToolHandler via McpTypedHandlers.adaptTool(McpTypedToolHandler) before it is stored. This overload is intentionally singular: a typed varargs overload would make addTool() ambiguous. To register multiple typed handlers, use chained addTool(...) calls, or adapt them explicitly with McpTypedHandlers.adaptTool(McpTypedToolHandler) and pass the results to addTool(McpToolHandler...).

      Parameters:
      handler - The typed handler to adapt and add.
      Returns:
      This object (for method chaining).

    • getPrompts

      public List<McpPromptHandler> getPrompts()
      Registered prompt handlers.
      Returns:
      Mutable list of handlers. Never null.

    • setPrompts

      public McpServerConfig setPrompts(List<McpPromptHandler> prompts)
      Sets the prompt handler list.

      The complete resulting registry is validated before publication; on failure, the previously published registry is left unchanged. See addPrompt(McpPromptHandler...) for the validated conditions.

      Parameters:
      prompts - The new value (or null to clear).
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If the resulting registry would be invalid.

    • addPrompt

      public McpServerConfig addPrompt(McpPromptHandler... handlers)
      Convenience: append one or more prompt handlers.

      The complete resulting registry - the handlers already registered plus handlers - is validated before publication; on failure, the previously published registry is left unchanged. Fails fast with IllegalArgumentException for a single prompt whose declared McpPromptArgument list either:

      • repeats a non-null argument name; or
      • attaches a non-null completer to a null or blank argument name.
      Parameters:
      handlers - Handlers to add.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If the resulting registry would be invalid.

    • getResources

      public List<McpResourceHandler> getResources()
      Registered resource handlers.
      Returns:
      Mutable list of handlers. Never null.

    • setResources

      public McpServerConfig setResources(List<McpResourceHandler> resources)
      Sets the resource handler list.
      Parameters:
      resources - The new value (or null to clear).
      Returns:
      This object (for method chaining).

    • addResource

      public McpServerConfig addResource(McpResourceHandler... handlers)
      Convenience: append one or more resource handlers.
      Parameters:
      handlers - Handlers to add.
      Returns:
      This object (for method chaining).

    • getResourceTemplates

      public List<McpResourceTemplateHandler> getResourceTemplates()
      Registered resource-template handlers.

      Every read of this property (re)validates the current registry if the list has been mutated directly since the last validated setResourceTemplates(List), addResourceTemplate(McpResourceTemplateHandler...), addResourceTemplate(McpResourceTemplateSpec...), or setResourceTemplateSpecs(List) call, so direct-list corruption is caught on first consumption rather than silently propagating to dispatch. A registry that has not been mutated since its last successful validation is returned without recompiling its templates.

      Returns:
      Mutable list of handlers. Never null.
      Throws:
      IllegalArgumentException - If the list was mutated directly into an invalid state (see addResourceTemplate(McpResourceTemplateHandler...) for the validated conditions).

    • setResourceTemplates

      public McpServerConfig setResourceTemplates(List<McpResourceTemplateHandler> value)
      Sets the resource-template handler list.

      The complete resulting registry is validated before publication; on failure, the previously published registry is left unchanged. See addResourceTemplate(McpResourceTemplateHandler...) for the validated conditions.

      Parameters:
      value - The new value (or null to clear).
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If the resulting registry would be invalid.

    • setResourceTemplateSpecs

      public McpServerConfig setResourceTemplateSpecs(List<McpResourceTemplateSpec> value)
      Sets the resource-template registry from bare descriptors, replacing each with a built-in listing-only handler equivalent to what addResourceTemplate(McpResourceTemplateSpec...) wraps.

      The complete resulting registry is validated before publication; on failure, the previously published registry is left unchanged.

      Parameters:
      value - The new descriptor list (or null to clear).
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If the resulting registry would be invalid.

    • addResourceTemplate

      public McpServerConfig addResourceTemplate(McpResourceTemplateHandler... values)
      Convenience: append one or more resource-template handlers.

      The complete resulting registry - the handlers already registered plus values - is validated before publication; on failure, the previously published registry is left unchanged. Fails fast with IllegalArgumentException naming the offending registration index and template for:

      A syntactically valid uriTemplate outside McpUriTemplateMatcher's reverse-matchable subset is a legal registration, not an error.
      Parameters:
      values - Handlers to add.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If the resulting registry would be invalid.

    • addResourceTemplate

      public McpServerConfig addResourceTemplate(McpResourceTemplateSpec... values)
      Convenience: append one or more resource-template descriptors as built-in listing-only handlers.

      Each descriptor is wrapped in a handler whose McpResourceTemplateHandler.descriptor() returns that same descriptor instance, whose read always returns null, and whose completer always returns null. The resulting registry is validated exactly as in addResourceTemplate(McpResourceTemplateHandler...).

      Parameters:
      values - Descriptors to add.
      Returns:
      This object (for method chaining).
      Throws:
      IllegalArgumentException - If the resulting registry would be invalid.

    • resolveResourceTemplate

      public McpServerConfig.ResourceTemplateMatch resolveResourceTemplate(String uri)
      Resolves the concrete resources/read request URI uri against the registered resource-template registry, selecting the single winning template handler using the deterministic specificity ranking shared identically by both dated adapters.

      A candidate is every reverse-matchable (McpUriTemplateMatcher.isReverseMatchable()) template handler whose McpUriTemplateMatcher.match(String) succeeds against uri; a non-reverse-matchable or non-matching template handler is never a candidate. Successful candidates are ranked, highest priority first, by exactly:

      1. greater literalOctetCount;
      2. then fewer variableCount; and
      3. then earlier registration index (candidates are scanned in registration order and a later candidate only displaces the current winner on a strictly better key, so the first-registered candidate wins a complete tie).
      No other tie-breaker - operator type, capture width, descriptor name/title, or match-time value length - is consulted.

      This method does not consult exact McpResourceHandler registrations. Exact lookup is unconditionally higher precedence than any template match; callers must perform exact lookup first and invoke this method only on an exact miss.

      Parameters:
      uri - The concrete request URI. Can be null, in which case this method returns null.
      Returns:
      The winning match (handler plus its immutable, insertion-ordered decoded variable map), or null if no registered reverse-matchable template matches uri.

    • promptCompleter

      public McpCompleter promptCompleter(String promptName, String argumentName)
      Resolves the completer registered for one declared argument of a registered prompt, by exact prompt name and exact argument name.

      This is one half of the neutral cross-target completion lookup shared identically by both dated adapters; see templateCompleter(String, String) for the resource-template half and completer(McpCompletionRef, String) for the unified entry point.

      Parameters:
      promptName - The exact prompt name to look up. Can be null, in which case this method returns null.
      argumentName - The exact argument name to look up. Can be null, in which case this method returns null.
      Returns:
      The argument's completer, or null if the prompt is unknown, the argument is undeclared, or the argument declares no completer. Never invokes the completer.

    • templateCompleter

      public McpCompleter templateCompleter(String uriTemplate, String variableName)
      Resolves the completer registered for one declared variable of a registered resource-template, by exact registered uriTemplate string and exact variable name.

      Matching is against the exact registered template string, not a reverse-match against a concrete URI: a completion/complete reference names the declaration being completed, never a concrete/expanded URI. This is one half of the neutral cross-target completion lookup shared identically by both dated adapters; see promptCompleter(String, String) for the prompt half and completer(McpCompletionRef, String) for the unified entry point. Delegates the "variable must be declared by the template" check to resourceTemplateCompleter(McpResourceTemplateHandler, String) rather than re-parsing.

      Parameters:
      uriTemplate - The exact registered uriTemplate to look up. Can be null, in which case this method returns null.
      variableName - The exact variable name to look up. Can be null, in which case this method returns null.
      Returns:
      The variable's completer, or null if the template is unregistered, the variable is undeclared, or the handler declares no completer for it. Never invokes the completer.

    • completer

      public McpCompleter completer(McpCompletionRef ref, String argumentName)
      Unified neutral completion lookup: resolves the completer for a completion/complete target, dispatching by McpCompletionRef.Kind to promptCompleter(String, String) or templateCompleter(String, String).

      Both dated adapters call this same method for both target kinds, so template/prompt resolution policy is defined exactly once, in this neutral module.

      Parameters:
      ref - The completion reference identifying the exact prompt name or registered template string. Can be null, in which case this method returns null.
      argumentName - The exact argument/variable name to look up. Can be null, in which case this method returns null.
      Returns:
      The resolved completer, or null if ref is null/has no kind, or if the target-specific lookup finds none. Never invokes the completer.

    • hasAnyCompleter

      public boolean hasAnyCompleter()
      Reports whether completions capability should be advertised: whether at least one registered prompt argument or resource-template variable currently declares a non-null completer.

      This never invokes a completer; it only detects registration, so both dated adapters can use it for auto-derived capability advertisement without side effects.

      Returns:
      true if at least one prompt-argument completer or resource-template variable completer is registered.

    • getCursor

      public McpCursor getCursor()
      Pagination strategy for list dispatchers (tools / prompts / resources / resource templates).
      Returns:
      The cursor. Never null (defaults to McpCursor.SINGLE_PAGE).

    • setCursor

      public McpServerConfig setCursor(McpCursor cursor)
      Sets the pagination strategy.
      Parameters:
      cursor - The new value (or null to reset to McpCursor.SINGLE_PAGE).
      Returns:
      This object (for method chaining).