## 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工具

```java
@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度");
    }
}
```

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

| 服务端                   | 客户端         |  备注               |
|-----------------------|-------------|-----------------|
| STDIO                 | STDIO       |                 |
| SSE                   | SSE         |                 |
| STREAMABLE            | STREAMABLE  |                 |
| STREAMABLE_STATELESS  | STREAMABLE  | 对 server 集群很友好  |


* 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，升级后会造成不兼容



```java
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）

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

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

```java
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();
```