openJiuwen agent-core-java MCP 客户端体系：SSE / stdio / streamable-http / OpenAPI / Playwright 的注册与使用指南-育师

人工智能
AI Agent
Agent 框架
工具调用
Agent 工作流
RAG
MCP Clients
强化学习

【免费下载链接】agent-core-java

openJiuwen agent core Java是 openJiuwen Core的 Java版本，提供AI Agent开发、运行、调优与演进相关的全套SDK能力。

项目地址：https://gitcode.com/openJiuwen/agent-core-java

导读

com.openjiuwen.core.foundation.tool.mcp.client是 openJiuwen agent-core-java 中面向 Model Context Protocol（MCP）的客户端实现集合，覆盖基于 HTTP JSON-RPC、SSE、stdio 以及从 OpenAPI 规范派生工具等五种接入形态。本文以该包的结构为主线，先梳理统一的McpClient接口契约与McpServerConfig配置模型，再逐一解析五种客户端的实现要点，最后说明 SDK 如何通过McpClients.registerDefaults()把客户端工厂注册进全局ClientRegistry，并给出结合ResourceMgr/ToolManager的注册路径与直接使用ClientRegistry的两种接入方式。读完本文，你将掌握在 Java 侧为 Agent 接入各类 MCP Server 的配置方法、clientType 归一化规则，以及各传输形态在源码层面的工作机理。

一、包结构与类型总览

client.README.md（documents/zh/2.开发指南/API文档/com.openjiuwen.core/foundation/tool/mcp/client.README.md）给出了本包的顶层索引，包内提供以下六种公开类型：

类型	说明
`OpenApiClient`	从本地 OpenAPI JSON/YAML 文件生成工具卡片，并可直接发起 HTTP 调用
`PlaywrightClient`	按`serverPath`自动在`SseClient`与`StdioClient`之间选择委托实现
`SseClient`	基于 SSE 风格的 MCP 客户端
`StdioClient`	通过`Content-Length`分帧 JSON-RPC 与本地子进程通信
`StreamableHttpClient`	面向 streamable-http 服务端的 HTTP JSON-RPC 客户端
`McpClients`	MCP 客户端注册门面，把默认 transport 注册到全局`ClientRegistry`

这些实现类的源码位于 core/src/main/java/com/openjiuwen/core/foundation/tool/mcp/client/ 目录。除公开类型外，包内还存在一个不作为公开文档页输出的抽象基类AbstractHttpMcpClient（源码见 AbstractHttpMcpClient.java），它是 HTTP 类传输的公共骨架。

说明：包内各实现类在代码注释中明确标注了其 Python 对应实现（如stdio_client.py、openapi_client.py、sse_client.py），本包是 openJiuwen Python 版 MCP client 体系的 Java 移植，接口语义保持一致。

二、统一契约：McpClient 接口

所有客户端实现都遵循McpClient接口（McpClient.java），该接口定义了"连接、断开、列出工具、调用工具、查询工具信息"的最小能力集：

方法	说明
`boolean connect(int retryTimes, float timeout)`	建立到 MCP 服务端的连接，可指定重试次数与超时（秒）
`default boolean connect()`	使用默认参数连接：重试 1 次、无超时
`boolean disconnect(float timeout)`	断开连接
`default boolean disconnect()`	使用无超时参数断开
`List<Object> listTools(float timeout)`	列出服务端暴露的工具元数据
`default List<Object> listTools()`	使用无超时参数列出工具
`Object callTool(String toolName, Map<String, Object> arguments, float timeout)`	按工具名发起调用
`default Object callTool(String toolName, Map<String, Object> arguments)`	使用无超时参数调用工具
`Optional<Object> getToolInfo(String toolName, float timeout)`	查询单个工具信息
`default Optional<Object> getToolInfo(String toolName)`	使用无超时参数查询
`String getServerPath()`	返回客户端对应的服务端路径

从源码看，接口在connect、listTools、callTool等默认重载之外，还补充了reconnect(float timeout)与reconnect()默认实现（先disconnect再connect，重试 1 次），以及listResources(float timeout)、readResource(String uri, float timeout)两个资源类方法的默认空实现。也就是说，各实现类可以只实现核心工具方法，资源能力按需覆盖——例如OpenApiClient的listResources固定返回空列表，而StdioClient与SseClient则真实实现了resources/list与resources/read的转发。

所有默认重载均基于McpServerConfig.NO_TIMEOUT（常量为-1.0F）作为"无超时"哨兵值，详见下文配置模型。

三、配置模型：McpServerConfig

McpServerConfig（McpServerConfig.java）是 MCP 服务端的配置对象，描述服务端标识、访问路径、客户端类型以及认证附加参数。源码通过 Builder 与 setter 提供两种构造方式，显式字段如下：

字段	类型	默认值	说明
`serverId`	`String`	优先取`serverName`，否则随机 UUID（去横线）	服务端唯一标识
`serverName`	`String`	`null`	服务端显示名称
`serverPath`	`String`	`null`	服务端路径或 URL
`clientType`	`String`	`"sse"`	客户端类型
`params`	`Map<String, Object>`	空`HashMap`	附加参数，例如 stdio 命令、环境变量或 OpenAPI 额外配置
`authHeaders`	`Map<String, String>`	空`HashMap`	认证请求头
`authQueryParams`	`Map<String, String>`	空`HashMap`	认证查询参数
`connectTimeoutSeconds`	`Double`	`null`	连接超时（秒），HTTP 类客户端读取
`callTimeoutSeconds`	`Double`	`null`	调用超时（秒）
`NO_TIMEOUT`	`float`	`-1`	无超时常量

几个值得注意的源码细节：

serverId自动生成：当serverId为空时，normalizeServerId()会优先回退到serverName，只有两者都缺失时才生成随机 UUID（无横线）。这一语义与文档描述一致。
clientType归一化：clientType会在 MCP Server 注册路径上做归一化后用于ClientRegistry查询，但原始配置对象中的字段值不会被改写（配置对象原样保留，归一化只发生在查询键的构造上）。支持的主要clientType包括sse、stdio、streamable-http、openapi、playwright，具体别名映射见第五节。
配置比较与日志脱敏：源码还提供了sameConnectionAs(...)（比较 serverId、serverName、serverPath 与归一化 clientType）和toMaskedDescription()——后者只输出认证头/查询参数的名字而非值，避免凭证泄漏到日志，这一细节在接入需要鉴权的远端 MCP Server 时尤其重要。

一个典型的 Builder 构造示例（来自McpClientsTest的用法）：

McpServerConfig config = McpServerConfig.builder() .serverId("registry-srv") .serverName("registry") .serverPath("http://127.0.0.1:3001/mcp") .clientType("streamable-http") .build();

四、五种客户端实现解析

4.1 SseClient：面向 SSE 服务端

SseClient（SseClient.java）以构造方法public SseClient(McpServerConfig config)创建，用于接入 SSE 风格的 MCP 服务端。

源码实现要点：

底层借助官方 MCP Java SDK 的HttpClientSseClientTransport构建传输，并用McpSyncClient封装同步会话；连接时若未指定超时，默认回退到DEFAULT_SSE_TIMEOUT_SECONDS = 60.0秒。
连接成功后执行initialize握手，listTools/callTool等操作会把远端返回的McpSchema.Tool等对象转换为带serverName/serverId的McpToolCard。
认证触发：connect时会通过AuthCallback.unifiedAuthHandler(...)触发TOOL_AUTH事件，从认证结果中提取auth_provider（实现AuthHeaderAndQueryProvider的对象），随后把其头信息注入 SSE 请求、把查询参数合并进 URL，实现鉴权接入。
自愈重连：listTools/callTool遇到可重试的传输错误（如connection reset、broken pipe、connection closed）时，会先reconnect一次再重放操作。

根据 SseClient.md 的说明，本类没有新增公开方法，公共连接与调用能力全部继承自McpClient接口契约。测试见 SseClientTest.java。

4.2 StdioClient：Content-Length 分帧的本地子进程客户端

StdioClient（StdioClient.java）通过Content-Length分帧的 JSON-RPC 协议与本地子进程通信，是接入本地 MCP Server 可执行文件（如python、java启动的 MCP 服务）的标准形态。

字段与公开方法：

字段	类型	默认值	说明
`config`	`McpServerConfig`	`-`	客户端配置
`requestCounter`	`AtomicLong`	`new AtomicLong()`	JSON-RPC 请求编号
`process`	`Process`	`null`	启动后的子进程
`stdout`	`BufferedInputStream`	`null`	读取子进程标准输出
`stdin`	`BufferedOutputStream`	`null`	写入子进程标准输入

方法	说明
`public boolean connect(int retryTimes, float timeout)`	按`params.command`或`serverPath`启动子进程，并尝试发送`initialize`请求
`public boolean disconnect(float timeout)`	关闭输入输出流并终止子进程
`public List<Object> listTools(float timeout)`	请求`tools/list`并把结果转成`McpToolCard`列表
`public Object callTool(String toolName, Map<String, Object> arguments, float timeout)`	请求`tools/call`
`public Optional<Object> getToolInfo(String toolName, float timeout)`	通过`listTools(...)`过滤目标工具
`public String getServerPath()`	返回配置中的`serverPath`

源码实现要点：

帧协议：JsonRpcProcessSession.writeFrame直接向 stdin 写入 JSON 并以换行结尾；readFrame则兼容两种读取方式——若行以content-length:开头则按头部解析后readNBytes(contentLength)读取定长 body，否则按换行分隔的 JSON 行解析。读取响应时会循环跳过不匹配当前请求id的帧，正确处理服务端主动推送的消息（如ping会回写result，未知方法回写-32601错误）。
初始化握手：initialize发送protocolVersion = "2024-11-05"、clientInfo = {name: "agent-core-java", version: ...}，随后发送notifications/initialized通知。
参数注入：params.args可追加命令行参数，params.env可注入环境变量，params.cwd可指定工作目录；params.encoding_error_handler支持strict/ignore/replace（非法值回退strict）。
安全约束：命令解析有一套明确的校验链——默认允许的命令白名单仅包含java、python、python3及各自.exe变体；若serverPath显式声明了命令，则要求实际请求的命令与其toRealPath()解析结果一致，否则抛出SecurityException（详见resolveAllowedCommand与resolveDefaultAllowedCommand）。启动前还会校验可执行文件存在且可执行，命令含\0非法字符会直接拒绝。
超时控制：正值超时通过独立 reader 线程 +Future.get实现，超时后清理子进程并把 stderr 尾部（最多 8192 字符）拼进异常信息辅助排障。
stderr 引流：子进程 stderr 由守护线程持续引流，避免管道写满导致子进程阻塞，同时保留诊断尾部。

对应文档 StdioClient.md，测试见 StdioClientTest.java。

4.3 StreamableHttpClient：streamable-http 服务端客户端

StreamableHttpClient（StreamableHttpClient.java）面向 streamable-http 传输的 MCP 服务端，是当前 MCP 规范推荐演进方向之一的 HTTP JSON-RPC 形态。它以public StreamableHttpClient(McpServerConfig config)创建，另提供了StreamableHttpClient(String serverPath)等便捷构造。

源码实现要点：

底层使用HttpClientStreamableHttpTransport，连接默认超时DEFAULT_TIMEOUT_SECONDS = 60.0F秒；认证逻辑通过AuthStrategyRegistry.executeAuth(...)获取AuthHeaderAndQueryProvider，随后注入请求头并把查询参数附加到 endpoint。
有界超时执行：凡是调用方传入正数超时的操作，都提交到一个有界线程池（核心 8、最大 192、SynchronousQueue交接队列）执行，超时统一表现为HttpTimeoutException；NO_TIMEOUT哨兵或非正数则内联执行。
重试感知的超时预算：retryAwareTimeout会把外层硬预算放大到调用方超时的 2 倍，以容纳"传输错误→重连→重放"的两次尝试，避免第一次慢请求吃掉重试机会（源码注释对此有明确解释）。
URL 解析会把serverPath拆成 base URI 与 endpoint 两部分，方便HttpClientStreamableHttpTransport.builder(baseUri).endpoint(...)使用。

对应文档 StreamableHttpClient.md，测试见 StreamableHttpClientTest.java。

4.4 OpenApiClient：从 OpenAPI 规范派生工具

OpenApiClient（OpenApiClient.java）是一个特殊形态：它不连接远端 MCP 服务端，而是读取本地 OpenAPI JSON/YAML 规范，把每个接口操作转换为McpToolCard，并可按生成的参数结构直接发起 HTTP 请求。

字段与公开方法：

字段	类型	默认值	说明
`config`	`McpServerConfig`	`-`	当前客户端配置
`httpClient`	`HttpClient`	`HttpClient.newHttpClient()`	发起 HTTP 请求的客户端
`operations`	`Map<String, Operation>`	`new LinkedHashMap<>()`	已加载的工具操作定义
`usedNames`	`Map<String, Integer>`	`new HashMap<>()`	用于消除工具名冲突的计数器

方法	说明
`public boolean connect(int retryTimes, float timeout)`	清空已有状态，读取`serverPath`中逗号分隔的多个规范文件并装载操作
`public boolean disconnect(float timeout)`	清空已加载操作并返回`true`
`public List<Object> listTools(float timeout)`	返回当前已加载操作对应的`McpToolCard`列表
`public Object callTool(String toolName, Map<String, Object> arguments, float timeout)`	按工具名解析操作，替换路径参数，并以 GET 查询串或 JSON 请求体调用远端接口
`public Optional<Object> getToolInfo(String toolName, float timeout)`	返回单个工具卡片信息
`public String getServerPath()`	返回配置中的`serverPath`
`public static Map<String, Object> loadConf(String filePath)`	读取并解析`.json`、`.yaml`或`.yml`格式的 OpenAPI 文件

源码实现要点：

多文件装载：connect会把serverPath按逗号拆分成多个规范文件路径依次加载，因此一个配置即可注册多个 OpenAPI 接口集。
文件安全校验：loadConf(...)要求路径存在、为普通文件且不能是符号链接；支持~开头的主目录展开；扩展名仅接受.json/.yaml/.yml，且解析结果必须是Map类型（dict），否则抛出TOOL_OPENAPI_CLIENT_EXECUTION_ERROR。
工具名生成与去冲突：工具名优先取operationId（按__切分取首段），其次取summary，兜底为HTTP方法_路径，长度超过 64 截断；当工具名冲突时，会在原名后追加_2、_3等后缀（usedNames计数器实现）。
入参 Schema 构建：buildInputSchema会合并 OpenAPIparameters（path/query/header 参数）与requestBody的 content schema，解析$ref引用，标记必填项，最终生成{type: "object", properties, required}形式的输入 Schema。
请求执行：callTool时先解析出baseUrl（优先取servers[0].url，可用params.base_url覆盖，并去掉尾部斜杠），把{param}路径模板替换为 URL 编码后的实参；请求体中的路径参数会在真正发送前移除（bodyArgs.remove(pathParam)），避免同时出现在 URL 与 JSON body 中；GET 方法把剩余参数拼成查询串，其他 HTTP 方法以 JSON body 发送。输出 Schema 从responses中的 200/201（或任意 2xx）响应内容中提取。
支持的标准 HTTP 方法集合为get / put / post / delete / options / head / patch / trace。

对应文档 OpenApiClient.md，测试见 OpenApiClientTest.java。

4.5 PlaywrightClient：自动选择委托实现的门面

PlaywrightClient（PlaywrightClient.java）是 Playwright MCP 客户端门面，根据McpServerConfig.serverPath的前缀在SseClient与StdioClient之间自动选择实际委托对象。

字段	类型	默认值	说明
`delegate`	`McpClient`	`-`	实际承担调用的客户端

方法	说明
`public boolean connect(int retryTimes, float timeout)`	委托到底层客户端
`public boolean disconnect(float timeout)`	委托到底层客户端
`public List<Object> listTools(float timeout)`	委托到底层客户端
`public Object callTool(String toolName, Map<String, Object> arguments, float timeout)`	委托到底层客户端
`public Optional<Object> getToolInfo(String toolName, float timeout)`	委托到底层客户端
`public String getServerPath()`	返回底层客户端的服务端路径

源码实现要点：

传输选择规则：构造时若serverPath以http://或https://开头则委托SseClient，否则委托StdioClient；此外params中的stdio_server_parameters（ServerParameters对象）或server_path键可以显式覆盖默认取值来源（rawServerPath()的优先级为params.stdio_server_parameters→params.server_path→config.getServerPath()）。
底层同样是McpSyncClient+HttpClientSseClientTransport/StdioClientTransport，统一完成初始化握手、工具列表与调用。

对应文档 PlaywrightClient.md，测试见 PlaywrightClientTest.java。

五、注册机制：McpClients 与 ClientRegistry

5.1 为什么需要显式注册

Java 版没有 PythonBaseClient.__init_subclass__形式的"类定义时自动注册"机制。因此 SDK 通过McpClients.registerDefaults()显式注册 MCP 客户端工厂（McpClients.java），使ResourceMgr与ToolManager可以继续按McpServerConfig.clientType走全局ClientRegistry创建客户端。

registerDefaults()是一个synchronized的幂等操作：每次注册前先通过listClients()检查mcp_<name>键是否已存在，已存在则跳过，因此重复调用不会报"已注册"异常（McpClientsTest.registerDefaultsRegistersAllMcpClientFactoriesIdempotently对此有专门验证）。

默认注册项如下：

`ClientRegistry`key	实现
`mcp_sse`	`SseClient`
`mcp_stdio`	`StdioClient`
`mcp_streamable-http`	`StreamableHttpClient`
`mcp_streamable_http`	`StreamableHttpClient`
`mcp_openapi`	`OpenApiClient`
`mcp_playwright`	`PlaywrightClient`

从源码看，registerIfMissing通过ClientRegistry.registerClient(name, "mcp", factory)注册，ClientRegistry内部会拼出完整键mcp_<name>存入工厂表（ClientRegistry.java）。注意streamable-http与streamable_http两个别名被同时注册且指向同一实现类，这正是McpClientsTest中同时断言mcp_streamable-http与mcp_streamable_http两个键存在的原因。

5.2 clientType 归一化规则

McpClients.normalizeClientType(String clientType)是注册查询的关键入口，其归一化算法在源码中清晰可见：

null或全空白字符串 →sse（默认类型）；
去除首尾空白；
把驼峰式拆成连字符（streamableHttp→streamable-http），统一转小写，并把下划线替换为连字符（STREAMABLE_HTTP→streamable-http）；
去掉mcp-前缀（mcp_stdio→stdio）；
对结果做最终映射：open-api→openapi，其余保留。

代表性映射：

输入示例	归一化结果
`null`、空字符串	`sse`
`SSE`、`mcp_SSE`	`sse`
`stdio`、`mcp_stdio`	`stdio`
`streamable_http`、`streamableHttp`、`STREAMABLE_HTTP`	`streamable-http`
`mcp_streamable_http`、`mcp-streamable-http`	`streamable-http`
`open-api`	`openapi`
`playwright`	`playwright`

上述映射均有McpClientsTest.normalizeClientTypeSupportsCommonAliases的断言背书，也就是说配置里写SSE、streamableHttp或mcp_streamable_http都能正确命中注册的工厂。

5.3 工厂的 kwargs 契约

每个注册的工厂都要求kwargs中包含config键，且值必须是McpServerConfig。McpClients.requiredConfig(...)会对不符合的值抛出IllegalArgumentException，错误信息形如：

MCP client factory requires kwargs['config'] to be McpServerConfig, actual: <实际类型>

McpClientsTest.registryFactoryRejectsMissingOrWrongConfig同时验证了缺config与传错类型（如字符串）两种情况都会被拒绝。

5.4 直接使用 ClientRegistry

如果业务代码直接通过ClientRegistry.getClient(name, "mcp", kwargs)创建 MCP client，应先调用McpClients.registerDefaults()。典型用法：

McpClients.registerDefaults(); McpServerConfig config = McpServerConfig.builder() .serverId("my-srv") .serverName("my-server") .serverPath("http://127.0.0.1:3001/mcp") .clientType("streamable-http") .authHeaders(Map.of("Authorization", "Bearer <token>")) .build(); // 通过注册表按 clientType 动态创建客户端 McpClient client = (McpClient) ClientRegistry.getClientRegistry() .getClient(McpClients.normalizeClientType(config.getClientType()), "mcp", Map.of("config", config)); client.connect(); List<Object> tools = client.listTools(); Object result = client.callTool("someTool", Map.of("param", "value")); client.disconnect();

创建出的实例类型与McpClientsTest.registryFactoriesCreateConcreteClientsFromMcpServerConfig的断言一致：sse→SseClient、stdio→StdioClient、streamable-http/streamable_http→StreamableHttpClient、openapi→OpenApiClient、playwright→PlaywrightClient。

六、与 ResourceMgr / ToolManager 的集成路径

在 SDK 的更高层，MCP Server 的注册是通过ResourceMgr.addMcpServer(McpServerConfig)系列方法（支持单个、批量以及异步变体）进入的，见 ResourceMgr.java。其内部ToolManager在创建客户端时（ToolManager.java 的defaultCreateClient）遵循如下策略：

优先尝试com.openjiuwen.core.foundation.tool.mcp.McpClientFactory.create(config)（SPI 工厂 / 显式注册）；
若 SPI 工厂不支持（抛出UnsupportedOperationException），则回退到McpClients.registerDefaults()+ClientRegistry.getClient(normalizeClientType(...), "mcp", Map.of("config", config))。

也就是说，ResourceMgr与ToolManager的 MCP Server 注册路径会确保默认 MCP client 已注册，业务代码通常无需手动调用registerDefaults()；只有直接使用ClientRegistry时才需要先注册。注册完成后，ToolManager会调用客户端的listTools拿到McpToolCard列表，为每个工具分配全局唯一的serverId_serverName_toolName形式的工具 id，并用McpTool包装成本地Tool供上层统一调用（McpTool会把远端异常转换为TOOL_MCP_EXECUTION_ERROR，且其stream方法固定抛出TOOL_STREAM_NOT_SUPPORTED，详见 McpTool.java 与 McpToolCard.java）。

在 examples 侧，仓库提供了对应的 MCP 接入示例基线（examples/mcp/README.md），覆盖openapi、sse、stdio、streamable_http、playwright五种形态的McpServerConfig构造示例，并可用mvn -Dtest=McpExampleSupportTest test验证。

七、选型建议与使用要点

场景	推荐 clientType	说明
远端 MCP Server（HTTP + SSE）	`sse`	默认类型，适合大多数托管 MCP 服务
本地可执行文件型 MCP Server	`stdio`	启动子进程，注意命令白名单与`params.args`/`params.env`/`params.cwd`
支持 streamable-http 的新式服务端	`streamable-http`	HTTP JSON-RPC 形态，具备有界超时与自愈重连
已有 OpenAPI 规范的 HTTP 服务	`openapi`	无需 MCP 服务端即可把接口转成 Agent 工具
Playwright 浏览器自动化	`playwright`	自动在 SSE / stdio 间选择

使用要点归纳：

配置对象统一使用McpServerConfig，clientType不区分大小写与连字符/下划线，别名会被归一化兼容；
认证通过authHeaders与authQueryParams下发，SSE 与 streamable-http 客户端都会在连接阶段触发统一认证流程，日志中只会出现认证键名而非凭证值；
超时：正值超时生效（stdio 超时清理子进程、streamable-http 有界线程池超时表现为HttpTimeoutException），-1（NO_TIMEOUT）表示无超时；HTTP 类客户端的 discovery 类 RPC（initialize、tools/list）在无超时参数时会回退到 30 秒默认值；
错误语义：远端 MCP 工具异常统一转为TOOL_MCP_EXECUTION_ERROR，OpenAPI 客户端错误对应TOOL_OPENAPI_CLIENT_EXECUTION_ERROR，可直接在 Agent 编排层捕获并分支处理。

参考资料

包索引：client.README.md
子文档：McpClients.md、SseClient.md、StdioClient.md、StreamableHttpClient.md、OpenApiClient.md、PlaywrightClient.md
接口与配置：McpClient.md、McpServerConfig.md、McpTool.md、McpToolCard.md
源码：client 实现目录、McpClient.java、McpServerConfig.java、ClientRegistry.java
测试：McpClientsTest.java 及各客户端测试
示例：examples/mcp/README.md