/*
 * Jooby https://jooby.io
 * Apache License Version 2.0 https://jooby.io/LICENSE.txt
 * Copyright 2014 Edgar Espina
 */
package io.jooby.mcp;

import java.util.List;

import io.jooby.Jooby;
import io.modelcontextprotocol.server.McpServerFeatures;
import io.modelcontextprotocol.server.McpStatelessServerFeatures;
import io.modelcontextprotocol.server.McpStatelessSyncServer;
import io.modelcontextprotocol.server.McpSyncServer;
import io.modelcontextprotocol.spec.McpSchema;

/**
 * High-performance dispatcher interface generated by the Jooby APT for MCP endpoints.
 *
 * <p>This interface serves as the primary bridge between the Model Context Protocol (MCP) SDK and
 * your user-defined Java/Kotlin methods. You generally do not implement this interface manually;
 * instead, the Jooby Annotation Processor (APT) generates implementations automatically (typically
 * suffixed with {@code Mcp_}) for any class containing {@code @McpTool}, {@code @McpPrompt}, or
 * {@code @McpResource} annotations.
 *
 * <p>These generated services are then passed to the {@link io.jooby.mcp.McpModule} to be wired
 * into the application lifecycle.
 *
 * @author edgar
 * @since 4.2.0
 */
public interface McpService {

  /**
   * Installs and registers the discovered tools, prompts, and resources into a stateful MCP server.
   *
   * @param application The current Jooby application instance.
   * @param server The stateful MCP server registry.
   * @throws Exception If an error occurs during route registration or schema generation.
   */
  void install(Jooby application, McpSyncServer server) throws Exception;

  /**
   * Installs and registers the discovered tools, prompts, and resources into a stateless MCP
   * server.
   *
   * @param application The current Jooby application instance.
   * @param server The stateless MCP server registry.
   * @throws Exception If an error occurs during route registration or schema generation.
   */
  void install(Jooby application, McpStatelessSyncServer server) throws Exception;

  /**
   * Populates the server capabilities builder with the features supported by this service. *
   *
   * <p>The generated implementation will dynamically enable the tools, prompts, or resources flags
   * depending on which annotations were present in the source class.
   *
   * @param capabilities The MCP server capabilities builder.
   */
  void capabilities(McpSchema.ServerCapabilities.Builder capabilities);

  /**
   * Generates the auto-completion specifications for arguments in a stateful server environment.
   *
   * @param application The current Jooby application instance used to resolve the {@link
   *     McpInvoker}.
   * @return A list of synchronous completion specifications for tools, prompts, or resources.
   */
  List<McpServerFeatures.SyncCompletionSpecification> completions(Jooby application);

  /**
   * Generates the auto-completion specifications for arguments in a stateless server environment.
   *
   * @param application The current Jooby application instance used to resolve the {@link
   *     McpInvoker}.
   * @return A list of synchronous completion specifications for tools, prompts, or resources.
   */
  List<McpStatelessServerFeatures.SyncCompletionSpecification> statelessCompletions(
      Jooby application);

  /**
   * Retrieves the server identifier this service is bound to. *
   *
   * <p>This correlates directly to the {@code @McpServer("name")} annotation. If no explicit server
   * name is provided, this defaults to {@code "default"}.
   *
   * @return The target server key.
   */
  String serverKey();

  McpService generateOutputSchema(boolean generateOutputSchema);
}
