Initial refactor of json/json schema api. Moved classes in mcp-json

into mcp-core.

Author: scottslewis

mcp-core/pom.xml

@@ -65,12 +65,6 @@
 	</build>
 
 	<dependencies>
-        <dependency>
-            <groupId>io.modelcontextprotocol.sdk</groupId>
-            <artifactId>mcp-json</artifactId>
-            <version>0.17.0-SNAPSHOT</version>
-        </dependency>
-
 		<dependency>
 			<groupId>org.slf4j</groupId>
 			<artifactId>slf4j-api</artifactId>
@@ -90,6 +84,11 @@
 
 
 		<!-- Used by the HttpServletSseServerTransport -->
+        <dependency>
+            <groupId>com.fasterxml.jackson.core</groupId>
+            <artifactId>jackson-databind</artifactId>
+            <version>${jackson.version}</version>
+        </dependency>
 		<dependency>
 			<groupId>jakarta.servlet</groupId>
 			<artifactId>jakarta.servlet-api</artifactId>
@@ -104,7 +103,6 @@
             <version>0.17.0-SNAPSHOT</version>
             <scope>test</scope>
         </dependency>
-
 		<dependency>
 			<groupId>org.springframework</groupId>
 			<artifactId>spring-webmvc</artifactId>

mcp-core/src/main/java/io/modelcontextprotocol/client/McpClient.java

@@ -13,8 +13,9 @@
 import java.util.function.Function;
 import java.util.function.Supplier;
 
-import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
 import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.json.internal.DefaultMcpJsonSchemaValidatorSupplier;
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
 import io.modelcontextprotocol.spec.McpSchema.ClientCapabilities;
@@ -475,7 +476,8 @@ public McpSyncClient build() {
 			McpClientFeatures.Async asyncFeatures = McpClientFeatures.Async.fromSync(syncFeatures);
 
 			return new McpSyncClient(new McpAsyncClient(transport, this.requestTimeout, this.initializationTimeout,
-					jsonSchemaValidator != null ? jsonSchemaValidator : JsonSchemaValidator.getDefault(),
+					jsonSchemaValidator != null ? jsonSchemaValidator
+							: DefaultMcpJsonSchemaValidatorSupplier.getDefaultJsonSchemaValidator(),
 					asyncFeatures), this.contextProvider);
 		}
 
@@ -809,7 +811,7 @@ public AsyncSpec enableCallToolSchemaCaching(boolean enableCallToolSchemaCaching
 		 */
 		public McpAsyncClient build() {
 			var jsonSchemaValidator = (this.jsonSchemaValidator != null) ? this.jsonSchemaValidator
-					: JsonSchemaValidator.getDefault();
+					: DefaultMcpJsonSchemaValidatorSupplier.getDefaultJsonSchemaValidator();
 			return new McpAsyncClient(this.transport, this.requestTimeout, this.initializationTimeout,
 					jsonSchemaValidator,
 					new McpClientFeatures.Async(this.clientInfo, this.capabilities, this.roots,

mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientSseClientTransport.java

@@ -24,6 +24,7 @@
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.json.McpJsonMapper;
 import io.modelcontextprotocol.json.TypeRef;
+import io.modelcontextprotocol.json.internal.DefaultMcpJsonMapperSupplier;
 import io.modelcontextprotocol.spec.HttpHeaders;
 import io.modelcontextprotocol.spec.McpClientTransport;
 import io.modelcontextprotocol.spec.McpSchema;
@@ -327,7 +328,8 @@ public Builder connectTimeout(Duration connectTimeout) {
 		public HttpClientSseClientTransport build() {
 			HttpClient httpClient = this.clientBuilder.connectTimeout(this.connectTimeout).build();
 			return new HttpClientSseClientTransport(httpClient, requestBuilder, baseUri, sseEndpoint,
-					jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper, httpRequestCustomizer);
+					jsonMapper == null ? DefaultMcpJsonMapperSupplier.getDefaultMcpJsonMapper() : jsonMapper,
+					httpRequestCustomizer);
 		}
 
 	}

mcp-core/src/main/java/io/modelcontextprotocol/client/transport/HttpClientStreamableHttpTransport.java

@@ -25,6 +25,7 @@
 import io.modelcontextprotocol.client.transport.customizer.McpSyncHttpClientRequestCustomizer;
 import io.modelcontextprotocol.common.McpTransportContext;
 import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.internal.DefaultMcpJsonMapperSupplier;
 import io.modelcontextprotocol.json.TypeRef;
 import io.modelcontextprotocol.spec.ClosedMcpTransportSession;
 import io.modelcontextprotocol.spec.DefaultMcpTransportSession;
@@ -813,7 +814,8 @@ public Builder supportedProtocolVersions(List<String> supportedProtocolVersions)
 		 */
 		public HttpClientStreamableHttpTransport build() {
 			HttpClient httpClient = this.clientBuilder.connectTimeout(this.connectTimeout).build();
-			return new HttpClientStreamableHttpTransport(jsonMapper == null ? McpJsonMapper.getDefault() : jsonMapper,
+			return new HttpClientStreamableHttpTransport(
+					jsonMapper == null ? DefaultMcpJsonMapperSupplier.getDefaultMcpJsonMapper() : jsonMapper,
 					httpClient, requestBuilder, baseUri, endpoint, resumableStreams, openConnectionOnStartup,
 					httpRequestCustomizer, supportedProtocolVersions);
 		}

mcp-core/src/main/java/io/modelcontextprotocol/json/McpJsonMapper.java

@@ -0,0 +1,90 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json;
+
+import java.io.IOException;
+
+/**
+ * Abstraction for JSON serialization/deserialization to decouple the SDK from any
+ * specific JSON library. A default implementation backed by Jackson is provided in
+ * io.modelcontextprotocol.spec.json.jackson.JacksonJsonMapper.
+ */
+public interface McpJsonMapper {
+
+	/**
+	 * Deserialize JSON string into a target type.
+	 * @param content JSON as String
+	 * @param type target class
+	 * @return deserialized instance
+	 * @param <T> generic type
+	 * @throws IOException on parse errors
+	 */
+	<T> T readValue(String content, Class<T> type) throws IOException;
+
+	/**
+	 * Deserialize JSON bytes into a target type.
+	 * @param content JSON as bytes
+	 * @param type target class
+	 * @return deserialized instance
+	 * @param <T> generic type
+	 * @throws IOException on parse errors
+	 */
+	<T> T readValue(byte[] content, Class<T> type) throws IOException;
+
+	/**
+	 * Deserialize JSON string into a parameterized target type.
+	 * @param content JSON as String
+	 * @param type parameterized type reference
+	 * @return deserialized instance
+	 * @param <T> generic type
+	 * @throws IOException on parse errors
+	 */
+	<T> T readValue(String content, TypeRef<T> type) throws IOException;
+
+	/**
+	 * Deserialize JSON bytes into a parameterized target type.
+	 * @param content JSON as bytes
+	 * @param type parameterized type reference
+	 * @return deserialized instance
+	 * @param <T> generic type
+	 * @throws IOException on parse errors
+	 */
+	<T> T readValue(byte[] content, TypeRef<T> type) throws IOException;
+
+	/**
+	 * Convert a value to a given type, useful for mapping nested JSON structures.
+	 * @param fromValue source value
+	 * @param type target class
+	 * @return converted value
+	 * @param <T> generic type
+	 */
+	<T> T convertValue(Object fromValue, Class<T> type);
+
+	/**
+	 * Convert a value to a given parameterized type.
+	 * @param fromValue source value
+	 * @param type target type reference
+	 * @return converted value
+	 * @param <T> generic type
+	 */
+	<T> T convertValue(Object fromValue, TypeRef<T> type);
+
+	/**
+	 * Serialize an object to JSON string.
+	 * @param value object to serialize
+	 * @return JSON as String
+	 * @throws IOException on serialization errors
+	 */
+	String writeValueAsString(Object value) throws IOException;
+
+	/**
+	 * Serialize an object to JSON bytes.
+	 * @param value object to serialize
+	 * @return JSON as bytes
+	 * @throws IOException on serialization errors
+	 */
+	byte[] writeValueAsBytes(Object value) throws IOException;
+
+}

mcp-core/src/main/java/io/modelcontextprotocol/json/McpJsonMapperSupplier.java

@@ -0,0 +1,14 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json;
+
+import java.util.function.Supplier;
+
+/**
+ * Strategy interface for resolving a {@link McpJsonMapper}.
+ */
+public interface McpJsonMapperSupplier extends Supplier<McpJsonMapper> {
+
+}

mcp-core/src/main/java/io/modelcontextprotocol/json/TypeRef.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2025 - 2025 the original author or authors.
+ */
+
+package io.modelcontextprotocol.json;
+
+import java.lang.reflect.ParameterizedType;
+import java.lang.reflect.Type;
+
+/**
+ * Captures generic type information at runtime for parameterized JSON (de)serialization.
+ * Usage: TypeRef<List<Foo>> ref = new TypeRef<>(){};
+ */
+public abstract class TypeRef<T> {
+
+	private final Type type;
+
+	/**
+	 * Constructs a new TypeRef instance, capturing the generic type information of the
+	 * subclass. This constructor should be called from an anonymous subclass to capture
+	 * the actual type arguments. For example: <pre>
+	 * TypeRef&lt;List&lt;Foo&gt;&gt; ref = new TypeRef&lt;&gt;(){};
+	 * </pre>
+	 * @throws IllegalStateException if TypeRef is not subclassed with actual type
+	 * information
+	 */
+	protected TypeRef() {
+		Type superClass = getClass().getGenericSuperclass();
+		if (superClass instanceof Class) {
+			throw new IllegalStateException("TypeRef constructed without actual type information");
+		}
+		this.type = ((ParameterizedType) superClass).getActualTypeArguments()[0];
+	}
+
+	/**
+	 * Returns the captured type information.
+	 * @return the Type representing the actual type argument captured by this TypeRef
+	 * instance
+	 */
+	public Type getType() {
+		return type;
+	}
+
+}

mcp-core/src/main/java/io/modelcontextprotocol/json/internal/DefaultMcpJsonMapperSupplier.java

@@ -0,0 +1,40 @@
+package io.modelcontextprotocol.json.internal;
+
+import java.util.Optional;
+import java.util.ServiceConfigurationError;
+import java.util.ServiceLoader;
+
+import io.modelcontextprotocol.json.McpJsonMapper;
+import io.modelcontextprotocol.json.McpJsonMapperSupplier;
+
+public class DefaultMcpJsonMapperSupplier {
+
+	private static McpJsonMapperSupplier jsonMapperSupplier;
+
+	private static McpJsonMapper defaultJsonMapper;
+
+	void setMcpJsonMapperSupplier(McpJsonMapperSupplier supplier) {
+		jsonMapperSupplier = supplier;
+	}
+
+	void unsetMcpJsonMapperSupplier(McpJsonMapperSupplier supplier) {
+		jsonMapperSupplier = null;
+		defaultJsonMapper = null;
+	}
+
+	public synchronized static McpJsonMapper getDefaultMcpJsonMapper() {
+		if (defaultJsonMapper == null) {
+			if (jsonMapperSupplier == null) {
+				// Use serviceloader
+				Optional<McpJsonMapperSupplier> sl = ServiceLoader.load(McpJsonMapperSupplier.class).findFirst();
+				if (sl.isEmpty()) {
+					throw new ServiceConfigurationError("No JsonMapperSupplier available for creating McpJsonMapper");
+				}
+				jsonMapperSupplier = sl.get();
+			}
+			defaultJsonMapper = jsonMapperSupplier.get();
+		}
+		return defaultJsonMapper;
+	}
+
+}

mcp-core/src/main/java/io/modelcontextprotocol/json/internal/DefaultMcpJsonSchemaValidatorSupplier.java

@@ -0,0 +1,42 @@
+package io.modelcontextprotocol.json.internal;
+
+import java.util.Optional;
+import java.util.ServiceConfigurationError;
+import java.util.ServiceLoader;
+
+import io.modelcontextprotocol.json.schema.JsonSchemaValidator;
+import io.modelcontextprotocol.json.schema.JsonSchemaValidatorSupplier;
+
+public class DefaultMcpJsonSchemaValidatorSupplier {
+
+	private static JsonSchemaValidatorSupplier jsonSchemaValidatorSupplier;
+
+	private static JsonSchemaValidator defaultJsonSchemaValidator;
+
+	void setJsonSchemaValidatorSupplier(JsonSchemaValidatorSupplier supplier) {
+		jsonSchemaValidatorSupplier = supplier;
+	}
+
+	void unsetJsonSchemaValidatorSupplier(JsonSchemaValidatorSupplier supplier) {
+		jsonSchemaValidatorSupplier = null;
+		defaultJsonSchemaValidator = null;
+	}
+
+	public synchronized static JsonSchemaValidator getDefaultJsonSchemaValidator() {
+		if (defaultJsonSchemaValidator == null) {
+			if (jsonSchemaValidatorSupplier == null) {
+				// Use serviceloader
+				Optional<JsonSchemaValidatorSupplier> sl = ServiceLoader.load(JsonSchemaValidatorSupplier.class)
+					.findFirst();
+				if (sl.isEmpty()) {
+					throw new ServiceConfigurationError(
+							"No JsonSchemaValidatorSupplier available for creating JsonSchemaValidator");
+				}
+				jsonSchemaValidatorSupplier = sl.get();
+			}
+			defaultJsonSchemaValidator = jsonSchemaValidatorSupplier.get();
+		}
+		return defaultJsonSchemaValidator;
+	}
+
+}

mcp-core/src/main/java/io/modelcontextprotocol/json/schema/JsonSchemaValidator.java

@@ -0,0 +1,44 @@
+/*
+ * Copyright 2024-2024 the original author or authors.
+ */
+package io.modelcontextprotocol.json.schema;
+
+import java.util.Map;
+
+/**
+ * Interface for validating structured content against a JSON schema. This interface
+ * defines a method to validate structured content based on the provided output schema.
+ *
+ * @author Christian Tzolov
+ */
+public interface JsonSchemaValidator {
+
+	/**
+	 * Represents the result of a validation operation.
+	 *
+	 * @param valid Indicates whether the validation was successful.
+	 * @param errorMessage An error message if the validation failed, otherwise null.
+	 * @param jsonStructuredOutput The text structured content in JSON format if the
+	 * validation was successful, otherwise null.
+	 */
+	record ValidationResponse(boolean valid, String errorMessage, String jsonStructuredOutput) {
+
+		public static ValidationResponse asValid(String jsonStructuredOutput) {
+			return new ValidationResponse(true, null, jsonStructuredOutput);
+		}
+
+		public static ValidationResponse asInvalid(String message) {
+			return new ValidationResponse(false, message, null);
+		}
+	}
+
+	/**
+	 * Validates the structured content against the provided JSON schema.
+	 * @param schema The JSON schema to validate against.
+	 * @param structuredContent The structured content to validate.
+	 * @return A ValidationResponse indicating whether the validation was successful or
+	 * not.
+	 */
+	ValidationResponse validate(Map<String, Object> schema, Object structuredContent);
+
+}