Skip to content

Latest commit

 

History

History
328 lines (239 loc) · 11.3 KB

migration-0.8.0.md

File metadata and controls

328 lines (239 loc) · 11.3 KB

MCP Java SDK Migration Guide: 0.7.0 to 0.8.0

This document outlines the breaking changes and provides guidance on how to migrate your code from version 0.7.0 to 0.8.0.

The 0.8.0 refactoring introduces a session-based architecture for server-side MCP implementations. It improves the SDK's ability to handle multiple concurrent client connections and provides an API better aligned with the MCP specification. The main changes include:

  1. Introduction of a session-based architecture
  2. New transport provider abstraction
  3. Exchange objects for client interaction
  4. Renamed and reorganized interfaces
  5. Updated handler signatures

Breaking Changes

1. Interface Renaming

Several interfaces have been renamed to better reflect their roles:

0.7.0 (Old) 0.8.0 (New)
ClientMcpTransport McpClientTransport
ServerMcpTransport McpServerTransport
DefaultMcpSession McpClientSession, McpServerSession

2. New Server Transport Architecture

The most significant change is the introduction of the McpServerTransportProvider interface, which replaces direct usage of ServerMcpTransport when creating servers. This new pattern separates the concerns of:

  1. Transport Provider: Manages connections with clients and creates individual transports for each connection
  2. Server Transport: Handles communication with a specific client connection
0.7.0 (Old) 0.8.0 (New)
ServerMcpTransport McpServerTransportProvider + McpServerTransport
Direct transport usage Session-based transport usage

Before (0.7.0):

// Create a transport
ServerMcpTransport transport = new WebFluxSseServerTransport(objectMapper, "/mcp/message");

// Create a server with the transport
McpServer.sync(transport)
    .serverInfo("my-server", "1.0.0")
    .build();

After (0.8.0):

// Create a transport provider
McpServerTransportProvider transportProvider = new WebFluxSseServerTransportProvider(objectMapper, "/mcp/message");

// Create a server with the transport provider
McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .build();

3. Handler Method Signature Changes

Tool, resource, and prompt handlers now receive an additional exchange parameter that provides access to client capabilities and methods to interact with the client:

0.7.0 (Old) 0.8.0 (New)
(args) -> result (exchange, args) -> result

The exchange objects (McpAsyncServerExchange and McpSyncServerExchange) provide context for the current session and access to session-specific operations.

Before (0.7.0):

// Tool handler
.tool(calculatorTool, args -> new CallToolResult("Result: " + calculate(args)))

// Resource handler
.resource(fileResource, req -> new ReadResourceResult(readFile(req)))

// Prompt handler
.prompt(analysisPrompt, req -> new GetPromptResult("Analysis prompt"))

After (0.8.0):

// Tool handler
.tool(calculatorTool, (exchange, args) -> new CallToolResult("Result: " + calculate(args)))

// Resource handler
.resource(fileResource, (exchange, req) -> new ReadResourceResult(readFile(req)))

// Prompt handler
.prompt(analysisPrompt, (exchange, req) -> new GetPromptResult("Analysis prompt"))

4. Registration vs. Specification

The naming convention for handlers has changed from "Registration" to "Specification":

0.7.0 (Old) 0.8.0 (New)
AsyncToolRegistration AsyncToolSpecification
SyncToolRegistration SyncToolSpecification
AsyncResourceRegistration AsyncResourceSpecification
SyncResourceRegistration SyncResourceSpecification
AsyncPromptRegistration AsyncPromptSpecification
SyncPromptRegistration SyncPromptSpecification

5. Roots Change Handler Updates

The roots change handlers now receive an exchange parameter:

Before (0.7.0):

.rootsChangeConsumers(List.of(
    roots -> {
        // Process roots
    }
))

After (0.8.0):

.rootsChangeHandlers(List.of(
    (exchange, roots) -> {
        // Process roots with access to exchange
    }
))

6. Server Creation Method Changes

The McpServer factory methods now accept McpServerTransportProvider instead of ServerMcpTransport:

0.7.0 (Old) 0.8.0 (New)
McpServer.async(ServerMcpTransport) McpServer.async(McpServerTransportProvider)
McpServer.sync(ServerMcpTransport) McpServer.sync(McpServerTransportProvider)

The method names for creating servers have been updated:

Root change handlers now receive an exchange object:

0.7.0 (Old) 0.8.0 (New)
rootsChangeConsumers(List<Consumer<List<Root>>>) rootsChangeHandlers(List<BiConsumer<McpSyncServerExchange, List<Root>>>)
rootsChangeConsumer(Consumer<List<Root>>) rootsChangeHandler(BiConsumer<McpSyncServerExchange, List<Root>>)

7. Direct Server Methods Moving to Exchange

Several methods that were previously available directly on the server are now accessed through the exchange object:

0.7.0 (Old) 0.8.0 (New)
server.listRoots() exchange.listRoots()
server.createMessage() exchange.createMessage()
server.getClientCapabilities() exchange.getClientCapabilities()
server.getClientInfo() exchange.getClientInfo()

The direct methods are deprecated and will be removed in 0.9.0:

  • McpSyncServer.listRoots()
  • McpSyncServer.getClientCapabilities()
  • McpSyncServer.getClientInfo()
  • McpSyncServer.createMessage()
  • McpAsyncServer.listRoots()
  • McpAsyncServer.getClientCapabilities()
  • McpAsyncServer.getClientInfo()
  • McpAsyncServer.createMessage()

Deprecation Notices

The following components are deprecated in 0.8.0 and will be removed in 0.9.0:

  • ClientMcpTransport interface (use McpClientTransport instead)
  • ServerMcpTransport interface (use McpServerTransport instead)
  • DefaultMcpSession class (use McpClientSession instead)
  • WebFluxSseServerTransport class (use WebFluxSseServerTransportProvider instead)
  • WebMvcSseServerTransport class (use WebMvcSseServerTransportProvider instead)
  • StdioServerTransport class (use StdioServerTransportProvider instead)
  • All *Registration classes (use corresponding *Specification classes instead)
  • Direct server methods for client interaction (use exchange object instead)

Migration Examples

Example 1: Creating a Server

Before (0.7.0):

// Create a transport
ServerMcpTransport transport = new WebFluxSseServerTransport(objectMapper, "/mcp/message");

// Create a server with the transport
var server = McpServer.sync(transport)
    .serverInfo("my-server", "1.0.0")
    .tool(calculatorTool, args -> new CallToolResult("Result: " + calculate(args)))
    .rootsChangeConsumers(List.of(
        roots -> System.out.println("Roots changed: " + roots)
    ))
    .build();

// Get client capabilities directly from server
ClientCapabilities capabilities = server.getClientCapabilities();

After (0.8.0):

// Create a transport provider
McpServerTransportProvider transportProvider = new WebFluxSseServerTransportProvider(objectMapper, "/mcp/message");

// Create a server with the transport provider
var server = McpServer.sync(transportProvider)
    .serverInfo("my-server", "1.0.0")
    .tool(calculatorTool, (exchange, args) -> {
        // Get client capabilities from exchange
        ClientCapabilities capabilities = exchange.getClientCapabilities();
        return new CallToolResult("Result: " + calculate(args));
    })
    .rootsChangeHandlers(List.of(
        (exchange, roots) -> System.out.println("Roots changed: " + roots)
    ))
    .build();

Example 2: Implementing a Tool with Client Interaction

Before (0.7.0):

McpServerFeatures.SyncToolRegistration tool = new McpServerFeatures.SyncToolRegistration(
    new Tool("weather", "Get weather information", schema),
    args -> {
        String location = (String) args.get("location");
        // Cannot interact with client from here
        return new CallToolResult("Weather for " + location + ": Sunny");
    }
);

var server = McpServer.sync(transport)
    .tools(tool)
    .build();

// Separate call to create a message
CreateMessageResult result = server.createMessage(new CreateMessageRequest(...));

After (0.8.0):

McpServerFeatures.SyncToolSpecification tool = new McpServerFeatures.SyncToolSpecification(
    new Tool("weather", "Get weather information", schema),
    (exchange, args) -> {
        String location = (String) args.get("location");
        
        // Can interact with client directly from the tool handler
        CreateMessageResult result = exchange.createMessage(new CreateMessageRequest(...));
        
        return new CallToolResult("Weather for " + location + ": " + result.content());
    }
);

var server = McpServer.sync(transportProvider)
    .tools(tool)
    .build();

Example 3: Converting Existing Registration Classes

If you have custom implementations of the registration classes, you can convert them to the new specification classes:

Before (0.7.0):

McpServerFeatures.AsyncToolRegistration toolReg = new McpServerFeatures.AsyncToolRegistration(
    tool,
    args -> Mono.just(new CallToolResult("Result"))
);

McpServerFeatures.AsyncResourceRegistration resourceReg = new McpServerFeatures.AsyncResourceRegistration(
    resource,
    req -> Mono.just(new ReadResourceResult(List.of()))
);

After (0.8.0):

// Option 1: Create new specification directly
McpServerFeatures.AsyncToolSpecification toolSpec = new McpServerFeatures.AsyncToolSpecification(
    tool,
    (exchange, args) -> Mono.just(new CallToolResult("Result"))
);

// Option 2: Convert from existing registration (during transition)
McpServerFeatures.AsyncToolRegistration oldToolReg = /* existing registration */;
McpServerFeatures.AsyncToolSpecification toolSpec = oldToolReg.toSpecification();

// Similarly for resources
McpServerFeatures.AsyncResourceSpecification resourceSpec = new McpServerFeatures.AsyncResourceSpecification(
    resource,
    (exchange, req) -> Mono.just(new ReadResourceResult(List.of()))
);

Architecture Changes

Session-Based Architecture

In 0.8.0, the MCP Java SDK introduces a session-based architecture where each client connection has its own session. This allows for better isolation between clients and more efficient resource management.

The McpServerTransportProvider is responsible for creating McpServerTransport instances for each session, and the McpServerSession manages the communication with a specific client.

Exchange Objects

The new exchange objects (McpAsyncServerExchange and McpSyncServerExchange) provide access to client-specific information and methods. They are passed to handler functions as the first parameter, allowing handlers to interact with the specific client that made the request.

Conclusion

The changes in version 0.8.0 represent a significant architectural improvement to the MCP Java SDK. While they require some code changes, the new design provides a more flexible and maintainable foundation for building MCP applications.

For assistance with migration or to report issues, please open an issue on the GitHub repository.