v0.13.0

Release Notes

🚀 Major Features & Enhancements

Protocol Version Support

• Added MCP protocol version 2025-06-18 support for streamable-http and stateless transports (#558)
  • Set MCP_2025_06_18 as upper supported protocol version
  • Updated LATEST_PROTOCOL_VERSION constant to reflect new upper bound

Module Restructuring

• Extracted mcp-core module (#557) - ⚠️ BREAKING CHANGE

  • Created new mcp-core module free of Jackson dependencies
  • mcp module now serves as an umbrella module bringing together mcp-json-jackson2 and mcp-core
  • Classes are now in different JARs, which may affect classpath dependencies

• Jackson decoupling (#543) - Related to (#557)

  • Abstract away Jackson usage with SPI interfaces
    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 (now mcp-core) module. The mcp-core (mcp previously) 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-core. I added the dependency mcp-jackson to both mcp-spring-mvc and mcp-spring-webflux to avoid a breaking change in those modules.

Enhanced Tool Output Support

• Support for array-type structured content in tools (#551) - ⚠️ BREAKING CHANGE
  • Changed CallToolResult.structuredContent type from Map<String,Object> to Object
  • Now supports both objects and arrays as structured content output
  • Updated JsonSchemaValidator to validate any Object type
  • Deprecated CallToolResult constructors in favor of builder pattern
  • Aligns with MCP specification requirements for array-type output schemas

🐛 Bug Fixes

Session Management

• Fixed LifecycleInitializer error recovery (#549)
  • Initializer can now recover from errors during doInitialize (e.g., HTTP errors)
  • Prevents getting stuck in error state and allows subsequent initialization calls to work
  • Particularly beneficial for OAuth2 token fetch scenarios

Serialization Improvements

• Added JsonInclude annotation to notification records (#552)
  • Enhanced proper JSON serialization for ResourcesUpdatedNotification and LoggingMessageNotification
  • Excludes absent (null/Optional.empty()) fields from serialized output
  • Ensures consistent serialization behavior across all notification types

Test Infrastructure

• Standardized test parameterization (#556)
  • Replaced @valuesource with @MethodSource for parameterized tests
  • Added consistent clientsForTesting() methods
  • Removed hardcoded Spring-related labels from framework-agnostic mcp-test module
  • Minor breaking change: moved utility classes from io.modelcontextprotocol.utils to io.modelcontextprotocol.util

⚠️ Breaking Changes Summary

1. Module Structure Changes (#557 and #543))

   • Classes previously in mcp are now in mcp-core. mcp module now serves as an umbrella module bringing together mcp-json-jackson2 and mcp-core.
   • May require classpath adjustments

2. Tool Result API Changes (#551)

   • CallToolResult.structuredContent() now returns Object instead of Map<String,Object>
   • Requires explicit casting when accessing map-like content: ((Map<String,Object>) result.structuredContent()).get("key")
   • Deprecated constructors - use builder pattern instead
   • Custom JsonSchemaValidator implementations need signature updates

3. Package Name Changes (#556)

   • Utility classes moved from io.modelcontextprotocol.utils to io.modelcontextprotocol.util

📝 Migration Guide

For Tool Result Changes

// Before
result.structuredContent().get("key")

// After  
((Map<String,Object>) result.structuredContent()).get("key")

// Use builder pattern instead of deprecated constructors
CallToolResult.builder()
  .content(content)
  .isError(isError)
  .structuredContent(structuredContent)
  .build()

For Module Dependencies

Ensure your dependencies account for the new module structure:

• mcp-core for Jackson-free core functionality
• mcp continues to work as umbrella module with Jackson support

New Contributors

• @sdelamo made their first contribution in #557
• @graemerocher made their first contribution in #543
• @valuesource made their first contribution in #556

Full Changelog: v0.12.1...v0.13.0