fix: configure mcp gateway tool timeout (#4783)

Author: fw-coder-tl

AGENTS.md

@@ -0,0 +1,150 @@
+# AGENTS.md - AI Assistant Guide for Spring AI Alibaba
+
+This file provides guidance for AI assistants working with the Spring AI Alibaba codebase.
+
+## Project Overview
+
+Spring AI Alibaba is a production-ready framework for building Agentic, Workflow, and Multi-agent applications. It is an implementation of the Spring AI framework tailored for Alibaba Cloud services and components. It provides a comprehensive ecosystem for developing AI-powered applications with built-in context engineering and human-in-the-loop support.
+
+**Key Features:**
+
+- Multi-Agent Orchestration with built-in patterns
+- Context Engineering with human-in-the-loop, context compaction, editing, model call limits
+- Graph-based workflow with conditional routing, nested graphs, parallel execution
+- A2A (Agent-to-Agent) support with Nacos integration
+- Rich model support (DashScope, OpenAI, DeepSeek) and MCP (Model Context Protocol)
+- One-stop visual agent platform
+
+## Repository Structure
+
+```
+spring-ai-alibaba/
+├── spring-ai-alibaba-agent-framework/ # Multi-agent framework (Sequential, Parallel, Routing, etc.)
+├── spring-ai-alibaba-graph-core/      # Runtime providing persistence, workflow orchestration, state mgmt
+├── spring-ai-alibaba-studio/          # Embedded UI for debugging agents visually
+├── spring-ai-alibaba-admin/           # One-stop Agent platform (visual dev, observability, MCP mgmt)
+├── spring-ai-alibaba-bom/             # Bill of Materials for dependency management
+├── spring-boot-starters/              # Spring Boot Starters
+│   ├── spring-ai-alibaba-starter-a2a-nacos/     # Nacos A2A communication
+│   ├── spring-ai-alibaba-starter-builtin-nodes/ # Built-in workflow nodes
+│   ├── spring-ai-alibaba-starter-config-nacos/  # Dynamic config with Nacos
+│   └── spring-ai-alibaba-starter-graph-observation/ # Observability
+├── examples/                          # Example applications
+│   ├── chatbot/                       # Chatbot example
+│   ├── deepresearch/                  # Deep research agent example
+│   └── documentation/                 # Documentation examples
+├── tools/                             # Build and linting tools
+└── docs/                              # Documentation
+```
+
+## Build System
+
+### Prerequisites
+
+- **JDK**: 17 (Required by `java.version` property)
+- **Maven**: 3.6+
+- **Git**
+
+### Common Build Commands
+
+```shell
+# Build the entire project (skip tests)
+./mvnw -B package -DskipTests=true
+
+# Build a specific module
+./mvnw -pl :spring-ai-alibaba-agent-framework -B package -DskipTests=true
+
+# Clean project
+./mvnw clean
+
+# Run tests
+./mvnw test
+
+# Run linting checks (using Makefile)
+make lint
+make licenses-check
+```
+
+## Architecture & Key Concepts
+
+### Core Components
+
+- **Agent Framework**: Built-in agents like `SequentialAgent`, `ParallelAgent`, `RoutingAgent`, `LoopAgent`.
+- **Graph Core**: Underlying engine for stateful agents, supporting persistence (PostgreSQL, MySQL, Oracle, MongoDB, Redis, File).
+- **A2A (Agent-to-Agent)**: Enables agents to seek and communicate with each other using Nacos as a registry.
+- **Admin & Studio**: Provides visual tools for developing and debugging agent workflows.
+
+### Technology Stack
+
+- **Framework**: Spring Boot 3.5.x, Spring AI 1.1.x
+- **Cloud Integration**: Alibaba Cloud DashScope, Nacos (Service Discovery & Config)
+- **Observability**: Spring Cloud Observation (Micrometer/OpenTelemetry)
+
+## Code Style & Conventions
+
+### General Guidelines
+
+- Follow **Spring AI** standard code formatting.
+- Use **Apache 2.0** license headers for all Java files.
+- **Java 17** features are encouraged (records, switch expressions, text blocks).
+- Avoid `System.out.println` - use SLF4J logging.
+- Use `final` for local variables and parameters where appropriate.
+- Use Lombok annotations (`@Data`, `@Slf4j`, etc.) to reduce boilerplate.
+
+### Linting & Formatting
+
+The project uses `make` for linting tasks:
+- `make codespell`: Checks for spelling errors.
+- `make yaml-lint`: Checks YAML file formatting.
+- `make licenses-check`: Verifies license headers.
+
+### License Header
+
+```java
+/*
+ * Copyright 2025-2026 the original author or authors.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+```
+
+## Testing
+
+### Frameworks
+
+- **JUnit 5** (`org.junit.jupiter`)
+- **Mockito**
+
+### Running Tests
+
+```shell
+# Run all tests
+./mvnw test
+
+# Run a specific test class
+./mvnw -pl :<module-name> -Dtest=<TestClassName> test
+```
+
+## Tips for AI Assistants
+
+1.  **JDK Version**: Project targets JDK 17. Use appropriate language features.
+2.  **Spring Boot**: Uses Spring Boot 3.x. Be aware of `jakarta.*` namespace vs `javax.*`.
+3.  **Dependencies**: Check `spring-ai-alibaba-bom` or parent pom for version management.
+4.  **Makefile**: Use the Makefile in the root for project maintenance tasks (linting, license checks).
+5.  **Structure**: When adding new features, prefer creating or updating modules within `spring-ai-alibaba-agent-framework` or `spring-boot-starters` depending on the scope.
+
+## Important Links
+
+- **Issues**: [https://github.com/alibaba/spring-ai-alibaba/issues](https://github.com/alibaba/spring-ai-alibaba/issues)
+- **Source**: [https://github.com/alibaba/spring-ai-alibaba](https://github.com/alibaba/spring-ai-alibaba)
+- **Contributing**: [CONTRIBUTING.md](CONTRIBUTING.md)

spring-boot-starters/spring-ai-alibaba-starter-config-nacos/src/main/java/com/alibaba/cloud/ai/agent/nacos/NacosMcpToolsInjector.java

@@ -47,7 +47,8 @@ public static McpServersVO getMcpServersVO(NacosOptions nacosOptions) {
 	public static List<ToolCallback> convert(NacosOptions nacosOptions, McpServersVO mcpServersVO) {
 
 		NacosMcpGatewayToolsInitializer nacosMcpGatewayToolsInitializer = new NacosMcpGatewayToolsInitializer(
-				nacosOptions.mcpOperationService, mcpServersVO.getMcpServers());
+				nacosOptions.mcpOperationService, mcpServersVO.getMcpServers(),
+				nacosOptions.getMcpGatewayToolTimeout());
 		return Collections.unmodifiableList(nacosMcpGatewayToolsInitializer.initializeTools());
 	}
 

spring-boot-starters/spring-ai-alibaba-starter-config-nacos/src/main/java/com/alibaba/cloud/ai/agent/nacos/NacosOptions.java

@@ -16,6 +16,7 @@
 
 package com.alibaba.cloud.ai.agent.nacos;
 
+import java.time.Duration;
 import java.util.Properties;
 
 import com.alibaba.cloud.ai.mcp.nacos.service.NacosMcpOperationService;
@@ -25,6 +26,8 @@
 import com.alibaba.nacos.maintainer.client.ai.AiMaintainerService;
 import com.alibaba.nacos.maintainer.client.ai.NacosAiMaintainerServiceImpl;
 
+import org.springframework.boot.convert.DurationStyle;
+
 public class NacosOptions {
 
 	protected boolean encrypted;
@@ -51,6 +54,8 @@ public class NacosOptions {
 
 	private String mcpNamespace;
 
+	private Duration mcpGatewayToolTimeout;
+
 	private void encryptParamInit(Properties properties) {
 		encrypted = Boolean.parseBoolean(properties.getProperty("encrypted", "false"));
 		String defaultEncrypted = String.valueOf(encrypted);
@@ -70,6 +75,7 @@ public NacosOptions(Properties properties) throws NacosException {
 		encryptParamInit(properties);
 		agentName = properties.getProperty("agentName");
 		mcpNamespace = properties.getProperty("mcpNamespace", properties.getProperty("namespace"));
+		mcpGatewayToolTimeout = parseMcpGatewayToolTimeout(properties);
 		String rawLabels = properties.getProperty("nacos.app.conn.labels", "");
 		if (StringUtils.isBlank(rawLabels)) {
 			rawLabels = "AgentName=" + agentName;
@@ -85,6 +91,19 @@ public NacosOptions(Properties properties) throws NacosException {
 
 	}
 
+	private Duration parseMcpGatewayToolTimeout(Properties properties) {
+		String timeout = properties.getProperty("mcpGatewayToolTimeout");
+		if (!StringUtils.isBlank(properties.getProperty("mcp-gateway-tool-timeout"))) {
+			timeout = properties.getProperty("mcp-gateway-tool-timeout");
+		}
+		if (StringUtils.isBlank(timeout)) {
+			return null;
+		}
+		properties.remove("mcpGatewayToolTimeout");
+		properties.remove("mcp-gateway-tool-timeout");
+		return DurationStyle.detectAndParse(timeout);
+	}
+
 	public boolean isEncrypted() {
 		return encrypted;
 	}
@@ -181,4 +200,12 @@ public void setMcpNamespace(String mcpNamespace) {
 		this.mcpNamespace = mcpNamespace;
 	}
 
+	public Duration getMcpGatewayToolTimeout() {
+		return mcpGatewayToolTimeout;
+	}
+
+	public void setMcpGatewayToolTimeout(Duration mcpGatewayToolTimeout) {
+		this.mcpGatewayToolTimeout = mcpGatewayToolTimeout;
+	}
+
 }

spring-boot-starters/spring-ai-alibaba-starter-config-nacos/src/main/java/com/alibaba/cloud/ai/agent/nacos/tools/NacosMcpGatewayToolCallback.java

@@ -16,6 +16,7 @@
 
 package com.alibaba.cloud.ai.agent.nacos.tools;
 
+import java.time.Duration;
 import java.util.HashMap;
 import java.util.Iterator;
 import java.util.List;
@@ -84,14 +85,27 @@ public class NacosMcpGatewayToolCallback implements ToolCallback {
 
 	McpServersVO.McpServerVO mcpServerVO;
 
+	private final Duration requestTimeout;
+
 	/**
 	 * Instantiates a new Nacos mcp gateway tool callback.
 	 * @param toolDefinition the tool definition
 	 */
 	public NacosMcpGatewayToolCallback(final McpGatewayToolDefinition toolDefinition, NacosMcpOperationService nacosMcpOperationService, McpServersVO.McpServerVO mcpServersVO) {
+		this(toolDefinition, nacosMcpOperationService, mcpServersVO, null);
+	}
+
+	public NacosMcpGatewayToolCallback(final McpGatewayToolDefinition toolDefinition,
+			NacosMcpOperationService nacosMcpOperationService, McpServersVO.McpServerVO mcpServersVO,
+			Duration requestTimeout) {
 		this.toolDefinition = (NacosMcpGatewayToolDefinition) toolDefinition;
 		this.nacosMcpOperationService = nacosMcpOperationService;
 		this.mcpServerVO = mcpServersVO;
+		this.requestTimeout = requestTimeout;
+	}
+
+	public Duration getRequestTimeout() {
+		return requestTimeout;
 	}
 
 	/**
@@ -528,7 +542,7 @@ private String handleMcpStreamProtocol(Map<String, Object> args, McpServerRemote
 				HttpClientSseClientTransport transport = transportBuilder.build();
 
 				// 创建MCP同步客户端
-				McpSyncClient client = McpClient.sync(transport).build();
+				McpSyncClient client = configureTimeouts(McpClient.sync(transport)).build();
 				try {
 					// 初始化客户端
 					InitializeResult initializeResult = client.initialize();
@@ -583,6 +597,14 @@ else if (first instanceof Map<?, ?> map && map.containsKey("text")) {
 		}
 	}
 
+	McpClient.SyncSpec configureTimeouts(McpClient.SyncSpec clientSpec) {
+		if (requestTimeout != null) {
+			clientSpec.requestTimeout(requestTimeout);
+			clientSpec.initializationTimeout(requestTimeout);
+		}
+		return clientSpec;
+	}
+
 	/**
 	 * Close.
 	 */

spring-boot-starters/spring-ai-alibaba-starter-config-nacos/src/main/java/com/alibaba/cloud/ai/agent/nacos/tools/NacosMcpGatewayToolsInitializer.java

@@ -16,6 +16,7 @@
 
 package com.alibaba.cloud.ai.agent.nacos.tools;
 
+import java.time.Duration;
 import java.util.ArrayList;
 import java.util.List;
 import java.util.Map;
@@ -41,9 +42,17 @@ public class NacosMcpGatewayToolsInitializer {
 
 	private List<McpServersVO.McpServerVO> mcpServers;
 
+	private final Duration requestTimeout;
+
 	public NacosMcpGatewayToolsInitializer(NacosMcpOperationService nacosMcpOperationService, List<McpServersVO.McpServerVO> mcpServers) {
+		this(nacosMcpOperationService, mcpServers, null);
+	}
+
+	public NacosMcpGatewayToolsInitializer(NacosMcpOperationService nacosMcpOperationService, List<McpServersVO.McpServerVO> mcpServers,
+			Duration requestTimeout) {
 		this.nacosMcpOperationService = nacosMcpOperationService;
 		this.mcpServers = mcpServers;
+		this.requestTimeout = requestTimeout;
 	}
 
 	public List<ToolCallback> initializeTools() {
@@ -122,7 +131,8 @@ private List<ToolCallback> parseToolsFromMcpServerDetailInfo(McpServerDetailInfo
 							.remoteServerConfig(mcpServerRemoteServiceConfig)
 							.toolsMeta(metaInfo)
 							.build();
-					toolCallbacks.add(new NacosMcpGatewayToolCallback(toolDefinition, nacosMcpOperationService, serverVO));
+					toolCallbacks.add(new NacosMcpGatewayToolCallback(toolDefinition, nacosMcpOperationService, serverVO,
+							requestTimeout));
 				}
 			}
 			return toolCallbacks;