Introduce McpJsonMapper interface to decouple from Jackson #543

graemerocher · 2025-09-10T10:30:43Z

Motivation and Context

The current MCP SDK is coupled to Jackson which prevents the use of other JSON serialization libraries and techniques.

This PR is an initial go and abstracting away Jackson usage in order to generate discussion. Left in draft to gather feedback.

This pull request creates two modules, mcp-json and mcp-json-jackson. It removes the com.fasterxml.jackson.core:jackson-databind and com.networknt:json-schema-validator dependencies from the mcp module. The mcp module now only depends on com.fasterxml.jackson.core:jackson-annotations.

To use Jackson, you have to add mcp-jackson to your dependencies in addition to mcp. I added the dependency mcp-jackson to both mcp-spring-mvc and mcp-spring-webflux to avoid a breaking change in those modules.

It provides two SPI JsonSchemaValidatorSupplier and JsonSchemaValidatorSupplier to allow easy replacement for consumers who don't want to use Jackson.

This pull request also ensures no McpJsonMapper is instantiated if one is provided via a builder method. Only if the builders don't receive a McpJsonMapper mapper, one is instantiated in the build method of the builder.
The logic behind this is to allow frameworks to provide a McpJsonMapper mapper singleton implementation and feed it to the builders without paying the price of instantiating McpJsonMappers, which will not be used. The goal is to be able to use the ObjectMapper singleton of an application also for the MCP code.

How Has This Been Tested?

Yes tests included.

Breaking Changes

This pull request also removes the deprecated Tool constructors, and it updates every test to use the builder API to instantiate tools.
Several constructors taking an ObjectMapper or constructor which forced the instantiation of a generic McpJsonMapper have been removed.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

sdelamo

I have created a PR on top of this graemerocher#1

sdelamo · 2025-09-10T10:54:04Z

...src/main/java/io/modelcontextprotocol/client/transport/WebClientStreamableHttpTransport.java

+			this.jsonMapper = new JacksonMcpJsonMapper(objectMapper);
+			return this;


Suggested change

this.jsonMapper = new JacksonMcpJsonMapper(objectMapper);

return this;

return jsonMapper(new JacksonMcpJsonMapper(objectMapper));

He-Pin · 2025-09-11T19:24:26Z

Do you want to use Vert.x's json?

sdelamo · 2025-09-12T07:32:26Z

Do you want to use Vert.x's json?

We want to use Micronaut Serialization. But basically, the idea is to allow users to use whatever JSON Serialization they want.

This pull request creates two modules, `mcp-json` and `mcp-json-jackson`. It removes the `com.fasterxml.jackson.core:jackson-databind` and `com.networknt:json-schema-validator` dependencies from the `mcp` module. The `mcp` module now only depends on `com.fasterxml.jackson.core:jackson-annotations`. To use Jackson, you have to add `mcp-jackson` to your dependencies in addition to `mcp`. I added the dependency `mcp-jackson` to both `mcp-spring-mvc` and `mcp-spring-webflux` to avoid a breaking change in those modules. It provides two [SPI](https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html) `JsonSchemaValidatorSupplier` and `JacksonJsonSchemaValidatorSupplier` to allow easy replacement for consumers who don't want to use Jackson. This pull request also ensures no `McpJsonMapper` is instantiated if one is provided via a builder method. Only if the builders don't receive a `McpJsonMapper` mapper, one is instantiated in the `build` method of the builder. The logic behind this is to allow frameworks to provide a `McpJsonMapper` mapper singleton implementation and feed it to the builders without paying the price of instantiating `McpJsonMappers`, which will not be used. The goal is to be able to use the `ObjectMapper` singleton of an application also for the MCP code. ## Breaking changes - This pull request also removes the deprecated `Tool` constructors, and it updates every test to use the builder API to instantiate tools. - Several constructors taking an ObjectMapper or constructor which forced the instantiation of a generic `McpJsonMapper` have been removed.

sdeleuze · 2025-09-12T11:57:07Z

I did not review everything in detail, but from a high level perspective, this PR looks great, thanks for contributing it @graemerocher @sdelamo.

The main open question for me is related to Jackson 3 which is about to be released. If we want to support Jackson 2 and Jackson 3 (which continues to use the same jackson-annotation:2.x dependency) side by side in the MCP SDK, we may want to rename the module mcp-json-jackson to mcp-json-jackson2 and use a jackson2 subpackage instead of jackson in this module.

If we just plan to upgrade from Jackson 2 to Jackson 3, current naming is fine.

graemerocher · 2025-09-12T12:43:25Z

probably including the major version makes sense for Jackson.

tzolov

Thanks @graemerocher, @sdelamo ! Nice work.

Few improvement requests:

Add the mcp-json and mcp-json-jackson modules to the mcp-bom

Add missing MIT license headers:

/*
 * Copyright 2025 - 2025 the original author or authors.
 */

Update mcp java sdk reference documentation (remainder for a follow-up PR)

There's another conceptual change that I'm puzzled with. Currently the mcp is self-contained. But with this PR it becomes a "core" component requiring an additional mcp-json-xxx (like mcp-json-jackson) dependency for the same bootstrap experience without breaking changes.

I wonder if we should rename the existing mcp module to mcp-core and create a small mcp module that includes both mcp-core and mcp-json-jackson by default?
This will preserver the existing single-click experience for the end users

tzolov · 2025-09-15T07:48:12Z

mcp/pom.xml

+            <version>0.13.0-SNAPSHOT</version>
+        </dependency>
+
+        <dependency>


move to the test section of the pom

tzolov · 2025-09-15T07:48:58Z

mcp-json/pom.xml

+		<artifactId>mcp-parent</artifactId>
+		<version>0.13.0-SNAPSHOT</version>
+	</parent>
+	<artifactId>mcp-json</artifactId>


add to the mcp-bom

see: graemerocher@1b4271b

tzolov · 2025-09-15T07:49:16Z

mcp-json-jackson/pom.xml

+		<artifactId>mcp-parent</artifactId>
+		<version>0.13.0-SNAPSHOT</version>
+	</parent>
+	<artifactId>mcp-json-jackson</artifactId>


add to the mcp-bom

see: graemerocher@1b4271b

sdelamo · 2025-09-15T12:43:03Z

@tzolov

There's another conceptual change that I'm puzzled with. Currently the mcp is self-contained. But with this PR it becomes a "core" component requiring an additional mcp-json-xxx (like mcp-json-jackson) dependency for the same bootstrap experience without breaking changes.

wonder if we should rename the existing mcp module to mcp-core and create a small mcp module that includes both mcp-core and mcp-json-jackson by default?
This will preserver the existing single-click experience for the end users

You are right. To avoid breaking changes, I left in this PR mcp-json-jackson as a compile dependency. Once this PR gets merged, I will create a PR that moves the mcp classes to mcp-core.

sdelamo · 2025-09-15T12:44:02Z

I did not review everything in detail, but from a high level perspective, this PR looks great, thanks for contributing it @graemerocher @sdelamo.

The main open question for me is related to Jackson 3 which is about to be released. If we want to support Jackson 2 and Jackson 3 (which continues to use the same jackson-annotation:2.x dependency) side by side in the MCP SDK, we may want to rename the module mcp-json-jackson to mcp-json-jackson2 and use a jackson2 subpackage instead of jackson in this module.

If we just plan to upgrade from Jackson 2 to Jackson 3, current naming is fine.

I renamed to module to mcp-json-jackson2

* add mcp-json and mcp-json-jackson to BOM * add license header * add mcp-json-jackon as a compile dependency * rename to jackson 2

This pull request creates two modules, `mcp-json` and `mcp-json-jackson`. It removes the `com.fasterxml.jackson.core:jackson-databind` and `com.networknt:json-schema-validator` dependencies from the `mcp` module. The `mcp` module now only depends on `com.fasterxml.jackson.core:jackson-annotations`. To use Jackson, you have to add `mcp-jackson` to your dependencies in addition to `mcp`. I added the dependency `mcp-jackson` to both `mcp-spring-mvc` and `mcp-spring-webflux` to avoid a breaking change in those modules. It provides two [SPI](https://docs.oracle.com/javase/tutorial/sound/SPI-intro.html) `JsonSchemaValidatorSupplier` and `JacksonJsonSchemaValidatorSupplier` to allow easy replacement for consumers who don't want to use Jackson. This pull request also ensures no `McpJsonMapper` is instantiated if one is provided via a builder method. Only if the builders don't receive a `McpJsonMapper` mapper, one is instantiated in the `build` method of the builder. The logic behind this is to allow frameworks to provide a `McpJsonMapper` mapper singleton implementation and feed it to the builders without paying the price of instantiating `McpJsonMappers`, which will not be used. The goal is to be able to use the `ObjectMapper` singleton of an application also for the MCP code. Signed-off-by: Christian Tzolov <[email protected]>

tzolov · 2025-09-15T14:08:12Z

Thank you @graemerocher @sdelamo

Rebased, conflicts resolved, squashed and merged at 80d0ad8

Introduce McpJsonMapper interface to decouple from Jackson

1396084

sdelamo mentioned this pull request Sep 10, 2025

Decouple the module from Jackson Core #487

Open

sdelamo reviewed Sep 11, 2025

View reviewed changes

sdelamo and others added 3 commits September 12, 2025 09:42

cleanup and cache default mapper/validator

f429a45

cleanup

82259bd

graemerocher marked this pull request as ready for review September 12, 2025 08:19

graemerocher added 2 commits September 12, 2025 14:44

formatting

81c2566

correct

aae7347

tzolov self-assigned this Sep 15, 2025

tzolov added this to the 0.13.0 milestone Sep 15, 2025

tzolov added breaking-change enhancement New feature or request labels Sep 15, 2025

tzolov requested changes Sep 15, 2025

View reviewed changes

Address pr feedback (#2)

06403ce

* add mcp-json and mcp-json-jackson to BOM * add license header * add mcp-json-jackon as a compile dependency * rename to jackson 2

tzolov removed the breaking-change label Sep 15, 2025

tzolov closed this Sep 15, 2025

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Introduce McpJsonMapper interface to decouple from Jackson #543

Introduce McpJsonMapper interface to decouple from Jackson #543

graemerocher commented Sep 10, 2025 •

edited

Loading

Uh oh!

sdelamo left a comment

Uh oh!

sdelamo Sep 10, 2025

Uh oh!

He-Pin commented Sep 11, 2025

Uh oh!

sdelamo commented Sep 12, 2025

Uh oh!

sdeleuze commented Sep 12, 2025

Uh oh!

graemerocher commented Sep 12, 2025

Uh oh!

tzolov left a comment

Uh oh!

tzolov Sep 15, 2025

Uh oh!

tzolov Sep 15, 2025

Uh oh!

sdelamo Sep 15, 2025

Uh oh!

tzolov Sep 15, 2025

Uh oh!

sdelamo Sep 15, 2025

Uh oh!

sdelamo commented Sep 15, 2025 •

edited

Loading

Uh oh!

sdelamo commented Sep 15, 2025 •

edited

Loading

Uh oh!

tzolov commented Sep 15, 2025

Uh oh!

Uh oh!

		this.jsonMapper = new JacksonMcpJsonMapper(objectMapper);
		return this;

	this.jsonMapper = new JacksonMcpJsonMapper(objectMapper);
	return this;
	return jsonMapper(new JacksonMcpJsonMapper(objectMapper));

Introduce McpJsonMapper interface to decouple from Jackson #543

Introduce McpJsonMapper interface to decouple from Jackson #543

Conversation

graemerocher commented Sep 10, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

sdelamo left a comment

Choose a reason for hiding this comment

Uh oh!

sdelamo Sep 10, 2025

Choose a reason for hiding this comment

Uh oh!

He-Pin commented Sep 11, 2025

Uh oh!

sdelamo commented Sep 12, 2025

Uh oh!

sdeleuze commented Sep 12, 2025

Uh oh!

graemerocher commented Sep 12, 2025

Uh oh!

tzolov left a comment

Choose a reason for hiding this comment

Uh oh!

tzolov Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

tzolov Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

sdelamo Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

tzolov Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

sdelamo Sep 15, 2025

Choose a reason for hiding this comment

Uh oh!

sdelamo commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

sdelamo commented Sep 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

tzolov commented Sep 15, 2025

Uh oh!

Uh oh!

graemerocher commented Sep 10, 2025 •

edited

Loading

sdelamo commented Sep 15, 2025 •

edited

Loading

sdelamo commented Sep 15, 2025 •

edited

Loading