java-sdk/mcp-docs/0.6.0-MIGRATION-GUIDE.md

# Spring AI MCP 0.6.0 Migration Guide

This guide outlines the steps required to migrate your code to Spring AI MCP 0.6.0.

## Key Changes

- New builder patterns for `McpClient` and `McpServer`
- Introduction of dedicated feature classes for sync/async operations
- Enhanced type safety and reactive support
- Deprecated methods and classes marked for removal

## Client Migration

### Creating Clients

Before:
```java
// Sync client
McpClient.using(transport)
    .requestTimeout(Duration.ofSeconds(5))
    .sync();

// Async client
McpClient.using(transport)
    .requestTimeout(Duration.ofSeconds(5))
    .async();
```

After:
```java
// Sync client
McpClient.sync(transport)
    .requestTimeout(Duration.ofSeconds(5))
    .build();

// Async client
McpClient.async(transport)
    .requestTimeout(Duration.ofSeconds(5))
    .build();
```

### Change Consumers

Before:
```java
// Sync client
McpClient.using(transport)
    .toolsChangeConsumer(tools -> handleTools(tools))
    .resourcesChangeConsumer(resources -> handleResources(resources))
    .promptsChangeConsumer(prompts -> handlePrompts(prompts))
    .sync();

// Async client
McpClient.using(transport)
    .toolsChangeConsumer(tools -> handleTools(tools))
    .resourcesChangeConsumer(resources -> handleResources(resources))
    .promptsChangeConsumer(prompts -> handlePrompts(prompts))
    .async();
```

After:
```java
// Sync client
McpClient.sync(transport)
    .toolsChangeConsumer(tools -> handleTools(tools))
    .resourcesChangeConsumer(resources -> handleResources(resources))
    .promptsChangeConsumer(prompts -> handlePrompts(prompts))
    .build();

// Async client
McpClient.async(transport)
    .toolsChangeConsumer(tools -> Mono.fromRunnable(() -> handleTools(tools)))
    .resourcesChangeConsumer(resources -> Mono.fromRunnable(() -> handleResources(resources)))
    .promptsChangeConsumer(prompts -> Mono.fromRunnable(() -> handlePrompts(prompts)))
    .build();
```

### Sampling Handlers

Before:
```java
// Sync client
McpClient.using(transport)
    .sampling(request -> new CreateMessageResult("response"))
    .sync();

// Async client
McpClient.using(transport)
    .sampling(request -> new CreateMessageResult("response"))
    .async();
```

After:
```java
// Sync client
McpClient.sync(transport)
    .sampling(request -> new CreateMessageResult("response"))
    .build();

// Async client
McpClient.async(transport)
    .sampling(request -> Mono.just(new CreateMessageResult("response")))
    .build();
```

## Server Migration

### Creating Servers

Before:
```java
// Sync server
McpServer.using(transport)
    .serverInfo("test-server", "1.0.0")
    .sync();

// Async server
McpServer.using(transport)
    .serverInfo("test-server", "1.0.0")
    .async();
```

After:
```java
// Sync server
McpServer.sync(transport)
    .serverInfo("test-server", "1.0.0")
    .build();

// Async server
McpServer.async(transport)
    .serverInfo("test-server", "1.0.0")
    .build();
```

### Tool Registration

Before:
```java
// Using ToolRegistration record
new ToolRegistration(
    new Tool("calculator", "Performs calculations", schema),
    args -> new CallToolResult("result")
);
```

After:
```java
// Sync server
new McpServerFeatures.SyncToolRegistration(
    new Tool("calculator", "Performs calculations", schema),
    args -> new CallToolResult("result")
);

// Async server
new McpServerFeatures.AsyncToolRegistration(
    new Tool("calculator", "Performs calculations", schema),
    args -> Mono.just(new CallToolResult("result"))
);
```

### Resource Registration

Before:
```java
// Using ResourceRegistration record
new ResourceRegistration(
    new Resource("docs", "Documentation", "text/markdown"),
    request -> new ReadResourceResult(content)
);
```

After:
```java
// Sync server
new McpServerFeatures.SyncResourceRegistration(
    new Resource("docs", "Documentation", "text/markdown"),
    request -> new ReadResourceResult(content)
);

// Async server
new McpServerFeatures.AsyncResourceRegistration(
    new Resource("docs", "Documentation", "text/markdown"),
    request -> Mono.just(new ReadResourceResult(content))
);
```

### Prompt Registration

Before:
```java
// Using PromptRegistration record
new PromptRegistration(
    new Prompt("analyze", "Code analysis"),
    request -> new GetPromptResult("result")
);
```

After:
```java
// Sync server
new McpServerFeatures.SyncPromptRegistration(
    new Prompt("analyze", "Code analysis"),
    request -> new GetPromptResult("result")
);

// Async server
new McpServerFeatures.AsyncPromptRegistration(
    new Prompt("analyze", "Code analysis"),
    request -> Mono.just(new GetPromptResult("result"))
);
```

## Spring Integration Changes

### Tool Helper Changes

Before:
```java
ToolHelper.toToolRegistration(functionCallback);
ToolHelper.toToolRegistration(functionCallbacks);
```

After:
```java
ToolHelper.toSyncToolRegistration(functionCallback);
ToolHelper.toSyncToolRegistration(functionCallbacks);
```

## Deprecated APIs

The following APIs are deprecated and will be removed in a future release:

- `McpClient.using()` - Use `McpClient.sync()` or `McpClient.async()` instead
- `McpServer.using()` - Use `McpServer.sync()` or `McpServer.async()` instead
- `McpServer.ToolRegistration` - Use `McpServerFeatures.SyncToolRegistration` or `McpServerFeatures.AsyncToolRegistration` instead
- `McpServer.ResourceRegistration` - Use `McpServerFeatures.SyncResourceRegistration` or `McpServerFeatures.AsyncResourceRegistration` instead
- `McpServer.PromptRegistration` - Use `McpServerFeatures.SyncPromptRegistration` or `McpServerFeatures.AsyncPromptRegistration` instead
- `ToolHelper.toToolRegistration()` - Use `ToolHelper.toSyncToolRegistration()` instead