fix: support freeform stopReason in sampling (#327)

- Add string values and JsonCreator method to StopReason enum
- Map unknown stop reason values to UNKNOWN constant for forward compatibility
- Add test coverage for unknown stop reason deserialization

Spec: https://github.com/modelcontextprotocol/modelcontextprotocol/blob/f5ccad944fdf2b7d9cc70cf817f66ca5a8aa03a4/schema/2024-11-05/schema.ts#L807

Resolves #328

Author: LucaButBoring

mcp/src/main/java/io/modelcontextprotocol/spec/McpSchema.java

@@ -6,10 +6,12 @@
 
 import java.io.IOException;
 import java.util.ArrayList;
+import java.util.Arrays;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
 
+import com.fasterxml.jackson.annotation.JsonCreator;
 import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
 import com.fasterxml.jackson.annotation.JsonInclude;
 import com.fasterxml.jackson.annotation.JsonProperty;
@@ -1136,9 +1138,24 @@ public record CreateMessageResult(// @formatter:off
 		@JsonProperty("stopReason") StopReason stopReason) {
 
 		public enum StopReason {
-			@JsonProperty("endTurn") END_TURN,
-			@JsonProperty("stopSequence") STOP_SEQUENCE,
-			@JsonProperty("maxTokens") MAX_TOKENS
+			@JsonProperty("endTurn") END_TURN("endTurn"),
+			@JsonProperty("stopSequence") STOP_SEQUENCE("stopSequence"),
+			@JsonProperty("maxTokens") MAX_TOKENS("maxTokens"),
+			@JsonProperty("unknown") UNKNOWN("unknown");
+
+			private final String value;
+
+			StopReason(String value) {
+				this.value = value;
+			}
+
+			@JsonCreator
+			private static StopReason of(String value) {
+				return Arrays.stream(StopReason.values())
+						.filter(stopReason -> stopReason.value.equals(value))
+						.findFirst()
+						.orElse(StopReason.UNKNOWN);
+			}
 		}
 
 		public static Builder builder() {

mcp/src/test/java/io/modelcontextprotocol/spec/McpSchemaTests.java

@@ -883,6 +883,23 @@ void testCreateMessageResult() throws Exception {
 							{"role":"assistant","content":{"type":"text","text":"Assistant response"},"model":"gpt-4","stopReason":"endTurn"}"""));
 	}
 
+	@Test
+	void testCreateMessageResultUnknownStopReason() throws Exception {
+		String input = """
+				{"role":"assistant","content":{"type":"text","text":"Assistant response"},"model":"gpt-4","stopReason":"arbitrary value"}""";
+
+		McpSchema.CreateMessageResult value = mapper.readValue(input, McpSchema.CreateMessageResult.class);
+
+		McpSchema.TextContent expectedContent = new McpSchema.TextContent("Assistant response");
+		McpSchema.CreateMessageResult expected = McpSchema.CreateMessageResult.builder()
+			.role(McpSchema.Role.ASSISTANT)
+			.content(expectedContent)
+			.model("gpt-4")
+			.stopReason(McpSchema.CreateMessageResult.StopReason.UNKNOWN)
+			.build();
+		assertThat(value).isEqualTo(expected);
+	}
+
 	// Elicitation Tests
 
 	@Test