feat: Add Tool.outputSchema and CallToolResult.structuredContent

mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java

@@ -4,6 +4,7 @@
 
 package io.modelcontextprotocol.server;
 
+import java.util.HashMap;
 import java.util.List;
 
 import io.modelcontextprotocol.spec.McpError;
@@ -17,6 +18,7 @@
 import io.modelcontextprotocol.spec.McpSchema.ServerCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.Tool;
 import io.modelcontextprotocol.spec.McpServerTransportProvider;
+
 import org.junit.jupiter.api.AfterEach;
 import org.junit.jupiter.api.BeforeEach;
 import org.junit.jupiter.api.Test;
@@ -125,7 +127,7 @@ void testAddTool() {
 
 	@Test
 	void testAddDuplicateTool() {
-		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema);
+		Tool duplicateTool = new McpSchema.Tool(TEST_TOOL_NAME, "Duplicate tool", emptyJsonSchema, emptyJsonSchema);
 
 		var mcpSyncServer = McpServer.sync(createMcpTransportProvider())
 			.serverInfo("test-server", "1.0.0")
@@ -134,7 +136,7 @@ void testAddDuplicateTool() {
 			.build();
 
 		assertThatThrownBy(() -> mcpSyncServer.addTool(new McpServerFeatures.SyncToolSpecification(duplicateTool,
-				(exchange, args) -> new CallToolResult(List.of(), false))))
+				(exchange, args) -> new CallToolResult(List.of(), false, new HashMap<String, Object>()))))
 			.isInstanceOf(McpError.class)
 			.hasMessage("Tool with name '" + TEST_TOOL_NAME + "' already exists");
 

mcp/pom.xml

@@ -202,6 +202,13 @@
 			<scope>test</scope>
 		</dependency>
 
+		<!-- Json validator dependency -->
+		<dependency>
+			<groupId>com.networknt</groupId>
+			<artifactId>json-schema-validator</artifactId>
+			<version>1.5.7</version>
+		</dependency>
+
 	</dependencies>
 
 

mcp/src/main/java/io/modelcontextprotocol/client/McpAsyncClient.java

@@ -8,12 +8,14 @@
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
+import java.util.Optional;
 import java.util.concurrent.ConcurrentHashMap;
 import java.util.concurrent.atomic.AtomicReference;
 import java.util.function.Function;
 import java.util.function.Supplier;
 
 import com.fasterxml.jackson.core.type.TypeReference;
+
 import io.modelcontextprotocol.spec.McpClientSession;
 import io.modelcontextprotocol.spec.McpClientSession.NotificationHandler;
 import io.modelcontextprotocol.spec.McpClientSession.RequestHandler;
@@ -27,6 +29,7 @@
 import io.modelcontextprotocol.spec.McpSchema.ElicitResult;
 import io.modelcontextprotocol.spec.McpSchema.GetPromptRequest;
 import io.modelcontextprotocol.spec.McpSchema.GetPromptResult;
+import io.modelcontextprotocol.spec.McpSchema.JsonSchema;
 import io.modelcontextprotocol.spec.McpSchema.ListPromptsResult;
 import io.modelcontextprotocol.spec.McpSchema.LoggingLevel;
 import io.modelcontextprotocol.spec.McpSchema.LoggingMessageNotification;
@@ -35,8 +38,11 @@
 import io.modelcontextprotocol.spec.McpTransportSessionNotFoundException;
 import io.modelcontextprotocol.util.Assert;
 import io.modelcontextprotocol.util.Utils;
+
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
+
+import io.modelcontextprotocol.server.McpServerFeatures;
 import reactor.core.publisher.Flux;
 import reactor.core.publisher.Mono;
 import reactor.core.publisher.Sinks;
@@ -118,6 +124,11 @@ public class McpAsyncClient {
 	 */
 	private final McpSchema.Implementation clientInfo;
 
+	/**
+	 * Cached tool output schemas.
+	 */
+	private final ConcurrentHashMap<String, Optional<JsonSchema>> toolsOutputSchemaCache;
+
 	/**
 	 * Roots define the boundaries of where servers can operate within the filesystem,
 	 * allowing them to understand which directories and files they have access to.
@@ -181,6 +192,7 @@ public class McpAsyncClient {
 		this.transport = transport;
 		this.roots = new ConcurrentHashMap<>(features.roots());
 		this.initializationTimeout = initializationTimeout;
+		this.toolsOutputSchemaCache = new ConcurrentHashMap<>();
 
 		// Request Handlers
 		Map<String, RequestHandler<?>> requestHandlers = new HashMap<>();
@@ -331,6 +343,14 @@ public McpSchema.Implementation getClientInfo() {
 		return this.clientInfo;
 	}
 
+	/**
+	 * Get the cached tool output schemas.
+	 * @return The cached tool output schemas
+	 */
+	public ConcurrentHashMap<String, Optional<JsonSchema>> getToolsOutputSchemaCache() {
+		return this.toolsOutputSchemaCache;
+	}
+
 	/**
 	 * Closes the client connection immediately.
 	 */
@@ -650,8 +670,13 @@ public Mono<McpSchema.CallToolResult> callTool(McpSchema.CallToolRequest callToo
 			if (init.get().capabilities().tools() == null) {
 				return Mono.error(new McpError("Server does not provide tools capability"));
 			}
-			return init.mcpSession()
-				.sendRequest(McpSchema.METHOD_TOOLS_CALL, callToolRequest, CALL_TOOL_RESULT_TYPE_REF);
+			// Refresh tool output schema cache, if necessary, prior to making tool call
+			Mono<Void> refreshCacheMono = Mono.empty();
+			if (!this.toolsOutputSchemaCache.containsKey(callToolRequest.name())) {
+				refreshCacheMono = refreshToolOutputSchemaCache();
+			}
+			return refreshCacheMono.then(init.mcpSession()
+				.sendRequest(McpSchema.METHOD_TOOLS_CALL, callToolRequest, CALL_TOOL_RESULT_TYPE_REF));
 		});
 	}
 
@@ -675,7 +700,33 @@ public Mono<McpSchema.ListToolsResult> listTools(String cursor) {
 			}
 			return init.mcpSession()
 				.sendRequest(McpSchema.METHOD_TOOLS_LIST, new McpSchema.PaginatedRequest(cursor),
-						LIST_TOOLS_RESULT_TYPE_REF);
+						LIST_TOOLS_RESULT_TYPE_REF)
+				.doOnNext(result -> {
+					// Cache tools output schema
+					if (result.tools() != null) {
+						// Cache tools output schema
+						result.tools()
+							.forEach(tool -> this.toolsOutputSchemaCache.put(tool.name(),
+									Optional.ofNullable(tool.outputSchema())));
+					}
+				});
+		});
+	}
+
+	/**
+	 * Refreshes the tool output schema cache by fetching all tools from the server.
+	 * @return A Mono that completes when all tool output schemas have been cached
+	 */
+	private Mono<Void> refreshToolOutputSchemaCache() {
+		return this.withSession("refreshing tool output schema cache", init -> {
+
+			// Use expand operator to handle pagination in a reactive way
+			return this.listTools(null).expand(result -> {
+				if (result.nextCursor() != null) {
+					return this.listTools(result.nextCursor());
+				}
+				return Mono.empty();
+			}).then();
 		});
 	}
 

mcp/src/main/java/io/modelcontextprotocol/client/McpSyncClient.java

@@ -5,15 +5,29 @@
 package io.modelcontextprotocol.client;
 
 import java.time.Duration;
+import java.util.Optional;
+import java.util.Set;
+import java.util.concurrent.ConcurrentHashMap;
 
+import org.slf4j.Logger;
+import org.slf4j.LoggerFactory;
+
+import com.fasterxml.jackson.core.JsonProcessingException;
+import com.fasterxml.jackson.databind.JsonNode;
+import com.fasterxml.jackson.databind.ObjectMapper;
+import com.fasterxml.jackson.databind.node.ObjectNode;
+import com.networknt.schema.JsonSchema;
+import com.networknt.schema.JsonSchemaFactory;
+import com.networknt.schema.SpecVersion;
+import com.networknt.schema.ValidationMessage;
+
+import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
 import io.modelcontextprotocol.spec.McpSchema.GetPromptRequest;
 import io.modelcontextprotocol.spec.McpSchema.GetPromptResult;
 import io.modelcontextprotocol.spec.McpSchema.ListPromptsResult;
 import io.modelcontextprotocol.util.Assert;
-import org.slf4j.Logger;
-import org.slf4j.LoggerFactory;
 
 /**
  * A synchronous client implementation for the Model Context Protocol (MCP) that wraps an
@@ -62,14 +76,28 @@ public class McpSyncClient implements AutoCloseable {
 
 	private final McpAsyncClient delegate;
 
+	/** JSON object mapper for message serialization/deserialization */
+	protected ObjectMapper objectMapper;
+
 	/**
 	 * Create a new McpSyncClient with the given delegate.
 	 * @param delegate the asynchronous kernel on top of which this synchronous client
 	 * provides a blocking API.
 	 */
 	McpSyncClient(McpAsyncClient delegate) {
+		this(delegate, new ObjectMapper());
+	}
+
+	/**
+	 * Create a new McpSyncClient with the given delegate.
+	 * @param delegate the asynchronous kernel on top of which this synchronous client
+	 * provides a blocking API.
+	 * @param objectMapper the object mapper for JSON serialization/deserialization
+	 */
+	McpSyncClient(McpAsyncClient delegate, ObjectMapper objectMapper) {
 		Assert.notNull(delegate, "The delegate can not be null");
 		this.delegate = delegate;
+		this.objectMapper = objectMapper;
 	}
 
 	/**
@@ -206,7 +234,8 @@ public Object ping() {
 	/**
 	 * Calls a tool provided by the server. Tools enable servers to expose executable
 	 * functionality that can interact with external systems, perform computations, and
-	 * take actions in the real world.
+	 * take actions in the real world. If tool contains an output schema, validates the
+	 * tool result structured content against the output schema.
 	 * @param callToolRequest The request containing: - name: The name of the tool to call
 	 * (must match a tool name from tools/list) - arguments: Arguments that conform to the
 	 * tool's input schema
@@ -215,7 +244,54 @@ public Object ping() {
 	 * Boolean indicating if the execution failed (true) or succeeded (false/absent)
 	 */
 	public McpSchema.CallToolResult callTool(McpSchema.CallToolRequest callToolRequest) {
-		return this.delegate.callTool(callToolRequest).block();
+		McpSchema.CallToolResult result = this.delegate.callTool(callToolRequest).block();
+		ConcurrentHashMap<String, Optional<McpSchema.JsonSchema>> toolsOutputSchemaCache = this.delegate
+			.getToolsOutputSchemaCache();
+		// Should not be triggered but added for completeness
+		if (!toolsOutputSchemaCache.containsKey(callToolRequest.name())) {
+			throw new McpError("Tool with name '" + callToolRequest.name() + "' not found");
+		}
+		Optional<McpSchema.JsonSchema> optOutputSchema = toolsOutputSchemaCache.get(callToolRequest.name());
+		if (result != null && optOutputSchema != null && optOutputSchema.isPresent()) {
+			if (result.structuredContent() == null) {
+				throw new McpError("CallToolResult validation failed: structuredContent is null and "
+						+ "does not match tool outputSchema.");
+			}
+			McpSchema.JsonSchema outputSchema = optOutputSchema.get();
+
+			try {
+				// Convert outputSchema to string
+				String outputSchemaString = this.objectMapper.writeValueAsString(outputSchema);
+
+				// Create JsonSchema validator
+				ObjectNode schemaNode = (ObjectNode) this.objectMapper.readTree(outputSchemaString);
+				// Set additional properties to false if not specified in output schema
+				if (!schemaNode.has("additionalProperties")) {
+					schemaNode.put("additionalProperties", false);
+				}
+				JsonSchema schema = JsonSchemaFactory.getInstance(SpecVersion.VersionFlag.V202012)
+					.getSchema(schemaNode);
+
+				// Convert structured content in reult to JsonNode
+				JsonNode jsonNode = this.objectMapper.valueToTree(result.structuredContent());
+
+				// Validate outputSchema against structuredContent
+				Set<ValidationMessage> validationResult = schema.validate(jsonNode);
+
+				// Check if validation passed
+				if (!validationResult.isEmpty()) {
+					// Handle validation errors
+					throw new McpError(
+							"CallToolResult validation failed: structuredContent does not match tool outputSchema.");
+				}
+			}
+			catch (JsonProcessingException e) {
+				// Log warning if output schema can't be parsed to prevent erroring out
+				// for successful call tool request
+				logger.warn("Failed to validate CallToolResult: Error parsing tool outputSchema: {}", e);
+			}
+		}
+		return result;
 	}
 
 	/**