modelcontextprotocol/java-sdk
Watch
1
0
Fork
You've already forked java-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Fix code formatting

Browse source
This commit is contained in:
Christian Tzolov 2024-12-30 13:16:08 +01:00
commit b6c9973cbf
2 changed files with 148 additions and 175 deletions
Download patch file Download diff file Expand all files Collapse all files

132
mcp/src/main/java/org/springframework/ai/mcp/client/McpClient.java
View file

@ -34,33 +34,37 @@ import org.springframework.ai.mcp.spec.McpTransport;
import org.springframework.ai.mcp.util.Assert; import org.springframework.ai.mcp.util.Assert;
/** /**
* Factory class for creating Model Context Protocol (MCP) clients. MCP is a protocol that enables * Factory class for creating Model Context Protocol (MCP) clients. MCP is a protocol that
* AI models to interact with external tools and resources through a standardized interface. * enables AI models to interact with external tools and resources through a standardized
* interface.
* *
* <p>This class serves as the main entry point for establishing connections with MCP servers, * <p>
* implementing the client-side of the MCP specification. The protocol follows a client-server * This class serves as the main entry point for establishing connections with MCP
* architecture where: * servers, implementing the client-side of the MCP specification. The protocol follows a
* client-server architecture where:
* <ul> * <ul>
* <li>The client (this implementation) initiates connections and sends requests * <li>The client (this implementation) initiates connections and sends requests
* <li>The server responds to requests and provides access to tools and resources * <li>The server responds to requests and provides access to tools and resources
* <li>Communication occurs through a transport layer (e.g., stdio, SSE) using JSON-RPC 2.0 * <li>Communication occurs through a transport layer (e.g., stdio, SSE) using JSON-RPC
* 2.0
* </ul> * </ul>
* *
* <p>The class provides factory methods to create either: * <p>
* The class provides factory methods to create either:
* <ul> * <ul>
* <li>{@link McpAsyncClient} for non-blocking operations with CompletableFuture responses * <li>{@link McpAsyncClient} for non-blocking operations with CompletableFuture responses
* <li>{@link McpSyncClient} for blocking operations with direct responses * <li>{@link McpSyncClient} for blocking operations with direct responses
* </ul> * </ul>
* *
* <p>Example of creating a basic client: * <p>
* <pre>{@code * Example of creating a basic client: <pre>{@code
* McpClient.using(transport) * McpClient.using(transport)
* .requestTimeout(Duration.ofSeconds(5)) * .requestTimeout(Duration.ofSeconds(5))
* .sync(); // or .async() * .sync(); // or .async()
* }</pre> * }</pre>
* *
* <p>Example with advanced configuration: * <p>
* <pre>{@code * Example with advanced configuration: <pre>{@code
* McpClient.using(transport) * McpClient.using(transport)
* .requestTimeout(Duration.ofSeconds(10)) * .requestTimeout(Duration.ofSeconds(10))
* .capabilities(new ClientCapabilities(...)) * .capabilities(new ClientCapabilities(...))
@ -70,7 +74,8 @@ import org.springframework.ai.mcp.util.Assert;
* .async(); * .async();
* }</pre> * }</pre>
* *
* <p>The client supports: * <p>
* The client supports:
* <ul> * <ul>
* <li>Tool discovery and invocation * <li>Tool discovery and invocation
* <li>Resource access and management * <li>Resource access and management
@ -88,14 +93,12 @@ import org.springframework.ai.mcp.util.Assert;
public interface McpClient { public interface McpClient {
/** /**
* Start building an MCP client with the specified transport layer. * Start building an MCP client with the specified transport layer. The transport
* The transport layer handles the low-level communication between * layer handles the low-level communication between client and server using protocols
* client and server using protocols like stdio or Server-Sent Events (SSE). * like stdio or Server-Sent Events (SSE).
* * @param transport The transport layer implementation for MCP communication. Common
* @param transport The transport layer implementation for MCP communication. * implementations include {@code StdioClientTransport} for stdio-based communication
* Common implementations include {@code StdioClientTransport} * and {@code SseClientTransport} for SSE-based communication.
* for stdio-based communication and {@code SseClientTransport}
* for SSE-based communication.
* @return A new builder instance for configuring the client * @return A new builder instance for configuring the client
* @throws IllegalArgumentException if transport is null * @throws IllegalArgumentException if transport is null
*/ */
@ -104,11 +107,12 @@ public interface McpClient {
} }
/** /**
* Builder class for creating and configuring MCP clients. This class follows * Builder class for creating and configuring MCP clients. This class follows the
* the builder pattern to provide a fluent API for setting up clients with * builder pattern to provide a fluent API for setting up clients with custom
* custom configurations. * configurations.
* *
* <p>The builder supports configuration of: * <p>
* The builder supports configuration of:
* <ul> * <ul>
* <li>Transport layer for client-server communication * <li>Transport layer for client-server communication
* <li>Request timeouts for operation boundaries * <li>Request timeouts for operation boundaries
@ -145,12 +149,11 @@ public interface McpClient {
} }
/** /**
* Sets the duration to wait for server responses before timing out requests. * Sets the duration to wait for server responses before timing out requests. This
* This timeout applies to all requests made through the client, including * timeout applies to all requests made through the client, including tool calls,
* tool calls, resource access, and prompt operations. * resource access, and prompt operations.
* * @param requestTimeout The duration to wait before timing out requests. Must not
* @param requestTimeout The duration to wait before timing out requests. * be null.
* Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if requestTimeout is null * @throws IllegalArgumentException if requestTimeout is null
*/ */
@ -162,9 +165,8 @@ public interface McpClient {
/** /**
* Sets the client capabilities that will be advertised to the server during * Sets the client capabilities that will be advertised to the server during
* connection initialization. Capabilities define what features the client supports, * connection initialization. Capabilities define what features the client
* such as tool execution, resource access, and prompt handling. * supports, such as tool execution, resource access, and prompt handling.
*
* @param capabilities The client capabilities configuration. Must not be null. * @param capabilities The client capabilities configuration. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if capabilities is null * @throws IllegalArgumentException if capabilities is null
@ -179,9 +181,8 @@ public interface McpClient {
* Sets the client implementation information that will be shared with the server * Sets the client implementation information that will be shared with the server
* during connection initialization. This helps with version compatibility and * during connection initialization. This helps with version compatibility and
* debugging. * debugging.
*
* @param clientInfo The client implementation details including name and version. * @param clientInfo The client implementation details including name and version.
* Must not be null. * Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if clientInfo is null * @throws IllegalArgumentException if clientInfo is null
*/ */
@ -192,10 +193,9 @@ public interface McpClient {
} }
/** /**
* Sets the root URIs that this client can access. Roots define the base URIs * Sets the root URIs that this client can access. Roots define the base URIs for
* for resources that the client can request from the server. For example, * resources that the client can request from the server. For example, a root
* a root might be "file://workspace" for accessing workspace files. * might be "file://workspace" for accessing workspace files.
*
* @param roots A list of root definitions. Must not be null. * @param roots A list of root definitions. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if roots is null * @throws IllegalArgumentException if roots is null
@ -209,9 +209,8 @@ public interface McpClient {
} }
/** /**
* Sets the root URIs that this client can access, using a varargs parameter * Sets the root URIs that this client can access, using a varargs parameter for
* for convenience. This is an alternative to {@link #roots(List)}. * convenience. This is an alternative to {@link #roots(List)}.
*
* @param roots An array of root definitions. Must not be null. * @param roots An array of root definitions. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if roots is null * @throws IllegalArgumentException if roots is null
@ -226,12 +225,11 @@ public interface McpClient {
} }
/** /**
* Sets a custom sampling handler for processing message creation requests. * Sets a custom sampling handler for processing message creation requests. The
* The sampling handler can modify or validate messages before they are sent * sampling handler can modify or validate messages before they are sent to the
* to the server, enabling custom processing logic. * server, enabling custom processing logic.
*
* @param samplingHandler A function that processes message requests and returns * @param samplingHandler A function that processes message requests and returns
* results. Must not be null. * results. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if samplingHandler is null * @throws IllegalArgumentException if samplingHandler is null
*/ */
@ -242,12 +240,11 @@ public interface McpClient {
} }
/** /**
* Adds a consumer to be notified when the available tools change. This allows * Adds a consumer to be notified when the available tools change. This allows the
* the client to react to changes in the server's tool capabilities, such as * client to react to changes in the server's tool capabilities, such as tools
* tools being added or removed. * being added or removed.
*
* @param toolsChangeConsumer A consumer that receives the updated list of * @param toolsChangeConsumer A consumer that receives the updated list of
* available tools. Must not be null. * available tools. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if toolsChangeConsumer is null * @throws IllegalArgumentException if toolsChangeConsumer is null
*/ */
@ -261,9 +258,8 @@ public interface McpClient {
* Adds a consumer to be notified when the available resources change. This allows * Adds a consumer to be notified when the available resources change. This allows
* the client to react to changes in the server's resource availability, such as * the client to react to changes in the server's resource availability, such as
* files being added or removed. * files being added or removed.
*
* @param resourcesChangeConsumer A consumer that receives the updated list of * @param resourcesChangeConsumer A consumer that receives the updated list of
* available resources. Must not be null. * available resources. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if resourcesChangeConsumer is null * @throws IllegalArgumentException if resourcesChangeConsumer is null
*/ */
@ -275,11 +271,10 @@ public interface McpClient {
/** /**
* Adds a consumer to be notified when the available prompts change. This allows * Adds a consumer to be notified when the available prompts change. This allows
* the client to react to changes in the server's prompt templates, such as * the client to react to changes in the server's prompt templates, such as new
* new templates being added or existing ones being modified. * templates being added or existing ones being modified.
*
* @param promptsChangeConsumer A consumer that receives the updated list of * @param promptsChangeConsumer A consumer that receives the updated list of
* available prompts. Must not be null. * available prompts. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if promptsChangeConsumer is null * @throws IllegalArgumentException if promptsChangeConsumer is null
*/ */
@ -290,13 +285,11 @@ public interface McpClient {
} }
/** /**
* Builds a synchronous MCP client that provides blocking operations. * Builds a synchronous MCP client that provides blocking operations. Synchronous
* Synchronous clients wait for each operation to complete before returning, * clients wait for each operation to complete before returning, making them
* making them simpler to use but potentially less performant for * simpler to use but potentially less performant for concurrent operations.
* concurrent operations. * @return A new instance of {@link McpSyncClient} configured with this builder's
* * settings
* @return A new instance of {@link McpSyncClient} configured with this
* builder's settings
*/ */
public McpSyncClient sync() { public McpSyncClient sync() {
return new McpSyncClient(async()); return new McpSyncClient(async());
@ -304,11 +297,10 @@ public interface McpClient {
/** /**
* Builds an asynchronous MCP client that provides non-blocking operations. * Builds an asynchronous MCP client that provides non-blocking operations.
* Asynchronous clients return CompletableFuture objects immediately, * Asynchronous clients return CompletableFuture objects immediately, allowing for
* allowing for concurrent operations and reactive programming patterns. * concurrent operations and reactive programming patterns.
* * @return A new instance of {@link McpAsyncClient} configured with this builder's
* @return A new instance of {@link McpAsyncClient} configured with this * settings
* builder's settings
*/ */
public McpAsyncClient async() { public McpAsyncClient async() {
return new McpAsyncClient(transport, requestTimeout, clientInfo, capabilities, roots, toolsChangeConsumers, return new McpAsyncClient(transport, requestTimeout, clientInfo, capabilities, roots, toolsChangeConsumers,

189
mcp/src/main/java/org/springframework/ai/mcp/server/McpServer.java
View file

@ -33,8 +33,9 @@ import org.springframework.ai.mcp.util.Assert;
* Factory class for creating Model Context Protocol (MCP) servers. MCP servers expose * Factory class for creating Model Context Protocol (MCP) servers. MCP servers expose
* tools, resources, and prompts to AI models through a standardized interface. * tools, resources, and prompts to AI models through a standardized interface.
* *
* <p>This class serves as the main entry point for implementing the server-side of * <p>
* the MCP specification. The server's responsibilities include: * This class serves as the main entry point for implementing the server-side of the MCP
* specification. The server's responsibilities include:
* <ul> * <ul>
* <li>Exposing tools that models can invoke to perform actions * <li>Exposing tools that models can invoke to perform actions
* <li>Providing access to resources that give models context * <li>Providing access to resources that give models context
@ -43,14 +44,15 @@ import org.springframework.ai.mcp.util.Assert;
* <li>Implementing capability negotiation * <li>Implementing capability negotiation
* </ul> * </ul>
* *
* <p>The class provides factory methods to create either: * <p>
* The class provides factory methods to create either:
* <ul> * <ul>
* <li>{@link McpAsyncServer} for non-blocking operations with CompletableFuture responses * <li>{@link McpAsyncServer} for non-blocking operations with CompletableFuture responses
* <li>{@link McpSyncServer} for blocking operations with direct responses * <li>{@link McpSyncServer} for blocking operations with direct responses
* </ul> * </ul>
* *
* <p>Example of creating a basic server: * <p>
* <pre>{@code * Example of creating a basic server: <pre>{@code
* McpServer.using(transport) * McpServer.using(transport)
* .info("my-server", "1.0.0") * .info("my-server", "1.0.0")
* .tool(new Tool("calculator", "Performs calculations", schema), * .tool(new Tool("calculator", "Performs calculations", schema),
@ -58,8 +60,8 @@ import org.springframework.ai.mcp.util.Assert;
* .sync(); // or .async() * .sync(); // or .async()
* }</pre> * }</pre>
* *
* <p>Example with comprehensive configuration: * <p>
* <pre>{@code * Example with comprehensive configuration: <pre>{@code
* McpServer.using(transport) * McpServer.using(transport)
* .info("advanced-server", "2.0.0") * .info("advanced-server", "2.0.0")
* .capabilities(new ServerCapabilities(...)) * .capabilities(new ServerCapabilities(...))
@ -94,8 +96,8 @@ import org.springframework.ai.mcp.util.Assert;
public interface McpServer { public interface McpServer {
/** /**
* Registration of a tool with its handler function. Tools are the primary way for * Registration of a tool with its handler function. Tools are the primary way for MCP
* MCP servers to expose functionality to AI models. Each tool represents a specific * servers to expose functionality to AI models. Each tool represents a specific
* capability, such as: * capability, such as:
* <ul> * <ul>
* <li>Performing calculations * <li>Performing calculations
@ -105,8 +107,8 @@ public interface McpServer {
* <li>Executing system commands * <li>Executing system commands
* </ul> * </ul>
* *
* <p>Example tool registration: * <p>
* <pre>{@code * Example tool registration: <pre>{@code
* new ToolRegistration( * new ToolRegistration(
* new Tool( * new Tool(
* "calculator", * "calculator",
@ -123,15 +125,15 @@ public interface McpServer {
* }</pre> * }</pre>
* *
* @param tool The tool definition including name, description, and parameter schema * @param tool The tool definition including name, description, and parameter schema
* @param call The function that implements the tool's logic, receiving arguments * @param call The function that implements the tool's logic, receiving arguments and
* and returning results * returning results
*/ */
public static record ToolRegistration(Tool tool, Function<Map<String, Object>, CallToolResult> call) { public static record ToolRegistration(Tool tool, Function<Map<String, Object>, CallToolResult> call) {
} }
/** /**
* Registration of a resource with its handler function. Resources provide context * Registration of a resource with its handler function. Resources provide context to
* to AI models by exposing data such as: * AI models by exposing data such as:
* <ul> * <ul>
* <li>File contents * <li>File contents
* <li>Database records * <li>Database records
@ -140,8 +142,8 @@ public interface McpServer {
* <li>Application state * <li>Application state
* </ul> * </ul>
* *
* <p>Example resource registration: * <p>
* <pre>{@code * Example resource registration: <pre>{@code
* new ResourceRegistration( * new ResourceRegistration(
* new Resource("docs", "Documentation files", "text/markdown"), * new Resource("docs", "Documentation files", "text/markdown"),
* request -> { * request -> {
@ -169,8 +171,8 @@ public interface McpServer {
* <li>Instruction templating * <li>Instruction templating
* </ul> * </ul>
* *
* <p>Example prompt registration: * <p>
* <pre>{@code * Example prompt registration: <pre>{@code
* new PromptRegistration( * new PromptRegistration(
* new Prompt("analyze", "Code analysis template"), * new Prompt("analyze", "Code analysis template"),
* request -> { * request -> {
@ -184,7 +186,7 @@ public interface McpServer {
* *
* @param prompt The prompt definition including name and description * @param prompt The prompt definition including name and description
* @param promptHandler The function that processes prompt requests and returns * @param promptHandler The function that processes prompt requests and returns
* formatted templates * formatted templates
*/ */
public static record PromptRegistration(McpSchema.Prompt propmpt, public static record PromptRegistration(McpSchema.Prompt propmpt,
Function<McpSchema.GetPromptRequest, McpSchema.GetPromptResult> promptHandler) { Function<McpSchema.GetPromptRequest, McpSchema.GetPromptResult> promptHandler) {
@ -248,9 +250,8 @@ public interface McpServer {
* Sets the server implementation information that will be shared with clients * Sets the server implementation information that will be shared with clients
* during connection initialization. This helps with version compatibility, * during connection initialization. This helps with version compatibility,
* debugging, and server identification. * debugging, and server identification.
*
* @param serverInfo The server implementation details including name and version. * @param serverInfo The server implementation details including name and version.
* Must not be null. * Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if serverInfo is null * @throws IllegalArgumentException if serverInfo is null
*/ */
@ -261,9 +262,8 @@ public interface McpServer {
} }
/** /**
* Sets the server implementation information using name and version strings. * Sets the server implementation information using name and version strings. This
* This is a convenience method alternative to {@link #info(McpSchema.Implementation)}. * is a convenience method alternative to {@link #info(McpSchema.Implementation)}.
*
* @param name The server name. Must not be null or empty. * @param name The server name. Must not be null or empty.
* @param version The server version. Must not be null or empty. * @param version The server version. Must not be null or empty.
* @return This builder instance for method chaining * @return This builder instance for method chaining
@ -288,8 +288,8 @@ public interface McpServer {
* <li>Streaming responses * <li>Streaming responses
* <li>Batch operations * <li>Batch operations
* </ul> * </ul>
* * @param serverCapabilities The server capabilities configuration. Must not be
* @param serverCapabilities The server capabilities configuration. Must not be null. * null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if serverCapabilities is null * @throws IllegalArgumentException if serverCapabilities is null
*/ */
@ -299,20 +299,19 @@ public interface McpServer {
} }
/** /**
* Adds a single tool with its implementation handler to the server. This is * Adds a single tool with its implementation handler to the server. This is a
* a convenience method for registering individual tools without creating a * convenience method for registering individual tools without creating a
* {@link ToolRegistration} explicitly. * {@link ToolRegistration} explicitly.
* *
* <p>Example usage: * <p>
* <pre>{@code * Example usage: <pre>{@code
* .tool( * .tool(
* new Tool("calculator", "Performs calculations", schema), * new Tool("calculator", "Performs calculations", schema),
* args -> new CallToolResult("Result: " + calculate(args)) * args -> new CallToolResult("Result: " + calculate(args))
* ) * )
* }</pre> * }</pre>
* * @param tool The tool definition including name, description, and schema. Must
* @param tool The tool definition including name, description, and schema. * not be null.
* Must not be null.
* @param handler The function that implements the tool's logic. Must not be null. * @param handler The function that implements the tool's logic. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if tool or handler is null * @throws IllegalArgumentException if tool or handler is null
@ -327,12 +326,11 @@ public interface McpServer {
} }
/** /**
* Adds multiple tools with their handlers to the server using a List. * Adds multiple tools with their handlers to the server using a List. This method
* This method is useful when tools are dynamically generated or loaded * is useful when tools are dynamically generated or loaded from a configuration
* from a configuration source. * source.
* * @param toolRegistrations The list of tool registrations to add. Must not be
* @param toolRegistrations The list of tool registrations to add. * null.
* Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if toolRegistrations is null * @throws IllegalArgumentException if toolRegistrations is null
* @see #tools(ToolRegistration...) * @see #tools(ToolRegistration...)
@ -344,18 +342,17 @@ public interface McpServer {
} }
/** /**
* Adds multiple tools with their handlers to the server using varargs. * Adds multiple tools with their handlers to the server using varargs. This
* This method provides a convenient way to register multiple tools inline. * method provides a convenient way to register multiple tools inline.
* *
* <p>Example usage: * <p>
* <pre>{@code * Example usage: <pre>{@code
* .tools( * .tools(
* new ToolRegistration(calculatorTool, calculatorHandler), * new ToolRegistration(calculatorTool, calculatorHandler),
* new ToolRegistration(weatherTool, weatherHandler), * new ToolRegistration(weatherTool, weatherHandler),
* new ToolRegistration(fileManagerTool, fileManagerHandler) * new ToolRegistration(fileManagerTool, fileManagerHandler)
* ) * )
* }</pre> * }</pre>
*
* @param toolRegistrations The tool registrations to add. Must not be null. * @param toolRegistrations The tool registrations to add. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if toolRegistrations is null * @throws IllegalArgumentException if toolRegistrations is null
@ -369,12 +366,11 @@ public interface McpServer {
} }
/** /**
* Registers multiple resources with their handlers using a Map. * Registers multiple resources with their handlers using a Map. This method is
* This method is useful when resources are dynamically generated * useful when resources are dynamically generated or loaded from a configuration
* or loaded from a configuration source. * source.
* * @param resourceRegsitrations Map of resource name to registration. Must not be
* @param resourceRegsitrations Map of resource name to registration. * null.
* Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if resourceRegsitrations is null * @throws IllegalArgumentException if resourceRegsitrations is null
* @see #resources(ResourceRegistration...) * @see #resources(ResourceRegistration...)
@ -386,12 +382,9 @@ public interface McpServer {
} }
/** /**
* Registers multiple resources with their handlers using a List. * Registers multiple resources with their handlers using a List. This method is
* This method is useful when resources need to be added in bulk * useful when resources need to be added in bulk from a collection.
* from a collection. * @param resourceRegsitrations List of resource registrations. Must not be null.
*
* @param resourceRegsitrations List of resource registrations.
* Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if resourceRegsitrations is null * @throws IllegalArgumentException if resourceRegsitrations is null
* @see #resources(ResourceRegistration...) * @see #resources(ResourceRegistration...)
@ -405,21 +398,19 @@ public interface McpServer {
} }
/** /**
* Registers multiple resources with their handlers using varargs. * Registers multiple resources with their handlers using varargs. This method
* This method provides a convenient way to register multiple * provides a convenient way to register multiple resources inline.
* resources inline.
* *
* <p>Example usage: * <p>
* <pre>{@code * Example usage: <pre>{@code
* .resources( * .resources(
* new ResourceRegistration(fileResource, fileHandler), * new ResourceRegistration(fileResource, fileHandler),
* new ResourceRegistration(dbResource, dbHandler), * new ResourceRegistration(dbResource, dbHandler),
* new ResourceRegistration(apiResource, apiHandler) * new ResourceRegistration(apiResource, apiHandler)
* ) * )
* }</pre> * }</pre>
* * @param resourceRegistrations The resource registrations to add. Must not be
* @param resourceRegistrations The resource registrations to add. * null.
* Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if resourceRegistrations is null * @throws IllegalArgumentException if resourceRegistrations is null
*/ */
@ -432,20 +423,18 @@ public interface McpServer {
} }
/** /**
* Sets the resource templates that define patterns for dynamic resource * Sets the resource templates that define patterns for dynamic resource access.
* access. Templates use URI patterns with placeholders that can be * Templates use URI patterns with placeholders that can be filled at runtime.
* filled at runtime.
* *
* <p>Example usage: * <p>
* <pre>{@code * Example usage: <pre>{@code
* .resourceTemplates( * .resourceTemplates(
* new ResourceTemplate("file://{path}", "Access files by path"), * new ResourceTemplate("file://{path}", "Access files by path"),
* new ResourceTemplate("db://{table}/{id}", "Access database records") * new ResourceTemplate("db://{table}/{id}", "Access database records")
* ) * )
* }</pre> * }</pre>
* * @param resourceTemplates List of resource templates. If null, clears existing
* @param resourceTemplates List of resource templates. If null, clears * templates.
* existing templates.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @see #resourceTemplates(ResourceTemplate...) * @see #resourceTemplates(ResourceTemplate...)
*/ */
@ -455,9 +444,8 @@ public interface McpServer {
} }
/** /**
* Sets the resource templates using varargs for convenience. * Sets the resource templates using varargs for convenience. This is an
* This is an alternative to {@link #resourceTemplates(List)}. * alternative to {@link #resourceTemplates(List)}.
*
* @param resourceTemplates The resource templates to set. * @param resourceTemplates The resource templates to set.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @see #resourceTemplates(List) * @see #resourceTemplates(List)
@ -470,12 +458,12 @@ public interface McpServer {
} }
/** /**
* Registers multiple prompts with their handlers using a Map. * Registers multiple prompts with their handlers using a Map. This method is
* This method is useful when prompts are dynamically generated * useful when prompts are dynamically generated or loaded from a configuration
* or loaded from a configuration source. * source.
* *
* <p>Example usage: * <p>
* <pre>{@code * Example usage: <pre>{@code
* Map<String, PromptRegistration> prompts = new HashMap<>(); * Map<String, PromptRegistration> prompts = new HashMap<>();
* prompts.put("analysis", new PromptRegistration( * prompts.put("analysis", new PromptRegistration(
* new Prompt("analysis", "Code analysis template"), * new Prompt("analysis", "Code analysis template"),
@ -483,7 +471,6 @@ public interface McpServer {
* )); * ));
* .prompts(prompts) * .prompts(prompts)
* }</pre> * }</pre>
*
* @param prompts Map of prompt name to registration. Must not be null. * @param prompts Map of prompt name to registration. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null * @throws IllegalArgumentException if prompts is null
@ -494,10 +481,8 @@ public interface McpServer {
} }
/** /**
* Registers multiple prompts with their handlers using a List. * Registers multiple prompts with their handlers using a List. This method is
* This method is useful when prompts need to be added in bulk * useful when prompts need to be added in bulk from a collection.
* from a collection.
*
* @param prompts List of prompt registrations. Must not be null. * @param prompts List of prompt registrations. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null * @throws IllegalArgumentException if prompts is null
@ -511,19 +496,17 @@ public interface McpServer {
} }
/** /**
* Registers multiple prompts with their handlers using varargs. * Registers multiple prompts with their handlers using varargs. This method
* This method provides a convenient way to register multiple * provides a convenient way to register multiple prompts inline.
* prompts inline.
* *
* <p>Example usage: * <p>
* <pre>{@code * Example usage: <pre>{@code
* .prompts( * .prompts(
* new PromptRegistration(analysisPrompt, analysisHandler), * new PromptRegistration(analysisPrompt, analysisHandler),
* new PromptRegistration(summaryPrompt, summaryHandler), * new PromptRegistration(summaryPrompt, summaryHandler),
* new PromptRegistration(reviewPrompt, reviewHandler) * new PromptRegistration(reviewPrompt, reviewHandler)
* ) * )
* }</pre> * }</pre>
*
* @param prompts The prompt registrations to add. Must not be null. * @param prompts The prompt registrations to add. Must not be null.
* @return This builder instance for method chaining * @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null * @throws IllegalArgumentException if prompts is null
@ -536,13 +519,12 @@ public interface McpServer {
} }
/** /**
* Builds a synchronous MCP server that provides blocking operations. * Builds a synchronous MCP server that provides blocking operations. Synchronous
* Synchronous servers process each request to completion before handling * servers process each request to completion before handling the next one, making
* the next one, making them simpler to implement but potentially less * them simpler to implement but potentially less performant for concurrent
* performant for concurrent operations. * operations.
* * @return A new instance of {@link McpSyncServer} configured with this builder's
* @return A new instance of {@link McpSyncServer} configured with this * settings
* builder's settings
*/ */
public McpSyncServer sync() { public McpSyncServer sync() {
return new McpSyncServer(async()); return new McpSyncServer(async());
@ -551,11 +533,10 @@ public interface McpServer {
/** /**
* Builds an asynchronous MCP server that provides non-blocking operations. * Builds an asynchronous MCP server that provides non-blocking operations.
* Asynchronous servers can handle multiple requests concurrently using * Asynchronous servers can handle multiple requests concurrently using
* CompletableFuture, making them more efficient for high-concurrency * CompletableFuture, making them more efficient for high-concurrency scenarios
* scenarios but more complex to implement. * but more complex to implement.
* * @return A new instance of {@link McpAsyncServer} configured with this builder's
* @return A new instance of {@link McpAsyncServer} configured with this * settings
* builder's settings
*/ */
public McpAsyncServer async() { public McpAsyncServer async() {
if (serverInfo == null) { if (serverInfo == null) {