MCP Server - Spring AI

Provides three tools for AI assistants: recipe search, points of interest (POI) lookup, and weather information.

✨ Features

• 🍳 Recipe Search: Find recipes from a curated database with 90+ diverse recipes
• 📍 POI Discovery: Locate nearby points of interest using real OpenStreetMap Overpass API
• 🌤️ Weather Queries: Get current weather information from real Open-Meteo API
• 🔄 Multiple Transports: Supports STDIO (MCP Inspector/Claude Desktop) and HTTP modes
• 🏗️ Hexagonal Architecture: Clean, maintainable code following ports & adapters pattern
• ⚡ High Performance: Redis caching, connection pooling, and optimized queries
• 🐳 Docker Ready: Complete containerization with Docker Compose
• 📊 Observability: Health checks, metrics, and comprehensive logging

🎯 Quick Start

Prerequisites

• Java 21 (OpenJDK or Oracle JDK)
• Maven 3.9+
• Docker & Docker Compose (recommended)
• PostgreSQL 15+ (if running without Docker)
• Redis 7+ (if running without Docker)

1. Clone and Build

git clone <repository-url>
cd mcp-server-project
mvn clean package -DskipTests

2. Start Dependencies with Docker

# Start PostgreSQL and Redis
docker-compose up -d postgres redis

# Wait for services to be ready
docker-compose ps

3. Run the MCP Server

For detailed instructions on running the server with a local database and connecting via MCP Inspector, please see the 🧪 Testing section below.

🛠️ Available Tools

1. getRecipe

Searches for recipes from a database of 90+ diverse recipes.

Parameters:

• query (required): Search term for recipes
• maxResults (optional): Maximum results to return (default: 10, max: 50)

Example Queries:

• "turkish" → Turkish cuisine (Döner, Baklava, Hummus, etc.)
• "dessert" → Sweet treats (Chocolate Cake, Tiramisu, etc.)
• "vegan" → Plant-based recipes
• "comfort" → Comfort food (Mac & Cheese, Pot Pie, etc.)

2. getRecentRecipes

Retrieves recently searched recipes from the database.

Parameters:

• limit (optional): Maximum number of recent recipes (default: 10, max: 20)

3. findPoi

Finds points of interest using real OpenStreetMap data.

Parameters:

• lat (required): Latitude (-90 to 90)
• lon (required): Longitude (-180 to 180)
• radiusMeters (optional): Search radius (default: 1000, max: 50000)
• poiType (optional): Filter by type

Supported POI Types: restaurant, cafe, hospital, school, bank, hotel, museum, police, supermarket, fuel, parking, and more.

4. getSupportedPoiTypes

Returns all supported POI types for searching.

5. getWeather

Retrieves current weather using real Open-Meteo API.

Parameters:

• lat (required): Latitude
• lon (required): Longitude

6. isWeatherAvailable

Checks if weather data is available for a location.

Parameters:

• lat (required): Latitude
• lon (required): Longitude

7. getWeatherDataAttribution

Returns the attribution text for the weather data source.

🏗️ Architecture

src/main/java/com/doksanbir/mcpserver/
├── domain/                 # Core business logic
│   ├── entity/            # JPA entities (Recipe)
│   └── valueobject/       # Value objects (RecipeInfo, WeatherInfo, etc.)
├── application/           # Application layer
│   ├── port/
│   │   ├── input/         # Use case interfaces
│   │   └── output/        # Repository & API interfaces
│   └── usecase/           # Use case implementations
├── infrastructure/        # External integrations
│   ├── persistence/       # Database implementations
│   ├── external/          # REAL API clients (Overpass, OpenMeteo)
│   └── cache/             # Redis + In-memory caching
├── adapter/               # Adapters layer
│   └── mcp/tool/          # MCP tools (@Tool annotations)
└── config/                # Spring configuration

🔧 Configuration

Environ

... View full README on GitHub