feat(completion): implement completion API support (#141)

Add completion API support to the MCP protocol implementation:

- Add CompleteRequest and CompleteResult schema classes
- Implement completion capabilities in ServerCapabilities
- Add completion handlers in McpAsyncServer and McpServer
- Add completion client methods in McpAsyncClient and McpSyncClient
- Add CompletionRefKey and completion specifications in McpServerFeatures
- Add integration test for completion functionality
- Fix isPresent() check to use isEmpty() in WebMvcSseServerTransportProvider
- Replace McpServerFeatures.CompletionRefKey by McpSchemaCompleteReference

Co-authored-by: Christian Tzolov <[email protected]>

Signed-off-by: jitokim <[email protected]>

Author: jitokim

mcp-spring/mcp-spring-webflux/src/test/java/io/modelcontextprotocol/WebFluxSseIntegrationTests.java

@@ -10,6 +10,7 @@
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.TimeUnit;
 import java.util.concurrent.atomic.AtomicReference;
+import java.util.function.BiFunction;
 import java.util.function.Function;
 import java.util.stream.Collectors;
 
@@ -20,19 +21,12 @@
 import io.modelcontextprotocol.server.McpServer;
 import io.modelcontextprotocol.server.McpServerFeatures;
 import io.modelcontextprotocol.server.TestUtil;
+import io.modelcontextprotocol.server.McpSyncServerExchange;
 import io.modelcontextprotocol.server.transport.WebFluxSseServerTransportProvider;
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
-import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
-import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageRequest;
-import io.modelcontextprotocol.spec.McpSchema.CreateMessageResult;
-import io.modelcontextprotocol.spec.McpSchema.InitializeResult;
-import io.modelcontextprotocol.spec.McpSchema.ModelPreferences;
-import io.modelcontextprotocol.spec.McpSchema.Role;
-import io.modelcontextprotocol.spec.McpSchema.Root;
-import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
-import io.modelcontextprotocol.spec.McpSchema.Tool;
+import io.modelcontextprotocol.spec.McpSchema.*;
+import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities.CompletionCapabilities;
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.params.ParameterizedTest;
@@ -759,4 +753,53 @@ void testLoggingNotification(String clientType) {
 		mcpServer.close();
 	}
 
-}
+	// ---------------------------------------
+	// Completion Tests
+	// ---------------------------------------
+	@ParameterizedTest(name = "{0} : Completion call")
+	@ValueSource(strings = { "httpclient", "webflux" })
+	void testCompletionShouldReturnExpectedSuggestions(String clientType) {
+		var clientBuilder = clientBuilders.get(clientType);
+
+		var expectedValues = List.of("python", "pytorch", "pyside");
+		var completionResponse = new McpSchema.CompleteResult(new CompleteResult.CompleteCompletion(expectedValues, 10, // total
+				true // hasMore
+		));
+
+		AtomicReference<CompleteRequest> samplingRequest = new AtomicReference<>();
+		BiFunction<McpSyncServerExchange, CompleteRequest, CompleteResult> completionHandler = (mcpSyncServerExchange,
+				request) -> {
+			samplingRequest.set(request);
+			return completionResponse;
+		};
+
+		var mcpServer = McpServer.sync(mcpServerTransportProvider)
+			.capabilities(ServerCapabilities.builder().completions(new CompletionCapabilities()).build())
+			.prompts(new McpServerFeatures.SyncPromptSpecification(
+					new Prompt("code_review", "this is code review prompt", List.of()),
+					(mcpSyncServerExchange, getPromptRequest) -> null))
+			.completions(new McpServerFeatures.SyncCompletionSpecification(
+					new McpSchema.PromptReference("ref/prompt", "code_review"), completionHandler))
+			.build();
+
+		try (var mcpClient = clientBuilder.build()) {
+
+			InitializeResult initResult = mcpClient.initialize();
+			assertThat(initResult).isNotNull();
+
+			CompleteRequest request = new CompleteRequest(new PromptReference("ref/prompt", "code_review"),
+					new CompleteRequest.CompleteArgument("language", "py"));
+
+			CompleteResult result = mcpClient.completeCompletion(request);
+
+			assertThat(result).isNotNull();
+
+			assertThat(samplingRequest.get().argument().name()).isEqualTo("language");
+			assertThat(samplingRequest.get().argument().value()).isEqualTo("py");
+			assertThat(samplingRequest.get().ref().type()).isEqualTo("ref/prompt");
+		}
+
+		mcpServer.close();
+	}
+
+}

mcp-spring/mcp-spring-webmvc/src/main/java/io/modelcontextprotocol/server/transport/WebMvcSseServerTransportProvider.java

@@ -300,7 +300,7 @@ private ServerResponse handleMessage(ServerRequest request) {
 			return ServerResponse.status(HttpStatus.SERVICE_UNAVAILABLE).body("Server is shutting down");
 		}
 
-		if (!request.param("sessionId").isPresent()) {
+		if (request.param("sessionId").isEmpty()) {
 			return ServerResponse.badRequest().body(new McpError("Session ID missing in message endpoint"));
 		}
 

mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java

@@ -71,6 +71,7 @@
  *
  * @author Dariusz Jędrzejczyk
  * @author Christian Tzolov
+ * @author Jihoon Kim
  * @see McpClient
  * @see McpSchema
  * @see McpClientSession
@@ -816,4 +817,25 @@ void setProtocolVersions(List<String> protocolVersions) {
 		this.protocolVersions = protocolVersions;
 	}
 
+	// --------------------------
+	// Completions
+	// --------------------------
+	private static final TypeReference<McpSchema.CompleteResult> COMPLETION_COMPLETE_RESULT_TYPE_REF = new TypeReference<>() {
+	};
+
+	/**
+	 * Sends a completion/complete request to generate value suggestions based on a given
+	 * reference and argument. This is typically used to provide auto-completion options
+	 * for user input fields.
+	 * @param completeRequest The request containing the prompt or resource reference and
+	 * argument for which to generate completions.
+	 * @return A Mono that completes with the result containing completion suggestions.
+	 * @see McpSchema.CompleteRequest
+	 * @see McpSchema.CompleteResult
+	 */
+	public Mono<McpSchema.CompleteResult> completeCompletion(McpSchema.CompleteRequest completeRequest) {
+		return this.withInitializationCheck("complete completions", initializedResult -> this.mcpSession
+			.sendRequest(McpSchema.METHOD_COMPLETION_COMPLETE, completeRequest, COMPLETION_COMPLETE_RESULT_TYPE_REF));
+	}
+
 }

mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java

@@ -46,6 +46,7 @@
  *
  * @author Dariusz Jędrzejczyk
  * @author Christian Tzolov
+ * @author Jihoon Kim
  * @see McpClient
  * @see McpAsyncClient
  * @see McpSchema
@@ -334,4 +335,14 @@ public void setLoggingLevel(McpSchema.LoggingLevel loggingLevel) {
 		this.delegate.setLoggingLevel(loggingLevel).block();
 	}
 
+	/**
+	 * Send a completion/complete request.
+	 * @param completeRequest the completion request contains the prompt or resource
+	 * reference and arguments for generating suggestions.
+	 * @return the completion result containing suggested values.
+	 */
+	public McpSchema.CompleteResult completeCompletion(McpSchema.CompleteRequest completeRequest) {
+		return this.delegate.completeCompletion(completeRequest).block();
+	}
+
 }

mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServer.java

@@ -69,6 +69,7 @@
  *
  * @author Christian Tzolov
  * @author Dariusz Jędrzejczyk
+ * @author Jihoon Kim
  * @see McpServer
  * @see McpSchema
  * @see McpClientSession
@@ -269,6 +270,8 @@ private static class AsyncServerImpl extends McpAsyncServer {
 		// broadcasting loggingNotification.
 		private LoggingLevel minLoggingLevel = LoggingLevel.DEBUG;
 
+		private final ConcurrentHashMap<McpSchema.CompleteReference, McpServerFeatures.AsyncCompletionSpecification> completions = new ConcurrentHashMap<>();
+
 		private List<String> protocolVersions = List.of(McpSchema.LATEST_PROTOCOL_VERSION);
 
 		AsyncServerImpl(McpServerTransportProvider mcpTransportProvider, ObjectMapper objectMapper,
@@ -282,6 +285,7 @@ private static class AsyncServerImpl extends McpAsyncServer {
 			this.resources.putAll(features.resources());
 			this.resourceTemplates.addAll(features.resourceTemplates());
 			this.prompts.putAll(features.prompts());
+			this.completions.putAll(features.completions());
 
 			Map<String, McpServerSession.RequestHandler<?>> requestHandlers = new HashMap<>();
 
@@ -314,6 +318,11 @@ private static class AsyncServerImpl extends McpAsyncServer {
 				requestHandlers.put(McpSchema.METHOD_LOGGING_SET_LEVEL, setLoggerRequestHandler());
 			}
 
+			// Add completion API handlers if the completion capability is enabled
+			if (this.serverCapabilities.completions() != null) {
+				requestHandlers.put(McpSchema.METHOD_COMPLETION_COMPLETE, completionCompleteRequestHandler());
+			}
+
 			Map<String, McpServerSession.NotificationHandler> notificationHandlers = new HashMap<>();
 
 			notificationHandlers.put(McpSchema.METHOD_NOTIFICATION_INITIALIZED, (exchange, params) -> Mono.empty());
@@ -706,6 +715,81 @@ private McpServerSession.RequestHandler<Object> setLoggerRequestHandler() {
 			};
 		}
 
+		private McpServerSession.RequestHandler<McpSchema.CompleteResult> completionCompleteRequestHandler() {
+			return (exchange, params) -> {
+				McpSchema.CompleteRequest request = parseCompletionParams(params);
+
+				if (request.ref() == null) {
+					return Mono.error(new McpError("ref must not be null"));
+				}
+
+				if (request.ref().type() == null) {
+					return Mono.error(new McpError("type must not be null"));
+				}
+
+				String type = request.ref().type();
+
+				// check if the referenced resource exists
+				if (type.equals("ref/prompt") && request.ref() instanceof McpSchema.PromptReference promptReference) {
+					McpServerFeatures.AsyncPromptSpecification prompt = this.prompts.get(promptReference.name());
+					if (prompt == null) {
+						return Mono.error(new McpError("Prompt not found: " + promptReference.name()));
+					}
+				}
+
+				if (type.equals("ref/resource")
+						&& request.ref() instanceof McpSchema.ResourceReference resourceReference) {
+					McpServerFeatures.AsyncResourceSpecification resource = this.resources.get(resourceReference.uri());
+					if (resource == null) {
+						return Mono.error(new McpError("Resource not found: " + resourceReference.uri()));
+					}
+				}
+
+				McpServerFeatures.AsyncCompletionSpecification specification = this.completions.get(request.ref());
+
+				if (specification == null) {
+					return Mono.error(new McpError("AsyncCompletionSpecification not found: " + request.ref()));
+				}
+
+				return specification.completionHandler().apply(exchange, request);
+			};
+		}
+
+		/**
+		 * Parses the raw JSON-RPC request parameters into a
+		 * {@link McpSchema.CompleteRequest} object.
+		 * <p>
+		 * This method manually extracts the `ref` and `argument` fields from the input
+		 * map, determines the correct reference type (either prompt or resource), and
+		 * constructs a fully-typed {@code CompleteRequest} instance.
+		 * @param object the raw request parameters, expected to be a Map containing "ref"
+		 * and "argument" entries.
+		 * @return a {@link McpSchema.CompleteRequest} representing the structured
+		 * completion request.
+		 * @throws IllegalArgumentException if the "ref" type is not recognized.
+		 */
+		@SuppressWarnings("unchecked")
+		private McpSchema.CompleteRequest parseCompletionParams(Object object) {
+			Map<String, Object> params = (Map<String, Object>) object;
+			Map<String, Object> refMap = (Map<String, Object>) params.get("ref");
+			Map<String, Object> argMap = (Map<String, Object>) params.get("argument");
+
+			String refType = (String) refMap.get("type");
+
+			McpSchema.CompleteReference ref = switch (refType) {
+				case "ref/prompt" -> new McpSchema.PromptReference(refType, (String) refMap.get("name"));
+				case "ref/resource" -> new McpSchema.ResourceReference(refType, (String) refMap.get("uri"));
+				default -> throw new IllegalArgumentException("Invalid ref type: " + refType);
+			};
+
+			String argName = (String) argMap.get("name");
+			String argValue = (String) argMap.get("value");
+			McpSchema.CompleteRequest.CompleteArgument argument = new McpSchema.CompleteRequest.CompleteArgument(
+					argName, argValue);
+
+			return new McpSchema.CompleteRequest(ref, argument);
+		}
+
 		// ---------------------------------------
 		// Sampling
 		// ---------------------------------------

mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java

@@ -115,6 +115,7 @@
  *
  * @author Christian Tzolov
  * @author Dariusz Jędrzejczyk
+ * @author Jihoon Kim
  * @see McpAsyncServer
  * @see McpSyncServer
  * @see McpServerTransportProvider
@@ -192,6 +193,8 @@ class AsyncSpecification {
 		 */
 		private final Map<String, McpServerFeatures.AsyncPromptSpecification> prompts = new HashMap<>();
 
+		private final Map<McpSchema.CompleteReference, McpServerFeatures.AsyncCompletionSpecification> completions = new HashMap<>();
+
 		private final List<BiFunction<McpAsyncServerExchange, List<McpSchema.Root>, Mono<Void>>> rootsChangeHandlers = new ArrayList<>();
 
 		private Duration requestTimeout = Duration.ofSeconds(10); // Default timeout
@@ -581,7 +584,8 @@ public AsyncSpecification objectMapper(ObjectMapper objectMapper) {
 		 */
 		public McpAsyncServer build() {
 			var features = new McpServerFeatures.Async(this.serverInfo, this.serverCapabilities, this.tools,
-					this.resources, this.resourceTemplates, this.prompts, this.rootsChangeHandlers, this.instructions);
+					this.resources, this.resourceTemplates, this.prompts, this.completions, this.rootsChangeHandlers,
+					this.instructions);
 			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
 			return new McpAsyncServer(this.transportProvider, mapper, features, this.requestTimeout);
 		}
@@ -635,6 +639,8 @@ class SyncSpecification {
 		 */
 		private final Map<String, McpServerFeatures.SyncPromptSpecification> prompts = new HashMap<>();
 
+		private final Map<McpSchema.CompleteReference, McpServerFeatures.SyncCompletionSpecification> completions = new HashMap<>();
+
 		private final List<BiConsumer<McpSyncServerExchange, List<McpSchema.Root>>> rootsChangeHandlers = new ArrayList<>();
 
 		private Duration requestTimeout = Duration.ofSeconds(10); // Default timeout
@@ -957,6 +963,37 @@ public SyncSpecification prompts(McpServerFeatures.SyncPromptSpecification... pr
 			return this;
 		}
 
+		/**
+		 * Registers multiple completions with their handlers using a List. This method is
+		 * useful when completions need to be added in bulk from a collection.
+		 * @param completions List of completion specifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if completions is null
+		 * @see #completions(McpServerFeatures.SyncCompletionSpecification...)
+		 */
+		public SyncSpecification completions(List<McpServerFeatures.SyncCompletionSpecification> completions) {
+			Assert.notNull(completions, "Completions list must not be null");
+			for (McpServerFeatures.SyncCompletionSpecification completion : completions) {
+				this.completions.put(completion.referenceKey(), completion);
+			}
+			return this;
+		}
+
+		/**
+		 * Registers multiple completions with their handlers using varargs. This method
+		 * is useful when completions are defined inline and added directly.
+		 * @param completions Array of completion specifications. Must not be null.
+		 * @return This builder instance for method chaining
+		 * @throws IllegalArgumentException if completions is null
+		 */
+		public SyncSpecification completions(McpServerFeatures.SyncCompletionSpecification... completions) {
+			Assert.notNull(completions, "Completions list must not be null");
+			for (McpServerFeatures.SyncCompletionSpecification completion : completions) {
+				this.completions.put(completion.referenceKey(), completion);
+			}
+			return this;
+		}
+
 		/**
 		 * Registers a consumer that will be notified when the list of roots changes. This
 		 * is useful for updating resource availability dynamically, such as when new
@@ -1023,8 +1060,8 @@ public SyncSpecification objectMapper(ObjectMapper objectMapper) {
 		 */
 		public McpSyncServer build() {
 			McpServerFeatures.Sync syncFeatures = new McpServerFeatures.Sync(this.serverInfo, this.serverCapabilities,
-					this.tools, this.resources, this.resourceTemplates, this.prompts, this.rootsChangeHandlers,
-					this.instructions);
+					this.tools, this.resources, this.resourceTemplates, this.prompts, this.completions,
+					this.rootsChangeHandlers, this.instructions);
 			McpServerFeatures.Async asyncFeatures = McpServerFeatures.Async.fromSync(syncFeatures);
 			var mapper = this.objectMapper != null ? this.objectMapper : new ObjectMapper();
 			var asyncServer = new McpAsyncServer(this.transportProvider, mapper, asyncFeatures, this.requestTimeout);