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 invocation of an {@link McpCompleter}.
023 *
024 * <p>
025 * Supersedes the wire-level {@code CompleteRequest} bean. Built by a dated adapter after it has
026 * validated the incoming {@code completion/complete} request and resolved the target
027 * {@link McpCompleter}; by the time an adapter constructs one of these, {@link #getValue()} is
028 * guaranteed non-<jk>null</jk>.
029 */
030public class McpCompletionRequest {
031
032   private McpCompletionRef ref;
033   private String argumentName;
034   private String value;
035   private Map<String,String> contextArguments = Map.of();
036
037   /**
038    * The completion target.
039    *
040    * @return The reference, or <jk>null</jk> if not set.
041    */
042   public McpCompletionRef getRef() {
043      return ref;
044   }
045
046   /**
047    * Sets the completion target.
048    *
049    * @param value The new value. Can be <jk>null</jk> to unset the property.
050    * @return This object.
051    */
052   public McpCompletionRequest setRef(McpCompletionRef value) {
053      ref = value;
054      return this;
055   }
056
057   /**
058    * The name of the prompt argument or template variable being completed.
059    *
060    * @return The argument name, or <jk>null</jk> if not set.
061    */
062   public String getArgumentName() {
063      return argumentName;
064   }
065
066   /**
067    * Sets the name of the prompt argument or template variable being completed.
068    *
069    * @param value The new value. Can be <jk>null</jk> to unset the property.
070    * @return This object.
071    */
072   public McpCompletionRequest setArgumentName(String value) {
073      argumentName = value;
074      return this;
075   }
076
077   /**
078    * The current (partial) value being completed.
079    *
080    * <p>
081    * Adapters must validate this as a non-<jk>null</jk> string before dispatching to a completer; this
082    * type does not itself enforce that constraint.
083    *
084    * @return The current value. Never <jk>null</jk> once an adapter has validated the request.
085    */
086   public String getValue() {
087      return value;
088   }
089
090   /**
091    * Sets the current (partial) value being completed.
092    *
093    * @param value The new value.
094    * @return This object.
095    */
096   public McpCompletionRequest setValue(String value) {
097      this.value = value;
098      return this;
099   }
100
101   /**
102    * Additional already-resolved argument values supplied by the client for context.
103    *
104    * @return An immutable, insertion-ordered map. Never <jk>null</jk>; empty when the request omitted
105    *    context.
106    */
107   public Map<String,String> getContextArguments() {
108      return contextArguments;
109   }
110
111   /**
112    * Sets the additional already-resolved argument values supplied by the client for context.
113    *
114    * <p>
115    * The supplied map is defensively copied into an immutable, insertion-ordered map. A <jk>null</jk>
116    * value normalizes to an immutable empty map, matching the contract for omitted context.
117    *
118    * @param value The new value. Can be <jk>null</jk>, which normalizes to an empty map.
119    * @return This object.
120    */
121   public McpCompletionRequest setContextArguments(Map<String,String> value) {
122      contextArguments = value == null ? Map.of() : Collections.unmodifiableMap(new LinkedHashMap<>(value));
123      return this;
124   }
125}