refactor(mcp): simplify generated code via runtime invoker adapters

- Introduced `McpOperation` to cleanly encapsulate static routing metadata and runtime arguments.
- Refactored `McpInvoker` to act as a factory, providing strongly-typed adapters (`asToolHandler`, `asCompletionHandler`, etc.) for both stateful and stateless servers.
- Updated APT generator (`McpRouter`, `McpRoute`) to output clean method references instead of complex, boilerplate-heavy lambda chains.

Author: jknack

docs/asciidoc/modules/mcp.adoc

@@ -204,16 +204,21 @@ Invokers are chained. You can register multiple invokers and they will wrap the
 ----
 import io.jooby.mcp.McpInvoker;
 import io.jooby.mcp.McpOperation;
+import io.jooby.mcp.McpChain;
+import io.modelcontextprotocol.common.McpTransportContext;
+import io.modelcontextprotocol.server.McpSyncServerExchange;
+import org.jspecify.annotations.Nullable;
 import org.slf4j.MDC;
 
 public class MdcMcpInvoker implements McpInvoker {
   @Override
-  public <R> R invoke(McpOperation operation, SneakyThrows.Supplier<R> action) {
+  public <R> R invoke(@Nullable McpSyncServerExchange exchange, McpTransportContext transportContext, McpOperation operation, McpChain chain) throws Exception {
     try {
-      MDC.put("mcp.id", operation.id());                 <1>
+      MDC.put("mcp.id", operation.id());                            // <1>
       MDC.put("mcp.class", operation.className());
       MDC.put("mcp.method", operation.methodName());
-      return action.get();                               <2>
+      
+      return chain.proceed(exchange, transportContext, operation);  // <2>
     } finally {
       MDC.remove("mcp.id");
       MDC.remove("mcp.class");
@@ -224,13 +229,13 @@ public class MdcMcpInvoker implements McpInvoker {
 
 {
   install(new McpModule(new CalculatorServiceMcp_())
-      .invoker(new MdcMcpInvoker()));                    <3>
+      .invoker(new MdcMcpInvoker()));                               // <3>
 }
 ----
 
 <1> Extract rich contextual data from the `McpOperation` record.
-<2> Proceed with the execution chain.
-<3> Register the invoker. Jooby will safely map any business exceptions thrown by your action into valid MCP JSON-RPC errors.
+<2> Proceed to the next interceptor in the chain or execute the final target handler.
+<3> Register the invoker. Jooby will safely map any business exceptions thrown by your chain into valid MCP JSON-RPC errors.
 
 === Multiple Servers
 

modules/jooby-apt/src/main/java/io/jooby/apt/JoobyProcessor.java

@@ -24,7 +24,7 @@
 import javax.tools.*;
 
 import io.jooby.internal.apt.*;
-
+import io.jooby.internal.apt.mcp.McpRouter;
 import io.jooby.internal.apt.ws.WsRouter;
 
 /** Process jooby/jakarta annotation and generate source code from MVC controllers. */

…java/io/jooby/internal/apt/McpRoute.java …/io/jooby/internal/apt/mcp/McpRoute.javamodules/jooby-apt/src/main/java/io/jooby/internal/apt/McpRoute.java renamed to modules/jooby-apt/src/main/java/io/jooby/internal/apt/mcp/McpRoute.java modules/jooby-apt/src/main/java/io/jooby/internal/apt/McpRoute.java renamed to modules/jooby-apt/src/main/java/io/jooby/internal/apt/mcp/McpRoute.java

@@ -3,7 +3,7 @@
  * Apache License Version 2.0 https://jooby.io/LICENSE.txt
  * Copyright 2014 Edgar Espina
  */
-package io.jooby.internal.apt;
+package io.jooby.internal.apt.mcp;
 
 import static io.jooby.internal.apt.CodeBlock.*;
 import static io.jooby.internal.apt.CodeBlock.string;
@@ -15,6 +15,8 @@
 
 import javax.lang.model.element.ExecutableElement;
 
+import io.jooby.internal.apt.AnnotationSupport;
+import io.jooby.internal.apt.WebRoute;
 import io.jooby.javadoc.JavaDocNode;
 import io.jooby.javadoc.MethodDoc;
 

…ava/io/jooby/internal/apt/McpRouter.java …io/jooby/internal/apt/mcp/McpRouter.javamodules/jooby-apt/src/main/java/io/jooby/internal/apt/McpRouter.java renamed to modules/jooby-apt/src/main/java/io/jooby/internal/apt/mcp/McpRouter.java modules/jooby-apt/src/main/java/io/jooby/internal/apt/McpRouter.java renamed to modules/jooby-apt/src/main/java/io/jooby/internal/apt/mcp/McpRouter.java

@@ -3,7 +3,7 @@
  * Apache License Version 2.0 https://jooby.io/LICENSE.txt
  * Copyright 2014 Edgar Espina
  */
-package io.jooby.internal.apt;
+package io.jooby.internal.apt.mcp;
 
 import static io.jooby.internal.apt.AnnotationSupport.VALUE;
 import static io.jooby.internal.apt.CodeBlock.*;
@@ -23,6 +23,9 @@
 import javax.lang.model.element.ExecutableElement;
 import javax.lang.model.element.TypeElement;
 
+import io.jooby.internal.apt.AnnotationSupport;
+import io.jooby.internal.apt.MvcContext;
+import io.jooby.internal.apt.WebRouter;
 import io.jooby.javadoc.JavaDocParser;
 import io.jooby.javadoc.MethodDoc;
 
@@ -347,38 +350,31 @@ private void appendCompletions(
               ? "io.modelcontextprotocol.spec.McpSchema.ResourceReference"
               : "io.modelcontextprotocol.spec.McpSchema.PromptReference";
 
-      String lambda;
+      String invokerCall;
       if (groups.containsKey(ref)) {
         var targetMethod = findTargetMethodName(ref);
         var handlerName = targetMethod + "CompletionHandler";
-        var operationArg = generateOperationArg(kt, "completions/" + ref, targetMethod);
-
-        String invokeArgs =
-            isStateless ? "null, ctx, req" : "exchange, exchange.transportContext(), req";
-        String lambdaArgs = isStateless ? "ctx, req" : "exchange, req";
-
-        lambda =
-            kt
-                ? "{ "
-                    + lambdaArgs
-                    + " -> invoker.invoke("
-                    + operationArg
-                    + ") { this."
-                    + handlerName
-                    + "("
-                    + invokeArgs
-                    + ") } }"
-                : "("
-                    + lambdaArgs
-                    + ") -> invoker.invoke("
-                    + operationArg
-                    + ", () -> this."
-                    + handlerName
-                    + "("
-                    + invokeArgs
-                    + "))";
+        var targetClass = getTargetType().toString();
+
+        String adapterMethod = isStateless ? "asStatelessCompletionHandler" : "asCompletionHandler";
+        String handlerRef = "this::" + handlerName;
+        String operationId = "completions/" + ref; // <--- ADD THIS
+
+        // Update the string builder to include operationId:
+        invokerCall =
+            "invoker."
+                + adapterMethod
+                + "("
+                + string(operationId)
+                + ", "
+                + string(targetClass)
+                + ", "
+                + string(targetMethod)
+                + ", "
+                + handlerRef
+                + ")";
       } else {
-        lambda =
+        invokerCall =
             kt
                 ? "{ _, _ -> io.jooby.mcp.McpResult(this.json).toCompleteResult(emptyList<Any>()) }"
                 : "(exchange, req) -> new"
@@ -398,7 +394,7 @@ private void appendCompletions(
                 "(",
                 string(ref),
                 "), ",
-                lambda,
+                invokerCall,
                 "))"));
       } else {
         buffer.append(
@@ -411,7 +407,7 @@ private void appendCompletions(
                 "(",
                 string(ref),
                 "), ",
-                lambda,
+                invokerCall,
                 "))",
                 semicolon(kt)));
       }
@@ -482,32 +478,30 @@ private void appendInstall(
       var mcpType = getMcpRouteType(route);
       if (mcpType.isEmpty()) continue;
 
-      var operationArg = generateOperationArg(kt, mcpType + "/" + mcpName, methodName);
-
-      String invokeArgs =
-          isStateless ? "null, ctx, req" : "exchange, exchange.transportContext(), req";
-      String lambdaArgs = isStateless ? "ctx, req" : "exchange, req";
-
-      var lambda =
-          kt
-              ? "{ "
-                  + lambdaArgs
-                  + " -> invoker.invoke("
-                  + operationArg
-                  + ") { this."
-                  + methodName
-                  + "("
-                  + invokeArgs
-                  + ") } }"
-              : "("
-                  + lambdaArgs
-                  + ") -> invoker.invoke("
-                  + operationArg
-                  + ", () -> this."
-                  + methodName
-                  + "("
-                  + invokeArgs
-                  + "))";
+      String adapterMethod = "";
+      if (route.isMcpTool())
+        adapterMethod = isStateless ? "asStatelessToolHandler" : "asToolHandler";
+      else if (route.isMcpPrompt())
+        adapterMethod = isStateless ? "asStatelessPromptHandler" : "asPromptHandler";
+      else if (route.isMcpResource() || route.isMcpResourceTemplate())
+        adapterMethod = isStateless ? "asStatelessResourceHandler" : "asResourceHandler";
+
+      String handlerRef = "this::" + methodName;
+      String targetClass = getTargetType().toString();
+      String operationId = mcpType + "/" + mcpName;
+      String invokerCall =
+          of(
+              "invoker.",
+              adapterMethod,
+              "(",
+              string(operationId),
+              ",",
+              string(targetClass),
+              ", ",
+              string(methodName),
+              ", ",
+              handlerRef,
+              ")");
 
       String prefix = kt ? "" : "new ";
       String serverMethod = "io.modelcontextprotocol.server." + featuresClass + ".";
@@ -522,7 +516,7 @@ private void appendInstall(
                 "SyncToolSpecification(",
                 methodName,
                 "ToolSpec(schemaGenerator), ",
-                lambda,
+                invokerCall,
                 "))",
                 semicolon(kt)));
       } else if (route.isMcpPrompt()) {
@@ -535,7 +529,7 @@ private void appendInstall(
                 "SyncPromptSpecification(",
                 methodName,
                 "PromptSpec(), ",
-                lambda,
+                invokerCall,
                 "))",
                 semicolon(kt)));
       } else if (route.isMcpResource() || route.isMcpResourceTemplate()) {
@@ -556,7 +550,7 @@ private void appendInstall(
                 methodName,
                 defMethod,
                 ", ",
-                lambda,
+                invokerCall,
                 "))",
                 semicolon(kt)));
       }
@@ -581,7 +575,7 @@ private void appendCompletionHandlers(
                     + " io.modelcontextprotocol.spec.McpSchema.CompleteRequest):"
                     + " io.modelcontextprotocol.spec.McpSchema.CompleteResult {"));
         buffer.append(
-            statement(indent(6), "val ctx = transportContext.get(\"CTX\") as io.jooby.Context"));
+            statement(indent(6), "val ctx = transportContext.get(\"CTX\") as? io.jooby.Context"));
         buffer.append(statement(indent(6), "val c = this.factory.apply(ctx)"));
         buffer.append(statement(indent(6), "val targetArg = req.argument()?.name() ?: \"\""));
         buffer.append(statement(indent(6), "val typedValue = req.argument()?.value() ?: \"\""));
@@ -686,18 +680,6 @@ else if (type.equals("io.modelcontextprotocol.common.McpTransportContext"))
     }
   }
 
-  private String generateOperationArg(boolean kt, String operationId, String targetMethod) {
-    String prefix = kt ? "" : "new ";
-    return prefix
-        + "io.jooby.mcp.McpOperation("
-        + string(operationId)
-        + ", "
-        + string(getTargetType().toString())
-        + ", "
-        + string(targetMethod)
-        + ")";
-  }
-
   public Optional<MethodDoc> getMethodDoc(String methodName, List<String> types) {
     return javadoc.parse(getTargetType().toString()).flatMap(it -> it.getMethod(methodName, types));
   }