Add sampling documentation

Author: tvallin

docs/mcp-declarative/README.md

@@ -494,6 +494,90 @@ 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);
+```
+
+#### 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`.
+
+```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

@@ -659,6 +659,110 @@ private class CancellationTool implements McpTool {
 }
 ```
 
+### 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);
+```
+
+#### 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`.
+
+```java
+import java.time.Duration;
+
+class SamplingTool implements McpTool {
+    @Override
+    public String name() {
+        return "sampling-tool";
+    }
+
+    @Override
+    public String description() {
+        return "Uses MCP Sampling to ask the connected client model.";
+    }
+
+    @Override
+    public String schema() {
+        return "";
+    }
+
+    @Override
+    public List<McpToolContent> process(McpRequest request) {
+        var sampling = request.features().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());
+        }
+    }
+}
+```
+
 ## Configuration
 
 MCP server configuration can be defined using Helidon configuration files. Example in YAML:

server/src/test/java/io/helidon/extensions/mcp/server/McpSamplingResponseTest.java

@@ -0,0 +1,43 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+package io.helidon.extensions.mcp.server;
+
+import org.junit.jupiter.api.Test;
+
+import static org.hamcrest.MatcherAssert.assertThat;
+import static org.hamcrest.Matchers.instanceOf;
+import static org.hamcrest.Matchers.is;
+
+class McpSamplingResponseTest {
+
+    @Test
+    void testCustomValues() {
+        McpSamplingResponse response = McpSamplingResponse.builder()
+                .model("helidon-model")
+                .stopReason(McpStopReason.END_TURN)
+                .message(McpSamplingMessages.textContent("text", McpRole.USER))
+                .build();
+
+        assertThat(response.stopReason().isPresent(), is(true));
+        assertThat(response.stopReason().get(), is(McpStopReason.END_TURN));
+        assertThat(response.model(), is("helidon-model"));
+        assertThat(response.message(), instanceOf(McpSamplingTextContent.class));
+
+        McpSamplingTextContent text = (McpSamplingTextContent) response.message();
+        assertThat(text.text(), is("text"));
+        assertThat(text.role(), is(McpRole.USER));
+    }
+}