feat(completion): Add prompt and resource completion support with annotations and server components

Author: codeboyzhou

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpPromptCompletion.java

@@ -0,0 +1,59 @@
+package com.github.codeboyzhou.mcp.declarative.annotation;
+
+import com.github.codeboyzhou.mcp.declarative.server.component.McpCompleteCompletion;
+import com.github.codeboyzhou.mcp.declarative.util.StringHelper;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation for marking methods that provide completion functionality for MCP prompts.
+ *
+ * <p>This annotation is used to identify methods that can handle completion requests for specific
+ * prompts in the Model Context Protocol (MCP) server. When applied to a method, it indicates that
+ * the method can provide auto-completion suggestions for the specified prompt.
+ *
+ * <p>Methods annotated with {@code @McpPromptCompletion} must:
+ *
+ * <ul>
+ *   <li>Return {@link McpCompleteCompletion}
+ *   <li>Accept exactly one parameter of type {@code McpSchema.CompleteRequest.CompleteArgument}
+ *   <li>Be properly configured with a prompt name
+ * </ul>
+ *
+ * <p>The annotation is retained at runtime and can only be applied to methods.
+ *
+ * @author codeboyzhou
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface McpPromptCompletion {
+  /**
+   * Specifies the name of the prompt for which completion is provided.
+   *
+   * <p>This value must match the name of an existing prompt that has been registered with the MCP
+   * server. The completion method will be invoked when completion requests are made for this
+   * specific prompt.
+   *
+   * <p>The name should be a non-empty string that follows the MCP naming conventions for prompts.
+   *
+   * @return the name of the prompt for which completion is provided
+   */
+  String name();
+
+  /**
+   * Specifies an optional title or description for the prompt completion.
+   *
+   * <p>This field provides a human-readable title or description for the completion functionality.
+   * It can be used in documentation, UI displays, or logging to provide more context about what the
+   * completion does.
+   *
+   * <p>If not specified, defaults to an empty string using {@link StringHelper#EMPTY}. This allows
+   * the title to be optional while maintaining consistency across the codebase.
+   *
+   * @return the title or description for the prompt completion, defaults to empty string if not
+   *     specified
+   */
+  String title() default StringHelper.EMPTY;
+}

src/main/java/com/github/codeboyzhou/mcp/declarative/annotation/McpResourceCompletion.java

@@ -0,0 +1,46 @@
+package com.github.codeboyzhou.mcp.declarative.annotation;
+
+import com.github.codeboyzhou.mcp.declarative.server.component.McpCompleteCompletion;
+import java.lang.annotation.ElementType;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
+import java.lang.annotation.Target;
+
+/**
+ * Annotation for marking methods that provide completion functionality for MCP resources.
+ *
+ * <p>This annotation is used to identify methods that can handle completion requests for specific
+ * resources in the Model Context Protocol (MCP) server. When applied to a method, it indicates that
+ * the method can provide auto-completion suggestions for the specified resource URI.
+ *
+ * <p>Methods annotated with {@code @McpResourceCompletion} must:
+ *
+ * <ul>
+ *   <li>Return {@link McpCompleteCompletion}
+ *   <li>Accept exactly one parameter of type {@code McpSchema.CompleteRequest.CompleteArgument}
+ *   <li>Be properly configured with a resource URI
+ * </ul>
+ *
+ * <p>The annotation is retained at runtime and can only be applied to methods. Resource completion
+ * is typically used to provide suggestions for resource identifiers, file paths, or other
+ * resource-specific parameters.
+ *
+ * @author codeboyzhou
+ */
+@Target(ElementType.METHOD)
+@Retention(RetentionPolicy.RUNTIME)
+public @interface McpResourceCompletion {
+  /**
+   * Specifies the URI of the resource for which completion is provided.
+   *
+   * <p>This value must match the URI of an existing resource that has been registered with the MCP
+   * server. The completion method will be invoked when completion requests are made for this
+   * specific resource.
+   *
+   * <p>The URI string must be non-null and non-empty. It should uniquely identify the resource
+   * within the MCP server context.
+   *
+   * @return the URI of the resource for which completion is provided
+   */
+  String uri();
+}

src/main/java/com/github/codeboyzhou/mcp/declarative/exception/McpServerComponentRegistrationException.java

@@ -0,0 +1,60 @@
+package com.github.codeboyzhou.mcp.declarative.exception;
+
+/**
+ * Exception thrown when an error occurs during MCP server component registration.
+ *
+ * <p>This exception is used to indicate failures that occur while attempting to register MCP server
+ * components such as resources, prompts, tools, or completion handlers. Common scenarios where this
+ * exception may be thrown include:
+ *
+ * <ul>
+ *   <li>Invalid method signatures for component handlers
+ *   <li>Missing or incorrect annotations on component methods
+ *   <li>Dependency injection failures during component creation
+ *   <li>Configuration errors in component metadata
+ *   <li>Reflection-related errors during component discovery
+ * </ul>
+ *
+ * <p>This exception extends {@link McpServerException} and is part of the MCP declarative
+ * framework's exception hierarchy, providing specific error information for component registration
+ * failures while maintaining compatibility with the general MCP server exception handling.
+ *
+ * @author codeboyzhou
+ */
+public class McpServerComponentRegistrationException extends McpServerException {
+  /**
+   * Constructs a new {@code McpServerComponentRegistrationException} with the specified detail
+   * message.
+   *
+   * <p>This constructor is typically used when the component registration failure can be described
+   * by a single error message without an underlying cause. The message should provide clear
+   * information about what went wrong during the registration process.
+   *
+   * @param message the detail message explaining the reason for the exception, may be null but
+   *     should provide meaningful error information
+   */
+  public McpServerComponentRegistrationException(String message) {
+    super(message);
+  }
+
+  /**
+   * Constructs a new {@code McpServerComponentRegistrationException} with the specified detail
+   * message and cause.
+   *
+   * <p>This constructor is typically used when the component registration failure is caused by
+   * another exception. The cause exception is preserved and can be accessed later for detailed
+   * error analysis and debugging.
+   *
+   * <p>Common causes include reflection exceptions, dependency injection failures, or validation
+   * errors during component creation. The message should provide context about the registration
+   * operation that failed.
+   *
+   * @param message the detail message explaining the reason for the exception, may be null but
+   *     should provide meaningful error information
+   * @param cause the underlying cause of the exception, may be null if the cause is unknown or not
+   *     applicable
+   */
+  public McpServerComponentRegistrationException(String message, Throwable cause) {
+    super(message, cause);
+  }
+}

src/main/java/com/github/codeboyzhou/mcp/declarative/reflect/MethodCache.java

@@ -1,7 +1,9 @@
 package com.github.codeboyzhou.mcp.declarative.reflect;
 
 import com.github.codeboyzhou.mcp.declarative.annotation.McpPrompt;
+import com.github.codeboyzhou.mcp.declarative.annotation.McpPromptCompletion;
 import com.github.codeboyzhou.mcp.declarative.annotation.McpResource;
+import com.github.codeboyzhou.mcp.declarative.annotation.McpResourceCompletion;
 import com.github.codeboyzhou.mcp.declarative.annotation.McpTool;
 import com.github.codeboyzhou.mcp.declarative.common.Immutable;
 import java.lang.reflect.Method;
@@ -43,6 +45,12 @@ public final class MethodCache {
   /** The annotation {@link McpTool} on the cached method. */
   private final McpTool mcpToolAnnotation;
 
+  /** The annotation {@link McpPromptCompletion} on the cached method. */
+  private final McpPromptCompletion mcpPromptCompletionAnnotation;
+
+  /** The annotation {@link McpResourceCompletion} on the cached method. */
+  private final McpResourceCompletion mcpResourceCompletionAnnotation;
+
   /**
    * Creates a new instance of {@code MethodCache} with the specified method.
    *
@@ -58,6 +66,8 @@ public MethodCache(Method method) {
     this.mcpResourceAnnotation = method.getAnnotation(McpResource.class);
     this.mcpPromptAnnotation = method.getAnnotation(McpPrompt.class);
     this.mcpToolAnnotation = method.getAnnotation(McpTool.class);
+    this.mcpPromptCompletionAnnotation = method.getAnnotation(McpPromptCompletion.class);
+    this.mcpResourceCompletionAnnotation = method.getAnnotation(McpResourceCompletion.class);
   }
 
   /**
@@ -151,6 +161,24 @@ public McpTool getMcpToolAnnotation() {
     return mcpToolAnnotation;
   }
 
+  /**
+   * Returns the annotation {@link McpPromptCompletion} on the cached method.
+   *
+   * @return the annotation {@link McpPromptCompletion} on the cached method
+   */
+  public McpPromptCompletion getMcpPromptCompletionAnnotation() {
+    return mcpPromptCompletionAnnotation;
+  }
+
+  /**
+   * Returns the annotation {@link McpResourceCompletion} on the cached method.
+   *
+   * @return the annotation {@link McpResourceCompletion} on the cached method
+   */
+  public McpResourceCompletion getMcpResourceCompletionAnnotation() {
+    return mcpResourceCompletionAnnotation;
+  }
+
   @Override
   public boolean equals(Object obj) {
     if (this == obj) {

src/main/java/com/github/codeboyzhou/mcp/declarative/server/AbstractMcpServer.java

@@ -19,14 +19,16 @@ public abstract class AbstractMcpServer<S extends McpServerInfo> implements McpS
    * @param serverInfo the server info
    */
   public void start(S serverInfo) {
+    McpServerComponentRegister register = new McpServerComponentRegister();
     McpSyncServer server =
         sync(serverInfo)
             .serverInfo(serverInfo.name(), serverInfo.version())
             .capabilities(serverCapabilities(serverInfo))
             .instructions(serverInfo.instructions())
             .requestTimeout(serverInfo.requestTimeout())
+            .completions(register.registerCompletions())
             .build();
-    McpServerComponentRegister.of(server).registerComponents();
+    register.registerComponents(server);
   }
 
   /**

src/main/java/com/github/codeboyzhou/mcp/declarative/server/component/McpCompleteCompletion.java

@@ -0,0 +1,133 @@
+package com.github.codeboyzhou.mcp.declarative.server.component;
+
+import java.util.Collection;
+import java.util.List;
+
+/**
+ * Represents a completion result for MCP (Model Context Protocol) server operations.
+ *
+ * <p>This record encapsulates the response data for completion requests, including the list of
+ * completion values, total count, and whether more results are available. The class is designed to
+ * be immutable and provides defensive copying to protect internal state from external modification.
+ *
+ * @param values the list of completion values, may be null
+ * @param total the total number of available completions, may be null
+ * @param hasMore true if more completions are available, false otherwise
+ * @author codeboyzhou
+ */
+public record McpCompleteCompletion(List<String> values, Integer total, boolean hasMore) {
+  /**
+   * Compact constructor that creates a defensive copy of the values list.
+   *
+   * <p>This constructor ensures that the internal list cannot be modified from outside the record
+   * by creating an immutable copy using {@link List#copyOf(Collection)}. If the input list is null,
+   * it remains null to preserve the original intent.
+   *
+   * @param values the input list of completion values to be defensively copied
+   */
+  public McpCompleteCompletion {
+    values = values == null ? null : List.copyOf(values);
+  }
+
+  /**
+   * Creates a new {@link Builder} instance for constructing {@link McpCompleteCompletion} objects.
+   *
+   * <p>This factory method provides a convenient way to create a builder for step-by-step
+   * construction of completion results using the builder pattern.
+   *
+   * @return a new {@link Builder} instance
+   */
+  public static McpCompleteCompletion.Builder builder() {
+    return new McpCompleteCompletion.Builder();
+  }
+
+  /**
+   * Creates an empty {@link McpCompleteCompletion} instance.
+   *
+   * <p>This factory method returns a completion result with no values, zero total count, and no
+   * more results available. Useful as a default or placeholder completion.
+   *
+   * @return an empty {@link McpCompleteCompletion} instance
+   */
+  public static McpCompleteCompletion empty() {
+    return builder().values(List.of()).total(0).hasMore(false).build();
+  }
+
+  /**
+   * Builder class for constructing {@link McpCompleteCompletion} instances.
+   *
+   * <p>This builder provides a fluent API for creating completion results with defensive copying to
+   * protect against external modification of mutable inputs. The builder maintains the same
+   * immutability guarantees as the record itself.
+   *
+   * @author codeboyzhou
+   */
+  public static class Builder {
+    /** The list of completion values. */
+    private List<String> values;
+
+    /** The total number of available completions. */
+    private Integer total;
+
+    /** Whether more completions are available. */
+    private boolean hasMore;
+
+    /**
+     * Sets the completion values with defensive copying.
+     *
+     * <p>This method creates an immutable copy of the input list to prevent external modification
+     * after the value has been set. If the input list is null, the internal values field is set to
+     * null.
+     *
+     * @param values the list of completion values to set, may be null
+     * @return this {@link Builder} instance for method chaining
+     */
+    public Builder values(List<String> values) {
+      // Create defensive copy to prevent external modification after setting
+      this.values = values == null ? null : List.copyOf(values);
+      return this;
+    }
+
+    /**
+     * Sets the total number of available completions.
+     *
+     * <p>This value represents the total count of completions that could be returned, which may be
+     * greater than the number of values in the current completion result if pagination is
+     * supported.
+     *
+     * @param total the total number of available completions, may be null
+     * @return this {@link Builder} instance for method chaining
+     */
+    public Builder total(Integer total) {
+      this.total = total;
+      return this;
+    }
+
+    /**
+     * Sets whether more completions are available.
+     *
+     * <p>This flag indicates whether additional completion results can be obtained through further
+     * requests, typically used for pagination or incremental loading scenarios.
+     *
+     * @param hasMore true if more completions are available, false otherwise
+     * @return this {@link Builder} instance for method chaining
+     */
+    public Builder hasMore(boolean hasMore) {
+      this.hasMore = hasMore;
+      return this;
+    }
+
+    /**
+     * Builds a new {@link McpCompleteCompletion} instance with the configured values.
+     *
+     * <p>This method creates a new record instance using the current builder state. The record's
+     * compact constructor will apply additional defensive copying to ensure the final object is
+     * fully immutable.
+     *
+     * @return a new {@link McpCompleteCompletion} instance with the configured values
+     */
+    public McpCompleteCompletion build() {
+      return new McpCompleteCompletion(values, total, hasMore);
+    }
+  }
+}