feat: Add taskHint and builder to schema

Signed-off-by: He-Pin <[email protected]>

Author: He-Pin

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

@@ -33,6 +33,7 @@
  * @author Luca Chang
  * @author Surbhi Bansal
  * @author Anurag Pant
+ * @author Pin He
  */
 public final class McpSchema {
 
@@ -111,6 +112,7 @@ private McpSchema() {
 	// ---------------------------
 	// JSON-RPC Error Codes
 	// ---------------------------
+
 	/**
 	 * Standard error codes used in MCP JSON-RPC responses.
 	 */
@@ -154,10 +156,10 @@ public static final class ErrorCodes {
 	public interface Meta {
 
 		/**
+		 * @return additional metadata related to this resource.
 		 * @see <a href=
 		 * "https://modelcontextprotocol.io/specification/2025-06-18/basic/index#meta">Specification</a>
 		 * for notes on _meta usage
-		 * @return additional metadata related to this resource.
 		 */
 		Map<String, Object> meta();
 
@@ -315,6 +317,7 @@ public record JSONRPCError( // @formatter:off
 	// ---------------------------
 	// Initialization
 	// ---------------------------
+
 	/**
 	 * This request is sent from the client to the server when it first connects, asking
 	 * it to begin initialization.
@@ -626,14 +629,15 @@ public Implementation(String name, String version) {
 	// Existing Enums and Base Types (from previous implementation)
 	public enum Role {
 
-	// @formatter:off
+		// @formatter:off
 		@JsonProperty("user") USER,
 		@JsonProperty("assistant") ASSISTANT
 	} // @formatter:on
 
 	// ---------------------------
 	// Resource Interfaces
 	// ---------------------------
+
 	/**
 	 * Base for objects that include optional annotations for the client. The client can
 	 * use annotations to inform how objects are used or displayed
@@ -706,7 +710,7 @@ public interface Identifier {
 		/**
 		 * Intended for UI and end-user contexts — optimized to be human-readable and
 		 * easily understood, even by those unfamiliar with domain-specific terminology.
-		 *
+		 * <p>
 		 * If not provided, the name should be used for display.
 		 */
 		String title();
@@ -858,8 +862,8 @@ public Resource build() {
 	 * @param mimeType The MIME type of this resource, if known.
 	 * @param annotations Optional annotations for the client. The client can use
 	 * annotations to inform how objects are used or displayed.
-	 * @see <a href="https://datatracker.ietf.org/doc/html/rfc6570">RFC 6570</a>
 	 * @param meta See specification for notes on _meta usage
+	 * @see <a href="https://datatracker.ietf.org/doc/html/rfc6570">RFC 6570</a>
 	 *
 	 */
 	@JsonInclude(JsonInclude.Include.NON_ABSENT)
@@ -1130,6 +1134,7 @@ public BlobResourceContents(String uri, String mimeType, String blob) {
 	// ---------------------------
 	// Prompt Interfaces
 	// ---------------------------
+
 	/**
 	 * A prompt or prompt template that the server offers.
 	 *
@@ -1180,7 +1185,7 @@ public PromptArgument(String name, String description, Boolean required) {
 
 	/**
 	 * Describes a message returned as part of a prompt.
-	 *
+	 * <p>
 	 * This is similar to `SamplingMessage`, but also supports the embedding of resources
 	 * from the MCP server.
 	 *
@@ -1207,7 +1212,7 @@ public record PromptMessage( // @formatter:off
 	public record ListPromptsResult( // @formatter:off
 		@JsonProperty("prompts") List<Prompt> prompts,
 		@JsonProperty("nextCursor") String nextCursor,
-		@JsonProperty("_meta") Map<String, Object> meta) implements Result  { // @formatter:on
+		@JsonProperty("_meta") Map<String, Object> meta) implements Result { // @formatter:on
 
 		public ListPromptsResult(List<Prompt> prompts, String nextCursor) {
 			this(prompts, nextCursor, null);
@@ -1255,6 +1260,7 @@ public GetPromptResult(String description, List<PromptMessage> messages) {
 	// ---------------------------
 	// Tool Interfaces
 	// ---------------------------
+
 	/**
 	 * The server's response to a tools/list request from the client.
 	 *
@@ -1297,12 +1303,51 @@ public record JsonSchema( // @formatter:off
 	}
 
 	/**
-	 * Additional properties describing a Tool to clients.
+	 * The task hint.
+	 * <p>
+	 * If taskHint is {@code always}, clients SHOULD invoke the tool as a task. Servers
+	 * MAY return a -32601 (Method not found) error if a client does not attempt to do so.
+	 * <p>
+	 * If taskHint is {@code optional}, clients MAY invoke the tool as a task or as a
+	 * normal request.
+	 * <p>
+	 * If taskHint is not present or {@code never}, clients MUST NOT attempt to invoke the
+	 * tool as a task. Servers SHOULD return a -32601 (Method not found) error if a client
+	 * attempts to do so. This is the default behavior.
 	 *
+	 */
+	public static enum TaskHint {
+
+		ALWAYS("always"), OPTIONAL("optional"), NEVER("never");
+
+		private final String value;
+
+		TaskHint(final String value) {
+			this.value = value;
+		}
+
+		public String getValue() {
+			return value;
+		}
+
+		public static TaskHint fromValue(String value) {
+			for (TaskHint hint : TaskHint.values()) {
+				if (hint.value.equalsIgnoreCase(value)) {
+					return hint;
+				}
+			}
+			throw new IllegalArgumentException("Unknown TaskHint value: " + value);
+		}
+
+	}
+
+	/**
+	 * Additional properties describing a Tool to clients.
+	 * <p>
 	 * NOTE: all properties in ToolAnnotations are **hints**. They are not guaranteed to
 	 * provide a faithful description of tool behavior (including descriptive properties
 	 * like `title`).
-	 *
+	 * <p>
 	 * Clients should never make tool use decisions based on ToolAnnotations received from
 	 * untrusted servers.
 	 */
@@ -1314,7 +1359,73 @@ public record ToolAnnotations( // @formatter:off
 		@JsonProperty("destructiveHint") Boolean destructiveHint,
 		@JsonProperty("idempotentHint") Boolean idempotentHint,
 		@JsonProperty("openWorldHint") Boolean openWorldHint,
-		@JsonProperty("returnDirect") Boolean returnDirect) { // @formatter:on
+		@JsonProperty("returnDirect") Boolean returnDirect,
+		@JsonProperty("taskHint") String taskHint) { // @formatter:on
+
+		public static Builder builder() {
+			return new Builder();
+		}
+
+		public static class Builder {
+
+			private String title;
+
+			private boolean readOnlyHint;
+
+			private boolean destructiveHint;
+
+			private boolean idempotentHint;
+
+			private boolean openWorldHint;
+
+			private boolean returnDirect;
+
+			private String taskHint;
+
+			public Builder title(String title) {
+				this.title = title;
+				return this;
+			}
+
+			public Builder readOnlyHint(boolean readOnlyHint) {
+				this.readOnlyHint = readOnlyHint;
+				return this;
+			}
+
+			public Builder destructiveHint(boolean destructiveHint) {
+				this.destructiveHint = destructiveHint;
+				return this;
+			}
+
+			public Builder idempotentHint(boolean idempotentHint) {
+				this.idempotentHint = idempotentHint;
+				return this;
+			}
+
+			public Builder openWorldHint(boolean openWorldHint) {
+				this.openWorldHint = openWorldHint;
+				return this;
+			}
+
+			public Builder returnDirect(boolean returnDirect) {
+				this.returnDirect = returnDirect;
+				return this;
+			}
+
+			/**
+			 * The task hint, {@link TaskHint}
+			 */
+			public Builder taskHint(String taskHint) {
+				this.taskHint = taskHint;
+				return this;
+			}
+
+			public ToolAnnotations build() {
+				return new ToolAnnotations(title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint,
+						returnDirect, taskHint);
+			}
+
+		}
 	}
 
 	/**
@@ -1686,6 +1797,7 @@ public CallToolResult build() {
 	// ---------------------------
 	// Sampling Interfaces
 	// ---------------------------
+
 	/**
 	 * The server's preferences for model selection, requested of the client during
 	 * sampling.
@@ -1837,7 +1949,7 @@ public CreateMessageRequest(List<SamplingMessage> messages, ModelPreferences mod
 
 		public enum ContextInclusionStrategy {
 
-		// @formatter:off
+			// @formatter:off
 			@JsonProperty("none") NONE,
 			@JsonProperty("thisServer") THIS_SERVER,
 			@JsonProperty("allServers")ALL_SERVERS
@@ -1951,7 +2063,7 @@ public record CreateMessageResult( // @formatter:off
 
 		public enum StopReason {
 
-		// @formatter:off
+			// @formatter:off
 			@JsonProperty("endTurn") END_TURN("endTurn"),
 			@JsonProperty("stopSequence") STOP_SEQUENCE("stopSequence"),
 			@JsonProperty("maxTokens") MAX_TOKENS("maxTokens"),
@@ -2032,6 +2144,7 @@ public CreateMessageResult build() {
 	}
 
 	// Elicitation
+
 	/**
 	 * A request from the server to elicit additional information from the user via the
 	 * client.
@@ -2114,7 +2227,7 @@ public record ElicitResult( // @formatter:off
 
 		public enum Action {
 
-		// @formatter:off
+			// @formatter:off
 			@JsonProperty("accept") ACCEPT,
 			@JsonProperty("decline") DECLINE,
 			@JsonProperty("cancel") CANCEL
@@ -2162,6 +2275,7 @@ public ElicitResult build() {
 	// ---------------------------
 	// Pagination Interfaces
 	// ---------------------------
+
 	/**
 	 * A request that supports pagination using cursors.
 	 *
@@ -2202,6 +2316,7 @@ public record PaginatedResult(@JsonProperty("nextCursor") String nextCursor) {
 	// ---------------------------
 	// Progress and Logging
 	// ---------------------------
+
 	/**
 	 * The Model Context Protocol (MCP) supports optional progress tracking for
 	 * long-running operations through notification messages. Either side can send
@@ -2313,7 +2428,7 @@ public LoggingMessageNotification build() {
 
 	public enum LoggingLevel {
 
-	// @formatter:off
+		// @formatter:off
 		@JsonProperty("debug") DEBUG(0),
 		@JsonProperty("info") INFO(1),
 		@JsonProperty("notice") NOTICE(2),
@@ -2371,7 +2486,7 @@ public sealed interface CompleteReference permits PromptReference, ResourceRefer
 	public record PromptReference( // @formatter:off
 		@JsonProperty("type") String type,
 		@JsonProperty("name") String name,
-		@JsonProperty("title") String title ) implements McpSchema.CompleteReference, Identifier { // @formatter:on
+		@JsonProperty("title") String title) implements McpSchema.CompleteReference, Identifier { // @formatter:on
 
 		public static final String TYPE = "ref/prompt";
 
@@ -2667,7 +2782,7 @@ public AudioContent(Annotations annotations, String data, String mimeType) {
 
 	/**
 	 * The contents of a resource, embedded into a prompt or tool call result.
-	 *
+	 * <p>
 	 * It is up to the client how best to render embedded resources for the benefit of the
 	 * LLM and/or the user.
 	 *
@@ -2821,6 +2936,7 @@ public ResourceLink build() {
 	// ---------------------------
 	// Roots
 	// ---------------------------
+
 	/**
 	 * Represents a root directory or file that the server can operate on.
 	 *

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

@@ -879,8 +879,10 @@ void testToolWithAnnotations() throws Exception {
 					"required": ["name"]
 				}
 				""";
-		McpSchema.ToolAnnotations annotations = new McpSchema.ToolAnnotations("A test tool", false, false, false, false,
-				false);
+		McpSchema.ToolAnnotations annotations = McpSchema.ToolAnnotations.builder()
+			.title("A test tool")
+			.taskHint(McpSchema.TaskHint.OPTIONAL.getValue())
+			.build();
 
 		McpSchema.Tool tool = McpSchema.Tool.builder()
 			.name("test-tool")
@@ -911,7 +913,8 @@ void testToolWithAnnotations() throws Exception {
 							"destructiveHint":false,
 							"idempotentHint":false,
 							"openWorldHint":false,
-							"returnDirect":false
+							"returnDirect":false,
+							"taskHint":"optional"
 						}
 					}
 					"""));
@@ -1014,8 +1017,13 @@ void testToolWithOutputSchemaAndAnnotations() throws Exception {
 				}
 				""";
 
-		McpSchema.ToolAnnotations annotations = new McpSchema.ToolAnnotations("A test tool with output", true, false,
-				true, false, true);
+		McpSchema.ToolAnnotations annotations = McpSchema.ToolAnnotations.builder()
+			.title("A test tool with output")
+			.readOnlyHint(true)
+			.idempotentHint(true)
+			.returnDirect(true)
+			.taskHint(McpSchema.TaskHint.OPTIONAL.getValue())
+			.build();
 
 		McpSchema.Tool tool = McpSchema.Tool.builder()
 			.name("test-tool")
@@ -1053,7 +1061,8 @@ void testToolWithOutputSchemaAndAnnotations() throws Exception {
 							"destructiveHint":false,
 							"idempotentHint":true,
 							"openWorldHint":false,
-							"returnDirect":true
+							"returnDirect":true,
+							"taskHint":"optional"
 						}
 					}"""));
 	}