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

134
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;
/**
* Factory class for creating Model Context Protocol (MCP) clients. MCP is a protocol that 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,
* implementing the client-side of the MCP specification. The protocol follows a client-server
* architecture where:
* Factory class for creating Model Context Protocol (MCP) clients. MCP is a protocol that
* 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, implementing the client-side of the MCP specification. The protocol follows a
* client-server architecture where:
* <ul>
* <li>The client (this implementation) initiates connections and sends requests
* <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>
*
* <p>The class provides factory methods to create either:
* <p>
* The class provides factory methods to create either:
* <ul>
* <li>{@link McpAsyncClient} for non-blocking operations with CompletableFuture responses
* <li>{@link McpSyncClient} for blocking operations with direct responses
* </ul>
*
* <p>Example of creating a basic client:
* <pre>{@code
* <p>
* Example of creating a basic client: <pre>{@code
* McpClient.using(transport)
* .requestTimeout(Duration.ofSeconds(5))
* .sync(); // or .async()
* }</pre>
*
* <p>Example with advanced configuration:
* <pre>{@code
* <p>
* Example with advanced configuration: <pre>{@code
* McpClient.using(transport)
* .requestTimeout(Duration.ofSeconds(10))
* .capabilities(new ClientCapabilities(...))
@ -70,7 +74,8 @@ import org.springframework.ai.mcp.util.Assert;
* .async();
* }</pre>
*
* <p>The client supports:
* <p>
* The client supports:
* <ul>
* <li>Tool discovery and invocation
* <li>Resource access and management
@ -88,14 +93,12 @@ import org.springframework.ai.mcp.util.Assert;
public interface McpClient {
/**
* Start building an MCP client with the specified transport layer.
* The transport layer handles the low-level communication between
* client and server using protocols like stdio or Server-Sent Events (SSE).
*
* @param transport The transport layer implementation for MCP communication.
* Common implementations include {@code StdioClientTransport}
* for stdio-based communication and {@code SseClientTransport}
* for SSE-based communication.
* Start building an MCP client with the specified transport layer. The transport
* layer handles the low-level communication between client and server using protocols
* like stdio or Server-Sent Events (SSE).
* @param transport The transport layer implementation for MCP communication. Common
* implementations include {@code StdioClientTransport} for stdio-based communication
* and {@code SseClientTransport} for SSE-based communication.
* @return A new builder instance for configuring the client
* @throws IllegalArgumentException if transport is null
*/
@ -104,11 +107,12 @@ public interface McpClient {
}
/**
* Builder class for creating and configuring MCP clients. This class follows
* the builder pattern to provide a fluent API for setting up clients with
* custom configurations.
* Builder class for creating and configuring MCP clients. This class follows the
* builder pattern to provide a fluent API for setting up clients with custom
* configurations.
*
* <p>The builder supports configuration of:
* <p>
* The builder supports configuration of:
* <ul>
* <li>Transport layer for client-server communication
* <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.
* 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.
* 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
*/
@ -162,9 +165,8 @@ public interface McpClient {
/**
* Sets the client capabilities that will be advertised to the server during
* connection initialization. Capabilities define what features the client supports,
* such as tool execution, resource access, and prompt handling.
*
* connection initialization. Capabilities define what features the client
* supports, such as tool execution, resource access, and prompt handling.
* @param capabilities The client capabilities configuration. Must not be null.
* @return This builder instance for method chaining
* @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
* during connection initialization. This helps with version compatibility and
* debugging.
*
* @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
* @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
* for resources that the client can request from the server. For example,
* a root might be "file://workspace" for accessing workspace files.
*
* Sets the root URIs that this client can access. Roots define the base URIs for
* resources that the client can request from the server. For example, a root
* might be "file://workspace" for accessing workspace files.
* @param roots A list of root definitions. Must not be null.
* @return This builder instance for method chaining
* @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
* for convenience. This is an alternative to {@link #roots(List)}.
*
* Sets the root URIs that this client can access, using a varargs parameter for
* convenience. This is an alternative to {@link #roots(List)}.
* @param roots An array of root definitions. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if roots is null
@ -226,12 +225,11 @@ public interface McpClient {
}
/**
* Sets a custom sampling handler for processing message creation requests.
* The sampling handler can modify or validate messages before they are sent
* to the server, enabling custom processing logic.
*
* Sets a custom sampling handler for processing message creation requests. The
* sampling handler can modify or validate messages before they are sent to the
* server, enabling custom processing logic.
* @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
* @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
* the client to react to changes in the server's tool capabilities, such as
* tools being added or removed.
*
* Adds a consumer to be notified when the available tools change. This allows the
* client to react to changes in the server's tool capabilities, such as tools
* being added or removed.
* @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
* @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
* the client to react to changes in the server's resource availability, such as
* files being added or removed.
*
* @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
* @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
* the client to react to changes in the server's prompt templates, such as
* new templates being added or existing ones being modified.
*
* the client to react to changes in the server's prompt templates, such as new
* templates being added or existing ones being modified.
* @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
* @throws IllegalArgumentException if promptsChangeConsumer is null
*/
@ -290,13 +285,11 @@ public interface McpClient {
}
/**
* Builds a synchronous MCP client that provides blocking operations.
* Synchronous clients wait for each operation to complete before returning,
* making them simpler to use but potentially less performant for
* concurrent operations.
*
* @return A new instance of {@link McpSyncClient} configured with this
* builder's settings
* Builds a synchronous MCP client that provides blocking operations. Synchronous
* clients wait for each operation to complete before returning, making them
* simpler to use but potentially less performant for concurrent operations.
* @return A new instance of {@link McpSyncClient} configured with this builder's
* settings
*/
public McpSyncClient sync() {
return new McpSyncClient(async());
@ -304,11 +297,10 @@ public interface McpClient {
/**
* Builds an asynchronous MCP client that provides non-blocking operations.
* Asynchronous clients return CompletableFuture objects immediately,
* allowing for concurrent operations and reactive programming patterns.
*
* @return A new instance of {@link McpAsyncClient} configured with this
* builder's settings
* Asynchronous clients return CompletableFuture objects immediately, allowing for
* concurrent operations and reactive programming patterns.
* @return A new instance of {@link McpAsyncClient} configured with this builder's
* settings
*/
public McpAsyncClient async() {
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
* 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
* the MCP specification. The server's responsibilities include:
* <p>
* This class serves as the main entry point for implementing the server-side of the MCP
* specification. The server's responsibilities include:
* <ul>
* <li>Exposing tools that models can invoke to perform actions
* <li>Providing access to resources that give models context
@ -43,14 +44,15 @@ import org.springframework.ai.mcp.util.Assert;
* <li>Implementing capability negotiation
* </ul>
*
* <p>The class provides factory methods to create either:
* <p>
* The class provides factory methods to create either:
* <ul>
* <li>{@link McpAsyncServer} for non-blocking operations with CompletableFuture responses
* <li>{@link McpSyncServer} for blocking operations with direct responses
* </ul>
*
* <p>Example of creating a basic server:
* <pre>{@code
* <p>
* Example of creating a basic server: <pre>{@code
* McpServer.using(transport)
* .info("my-server", "1.0.0")
* .tool(new Tool("calculator", "Performs calculations", schema),
@ -58,8 +60,8 @@ import org.springframework.ai.mcp.util.Assert;
* .sync(); // or .async()
* }</pre>
*
* <p>Example with comprehensive configuration:
* <pre>{@code
* <p>
* Example with comprehensive configuration: <pre>{@code
* McpServer.using(transport)
* .info("advanced-server", "2.0.0")
* .capabilities(new ServerCapabilities(...))
@ -94,8 +96,8 @@ import org.springframework.ai.mcp.util.Assert;
public interface McpServer {
/**
* Registration of a tool with its handler function. Tools are the primary way for
* MCP servers to expose functionality to AI models. Each tool represents a specific
* Registration of a tool with its handler function. Tools are the primary way for MCP
* servers to expose functionality to AI models. Each tool represents a specific
* capability, such as:
* <ul>
* <li>Performing calculations
@ -105,8 +107,8 @@ public interface McpServer {
* <li>Executing system commands
* </ul>
*
* <p>Example tool registration:
* <pre>{@code
* <p>
* Example tool registration: <pre>{@code
* new ToolRegistration(
* new Tool(
* "calculator",
@ -123,15 +125,15 @@ public interface McpServer {
* }</pre>
*
* @param tool The tool definition including name, description, and parameter schema
* @param call The function that implements the tool's logic, receiving arguments
* and returning results
* @param call The function that implements the tool's logic, receiving arguments and
* returning results
*/
public static record ToolRegistration(Tool tool, Function<Map<String, Object>, CallToolResult> call) {
}
/**
* Registration of a resource with its handler function. Resources provide context
* to AI models by exposing data such as:
* Registration of a resource with its handler function. Resources provide context to
* AI models by exposing data such as:
* <ul>
* <li>File contents
* <li>Database records
@ -140,8 +142,8 @@ public interface McpServer {
* <li>Application state
* </ul>
*
* <p>Example resource registration:
* <pre>{@code
* <p>
* Example resource registration: <pre>{@code
* new ResourceRegistration(
* new Resource("docs", "Documentation files", "text/markdown"),
* request -> {
@ -169,8 +171,8 @@ public interface McpServer {
* <li>Instruction templating
* </ul>
*
* <p>Example prompt registration:
* <pre>{@code
* <p>
* Example prompt registration: <pre>{@code
* new PromptRegistration(
* new Prompt("analyze", "Code analysis template"),
* request -> {
@ -184,7 +186,7 @@ public interface McpServer {
*
* @param prompt The prompt definition including name and description
* @param promptHandler The function that processes prompt requests and returns
* formatted templates
* formatted templates
*/
public static record PromptRegistration(McpSchema.Prompt propmpt,
Function<McpSchema.GetPromptRequest, McpSchema.GetPromptResult> promptHandler) {
@ -248,9 +250,8 @@ public interface McpServer {
* Sets the server implementation information that will be shared with clients
* during connection initialization. This helps with version compatibility,
* debugging, and server identification.
*
* @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
* @throws IllegalArgumentException if serverInfo is null
*/
@ -261,9 +262,8 @@ public interface McpServer {
}
/**
* Sets the server implementation information using name and version strings.
* This is a convenience method alternative to {@link #info(McpSchema.Implementation)}.
*
* Sets the server implementation information using name and version strings. This
* is a convenience method alternative to {@link #info(McpSchema.Implementation)}.
* @param name The server name. Must not be null or empty.
* @param version The server version. Must not be null or empty.
* @return This builder instance for method chaining
@ -288,8 +288,8 @@ public interface McpServer {
* <li>Streaming responses
* <li>Batch operations
* </ul>
*
* @param serverCapabilities The server capabilities configuration. Must not be null.
* @param serverCapabilities The server capabilities configuration. Must not be
* null.
* @return This builder instance for method chaining
* @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
* a convenience method for registering individual tools without creating a
* 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.
*
* <p>Example usage:
* <pre>{@code
* <p>
* Example usage: <pre>{@code
* .tool(
* new Tool("calculator", "Performs calculations", schema),
* args -> new CallToolResult("Result: " + calculate(args))
* )
* }</pre>
*
* @param tool The tool definition including name, description, and schema.
* Must not be null.
* @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.
* @return This builder instance for method chaining
* @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.
* 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 null.
* 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
* null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if toolRegistrations is null
* @see #tools(ToolRegistration...)
@ -344,18 +342,17 @@ public interface McpServer {
}
/**
* Adds multiple tools with their handlers to the server using varargs.
* This method provides a convenient way to register multiple tools inline.
* Adds multiple tools with their handlers to the server using varargs. This
* method provides a convenient way to register multiple tools inline.
*
* <p>Example usage:
* <pre>{@code
* <p>
* Example usage: <pre>{@code
* .tools(
* new ToolRegistration(calculatorTool, calculatorHandler),
* new ToolRegistration(weatherTool, weatherHandler),
* new ToolRegistration(fileManagerTool, fileManagerHandler)
* )
* }</pre>
*
* @param toolRegistrations The tool registrations to add. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if toolRegistrations is null
@ -369,12 +366,11 @@ public interface McpServer {
}
/**
* 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.
* 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.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if resourceRegsitrations is null
* @see #resources(ResourceRegistration...)
@ -386,12 +382,9 @@ public interface McpServer {
}
/**
* 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.
* 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.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if resourceRegsitrations is null
* @see #resources(ResourceRegistration...)
@ -405,21 +398,19 @@ public interface McpServer {
}
/**
* Registers multiple resources with their handlers using varargs.
* This method provides a convenient way to register multiple
* resources inline.
* Registers multiple resources with their handlers using varargs. This method
* provides a convenient way to register multiple resources inline.
*
* <p>Example usage:
* <pre>{@code
* <p>
* Example usage: <pre>{@code
* .resources(
* new ResourceRegistration(fileResource, fileHandler),
* new ResourceRegistration(dbResource, dbHandler),
* new ResourceRegistration(apiResource, apiHandler)
* )
* }</pre>
*
* @param resourceRegistrations The resource registrations to add.
* Must not be null.
* @param resourceRegistrations The resource registrations to add. Must not be
* null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if resourceRegistrations is null
*/
@ -432,20 +423,18 @@ public interface McpServer {
}
/**
* Sets the resource templates that define patterns for dynamic resource
* access. Templates use URI patterns with placeholders that can be
* filled at runtime.
* Sets the resource templates that define patterns for dynamic resource access.
* Templates use URI patterns with placeholders that can be filled at runtime.
*
* <p>Example usage:
* <pre>{@code
* <p>
* Example usage: <pre>{@code
* .resourceTemplates(
* new ResourceTemplate("file://{path}", "Access files by path"),
* new ResourceTemplate("db://{table}/{id}", "Access database records")
* )
* }</pre>
*
* @param resourceTemplates List of resource templates. If null, clears
* existing templates.
* @param resourceTemplates List of resource templates. If null, clears existing
* templates.
* @return This builder instance for method chaining
* @see #resourceTemplates(ResourceTemplate...)
*/
@ -455,9 +444,8 @@ public interface McpServer {
}
/**
* Sets the resource templates using varargs for convenience.
* This is an alternative to {@link #resourceTemplates(List)}.
*
* Sets the resource templates using varargs for convenience. This is an
* alternative to {@link #resourceTemplates(List)}.
* @param resourceTemplates The resource templates to set.
* @return This builder instance for method chaining
* @see #resourceTemplates(List)
@ -470,12 +458,12 @@ public interface McpServer {
}
/**
* Registers multiple prompts with their handlers using a Map.
* This method is useful when prompts are dynamically generated
* or loaded from a configuration source.
* Registers multiple prompts with their handlers using a Map. This method is
* useful when prompts are dynamically generated or loaded from a configuration
* source.
*
* <p>Example usage:
* <pre>{@code
* <p>
* Example usage: <pre>{@code
* Map<String, PromptRegistration> prompts = new HashMap<>();
* prompts.put("analysis", new PromptRegistration(
* new Prompt("analysis", "Code analysis template"),
@ -483,7 +471,6 @@ public interface McpServer {
* ));
* .prompts(prompts)
* }</pre>
*
* @param prompts Map of prompt name to registration. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null
@ -494,10 +481,8 @@ public interface McpServer {
}
/**
* Registers multiple prompts with their handlers using a List.
* This method is useful when prompts need to be added in bulk
* from a collection.
*
* 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.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null
@ -511,19 +496,17 @@ public interface McpServer {
}
/**
* Registers multiple prompts with their handlers using varargs.
* This method provides a convenient way to register multiple
* prompts inline.
* Registers multiple prompts with their handlers using varargs. This method
* provides a convenient way to register multiple prompts inline.
*
* <p>Example usage:
* <pre>{@code
* <p>
* Example usage: <pre>{@code
* .prompts(
* new PromptRegistration(analysisPrompt, analysisHandler),
* new PromptRegistration(summaryPrompt, summaryHandler),
* new PromptRegistration(reviewPrompt, reviewHandler)
* )
* }</pre>
*
* @param prompts The prompt registrations to add. Must not be null.
* @return This builder instance for method chaining
* @throws IllegalArgumentException if prompts is null
@ -536,13 +519,12 @@ public interface McpServer {
}
/**
* Builds 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.
*
* @return A new instance of {@link McpSyncServer} configured with this
* builder's settings
* Builds 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.
* @return A new instance of {@link McpSyncServer} configured with this builder's
* settings
*/
public McpSyncServer sync() {
return new McpSyncServer(async());
@ -551,11 +533,10 @@ public interface McpServer {
/**
* Builds an asynchronous MCP server that provides non-blocking operations.
* Asynchronous servers can handle multiple requests concurrently using
* CompletableFuture, making them more efficient for high-concurrency
* scenarios but more complex to implement.
*
* @return A new instance of {@link McpAsyncServer} configured with this
* builder's settings
* CompletableFuture, making them more efficient for high-concurrency scenarios
* but more complex to implement.
* @return A new instance of {@link McpAsyncServer} configured with this builder's
* settings
*/
public McpAsyncServer async() {
if (serverInfo == null) {