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 org.apache.juneau.commons.inject.*;
020
021/**
022 * Service-provider interface implemented once per MCP protocol revision.
023 *
024 * <p>
025 * A consumer binds exactly one revision at compile time, by extending that revision's abstract
026 * servlet or composing its endpoint mixin. There is deliberately no {@code ServiceLoader} wiring
027 * and no {@code priority()}/{@code isAvailable()} pair: unlike the transport-provider precedent in
028 * {@code juneau-rest-client-apache-httpclient-45}, there is never a set of runtime candidates to
029 * choose between.
030 *
031 * <p>
032 * <b>This interface has exactly three methods and must stay that way.</b> {@code default} methods
033 * here are reserved for genuinely additive future protocol growth — a hook a later revision needs
034 * that earlier revisions can no-op. They are <em>not</em> for utility plumbing: a revision-neutral
035 * helper belongs on whichever neutral type already owns the concept (an envelope bean,
036 * {@link McpCursor}, {@link McpParamUtils}), never here.
037 */
038public interface McpRevision {
039
040   /**
041    * The MCP protocol revision string this implementation speaks.
042    *
043    * @return The revision token (e.g. {@code "2025-06-18"}). Never <jk>null</jk>.
044    */
045   String protocolVersion();
046
047   /**
048    * Dispatches one JSON-RPC request.
049    *
050    * @param exchange The inbound envelope plus header access. Never <jk>null</jk>.
051    * @param config The neutral handler registry and pagination strategy. Never <jk>null</jk>.
052    * @param ctx The per-request bean store, passed through to handlers. Never <jk>null</jk>.
053    * @return A {@link McpResponseResult} for a normal request, a {@link McpStreamResult} (for example
054    *    wrapping a {@code Flow.Publisher} produced by a v2-only method) for a request whose response is
055    *    not a single JSON-RPC envelope, or <jk>null</jk> for a notification request (which the HTTP layer
056    *    renders as an empty body).
057    */
058   McpDispatchResult dispatch(McpExchange exchange, McpServerConfig config, BeanStore ctx);
059
060   /**
061    * Maps a neutral failure classification to this revision's JSON-RPC error code.
062    *
063    * @param kind The failure classification. Never <jk>null</jk>.
064    * @return The JSON-RPC error code this revision reports for that kind.
065    */
066   int errorCode(McpErrorKind kind);
067}