package io.modelcontextprotocol.spec;

/** Wraps the OAuth 2.1 access token used in Authorization headers. */
public record TokenInfo(String accessToken) { }

/**
* Negotiated protocol version and server capabilities returned by the server.
*
* @param protocolVersion the agreed MCP protocol version
* @param capabilitiesJson server capabilities serialized as JSON (or any text format)
*/
public record ServerMetadata(String protocolVersion, String capabilitiesJson) { }

package io.modelcontextprotocol.spec;

import java.util.Optional;

/**
 * Persists MCP client state so a Streamable-HTTP client can resume seamlessly
 * after a JVM restart. Implementations MUST be thread-safe.
 *
 * <p>Host applications remain in full control of where & how the data is stored.
 *
 * <p>Example usage:
 *
 * <pre>{@code
 * StreamableHttpClientStateStore myStateStore = new MyJdbcBackedStateStore("my-client-key");
 * var transport = HttpClientStreamableHttpTransport.builder("https://example.com/mcp")
 *         .clientStateStore(myStateStore)
 *         .build();
 *
 * McpSyncClient client = McpClient.sync(transport).build();
 * }</pre>
 */
public interface StreamableHttpClientStateStore {

    /* ------- Session ------- */

    /**
     * Called by the MCP client when a remote MCP server returns an MCP-Session-Id
     * per the Streamable HTTP specification after an initialize request.
     *
     * @param the session ID returned by the server.
     */
    void setSessionId(String sessionId);

    /**
     * Called by the MCP client before sending any requests to the server.
     * If a value is present, it will be included in the Mcp-Session-Id header.
     *
     * @return an Optional containing the stored session ID if one was previously stored.
     */
    Optional<String> getSessionId();

    /**
     * Called by the MCP client when the server indicates that the session has expired or is invalid,
     * to clear the stored session ID.
     */
    void clearSessionId();

    /* ------- Access Token ------- */

    /**
     * Called by the MCP client after obtaining a new OAuth 2.1 access token from the authorization server.
     *
     * @param token the TokenInfo containing the new access token.
     */
    void setAccessToken(TokenInfo token);

    /**
     * Called by the MCP client before sending any authorized requests to the server.
     * If a value is present, it will be included in the Authorization header as a Bearer token.
     *
     * @return an Optional containing the stored access token if one was previously stored.
     */
    Optional<TokenInfo> getAccessToken();

    /**
     * Called by the MCP client when the access token is revoked, expires, or is no longer valid,
     * to clear the stored token.
     */
    void clearAccessToken();

    /* ------- Server Metadata ------- */

    /**
     * Called by the MCP client after initialization to store the negotiated
     * protocol version and server capabilities for future reuse.
     *
     * @param metadata the ServerMetadata containing protocol version and capabilitiesJson.
     */
    void setServerMetadata(ServerMetadata metadata);

    /**
     * Called by the MCP client before initialization to retrieve any previously stored
     * protocol version and server capabilities.
     *
     * @return an Optional containing the stored ServerMetadata if one was previously stored.
     */
    Optional<ServerMetadata> getServerMetadata();

    /**
     * Called by the MCP client to clear any stored server metadata,
     * for example if the protocol version becomes incompatible.
     */
    void clearServerMetadata();
}

var transport = HttpClientStreamableHttpTransport.builder("https://example.com/mcp")
    .clientStateStore(new FileBasedStateStore("./mcp-state.json"))
    .build();