feat(mcp): expose protocolVersions configuration in McpClientBuilder

[BeastDamon]

AgentScope-Java Version

1.0.12-SNAPSHOT (main branch)

Description

When connecting to third-party MCP servers via stdio transport, the client fails with "Unsupported protocol version" if the server responds with a protocol version other than "2024-11-05". For example, CodeGraphContext returns "protocolVersion": "2025-03-26" in its initialize response.

The root cause is that McpTransport.protocolVersions() defaults to List.of("2024-11-05") only, and LifecycleInitializer.doInitialize() performs a strict protocolVersions.contains(result.protocolVersion()) check. Neither the MCP Java SDK's McpClient builder nor AgentScope's McpClientBuilder exposes this configuration to users.

The MCP protocol is actively evolving (4 versions already defined in ProtocolVersions.java), making hardcoded single-version lists increasingly problematic for third-party server integration.

This PR adds a protocolVersions(String...) method to McpClientBuilder:

McpClientWrapper client = McpClientBuilder.create("server")
        .stdioTransport("python", "server.py")
        .protocolVersions("2024-11-05", "2025-03-26")
        .buildAsync()
        .block();

Implementation uses a ProtocolVersionOverrideTransport decorator that wraps any McpClientTransport and overrides protocolVersions(). This approach:

• Works with all transport types (StdIO, SSE, StreamableHTTP)
• Is non-breaking — existing behavior is preserved when protocolVersions() is not called
• Requires no changes to the upstream MCP Java SDK

Files changed:

File	Change
McpClientBuilder.java	New protocolVersions() builder method + ProtocolVersionOverrideTransport inner class
McpClientBuilderTest.java	10 new test cases covering single/multiple versions, validation, all transports
docs/en/task/mcp.md	English documentation for Protocol Version Configuration
docs/zh/task/mcp.md	Chinese documentation for Protocol Version Configuration

How to test:

mvn test -pl agentscope-core -Dtest=McpClientBuilderTest
# 108 tests run, 0 failures, 0 errors

Closes #1173

Checklist

• Code has been formatted with mvn spotless:apply
• All tests are passing (mvn test)
• Javadoc comments are complete and follow project conventions
• Related documentation has been updated (e.g. links, examples, etc.)
• Code is ready for review

[CLAassistant]

All committers have signed the CLA.

[codecov]

Codecov Report

❌ Patch coverage is 71.42857% with 6 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
.../io/agentscope/core/tool/mcp/McpClientBuilder.java	71.42%	6 Missing ⚠️

📢 Thoughts on this report? Let us know!