v3.8.0 SolonMcp 更新与兼容说明

v3.8.0 更新与兼容说明

重要变化：

• mcp-java-sdk 升为 v0.17 （支持 2025-06-18 版本协议）
• 添加 mcp-server McpChannel.STREAMABLE_STATELESS 通道支持（集群友好）
• 添加 mcp-server 异步支持

具体更新：

• 添加 solon-ai FunctionPrompt:handleAsync（用于 mcp-server 异步支持）
• 添加 solon-ai FunctionResource:handleAsync（用于 mcp-server 异步支持）
• 添加 solon-ai FunctionTool:handleAsync（用于 mcp-server 异步支持）
• 添加 solon-ai-core ChatMessage:toNdjson,fromNdjson 方法（替代 ChatSession:toNdjson, loadNdjson），新方法机制上更自由
• 添加 solon-ai-core ToolSchemaUtil.jsonSchema Publisher 泛型支持
• 添加 solon-ai-mcp mcp-java-sdk v0.17 适配（支持 2025-06-18 版本协议）
• 添加 solon-ai-mcp mcp-server 异步支持
• 添加 solon-ai-mcp mcp-server streamable_stateless 支持
• 添加 solon-ai-mcp Tool,Resource,Prompt 对 org.reactivestreams.Publisher<X> 异步返回支持
• 添加 solon-ai-mcp McpServerHost 服务宿主接口，用于隔离有状态与无状态服务
• 添加 solon-ai-mcp McpChannel.STREAMABLE_STATELESS （服务端）无状态会话
• 添加 solon-ai-mcp McpClientProvider:customize 方法（用于扩展 roots, sampling 等）
• 添加 solon-ai-mcp mcpServer McpAsyncServerExchange 注入支持（用于扩展 roots, sampling 等）
• 优化 solon-ai-dialect-openai claude 兼容性
• 优化 solon-ai-mcp mcp StreamableHttp 模式下 服务端正常返回时 客户端异常日志打印的情况
• 调整 solon-ai-mcp getResourceTemplates、getResources 不再共享注册
• 调整 solon-ai-mcp McpServerManager 内部接口更名为 McpPrimitivesRegistry （MCP 原语注册器）
• 调整 solon-ai-mcp McpClientProvider 默认不启用心跳机制（随着 mcp-sdk 的成熟，server 都有心跳机制了）

新特性展示：1.MCP 无状态会话（STREAMABLE_STATELESS）和 2.CompletableFuture 异步MCP工具

@McpServerEndpoint(channel = McpChannel.STREAMABLE_STATELESS, mcpEndpoint = "/mcp1")
public class McpServerTool {
    @ToolMapping(description = "查询天气预报", returnDirect = true)
    public CompletableFuture<String> getWeather(@Param(description = "城市位置") String location) {
        return CompletableFuture.completedFuture("晴，14度");
    }
}

传输方式对应表：（服务端与客户端，须使用对应的传输方式才可通讯）

• STREAMABLE_STATELESS 集群，不需要 ip_hash，但“原语”变化后无法通知 client

v3.5.3（修复问题，并优化兼容性）

1、更新说明

• 优化 solon-ai-core chatModel.stream 与背压处理的兼容性
• 调整 solon-ai-map getPrompt,readResource,callTool 取消自动异常转换（侧重原始返回）
• 调整 solon-ai-map callTool 错误结果传递，自动添加 'Error:' （方便 llm 识别）
• 修复 solon-ai-mcp callTool isError=true 时，不能正常与 llm 交互的问题
• 修复 solon-ai-mcp ToolAnnotations:returnDirect 为 null 时的传递兼容性

Solon 配套的更新参考：

• 优化 solon-rx 确保 SimpleSubscriber:doOnComplete 只被运行一次（之前可能会被外部触发多次）
• 优化 solon-rx SimpleSubscriber 改为流控模式（只请求1，之前请求 max）//所有相关的都要测试
• 优化 solon-net-httputils 确保 TextStreamUtil:onSseStreamRequestDo 只会有一次触发 onComplete
• 优化 solon-web-rx RxSubscriberImpl 改为流控模式（只请求1，之前请求 max）//所有相关的都要测试
• 优化 solon-net-httputils sse 与背压处理的兼容性
• 修复 solon-net-httputils JdkHttpResponse:contentEncoding 不能获取 charset 的问题（并更名为 contentCharset，原名标为弃用）

v3.5.2

1、更新说明

• 添加 solon-ai-core ToolSchemaUtil 简化方法
• 添加 solon-ai-mcp McpClientProperties:timeout 属性，方便简化超时配置（可省略 httpTimeout, requestTimeout, initializationTimeout）
• 添加 solon-ai-mcp McpClientProvider:toolsChangeConsumer,resourcesChangeConsumer,resourcesUpdateConsumer,promptsChangeConsumer 配置支持
• 添加 solon-ai-mcp McpClientProvider 缓存锁和变更刷新控制
• 调整 solon-ai-core FunctionToolDesc:doHandle 改用 ToolHandler 参数类型（之前为 Function），方便传递异常

v3.5.1

1、更新说明

• 添加 solon-ai-mcp McpServerEndpointProvider:Builder 添加 context-path 配置
• 优化 solon-ai-mcp McpClientProvider 配置向 McpServers json 格式上靠
• 修复 solon-ai-core think-> tool -> think 时，工具调用的内容无法加入到对话的问题
• 修复 solon-ai-mcp 服务端传输层的会话长连会超时的问题
• 修复 solon-ai-mcp 客户端提供者心跳失效的问题
• 修复 solon-ai-mcp SSE 传输时 message 端点未附加 context-path 的问题
• mcp McpSchema:*Capabilities 添加 @JsonIgnoreProperties(ignoreUnknown = true) 增强跨协议版本兼容性

v3.5.0

1、更新说明

• 新增 solon-ai-mcp MCP_2025-03-26 版本协议支持
• 调整 solon-ai-mcp channel 取消默认值（之前为 sse），且为必填（为兼容过度，有明确的开发时、启动时提醒）
  • 如果默认值仍为 sse ，升级后可能忘了修改了升级
  • 如果默认值改为 streamable，升级后会造成不兼容

public interface McpChannel {
    String STDIO = "stdio";
    String SSE = "sse";               //MCP官方已标为弃用
    String STREAMABLE = "streamable"; //新增（MCP_2025-03-26 版本新增）
}

2、兼容说明

• channel 取消默认值（之前为 sse），且为必填

提醒：SSE 与 STREAMABLE 不能互通（升级时，要注意这点）

3、应用示例

for server （如果 channel 不加，默认为 streamable。之前默认为 sse）

@McpServerEndpoint(channel=McpChannel.STREAMABLE, mcpEndpoint = "/mcp") 
public class McpServerTool {
    @ToolMapping(description = "查询天气预报")
    public String getWeather(@Param(description = "城市位置") String location) {
        return "晴，14度";
    }
}

client （如果 channel 不加，默认为 streamable。之前默认为 sse）

McpClientProvider mcpClient = McpClientProvider.builder()
            .channel(McpChannel.STREAMABLE)
            .apiUrl("http://localhost:8081/mcp")
            .build();

//测试
String resp = mcpClient.callToolAsText("getWeather", Utils.asMap("location", "杭州")).getContent();
System.out.println(resp);


//对接 LLM
ChatModel chatModel = ChatModel.of(apiUrl).provider(...).model(...)
                .defaultToolsAdd(mcpClient) //绑定 mcp 工具
                .build();

ChatResponse resp = chatModel
        .prompt("今天杭州的天气情况？")
        .call();