feat: Add Tool.outputSchema and CallToolResult.structuredContent

- Implement support for outputSchema in Tool and structuredContent in
  CallToolResult.
- Add a client-side cache that maintains track of all server tools and
  their output schemas (if any).
- Implement a mechanism to refresh the client side cache when
  encountering a tool call request for an uncached tool.
- Implement json validation between tool's output schema and result's
  structured content, when an output schema is specified for the tool.

Author: pantanurag555

mcp-test/src/main/java/io/modelcontextprotocol/server/.LCKAbstractMcpSyncServerTests.java~

@@ -0,0 +1 @@
+/local/home/pantanur/workspace/java-sdk/mcp-test/src/main/java/io/modelcontextprotocol/server/AbstractMcpSyncServerTests.java

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

@@ -14,6 +14,7 @@
 import java.util.function.Function;
 
 import com.fasterxml.jackson.core.type.TypeReference;
+
 import io.modelcontextprotocol.spec.McpClientSession;
 import io.modelcontextprotocol.spec.McpClientSession.NotificationHandler;
 import io.modelcontextprotocol.spec.McpClientSession.RequestHandler;
@@ -33,8 +34,11 @@
 import io.modelcontextprotocol.spec.McpTransport;
 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;
@@ -123,6 +127,11 @@ public class McpAsyncClient {
 	 */
 	private McpSchema.Implementation serverInfo;
 
+	/**
+	 * Cached tool output schemas.
+	 */
+	private final HashMap<String, McpSchema.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.
@@ -171,6 +180,7 @@ public class McpAsyncClient {
 		this.transport = transport;
 		this.roots = new ConcurrentHashMap<>(features.roots());
 		this.initializationTimeout = initializationTimeout;
+		this.toolsOutputSchemaCache = new HashMap<>();
 
 		// Request Handlers
 		Map<String, RequestHandler<?>> requestHandlers = new HashMap<>();
@@ -287,6 +297,14 @@ public McpSchema.Implementation getClientInfo() {
 		return this.clientInfo;
 	}
 
+	/**
+	 * Get the cached tool output schemas.
+	 * @return The cached tool output schemas
+	 */
+	public HashMap<String, McpSchema.JsonSchema> getToolsOutputSchemaCache() {
+		return this.toolsOutputSchemaCache;
+	}
+
 	/**
 	 * Closes the client connection immediately.
 	 */
@@ -525,7 +543,13 @@ public Mono<McpSchema.CallToolResult> callTool(McpSchema.CallToolRequest callToo
 			if (this.serverCapabilities.tools() == null) {
 				return Mono.error(new McpError("Server does not provide tools capability"));
 			}
-			return this.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(this.mcpSession.sendRequest(McpSchema.METHOD_TOOLS_CALL, callToolRequest,
+					CALL_TOOL_RESULT_TYPE_REF));
 		});
 	}
 
@@ -547,8 +571,34 @@ public Mono<McpSchema.ListToolsResult> listTools(String cursor) {
 			if (this.serverCapabilities.tools() == null) {
 				return Mono.error(new McpError("Server does not provide tools capability"));
 			}
-			return this.mcpSession.sendRequest(McpSchema.METHOD_TOOLS_LIST, new McpSchema.PaginatedRequest(cursor),
-					LIST_TOOLS_RESULT_TYPE_REF);
+			return this.mcpSession
+				.sendRequest(McpSchema.METHOD_TOOLS_LIST, new McpSchema.PaginatedRequest(cursor),
+						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(), 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.withInitializationCheck("refreshing tool output schema cache", initializedResult -> {
+
+			// 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,28 @@
 package io.modelcontextprotocol.client;
 
 import java.time.Duration;
+import java.util.HashMap;
+import java.util.Set;
 
+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
@@ -55,6 +68,8 @@ public class McpSyncClient implements AutoCloseable {
 
 	private static final Logger logger = LoggerFactory.getLogger(McpSyncClient.class);
 
+	private static final ObjectMapper OBJECT_MAPPER = new ObjectMapper();
+
 	// TODO: Consider providing a client config to set this properly
 	// this is currently a concern only because AutoCloseable is used - perhaps it
 	// is not a requirement?
@@ -206,7 +221,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 +231,53 @@ 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();
+		HashMap<String, 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");
+		}
+		if (result != null && toolsOutputSchemaCache.get(callToolRequest.name()) != null) {
+			if (result.structuredContent() == null) {
+				throw new McpError("CallToolResult validation failed: structuredContent is null and "
+						+ "does not match tool outputSchema.");
+			}
+
+			McpSchema.JsonSchema outputSchema = toolsOutputSchemaCache.get(callToolRequest.name());
+
+			try {
+				// Convert outputSchema to string
+				String outputSchemaString = OBJECT_MAPPER.writeValueAsString(outputSchema);
+
+				// Create JsonSchema validator
+				ObjectNode schemaNode = (ObjectNode) OBJECT_MAPPER.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 = OBJECT_MAPPER.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 error if output schema can't be parsed to prevent erroring out for
+				// successful call tool request
+				logger.error("Encountered exception when parsing outputSchema: {}", e);
+			}
+		}
+		return result;
 	}
 
 	/**
@@ -353,4 +415,8 @@ public McpSchema.CompleteResult completeCompletion(McpSchema.CompleteRequest com
 		return this.delegate.completeCompletion(completeRequest).block();
 	}
 
+	private void isStrict(boolean b) {
+		throw new UnsupportedOperationException("Not supported yet.");
+	}
+
 }