- * The class provides factory methods to create either: + * 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. + * + *
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: *
- * Use the builder pattern for flexible client configuration: + *
The class provides factory methods to create either: + *
Example of creating a basic client: *
{@code
* McpClient.using(transport)
- * .requestTimeout(Duration.ofSeconds(5))
- * .sync(); // or .async()
+ * .requestTimeout(Duration.ofSeconds(5))
+ * .sync(); // or .async()
* }
*
+ * Example with advanced configuration: + *
{@code
+ * McpClient.using(transport)
+ * .requestTimeout(Duration.ofSeconds(10))
+ * .capabilities(new ClientCapabilities(...))
+ * .clientInfo(new Implementation("My Client", "1.0.0"))
+ * .roots(new Root("file://workspace", "Workspace Files"))
+ * .toolsChangeConsumer(tools -> System.out.println("Tools updated: " + tools))
+ * .async();
+ * }
+ *
+ * The client supports: + *
The builder supports configuration of: + *
- * The class provides factory methods to create either: + *
This class serves as the main entry point for implementing the server-side of + * the MCP specification. The server's responsibilities include: *
- * Use the builder pattern for flexible server configuration: + *
The class provides factory methods to create either: + *
Example of creating a basic server: *
{@code
* McpServer.using(transport)
- * .serverInfo(new McpSchema.Implementation("my-server", "1.0.0"))
- * .tool(new MyToolHandler())
- * .async(); // or .sync()
+ * .info("my-server", "1.0.0")
+ * .tool(new Tool("calculator", "Performs calculations", schema),
+ * args -> new CallToolResult("Result: " + calculate(args)))
+ * .sync(); // or .async()
+ * }
+ *
+ * Example with comprehensive configuration: + *
{@code
+ * McpServer.using(transport)
+ * .info("advanced-server", "2.0.0")
+ * .capabilities(new ServerCapabilities(...))
+ * // Register tools
+ * .tools(
+ * new ToolRegistration(calculatorTool, calculatorHandler),
+ * new ToolRegistration(weatherTool, weatherHandler)
+ * )
+ * // Register resources
+ * .resources(
+ * new ResourceRegistration(fileResource, fileHandler),
+ * new ResourceRegistration(dbResource, dbHandler)
+ * )
+ * // Add resource templates
+ * .resourceTemplates(
+ * new ResourceTemplate("file://{path}", "Access files"),
+ * new ResourceTemplate("db://{table}", "Access database")
+ * )
+ * // Register prompts
+ * .prompts(
+ * new PromptRegistration(analysisPrompt, analysisHandler),
+ * new PromptRegistration(summaryPrompt, summaryHandler)
+ * )
+ * .async();
* }
*
* @author Christian Tzolov
+ * @see McpAsyncServer
+ * @see McpSyncServer
+ * @see McpTransport
*/
public interface McpServer {
/**
- * Registration of a tool with its handler function. MCP allows servers to expose
- * tools that can be invoked by language models. Tools enable models to interact with
- * external systems, such as querying databases, calling APIs, or performing
- * computations. Each tool is uniquely identified by a name and includes metadata
- * describing its schema.
+ * 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:
+ * Example tool registration: + *
{@code
+ * new ToolRegistration(
+ * new Tool(
+ * "calculator",
+ * "Performs mathematical calculations",
+ * new JsonSchemaObject()
+ * .required("expression")
+ * .property("expression", JsonSchemaType.STRING)
+ * ),
+ * args -> {
+ * String expr = (String) args.get("expression");
+ * return new CallToolResult("Result: " + evaluate(expr));
+ * }
+ * )
+ * }
+ *
+ * @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
*/
public static record ToolRegistration(Tool tool, FunctionExample resource registration: + *
{@code
+ * new ResourceRegistration(
+ * new Resource("docs", "Documentation files", "text/markdown"),
+ * request -> {
+ * String content = readFile(request.getPath());
+ * return new ReadResourceResult(content);
+ * }
+ * )
+ * }
+ *
+ * @param resource The resource definition including name, description, and MIME type
+ * @param readHandler The function that handles resource read requests
+ */
public static record ResourceRegistration(McpSchema.Resource resource,
FunctionExample prompt registration: + *
{@code
+ * new PromptRegistration(
+ * new Prompt("analyze", "Code analysis template"),
+ * request -> {
+ * String code = request.getArguments().get("code");
+ * return new GetPromptResult(
+ * "Analyze this code:\n\n" + code + "\n\nProvide feedback on:"
+ * );
+ * }
+ * )
+ * }
+ *
+ * @param prompt The prompt definition including name and description
+ * @param promptHandler The function that processes prompt requests and returns
+ * formatted templates
+ */
public static record PromptRegistration(McpSchema.Prompt propmpt,
FunctionExample usage: + *
{@code
+ * .tool(
+ * new Tool("calculator", "Performs calculations", schema),
+ * 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.
+ * @return This builder instance for method chaining
+ * @throws IllegalArgumentException if tool or handler is null
*/
public Builder tool(McpSchema.Tool tool, FunctionExample usage: + *
{@code
+ * .tools(
+ * new ToolRegistration(calculatorTool, calculatorHandler),
+ * new ToolRegistration(weatherTool, weatherHandler),
+ * new ToolRegistration(fileManagerTool, fileManagerHandler)
+ * )
+ * }
+ *
+ * @param toolRegistrations The tool registrations to add. Must not be null.
+ * @return This builder instance for method chaining
+ * @throws IllegalArgumentException if toolRegistrations is null
+ * @see #tools(List)
*/
public Builder tools(ToolRegistration... toolRegistrations) {
for (ToolRegistration tool : toolRegistrations) {
@@ -204,9 +369,15 @@ public interface McpServer {
}
/**
- * Register resources with the server.
- * @param resourceRegsitrations The map of resources to register
- * @return This builder instance
+ * 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...)
*/
public Builder resources(MapExample usage: + *
{@code
+ * .resources(
+ * new ResourceRegistration(fileResource, fileHandler),
+ * new ResourceRegistration(dbResource, dbHandler),
+ * new ResourceRegistration(apiResource, apiHandler)
+ * )
+ * }
+ *
+ * @param resourceRegistrations The resource registrations to add.
+ * Must not be null.
+ * @return This builder instance for method chaining
+ * @throws IllegalArgumentException if resourceRegistrations is null
*/
public Builder resources(ResourceRegistration... resourceRegistrations) {
Assert.notNull(resourceRegistrations, "Resource handlers list must not be null");
@@ -241,15 +432,36 @@ public interface McpServer {
}
/**
- * Set the resource templates.
- * @param resourceTemplates The list of resource templates
- * @return This builder instance
+ * Sets the resource templates that define patterns for dynamic resource
+ * access. Templates use URI patterns with placeholders that can be
+ * filled at runtime.
+ *
+ * Example usage: + *
{@code
+ * .resourceTemplates(
+ * new ResourceTemplate("file://{path}", "Access files by path"),
+ * new ResourceTemplate("db://{table}/{id}", "Access database records")
+ * )
+ * }
+ *
+ * @param resourceTemplates List of resource templates. If null, clears
+ * existing templates.
+ * @return This builder instance for method chaining
+ * @see #resourceTemplates(ResourceTemplate...)
*/
public Builder resourceTemplates(ListExample usage: + *
{@code
+ * Map prompts = new HashMap<>();
+ * prompts.put("analysis", new PromptRegistration(
+ * new Prompt("analysis", "Code analysis template"),
+ * request -> new GetPromptResult(generateAnalysisPrompt(request))
+ * ));
+ * .prompts(prompts)
+ * }
+ *
+ * @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
*/
public Builder prompts(MapExample usage: + *
{@code
+ * .prompts(
+ * new PromptRegistration(analysisPrompt, analysisHandler),
+ * new PromptRegistration(summaryPrompt, summaryHandler),
+ * new PromptRegistration(reviewPrompt, reviewHandler)
+ * )
+ * }
+ *
+ * @param prompts The prompt registrations to add. Must not be null.
+ * @return This builder instance for method chaining
+ * @throws IllegalArgumentException if prompts is null
*/
public Builder prompts(PromptRegistration... prompts) {
for (PromptRegistration prompt : prompts) {
@@ -292,16 +536,26 @@ public interface McpServer {
}
/**
- * Build a synchronous MCP server.
- * @return A new instance of {@link McpSyncServer}
+ * 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());
}
/**
- * Build an asynchronous MCP server.
- * @return A new instance of {@link McpAsyncServer}
+ * 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
*/
public McpAsyncServer async() {
if (serverInfo == null) {