Review changes

Author: tvallin

docs/mcp-declarative/README.md

@@ -496,88 +496,18 @@ List<McpToolContent> cancellationTool(McpCancellation cancellation) {
 
 ### Sampling
 
-The MCP Sampling feature provides a standardized mechanism that allows servers to request LLM sampling operations from language
-models through connected clients. It enables servers to seamlessly integrate AI capabilities into their workflows without
-requiring API keys. Like other MCP features, sampling can be accessed via the MCP request features.
-Sampling support is optional for clients, and servers can verify its availability using the `enabled` method:
-
-```java
-var sampling = request.features().sampling();
-if (!sampling.enabled()) {
-}
-```
-
-If the client supports sampling, you can send a sampling request using the request method. A builder is provided to configure
-and customize the sampling request as needed:
-
-```java
-McpSamplingRequest request = McpSamplingRequest.builder()
-                .maxTokens(1)
-                .temperature(0.1)
-                .costPriority(0.1)
-                .speedPriority(0.1)
-                .hints(List.of("hint1"))
-                .metadata(JsonValue.TRUE)
-                .intelligencePriority(0.1)
-                .systemPrompt("system prompt")
-                .timeout(Duration.ofSeconds(10))
-                .stopSequences(List.of("stop1"))
-                .includeContext(McpIncludeContext.NONE)
-                .addMessage(McpSamplingMessages.textContent("text", McpRole.USER))
-                .build();
-```
-
-Once your request is built, send it using the sampling feature. The request method may throw an `McpSamplingException` if an
-error occurs during processing. On success, it returns an McpSamplingResponse containing the response message, the model used,
-and optionally a stop reason.
-
-```java
-try {
-    McpSamplingResponse response = sampling.request(req -> req.addMessage(message));
-} catch(McpSamplingException exception) {
-    // Manage error
-}
-```
-
-The messages you send are prompts to the language model, and they follow the same structure as MCP prompts. You can use the
-`McpSamplingMessages` utility class to create different types of messages for the client model:
-
-```java
-var text = McpSamplingMessages.textContent("Explain Helidon MCP in one paragraph.", McpRole.USER);
-var image = McpSamplingMessages.imageContent(pngBytes, MediaTypes.create("image/png"), McpRole.USER);
-var audio = McpSamplingMessages.audioContent(wavBytes, MediaTypes.create("audio/wav"), McpRole.USER);
-```
+See the full [sampling documentation details](../mcp/README.md#sampling)
 
 #### Example
 
-Below is an example of a tool that uses the Sampling feature. If the connected client does not support sampling, the tool
-throws a `McpToolErrorException`.
+Below is an example of a tool that uses the Sampling feature. `McpSampling` object can be used as method parameter.
 
 ```java
 @Mcp.Tool("Uses MCP Sampling to ask the connected client model.")
 List<McpToolContent> samplingTool(McpSampling sampling) {
-    if (!sampling.enabled()) {
-        throw new McpToolErrorException("This tool requires sampling feature");
-    }
-
-    try {
-        McpSamplingResponse response = sampling.request(req -> req
-                .timeout(Duration.ofSeconds(10))
-                .systemPrompt("You are a concise, helpful assistant.")
-                .addMessage(McpSamplingMessages.textContent("Write a 3-line summary of Helidon MCP Sampling.", McpRole.USER)));
-
-        McpSamplingMessage message = response.message();
-        if (message instanceof McpSamplingTextContent text) {
-            return List.of(McpToolContents.textContent(text.text()));
-        }
-        throw new McpToolErrorException("Received non-text sampling content.");
-    } catch (McpSamplingException e) {
-        throw new McpToolErrorException(e.getMessage());
-    }
 }
 ```
 
-
 ## References
 
 - [MCP Specification](https://modelcontextprotocol.io/introduction)

docs/mcp/README.md

@@ -719,8 +719,6 @@ Below is an example of a tool that uses the Sampling feature. If the connected c
 throws a `McpToolErrorException`.
 
 ```java
-import java.time.Duration;
-
 class SamplingTool implements McpTool {
     @Override
     public String name() {
@@ -750,12 +748,7 @@ class SamplingTool implements McpTool {
                     .timeout(Duration.ofSeconds(10))
                     .systemPrompt("You are a concise, helpful assistant.")
                     .addMessage(McpSamplingMessages.textContent("Write a 3-line summary of Helidon MCP Sampling.", McpRole.USER)));
-
-            McpSamplingMessage message = response.message();
-            if (message instanceof McpSamplingTextContent text) {
-                return List.of(McpToolContents.textContent(text.text()));
-            }
-            throw new McpToolErrorException("Received non-text sampling content.");
+            return List.of(McpToolContents.textContent(response.asTextMessage()));
         } catch (McpSamplingException e) {
             throw new McpToolErrorException(e.getMessage());
         }

server/src/main/java/io/helidon/extensions/mcp/server/McpContent.java

@@ -22,7 +22,6 @@
 public sealed interface McpContent permits McpTextContent,
                                            McpMediaContent,
                                            McpResourceContent,
-                                           McpSamplingMessage,
                                            McpEmbeddedResource {
     /**
      * Content type.

server/src/main/java/io/helidon/extensions/mcp/server/McpJsonRpc.java

@@ -378,13 +378,13 @@ static JsonObjectBuilder toJson(McpContent content) {
     }
 
     static JsonObjectBuilder toJson(McpSamplingMessage message) {
-        if (message instanceof McpSamplingTextContentImpl text) {
+        if (message instanceof McpSamplingTextMessageImpl text) {
             return toJson(text);
         }
-        if (message instanceof McpSamplingImageContentImpl image) {
+        if (message instanceof McpSamplingImageMessageImpl image) {
             return toJson(image);
         }
-        if (message instanceof McpSamplingAudioContentImpl resource) {
+        if (message instanceof McpSamplingAudioMessageImpl resource) {
             return toJson(resource);
         }
         throw new IllegalArgumentException("Unsupported content type: " + message.getClass().getName());
@@ -427,7 +427,7 @@ static JsonObjectBuilder toJson(McpPromptAudioContent audio) {
                 .add("content", toJson(audio.content()));
     }
 
-    static JsonObjectBuilder toJson(McpSamplingImageContent image) {
+    static JsonObjectBuilder toJson(McpSamplingImageMessage image) {
         return JSON_BUILDER_FACTORY.createObjectBuilder()
                 .add("role", image.role().text())
                 .add("content", JSON_BUILDER_FACTORY.createObjectBuilder()
@@ -436,15 +436,15 @@ static JsonObjectBuilder toJson(McpSamplingImageContent image) {
                         .add("mimeType", image.mediaType().text()));
     }
 
-    static JsonObjectBuilder toJson(McpSamplingTextContent text) {
+    static JsonObjectBuilder toJson(McpSamplingTextMessage text) {
         return JSON_BUILDER_FACTORY.createObjectBuilder()
                 .add("role", text.role().text())
                 .add("content", JSON_BUILDER_FACTORY.createObjectBuilder()
                         .add("type", text.type().text())
                         .add("text", text.text()));
     }
 
-    static JsonObjectBuilder toJson(McpSamplingAudioContent audio) {
+    static JsonObjectBuilder toJson(McpSamplingAudioMessage audio) {
         return JSON_BUILDER_FACTORY.createObjectBuilder()
                 .add("role", audio.role().text())
                 .add("content", JSON_BUILDER_FACTORY.createObjectBuilder()
@@ -577,8 +577,6 @@ static McpSamplingResponse createSamplingResponse(JsonObject object) throws McpS
                     throw new McpSamplingException(error.message());
                 });
         try {
-            var builder = McpSamplingResponse.builder();
-
             var result = find(object, "result")
                     .filter(McpJsonRpc::isJsonObject)
                     .map(JsonValue::asJsonObject)
@@ -587,15 +585,13 @@ static McpSamplingResponse createSamplingResponse(JsonObject object) throws McpS
             String model = result.getString("model");
             McpRole role = McpRole.valueOf(result.getString("role").toUpperCase());
             McpSamplingMessage message = parseMessage(role, result.getJsonObject("content"));
-            Optional<McpStopReason> stopReason = find(result, "stopReason")
+            McpStopReason stopReason = find(result, "stopReason")
                     .filter(McpJsonRpc::isJsonString)
                     .map(JsonString.class::cast)
                     .map(JsonString::getString)
-                    .map(McpStopReason::map);
-            builder.model(model);
-            builder.message(message);
-            builder.stopReason(stopReason);
-            return builder.build();
+                    .map(McpStopReason::map)
+                    .orElse(null);
+            return new McpSamplingResponseImpl(message, model, stopReason);
         } catch (Exception e) {
             throw new McpSamplingException("Wrong sampling response format", e);
         }
@@ -651,20 +647,19 @@ static JsonObject timeoutResponse(long requestId) {
 
     private static McpSamplingMessage parseMessage(McpRole role, JsonObject object) {
         String type = object.getString("type").toUpperCase();
-        McpContent.ContentType contentType = McpContent.ContentType.valueOf(type);
-        return switch (contentType) {
-            case TEXT -> new McpSamplingTextContentImpl(object.getString("text"), role);
+        McpSamplingMessageType messageType = McpSamplingMessageType.valueOf(type);
+        return switch (messageType) {
+            case TEXT -> new McpSamplingTextMessageImpl(object.getString("text"), role);
             case IMAGE -> {
                 byte[] data = object.getString("data").getBytes(StandardCharsets.UTF_8);
                 MediaType mediaType = MediaTypes.create(object.getString("mimeType"));
-                yield new McpSamplingImageContentImpl(data, mediaType, role);
+                yield new McpSamplingImageMessageImpl(data, mediaType, role);
             }
             case AUDIO -> {
                 byte[] data = object.getString("data").getBytes(StandardCharsets.UTF_8);
                 MediaType mediaType = MediaTypes.create(object.getString("mimeType"));
-                yield new McpSamplingAudioContentImpl(data, mediaType, role);
+                yield new McpSamplingAudioMessageImpl(data, mediaType, role);
             }
-            default -> throw new IllegalArgumentException("Unknown content type: " + type);
         };
     }
 

server/src/main/java/io/helidon/extensions/mcp/server/McpSamplingAudioContent.java renamed to server/src/main/java/io/helidon/extensions/mcp/server/McpSamplingAudioMessage.java

@@ -18,6 +18,6 @@
 /**
  * MCP sampling audio content.
  */
-public sealed interface McpSamplingAudioContent extends McpSamplingMessage,
-                                                        McpSamplingMediaContent permits McpSamplingAudioContentImpl {
+public sealed interface McpSamplingAudioMessage extends McpSamplingMessage,
+                                                        McpSamplingMediaMessage permits McpSamplingAudioMessageImpl {
 }

server/src/main/java/io/helidon/extensions/mcp/server/McpSamplingAudioContentImpl.java renamed to server/src/main/java/io/helidon/extensions/mcp/server/McpSamplingAudioMessageImpl.java

@@ -22,20 +22,20 @@
 /**
  * MCP sampling audio content.
  */
-final class McpSamplingAudioContentImpl implements McpSamplingAudioContent {
+final class McpSamplingAudioMessageImpl implements McpSamplingAudioMessage {
     private final byte[] data;
     private final McpRole role;
     private final MediaType type;
 
-    McpSamplingAudioContentImpl(byte[] data, MediaType type, McpRole role) {
+    McpSamplingAudioMessageImpl(byte[] data, MediaType type, McpRole role) {
         this.data = data;
         this.role = role;
         this.type = type;
     }
 
     @Override
-    public ContentType type() {
-        return ContentType.AUDIO;
+    public McpSamplingMessageType type() {
+        return McpSamplingMessageType.AUDIO;
     }
 
     @Override
@@ -55,11 +55,11 @@ public byte[] data() {
 
     @Override
     public byte[] decodeBase64Data() {
-        return Base64.getMimeDecoder().decode(data);
+        return Base64.getDecoder().decode(data);
     }
 
     @Override
     public String encodeBase64Data() {
-        return Base64.getMimeEncoder().encodeToString(data);
+        return Base64.getEncoder().encodeToString(data);
     }
 }

server/src/main/java/io/helidon/extensions/mcp/server/McpSamplingImageContent.java renamed to server/src/main/java/io/helidon/extensions/mcp/server/McpSamplingImageMessage.java

@@ -18,7 +18,7 @@
 /**
  * MCP sampling image content.
  */
-public sealed interface McpSamplingImageContent extends McpSamplingMessage,
-                                                        McpSamplingMediaContent permits McpSamplingImageContentImpl {
+public sealed interface McpSamplingImageMessage extends McpSamplingMessage,
+                                                        McpSamplingMediaMessage permits McpSamplingImageMessageImpl {
 
 }

server/src/main/java/io/helidon/extensions/mcp/server/McpSamplingImageContentImpl.java renamed to server/src/main/java/io/helidon/extensions/mcp/server/McpSamplingImageMessageImpl.java

@@ -22,20 +22,20 @@
 /**
  * MCP sampling image content.
  */
-final class McpSamplingImageContentImpl implements McpSamplingImageContent {
+final class McpSamplingImageMessageImpl implements McpSamplingImageMessage {
     private final byte[] data;
     private final McpRole role;
     private final MediaType type;
 
-    McpSamplingImageContentImpl(byte[] data, MediaType mediaType, McpRole role) {
+    McpSamplingImageMessageImpl(byte[] data, MediaType mediaType, McpRole role) {
         this.data = data;
         this.role = role;
         this.type = mediaType;
     }
 
     @Override
-    public ContentType type() {
-        return ContentType.IMAGE;
+    public McpSamplingMessageType type() {
+        return McpSamplingMessageType.IMAGE;
     }
 
     @Override
@@ -55,11 +55,11 @@ public byte[] data() {
 
     @Override
     public byte[] decodeBase64Data() {
-        return Base64.getMimeDecoder().decode(data);
+        return Base64.getDecoder().decode(data);
     }
 
     @Override
     public String encodeBase64Data() {
-        return Base64.getMimeEncoder().encodeToString(data);
+        return Base64.getEncoder().encodeToString(data);
     }
 }

server/src/main/java/io/helidon/extensions/mcp/server/McpSamplingMediaContent.java renamed to server/src/main/java/io/helidon/extensions/mcp/server/McpSamplingMediaMessage.java

@@ -20,7 +20,7 @@
 /**
  * MCP sampling media content.
  */
-public sealed interface McpSamplingMediaContent permits McpSamplingAudioContent, McpSamplingImageContent {
+public sealed interface McpSamplingMediaMessage permits McpSamplingAudioMessage, McpSamplingImageMessage {
     /**
      * Image content raw data.
      *
@@ -29,14 +29,14 @@ public sealed interface McpSamplingMediaContent permits McpSamplingAudioContent,
     byte[] data();
 
     /**
-     * Media content decoded data.
+     * Returns the decoded image data using base64 decoder.
      *
      * @return decoded content.
      */
     byte[] decodeBase64Data();
 
     /**
-     * Media content data encoded in base64.
+     * Returns the encoded image data using base64 encoder.
      *
      * @return content in base64.
      */

server/src/main/java/io/helidon/extensions/mcp/server/McpSamplingMessage.java

@@ -19,13 +19,18 @@
 /**
  * MCP sampling message.
  */
-public sealed interface McpSamplingMessage extends McpContent permits McpSamplingTextContent,
-                                                                      McpSamplingImageContent,
-                                                                      McpSamplingAudioContent {
+public sealed interface McpSamplingMessage permits McpSamplingTextMessage, McpSamplingImageMessage, McpSamplingAudioMessage {
     /**
      * Sampling message role.
      *
      * @return role
      */
     McpRole role();
+
+    /**
+     * Sampling message type.
+     *
+     * @return type
+     */
+    McpSamplingMessageType type();
 }