Skip to content

Commit 6dd0370

Browse files
jmartiskjmartisk
authored
Merge pull request #2203 from jmartisk/mcp
Blog post about MCP client
2 parents 123151e + 79d7e37 commit 6dd0370

File tree

3 files changed

+215
-0
lines changed

3 files changed

+215
-0
lines changed

‎_data/authors.yaml‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -573,3 +573,10 @@ mariofusco:
573573
job_title: "Senior Principal Software Engineer"
574574
twitter: "mariofusco"
575575
bio: "Senior Principal Software Engineer at Red Hat ~ Java Champion ~ Open source advocate ~ Frequent speaker ~ @jugmilano coordinator ~ Drools project lead at RedHat ~ Pragmatic dreamer ~ Europeist"
576+
jmartisk:
577+
name: "Jan Martiška"
578+
email: "[email protected]"
579+
emailhash: "165fddadd5535ca662008df08e8ad59b"
580+
job_title: "Software Engineer"
581+
twitter: "janmartiska"
582+
bio: "Software engineer at Red Hat"

‎_posts/2025-01-08-quarkus-langchain4j-mcp.adoc‎

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
---
2+
layout: post
3+
title: 'Using the Model Context Protocol with Quarkus+LangChain4j'
4+
date: 2025-01-08
5+
tags: langchain4j llm ai
6+
synopsis: 'Executing tools via the Model Context Protocol with Quarkus+LangChain4j'
7+
author: jmartisk
8+
---
9+
:imagesdir: /assets/images/posts/mcp
10+
11+
We are thrilled to announce that starting with version 0.23.0, the Quarkus
12+
LangChain4j project integrates calling tools using the
13+
https://modelcontextprotocol.io[Model Context Protocol (MCP)].
14+
15+
== What is the Model Context Protocol?
16+
17+
MCP is an open protocol that standardizes how applications provide context
18+
to LLMs. An MCP server is an application that can provide tools, resources
19+
(be it a set of static documents or dynamically accessed data, for example
20+
from a database), or pre-defined prompts that your AI-infused application
21+
can use when talking to LLMs. When you package such functionality into an
22+
MCP server, it can be plugged into and used by any LLM client toolkit that
23+
supports MCP, including Quarkus and LangChain4j. There is also already a
24+
growing ecosystem of reusable MCP servers that you can use out of the box,
25+
and Quarkus also offers the
26+
https://github.com/quarkiverse/quarkus-mcp-server[quarkus-mcp-server extension] that allows you
27+
to create MCP servers, but in this article, we will focus on the client
28+
side. More on creating MCP servers later.
29+
30+
In version 0.23.x,
31+
https://github.com/quarkiverse/quarkus-langchain4j[Quarkus LangChain4j]
32+
implements the client side of the MCP protocol to allow tool execution.
33+
Support for resources and prompts is planned for future releases.
34+
35+
In this article, we will show you how to use Quarkus and LangChain4j to
36+
easily create an application that connects to an MCP server providing
37+
filesystem-related tools and exposes a chatbot that a user can use to
38+
interact with the local filesystem, that means read and write files as
39+
instructed by the user.
40+
41+
There is no need to set up an MCP server separately, we will configure
42+
Quarkus to run one as a subprocess. As you will see, setting up MCP with
43+
Quarkus is extremely easy.
44+
45+
NOTE: To download the final project, visit the
46+
https://github.com/quarkiverse/quarkus-langchain4j/tree/0.23.0/samples/mcp-tools[
47+
quarkus-langchain4j samples]. That sample contains the final functionality
48+
developed in this article, plus some stuff on top, like a JavaScript-based
49+
UI. In this article, for simplicity, we will skip the creation of that UI,
50+
and we will only use the Dev UI chat page that comes bundled in Quarkus out
51+
of the box.
52+
53+
== Prerequisites
54+
55+
* Apache Maven 3.9+
56+
* The `npm` package manager installed on your machine
57+
58+
== Creating a Filesystem assistant project
59+
60+
We will assume that you are using OpenAI as the LLM provider. If you are
61+
using a different provider, you will need to swap out the
62+
`quarkus-langchain4j-openai` extension and use something else.
63+
64+
Start by generating a Quarkus project. If you are using the Quarkus CLI, you can do it like this:
65+
66+
[source, shell]
67+
----
68+
quarkus create app org.acme:filesystem-assistant:1.0-SNAPSHOT \
69+
--extensions="langchain4j-openai,langchain4j-mcp,vertx-http" -S 3.17
70+
----
71+
72+
If you prefer to use the web-based project generator, go to
73+
https://code.quarkus.io/[code.quarkus.io] and select the same extensions.
74+
75+
Whenever you run the application, make sure the
76+
`QUARKUS_LANGCHAIN4J_OPENAI_API_KEY` environment variable is set to your
77+
OpenAI API key.
78+
79+
=== Create the directory to be used by the agent
80+
81+
Under the root directory of the Maven project, create a directory named `playground`.
82+
This will be the only directory that the agent will be allowed to interact with.
83+
84+
Inside that directory, create any files that you want for testing. For
85+
example, create a file named `playground/hello.txt` with the following
86+
contents:
87+
88+
----
89+
Hello, world!
90+
----
91+
92+
=== Create the AI service
93+
94+
Next, we need to define an AI service that will define how the bot should
95+
behave. The interface will look like this:
96+
97+
[source, java]
98+
----
99+
@RegisterAiService
100+
@SessionScoped
101+
public interface Bot {
102+
103+
@SystemMessage("""
104+
You have tools to interact with the local filesystem and the users
105+
will ask you to perform operations like reading and writing files.
106+
107+
The only directory allowed to interact with is the 'playground' directory relative
108+
to the current working directory. If a user specifies a relative path to a file and
109+
it does not start with 'playground', prepend the 'playground'
110+
directory to the path.
111+
112+
If the user asks, tell them you have access to a tool server
113+
via the Model Context Protocol (MCP) and that they can find more
114+
information about it on https://modelcontextprotocol.io/.
115+
"""
116+
)
117+
String chat(@UserMessage String question);
118+
}
119+
----
120+
121+
Feel free to adjust the system message to your liking, but this one should
122+
be suitable to get the application working as expected.
123+
124+
=== Configure the MCP server and the connection to it
125+
126+
We will use
127+
https://www.npmjs.com/package/@modelcontextprotocol/server-filesystem[server-filesystem]
128+
MCP server that comes as an NPM package, this is why you need to have `npm`
129+
installed on your machine. It is assumed that you have the `npm` binary
130+
available on your `PATH` (the `PATH` variable that the Quarkus process
131+
sees).
132+
133+
Starting the server and configuring the connection to it is extremely easy.
134+
We will simply tell Quarkus to start up a `server-filesystem` MCP server as
135+
a subprocess and then communicate with it over the `stdio` transport. All
136+
you need to do is to add two lines into your `application.properties`:
137+
138+
[source, properties]
139+
----
140+
quarkus.langchain4j.mcp.filesystem.transport-type=stdio
141+
quarkus.langchain4j.mcp.filesystem.command=npm,exec,@modelcontextprotocol/[email protected],playground
142+
----
143+
144+
With this configuration, Quarkus will know that it should create a MCP
145+
client that will be backed by a server that will be started by executing
146+
`npm exec @modelcontextprotocol/[email protected] playground` as a
147+
subprocess. The `playground` argument denotes the path to the directory that
148+
the agent will be allowed to interact with. The `stdio` transport means that
149+
the client will communicate with the server over standard input and output.
150+
151+
When you configure one or more MCP connections this way, Quarkus also
152+
automatically generates a `ToolProvider`. Any AI service that does not
153+
explicitly specify a tool provider will be automatically wired up to this
154+
generated one, so you don't need to do anything else to make the MCP
155+
functionality available to the AI service.
156+
157+
Optionally, if you want to see the actual traffic between the application
158+
and the MCP server, add these three additional lines to your
159+
`application.properties`:
160+
161+
[source, properties]
162+
----
163+
quarkus.langchain4j.mcp.filesystem.log-requests=true
164+
quarkus.langchain4j.mcp.filesystem.log-responses=true
165+
quarkus.log.category.\"dev.langchain4j\".level=DEBUG
166+
----
167+
168+
And that's all! Now, let's test it.
169+
170+
=== Try it out
171+
172+
Since we didn't create any UI for our application that a user could use,
173+
let's use the Dev UI that comes with Quarkus out of the box. With the
174+
application running in development mode, access
175+
http://localhost:8080/q/dev-ui in your browser and click the `Chat` link in
176+
the `LangChain4j` card (either that, or go to
177+
http://localhost:8080/q/dev-ui/io.quarkiverse.langchain4j.quarkus-langchain4j-core/chat
178+
directly).
179+
180+
Try a prompt to ask the agent to read a file that you created previously, such as:
181+
182+
----
183+
Read the contents of the file hello.txt.
184+
----
185+
186+
If all is set up correctly, the agent will respond with the contents of the
187+
file, like in this screenshot:
188+
189+
image::devui.png[Dev UI chat page after asking about a file,400,float="right",align="center"]
190+
191+
The bot can also write files, so try a prompt such as:
192+
193+
----
194+
Write a Python script that prints "Hello, world!" and save it as hello.py.
195+
----
196+
197+
Then have a look into your `playground` directory, and you should see the new Python file there!
198+
199+
=== Conclusion
200+
201+
The Model Context Protocol allows you to easily integrate reusable sets of
202+
tools and resources to AI-infused applications in a portable way. With the
203+
Quarkus LangChain4j extension, you can instruct Quarkus to run a server
204+
locally as a subprocess, and configuring application to use it is just a
205+
matter of adding a few configuration properties.
206+
207+
And that's not all. Stay tuned, because Quarkus also has an extension that
208+
allows you to create MCP servers! More about that soon.

‎assets/images/posts/mcp/devui.png‎

34.4 KB
Loading

0 commit comments

Comments
 (0)