Spring AI MCP PoC

Spring AI MCP 概念実証

Spring AI フレームワーク、GitHub MCP（Model Context Protocol）サーバー、LLM モデルの連携を実証する概念実証です。

概要

このプロジェクトでは、次の機能を備えた AI 搭載アプリケーションの構築方法を紹介します。

• Spring AI を使用して自然言語のプロンプトを処理する
• MCP（Model Context Protocol）を通じて GitHub と連携する
• OpenAI の GPT モデルを活用して、適切な応答を生成する
• 関数呼び出しを通じて GitHub 固有の機能を提供する

アーキテクチャ

User Request → Spring Boot API → Spring AI → OpenAI LLM
                     ↓
              GitHub MCP Server → GitHub API

機能

• Spring AI との連携：Spring AI フレームワークを活用して LLM とやり取りします
• GitHub MCP のサポート：Model Context Protocol を通じて GitHub に接続します
• 関数呼び出し：ユーザーのプロンプトに基づいて、AI が GitHub の操作を実行できます
• RESTful API：プロンプト処理用のシンプルな REST エンドポイントを提供します
• 設定可能：さまざまな環境に簡単に設定できます
• エラー処理：堅牢なエラー処理とロギングを備えています

前提条件

• Java 17 以上
• Gradle 8.6 以上（または同梱のラッパーを使用）
• OpenAI API キー
• GitHub MCP サーバーが稼働していること（基本機能では省略可能）

セットアップ

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

git clone https://github.com/shesadri/spring_ai_mcp_poc.git
cd spring_ai_mcp_poc

2. 環境変数を設定する

.env ファイルを作成するか、環境変数を設定します。

export OPENAI_API_KEY="your-openai-api-key"
export GITHUB_MCP_SERVER_URL="http://localhost:3000"  # Optional
export GITHUB_TOKEN="your-github-token"  # Optional for enhanced features

3. アプリケーションのプロパティを設定する

src/main/resources/application.yml を編集するか、環境変数を使用します。

spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY:your-openai-api-key-here}
      
app:
  github:
    mcp:
      server:
        url: ${GITHUB_MCP_SERVER_URL:http://localhost:3000}

4. ビルドして実行する

# Build the project
./gradlew build

# Run the application
./gradlew bootRun

# Or run with specific profile
./gradlew bootRun --args='--spring.profiles.active=dev'

# Alternative: Use custom tasks
./gradlew runDev    # Development profile
./gradlew runProd   # Production profile

アプリケーションは http://localhost:8080 で起動します。

使い方

ヘルスチェック

curl http://localhost:8080/api/v1/health

プロンプトを処理する

curl -X POST http://localhost:8080/api/v1/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Tell me about Spring AI framework",
    "enableMcpTools": true
  }'

GitHub 固有のプロンプト

curl -X POST http://localhost:8080/api/v1/prompt \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Show me information about my GitHub repositories",
    "enableMcpTools": true
  }'

利用可能な MCP ツールを取得する

curl http://localhost:8080/api/v1/mcp/tools

API エンドポイント

メソッド	エンドポイント	説明
GET	/api/v1/health	ヘルスチェック
POST	/api/v1/prompt	AI プロンプトを処理
GET	/api/v1/mcp/tools	利用可能な MCP ツールを取得

リクエスト／レスポンス形式

プロンプトリクエスト

{
  "prompt": "Your question or instruction",
  "context": "Optional context",
  "enableMcpTools": true,
  "githubToken": "optional-github-token"
}

プロンプトレスポンス

{
  "response": "AI generated response",
  "mcpData": {
    "repositories": [...],
    "status": "success"
  },
  "usedMcpTools": true,
  "timestamp": "2024-01-01T12:00:00",
  "status": "success",
  "model": "gpt-4"
}

設定

環境変数

• OPENAI_API_KEY：OpenAI API キー（必須）
• GITHUB_MCP_SERVER_URL：GitHub MCP サーバーの URL（省略可能）
• GITHUB_TOKEN：GitHub 個人用アクセストークン（省略可能）
• PORT：サーバーのポート（デフォルト：8080）

アプリケーションのプロパティ

詳細な設定オプションについては application.yml を参照してください。次の項目などを設定できます。

• AI モデルの設定
• サーバーの設定
• CORS の設定
• ログレベル
• 管理エンドポイント

GitHub MCP サーバー

このアプリケーションで GitHub の機能をさらに活用するには、GitHub MCP サーバーが稼働している必要があります。MCP サーバーは次の機能を提供する必要があります。

• リポジトリ情報のエンドポイント
• Issue の管理機能
• プルリクエストの操作
• コード検索機能

MCP サーバーが利用できない場合でもアプリケーションは動作しますが、GitHub との連携は制限されます。

開発

テストの実行

./gradlew test

開発プロファイル

./gradlew runDev
# or
./gradlew bootRun --args='--spring.profiles.active=dev'

本番環境向けのビルド

./gradlew clean build
java -jar build/libs/spring-ai-mcp-poc-1.0.0-SNAPSHOT.jar

Gradle コマンド

# Build project
./gradlew build

# Run application
./gradlew bootRun

# Run tests
./gradlew test

# Clean build
./gradlew clean

# Generate Gradle wrapper (if needed)
gradle wrapper --gradle-version 8.6

# Check dependencies
./gradlew dependencies

# Build info
./gradlew tasks

プロジェクト構成

src/
├── main/
│   ├── java/com/example/springaimcp/
│   │   ├── SpringAiMcpApplication.java     # Main application class
│   │   ├── config/
│   │   │   └── SpringAiConfig.java         # Spring AI configuration
│   │   ├── controller/
│   │   │   └── PromptController.java       # REST API endpoints
│   │   ├── service/
│   │   │   ├── AiMcpService.java          # Main service orchestrating AI and MCP
│   │   │   └── mcp/
│   │   │       └── GitHubMcpClient.java   # GitHub MCP client
│   │   └── model/
│   │       ├── PromptRequest.java         # Request model
│   │       └── PromptResponse.java        # Response model
│   └── resources/
│       ├── application.yml                # Main configuration
│       └── application.properties         # Alternative configuration
└── test/
    └── java/
        └── ... # Test classes

# Gradle files
build.gradle                     # Gradle build script
settings.gradle                  # Gradle settings
gradle/
└── wrapper/
    ├── gradle-wrapper.properties    # Gradle wrapper config
    └── gradle-wrapper.jar          # Gradle wrapper JAR
gradlew                         # Gradle wrapper script (Unix)
gradlew.bat                     # Gradle wrapper script (Windows)

使用技術

• Spring Boot 3.2.5：アプリケーションフレームワーク
• Spring AI 1.0.0-M1：AI 連携フレームワーク
• OpenAI GPT-4：大規模言語モデル
• WebFlux：MCP 通信用のリアクティブ Web クライアント
• Jackson：JSON 処理
• Gradle 8.6：ビルドツール

コントリビューション

1. リポジトリをフォークする
2. 機能ブランチを作成する
3. 変更を加える
4. テストを追加する
5. プルリクエストを送信する

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。

トラブルシューティング

よくある問題

1. OpenAI API キーの問題

   • API キーが有効で、十分なクレジットがあることを確認してください
   • 環境変数が正しく設定されているか確認してください

2. MCP サーバーの接続問題

   • MCP サーバーが起動していることを確認してください
   • サーバー URL の設定を確認してください
   • ネットワーク接続を確認してください

3. GitHub 連携の問題

   • GitHub トークンに適切な権限があることを確認してください
   • MCP サーバーの GitHub 設定を確認してください

4. Gradle の問題

   • ./gradlew --version を使用して Gradle のバージョンを確認してください
   • ./gradlew clean build を実行してクリーンアップと再ビルドを行ってください
   • java -version で Java のバージョンを確認してください

ログ

詳細なエラー情報については、アプリケーションのログを確認してください。

# View logs in development
tail -f logs/spring-ai-mcp-poc.log

# Increase log level for debugging
export LOGGING_LEVEL_COM_EXAMPLE_SPRINGAIMCP=DEBUG

Gradle Wrapper

Gradle wrapper で問題が発生した場合：

# Regenerate wrapper files
gradle wrapper --gradle-version 8.6

# Make gradlew executable on Unix systems
chmod +x gradlew

サポート

問題や質問について：

• このリポジトリに issue を作成してください
• Spring AI のドキュメントを確認してください
• OpenAI API のドキュメントを確認してください
• Gradle のドキュメントを参照してください