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.bean.mcp.v20260728;
018
019import static org.apache.juneau.commons.utils.CollectionUtils.*;
020import static org.apache.juneau.commons.utils.Shorts.*;
021
022import java.util.*;
023
024import org.apache.juneau.marshall.*;
025
026/**
027 * Result payload for {@value McpMethods#TOOLS_CALL}.
028 */
029@Marshalled
030public class CallToolResult extends Result<CallToolResult> {
031
032   private List<Content> content;
033   private Boolean isError;
034   private Object structuredContent;
035
036   /**
037    * Content blocks returned by the tool.
038    *
039    * @return The content list, or {@code null} if not set.
040    */
041   public List<Content> getContent() {
042      return u(content);
043   }
044
045   /**
046    * Sets the content blocks.
047    *
048    * @param value The new value.  Can be <jk>null</jk> to unset the property.
049    * @return This object (for method chaining).
050    */
051   public CallToolResult setContent(List<Content> value) {
052      content = value;
053      return this;
054   }
055
056   /**
057    * Sets the content blocks.
058    *
059    * @param value The new value.  Can be <jk>null</jk> to unset the property.
060    * @return This object (for method chaining).
061    */
062   public CallToolResult setContent(Content...value) {
063      content = list(value);
064      return this;
065   }
066
067   /**
068    * Appends to the content blocks.
069    *
070    * @param value The values to append.
071    * @return This object (for method chaining).
072    */
073   public CallToolResult addContent(Content...value) {
074      if (content == null)
075         content = list();
076      Collections.addAll(content, value);
077      return this;
078   }
079
080   /**
081    * Appends to the content blocks.
082    *
083    * @param value The values to append.
084    * @return This object (for method chaining).
085    */
086   public CallToolResult addContent(Collection<Content> value) {
087      if (content == null)
088         content = list();
089      content.addAll(value);
090      return this;
091   }
092
093   /**
094    * Returns the text of the first {@link TextContent} block anywhere in the content list.
095    *
096    * <p>
097    * Convenience for the common case of a tool that returns text (possibly alongside other blocks, e.g. an
098    * image with a caption): scans past any leading non-text blocks instead of only ever looking at index 0,
099    * and avoids the {@code ((TextContent)result.getContent().get(i)).getText()} cast every such caller would
100    * otherwise repeat.
101    *
102    * @return The first {@link TextContent} block's text found while scanning the content list in order, or
103    *    {@code null} if the content list is empty or unset, or it contains no {@link TextContent} block.
104    */
105   public String firstText() {
106      var c = getContent();
107      if (c == null)
108         return null;
109      for (var b : c)
110         if (b instanceof TextContent t)
111            return t.getText();
112      return null;
113   }
114
115   /**
116    * When {@code true}, the tool reported an application-level error.
117    *
118    * @return The flag, or {@code null} if not set.
119    */
120   public Boolean getIsError() {
121      return isError;
122   }
123
124   /**
125    * Sets the error flag.
126    *
127    * @param value The new value.  Can be <jk>null</jk> to unset the property.
128    * @return This object (for method chaining).
129    */
130   public CallToolResult setIsError(Boolean value) {
131      isError = value;
132      return this;
133   }
134
135   /**
136    * Structured tool output, validated against the tool's {@code outputSchema} when present.
137    *
138    * <p>
139    * May be any JSON-compatible value (object, array, string, number, boolean, or {@code null}).
140    *
141    * @return The structured content, or {@code null} if not set.
142    */
143   public Object getStructuredContent() {
144      return structuredContent;
145   }
146
147   /**
148    * Sets the structured tool output.
149    *
150    * @param value Any JSON-compatible value.  Can be <jk>null</jk>.
151    * @return This object (for method chaining).
152    */
153   public CallToolResult setStructuredContent(Object value) {
154      structuredContent = value;
155      return this;
156   }
157}