类class io.agentscope.extensions.higress 2.x

HigressMcpClientBuilder

public class HigressMcpClientBuilder

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:69–449

Higress MCP 客户端构建器，用于构建并配置目标实例。位于 io.agentscope.extensions.higress 包。核心成员包括 create、sseEndpoint、streamableHttpEndpoint、header、headers、queryParam。

Builder for creating HigressMcpClientWrapper instances.

This builder follows the same pattern as McpClientBuilder in agentscope-core, providing a fluent API for configuring and building Higress MCP clients.

Supports two transport types:

SSE (Server-Sent Events) - for stateful connections with server push
StreamableHTTP - for stateless HTTP streaming

Example usage with SSE transport:

`HigressMcpClientWrapper client = HigressMcpClientBuilder
.create("higress-mcp")
.sseEndpoint("http://higress-gateway/mcp-servers/union-tools-search/sse")
.build();
`

Example usage with StreamableHTTP transport:

`HigressMcpClientWrapper client = HigressMcpClientBuilder
.create("higress-mcp")
.streamableHttpEndpoint("http://higress-gateway/mcp-servers/union-tools-search")
.build();
`

Example with authentication:

`HigressMcpClientWrapper client = HigressMcpClientBuilder
.create("higress-mcp")
.sseEndpoint("http://higress-gateway/mcp-servers/union-tools-search/sse")
.header("Authorization", "Bearer " + token)
.header("X-Api-Key", apiKey)
.timeout(Duration.ofSeconds(60))
.buildAsync()
.block();
`

方法摘要Method Summary

方法Method	说明Description
`public static` `HigressMcpClientBuilder create(String clientName)` static	创建并返回实例。 Creates a new builder with the specified client name.
`public` `HigressMcpClientBuilder sseEndpoint(String endpoint)`	设置SSE 端点。 Configures SSE (Server-Sent Events) transport endpoint.
`public` `HigressMcpClientBuilder streamableHttpEndpoint(String endpoint)`	设置该配置项。 Configures StreamableHTTP transport endpoint.
`public` `HigressMcpClientBuilder header(String key, String value)`	设置请求头。 Adds an HTTP header to be sent with each request.
`public` `HigressMcpClientBuilder headers(Map<String, String> headers)`	设置请求头。 Sets multiple HTTP headers at once.
`public` `HigressMcpClientBuilder queryParam(String key, String value)`	设置查询参数。 Adds a query parameter to the URL.
`public` `HigressMcpClientBuilder queryParams(Map<String, String> queryParams)`	设置查询参数。 Sets multiple query parameters at once.
`public` `HigressMcpClientBuilder timeout(Duration timeout)`	设置请求超时时长。 Sets the request timeout duration.
`public` `HigressMcpClientBuilder initializationTimeout(Duration timeout)`	设置该配置项。 Sets the initialization timeout duration.
`public` `HigressMcpClientBuilder toolSearch(String query)`	设置工具搜索。 Enables tool search with the specified query.
`public` `HigressMcpClientBuilder toolSearch(String query, int topK)`	设置工具搜索。 Enables tool search with the specified query and topK.
`public Mono<HigressMcpClientWrapper> buildAsync()`	构建异步。 Builds an asynchronous `HigressMcpClientWrapper` instance.
`public` `HigressMcpClientWrapper buildSync()`	构建同步。 Builds a synchronous `HigressMcpClientWrapper` instance (blocking operation).

方法详情Method Detail

create

public static HigressMcpClientBuilder create(String clientName)

static

创建并返回实例。

Creates a new builder with the specified client name.

参数Parameters

名称Name	类型Type	说明Description
`clientName`	String	客户端名称（类型 `String`）。unique identifier for the MCP client

返回Returns HigressMcpClientBuilder

返回HigressMcpClientBuilder。new builder instance

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if clientName is null or empty

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:101–106

sseEndpoint

public HigressMcpClientBuilder sseEndpoint(String endpoint)

设置SSE 端点。

Configures SSE (Server-Sent Events) transport endpoint.

参数Parameters

名称Name	类型Type	说明Description
`endpoint`	String	端点地址（类型 `String`）。the SSE endpoint URL (e.g., "http://higress-gateway/mcp-servers/union-tools-search/sse")

返回Returns HigressMcpClientBuilder

返回HigressMcpClientBuilder。this builder for method chaining

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:118–122

streamableHttpEndpoint

public HigressMcpClientBuilder streamableHttpEndpoint(String endpoint)

设置该配置项。

Configures StreamableHTTP transport endpoint.

参数Parameters

名称Name	类型Type	说明Description
`endpoint`	String	端点地址（类型 `String`）。the StreamableHTTP endpoint URL (e.g., "http://higress-gateway/mcp-servers/union-tools-search")

返回Returns HigressMcpClientBuilder

返回HigressMcpClientBuilder。this builder for method chaining

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:133–137

header

public HigressMcpClientBuilder header(String key, String value)

设置请求头。

Adds an HTTP header to be sent with each request.

参数Parameters

名称Name	类型Type	说明Description
`key`	String	键（类型 `String`）。header name
`value`	String	值（类型 `String`）。header value

返回Returns HigressMcpClientBuilder

返回HigressMcpClientBuilder。this builder for method chaining

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:152–155

headers

public HigressMcpClientBuilder headers(Map<String, String> headers)

设置请求头。

Sets multiple HTTP headers at once.

参数Parameters

名称Name	类型Type	说明Description
`headers`	Map<String, String>	请求头（类型 `Map`）。map of header name-value pairs

返回Returns HigressMcpClientBuilder

返回HigressMcpClientBuilder。this builder for method chaining

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:163–168

queryParam

public HigressMcpClientBuilder queryParam(String key, String value)

设置查询参数。

Adds a query parameter to the URL.

参数Parameters

名称Name	类型Type	说明Description
`key`	String	键（类型 `String`）。query parameter name
`value`	String	值（类型 `String`）。query parameter value

返回Returns HigressMcpClientBuilder

返回HigressMcpClientBuilder。this builder for method chaining

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:190–193

queryParams

public HigressMcpClientBuilder queryParams(Map<String, String> queryParams)

设置查询参数。

Sets multiple query parameters at once.

参数Parameters

名称Name	类型Type	说明Description
`queryParams`	Map<String, String>	查询参数（类型 `Map`）。map of query parameter name-value pairs

返回Returns HigressMcpClientBuilder

返回HigressMcpClientBuilder。this builder for method chaining

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:201–206

timeout

public HigressMcpClientBuilder timeout(Duration timeout)

设置请求超时时长。

Sets the request timeout duration.

参数Parameters

名称Name	类型Type	说明Description
`timeout`	Duration	超时时间（类型 `Duration`）。timeout duration

返回Returns HigressMcpClientBuilder

返回HigressMcpClientBuilder。this builder for method chaining

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:217–220

initializationTimeout

public HigressMcpClientBuilder initializationTimeout(Duration timeout)

设置该配置项。

Sets the initialization timeout duration.

参数Parameters

名称Name	类型Type	说明Description
`timeout`	Duration	超时时间（类型 `Duration`）。timeout duration

返回Returns HigressMcpClientBuilder

返回HigressMcpClientBuilder。this builder for method chaining

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:231–234

toolSearch

public HigressMcpClientBuilder toolSearch(String query)

设置工具搜索。

Enables tool search with the specified query.

参数Parameters

名称Name	类型Type	说明Description
`query`	String	查询文本（类型 `String`）。the search query describing what tools are needed

返回Returns HigressMcpClientBuilder

返回HigressMcpClientBuilder。this builder for method chaining

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:254–258

toolSearch

public HigressMcpClientBuilder toolSearch(String query, int topK)

设置工具搜索。

Enables tool search with the specified query and topK.

参数Parameters

名称Name	类型Type	说明Description
`query`	String	查询文本（类型 `String`）。the search query describing what tools are needed
`topK`	int	top K（类型 `int`）。the maximum number of tools to return (must be positive)

返回Returns HigressMcpClientBuilder

返回HigressMcpClientBuilder。this builder for method chaining

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if topK is not positive

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:277–285

buildAsync

public Mono<HigressMcpClientWrapper> buildAsync()

构建异步。

Builds an asynchronous HigressMcpClientWrapper instance.

返回Returns Mono<HigressMcpClientWrapper>

返回Mono。Mono emitting the configured HigressMcpClientWrapper instance

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if endpoint is not configured
IllegalStateException 可能抛出 `IllegalStateException`。if transport type is not configured

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:311–332

buildSync

public HigressMcpClientWrapper buildSync()

构建同步。

Builds a synchronous HigressMcpClientWrapper instance (blocking operation).

返回Returns HigressMcpClientWrapper

返回HigressMcpClientWrapper。configured and initialized HigressMcpClientWrapper instance

抛出Throws

IllegalArgumentException 可能抛出 `IllegalArgumentException`。if endpoint is not configured
IllegalStateException 可能抛出 `IllegalStateException`。if transport type is not configured

源码Source io/agentscope/extensions/higress/HigressMcpClientBuilder.java:357–379