Merge pull request #2222 from maxandersen/mcpservers

introducing mcp servers

_posts/2025-01-29-introducing-mcp-servers.adoc

@@ -0,0 +1,118 @@
+---
+layout: post
+title: 'Introducing Model Context Protocol servers project'
+date: 2025-01-29
+tags: ai
+synopsis: Introducing the Model Context Protocol servers project which provides a set of MCP servers implemented using Quarkus and Java. Starting with JDBC, filesystem and JavaFX.
+author: maxandersen
+---
+:imagesdir: /assets/images/posts/mcpservers
+ifdef::env-github,env-browser,env-vscode[:imagesdir: ../assets/images/posts/mcpservers]
+
+Today, I'm excited to introduce the Model Context Protocol (MCP) servers project.
+
+Model Context Protocol is the recent approach to enable AI models to interact with your applications and services in a nice decoupled way.
+
+The https://github.com/quarkiverse/quarkus-mcp-servers[mcp-servers] project is as far as I know the first one to provide a set of MCP servers implemented using Java and at least uniquely Quarkus.
+
+Intended to show-case the capabilities of the Model Context Protocol, and inspiration for what you can do with it - especially in Java.
+
+== The Servers
+
+At time of writing there are three servers implemented:
+
+JDBC:: Let your AI app introspect and interact to any JDBC-compatible database, let it be PostgreSQL, MySQL, MariaDB, SQLite, Oracle, etc. image:https://github.com/quarkiverse/quarkus-mcp-servers/raw/main/jdbc/images/jdbc-trends-demo.png[JDBC server]
+
+Filesystem:: Access the file system of your machine, let it be your home directory, your code directory, your project directory, etc. image:https://github.com/quarkiverse/quarkus-mcp-servers/raw/main/filesystem/images/filesystem-demo.png[Filesystem server]
+
+JavaFX:: Draw on a JavaFX canvas, get your AI to draw some art for you! Based on idea from https://gist.github.com/konczdev/5e6774d2d8640bf83baab88cb068bcc2[@konczdev]image:https://github.com/quarkiverse/quarkus-mcp-servers/raw/main/jfx/images/jfx-demo.png[JavaFX server]
+
+Each server is implemented using Quarkus and Java, and each server is available to easily run using JBang. No need for user to install Java, Quarkus or any other Java tool.
+
+== How to use the servers
+
+The general setup is to install https://jbang.dev/download/[JBang], preferably using a package manager as then desktop apps are more likely to find `jbang` in the PATH.
+
+Then in your MCP client configure it with:
+
+`jbang [server-name]@quarkiverse/quarkus-mcp-servers [arguments]`
+
+For example to run the JDBC server to connect to a MariaDB database you would do:
+
+`jbang mcp-jdbc-server@quarkiverse/quarkus-mcp-servers jdbc:mariadb://localhost:3306/test --user root --password mysecretpassword`
+
+or use a downlodable SQLite database of Netflix movies:
+
+`jbang mcp-jdbc-server@quarkiverse/quarkus-mcp-servers jdbc:sqlite:%{https://github.com/lerocha/netflixdb/releases/download/v1.0.0/netflixdb.sqlite}`
+
+TIP: Tthe `%{}` syntax is a JBang feature to download a file from a URL in the command line and use it as a local file.
+
+Similar there is `jbang jfx@quarkiverse/quarkus-mcp-servers` to draw on a JavaFX canvas, and `jbang filesystem@quarkiverse/quarkus-mcp-servers [path]` to access the file system.
+
+== Tested MCP Clients
+
+During development we tested the servers with the following clients:
+
+* https://claude.ai/download[Claude Desktop]
+* https://github.com/chrishayuk/mcp-cli[mcp-cli]
+* https://block.github.io/goose/docs/quickstart/[Goose]
+
+There are more MCP clients out there, and we're sure that the servers will work with many more.
+
+Goose is noteworthy given it is opensource and available both as a desktop app (on MacOS) and as a cli tool. It was https://block.github.io/goose/docs/quickstart/[recently announced] with full support for the Model Context Protocol.
+
+Here I configured Goose to use the SQLLite database from the Northwind sample database with this setup stored in `~/.config/goose/config.yaml`:
+
+```yaml
+extensions:
+  netflixdb:
+  args:
+    - jdbc@quarkiverse/quarkus-mcp-servers
+    - jdbc:sqlite:%{https://github.com/lerocha/netflixdb/releases/download/v1.0.0/netflixdb.sqlite}
+    cmd: jbang
+    enabled: true
+    envs: {}
+    name: netflixdb
+    type: stdio
+```
+
+Note: we do recommend to use `goose config` to generate/edit the config file.
+
+With the above config Goose will be able to use the JDBC server to connect to the SQLLite database:
+
+image::mcp-jdbc-goose.png[Goose using the JDBC server to connect to the SQLLite database]
+
+== Unique features for Quarkus MCP Servers
+
+All that is great, but why use Quarkus for implementing the MCP servers?
+
+First is that the programming model provided by Quarkus is very powerful, allowing you to easily focus on the business logic of your application. See https://quarkus.io/blog/mcp-server/[previous blog] for details on how to implement a server or look at the https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/jdbc/src/main/java/io/quarkus/mcp/servers/jdbc/MCPServerJDBC.java[code of the JDBC servers]. Notice how compact it is!
+
+Second, is the wast Java ecosystem provides things like JDBC drivers which enables us to make a single server that works with any JDBC-compatible database. We use `jbang` to dynamically download https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/jdbc/.scripts/mcpjdbc.java[the right JDBC driver] and then launch the quarkus mcp server. Similar is done for `jfx` to https://github.com/quarkiverse/quarkus-mcp-servers/blob/main/jbang-catalog.json#L34[fetch] the right OS specific JavaFX dependencies.
+
+Thirdly, ability to run the servers as a native executable. In the MCP servers project the `filesystem` server is https://github.com/quarkiverse/quarkus-mcp-servers/releases[published as a native executable] you can download and gain a much faster startup time.
+
+There is also a lot of interesting things to come around how to use quarkus dev mode with MCP servers and testing - but that will be for another blog post.
+
+== JBang required or not ?
+
+JBang is in general not required to run an MCP server, but it makes it much easier and makes it possible for anyone, especially non-Java developers to use these servers.
+
+You can of course run a simple MCP servers as a normal Java application, but then you need to install right version of Java, download the server and their dependencies and run it like `java -jar [path to server jar]`.
+
+For the MCP servers project we have chosen to use JBang as we go beyond and utiize JBang to dynamically fetch drivers and OS specific deps. Without JBang that would be much harder, if not impossible to make consumable.
+
+== Sky is the limit!
+
+The Model Context Protocol opens up exciting possibilities for building intelligent applications using your application data with your favourite programming language and framework. With Quarkus MCP Servers, you have a powerful foundation to create your own Java based servers that can bridge AI with any data source or system you can imagine.
+
+Whether you want to connect to your favorite database, integrate with your company's internal systems, or build something completely new - the sky truly is the limit! The simplicity of implementing MCP servers with Quarkus means you can focus on the creative aspects rather than the plumbing.
+
+We'd love to see what you build! Leave a comment or consider contributing your MCP servers back to the community through the https://github.com/quarkiverse/quarkus-mcp-servers[Quarkiverse MCP Servers project]. Your implementation could help others solve similar problems or inspire them to create something even more amazing.
+
+So what are you waiting for? Grab the code, fire up your IDE, and start building your own MCP server today. The future of AI-powered applications is here, and you can be part of shaping it!
+
+Have Fun!
+
+p.s. Next week on Thursday February 6th we're hosting a https://quarkus.io/insights/[MCP server Insights] where we will discuss the MCP server and client SDK's in Quarkus project and how you can use it to build your own MCP servers and extend your AI infused applications.
+