org.tio.http.mcp.server

Class McpServer

java.lang.Object

org.tio.http.mcp.server.McpServer

public class McpServer
extends Object

mcp 服务

Author:

L.cm

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_MESSAGE_ENDPOINT Default message endpoint path as specified by the MCP transport specification.
static String	DEFAULT_SSE_ENDPOINT Default SSE endpoint path as specified by the MCP transport specification.
static String	ENDPOINT_EVENT_TYPE Event type for sending the message endpoint URI to clients.

Constructor Summary

Constructors

Constructor and Description
McpServer()
McpServer(String sseEndpoint, String messageEndpoint)

Method Summary

Modifier and Type	Method and Description
McpServer	capabilities(McpServerCapabilities serverCapabilities) Sets the server capabilities that will be advertised to clients during connection initialization.
String	getMessageEndpoint()
String	getSseEndpoint()
McpServer	prompts(List<McpPromptSpecification> prompts) Registers multiple prompts with their handlers using a List.
McpServer	prompts(Map<String,McpPromptSpecification> prompts) Registers multiple prompts with their handlers using a Map.
McpServer	prompts(McpPromptSpecification... prompts) Registers multiple prompts with their handlers using varargs.
McpServer	resources(List<McpResourceSpecification> resourceSpecifications) Registers multiple resources with their handlers using a List.
McpServer	resources(Map<String,McpResourceSpecification> resourceSpecifications) Registers multiple resources with their handlers using a Map.
McpServer	resources(McpResourceSpecification... resourceSpecifications) Registers multiple resources with their handlers using varargs.
McpServer	resourceTemplates(List<McpResourceTemplateSpecification> resourceTemplates) Sets the resource templates that define patterns for dynamic resource access.
McpServer	resourceTemplates(McpResourceTemplateSpecification... resourceTemplates) Sets the resource templates using varargs for convenience.
McpServer	rootsChangeHandler(BiConsumer<McpServerSession,List<McpRoot>> handler) Registers a consumer that will be notified when the list of roots changes.
McpServer	rootsChangeHandlers(BiConsumer<McpServerSession,List<McpRoot>>... handlers) Registers multiple consumers that will be notified when the list of roots changes using varargs.
McpServer	rootsChangeHandlers(List<BiConsumer<McpServerSession,List<McpRoot>>> handlers) Registers multiple consumers that will be notified when the list of roots changes.
void	sendHeartbeat() 发送心跳
McpServer	serverInfo(McpImplementation serverInfo) Sets the server implementation information that will be shared with clients during connection initialization.
McpServer	serverInfo(String name, String version) Sets the server implementation information using name and version strings.
HttpResponse	sseEndpoint(HttpRequest request) sse endpoint
HttpResponse	sseMessageEndpoint(HttpRequest request) sse message endpoint
McpServer	tool(McpTool tool, BiFunction<McpServerSession,Map<String,Object>,McpCallToolResult> handler) Adds a single tool with its implementation handler to the server.
McpServer	tools(List<McpToolSpecification> toolSpecifications) Adds multiple tools with their handlers to the server using a List.
McpServer	tools(McpToolSpecification... toolSpecifications) Adds multiple tools with their handlers to the server using varargs.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ENDPOINT_EVENT_TYPE

public static final String ENDPOINT_EVENT_TYPE

Event type for sending the message endpoint URI to clients.

See Also:

Constant Field Values

DEFAULT_SSE_ENDPOINT

public static final String DEFAULT_SSE_ENDPOINT

Default SSE endpoint path as specified by the MCP transport specification.

See Also:

Constant Field Values

DEFAULT_MESSAGE_ENDPOINT

public static final String DEFAULT_MESSAGE_ENDPOINT

Default message endpoint path as specified by the MCP transport specification.

See Also:

Constant Field Values

Constructor Detail

McpServer

public McpServer()

McpServer

public McpServer(String sseEndpoint,
                 String messageEndpoint)

Method Detail

serverInfo

public McpServer serverInfo(McpImplementation serverInfo)

Sets the server implementation information that will be shared with clients during connection initialization. This helps with version compatibility, debugging, and server identification.

Parameters:

serverInfo - The server implementation details including name and version. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if serverInfo is null

serverInfo

public McpServer serverInfo(String name,
                            String version)

Sets the server implementation information using name and version strings. This is a convenience method alternative to serverInfo(McpImplementation).

Parameters:

name - The server name. Must not be null or empty.

version - The server version. Must not be null or empty.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if name or version is null or empty

See Also:

serverInfo(McpImplementation)

capabilities

public McpServer capabilities(McpServerCapabilities serverCapabilities)

Sets the server capabilities that will be advertised to clients during connection initialization. Capabilities define what features the server supports, such as:

• Tool execution
• Resource access
• Prompt handling

Parameters:

serverCapabilities - The server capabilities configuration. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if serverCapabilities is null

tool

public McpServer tool(McpTool tool,
                      BiFunction<McpServerSession,Map<String,Object>,McpCallToolResult> handler)

Adds a single tool with its implementation handler to the server. This is a convenience method for registering individual tools without creating a McpToolSpecification explicitly.

Example usage:

 .tool(
     new Tool("calculator", "Performs calculations", schema),
     (exchange, args) -> new CallToolResult("Result: " + calculate(args))
 )
 

Parameters:

tool - The tool definition including name, description, and schema. Must not be null.

handler - The function that implements the tool's logic. Must not be null. The function's first argument is an McpServer upon which the server can interact with the connected client. The second argument is the list of arguments passed to the tool.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if tool or handler is null

tools

public McpServer tools(List<McpToolSpecification> toolSpecifications)

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.

Parameters:

toolSpecifications - The list of tool specifications to add. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if toolSpecifications is null

See Also:

tools(McpToolSpecification...)

tools

public McpServer tools(McpToolSpecification... toolSpecifications)

Adds multiple tools with their handlers to the server using varargs. This method provides a convenient way to register multiple tools inline.

Example usage:

 .tools(
     new ToolSpecification(calculatorTool, calculatorHandler),
     new ToolSpecification(weatherTool, weatherHandler),
     new ToolSpecification(fileManagerTool, fileManagerHandler)
 )
 

Parameters:

toolSpecifications - The tool specifications to add. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if toolSpecifications is null

See Also:

tools(List)

resources

public McpServer resources(Map<String,McpResourceSpecification> resourceSpecifications)

Registers multiple resources with their handlers using a Map. This method is useful when resources are dynamically generated or loaded from a configuration source.

Parameters:

resourceSpecifications - Map of resource name to specification. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if resourceSpecifications is null

See Also:

resources(McpResourceSpecification...)

resources

public McpServer resources(List<McpResourceSpecification> resourceSpecifications)

Registers multiple resources with their handlers using a List. This method is useful when resources need to be added in bulk from a collection.

Parameters:

resourceSpecifications - List of resource specifications. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if resourceSpecifications is null

See Also:

resources(McpResourceSpecification...)

resources

public McpServer resources(McpResourceSpecification... resourceSpecifications)

Registers multiple resources with their handlers using varargs. This method provides a convenient way to register multiple resources inline.

Example usage:

 .resources(
     new ResourceSpecification(fileResource, fileHandler),
     new ResourceSpecification(dbResource, dbHandler),
     new ResourceSpecification(apiResource, apiHandler)
 )
 

Parameters:

resourceSpecifications - The resource specifications to add. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if resourceSpecifications is null

resourceTemplates

public McpServer resourceTemplates(List<McpResourceTemplateSpecification> resourceTemplates)

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:

 .resourceTemplates(
     new ResourceTemplate("file://{path}", "Access files by path"),
     new ResourceTemplate("db://{table}/{id}", "Access database records")
 )
 

Parameters:

resourceTemplates - List of resource templates. If null, clears existing templates.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if resourceTemplates is null.

See Also:

#resourceTemplates(List...)

resourceTemplates

public McpServer resourceTemplates(McpResourceTemplateSpecification... resourceTemplates)

Sets the resource templates using varargs for convenience. This is an alternative to resourceTemplates(List).

Parameters:

resourceTemplates - The resource templates to set.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if resourceTemplates is null

See Also:

resourceTemplates(List)

prompts

public McpServer prompts(Map<String,McpPromptSpecification> prompts)

Registers multiple prompts with their handlers using a Map. This method is useful when prompts are dynamically generated or loaded from a configuration source.

Example usage:

 Map<String, PromptSpecification> prompts = new HashMap<>();
 prompts.put("analysis", new PromptSpecification(
     new Prompt("analysis", "Code analysis template"),
     (exchange, request) -> new GetPromptResult(generateAnalysisPrompt(request))
 ));
 .prompts(prompts)
 

Parameters:

prompts - Map of prompt name to specification. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if prompts is null

prompts

public McpServer prompts(List<McpPromptSpecification> prompts)

Registers multiple prompts with their handlers using a List. This method is useful when prompts need to be added in bulk from a collection.

Parameters:

prompts - List of prompt specifications. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if prompts is null

See Also:

prompts(McpPromptSpecification...)

prompts

public McpServer prompts(McpPromptSpecification... prompts)

Registers multiple prompts with their handlers using varargs. This method provides a convenient way to register multiple prompts inline.

Example usage:

 .prompts(
     new PromptSpecification(analysisPrompt, analysisHandler),
     new PromptSpecification(summaryPrompt, summaryHandler),
     new PromptSpecification(reviewPrompt, reviewHandler)
 )
 

Parameters:

prompts - The prompt specifications to add. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if prompts is null

rootsChangeHandler

public McpServer rootsChangeHandler(BiConsumer<McpServerSession,List<McpRoot>> handler)

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.

Parameters:

handler - The handler to register. Must not be null. The function's first argument is an McpServerSession upon which the server can interact with the connected client. The second argument is the list of roots.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if consumer is null

rootsChangeHandlers

public McpServer rootsChangeHandlers(List<BiConsumer<McpServerSession,List<McpRoot>>> handlers)

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.

Parameters:

handlers - The list of handlers to register. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if consumers is null

See Also:

rootsChangeHandler(BiConsumer)

rootsChangeHandlers

@SafeVarargs
public final McpServer rootsChangeHandlers(BiConsumer<McpServerSession,List<McpRoot>>... handlers)

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.

Parameters:

handlers - The handlers to register. Must not be null.

Returns:

This builder instance for method chaining

Throws:

IllegalArgumentException - if consumers is null

See Also:

rootsChangeHandlers(List)

sseEndpoint

public HttpResponse sseEndpoint(HttpRequest request)

sse endpoint

Parameters:

request - HttpRequest

Returns:

HttpResponse

sseMessageEndpoint

public HttpResponse sseMessageEndpoint(HttpRequest request)

sse message endpoint

Parameters:

request - HttpRequest

Returns:

HttpResponse

sendHeartbeat

public void sendHeartbeat()

发送心跳

getMessageEndpoint

public String getMessageEndpoint()

getSseEndpoint

public String getSseEndpoint()