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.client.mcp;
018
019import org.apache.juneau.bean.jsonrpc.*;
020import org.apache.juneau.commons.inject.*;
021
022/**
023 * Callback invoked by {@link McpDuplexDispatcher} to handle a single server-initiated JSON-RPC request
024 * delivered over an MCP client's duplex event-stream channel (for example {@code sampling/createMessage};
025 * illustrative only, as sampling is deprecated per SEP-2577).
026 *
027 * @since 10.0.0
028 */
029@SuppressWarnings({
030   "java:S112" // This SPI callback intentionally declares 'throws Exception' so handler implementations can throw any exception type, which the dispatcher wraps.
031})
032@FunctionalInterface
033public interface McpServerRequestHandler {
034
035   /**
036    * Handles a single server-initiated request.
037    *
038    * @param request The inbound request, with its {@code params} left as the generic, revision-neutral wire
039    *    representation. Never <jk>null</jk>.
040    * @param ctx The request-scoped bean store. Never <jk>null</jk>.
041    * @return The result to return to the server, marshaled as the {@code result} of the JSON-RPC response
042    *    {@link McpDuplexDispatcher} posts back. Can be <jk>null</jk>.
043    * @throws Exception If handling fails. An {@link McpException} thrown here propagates to the caller as-is;
044    *    any other exception is wrapped by {@link McpDuplexDispatcher#dispatch(JsonRpcRequest, BeanStore)} as a
045    *    {@code -32603} internal-error {@link McpException}.
046    */
047   Object handle(JsonRpcRequest request, BeanStore ctx) throws Exception;
048}