Developing a Spring AI Enhanced Restaurant Booking System Employing an API-first Approach

API ファーストのアプローチによる Spring AI 拡張レストラン予約システムの開発

このマルチモジュールプロジェクトには、ResOs API の OpenAPI 派生仕様から生成されたクライアントコードと Spring AI の実装が含まれています。 また、MCP サーバー、Claude で使用するための MCP クライアント設定、ReactJS を利用したスタンドアロンのチャットボット UI も含まれています。

• 背景
• はじめに
• 前提条件
• 方法
  • クローン
  • ビルド
  • 利用
  • 実行
• ドキュメント
  • アーキテクチャ - 包括的なアーキテクチャドキュメント
  • 計画 - ロードマップと今後の作業
  • プロジェクトの起源 - このプロジェクトの始まり
• 関連項目
  • ResOS API - 外部 API リファレンス

背景

Spring Boot と Spring AI の開発者として、アプリケーションに機能を手軽に追加できるライブラリを利用したいと考えています。

ユースケース：

• OpenTable や Tock を利用する代わりに、チャットボットと会話してレストランを検索し、予約を代行してもらえると想像してみてください。

テクノロジー

• Spring Boot 4.0.1
• Spring AI 2.0.0-M1
• Spring Cloud 2025.1.0
• Spring Security 7.0.2
• Java 25
• Maven 3.9.11

はじめに

以下を用意してください。

• Github アカウント
• （任意）ResOS のAPI キー
  • レストラン経営者として登録する場合にのみ必要です！
  • Spring Boot Starter Data JDBC で実装された、API 互換のバックエンドを起動します。
• LLM プロバイダー
  • 例：Groq Cloud、OpenRouter、OpenAI

前提条件

• Git CLI（2.43.0 以降）
• Github CLI（2.65.0 以降）
• httpie CLI（3.2.2 以降）
• Java SDK（25 以降）
• Maven（3.9.11 以降）
• LLM プロバイダーのアカウント（パブリッククラウドまたは商用ホスト型モデルを使用する場合）

クローン

Git CLI を使用する場合

git clone https://github.com/pacphi/spring-ai-resos

Github CLI を使用する場合

gh repo clone pacphi/spring-ai-resos

ビルド

ターミナルを開き、次を実行します。

cd spring-ai-resos
mvn clean install

利用

スターターを依存関係として独自のプロジェクトに組み込みたい場合は、次のようにします。

依存関係の追加

Maven

<dependency>
    <groupId>me.pacphi</groupId>
    <artifactId>spring-ai-resos-client</artifactId>
    <version>{release-version}</version>
</dependency>

Gradle

implementation 'me.pacphi:spring-ai-resos-client:{release-version}'

上記の {release-version} を、有効なアーティファクトのリリースバージョン番号に置き換えてください。

設定の追加

Spring Boot の規約に従い、次のファイルに以下のような設定を追加します。

application.properties

default.url=${RESOS_API_ENDPOINT:https://api.resos.com/v1}

application.yml

default:
  url: ${RESOS_API_ENDPOINT:https://api.resos.com/v1}

クライアントを有効にするには、API キー（必要な場合）を指定し、関連するその他の設定を調整してください。

追加可能な別の dependencies と configuration については、chatbot モジュールの設定を参照してください。

設定は、application.yml ファイル内の spring.config.activate.on-profile でラベル付けされたセクションにあります。

実行

レストラン経営者で、有効な API キーを使って ResOS v1.2 API と連携する場合を除き、まずバックエンドモジュールを起動する必要があります。

バックエンドを起動するには、ターミナルを開いて次を実行します。

cd backend
mvn clean spring-boot:run -Dspring-boot.run.profiles=dev -Dspring-boot.run.jvmArguments="--add-opens java.base/java.net=ALL-UNNAMED"

chatbot モジュールがあります。

また、MCP クライアント設定を通じて Claude デスクトップと連携し、MCP サーバーの実装を利用する方法もあります。

Claude Desktop の場合

Claude Desktop は STDIO トランスポートを使用して MCP サーバーに接続できます。これにより、Claude はレストラン管理ツールを直接呼び出せます。

前提条件

1. MCP サーバーの STDIO 版を取得します。
   • オプション A：Releases からダウンロード - Releases ページから spring-ai-resos-mcp-server-stdio-{VERSION}.jar をダウンロードします。
   • オプション B：ソースからビルド - cd mcp-server && mvn clean package -Pstdio を実行します。
2. バックエンドが実行中であることを確認します（ローカル開発を使用する場合）。

cd backend
mvn spring-boot:run -Dspring-boot.run.profiles=dev -Dspring-boot.run.jvmArguments="--add-opens java.base/java.net=ALL-UNNAMED"

設定

Claude Desktop の設定ファイルに以下を追加します。

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json
• Linux：~/.config/claude/claude_desktop_config.json

ダウンロードしたリリース JAR を使用する場合：

{
  "mcpServers": {
    "spring-ai-resos": {
      "command": "java",
      "args": [
        "-Dspring.profiles.active=stdio",
        "-jar",
        "<path-to-jar>/spring-ai-resos-mcp-server-stdio-{VERSION}.jar"
      ],
      "env": {
        "RESOS_API_ENDPOINT": "http://localhost:8080/api/v1/resos"
      }
    }
  }
}

ソースからビルドした場合：

{
  "mcpServers": {
    "spring-ai-resos": {
      "command": "java",
      "args": [
        "-Dspring.profiles.active=stdio",
        "-jar",
        "<path-to-project>/mcp-server/target/spring-ai-resos-mcp-server-1.0.0-SNAPSHOT.jar"
      ],
      "env": {
        "RESOS_API_ENDPOINT": "http://localhost:8080/api/v1/resos"
      }
    }
  }
}

<path-to-jar> または <path-to-project> を、JAR ファイルまたはプロジェクトディレクトリの絶対パスに置き換えてください。

利用可能なツール

接続すると、Claude Desktop から以下のツールを利用できます。

ツール	説明
getTables	レストランのすべてのテーブルを取得します
getCustomers	フィルタリング／ページネーションを指定して顧客レコードを取得します
getCustomerById	指定した顧客を取得します
getFeedback	顧客のフィードバックとレビューを取得します
getFeedbackById	指定したフィードバックを取得します
getOpeningHours	今後 2 週間の営業時間を取得します
getOpeningHoursById	指定した営業時間を取得します

検証

1. 設定を更新した後、Claude Desktop を再起動します。
2. Claude のインターフェースでツールアイコン（ハンマー）を探します。
3. 利用可能なツールとともに「spring-ai-resos」が表示されていることを確認します。
4. 「すべての顧客を表示して」や「利用可能なテーブルは？」と尋ねてみます。

トラブルシューティング

サーバーに接続できない場合：

• JAR のパスが絶対パスで、正しいことを確認します。
• Java 25 以降がインストールされ、PATH に設定されていることを確認します。
• バックエンドサーバーがポート 8080 で実行中であることを確認します。

ツールが表示されない場合：

• 設定 JSON の構文が有効であることを確認します。
• Claude Desktop のログでエラーを確認します。
• Claude Desktop を完全に再起動します（チャットだけでなくアプリ全体を再起動してください）。

バックエンド接続エラーの場合：

• RESOS_API_ENDPOINT 環境変数が正しいことを確認します。
• 設定した URL でバックエンドにアクセスできることを確認します。

チャットボットの場合

以下の手順に従ってください。

サーバー モジュールを起動するには、ターミナルを開いて次のコマンドを実行します。

cd mcp-server
export RESOS_API_ENDPOINT=http://localhost:8080/api/v1/resos
mvn spring-boot:run -Dspring-boot.run.profiles=cloud,dev

次に、チャットボットが LLM サービスプロバイダーとやり取りできるように、API キーを認証情報ファイルに保存します。

cd ../mcp-client

OpenAI を利用する

OpenAI で使用できるチャットボットのバージョンをビルドして実行します。API キーを取得する必要があります。

アプリを起動する前に：

• src フォルダーと同じ階層に config フォルダーを作成します。そのフォルダー内に creds.yml という名前のファイルを作成し、自分の API キーを追加します。

spring:
  ai:
    openai:
      api-key: { REDACTED }

上記の {REDACTED} を OpenAI API キーに置き換えてください。

次に、チャットボットを起動するには、ターミナルを開いて次のコマンドを実行します。

mvn spring-boot:run -Dspring-boot.run.profiles=openai,dev

Groq Cloud の活用

Groq Cloud で使用できるチャットボットのバージョンをビルドして実行します。API キーを取得する必要があります。 Groq は現在、テキスト埋め込みをサポートしていません。そのため、groq-cloud Spring プロファイルを有効にして実行する場合は、追加の認証情報も用意する必要があります。

アプリを起動する前に：

• src フォルダーと同じ階層に config フォルダーを作成します。そのフォルダー内に creds.yml というファイルを作成し、自分の API キーを追加します。

spring:
  ai:
    openai:
      api-key: { REDACTED-1 }
      embedding:
        api-key: { REDACTED-2 }

上記の {REDACTED-1} と {REDACTED-2} を、それぞれ Groq Cloud API キーと OpenAI キーに置き換えてください。

次に、チャットボットを起動するには、ターミナルシェルを開いて次のコマンドを実行します。

mvn spring-boot:run -Dspring-boot.run.profiles=groq-cloud,dev

OpenRouter の活用

OpenRouter で使用できるチャットボットのバージョンをビルドして実行します。API キーを取得する必要があります。 OpenRouter は現在、テキスト埋め込みをサポートしていません。そのため、openrouter Spring プロファイルを有効にして実行する場合は、追加の認証情報も用意する必要があります。

アプリを起動する前に：

• src フォルダーと同じ階層に config フォルダーを作成します。そのフォルダー内に creds.yml というファイルを作成し、自分の API キーを追加します。

spring:
  ai:
    openai:
      api-key: { REDACTED-1 }
      embedding:
        api-key: { REDACTED-2 }

上記の {REDACTED-1} と {REDACTED-2} を、それぞれ OpenRouter API キーと OpenAI キーに置き換えてください。

次に、チャットボットを起動するには、ターミナルシェルを開いて次のコマンドを実行します。

mvn spring-boot:run -Dspring-boot.run.profiles=openrouter,dev

続いて、お好みのウェブブラウザーで http://localhost:8081 にアクセスします。