quarkus-mcp-server-example

Quarkus MCP サーバーの例

Quarkus を使用して、REST API 操作を AI ツールとして公開する Model Context Protocol（MCP）サーバー の構築方法を示す包括的な例です。これにより、Goose CLI を使って、Claude のような大規模言語モデルが自然言語でアプリケーションのデータを操作できるようになります。

🎯 この例で紹介する内容

このプロジェクトでは、3 つの強力なテクノロジーの連携を紹介します。

• Quarkus：モダンなアプリケーションを構築するための超高速かつ軽量な Java フレームワーク
• MCP（Model Context Protocol）：AI アシスタントをデータソースやツールに接続するためのオープンな標準
• Goose CLI：MCP サーバーと連携できる、AI 搭載の開発アシスタント

📋 目次

• MCP とは？
• Quarkus とは？
• Goose とは？
• ソリューションのアーキテクチャ
• 前提条件
• 例の実行
• 使用例

🔗 MCP とは？

Model Context Protocol（MCP） は、AI アシスタントがさまざまなデータソースやツールに安全に接続し、連携できるようにするオープンな標準です。AI アシスタントごとにカスタム連携を構築する代わりに、MCP は以下のための汎用プロトコルを提供します。

• ツールの検出：AI アシスタントが利用可能なツールを検出できます
• ツールの実行：外部システムに対する操作を安全に実行します
• データアクセス：さまざまなソースからデータを取得し、操作します
• 標準化：1 つの実装で、MCP 対応のあらゆる AI アシスタントと連携できます

MCP のメリット

• 相互運用性：MCP 対応のあらゆる AI アシスタントと連携できます
• セキュリティ：外部リソースへのアクセスを制御できます
• 拡張性：新しいツールや機能を簡単に追加できます
• 標準化：AI アシスタントごとにカスタム連携を行う必要がありません

⚡ Quarkus とは？

Quarkus は、モダンなアプリケーション開発向けに設計された、Kubernetes ネイティブの Java フレームワークです。

• 高速な起動：1 秒未満で起動します
• 低メモリ使用量：コンテナ化された環境向けに最適化されています
• 快適な開発体験：ライブリロード、統一された設定、優れたツールを提供します
• クラウドネイティブ：Kubernetes、サーバーレス、マイクロサービス向けに構築されています
• 標準ベース：使い慣れた Java 標準（JAX-RS、CDI、JPA）を使用します

MCP に適した Quarkus

Quarkus が MCP サーバーに最適な理由は次のとおりです。

• 迅速な開発：ライブリロードによる素早いフィードバックループ
• 軽量：ツールサーバーのリソース使用量を最小限に抑えます
• ネイティブコンパイル：GraalVM による超高速な起動
• 豊富なエコシステム：データベース、REST クライアントなどに対応する幅広いエクステンション

🦆 Goose とは？

Goose は、次のような機能で開発者を支援する、AI 搭載の開発アシスタント CLI です。

• 自然言語インターフェース：平易な英語で開発環境を操作します
• MCP 連携：MCP サーバーに接続して、外部のツールやデータにアクセスします
• コンテキスト認識：プロジェクトの構造やコードベースを理解します
• ツールの実行：コマンドの実行、ファイルの変更、API との連携が可能です
• マルチモデル対応：Claude、GPT など、さまざまな LLM に対応しています

MCP と連携する Goose

MCP サーバーと組み合わせると、Goose は次のことができます。

• 自然言語でデータベースにクエリを実行する
• curl コマンドを手動で実行せずに REST API と連携する
• 複数のツールを組み合わせて複雑な操作を実行する
• アプリケーションデータに基づくインテリジェントな分析結果を提供する

🏗️ ソリューションのアーキテクチャ

┌─────────────────────────────────────────────────────────────────────────────┐
│                           MCP Integration Flow                               │
└─────────────────────────────────────────────────────────────────────────────┘

    ┌─────────────┐    MCP Protocol     ┌─────────────────┐    REST API    ┌──────────────┐
    │             │   (JSON-RPC over    │                 │   (HTTP/JSON)  │              │
    │    Goose    │◄───────────────────►│   Quarkus MCP   │◄──────────────►│   Quarkus    │
    │     CLI     │     STDIO/SSE)      │     Server      │                │ Applications │
    │             │                     │                 │                │      MS      │
    └─────────────┘                     └─────────────────┘                └──────────────┘
           │                                      │                               │
           │                                      │                               │
    ┌──────▼──────┐                        ┌─────▼─────┐                 ┌───────▼───────┐
    │             │                        │           │                 │               │
    │   Claude    │                        │ MCP Tools │                 │  PostgreSQL   │
    │     LLM     │                        │           │                 │   Database    │
    │             │                        │ • list    │                 │               │
    └─────────────┘                        │ • get     │                 └───────────────┘
                                           │ • filter  │
                                           │ • add     │
                                           └───────────┘

┌─────────────────────────────────────────────────────────────────────────────┐
│                              Data Flow                                      │
└─────────────────────────────────────────────────────────────────────────────┘

1. User asks Goose: "Show me all applications from Spain"
                    ↓
2. Goose sends MCP request to discover available tools
                    ↓
3. MCP Server exposes tools: list_applications, get_applications_by_country, etc.
                    ↓
4. Goose calls get_applications_by_country("Spain") tool
                    ↓
5. MCP Server makes REST call to Applications MS
                    ↓
6. Applications MS queries PostgreSQL database
                    ↓
7. Results flow back through the chain to Goose
                    ↓
8. Goose presents results to user in natural language

コンポーネントの役割

コンポーネント	目的	テクノロジー
Goose CLI	AI アシスタントのインターフェース、自然言語処理	Go、LLM 連携
Quarkus MCP Server	プロトコルブリッジ、ツール定義	Quarkus、MCP プロトコル
Quarkus Applications MS	ビジネスロジック、データ操作	Quarkus、JAX-RS、Hibernate
PostgreSQL	データ永続化	リレーショナルデータベース

前提条件

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

• Java 21：Quarkus アプリケーションに必要です
• Maven：Java プロジェクト用のビルドツールです
• Podman/Docker：PostgreSQL データベース用のコンテナーランタイムです
• Goose CLI：AI アシスタントツール（インストールガイド）

Goose のインストール

# Using Go (requires Go 1.21+)
go install github.com/square/goose@latest

# Or download binary from releases
# https://github.com/square/goose/releases

🚀 サンプルの実行

ステップ 1：プロジェクトをビルドする

mvn clean package

ステップ 2：PostgreSQL データベースを起動する

podman run -d --name db-server \
  -e POSTGRES_USER=test \
  -e POSTGRES_PASSWORD=test \
  -e POSTGRES_DB=applications \
  -p 5432:5432 \
  postgres:16

ステップ 3：Applications マイクロサービスを起動する

cd quarkus-applications-ms && mvn quarkus:dev

Applications サービスは http://localhost:8080 で起動します。

ステップ 4：（任意）サンプルデータを追加する

curl -i -X POST \
  -F "name=Angel" \
  -F "surname=Miralles" \
  -F "personalId=12345R" \
  -F "country=Spain" \
  http://localhost:8080/application.html

curl -i -X POST \
  -F "name=Juan" \
  -F "surname=Garcia" \
  -F "personalId=31234R" \
  -F "country=Spain" \
  http://localhost:8080/application.html
  
curl -i -X POST \
  -F "name=Pedro" \
  -F "surname=Rodriguez" \
  -F "personalId=54321R" \
  -F "country=Germany" \
  http://localhost:8080/application.html

ステップ 5：MCP サーバーとともに Goose を起動する

goose session --with-extension="java -jar quarkus-mcp-server/target/quarkus-mcp-server-1.0.0-SNAPSHOT.jar"

💡 使用例

MCP サーバーとともに Goose を起動すると、自然言語を使ってアプリケーションのデータを操作できます。

基本的なクエリ

> Show me all applications in the system
> List applications from Spain
> Get application with ID 1

フィルター付きクエリ

> Show me all applications from France with COMPLETED status
> List all STARTED applications
> Find applications from Germany

データ管理

> Add a new application for John Doe from USA with ID 67890
> Create an application for Maria Garcia from Mexico

利用可能な MCP ツール

MCP サーバーは、以下のツールを Goose に公開します。

ツール名	説明	パラメーター
list_applications	すべてのアプリケーションを一覧表示します	なし
get_application_by_id	指定したアプリケーションを取得します	id: Long
get_applications_by_country	国で絞り込みます	countryName: String
get_applications_by_country_and_status	国とステータスで絞り込みます	countryName: String、status: ApplicationStatus
add_application	新しいアプリケーションを作成します	application: Application

アプリケーションのステータス値

• STARTED
• PREPROCESSED
• PROCESSED
• COMPLETED
• CANCELED
• ERROR

🔧 開発

開発モード

# Start applications service in dev mode (hot reload)
cd quarkus-applications-ms && mvn quarkus:dev

# Package MCP server for testing
cd quarkus-mcp-server && mvn package

プロジェクト構成

quarkus-mcp-server-example/
├── quarkus-applications-ms/           # REST API microservice
│   ├── src/main/java/me/amiralles/applications/
│   │   ├── boundary/ApplicationsResource.java    # REST endpoints
│   │   ├── entity/Application.java               # JPA entity
│   │   └── control/ApplicationExceptionMapper.java
│   └── src/main/resources/application.properties
├── quarkus-mcp-server/                # MCP server
│   ├── src/main/java/me/amiralles/mcp/
│   │   ├── McpApplicationsServer.java            # MCP tools definition
│   │   ├── client/ApplicationsClient.java        # REST client
│   │   └── model/Application.java                # Data models
│   └── src/test/java/
└── deployment/docker-compose/         # Monitoring stack

🔗 参考資料

• Model Context Protocol (MCP)
• Quarkus Framework
• Quarkus MCP Extension
• Goose CLI
• Claude AI

📄 ライセンス

このプロジェクトは、教育目的のサンプルとして提供されています。