fix: Fixed the issue where the returnDirect attribute was not effective on the MCP server side.

[sunyuhan1998]

Background

Before this PR, when using the @Tool annotation to define tools on the MCP server side and specifying the returnDirect attribute, the attribute would not be properly propagated. As a result, the client was unable to retrieve this information. For a detailed discussion and root cause analysis of this issue, please refer to: #3481 .

Thanks to the merge of PR #3781 , we now have the foundation to fix this problem.

---

Changes in This PR

1. Preserve the returnDirect Attribute
   Adjusted the logic in the McpToolUtils class that constructs tool declarations, ensuring that the returnDirect attribute from the @Tool annotation is correctly retained and passed through.

2. Implemented getToolMetadata Method
   Added implementations of the getToolMetadata method in both AsyncMcpToolCallback and SyncMcpToolCallback classes. This enables clients to retrieve tool metadata, including the returnDirect flag.

3. Added Unit Tests
   Included corresponding unit tests to verify the correctness and stability of the above changes.

Fixes: #3481

[ilayaperumalg]

@sunyuhan1998 Thanks for the quick follow up on this!

[KallivdH]

Will this fix be added to the 1.1.0.M3 pre-release @markpollack ?

[ilayaperumalg]

Hi @sunyuhan1998 Sorry about the delay in getting to this. Having the returnDirect as MCP schema ToolAnnotations attribute in the MCP JavaSDK is rather invasive as the MCP spec and its implementation shouldn't know anything about Spring AI's behaviour. We need to find a better approach to handle returnDirect instead of the current MCP Schema ToolAnnotations. What do you think?

[sunyuhan1998]

Hi @sunyuhan1998 Sorry about the delay in getting to this. Having the returnDirect as MCP schema ToolAnnotations attribute in the MCP JavaSDK is rather invasive as the MCP spec and its implementation shouldn't know anything about Spring AI's behaviour. We need to find a better approach to handle returnDirect instead of the current MCP Schema ToolAnnotations. What do you think?

You're right. At the time this PR was conceived and submitted, the mcp-annotations project hadn't yet introduced the @McpTool annotation. Currently, @McpTool is strictly implemented according to the MCP specification and does not include any logic related to returnDirect. I suspect that using the @Tool annotation on the MCP server side early on was perhaps a workaround or a shortcut? I'm curious about our future plans for balancing the capabilities of @McpTool and @Tool on the MCP server side. Do we intend to gradually phase out the use of @Tool for defining tools in the MCP server going forward?

[ilayaperumalg]

@sunyuhan1998 We intend to use @McpTool for the tools specific to MCP servers while the Spring AI @Tool for non MCP tools. But, currently, for backwards compatibility and the ease of use, we support both the options.

Do we intend to gradually phase out the use of @tool for defining tools in the MCP server going forward?

I agree. This could be something in Spring AI 2.0 cc @tzolov

[sunyuhan1998]

@sunyuhan1998 We intend to use @McpTool for the tools specific to MCP servers while the Spring AI @Tool for non MCP tools. But, currently, for backwards compatibility and the ease of use, we support both the options.

Do we intend to gradually phase out the use of @tool for defining tools in the MCP server going forward?

I agree. This could be something in Spring AI 2.0 cc @tzolov

Thank you for your explanation. I understand now. If that's the case, does it mean the issue we've been discussing in this PR no longer needs to be followed up on? Should I close this PR?

[ilayaperumalg]

@sunyuhan1998 Yes, please. Let's close this PR.

[KallivdH]

Thank you for following up!

Hi @sunyuhan1998 Sorry about the delay in getting to this. Having the returnDirect as MCP schema ToolAnnotations attribute in the MCP JavaSDK is rather invasive as the MCP spec and its implementation shouldn't know anything about Spring AI's behaviour. We need to find a better approach to handle returnDirect instead of the current MCP Schema ToolAnnotations. What do you think?

@sunyuhan1998 The audience annotation look like a right fit for the returnDirect functionality. For example, if audience user is specified.