程序包 io.agentscope.core.tool.mcp

类 McpClientBuilder

java.lang.Object
io.agentscope.core.tool.mcp.McpClientBuilder
public class McpClientBuilder extends Object
Builder for creating MCP client wrappers with fluent configuration.

Supports three transport types:

  • StdIO - for local process communication
  • SSE - for HTTP Server-Sent Events (stateful)
  • StreamableHTTP - for HTTP streaming (stateless)

Example usage: 


 // StdIO transport
 McpClientWrapper client = McpClientBuilder.create("git-mcp")
         .stdioTransport("python", "-m", "mcp_server_git")
         .buildAsync()
         .block();

 // SSE transport with headers and query parameters
 McpClientWrapper client = McpClientBuilder.create("remote-mcp")
         .sseTransport("https://mcp.example.com/sse")
         .header("Authorization", "Bearer " + token)
         .queryParam("queryKey", "queryValue")
         .timeout(Duration.ofSeconds(60))
         .buildAsync()
         .block();

 // HTTP transport with multiple query parameters
 McpClientWrapper client = McpClientBuilder.create("http-mcp")
         .streamableHttpTransport("https://mcp.example.com/http")
         .queryParams(Map.of("token", "abc123", "env", "prod"))
         .buildSync();

  • 方法详细资料

    • create

      public static McpClientBuilder create(String name)
      Creates a new MCP client builder with the specified name.
      参数:
      name - unique identifier for the MCP client
      返回:
      new builder instance

    • stdioTransport

      public McpClientBuilder stdioTransport(String command, String... args)
      Configures StdIO transport for local process communication.
      参数:
      command - the executable command
      args - command arguments
      返回:
      this builder

    • stdioTransport

      public McpClientBuilder stdioTransport(String command, List<String> args, Map<String,String> env)
      Configures StdIO transport with environment variables.
      参数:
      command - the executable command
      args - command arguments list
      env - environment variables
      返回:
      this builder

    • sseTransport

      public McpClientBuilder sseTransport(String url)
      Configures HTTP SSE (Server-Sent Events) transport for stateful connections.
      参数:
      url - the server URL
      返回:
      this builder

    • customizeSseClient

      public McpClientBuilder customizeSseClient(Consumer<HttpClient.Builder> customizer)
      Customizes the HTTP client for SSE transport (only applicable after calling sseTransport). This allows advanced HTTP client configuration like HTTP/2, custom timeouts, SSL settings, etc.

      Example usage for HTTP/2: 

      
 McpClientWrapper client = McpClientBuilder.create("mcp")
         .sseTransport("https://example.com/sse")
     .customizeSseClient(clientBuilder ->
         clientBuilder.version(java.net.http.HttpClient.Version.HTTP_2))
         .buildAsync()
         .block();
      参数:
      customizer - consumer to customize the HttpClient.Builder
      返回:
      this builder

    • streamableHttpTransport

      public McpClientBuilder streamableHttpTransport(String url)
      Configures HTTP StreamableHTTP transport for stateless connections.
      参数:
      url - the server URL
      返回:
      this builder

    • customizeStreamableHttpClient

      public McpClientBuilder customizeStreamableHttpClient(Consumer<HttpClient.Builder> customizer)
      Customizes the HTTP client for StreamableHTTP transport (only applicable after calling streamableHttpTransport). This allows advanced HTTP client configuration like HTTP/2, custom timeouts, SSL settings, etc.

      Example usage for HTTP/2: 

      
 McpClientWrapper client = McpClientBuilder.create("mcp")
         .streamableHttpTransport("https://example.com/http")
         .customizeStreamableHttpClient(
                 clientBuilder -> clientBuilder.version(java.net.http.HttpClient.Version.HTTP_2))
         .buildAsync()
         .block();
      参数:
      customizer - consumer to customize the HttpClient.Builder
      返回:
      this builder

    • header

      public McpClientBuilder header(String key, String value)
      Adds an HTTP header (only applicable for HTTP transports).
      参数:
      key - header name
      value - header value
      返回:
      this builder

    • headers

      public McpClientBuilder headers(Map<String,String> headers)
      Sets multiple HTTP headers (only applicable for HTTP transports).
      参数:
      headers - map of header name-value pairs
      返回:
      this builder

    • queryParam

      public McpClientBuilder queryParam(String key, String value)
      Adds a query parameter to the URL (only applicable for HTTP transports).

      Query parameters added via this method will be merged with any existing query parameters in the URL. If the same parameter key exists in both the URL and the added parameters, the added parameter will take precedence.

      参数:
      key - query parameter name
      value - query parameter value
      返回:
      this builder

    • queryParams

      public McpClientBuilder queryParams(Map<String,String> queryParams)
      Sets multiple query parameters (only applicable for HTTP transports).

      This method replaces any previously added query parameters. Query parameters in the original URL are still preserved and merged.

      参数:
      queryParams - map of query parameter name-value pairs
      返回:
      this builder

    • timeout

      public McpClientBuilder timeout(Duration timeout)
      Sets the request timeout duration.
      参数:
      timeout - timeout duration
      返回:
      this builder

    • initializationTimeout

      public McpClientBuilder initializationTimeout(Duration timeout)
      Sets the initialization timeout duration.
      参数:
      timeout - timeout duration
      返回:
      this builder

    • asyncElicitation

      public McpClientBuilder asyncElicitation(Function<io.modelcontextprotocol.spec.McpSchema.ElicitRequest,reactor.core.publisher.Mono<io.modelcontextprotocol.spec.McpSchema.ElicitResult>> handler)
      Registers an asynchronous elicitation handler for processing elicit requests from the server.

      When an elicitation handler is registered, the client will automatically enable the elicitation capability in ClientCapabilities.

      This method is for use with buildAsync(). The handler returns a Mono for asynchronous processing.

      Example usage: 

      
 McpClientWrapper client = McpClientBuilder.create("mcp")
     .stdioTransport("python", "-m", "mcp_server")
     .asyncElicitation(request -> {
         // Handle elicitation request asynchronously
         return Mono.just(ElicitResult.builder()...build());
     })
     .buildAsync()
     .block();
      参数:
      handler - function to handle elicit requests asynchronously
      返回:
      this builder

    • syncElicitation

      public McpClientBuilder syncElicitation(Function<io.modelcontextprotocol.spec.McpSchema.ElicitRequest,io.modelcontextprotocol.spec.McpSchema.ElicitResult> handler)
      Registers a synchronous elicitation handler for processing elicit requests from the server.

      When an elicitation handler is registered, the client will automatically enable the elicitation capability in ClientCapabilities.

      This method is for use with buildSync(). The handler returns an McpSchema.ElicitResult directly for synchronous processing.

      Example usage: 

      
 McpClientWrapper client = McpClientBuilder.create("mcp")
     .stdioTransport("python", "-m", "mcp_server")
     .syncElicitation(request -> {
         // Handle elicitation request synchronously
         return ElicitResult.builder()...build();
     })
     .buildSync();
      参数:
      handler - function to handle elicit requests synchronously
      返回:
      this builder

    • buildAsync

      public reactor.core.publisher.Mono<McpClientWrapper> buildAsync()
      Builds an asynchronous MCP client wrapper.
      返回:
      Mono emitting the async client wrapper

    • buildSync

      public McpClientWrapper buildSync()
      Builds a synchronous MCP client wrapper (blocking operations).
      返回:
      synchronous client wrapper