001/*
002 * Copyright 2022-2026 Revetware LLC.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016
017package com.soklet.annotation;
018
019import com.soklet.McpAppToolMetadata;
020import com.soklet.McpProtocolVersion;
021import org.jspecify.annotations.NonNull;
022
023import java.lang.annotation.ElementType;
024import java.lang.annotation.Retention;
025import java.lang.annotation.RetentionPolicy;
026import java.lang.annotation.Target;
027
028/**
029 * Attaches MCP Apps metadata to an {@link McpTool} handler method.
030 *
031 * <p>The annotation processor requires {@code @McpTool} on the same method
032 * and generates the equivalent {@link McpAppToolMetadata} registration.
033 * Visibility and resource association do not grant authorization or prove
034 * that an invocation originated from an authorized UI. Applications must
035 * authorize every invocation.
036 *
037 * @author <a href="https://www.revetkn.com">Mark Allen</a>
038 */
039@Target(ElementType.METHOD)
040@Retention(RetentionPolicy.RUNTIME)
041public @interface McpAppTool {
042        /**
043         * Exact revisions on which this tool advertises its Apps association.
044         * This must be a nonempty subset of the owning tool's revisions.
045         *
046         * @return Apps association revisions
047         */
048        @NonNull
049        McpProtocolVersion @NonNull [] protocolVersions();
050
051        /**
052         * Associates an exact UI resource registered in the same endpoint.
053         * The processor applies the same URI validation as programmatic Apps
054         * metadata; endpoint construction validates the resource's eligibility.
055         *
056         * @return concrete normalized absolute ASCII {@code ui://} URI, or an
057         * empty string for no association
058         */
059        @NonNull
060        String resourceUri() default "";
061
062        /**
063         * The tool's effective audiences, defaulting to both model and app.
064         * Explicitly supplying an empty array means neither audience; duplicate
065         * values are collapsed into the generated metadata's set.
066         *
067         * @return non-null audiences, stored in enum declaration order
068         */
069        McpAppToolMetadata.@NonNull Visibility @NonNull [] visibility() default {
070                        McpAppToolMetadata.Visibility.MODEL, McpAppToolMetadata.Visibility.APP};
071}