research

Quarkus Agentic MCP Demo

このプロジェクトでは、Quarkus（Supersonic Subatomic Java フレームワーク）と Model Context Protocol (MCP) を使って構築した、インテリジェントなエージェント型アプリケーションを紹介します。複数の MCP サーバーを Quarkus および LangChain4j と統合し、ウェブ検索、位置情報サービス、ファイル管理、チームコラボレーションに対応する強力な AI アシスタントを実現します。

🌟 Java、Quarkus、MCP でエージェント型 AI アプリを構築する理由

エンタープライズ AI における Java の強み

Java は今なおエンタープライズアプリケーションの基盤であり、AI 革命を迎えた今、その力を発揮する絶好の位置にあります。

• 🏢 エンタープライズ対応：成熟した Java エコシステム、実績のある信頼性、そして企業から信頼される豊富なツールを活用できます。
• 🔒 型安全性とセキュリティ：強い型付けによりコンパイル時にエラーを検出できます。これは本番環境の AI システムに不可欠です。
• ⚡ パフォーマンス：Quarkus は 1 秒未満の起動時間と最小限のメモリフットプリントを実現し、クラウドネイティブな AI のデプロイに最適です。
• 🔄 シームレスな統合：既存の Java マイクロサービス、データベース、エンタープライズシステムに AI 機能をスムーズに接続できます。
• 👥 開発者の人材：AI プロジェクトで、世界最大の開発者コミュニティ（Java 開発者 900 万人以上）の力を活用できます。

AI アプリケーションに Quarkus を選ぶ理由

Quarkus は、クラウドネイティブな AI ワークロード向けに構築された最新の Java フレームワークです。

• ⚡ 圧倒的な速さ：ネイティブモードでは、従来の Java フレームワークに対して約 0.1 秒で起動します。
• 💾 メモリ効率：従来の Java スタックの 10 分の 1 のメモリ使用量を実現し、コスト効率の高い AI デプロイに不可欠です。
• 🔥 ライブコーディング：開発中に即座にホットリロードでき、AI の動作の変化をすぐに確認できます。
• 📊 組み込みの可観測性：OpenTelemetry を標準で統合しており、AI エージェントの判断を監視できます。
• 🐳 コンテナーを第一に考えた設計：Kubernetes、Docker、サーバーレスプラットフォームに最適化されています。
• 🎯 開発者にとっての使いやすさ：統一された設定、開発用 UI、エクステンションにより、生産性の高い AI 開発を実現します。

MCP の利点

Model Context Protocol (MCP) は、エージェント型 AI の構築を大きく変えるものです。

• 🔌 標準化されたツール統合：統一プロトコルを通じて、あらゆるサービス（Slack、Google Maps、ファイルシステム）に接続できます。
• 🧩 組み合わせ可能なアーキテクチャ：MCP サーバーを積み木のように組み合わせられ、独自の統合コードは不要です。
• 🔄 再利用可能なコンポーネント：MCP サーバーは、さまざまな AI モデルやフレームワークで利用できます。
• 🚀 迅速な開発：統合コードを書くのではなく、MCP サーバーを設定するだけで新しい機能を追加できます。
• 🌐 拡大するエコシステム：コミュニティが構築した MCP サーバーを活用して、一般的なタスクに対応できます。
• 🎭 マルチエージェント対応：共有コンテキストとツールを使って、複数の AI エージェントを連携させられます。

このデモで実証すること

このアプリケーションでは、Java、Quarkus、MCP の理想的な相乗効果を紹介します。

✅ 本番環境に対応した AI：Java の信頼性を活かし、エンタープライズ対応のエージェント型システムを構築できます。
✅ クラウドネイティブなパフォーマンス：ミリ秒単位で起動し、効率的にスケールする AI エージェントをデプロイできます。
✅ 迅速なプロトタイピング：ライブコーディングを使えば、アイデアから動作する AI エージェントまで数分で実現できます。
✅ 実環境との統合：AI を実際のサービス（Slack、Google Maps、ファイルシステム）に接続できます。
✅ 可観測性とデバッグのしやすさ：組み込みのテレメトリにより、AI の意思決定をすべて把握できます。
✅ 将来性：オープン標準（MCP）と最新の Java（Quarkus）を基盤としています。

実際のユースケース

このアーキテクチャにより、エンタープライズ向けの強力な AI シナリオを実現できます。

• 🤖 インテリジェントアシスタント：ウェブ検索、データベースへのアクセス、アクションの実行ができるチャットボットを構築できます
• 📊 データ分析エージェント：ファイルを読み込み、API に問い合わせ、レポートを生成する AI を作成できます
• 🔄 ワークフロー自動化：複数のシステム（CRM、メール、カレンダー）間で連携するエージェントを開発できます
• 🎯 カスタマーサポート：ナレッジベースへのアクセス、チケットの作成、問題のエスカレーションができる AI を導入できます
• 📈 ビジネスインテリジェンス：複数のソースからデータを収集し、洞察を提供するエージェントを構築できます

要するに：エンタープライズ向けの AI アプリケーションを構築するなら、Java + Quarkus + MCP により、Python フレームワークのパフォーマンスと、Java の信頼性およびエコシステムを活用できます。

---

📋 目次

• 概要
• 前提条件
• インストールとセットアップ
• アプリケーションの実行
• アプリケーションのテスト
• パッケージ化とデプロイ
• トラブルシューティング
• その他のリソース

🎯 概要

このアプリケーションでは、以下を紹介します。

• OpenAI の GPT モデルを使用した AI 搭載エージェントの推論
• 複数の MCP サーバーとの統合：Brave Search、Google Maps、Slack、ファイルシステム、メモリー、時刻
• WebSocket によるリアルタイムチャットインターフェース
• OpenTelemetry、Grafana、LGTM スタックによる組み込みの可観測性
• Quarkus Dev Mode によるライブコーディング

⚙️ 前提条件

このアプリケーションを実行する前に、以下がインストールされていることを確認してください。

必要なソフトウェア

1. Java 21 以降

   • バージョンの確認：java -version
   • 推奨：Java のバージョン管理には SDKMAN! を使用してください
   • このプロジェクトでは Java 21 を使用します（.sdkmanrc を参照）

   # Install SDKMAN (if not already installed)
   curl -s "https://get.sdkman.io" | bash
   
   # Install Java 21
   sdk install java 21.0.2-tem
   sdk use java 21.0.2-tem
   

2. Maven 3.9+

   • バージョンの確認：./mvnw --version
   • Maven ラッパー（mvnw）はプロジェクトに含まれています

3. Node.js と npm

   • MCP サーバープロセスに必要です
   • バージョンの確認：node --version と npm --version
   • 推奨：Node.js 18+ および npm 9+
   • nodejs.org からインストールするか、nvm を使用してください

   # Using nvm (recommended)
   nvm install --lts
   nvm use --lts
   

4. Python 3.8+（時刻 MCP サーバー用）

   • バージョンの確認：python3 --version
   • MCP time サーバーをインストールします。

   pip3 install mcp-server-time
   

5. コンテナランタイム（任意ですが推奨）

   • Docker Desktop、Podman など
   • 組み込みのテレメトリー／可観測性機能（Grafana、LGTM スタック）に必要です
   • 利用できない場合は、テレメトリーの無効化を参照してください

API キー

以下のサービスの API キーが必要です。

サービス	用途	API キーの取得先
OpenAI	LLM チャットモデル（GPT-4o-mini）	platform.openai.com
Brave Search	ウェブ検索機能	brave.com/search/api
Google Maps	位置情報と経路案内	Google Maps API
Slack	チームメッセージングとの統合	Slack MCP Setup

Slack に関する注意：Bot User OAuth Token（xoxb- で始まるもの）と Team ID の両方が必要です。セットアップ手順に従って Slack アプリを作成し、これらの認証情報を取得してください。

🚀 インストールとセットアップ

1. リポジトリをクローンする

git clone <repository-url>
cd quarkus-agentic-mcp

2. Playground ディレクトリを作成する

ファイルシステム MCP サーバーには playground ディレクトリが必要です。

mkdir -p playground

任意で、サンプルのチームファイルを作成します。

mkdir -p playground/calendar
echo "Daniel Oh - Likes Italian food" > playground/team.txt
echo "Colleague - Gluten-free diet" >> playground/team.txt

3. API キーを設定する

プロジェクトのルートディレクトリに .env ファイルを作成します（このファイルはすでに .gitignore に含まれています）。

touch .env

API キーを .env ファイルに追加します。

# OpenAI Configuration
quarkus.langchain4j.openai.api-key=sk-proj-xxxxxxxxxxxxxxxxxxxxx

# Brave Search API Key
quarkus.langchain4j.mcp.bravesearch.environment.BRAVE_API_KEY=BSAxxxxxxxxxxxxxxxxxxxxx

# Google Maps API Key
quarkus.langchain4j.mcp.googlemaps.environment.GOOGLE_MAPS_API_KEY=AIzaxxxxxxxxxxxxxxxxxxxxx

# Slack Configuration
quarkus.langchain4j.mcp.slack.environment.SLACK_BOT_TOKEN=xoxb-xxxxxxxxxxxxxxxxxxxxx
quarkus.langchain4j.mcp.slack.environment.SLACK_TEAM_ID=Txxxxxxxxxxxxx

⚠️ セキュリティに関する警告：.env ファイルをバージョン管理に絶対にコミットしないでください。本番環境へのデプロイでは、HashiCorp Vault、Kubernetes Secrets、クラウドプロバイダーのシークレット管理サービスなど、安全なシークレット管理ソリューションを使用してください。

4. MCP サーバーの依存関係を確認する

アプリケーションの起動時に、MCP サーバーのパッケージが npm 経由で自動的にダウンロードされます。npm からこれらのパッケージにアクセスできることを確認するには、次を実行します。

# Test npm access
npm view @modelcontextprotocol/server-filesystem version
npm view @modelcontextprotocol/server-memory version
npm view @modelcontextprotocol/server-brave-search version
npm view @modelcontextprotocol/server-google-maps version
npm view @modelcontextprotocol/server-slack version

5. テレメトリーを無効にする（任意）

コンテナーランタイムを利用できない場合は、src/main/resources/application.properties 内の次の行をコメントアウトして、テレメトリーを無効にします。

# Comment out these lines if no container runtime is available:
# %dev.quarkus.otel.exporter.otlp.traces.endpoint=http://localhost:4317
# %dev.quarkus.otel.exporter.otlp.traces.headers=authorization=Bearer my_secret
# %dev.quarkus.datasource.jdbc.telemetry=true
# %dev.quarkus.otel.logs.enabled=true
# %dev.quarkus.otel.traces.enabled=true

または、.env ファイルに次の設定を追加します。

quarkus.observability.enabled=false

🏃 アプリケーションの実行

開発モード（推奨）

ライブリロードを有効にして、開発モードでアプリケーションを起動します。

./mvnw compile quarkus:dev

起動時に行われる処理：

• Maven が Java コードをコンパイルします
• Quarkus がポート 8080 でアプリケーションを起動します
• MCP サーバーが npm/python 経由で自動的に起動します
• Dev Services（LGTM スタックなど）がコンテナー内で起動します（利用可能な場合）
• コードの変更が即座に反映されるよう、ライブリロードが有効になります

アクセス先：

• メインアプリケーション：http://localhost:8080
• Dev UI：http://localhost:8080/q/dev/
• Grafana（テレメトリーが有効な場合）：Dev UI → Observability から利用できます

初回起動時

初回の起動には、次の処理が行われるため、時間がかかる場合があります。

1. Maven の依存関係をダウンロードします
2. MCP サーバー用の npm パッケージをダウンロードします
3. Dev Services のコンテナーを起動します
4. アプリケーションをコンパイルします

2 回目以降の起動は、はるかに速くなります。

アプリケーションの起動を確認する

次のような出力が表示されます。

__  ____  __  _____   ___  __ ____  ______
 --/ __ \/ / / / _ | / _ \/ //_/ / / / __/
 -/ /_/ / /_/ / __ |/ , _/ ,< / /_/ /\ \
--\___\_\____/_/ |_/_/|_/_/|_|\____/___/
INFO  [io.quarkus] (Quarkus Main Thread) research 1.0-SNAPSHOT on JVM (powered by Quarkus 3.36.0) started in 3.456s. Listening on: http://localhost:8080
INFO  [io.quarkus] (Quarkus Main Thread) Profile dev activated. Live Coding activated.
INFO  [io.quarkus] (Quarkus Main Thread) Installed features: [cdi, langchain4j-mcp, langchain4j-openai, ...]

🧪 アプリケーションのテスト

Web インターフェース

アプリケーションが起動したら、ブラウザーで http://localhost:8080 を開きます。AI アシスタントとやり取りできるチャットインターフェースが表示されます。

プロンプトの例

次のプロンプトを試して、エージェントの推論とツールの使用を確認します。

複雑な複数ステップのタスク

My name is Daniel Oh. I am a member of a team of 2. I like Italian food, while my colleague is on a strict gluten-free diet.

Please find one good restaurant in Boston, MA with the highest rating that meets the team's dietary needs and preferences.
Then, invite the team to a lunch at 12pm next Friday. In your message, include the name and description of the restaurant,
the time and date of the lunch, and driving directions from Back Bay, Boston.

この例で確認できること：

• playground/team.txt からチーム情報を読み取る（ファイルシステム MCP）
• レストランを Web 検索する（Brave Search MCP）
• 位置情報と道順を調べる（Google Maps MCP）
• 日付と時刻を計算する（Time MCP）
• 会話のコンテキストを記憶する（Memory MCP）

続けて試すタスク

最初のプロンプトを送信した後、次の内容を試します。

Send the restaurant recommendation details to the slack channel "#lunchtime".

Create an ICS calendar file for me in my calendar in the "playground/calendar" directory.

推論と振り返りのプロンプト

What was the reasoning you used to arrive at that recommendation?

How did you choose the restaurant?

What actions did you take for each step and which tools did you use?

Why did you search for gluten-free restaurants?

What do you remember about each person on the team based on team.txt file?

Dev UI の使用

Quarkus Dev UI では、追加のテスト機能を利用できます。

1. http://localhost:8080/q/dev/ に移動します
2. Extensions → LangChain4j → Chat を開きます
3. Bot.java のシステムメッセージがあらかじめ入力されています
4. AI アシスタントとのチャットを開始します

Dev UI の機能：

• 利用可能なすべての MCP ツールを表示する
• リクエスト／レスポンスのログを監視する
• Grafana ダッシュボードにアクセスする（テレメトリーが有効な場合）
• コードの変更をホットリロードする
• アプリケーションのメトリクスを表示する

オブザーバビリティ

テレメトリーが有効な場合（コンテナーランタイムを利用できる場合）は、次の手順に従います。

1. Dev UI → Observability に移動します
2. Grafana のリンクをクリックします
3. トレース、ログ、メトリクスを確認します
4. LLM のリクエスト／レスポンスの詳細を表示します
5. MCP サーバーとのやり取りを監視します

📦 パッケージ化とデプロイ

標準 JVM パッケージ

標準の JVM パッケージをビルドします。

./mvnw package

依存関係が target/quarkus-app/lib/ に格納され、target/quarkus-app/quarkus-run.jar が作成されます。

パッケージ化したアプリケーションを実行する：

# Ensure API keys are set as environment variables
export OPENAI_API_KEY="your-key-here"
export BRAVE_API_KEY="your-key-here"
export GOOGLE_MAPS_API_KEY="your-key-here"
export SLACK_BOT_TOKEN="your-token-here"
export SLACK_TEAM_ID="your-team-id"

# Run the application
java -jar target/quarkus-app/quarkus-run.jar

Uber JAR パッケージ

すべての依存関係を含む、実行可能な単一の JAR をビルドします。

./mvnw package -Dquarkus.package.type=uber-jar

Uber JAR を実行する：

java -jar target/research-1.0-SNAPSHOT-runner.jar

ネイティブ実行ファイル

起動を高速化し、メモリ使用量を削減するには、ネイティブ実行ファイルをビルドします。

オプション 1：GraalVM をローカルにインストールしてビルド

# Ensure GraalVM is installed and GRAALVM_HOME is set
./mvnw package -Dnative

オプション 2：コンテナビルドを使用（推奨）

# No GraalVM installation required
./mvnw package -Dnative -Dquarkus.native.container-build=true

ネイティブ実行ファイルを実行：

# Set environment variables
export OPENAI_API_KEY="your-key-here"
# ... (other API keys)

# Run
./target/research-1.0-SNAPSHOT-runner

ネイティブビルドのメリット：

• ⚡ 起動時間：約 0.1 秒（JVM の場合は約 3 秒）
• 💾 メモリ使用量：約 50 MB（JVM の場合は約 200 MB）
• 📦 単一の実行可能バイナリ
• 🚀 コンテナやサーバーレスに最適

注：ネイティブビルドには時間がかかります（5〜10 分）が、高度に最適化された実行ファイルが生成されます。

コンテナのデプロイ

コンテナイメージをビルドします。

# Using Docker
docker build -f src/main/docker/Dockerfile.jvm -t quarkus-agentic-mcp:jvm .

# Or for native
docker build -f src/main/docker/Dockerfile.native -t quarkus-agentic-mcp:native .

コンテナを実行：

docker run -i --rm -p 8080:8080 \
  -e OPENAI_API_KEY="your-key" \
  -e BRAVE_API_KEY="your-key" \
  -e GOOGLE_MAPS_API_KEY="your-key" \
  -e SLACK_BOT_TOKEN="your-token" \
  -e SLACK_TEAM_ID="your-team-id" \
  quarkus-agentic-mcp:jvm

🔧 トラブルシューティング

よくある問題

1.「node または npm が見つかりません」

問題：Node.js/npm が見つからないため、MCP サーバーを起動できません。

解決策：

# Verify installation
node --version
npm --version

# If not installed, install Node.js
# macOS (using Homebrew)
brew install node

# Linux (using nvm)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install --lts

2.「Python3 が見つかりません」または Time MCP サーバーが失敗する

問題：Time MCP サーバーには Python 3 が必要です。

解決策：

# Install Python 3
# macOS
brew install python3

# Install the MCP time server
pip3 install mcp-server-time

# Verify
python3 --version
python3 -m mcp_server_time --help

3. API キーのエラー

問題：「Unauthorized」または「Invalid API key」エラーが発生します。

解決策：

• .env ファイルが存在し、有効なキーが含まれていることを確認します
• キーに余分なスペースや引用符が含まれていないことを確認します
• .env ファイルがプロジェクトのルートディレクトリにあることを確認します
• .env の更新後、アプリケーションを再起動します

4. ポート 8080 がすでに使用されています

問題：別のアプリケーションがポート 8080 を使用しています。

解決策：

# Find what's using the port
lsof -i :8080

# Kill the process or change Quarkus port
# Add to .env:
quarkus.http.port=8081

5. コンテナ／Docker の問題

問題：テレメトリ機能を起動できません。

解決策：

• Docker/Podman が起動していることを確認します：docker ps
• または、テレメトリを無効にします（テレメトリの無効化を参照）

6. MCP サーバーへの接続失敗

問題：「Failed to connect to MCP server」エラーが発生します。

解決策：

# Test npm package access
npm view @modelcontextprotocol/server-filesystem

# Clear npm cache if needed
npm cache clean --force

# Verify playground directory exists
ls -la playground/

7. メモリ不足エラー

問題：OutOfMemoryError によりアプリケーションがクラッシュします。

解決策：

# Increase JVM heap size
./mvnw compile quarkus:dev -Djvm.args="-Xmx2g"

デバッグモード

トラブルシューティングのために詳細なログを有効にします。

.env に追加します：

quarkus.log.level=DEBUG
quarkus.log.category."io.quarkiverse.langchain4j".level=DEBUG
quarkus.log.category."dev.langchain4j".level=DEBUG

ヘルプを得る

• Quarkus のドキュメント：https://quarkus.io/guides/
• LangChain4j Quarkus：https://docs.quarkiverse.io/quarkus-langchain4j/dev/
• MCP のドキュメント：https://modelcontextprotocol.io/
• GitHub Issues：リポジトリでバグを報告したり、質問したりできます

📚 追加リソース

ドキュメント

• Quarkus：https://quarkus.io/
• LangChain4j：https://docs.langchain4j.dev/
• Model Context Protocol：https://modelcontextprotocol.io/
• OpenAI API：https://platform.openai.com/docs/

主なテクノロジー

• Quarkus LangChain4j MCP Extension（ガイド）：MCP クライアントの実装
• Quarkus LangChain4j OpenAI（ガイド）：OpenAI との統合
• Quarkus WebSockets：リアルタイム通信
• Quarkus OpenTelemetry：オブザーバビリティとトレーシング

使用する MCP サーバー

サーバー	用途	ドキュメント
filesystem	ファイル操作	npm
memory	会話のメモリ	npm
brave-search	ウェブ検索	npm
google-maps	位置情報サービス	npm
slack	チームメッセージング	npm
time	日付／時刻の操作	PyPI

プロジェクト構成

quarkus-agentic-mcp/
├── src/main/java/
│   ├── Bot.java              # AI assistant configuration
│   └── BotWebsocket.java     # WebSocket endpoint
├── src/main/resources/
│   ├── application.properties # Configuration
│   └── META-INF/resources/
│       └── index.html        # Web UI
├── playground/               # Filesystem MCP workspace
├── pom.xml                   # Maven dependencies
├── .env                      # API keys (create this)
└── README.md                 # This file

設定リファレンス

application.properties の主な設定プロパティ：

• LLM モデル：quarkus.langchain4j.openai.chat-model.model-name=gpt-4o-mini
• Temperature：quarkus.langchain4j.openai.chat-model.temperature=0.8
• タイムアウト：quarkus.langchain4j.openai.timeout=3m
• MCP サーバー：quarkus.langchain4j.mcp.<server-name>.*

コントリビューション

コントリビューションを歓迎します。以下の手順に従ってください。

1. リポジトリをフォークします
2. フィーチャーブランチを作成します
3. 変更を加えます
4. プルリクエストを送信します

ライセンス

[Add your license information here]

---

Quarkus、LangChain4j、Model Context Protocol を使用して ❤️ を込めて構築