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();
+
+ String argumentName = request.argument().name();
+
+ // check if the referenced resource exists
+ if (type.equals("ref/prompt") && request.ref() instanceof McpSchema.PromptReference promptReference) {
+ McpServerFeatures.AsyncPromptSpecification promptSpec = this.prompts.get(promptReference.name());
+ if (promptSpec == null) {
+ return Mono.error(new McpError("Prompt not found: " + promptReference.name()));
+ }
+ if (!promptSpec.prompt()
+ .arguments()
+ .stream()
+ .filter(arg -> arg.name().equals(argumentName))
+ .findFirst()
+ .isPresent()) {
+
+ return Mono.error(new McpError("Argument not found: " + argumentName));
+ }
+ }
+
+ if (type.equals("ref/resource") && request.ref() instanceof McpSchema.ResourceReference resourceReference) {
+ McpServerFeatures.AsyncResourceSpecification resourceSpec = this.resources.get(resourceReference.uri());
+ if (resourceSpec == null) {
+ return Mono.error(new McpError("Resource not found: " + resourceReference.uri()));
+ }
+ if (!uriTemplateManagerFactory.create(resourceSpec.resource().uri())
+ .getVariableNames()
+ .contains(argumentName)) {
+ return Mono.error(new McpError("Argument not found: " + argumentName));
+ }
+
+ }
+
+ 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);
+ };
+ }
/**
- * Create a new message using the sampling capabilities of the client. The Model
- * Context Protocol (MCP) provides a standardized way for servers to request LLM
- * sampling (“completions” or “generations”) from language models via clients. This
- * flow allows clients to maintain control over model access, selection, and
- * permissions while enabling servers to leverage AI capabilities—with no server API
- * keys necessary. Servers can request text or image-based interactions and optionally
- * include context from MCP servers in their prompts.
- * @param createMessageRequest The request to create a new message
- * @return A Mono that completes when the message has been created
- * @throws McpError if the client has not been initialized or does not support
- * sampling capabilities
- * @throws McpError if the client does not support the createMessage method
- * @see McpSchema.CreateMessageRequest
- * @see McpSchema.CreateMessageResult
- * @see Sampling
- * Specification
+ * Parses the raw JSON-RPC request parameters into a {@link McpSchema.CompleteRequest}
+ * object.
+ *
+ * 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.
*/
- public Mono createMessage(McpSchema.CreateMessageRequest createMessageRequest) {
+ @SuppressWarnings("unchecked")
+ private McpSchema.CompleteRequest parseCompletionParams(Object object) {
+ Map params = (Map) object;
+ Map refMap = (Map) params.get("ref");
+ Map argMap = (Map) 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);
+ };
- if (this.clientCapabilities == null) {
- return Mono.error(new McpError("Client must be initialized. Call the initialize method first!"));
- }
- if (this.clientCapabilities.sampling() == null) {
- return Mono.error(new McpError("Client must be configured with sampling capabilities"));
- }
- return this.mcpSession.sendRequest(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE, createMessageRequest,
- CREATE_MESSAGE_RESULT_TYPE_REF);
+ 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);
}
/**
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
new file mode 100644
index 00000000..889dc66d
--- /dev/null
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpAsyncServerExchange.java
@@ -0,0 +1,148 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+
+package io.modelcontextprotocol.server;
+
+import com.fasterxml.jackson.core.type.TypeReference;
+import io.modelcontextprotocol.spec.McpError;
+import io.modelcontextprotocol.spec.McpSchema;
+import io.modelcontextprotocol.spec.McpSchema.LoggingLevel;
+import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
+import io.modelcontextprotocol.spec.McpServerSession;
+import io.modelcontextprotocol.util.Assert;
+import reactor.core.publisher.Mono;
+
+/**
+ * Represents an asynchronous exchange with a Model Context Protocol (MCP) client. The
+ * exchange provides methods to interact with the client and query its capabilities.
+ *
+ * @author Dariusz Jędrzejczyk
+ * @author Christian Tzolov
+ */
+public class McpAsyncServerExchange {
+
+ private final McpServerSession session;
+
+ private final McpSchema.ClientCapabilities clientCapabilities;
+
+ private final McpSchema.Implementation clientInfo;
+
+ private volatile LoggingLevel minLoggingLevel = LoggingLevel.INFO;
+
+ private static final TypeReference CREATE_MESSAGE_RESULT_TYPE_REF = new TypeReference<>() {
+ };
+
+ private static final TypeReference LIST_ROOTS_RESULT_TYPE_REF = new TypeReference<>() {
+ };
+
+ /**
+ * Create a new asynchronous exchange with the client.
+ * @param session The server session representing a 1-1 interaction.
+ * @param clientCapabilities The client capabilities that define the supported
+ * features and functionality.
+ * @param clientInfo The client implementation information.
+ */
+ public McpAsyncServerExchange(McpServerSession session, McpSchema.ClientCapabilities clientCapabilities,
+ McpSchema.Implementation clientInfo) {
+ this.session = session;
+ this.clientCapabilities = clientCapabilities;
+ this.clientInfo = clientInfo;
+ }
+
+ /**
+ * Get the client capabilities that define the supported features and functionality.
+ * @return The client capabilities
+ */
+ public McpSchema.ClientCapabilities getClientCapabilities() {
+ return this.clientCapabilities;
+ }
+
+ /**
+ * Get the client implementation information.
+ * @return The client implementation details
+ */
+ public McpSchema.Implementation getClientInfo() {
+ return this.clientInfo;
+ }
+
+ /**
+ * Create a new message using the sampling capabilities of the client. The Model
+ * Context Protocol (MCP) provides a standardized way for servers to request LLM
+ * sampling (“completions” or “generations”) from language models via clients. This
+ * flow allows clients to maintain control over model access, selection, and
+ * permissions while enabling servers to leverage AI capabilities—with no server API
+ * keys necessary. Servers can request text or image-based interactions and optionally
+ * include context from MCP servers in their prompts.
+ * @param createMessageRequest The request to create a new message
+ * @return A Mono that completes when the message has been created
+ * @see McpSchema.CreateMessageRequest
+ * @see McpSchema.CreateMessageResult
+ * @see Sampling
+ * Specification
+ */
+ public Mono createMessage(McpSchema.CreateMessageRequest createMessageRequest) {
+ if (this.clientCapabilities == null) {
+ return Mono.error(new McpError("Client must be initialized. Call the initialize method first!"));
+ }
+ if (this.clientCapabilities.sampling() == null) {
+ return Mono.error(new McpError("Client must be configured with sampling capabilities"));
+ }
+ return this.session.sendRequest(McpSchema.METHOD_SAMPLING_CREATE_MESSAGE, createMessageRequest,
+ CREATE_MESSAGE_RESULT_TYPE_REF);
+ }
+
+ /**
+ * Retrieves the list of all roots provided by the client.
+ * @return A Mono that emits the list of roots result.
+ */
+ public Mono listRoots() {
+ return this.listRoots(null);
+ }
+
+ /**
+ * Retrieves a paginated list of roots provided by the client.
+ * @param cursor Optional pagination cursor from a previous list request
+ * @return A Mono that emits the list of roots result containing
+ */
+ public Mono listRoots(String cursor) {
+ return this.session.sendRequest(McpSchema.METHOD_ROOTS_LIST, new McpSchema.PaginatedRequest(cursor),
+ LIST_ROOTS_RESULT_TYPE_REF);
+ }
+
+ /**
+ * Send a logging message notification to all connected clients. Messages below the
+ * current minimum logging level will be filtered out.
+ * @param loggingMessageNotification The logging message to send
+ * @return A Mono that completes when the notification has been sent
+ */
+ public Mono loggingNotification(LoggingMessageNotification loggingMessageNotification) {
+
+ if (loggingMessageNotification == null) {
+ return Mono.error(new McpError("Logging message must not be null"));
+ }
+
+ return Mono.defer(() -> {
+ if (this.isNotificationForLevelAllowed(loggingMessageNotification.level())) {
+ return this.session.sendNotification(McpSchema.METHOD_NOTIFICATION_MESSAGE, loggingMessageNotification);
+ }
+ return Mono.empty();
+ });
+ }
+
+ /**
+ * Set the minimum logging level for the client. Messages below this level will be
+ * filtered out.
+ * @param minLoggingLevel The minimum logging level
+ */
+ void setMinLoggingLevel(LoggingLevel minLoggingLevel) {
+ Assert.notNull(minLoggingLevel, "minLoggingLevel must not be null");
+ this.minLoggingLevel = minLoggingLevel;
+ }
+
+ private boolean isNotificationForLevelAllowed(LoggingLevel loggingLevel) {
+ return loggingLevel.level() >= this.minLoggingLevel.level();
+ }
+
+}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
index 54c7a28f..d6ec2cc3 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServer.java
@@ -4,19 +4,23 @@
package io.modelcontextprotocol.server;
+import java.time.Duration;
import java.util.ArrayList;
+import java.util.Arrays;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
-import java.util.function.Consumer;
-import java.util.function.Function;
+import java.util.function.BiConsumer;
+import java.util.function.BiFunction;
+import com.fasterxml.jackson.databind.ObjectMapper;
import io.modelcontextprotocol.spec.McpSchema;
-import io.modelcontextprotocol.spec.McpTransport;
-import io.modelcontextprotocol.spec.ServerMcpTransport;
import io.modelcontextprotocol.spec.McpSchema.CallToolResult;
import io.modelcontextprotocol.spec.McpSchema.ResourceTemplate;
+import io.modelcontextprotocol.spec.McpServerTransportProvider;
import io.modelcontextprotocol.util.Assert;
+import io.modelcontextprotocol.util.DeafaultMcpUriTemplateManagerFactory;
+import io.modelcontextprotocol.util.McpUriTemplateManagerFactory;
import reactor.core.publisher.Mono;
/**
@@ -49,45 +53,50 @@
*
* The class provides factory methods to create either:
*
- * - {@link McpAsyncServer} for non-blocking operations with CompletableFuture responses
+ *
- {@link McpAsyncServer} for non-blocking operations with reactive responses
*
- {@link McpSyncServer} for blocking operations with direct responses
*
*
*
* Example of creating a basic synchronous server:
{@code
- * McpServer.sync(transport)
+ * McpServer.sync(transportProvider)
* .serverInfo("my-server", "1.0.0")
* .tool(new Tool("calculator", "Performs calculations", schema),
- * args -> new CallToolResult("Result: " + calculate(args)))
+ * (exchange, args) -> new CallToolResult("Result: " + calculate(args)))
* .build();
* }
*
* Example of creating a basic asynchronous server: {@code
- * McpServer.async(transport)
+ * McpServer.async(transportProvider)
* .serverInfo("my-server", "1.0.0")
* .tool(new Tool("calculator", "Performs calculations", schema),
- * args -> Mono.just(new CallToolResult("Result: " + calculate(args))))
+ * (exchange, args) -> Mono.fromSupplier(() -> calculate(args))
+ * .map(result -> new CallToolResult("Result: " + result)))
* .build();
* }
*
*
* Example with comprehensive asynchronous configuration:
{@code
- * McpServer.async(transport)
+ * McpServer.async(transportProvider)
* .serverInfo("advanced-server", "2.0.0")
* .capabilities(new ServerCapabilities(...))
* // Register tools
* .tools(
- * new McpServerFeatures.AsyncToolRegistration(calculatorTool,
- * args -> Mono.just(new CallToolResult("Result: " + calculate(args)))),
- * new McpServerFeatures.AsyncToolRegistration(weatherTool,
- * args -> Mono.just(new CallToolResult("Weather: " + getWeather(args))))
+ * new McpServerFeatures.AsyncToolSpecification(calculatorTool,
+ * (exchange, args) -> Mono.fromSupplier(() -> calculate(args))
+ * .map(result -> new CallToolResult("Result: " + result))),
+ * new McpServerFeatures.AsyncToolSpecification(weatherTool,
+ * (exchange, args) -> Mono.fromSupplier(() -> getWeather(args))
+ * .map(result -> new CallToolResult("Weather: " + result)))
* )
* // Register resources
* .resources(
- * new McpServerFeatures.AsyncResourceRegistration(fileResource,
- * req -> Mono.just(new ReadResourceResult(readFile(req)))),
- * new McpServerFeatures.AsyncResourceRegistration(dbResource,
- * req -> Mono.just(new ReadResourceResult(queryDb(req))))
+ * new McpServerFeatures.AsyncResourceSpecification(fileResource,
+ * (exchange, req) -> Mono.fromSupplier(() -> readFile(req))
+ * .map(ReadResourceResult::new)),
+ * new McpServerFeatures.AsyncResourceSpecification(dbResource,
+ * (exchange, req) -> Mono.fromSupplier(() -> queryDb(req))
+ * .map(ReadResourceResult::new))
* )
* // Add resource templates
* .resourceTemplates(
@@ -96,60 +105,69 @@
* )
* // Register prompts
* .prompts(
- * new McpServerFeatures.AsyncPromptRegistration(analysisPrompt,
- * req -> Mono.just(new GetPromptResult(generateAnalysisPrompt(req)))),
+ * new McpServerFeatures.AsyncPromptSpecification(analysisPrompt,
+ * (exchange, req) -> Mono.fromSupplier(() -> generateAnalysisPrompt(req))
+ * .map(GetPromptResult::new)),
* new McpServerFeatures.AsyncPromptRegistration(summaryPrompt,
- * req -> Mono.just(new GetPromptResult(generateSummaryPrompt(req))))
+ * (exchange, req) -> Mono.fromSupplier(() -> generateSummaryPrompt(req))
+ * .map(GetPromptResult::new))
* )
* .build();
* }
*
* @author Christian Tzolov
* @author Dariusz Jędrzejczyk
+ * @author Jihoon Kim
* @see McpAsyncServer
* @see McpSyncServer
- * @see McpTransport
+ * @see McpServerTransportProvider
*/
public interface McpServer {
/**
* Starts building a synchronous MCP server that provides blocking operations.
- * Synchronous servers process each request to completion before handling the next
- * one, making them simpler to implement but potentially less performant for
- * concurrent operations.
- * @param transport The transport layer implementation for MCP communication
- * @return A new instance of {@link SyncSpec} for configuring the server.
+ * Synchronous servers block the current Thread's execution upon each request before
+ * giving the control back to the caller, making them simpler to implement but
+ * potentially less scalable for concurrent operations.
+ * @param transportProvider The transport layer implementation for MCP communication.
+ * @return A new instance of {@link SyncSpecification} for configuring the server.
*/
- static SyncSpec sync(ServerMcpTransport transport) {
- return new SyncSpec(transport);
+ static SyncSpecification sync(McpServerTransportProvider transportProvider) {
+ return new SyncSpecification(transportProvider);
}
/**
- * Starts building an asynchronous MCP server that provides blocking operations.
- * Asynchronous servers can handle multiple requests concurrently using a functional
- * paradigm with non-blocking server transports, making them more efficient for
- * high-concurrency scenarios but more complex to implement.
- * @param transport The transport layer implementation for MCP communication
- * @return A new instance of {@link SyncSpec} for configuring the server.
+ * Starts building an asynchronous MCP server that provides non-blocking operations.
+ * Asynchronous servers can handle multiple requests concurrently on a single Thread
+ * using a functional paradigm with non-blocking server transports, making them more
+ * scalable for high-concurrency scenarios but more complex to implement.
+ * @param transportProvider The transport layer implementation for MCP communication.
+ * @return A new instance of {@link AsyncSpecification} for configuring the server.
*/
- static AsyncSpec async(ServerMcpTransport transport) {
- return new AsyncSpec(transport);
+ static AsyncSpecification async(McpServerTransportProvider transportProvider) {
+ return new AsyncSpecification(transportProvider);
}
/**
* Asynchronous server specification.
*/
- class AsyncSpec {
+ class AsyncSpecification {
private static final McpSchema.Implementation DEFAULT_SERVER_INFO = new McpSchema.Implementation("mcp-server",
"1.0.0");
- private final ServerMcpTransport transport;
+ private final McpServerTransportProvider transportProvider;
+
+ private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+
+ private ObjectMapper objectMapper;
private McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
private McpSchema.ServerCapabilities serverCapabilities;
+ private String instructions;
+
/**
* The Model Context Protocol (MCP) allows servers to expose tools that can be
* invoked by language models. Tools enable models to interact with external
@@ -157,7 +175,7 @@ class AsyncSpec {
* Each tool is uniquely identified by a name and includes metadata describing its
* schema.
*/
- private final List tools = new ArrayList<>();
+ private final List tools = new ArrayList<>();
/**
* The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -166,7 +184,7 @@ class AsyncSpec {
* application-specific information. Each resource is uniquely identified by a
* URI.
*/
- private final Map resources = new HashMap<>();
+ private final Map resources = new HashMap<>();
private final List resourceTemplates = new ArrayList<>();
@@ -177,13 +195,45 @@ class AsyncSpec {
* discover available prompts, retrieve their contents, and provide arguments to
* customize them.
*/
- private final Map prompts = new HashMap<>();
+ private final Map prompts = new HashMap<>();
+
+ private final Map completions = new HashMap<>();
+
+ private final List, Mono>> rootsChangeHandlers = new ArrayList<>();
+
+ private Duration requestTimeout = Duration.ofSeconds(10); // Default timeout
- private final List, Mono>> rootsChangeConsumers = new ArrayList<>();
+ private AsyncSpecification(McpServerTransportProvider transportProvider) {
+ Assert.notNull(transportProvider, "Transport provider must not be null");
+ this.transportProvider = transportProvider;
+ }
+
+ /**
+ * Sets the URI template manager factory to use for creating URI templates. This
+ * allows for custom URI template parsing and variable extraction.
+ * @param uriTemplateManagerFactory The factory to use. Must not be null.
+ * @return This builder instance for method chaining
+ * @throws IllegalArgumentException if uriTemplateManagerFactory is null
+ */
+ public AsyncSpecification uriTemplateManagerFactory(McpUriTemplateManagerFactory uriTemplateManagerFactory) {
+ Assert.notNull(uriTemplateManagerFactory, "URI template manager factory must not be null");
+ this.uriTemplateManagerFactory = uriTemplateManagerFactory;
+ return this;
+ }
- private AsyncSpec(ServerMcpTransport transport) {
- Assert.notNull(transport, "Transport must not be null");
- this.transport = transport;
+ /**
+ * Sets the duration to wait for server responses before timing out requests. This
+ * timeout applies to all requests made through the client, including tool calls,
+ * resource access, and prompt operations.
+ * @param requestTimeout The duration to wait before timing out requests. Must not
+ * be null.
+ * @return This builder instance for method chaining
+ * @throws IllegalArgumentException if requestTimeout is null
+ */
+ public AsyncSpecification requestTimeout(Duration requestTimeout) {
+ Assert.notNull(requestTimeout, "Request timeout must not be null");
+ this.requestTimeout = requestTimeout;
+ return this;
}
/**
@@ -195,7 +245,7 @@ private AsyncSpec(ServerMcpTransport transport) {
* @return This builder instance for method chaining
* @throws IllegalArgumentException if serverInfo is null
*/
- public AsyncSpec serverInfo(McpSchema.Implementation serverInfo) {
+ public AsyncSpecification serverInfo(McpSchema.Implementation serverInfo) {
Assert.notNull(serverInfo, "Server info must not be null");
this.serverInfo = serverInfo;
return this;
@@ -211,13 +261,25 @@ public AsyncSpec serverInfo(McpSchema.Implementation serverInfo) {
* @throws IllegalArgumentException if name or version is null or empty
* @see #serverInfo(McpSchema.Implementation)
*/
- public AsyncSpec serverInfo(String name, String version) {
+ public AsyncSpecification serverInfo(String name, String version) {
Assert.hasText(name, "Name must not be null or empty");
Assert.hasText(version, "Version must not be null or empty");
this.serverInfo = new McpSchema.Implementation(name, version);
return this;
}
+ /**
+ * Sets the server instructions that will be shared with clients during connection
+ * initialization. These instructions provide guidance to the client on how to
+ * interact with this server.
+ * @param instructions The instructions text. Can be null or empty.
+ * @return This builder instance for method chaining
+ */
+ public AsyncSpecification instructions(String instructions) {
+ this.instructions = instructions;
+ return this;
+ }
+
/**
* Sets the server capabilities that will be advertised to clients during
* connection initialization. Capabilities define what features the server
@@ -226,15 +288,14 @@ public AsyncSpec serverInfo(String name, String version) {
* Tool execution
* Resource access
* Prompt handling
- * Streaming responses
- * Batch operations
*
* @param serverCapabilities The server capabilities configuration. Must not be
* null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if serverCapabilities is null
*/
- public AsyncSpec capabilities(McpSchema.ServerCapabilities serverCapabilities) {
+ public AsyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabilities) {
+ Assert.notNull(serverCapabilities, "Server capabilities must not be null");
this.serverCapabilities = serverCapabilities;
return this;
}
@@ -242,26 +303,31 @@ public AsyncSpec capabilities(McpSchema.ServerCapabilities serverCapabilities) {
/**
* Adds a single tool with its implementation handler to the server. This is a
* convenience method for registering individual tools without creating a
- * {@link McpServerFeatures.AsyncToolRegistration} explicitly.
+ * {@link McpServerFeatures.AsyncToolSpecification} explicitly.
*
*
* Example usage:
{@code
* .tool(
* new Tool("calculator", "Performs calculations", schema),
- * args -> Mono.just(new CallToolResult("Result: " + calculate(args)))
+ * (exchange, args) -> Mono.fromSupplier(() -> calculate(args))
+ * .map(result -> new CallToolResult("Result: " + result))
* )
* }
* @param tool The tool definition including name, description, and schema. Must
* not be null.
* @param handler The function that implements the tool's logic. Must not be null.
+ * The function's first argument is an {@link McpAsyncServerExchange} upon which
+ * the server can interact with the connected client. The second argument is the
+ * map of arguments passed to the tool.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if tool or handler is null
*/
- public AsyncSpec tool(McpSchema.Tool tool, Function, Mono> handler) {
+ public AsyncSpecification tool(McpSchema.Tool tool,
+ BiFunction, Mono> handler) {
Assert.notNull(tool, "Tool must not be null");
Assert.notNull(handler, "Handler must not be null");
- this.tools.add(new McpServerFeatures.AsyncToolRegistration(tool, handler));
+ this.tools.add(new McpServerFeatures.AsyncToolSpecification(tool, handler));
return this;
}
@@ -270,15 +336,15 @@ public AsyncSpec tool(McpSchema.Tool tool, Function, Mono toolRegistrations) {
- Assert.notNull(toolRegistrations, "Tool handlers list must not be null");
- this.tools.addAll(toolRegistrations);
+ public AsyncSpecification tools(List toolSpecifications) {
+ Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
+ this.tools.addAll(toolSpecifications);
return this;
}
@@ -289,18 +355,19 @@ public AsyncSpec tools(List toolRegistr
*
* Example usage:
{@code
* .tools(
- * new McpServerFeatures.AsyncToolRegistration(calculatorTool, calculatorHandler),
- * new McpServerFeatures.AsyncToolRegistration(weatherTool, weatherHandler),
- * new McpServerFeatures.AsyncToolRegistration(fileManagerTool, fileManagerHandler)
+ * new McpServerFeatures.AsyncToolSpecification(calculatorTool, calculatorHandler),
+ * new McpServerFeatures.AsyncToolSpecification(weatherTool, weatherHandler),
+ * new McpServerFeatures.AsyncToolSpecification(fileManagerTool, fileManagerHandler)
* )
* }
- * @param toolRegistrations The tool registrations to add. Must not be null.
+ * @param toolSpecifications The tool specifications to add. Must not be null.
* @return This builder instance for method chaining
- * @throws IllegalArgumentException if toolRegistrations is null
+ * @throws IllegalArgumentException if toolSpecifications is null
* @see #tools(List)
*/
- public AsyncSpec tools(McpServerFeatures.AsyncToolRegistration... toolRegistrations) {
- for (McpServerFeatures.AsyncToolRegistration tool : toolRegistrations) {
+ public AsyncSpecification tools(McpServerFeatures.AsyncToolSpecification... toolSpecifications) {
+ Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
+ for (McpServerFeatures.AsyncToolSpecification tool : toolSpecifications) {
this.tools.add(tool);
}
return this;
@@ -310,29 +377,31 @@ public AsyncSpec tools(McpServerFeatures.AsyncToolRegistration... toolRegistrati
* Registers multiple resources with their handlers using a Map. This method is
* useful when resources are dynamically generated or loaded from a configuration
* source.
- * @param resourceRegsitrations Map of resource name to registration. Must not be
- * null.
+ * @param resourceSpecifications Map of resource name to specification. Must not
+ * be null.
* @return This builder instance for method chaining
- * @throws IllegalArgumentException if resourceRegsitrations is null
- * @see #resources(McpServerFeatures.AsyncResourceRegistration...)
+ * @throws IllegalArgumentException if resourceSpecifications is null
+ * @see #resources(McpServerFeatures.AsyncResourceSpecification...)
*/
- public AsyncSpec resources(Map resourceRegsitrations) {
- Assert.notNull(resourceRegsitrations, "Resource handlers map must not be null");
- this.resources.putAll(resourceRegsitrations);
+ public AsyncSpecification resources(
+ Map resourceSpecifications) {
+ Assert.notNull(resourceSpecifications, "Resource handlers map must not be null");
+ this.resources.putAll(resourceSpecifications);
return this;
}
/**
* Registers multiple resources with their handlers using a List. This method is
* useful when resources need to be added in bulk from a collection.
- * @param resourceRegsitrations List of resource registrations. Must not be null.
+ * @param resourceSpecifications List of resource specifications. Must not be
+ * null.
* @return This builder instance for method chaining
- * @throws IllegalArgumentException if resourceRegsitrations is null
- * @see #resources(McpServerFeatures.AsyncResourceRegistration...)
+ * @throws IllegalArgumentException if resourceSpecifications is null
+ * @see #resources(McpServerFeatures.AsyncResourceSpecification...)
*/
- public AsyncSpec resources(List resourceRegsitrations) {
- Assert.notNull(resourceRegsitrations, "Resource handlers list must not be null");
- for (McpServerFeatures.AsyncResourceRegistration resource : resourceRegsitrations) {
+ public AsyncSpecification resources(List resourceSpecifications) {
+ Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
+ for (McpServerFeatures.AsyncResourceSpecification resource : resourceSpecifications) {
this.resources.put(resource.resource().uri(), resource);
}
return this;
@@ -345,19 +414,19 @@ public AsyncSpec resources(List res
*
* Example usage:
{@code
* .resources(
- * new McpServerFeatures.AsyncResourceRegistration(fileResource, fileHandler),
- * new McpServerFeatures.AsyncResourceRegistration(dbResource, dbHandler),
- * new McpServerFeatures.AsyncResourceRegistration(apiResource, apiHandler)
+ * new McpServerFeatures.AsyncResourceSpecification(fileResource, fileHandler),
+ * new McpServerFeatures.AsyncResourceSpecification(dbResource, dbHandler),
+ * new McpServerFeatures.AsyncResourceSpecification(apiResource, apiHandler)
* )
* }
- * @param resourceRegistrations The resource registrations to add. Must not be
+ * @param resourceSpecifications The resource specifications to add. Must not be
* null.
* @return This builder instance for method chaining
- * @throws IllegalArgumentException if resourceRegistrations is null
+ * @throws IllegalArgumentException if resourceSpecifications is null
*/
- public AsyncSpec resources(McpServerFeatures.AsyncResourceRegistration... resourceRegistrations) {
- Assert.notNull(resourceRegistrations, "Resource handlers list must not be null");
- for (McpServerFeatures.AsyncResourceRegistration resource : resourceRegistrations) {
+ public AsyncSpecification resources(McpServerFeatures.AsyncResourceSpecification... resourceSpecifications) {
+ Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
+ for (McpServerFeatures.AsyncResourceSpecification resource : resourceSpecifications) {
this.resources.put(resource.resource().uri(), resource);
}
return this;
@@ -377,9 +446,11 @@ public AsyncSpec resources(McpServerFeatures.AsyncResourceRegistration... resour
* @param resourceTemplates List of resource templates. If null, clears existing
* templates.
* @return This builder instance for method chaining
+ * @throws IllegalArgumentException if resourceTemplates is null.
* @see #resourceTemplates(ResourceTemplate...)
*/
- public AsyncSpec resourceTemplates(List resourceTemplates) {
+ public AsyncSpecification resourceTemplates(List resourceTemplates) {
+ Assert.notNull(resourceTemplates, "Resource templates must not be null");
this.resourceTemplates.addAll(resourceTemplates);
return this;
}
@@ -389,9 +460,11 @@ public AsyncSpec resourceTemplates(List resourceTemplates) {
* alternative to {@link #resourceTemplates(List)}.
* @param resourceTemplates The resource templates to set.
* @return This builder instance for method chaining
+ * @throws IllegalArgumentException if resourceTemplates is null.
* @see #resourceTemplates(List)
*/
- public AsyncSpec resourceTemplates(ResourceTemplate... resourceTemplates) {
+ public AsyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+ Assert.notNull(resourceTemplates, "Resource templates must not be null");
for (ResourceTemplate resourceTemplate : resourceTemplates) {
this.resourceTemplates.add(resourceTemplate);
}
@@ -405,16 +478,18 @@ public AsyncSpec resourceTemplates(ResourceTemplate... resourceTemplates) {
*
*
* Example usage:
{@code
- * .prompts(Map.of("analysis", new McpServerFeatures.AsyncPromptRegistration(
+ * .prompts(Map.of("analysis", new McpServerFeatures.AsyncPromptSpecification(
* new Prompt("analysis", "Code analysis template"),
- * request -> Mono.just(new GetPromptResult(generateAnalysisPrompt(request)))
+ * request -> Mono.fromSupplier(() -> generateAnalysisPrompt(request))
+ * .map(GetPromptResult::new)
* )));
* }
- * @param prompts Map of prompt name to registration. Must not be null.
+ * @param prompts Map of prompt name to specification. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null
*/
- public AsyncSpec prompts(Map prompts) {
+ public AsyncSpecification prompts(Map prompts) {
+ Assert.notNull(prompts, "Prompts map must not be null");
this.prompts.putAll(prompts);
return this;
}
@@ -422,13 +497,14 @@ public AsyncSpec prompts(Map
/**
* Registers multiple prompts with their handlers using a List. This method is
* useful when prompts need to be added in bulk from a collection.
- * @param prompts List of prompt registrations. Must not be null.
+ * @param prompts List of prompt specifications. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null
- * @see #prompts(McpServerFeatures.AsyncPromptRegistration...)
+ * @see #prompts(McpServerFeatures.AsyncPromptSpecification...)
*/
- public AsyncSpec prompts(List prompts) {
- for (McpServerFeatures.AsyncPromptRegistration prompt : prompts) {
+ public AsyncSpecification prompts(List prompts) {
+ Assert.notNull(prompts, "Prompts list must not be null");
+ for (McpServerFeatures.AsyncPromptSpecification prompt : prompts) {
this.prompts.put(prompt.prompt().name(), prompt);
}
return this;
@@ -441,33 +517,67 @@ public AsyncSpec prompts(List prompts
*
* Example usage:
{@code
* .prompts(
- * new McpServerFeatures.AsyncPromptRegistration(analysisPrompt, analysisHandler),
- * new McpServerFeatures.AsyncPromptRegistration(summaryPrompt, summaryHandler),
- * new McpServerFeatures.AsyncPromptRegistration(reviewPrompt, reviewHandler)
+ * new McpServerFeatures.AsyncPromptSpecification(analysisPrompt, analysisHandler),
+ * new McpServerFeatures.AsyncPromptSpecification(summaryPrompt, summaryHandler),
+ * new McpServerFeatures.AsyncPromptSpecification(reviewPrompt, reviewHandler)
* )
* }
- * @param prompts The prompt registrations to add. Must not be null.
+ * @param prompts The prompt specifications to add. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null
*/
- public AsyncSpec prompts(McpServerFeatures.AsyncPromptRegistration... prompts) {
- for (McpServerFeatures.AsyncPromptRegistration prompt : prompts) {
+ public AsyncSpecification prompts(McpServerFeatures.AsyncPromptSpecification... prompts) {
+ Assert.notNull(prompts, "Prompts list must not be null");
+ for (McpServerFeatures.AsyncPromptSpecification prompt : prompts) {
this.prompts.put(prompt.prompt().name(), prompt);
}
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
+ */
+ public AsyncSpecification completions(List completions) {
+ Assert.notNull(completions, "Completions list must not be null");
+ for (McpServerFeatures.AsyncCompletionSpecification 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 AsyncSpecification completions(McpServerFeatures.AsyncCompletionSpecification... completions) {
+ Assert.notNull(completions, "Completions list must not be null");
+ for (McpServerFeatures.AsyncCompletionSpecification 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
* files are added or removed.
- * @param consumer The consumer to register. Must not be null.
+ * @param handler The handler to register. Must not be null. The function's first
+ * argument is an {@link McpAsyncServerExchange} upon which the server can
+ * interact with the connected client. The second argument is the list of roots.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if consumer is null
*/
- public AsyncSpec rootsChangeConsumer(Function, Mono> consumer) {
- Assert.notNull(consumer, "Consumer must not be null");
- this.rootsChangeConsumers.add(consumer);
+ public AsyncSpecification rootsChangeHandler(
+ BiFunction, Mono> handler) {
+ Assert.notNull(handler, "Consumer must not be null");
+ this.rootsChangeHandlers.add(handler);
return this;
}
@@ -475,13 +585,15 @@ public AsyncSpec rootsChangeConsumer(Function, Mono>
* Registers multiple consumers that will be notified when the list of roots
* changes. This method is useful when multiple consumers need to be registered at
* once.
- * @param consumers The list of consumers to register. Must not be null.
+ * @param handlers The list of handlers to register. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if consumers is null
+ * @see #rootsChangeHandler(BiFunction)
*/
- public AsyncSpec rootsChangeConsumers(List, Mono>> consumers) {
- Assert.notNull(consumers, "Consumers list must not be null");
- this.rootsChangeConsumers.addAll(consumers);
+ public AsyncSpecification rootsChangeHandlers(
+ List, Mono>> handlers) {
+ Assert.notNull(handlers, "Handlers list must not be null");
+ this.rootsChangeHandlers.addAll(handlers);
return this;
}
@@ -489,27 +601,41 @@ public AsyncSpec rootsChangeConsumers(List, Mono, Mono>... consumers) {
- for (Function, Mono> consumer : consumers) {
- this.rootsChangeConsumers.add(consumer);
- }
+ public AsyncSpecification rootsChangeHandlers(
+ @SuppressWarnings("unchecked") BiFunction, Mono>... handlers) {
+ Assert.notNull(handlers, "Handlers list must not be null");
+ return this.rootsChangeHandlers(Arrays.asList(handlers));
+ }
+
+ /**
+ * Sets the object mapper to use for serializing and deserializing JSON messages.
+ * @param objectMapper the instance to use. Must not be null.
+ * @return This builder instance for method chaining.
+ * @throws IllegalArgumentException if objectMapper is null
+ */
+ public AsyncSpecification objectMapper(ObjectMapper objectMapper) {
+ Assert.notNull(objectMapper, "ObjectMapper must not be null");
+ this.objectMapper = objectMapper;
return this;
}
/**
* Builds an asynchronous MCP server that provides non-blocking operations.
* @return A new instance of {@link McpAsyncServer} configured with this builder's
- * settings
+ * settings.
*/
public McpAsyncServer build() {
- return new McpAsyncServer(this.transport,
- new McpServerFeatures.Async(this.serverInfo, this.serverCapabilities, this.tools, this.resources,
- this.resourceTemplates, this.prompts, this.rootsChangeConsumers));
+ var features = new McpServerFeatures.Async(this.serverInfo, this.serverCapabilities, this.tools,
+ 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,
+ this.uriTemplateManagerFactory);
}
}
@@ -517,17 +643,23 @@ public McpAsyncServer build() {
/**
* Synchronous server specification.
*/
- class SyncSpec {
+ class SyncSpecification {
private static final McpSchema.Implementation DEFAULT_SERVER_INFO = new McpSchema.Implementation("mcp-server",
"1.0.0");
- private final ServerMcpTransport transport;
+ private McpUriTemplateManagerFactory uriTemplateManagerFactory = new DeafaultMcpUriTemplateManagerFactory();
+
+ private final McpServerTransportProvider transportProvider;
+
+ private ObjectMapper objectMapper;
private McpSchema.Implementation serverInfo = DEFAULT_SERVER_INFO;
private McpSchema.ServerCapabilities serverCapabilities;
+ private String instructions;
+
/**
* The Model Context Protocol (MCP) allows servers to expose tools that can be
* invoked by language models. Tools enable models to interact with external
@@ -535,7 +667,7 @@ class SyncSpec {
* Each tool is uniquely identified by a name and includes metadata describing its
* schema.
*/
- private final List tools = new ArrayList<>();
+ private final List tools = new ArrayList<>();
/**
* The Model Context Protocol (MCP) provides a standardized way for servers to
@@ -544,7 +676,7 @@ class SyncSpec {
* application-specific information. Each resource is uniquely identified by a
* URI.
*/
- private final Map resources = new HashMap<>();
+ private final Map resources = new HashMap<>();
private final List resourceTemplates = new ArrayList<>();
@@ -555,13 +687,45 @@ class SyncSpec {
* discover available prompts, retrieve their contents, and provide arguments to
* customize them.
*/
- private final Map prompts = new HashMap<>();
+ private final Map prompts = new HashMap<>();
+
+ private final Map completions = new HashMap<>();
+
+ private final List>> rootsChangeHandlers = new ArrayList<>();
+
+ private Duration requestTimeout = Duration.ofSeconds(10); // Default timeout
- private final List>> rootsChangeConsumers = new ArrayList<>();
+ private SyncSpecification(McpServerTransportProvider transportProvider) {
+ Assert.notNull(transportProvider, "Transport provider must not be null");
+ this.transportProvider = transportProvider;
+ }
+
+ /**
+ * Sets the URI template manager factory to use for creating URI templates. This
+ * allows for custom URI template parsing and variable extraction.
+ * @param uriTemplateManagerFactory The factory to use. Must not be null.
+ * @return This builder instance for method chaining
+ * @throws IllegalArgumentException if uriTemplateManagerFactory is null
+ */
+ public SyncSpecification uriTemplateManagerFactory(McpUriTemplateManagerFactory uriTemplateManagerFactory) {
+ Assert.notNull(uriTemplateManagerFactory, "URI template manager factory must not be null");
+ this.uriTemplateManagerFactory = uriTemplateManagerFactory;
+ return this;
+ }
- private SyncSpec(ServerMcpTransport transport) {
- Assert.notNull(transport, "Transport must not be null");
- this.transport = transport;
+ /**
+ * Sets the duration to wait for server responses before timing out requests. This
+ * timeout applies to all requests made through the client, including tool calls,
+ * resource access, and prompt operations.
+ * @param requestTimeout The duration to wait before timing out requests. Must not
+ * be null.
+ * @return This builder instance for method chaining
+ * @throws IllegalArgumentException if requestTimeout is null
+ */
+ public SyncSpecification requestTimeout(Duration requestTimeout) {
+ Assert.notNull(requestTimeout, "Request timeout must not be null");
+ this.requestTimeout = requestTimeout;
+ return this;
}
/**
@@ -573,7 +737,7 @@ private SyncSpec(ServerMcpTransport transport) {
* @return This builder instance for method chaining
* @throws IllegalArgumentException if serverInfo is null
*/
- public SyncSpec serverInfo(McpSchema.Implementation serverInfo) {
+ public SyncSpecification serverInfo(McpSchema.Implementation serverInfo) {
Assert.notNull(serverInfo, "Server info must not be null");
this.serverInfo = serverInfo;
return this;
@@ -589,13 +753,25 @@ public SyncSpec serverInfo(McpSchema.Implementation serverInfo) {
* @throws IllegalArgumentException if name or version is null or empty
* @see #serverInfo(McpSchema.Implementation)
*/
- public SyncSpec serverInfo(String name, String version) {
+ public SyncSpecification serverInfo(String name, String version) {
Assert.hasText(name, "Name must not be null or empty");
Assert.hasText(version, "Version must not be null or empty");
this.serverInfo = new McpSchema.Implementation(name, version);
return this;
}
+ /**
+ * Sets the server instructions that will be shared with clients during connection
+ * initialization. These instructions provide guidance to the client on how to
+ * interact with this server.
+ * @param instructions The instructions text. Can be null or empty.
+ * @return This builder instance for method chaining
+ */
+ public SyncSpecification instructions(String instructions) {
+ this.instructions = instructions;
+ return this;
+ }
+
/**
* Sets the server capabilities that will be advertised to clients during
* connection initialization. Capabilities define what features the server
@@ -604,15 +780,14 @@ public SyncSpec serverInfo(String name, String version) {
* Tool execution
* Resource access
* Prompt handling
- * Streaming responses
- * Batch operations
*
* @param serverCapabilities The server capabilities configuration. Must not be
* null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if serverCapabilities is null
*/
- public SyncSpec capabilities(McpSchema.ServerCapabilities serverCapabilities) {
+ public SyncSpecification capabilities(McpSchema.ServerCapabilities serverCapabilities) {
+ Assert.notNull(serverCapabilities, "Server capabilities must not be null");
this.serverCapabilities = serverCapabilities;
return this;
}
@@ -620,26 +795,30 @@ public SyncSpec capabilities(McpSchema.ServerCapabilities serverCapabilities) {
/**
* Adds a single tool with its implementation handler to the server. This is a
* convenience method for registering individual tools without creating a
- * {@link ToolRegistration} explicitly.
+ * {@link McpServerFeatures.SyncToolSpecification} explicitly.
*
*
* Example usage:
{@code
* .tool(
* new Tool("calculator", "Performs calculations", schema),
- * args -> new CallToolResult("Result: " + calculate(args))
+ * (exchange, args) -> new CallToolResult("Result: " + calculate(args))
* )
* }
* @param tool The tool definition including name, description, and schema. Must
* not be null.
* @param handler The function that implements the tool's logic. Must not be null.
+ * The function's first argument is an {@link McpSyncServerExchange} upon which
+ * the server can interact with the connected client. The second argument is the
+ * list of arguments passed to the tool.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if tool or handler is null
*/
- public SyncSpec tool(McpSchema.Tool tool, Function, McpSchema.CallToolResult> handler) {
+ public SyncSpecification tool(McpSchema.Tool tool,
+ BiFunction, McpSchema.CallToolResult> handler) {
Assert.notNull(tool, "Tool must not be null");
Assert.notNull(handler, "Handler must not be null");
- this.tools.add(new McpServerFeatures.SyncToolRegistration(tool, handler));
+ this.tools.add(new McpServerFeatures.SyncToolSpecification(tool, handler));
return this;
}
@@ -648,15 +827,15 @@ public SyncSpec tool(McpSchema.Tool tool, Function, McpSchem
* Adds multiple tools with their handlers to the server using a List. This method
* is useful when tools are dynamically generated or loaded from a configuration
* source.
- * @param toolRegistrations The list of tool registrations to add. Must not be
+ * @param toolSpecifications The list of tool specifications to add. Must not be
* null.
* @return This builder instance for method chaining
- * @throws IllegalArgumentException if toolRegistrations is null
- * @see #tools(McpServerFeatures.SyncToolRegistration...)
+ * @throws IllegalArgumentException if toolSpecifications is null
+ * @see #tools(McpServerFeatures.SyncToolSpecification...)
*/
- public SyncSpec tools(List toolRegistrations) {
- Assert.notNull(toolRegistrations, "Tool handlers list must not be null");
- this.tools.addAll(toolRegistrations);
+ public SyncSpecification tools(List toolSpecifications) {
+ Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
+ this.tools.addAll(toolSpecifications);
return this;
}
@@ -667,18 +846,19 @@ public SyncSpec tools(List toolRegistrat
*
* Example usage:
{@code
* .tools(
- * new ToolRegistration(calculatorTool, calculatorHandler),
- * new ToolRegistration(weatherTool, weatherHandler),
- * new ToolRegistration(fileManagerTool, fileManagerHandler)
+ * new ToolSpecification(calculatorTool, calculatorHandler),
+ * new ToolSpecification(weatherTool, weatherHandler),
+ * new ToolSpecification(fileManagerTool, fileManagerHandler)
* )
* }
- * @param toolRegistrations The tool registrations to add. Must not be null.
+ * @param toolSpecifications The tool specifications to add. Must not be null.
* @return This builder instance for method chaining
- * @throws IllegalArgumentException if toolRegistrations is null
+ * @throws IllegalArgumentException if toolSpecifications is null
* @see #tools(List)
*/
- public SyncSpec tools(McpServerFeatures.SyncToolRegistration... toolRegistrations) {
- for (McpServerFeatures.SyncToolRegistration tool : toolRegistrations) {
+ public SyncSpecification tools(McpServerFeatures.SyncToolSpecification... toolSpecifications) {
+ Assert.notNull(toolSpecifications, "Tool handlers list must not be null");
+ for (McpServerFeatures.SyncToolSpecification tool : toolSpecifications) {
this.tools.add(tool);
}
return this;
@@ -688,29 +868,31 @@ public SyncSpec tools(McpServerFeatures.SyncToolRegistration... toolRegistration
* Registers multiple resources with their handlers using a Map. This method is
* useful when resources are dynamically generated or loaded from a configuration
* source.
- * @param resourceRegsitrations Map of resource name to registration. Must not be
- * null.
+ * @param resourceSpecifications Map of resource name to specification. Must not
+ * be null.
* @return This builder instance for method chaining
- * @throws IllegalArgumentException if resourceRegsitrations is null
- * @see #resources(McpServerFeatures.SyncResourceRegistration...)
+ * @throws IllegalArgumentException if resourceSpecifications is null
+ * @see #resources(McpServerFeatures.SyncResourceSpecification...)
*/
- public SyncSpec resources(Map resourceRegsitrations) {
- Assert.notNull(resourceRegsitrations, "Resource handlers map must not be null");
- this.resources.putAll(resourceRegsitrations);
+ public SyncSpecification resources(
+ Map resourceSpecifications) {
+ Assert.notNull(resourceSpecifications, "Resource handlers map must not be null");
+ this.resources.putAll(resourceSpecifications);
return this;
}
/**
* Registers multiple resources with their handlers using a List. This method is
* useful when resources need to be added in bulk from a collection.
- * @param resourceRegsitrations List of resource registrations. Must not be null.
+ * @param resourceSpecifications List of resource specifications. Must not be
+ * null.
* @return This builder instance for method chaining
- * @throws IllegalArgumentException if resourceRegsitrations is null
- * @see #resources(McpServerFeatures.SyncResourceRegistration...)
+ * @throws IllegalArgumentException if resourceSpecifications is null
+ * @see #resources(McpServerFeatures.SyncResourceSpecification...)
*/
- public SyncSpec resources(List resourceRegsitrations) {
- Assert.notNull(resourceRegsitrations, "Resource handlers list must not be null");
- for (McpServerFeatures.SyncResourceRegistration resource : resourceRegsitrations) {
+ public SyncSpecification resources(List resourceSpecifications) {
+ Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
+ for (McpServerFeatures.SyncResourceSpecification resource : resourceSpecifications) {
this.resources.put(resource.resource().uri(), resource);
}
return this;
@@ -723,19 +905,19 @@ public SyncSpec resources(List resou
*
* Example usage:
{@code
* .resources(
- * new ResourceRegistration(fileResource, fileHandler),
- * new ResourceRegistration(dbResource, dbHandler),
- * new ResourceRegistration(apiResource, apiHandler)
+ * new ResourceSpecification(fileResource, fileHandler),
+ * new ResourceSpecification(dbResource, dbHandler),
+ * new ResourceSpecification(apiResource, apiHandler)
* )
* }
- * @param resourceRegistrations The resource registrations to add. Must not be
+ * @param resourceSpecifications The resource specifications to add. Must not be
* null.
* @return This builder instance for method chaining
- * @throws IllegalArgumentException if resourceRegistrations is null
+ * @throws IllegalArgumentException if resourceSpecifications is null
*/
- public SyncSpec resources(McpServerFeatures.SyncResourceRegistration... resourceRegistrations) {
- Assert.notNull(resourceRegistrations, "Resource handlers list must not be null");
- for (McpServerFeatures.SyncResourceRegistration resource : resourceRegistrations) {
+ public SyncSpecification resources(McpServerFeatures.SyncResourceSpecification... resourceSpecifications) {
+ Assert.notNull(resourceSpecifications, "Resource handlers list must not be null");
+ for (McpServerFeatures.SyncResourceSpecification resource : resourceSpecifications) {
this.resources.put(resource.resource().uri(), resource);
}
return this;
@@ -755,9 +937,11 @@ public SyncSpec resources(McpServerFeatures.SyncResourceRegistration... resource
* @param resourceTemplates List of resource templates. If null, clears existing
* templates.
* @return This builder instance for method chaining
+ * @throws IllegalArgumentException if resourceTemplates is null.
* @see #resourceTemplates(ResourceTemplate...)
*/
- public SyncSpec resourceTemplates(List resourceTemplates) {
+ public SyncSpecification resourceTemplates(List resourceTemplates) {
+ Assert.notNull(resourceTemplates, "Resource templates must not be null");
this.resourceTemplates.addAll(resourceTemplates);
return this;
}
@@ -767,9 +951,11 @@ public SyncSpec resourceTemplates(List resourceTemplates) {
* alternative to {@link #resourceTemplates(List)}.
* @param resourceTemplates The resource templates to set.
* @return This builder instance for method chaining
+ * @throws IllegalArgumentException if resourceTemplates is null
* @see #resourceTemplates(List)
*/
- public SyncSpec resourceTemplates(ResourceTemplate... resourceTemplates) {
+ public SyncSpecification resourceTemplates(ResourceTemplate... resourceTemplates) {
+ Assert.notNull(resourceTemplates, "Resource templates must not be null");
for (ResourceTemplate resourceTemplate : resourceTemplates) {
this.resourceTemplates.add(resourceTemplate);
}
@@ -783,18 +969,19 @@ public SyncSpec resourceTemplates(ResourceTemplate... resourceTemplates) {
*
*
* Example usage:
{@code
- * Map prompts = new HashMap<>();
- * prompts.put("analysis", new PromptRegistration(
+ * Map prompts = new HashMap<>();
+ * prompts.put("analysis", new PromptSpecification(
* new Prompt("analysis", "Code analysis template"),
- * request -> new GetPromptResult(generateAnalysisPrompt(request))
+ * (exchange, request) -> new GetPromptResult(generateAnalysisPrompt(request))
* ));
* .prompts(prompts)
* }
- * @param prompts Map of prompt name to registration. Must not be null.
+ * @param prompts Map of prompt name to specification. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null
*/
- public SyncSpec prompts(Map prompts) {
+ public SyncSpecification prompts(Map prompts) {
+ Assert.notNull(prompts, "Prompts map must not be null");
this.prompts.putAll(prompts);
return this;
}
@@ -802,13 +989,14 @@ public SyncSpec prompts(Map pr
/**
* Registers multiple prompts with their handlers using a List. This method is
* useful when prompts need to be added in bulk from a collection.
- * @param prompts List of prompt registrations. Must not be null.
+ * @param prompts List of prompt specifications. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null
- * @see #prompts(McpServerFeatures.SyncPromptRegistration...)
+ * @see #prompts(McpServerFeatures.SyncPromptSpecification...)
*/
- public SyncSpec prompts(List prompts) {
- for (McpServerFeatures.SyncPromptRegistration prompt : prompts) {
+ public SyncSpecification prompts(List prompts) {
+ Assert.notNull(prompts, "Prompts list must not be null");
+ for (McpServerFeatures.SyncPromptSpecification prompt : prompts) {
this.prompts.put(prompt.prompt().name(), prompt);
}
return this;
@@ -821,33 +1009,67 @@ public SyncSpec prompts(List prompts)
*
* Example usage:
{@code
* .prompts(
- * new PromptRegistration(analysisPrompt, analysisHandler),
- * new PromptRegistration(summaryPrompt, summaryHandler),
- * new PromptRegistration(reviewPrompt, reviewHandler)
+ * new PromptSpecification(analysisPrompt, analysisHandler),
+ * new PromptSpecification(summaryPrompt, summaryHandler),
+ * new PromptSpecification(reviewPrompt, reviewHandler)
* )
* }
- * @param prompts The prompt registrations to add. Must not be null.
+ * @param prompts The prompt specifications to add. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null
*/
- public SyncSpec prompts(McpServerFeatures.SyncPromptRegistration... prompts) {
- for (McpServerFeatures.SyncPromptRegistration prompt : prompts) {
+ public SyncSpecification prompts(McpServerFeatures.SyncPromptSpecification... prompts) {
+ Assert.notNull(prompts, "Prompts list must not be null");
+ for (McpServerFeatures.SyncPromptSpecification prompt : prompts) {
this.prompts.put(prompt.prompt().name(), prompt);
}
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 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
* files are added or removed.
- * @param consumer The consumer to register. Must not be null.
+ * @param handler The handler to register. Must not be null. The function's first
+ * argument is an {@link McpSyncServerExchange} upon which the server can interact
+ * with the connected client. The second argument is the list of roots.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if consumer is null
*/
- public SyncSpec rootsChangeConsumer(Consumer> consumer) {
- Assert.notNull(consumer, "Consumer must not be null");
- this.rootsChangeConsumers.add(consumer);
+ public SyncSpecification rootsChangeHandler(BiConsumer> handler) {
+ Assert.notNull(handler, "Consumer must not be null");
+ this.rootsChangeHandlers.add(handler);
return this;
}
@@ -855,13 +1077,15 @@ public SyncSpec rootsChangeConsumer(Consumer> consumer) {
* Registers multiple consumers that will be notified when the list of roots
* changes. This method is useful when multiple consumers need to be registered at
* once.
- * @param consumers The list of consumers to register. Must not be null.
+ * @param handlers The list of handlers to register. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if consumers is null
+ * @see #rootsChangeHandler(BiConsumer)
*/
- public SyncSpec rootsChangeConsumers(List>> consumers) {
- Assert.notNull(consumers, "Consumers list must not be null");
- this.rootsChangeConsumers.addAll(consumers);
+ public SyncSpecification rootsChangeHandlers(
+ List>> handlers) {
+ Assert.notNull(handlers, "Handlers list must not be null");
+ this.rootsChangeHandlers.addAll(handlers);
return this;
}
@@ -869,27 +1093,44 @@ public SyncSpec rootsChangeConsumers(List>> consum
* Registers multiple consumers that will be notified when the list of roots
* changes using varargs. This method provides a convenient way to register
* multiple consumers inline.
- * @param consumers The consumers to register. Must not be null.
+ * @param handlers The handlers to register. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if consumers is null
+ * @see #rootsChangeHandlers(List)
*/
- public SyncSpec rootsChangeConsumers(Consumer>... consumers) {
- for (Consumer> consumer : consumers) {
- this.rootsChangeConsumers.add(consumer);
- }
+ public SyncSpecification rootsChangeHandlers(
+ BiConsumer>... handlers) {
+ Assert.notNull(handlers, "Handlers list must not be null");
+ return this.rootsChangeHandlers(List.of(handlers));
+ }
+
+ /**
+ * Sets the object mapper to use for serializing and deserializing JSON messages.
+ * @param objectMapper the instance to use. Must not be null.
+ * @return This builder instance for method chaining.
+ * @throws IllegalArgumentException if objectMapper is null
+ */
+ public SyncSpecification objectMapper(ObjectMapper objectMapper) {
+ Assert.notNull(objectMapper, "ObjectMapper must not be null");
+ this.objectMapper = objectMapper;
return this;
}
/**
* Builds a synchronous MCP server that provides blocking operations.
* @return A new instance of {@link McpSyncServer} configured with this builder's
- * settings
+ * settings.
*/
public McpSyncServer build() {
McpServerFeatures.Sync syncFeatures = new McpServerFeatures.Sync(this.serverInfo, this.serverCapabilities,
- this.tools, this.resources, this.resourceTemplates, this.prompts, this.rootsChangeConsumers);
- return new McpSyncServer(
- new McpAsyncServer(this.transport, McpServerFeatures.Async.fromSync(syncFeatures)));
+ 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,
+ this.uriTemplateManagerFactory);
+
+ return new McpSyncServer(asyncServer);
}
}
diff --git a/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java b/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
index c8f8399a..8311f5d4 100644
--- a/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
+++ b/mcp/src/main/java/io/modelcontextprotocol/server/McpServerFeatures.java
@@ -8,8 +8,8 @@
import java.util.HashMap;
import java.util.List;
import java.util.Map;
-import java.util.function.Consumer;
-import java.util.function.Function;
+import java.util.function.BiConsumer;
+import java.util.function.BiFunction;
import io.modelcontextprotocol.spec.McpSchema;
import io.modelcontextprotocol.util.Assert;
@@ -21,6 +21,7 @@
* MCP server features specification that a particular server can choose to support.
*
* @author Dariusz Jędrzejczyk
+ * @author Jihoon Kim
*/
public class McpServerFeatures {
@@ -29,41 +30,48 @@ public class McpServerFeatures {
*
* @param serverInfo The server implementation details
* @param serverCapabilities The server capabilities
- * @param tools The list of tool registrations
- * @param resources The map of resource registrations
+ * @param tools The list of tool specifications
+ * @param resources The map of resource specifications
* @param resourceTemplates The list of resource templates
- * @param prompts The map of prompt registrations
+ * @param prompts The map of prompt specifications
* @param rootsChangeConsumers The list of consumers that will be notified when the
* roots list changes
+ * @param instructions The server instructions text
*/
record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
- List tools, Map resources,
+ List tools, Map resources,
List resourceTemplates,
- Map prompts,
- List, Mono>> rootsChangeConsumers) {
+ Map prompts,
+ Map completions,
+ List, Mono>> rootsChangeConsumers,
+ String instructions) {
/**
* Create an instance and validate the arguments.
* @param serverInfo The server implementation details
* @param serverCapabilities The server capabilities
- * @param tools The list of tool registrations
- * @param resources The map of resource registrations
+ * @param tools The list of tool specifications
+ * @param resources The map of resource specifications
* @param resourceTemplates The list of resource templates
- * @param prompts The map of prompt registrations
+ * @param prompts The map of prompt specifications
* @param rootsChangeConsumers The list of consumers that will be notified when
* the roots list changes
+ * @param instructions The server instructions text
*/
Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
- List tools, Map resources,
+ List tools, Map resources,
List resourceTemplates,
- Map prompts,
- List, Mono>> rootsChangeConsumers) {
+ Map prompts,
+ Map completions,
+ List, Mono>> rootsChangeConsumers,
+ String instructions) {
Assert.notNull(serverInfo, "Server info must not be null");
this.serverInfo = serverInfo;
this.serverCapabilities = (serverCapabilities != null) ? serverCapabilities
- : new McpSchema.ServerCapabilities(null, // experimental
+ : new McpSchema.ServerCapabilities(null, // completions
+ null, // experimental
new McpSchema.ServerCapabilities.LoggingCapabilities(), // Enable
// logging
// by
@@ -77,7 +85,9 @@ record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities s
this.resources = (resources != null) ? resources : Map.of();
this.resourceTemplates = (resourceTemplates != null) ? resourceTemplates : List.of();
this.prompts = (prompts != null) ? prompts : Map.of();
+ this.completions = (completions != null) ? completions : Map.of();
this.rootsChangeConsumers = (rootsChangeConsumers != null) ? rootsChangeConsumers : List.of();
+ this.instructions = instructions;
}
/**
@@ -89,30 +99,36 @@ record Async(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities s
* user.
*/
static Async fromSync(Sync syncSpec) {
- List tools = new ArrayList<>();
+ List tools = new ArrayList<>();
for (var tool : syncSpec.tools()) {
- tools.add(AsyncToolRegistration.fromSync(tool));
+ tools.add(AsyncToolSpecification.fromSync(tool));
}
- Map resources = new HashMap<>();
+ Map resources = new HashMap<>();
syncSpec.resources().forEach((key, resource) -> {
- resources.put(key, AsyncResourceRegistration.fromSync(resource));
+ resources.put(key, AsyncResourceSpecification.fromSync(resource));
});
- Map prompts = new HashMap<>();
+ Map prompts = new HashMap<>();
syncSpec.prompts().forEach((key, prompt) -> {
- prompts.put(key, AsyncPromptRegistration.fromSync(prompt));
+ prompts.put(key, AsyncPromptSpecification.fromSync(prompt));
});
- List, Mono>> rootChangeConsumers = new ArrayList<>();
+ Map completions = new HashMap<>();
+ syncSpec.completions().forEach((key, completion) -> {
+ completions.put(key, AsyncCompletionSpecification.fromSync(completion));
+ });
+
+ List, Mono>> rootChangeConsumers = new ArrayList<>();
for (var rootChangeConsumer : syncSpec.rootsChangeConsumers()) {
- rootChangeConsumers.add(list -> Mono.fromRunnable(() -> rootChangeConsumer.accept(list))
+ rootChangeConsumers.add((exchange, list) -> Mono
+ .fromRunnable(() -> rootChangeConsumer.accept(new McpSyncServerExchange(exchange), list))
.subscribeOn(Schedulers.boundedElastic()));
}
return new Async(syncSpec.serverInfo(), syncSpec.serverCapabilities(), tools, resources,
- syncSpec.resourceTemplates(), prompts, rootChangeConsumers);
+ syncSpec.resourceTemplates(), prompts, completions, rootChangeConsumers, syncSpec.instructions());
}
}
@@ -121,43 +137,49 @@ static Async fromSync(Sync syncSpec) {
*
* @param serverInfo The server implementation details
* @param serverCapabilities The server capabilities
- * @param tools The list of tool registrations
- * @param resources The map of resource registrations
+ * @param tools The list of tool specifications
+ * @param resources The map of resource specifications
* @param resourceTemplates The list of resource templates
- * @param prompts The map of prompt registrations
+ * @param prompts The map of prompt specifications
* @param rootsChangeConsumers The list of consumers that will be notified when the
* roots list changes
+ * @param instructions The server instructions text
*/
record Sync(McpSchema.Implementation serverInfo, McpSchema.ServerCapabilities serverCapabilities,
- List tools,
- Map resources,
+ List