001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.server.mcp;
018
019import java.util.*;
020
021/**
022 * Revision-neutral result of a {@code tools/call} invocation.
023 *
024 * <p>
025 * Supersedes the wire-level {@code CallToolResult} bean. {@code structuredContent} is cross-revision.
026 * Deliberately absent: {@code cachePolicy}, which remains specific to later MCP revisions.
027 *
028 * <p>
029 * Note the field is named {@code error}, while the {@code 2025-06-18} wire property is
030 * {@code isError}; the rename happens at the adapter boundary and is intentional. Do not
031 * "fix" this field name to match the wire.
032 */
033public class McpToolOutcome {
034
035   private List<McpContentBlock> content;
036   private Boolean error;
037   private Object structuredContent;
038
039   /**
040    * Creates an outcome carrying a single text block.
041    *
042    * @param value The text. Can be <jk>null</jk>.
043    * @return A new outcome. Never <jk>null</jk>.
044    */
045   public static McpToolOutcome text(String value) {
046      return new McpToolOutcome().setContent(List.of(McpContentBlock.text(value)));
047   }
048
049   /**
050    * Creates an outcome carrying the supplied blocks.
051    *
052    * @param values The content blocks. Must not be <jk>null</jk>.
053    * @return A new outcome. Never <jk>null</jk>.
054    */
055   public static McpToolOutcome of(McpContentBlock... values) {
056      return new McpToolOutcome().setContent(List.of(values));
057   }
058
059   /**
060    * The content blocks returned by the tool.
061    *
062    * @return The blocks, or <jk>null</jk> if not set. A <jk>null</jk> value is distinct from an empty
063    *    list: it means the wire property is omitted entirely.
064    */
065   public List<McpContentBlock> getContent() {
066      return content;
067   }
068
069   /**
070    * Sets the content blocks.
071    *
072    * @param value The new value. Can be <jk>null</jk> to unset the property.
073    * @return This object.
074    */
075   public McpToolOutcome setContent(List<McpContentBlock> value) {
076      content = value;
077      return this;
078   }
079
080   /**
081    * Whether the tool call represents an error result.
082    *
083    * @return The flag, or <jk>null</jk> if not set.
084    */
085   public Boolean getError() {
086      return error;
087   }
088
089   /**
090    * Sets the error flag.
091    *
092    * @param value The new value. Can be <jk>null</jk> to unset the property.
093    * @return This object.
094    */
095   public McpToolOutcome setError(Boolean value) {
096      error = value;
097      return this;
098   }
099
100   /**
101    * The structured JSON result returned by the tool.
102    *
103    * @return The JSON value, or <jk>null</jk> if absent.
104    */
105   public Object getStructuredContent() {
106      return structuredContent;
107   }
108
109   /**
110    * Sets the structured JSON result.
111    *
112    * @param value Any JSON-compatible value. Can be <jk>null</jk>.
113    * @return This object.
114    */
115   public McpToolOutcome setStructuredContent(Object value) {
116      structuredContent = value;
117      return this;
118   }
119}