Spring AI Explorer

A demonstration project showcasing the integration of Spring AI with OpenAI (GPT-5 Mini) and MCP (Model Context Protocol). This project implements a chat assistant with tool calling capabilities (weather) and external context integration via Google Calendar.

🚀 Features

• OpenAI Integration: Powered by GPT-5 Mini and Text Embedding 3 Large.
• Tool Calling: Custom tools defined using @Tool (e.g., getWeather).
• MCP Client: Integrated Model Context Protocol client for Google Calendar.
• RESTful API: Simple interface for AI interaction.
• System Prompting: Hardcoded personality and instructions for more relevant responses.

📋 Prerequisites

• Java 25 (required for latest language features).
• Maven 3.x.
• OpenAI API Key.

🛠️ Configuration & Setup

Environment Variables

Local development requires a .env file (or system environment variables) with your OpenAI key:

SPRING_AI_OPENAI_API_KEY=your_openai_api_key_here

application.properties

Key configurations located in src/main/resources/application.properties:

• spring.ai.openai.chat.model: gpt-5-mini
• spring.ai.openai.chat.temperature: 0.7
• spring.ai.openai.embedding.model: text-embedding-3-large
• MCP Config: classpath:mcp-google.calendar.json

🏗️ Build & Run

Maven Commands

# Build the project
./mvnw clean install

# Run the application
./mvnw spring-boot:run

# Run tests
./mvnw test

🔌 API Usage

Chat Endpoint

The application exposes a single REST endpoint to interact with the AI assistant.

Request:

• URL: POST /api/chat
• Body: JSON

{
  "question": "What is the weather like in New York?"
}

Example (cURL):

curl -X POST http://localhost:8080/api/chat \
     -H "Content-Type: application/json" \
     -d '{"question": "Hello, can you help me with coding?"}'

🏛️ Architecture

The request flow follows a standard Spring Boot pattern:

POST /api/chat → AssitantController → AssistantService → ChatClient (Spring AI) → OpenAI API

Key Components

• AssitantController: Manages the HTTP entry points.
• AssistantService: Configures the ChatClient with system prompts and wires available tools.
• AssistantTools: Defines capabilities that the AI can call (e.g., getWeather).
• MCP Client: Connects to the Google Calendar MCP server for context-aware responses.

🛠️ MCP Integration

This project uses the spring-ai-starter-mcp-client to interact with external context providers. The configuration for the Google Calendar MCP server is stored in: src/main/resources/static/mcp-google.calendar.json

---

Note

This project is currently in active development, utilizing Spring Boot 4.0.x and Spring AI Milestone releases.