McpClient and ToolProvider support added (helidon-io#10533)

Verdent · web-flow · commit 72ee6f02b8bb · 2025-08-21T08:53:16.000+02:00
McpClient and ToolProvider support added

Signed-off-by: David Kral &lt;david.k.kral@oracle.com&gt;
diff --git a/docs/src/main/asciidoc/se/integrations/langchain4j/langchain4j.adoc b/docs/src/main/asciidoc/se/integrations/langchain4j/langchain4j.adoc
@@ -240,6 +240,8 @@ Helidon's LangChain4J integration introduces a declarative Helidon Inject-based
     ** *Retrieval Augmentor*: `dev.langchain4j.rag.RetrievalAugmentor`
 * *Callback Functions*:
     ** Methods annotated with `dev.langchain4j.agent.tool.Tool`
+* *MCP Client*:
+    ** `dev.langchain4j.mcp.client.McpClient`
 
 === Creating AI Service
 
@@ -270,6 +272,8 @@ In this scenario all LangChain4J components from the list above are taken from t
 | `Ai.ModerationModel`     | Specifies the name of a service in the service registry that implements `ModerationModel` to use in the annotated Ai Service.
 | `Ai.ContentRetriever`    | Specifies the name of a service in the service registry that implements `ContentRetriever` to use in the annotated Ai Service. Mutually exclusive with `Ai.RetrievalAugmentor`.
 | `Ai.RetrievalAugmentor`  | Specifies the name of a service in the service registry that implements `RetrievalAugmentor` to use in the annotated Ai Service. Mutually exclusive with `Ai.ContentRetriever`.
+| `Ai.ToolProvider`        | Specifies the name of a service in the service registry that implements `ToolProvider` to use in the annotated Ai Service. Mutually exclusive with `Ai.McpClients`.
+| `Ai.McpClients`          | Specifies the name/s of a `McpClient` in the service registry that implements `ToolProvider` to use in the annotated Ai Service. `McpToolProvider` is created from these clients. Mutually exclusive with `Ai.ToolProvider`.
 |===
 
 For example, in the snippet below a service with name "myCustomChatMemory" will be used as chat memory and all other components are discovered automatically.
@@ -285,6 +289,12 @@ public interface ChatAiService {
 
 NOTE: There is a possibility to switch off automatic discovery by using `@Ai.Service(autodicovery=false)`. In this case the service components are not discovered automatically and users must add components manually using annotations specified above. `@ChatModel` or `@StreamingChatModel` annotations are required.
 
+Since `Ai.ToolProvider` and `Ai.McpClients` are mutually exclusive, some clarification is needed regarding their functionality. Assume that automatic discovery is set to true in this context:
+
+* If neither annotation is present, a `ToolProvider` will be automatically discovered from the service registry.
+* If the `Ai.McpClients` annotation is present, corresponding MCP client services will be discovered, and no `ToolProvider` will be discovered.
+* If both annotations are present, an exception will be thrown.
+
 === Tools (Callback Functions)
 
 In LangChain4J, tools are callback functions that the language model can invoke during a conversation to perform specific tasks, retrieve information, or execute external logic. These tools extend the model's capabilities beyond simple text generation, allowing it to dynamically interact with external systems. For instance, a tool might query a database, call an external API, or perform calculations. Based on user input, the model can decide to call a tool, interpret its response, and incorporate it into the conversation for a more context-aware and multi-step interaction.
@@ -307,6 +317,24 @@ NOTE: If you are using Helidon MP, to enable `@Tool`-annotated methods in CDI be
 
 For more details, read the https://docs.langchain4j.dev/tutorials/tools#high-level-tool-api[LangChain4J Documentation on Tools].
 
+=== MCP Client
+In LangChain4J, an MCP (Model Context Protocol) client acts as a bridge between the language model and external services or resources that follow the MCP standard. Instead of directly embedding custom logic into the application, the MCP client enables the model to discover, connect to, and interact with external tools and data providers in a standardized way.
+
+To add MCP Clients to your AI Service, use the following:
+[source,java]
+----
+@Ai.Service
+@Ai.McpClients
+public interface ChatAiService {
+    String chat(String question);
+}
+----
+
+If you want to have your MCP clients created from the configuration, it should be placed under the `langchain4j.mcp-clients`.
+These are all the MCP Client configuration options currently supported:
+
+include::{rootdir}/config/io_helidon_integrations_langchain4j_McpClientConfig.adoc[leveloffset=+2,tag=config]
+
 == Additional Information
 
 * https://docs.langchain4j.dev/[LangChain4J documentation]
diff --git a/integrations/langchain4j/codegen/src/main/java/io/helidon/integrations/langchain4j/codegen/AiServiceCodegen.java b/integrations/langchain4j/codegen/src/main/java/io/helidon/integrations/langchain4j/codegen/AiServiceCodegen.java
@@ -42,21 +42,26 @@
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.AI_CHAT_MEMORY_WINDOW;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.AI_CHAT_MODEL;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.AI_CONTENT_RETRIEVER;
+import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.AI_MCP_CLIENTS;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.AI_MODERATION_MODEL;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.AI_RETRIEVER_AUGMENTOR;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.AI_SERVICE;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.AI_STREAMING_CHAT_MODEL;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.AI_TOOLS;
+import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.AI_TOOL_PROVIDER;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_AI_SERVICES;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_CHAT_MEMORY;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_CHAT_MEMORY_PROVIDER;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_CHAT_MEMORY_STORE;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_CHAT_MEMORY_WINDOW;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_CHAT_MODEL;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_CONTENT_RETRIEVER;
+import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_MCP_CLIENT;
+import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_MCP_TOOL_PROVIDER;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_MODERATION_MODEL;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_RETRIEVAL_AUGMENTOR;
 import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_STREAMING_CHAT_MODEL;
+import static io.helidon.integrations.langchain4j.codegen.LangchainTypes.LC_TOOL_PROVIDER;
 import static io.helidon.service.codegen.ServiceCodegenTypes.SERVICE_ANNOTATION_NAMED;
 import static io.helidon.service.codegen.ServiceCodegenTypes.SERVICE_ANNOTATION_SINGLETON;
 
@@ -162,6 +167,46 @@ private void aiServicesParameter(Constructor.Builder ctr,
                 .addContentLine(");");
     }
 
+    private void aiMcpClientParameter(Constructor.Builder builder, TypeInfo aiInterface, CodegenContext ctx) {
+        Optional<TypeInfo> mcpClientTypeInfo = ctx.typeInfo(LC_MCP_CLIENT);
+        if (mcpClientTypeInfo.isEmpty()) {
+            //McpClients annotation present. Dependency needs to be added.
+            throw new CodegenException("McpClients annotation is being used, "
+                                               + "but the required LC4J MCP dependency is missing. "
+                                               + "Please add: dev.langchain4j:langchain4j-mcp");
+        }
+        List<String> mcpClients = aiInterface.findAnnotation(AI_MCP_CLIENTS)
+                .flatMap(Annotation::stringValues)
+                .orElseGet(List::of);
+        List<String> mcpClientParameters = new ArrayList<>();
+        if (mcpClients.isEmpty()) {
+            builder.addParameter(tools -> tools
+                    .name("mcpClients")
+                    .type(listType(LC_MCP_CLIENT)));
+            mcpClientParameters.add("mcpClients");
+        } else {
+            int index = 1;
+            for (String clientName : mcpClients) {
+                String toolParameter = "mcpClient_" + index++;
+                builder.addParameter(param -> param
+                        .name(toolParameter)
+                        .type(LC_MCP_CLIENT)
+                        .addAnnotation(namedAnnotation(clientName)));
+                mcpClientParameters.add(toolParameter);
+            }
+        }
+        builder.addContent("var mcpToolProvider = ")
+                .addContent(LC_MCP_TOOL_PROVIDER)
+                .addContentLine(".builder()")
+                .increaseContentPadding()
+                .addContent(".mcpClients(")
+                .addContent(String.join(", ", mcpClientParameters))
+                .addContentLine(")")
+                .addContentLine(".build();")
+                .decreaseContentPadding();
+        builder.addContentLine("builder.toolProvider(mcpToolProvider);");
+    }
+
     private Annotation namedAnnotation(String modelName) {
         return Annotation.create(SERVICE_ANNOTATION_NAMED, modelName);
     }
@@ -243,6 +288,7 @@ private void generateInterfaceSupplier(RoundContext roundCtx, TypeInfo aiInterfa
                                         AI_CONTENT_RETRIEVER,
                                         LC_CONTENT_RETRIEVER,
                                         "contentRetriever");
+                    aiMcpClientAndToolProvider(it, aiInterface, autoDiscovery, ctx);
                     aiServicesToolParameters(it,
                                              aiInterface);
                 })
@@ -262,6 +308,25 @@ private void generateInterfaceSupplier(RoundContext roundCtx, TypeInfo aiInterfa
         roundCtx.addGeneratedType(generatedType, classModel, aiInterfaceType, aiInterface.originatingElementValue());
     }
 
+    private void aiMcpClientAndToolProvider(Constructor.Builder it,
+                                            TypeInfo aiInterface,
+                                            boolean autoDiscovery,
+                                            CodegenContext ctx) {
+        if (aiInterface.hasAnnotation(AI_TOOL_PROVIDER) && aiInterface.hasAnnotation(AI_MCP_CLIENTS)) {
+            throw new CodegenException("McpClients and ToolProvider annotations cannot be used at the same time.",
+                                       aiInterface.originatingElementValue());
+        } else if (aiInterface.hasAnnotation(AI_MCP_CLIENTS)) {
+            aiMcpClientParameter(it, aiInterface, ctx);
+        } else {
+            aiServicesParameter(it,
+                                autoDiscovery,
+                                aiInterface,
+                                AI_TOOL_PROVIDER,
+                                LC_TOOL_PROVIDER,
+                                "toolProvider");
+        }
+    }
+
     private void aiServicesChatMemoryConstructor(Constructor.Builder ctr, boolean autoDiscovery, TypeInfo aiInterface) {
         Optional<Annotation> chatMemoryWindow = aiInterface.findAnnotation(AI_CHAT_MEMORY_WINDOW);
 
diff --git a/integrations/langchain4j/codegen/src/main/java/io/helidon/integrations/langchain4j/codegen/LangchainTypes.java b/integrations/langchain4j/codegen/src/main/java/io/helidon/integrations/langchain4j/codegen/LangchainTypes.java
@@ -29,6 +29,8 @@ final class LangchainTypes {
     static final TypeName AI_MODERATION_MODEL = TypeName.create("io.helidon.integrations.langchain4j.Ai.ModerationModel");
     static final TypeName AI_CONTENT_RETRIEVER = TypeName.create("io.helidon.integrations.langchain4j.Ai.ContentRetriever");
     static final TypeName AI_RETRIEVER_AUGMENTOR = TypeName.create("io.helidon.integrations.langchain4j.Ai.RetrievalAugmentor");
+    static final TypeName AI_TOOL_PROVIDER = TypeName.create("io.helidon.integrations.langchain4j.Ai.ToolProvider");
+    static final TypeName AI_MCP_CLIENTS = TypeName.create("io.helidon.integrations.langchain4j.Ai.McpClients");
     static final TypeName AI_TOOLS = TypeName.create("io.helidon.integrations.langchain4j.Ai.Tools");
     static final TypeName AI_TOOL = TypeName.create("io.helidon.integrations.langchain4j.Ai.Tool");
     static final Annotation TOOL_QUALIFIER_ANNOTATION = Annotation.create(AI_TOOL);
@@ -58,6 +60,9 @@ final class LangchainTypes {
     static final TypeName LC_HTTP_CLIENT_BUILDER = TypeName.create("dev.langchain4j.http.client.HttpClientBuilder");
     static final TypeName LC_CHAT_MODEL_LISTENER = TypeName.create("dev.langchain4j.model.chat.listener.ChatModelListener");
     static final TypeName LC_DEF_REQUEST_PARAMS = TypeName.create("dev.langchain4j.model.chat.request.ChatRequestParameters");
+    static final TypeName LC_TOOL_PROVIDER = TypeName.create("dev.langchain4j.service.tool.ToolProvider");
+    static final TypeName LC_MCP_TOOL_PROVIDER = TypeName.create("dev.langchain4j.mcp.McpToolProvider");
+    static final TypeName LC_MCP_CLIENT = TypeName.create("dev.langchain4j.mcp.client.McpClient");
 
     static final TypeName SVC_QUALIFIED_INSTANCE = TypeName.create("io.helidon.service.registry.Service.QualifiedInstance");
     static final TypeName SVC_SERVICES_FACTORY = TypeName.create("io.helidon.service.registry.Service.ServicesFactory");
diff --git a/integrations/langchain4j/langchain4j/pom.xml b/integrations/langchain4j/langchain4j/pom.xml
@@ -63,6 +63,10 @@
             <groupId>dev.langchain4j</groupId>
             <artifactId>langchain4j</artifactId>
         </dependency>
+        <dependency>
+            <groupId>dev.langchain4j</groupId>
+            <artifactId>langchain4j-mcp</artifactId>
+        </dependency>
         <dependency>
             <groupId>io.helidon.common.features</groupId>
             <artifactId>helidon-common-features-api</artifactId>
diff --git a/integrations/langchain4j/langchain4j/src/main/java/io/helidon/integrations/langchain4j/Ai.java b/integrations/langchain4j/langchain4j/src/main/java/io/helidon/integrations/langchain4j/Ai.java
@@ -231,6 +231,38 @@ private Ai() {
         String value();
     }
 
+    /**
+     * Annotation to specify a ToolProvider for the service.
+     * This is mutually exclusive with the {@link McpClients}.
+     */
+    @Target(TYPE)
+    @Retention(RUNTIME)
+    public @interface ToolProvider {
+        /**
+         * Name of the Tool provider to be used.
+         *
+         * @return name of the Tool provider
+         */
+        String value();
+    }
+
+    /**
+     * Annotation to specify an MCP Clients to be used in McpToolProvider.
+     * This is mutually exclusive with the {@link ToolProvider}.
+     * It requires to have {@code dev.langchain4j:langchain4j-mcp} dependency added on the classpath for it to work properly.
+     */
+    @Target(TYPE)
+    @Retention(RUNTIME)
+    public @interface McpClients {
+        /**
+         * Names of the MCP Clients to be used in McpToolProvider creation.
+         * These names are mapped from the {@code key} values of the MCP Client.
+         *
+         * @return client names
+         */
+        String[] value() default {};
+    }
+
     /**
      * Annotation to manually specify classes containing tools for the service.
      */
diff --git a/integrations/langchain4j/langchain4j/src/main/java/io/helidon/integrations/langchain4j/McpClientConfigBlueprint.java b/integrations/langchain4j/langchain4j/src/main/java/io/helidon/integrations/langchain4j/McpClientConfigBlueprint.java
@@ -0,0 +1,166 @@
+/*
+ * Copyright (c) 2025 Oracle and/or its affiliates.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.helidon.integrations.langchain4j;
+
+import java.net.URI;
+import java.time.Duration;
+import java.util.Optional;
+
+import io.helidon.builder.api.Option;
+import io.helidon.builder.api.Prototype;
+
+@Prototype.Configured
+@Prototype.Blueprint
+interface McpClientConfigBlueprint {
+
+    /**
+     * The default configuration prefix.
+     */
+    String CONFIG_ROOT = "langchain4j.mcp-clients";
+
+    /**
+     * The initial URI where to connect to the server and request a SSE
+     * channel.
+     *
+     * @return sse uri
+     */
+    @Option.Configured
+    URI sseUri();
+
+    /**
+     * Sets the name that the client will use to identify itself to the
+     * MCP server in the initialization message.
+     * Overwrites the default client name from langchain4j.
+     *
+     * @return client name
+     */
+    @Option.Configured
+    Optional<String> clientName();
+
+    /**
+     * Sets the version string that the client will use to identify
+     * itself to the MCP server in the initialization message.
+     * Overwrites the default client version from langchain4j.
+     *
+     * @return client version
+     */
+    @Option.Configured
+    Optional<String> clientVersion();
+
+    /**
+     * Sets a unique identifier for the client. If none is provided, a
+     * UUID will be automatically generated. This key is later used to identify the client
+     * in the service registry.
+     *
+     * @return client key
+     */
+    @Option.Configured
+    Optional<String> key();
+
+    /**
+     * Sets the protocol version that the client will advertise in the
+     * initialization message. Overwrites the default version from langchain4j.
+     *
+     * @return protocol version
+     */
+    @Option.Configured
+    Optional<String> protocolVersion();
+
+    /**
+     * Sets the timeout for initializing the client.
+     * Overwrites the default timeout for initializing from langchain4j.
+     *
+     * @return initialization timout
+     */
+    @Option.Configured
+    Optional<Duration> initializationTimeout();
+
+    /**
+     * Sets the timeout for tool execution.
+     * This value applies to each tool execution individually.
+     * A value of zero means no timeout.
+     * Overwrites the default timeout for tool execution from langchain4j.
+     *
+     * @return tool execution timout
+     */
+    @Option.Configured
+    Optional<Duration> toolExecutionTimeout();
+
+    /**
+     * Sets the timeout for resource-related operations (listing resources as well as reading the contents of a resource).
+     * A value of zero means no timeout.
+     * Overwrites the default timeout for resource-related operations from langchain4j.
+     *
+     * @return resources timeout
+     */
+    @Option.Configured
+    Optional<Duration> resourcesTimeout();
+
+    /**
+     * The timeout for prompt-related operations (listing prompts as well as rendering the contents of a prompt).
+     * A value of zero means no timeout.
+     * Overwrites the default timeout for prompt-related operations from langchain4j.
+     *
+     * @return prompts timeout
+     */
+    @Option.Configured
+    Optional<Duration> promptsTimeout();
+
+    /**
+     * The timeout to apply when waiting for a ping response.
+     * Overwrites the default timeout when waiting for a ping response from langchain4j.
+     *
+     * @return ping timeout
+     */
+    @Option.Configured
+    Optional<Duration> pingTimeout();
+
+    /**
+     * The delay before attempting to reconnect after a failed connection.
+     * Overwrites the default reconnect interval from langchain4j.
+     *
+     * @return reconnect interval
+     */
+    @Option.Configured
+    Optional<Duration> reconnectInterval();
+
+    /**
+     * The error message to return when a tool execution times out.
+     * Overwrites the default error message from langchain4j.
+     *
+     * @return time out error message
+     */
+    @Option.Configured
+    Optional<String> toolExecutionTimeoutErrorMessage();
+
+    /**
+     * Whether to log request traffic.
+     *
+     * @return log request traffic
+     */
+    @Option.Configured
+    Optional<Boolean> logRequests();
+
+    /**
+     * Whether to log response traffic.
+     *
+     * @return log response traffic
+     */
+    @Option.Configured
+    Optional<Boolean> logResponses();
+
+}
diff --git a/integrations/langchain4j/langchain4j/src/main/java/io/helidon/integrations/langchain4j/McpClientFactory.java b/integrations/langchain4j/langchain4j/src/main/java/io/helidon/integrations/langchain4j/McpClientFactory.java
diff --git a/integrations/langchain4j/langchain4j/src/main/java/module-info.java b/integrations/langchain4j/langchain4j/src/main/java/module-info.java
