- add javadoc to public classes

Author: jknack

modules/jooby-mcp/src/main/java/io/jooby/mcp/McpInvoker.java

@@ -7,18 +7,73 @@
 
 import io.jooby.SneakyThrows;
 
+/**
+ * Intercepts and wraps the execution of MCP (Model Context Protocol) operations, such as tools,
+ * prompts, resources, and completions.
+ *
+ * <p>The {@link McpInvoker} acts as a middleware or decorator around the generated MCP routing
+ * logic. It allows you to seamlessly inject cross-cutting concerns—such as telemetry, logging
+ * (SLF4J MDC), transaction management, or custom error handling—right before and after an operation
+ * executes.
+ *
+ * <h2>Chaining Invokers</h2>
+ *
+ * <p>Jooby provides a default internal invoker that gracefully maps standard framework exceptions
+ * to MCP JSON-RPC errors. When you register a custom invoker via {@link
+ * io.jooby.mcp.McpModule#invoker(McpInvoker)}, the framework automatically chains your custom
+ * invoker with the default one using the {@link #then(McpInvoker)} method.
+ *
+ * <h3>Example: MDC Context Propagation</h3>
+ *
+ * <pre>{@code
+ * public class MdcMcpInvoker implements McpInvoker {
+ * public <R> R invoke(String operationId, SneakyThrows.Supplier<R> action) {
+ * try {
+ * MDC.put("mcp.operation", operationId);
+ * // Execute the actual tool or proceed to the next invoker in the chain
+ * return action.get();
+ * } finally {
+ * MDC.remove("mcp.operation");
+ * }
+ * }
+ * }
+ * * // Register and automatically chain it:
+ * install(new McpModule(new MyServiceMcp_())
+ * .invoker(new MdcMcpInvoker()));
+ * }</pre>
+ *
+ * @author edgar
+ * @since 4.2.0
+ */
 public interface McpInvoker {
 
+  /**
+   * Executes the given MCP operation.
+   *
+   * @param operationId The identifier of the operation being executed. Typically formatted as
+   *     {@code [type]/[name]} (e.g., {@code "tools/add_numbers"}, {@code "prompts/greeting"}, or
+   *     {@code "resources/file://config"}).
+   * @param action The actual execution of the operation, or the next invoker in the chain. Must be
+   *     invoked via {@link SneakyThrows.Supplier#get()} to proceed.
+   * @param <R> The return type of the operation.
+   * @return The result of the operation.
+   */
   <R> R invoke(String operationId, SneakyThrows.Supplier<R> action);
 
   /**
    * Chains this invoker with another one. This invoker runs first, and its "action" becomes calling
    * the next invoker.
    *
+   * <p>This is used internally by {@link io.jooby.mcp.McpModule} to compose user-provided invokers
+   * with the default framework exception mappers.
+   *
    * @param next The next invoker in the chain.
    * @return A composed invoker.
    */
   default McpInvoker then(McpInvoker next) {
+    if (next == null) {
+      return this;
+    }
     return new McpInvoker() {
       @Override
       public <R> R invoke(String operationId, SneakyThrows.Supplier<R> action) {

modules/jooby-mcp/src/main/java/io/jooby/mcp/McpModule.java

@@ -34,85 +34,108 @@
 /**
  * MCP (Model Context Protocol) module for Jooby.
  *
- * <p>The MCP module provides integration with the Model Context Protocol server, enabling
- * standardized communication between clients and servers. It allows applications to:
+ * <p>The MCP module provides seamless integration with the Model Context Protocol, allowing your
+ * application to act as a standardized AI context server. It automatically bridges your Java/Kotlin
+ * methods with LLM clients by exposing them as Tools, Resources, and Prompts.
+ *
+ * <h2>Key Features</h2>
  *
  * <ul>
- *   <li>Expose server capabilities as tools, resources, and prompts
- *   <li>Handle client connections and sessions via SSE
- *   <li>Process protocol messages and events
- *   <li>Manage server capabilities and tool specifications
+ *   <li><b>Compile-Time Discovery:</b> Automatically generates routing logic for {@code @McpTool},
+ *       {@code @McpPrompt}, and {@code @McpResource} annotations with zero reflection overhead via
+ *       APT.
+ *   <li><b>Rich Schema Generation:</b> Tool and parameter descriptions are extracted directly from
+ *       your MCP annotations, gracefully falling back to standard JavaDoc comments if omitted.
+ *   <li><b>Transport Flexibility:</b> Supports {@link Transport#STREAMABLE_HTTP} (default), {@link
+ *       Transport#SSE}, {@link Transport#WEBSOCKET}, and {@link
+ *       Transport#STATELESS_STREAMABLE_HTTP}.
+ *   <li><b>Execution Interception:</b> Chain custom {@link McpInvoker} instances to seamlessly
+ *       inject MDC context, telemetry, or custom error handling around executions.
+ *   <li><b>LLM Self-Healing:</b> Automatically catches internal business exceptions and translates
+ *       them into valid MCP error payloads, allowing LLMs to auto-correct their own mistakes.
  * </ul>
  *
- * <h2>Usage</h2>
+ * <h2>Basic Usage</h2>
+ *
+ * <p>By default, the module requires zero configuration in {@code application.conf} and will spin
+ * up a single {@code streamable-http} server.
  *
- * <p>Add the module to your application:
+ * <p>The module relies on Jackson for JSON-RPC message serialization. Here is the standard setup
+ * using Jackson 3:
  *
  * <pre>{@code
  * {
- *   install(new JacksonModule());
- *   install(new McpModule(new DefaultMcpServer()));
+ *  // 1. Install Jackson 3 support
+ *  install(new Jackson3Module());
+ *  install(new McpJackson3Module());
+ *  // 2. Install the MCP module with your APT-generated McpService
+ *  install(new McpModule(new MyServiceMcp_()));
  * }
  * }</pre>
  *
- * <h2>Configuration</h2>
+ * <i>Note: If your project still uses Jackson 2, simply swap the modules to {@code install(new
+ * JacksonModule());} and {@code install(new McpJackson2Module());}.</i>
  *
- * <p>The module requires the following configuration in your application.conf:
+ * <h2>Changing the Default Transport</h2>
+ *
+ * <p>If you want to use a different transport protocol for the default server, you can configure it
+ * directly in the Java DSL:
  *
  * <pre>{@code
- * mcp.default {
- *     name: "my-awesome-mcp-server"     # Required
- *     version: "0.0.1"                  # Required
- *     sseEndpoint: "/mcp/sse"           # Optional (default: /mcp/sse)
- *     messageEndpoint: "/mcp/message"   # Optional (default: /mcp/message)
+ * {
+ * install(new McpModule(new MyServiceMcp_())
+ * .transport(Transport.SSE)); // Or Transport.WEBSOCKET, Transport.STATELESS_STREAMABLE_HTTP
  * }
  * }</pre>
  *
- * <h2>Features</h2>
+ * <h2>Custom Invokers & Telemetry</h2>
  *
- * <ul>
- *   <li>MCP server implementation with SSE transport
- *   <li>Tools Auto-discovery at build time
- *   <li>Server capabilities configuration
- *   <li>Configurable endpoints
- *   <li>Multiple servers support
- * </ul>
+ * <p>You can inject custom logic (like SLF4J MDC context propagation or Tracing spans) around every
+ * tool, prompt, or resource call by providing a custom {@link McpInvoker}:
+ *
+ * <pre>{@code
+ * {
+ * install(new McpModule(new MyServiceMcp_())
+ * .invoker(new MyCustomMdcInvoker())); // Chains automatically with the Default Exception Mapper
+ * }
+ * }</pre>
+ *
+ * <h2>Multiple Servers</h2>
  *
- * <h2>Multiple servers</h2>
+ * <p>The generated {@link McpService} instances do not represent servers themselves; they are
+ * mapped to specific server instances using the {@code @McpServer("serverKey")} annotation on your
+ * original class.
  *
- * <p>To run multiple MCP server instances in the same application, use a @McpServer("calculator")
- * annotation:
+ * <p>If you route services to multiple, isolated servers, you <b>must</b> define their specific
+ * configurations in your {@code application.conf}:
  *
  * <pre>{@code
  * {
- *
- *   install(new JacksonModule());
- *   install(new McpModule(new DefaultMcpServer(), new CalculatorMcpServer()));
+ * // Jooby will boot two separate MCP servers based on the @McpServer mapping of these services
+ * install(new McpModule(new DefaultServiceMcp_(), new CalculatorServiceMcp_()));
  * }
  * }</pre>
  *
- * <p>Each instance requires its own configuration block:
+ * <p>{@code application.conf}:
  *
  * <pre>{@code
- * mcp {
- *  default {
- *    name: "default-mcp-server"
- *    version: "1.0.0"
- *    sseEndpoint: "/mcp/sse"
- *    messageEndpoint: "/mcp/message"
- *  }
- *  calculator {
- *    name: "calculator-mcp-server"
- *    version: "1.0.0"
- *    sseEndpoint: "/mcp/calculator/sse"
- *    messageEndpoint: "/mcp/calculator/message"
- *  }
+ * mcp.calculator {
+ * name: "calculator-mcp-server"
+ * version: "1.0.0"
+ * transport: "web-socket"
+ * mcpEndpoint: "/mcp/calculator/ws"
  * }
- *
  * }</pre>
  *
+ * <h2>Testing and Debugging</h2>
+ *
+ * <p>For local development, Jooby provides a built-in UI to test your AI capabilities. Simply
+ * install the {@link McpInspectorModule} alongside this module to interactively execute your tools,
+ * prompts, and resources straight from your browser.
+ *
  * @author kliushnichenko
- * @since 1.0.0
+ * @author edgar
+ * @since 4.2.0
  */
 public class McpModule implements Extension {
 

modules/jooby-mcp/src/main/java/io/jooby/mcp/McpResult.java

@@ -17,14 +17,55 @@
 import io.modelcontextprotocol.spec.McpError;
 import io.modelcontextprotocol.spec.McpSchema;
 
+/**
+ * Result mapping utility for the Model Context Protocol (MCP) integration.
+ *
+ * <p>This class acts as the bridge between standard Java/Kotlin return types and the strict
+ * JSON-RPC payload structures required by the MCP specification. It is utilized heavily by the
+ * APT-generated routing classes ({@code *Mcp_}) to seamlessly translate user-defined method outputs
+ * into valid protocol responses.
+ *
+ * <h2>Conversion Strategies</h2>
+ *
+ * <ul>
+ *   <li><b>Pass-through:</b> If a method returns a native MCP schema object (e.g., {@link
+ *       McpSchema.CallToolResult}, {@link McpSchema.GetPromptResult}), it is returned as-is.
+ *   <li><b>Primitives & Strings:</b> Standard strings and primitives are automatically wrapped in
+ *       the appropriate textual content blocks (e.g., {@link McpSchema.TextContent}).
+ *   <li><b>POJOs & Collections:</b> Complex objects and lists are automatically serialized into
+ *       JSON strings using the configured {@link McpJsonMapper}, or passed as structured content
+ *       depending on the tool's schema capabilities.
+ *   <li><b>Prompts:</b> Raw strings or lists returned by a Prompt handler are automatically wrapped
+ *       in a {@link McpSchema.PromptMessage} assigned to the {@link McpSchema.Role#USER}.
+ * </ul>
+ *
+ * <p>By handling these conversions internally, developers can write natural, idiomatic Java/Kotlin
+ * methods without needing to couple their business logic to the MCP SDK classes.
+ *
+ * @author edgar
+ * @since 4.2.0
+ */
 public class McpResult {
 
   private final McpJsonMapper json;
 
+  /**
+   * Creates a new result mapper using the provided JSON mapper for object serialization.
+   *
+   * @param json The JSON mapper instance.
+   */
   public McpResult(McpJsonMapper json) {
     this.json = json;
   }
 
+  /**
+   * Converts a raw method return value into an MCP tool result.
+   *
+   * @param result The raw return value from the tool execution.
+   * @param structuredContent True if complex objects should be returned as structured data objects,
+   *     false to serialize them as JSON text.
+   * @return A valid {@link McpSchema.CallToolResult}.
+   */
   public McpSchema.CallToolResult toCallToolResult(Object result, boolean structuredContent) {
     try {
       if (result == null) {
@@ -50,6 +91,12 @@ public McpSchema.CallToolResult toCallToolResult(Object result, boolean structur
     }
   }
 
+  /**
+   * Converts a raw method return value into an MCP prompt result.
+   *
+   * @param result The raw return value from the prompt execution.
+   * @return A valid {@link McpSchema.GetPromptResult}.
+   */
   public McpSchema.GetPromptResult toPromptResult(Object result) {
     if (result == null) {
       return new McpSchema.GetPromptResult(null, List.of());
@@ -73,6 +120,13 @@ public McpSchema.GetPromptResult toPromptResult(Object result) {
     }
   }
 
+  /**
+   * Converts a raw method return value into an MCP resource result.
+   *
+   * @param uri The requested resource URI.
+   * @param result The raw return value from the resource execution.
+   * @return A valid {@link McpSchema.ReadResourceResult}.
+   */
   public McpSchema.ReadResourceResult toResourceResult(String uri, Object result) {
     try {
       if (result == null) {
@@ -91,6 +145,12 @@ public McpSchema.ReadResourceResult toResourceResult(String uri, Object result)
     }
   }
 
+  /**
+   * Converts a raw method return value into an MCP completion result.
+   *
+   * @param result The raw return value from the completion execution.
+   * @return A valid {@link McpSchema.CompleteResult}.
+   */
   public McpSchema.CompleteResult toCompleteResult(Object result) {
     try {
       Objects.requireNonNull(result, "Completion result cannot be null");