mcp-server-project by ylcn91 - MCP Server

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

Environment Variables

Variable	Description	Default
`SPRING_PROFILES_ACTIVE`	Active profile (`stdio` or `http`)	`stdio`
`SPRING_DATASOURCE_URL`	PostgreSQL connection URL	`jdbc:postgresql://localhost:5432/mcpserver`
`SPRING_DATASOURCE_USERNAME`	Database username	`mcpserver`
`SPRING_DATASOURCE_PASSWORD`	Database password	`mcpserver`
`SPRING_DATA_REDIS_HOST`	Redis host	`localhost`
`SPRING_DATA_REDIS_PORT`	Redis port	`6379`

Profile-Specific Configurations

STDIO Profile (`application-stdio.yml`)

✅ Console output: Completely disabled
✅ Logging: File-only (logs/mcp-server-stdio.log)
✅ Banner: Disabled
✅ Web server: Disabled (NONE mode)

HTTP Profile (`application-http.yml`)

✅ REST endpoints: Enabled on port 8080
✅ Health checks: /actuator/health
✅ Metrics: /actuator/metrics

🐳 Docker Deployment

Complete Stack with Docker Compose

# Build and start everything
docker-compose up -d

# Check services
docker-compose ps

# View logs
docker-compose logs -f mcp-server-http

STDIO Mode in Docker

# Start STDIO service
docker-compose --profile stdio up -d mcp-server-stdio

# Follow logs
docker-compose logs -f mcp-server-stdio

🧪 Testing

This section provides instructions for testing the server locally using the MCP Inspector or Claude Desktop.

1. Local Database Setup

This project requires a running PostgreSQL database. Before running the application, you must configure your database credentials in the src/main/resources/application.yml file.

Open src/main/resources/application.yml and update the following spring.datasource properties to match your local PostgreSQL setup:

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/mcpserver
    username: your_postgres_username
    password: your_postgres_password

Note: Ensure a database named mcpserver exists and that the user has full permissions on it.

If you encounter a Flyway checksum mismatch error upon first run, it means a migration file has changed after it was first applied. You can fix this by running the Flyway repair command with Maven:

mvn flyway:repair

2. Running with MCP Inspector

Once your database is set up, you can connect the server to the MCP Inspector.

Launch MCP Inspector:
```
npx mcp-inspector
```
Configure the Server Entry:
- Transport Type: STDIO
- Command: java
- Arguments: Copy and paste the following line, making sure to replace /path/to/your/project with the absolute path to the mcp-server-project directory on your machine.
```
-Dspring.profiles.active=stdio -jar /path/to/your/project/target/mcp-server-1.0.0.jar
```
For example, if your project is at /Users/yalcindoksanbir/mcp-server-project, the arguments would be:
```
-Dspring.profiles.active=stdio -jar /Users/yalcindoksanbir/mcp-server-project/target/mcp-server-1.0.0.jar
```
Click "Connect". The server will start, and you can begin calling tools.

3. Running with Claude Desktop

To use this MCP server with Claude Desktop, you need to create a configuration file and register the server within Claude Desktop.

Create MCP Configuration File: Create a file named mcp-config.json with the following content:

{
  "mcpServers": {
    "mcp-doksanbir": {
      "command": "/bin/bash",
      "args": [
        "/path/to/your/project/run-mcp-silent.sh"
      ]
    }
  }
}

Replace /path/to/your/project with the absolute path to your project directory.

Configure Claude Desktop:
- Open Claude Desktop
- Go to Settings → Developer
- Under "MCP Configuration File", click "Choose File" and select your mcp-config.json
- Restart Claude Desktop
Testing with Claude:
- Start a new conversation with Claude
- Claude will now have access to the recipe, POI, and weather tools
- Try queries like:
  - "Find me Italian recipes"
  - "What points of interest are near latitude 40.7128, longitude -74.0060?"
  - "What's the weather like at latitude 51.5074, longitude -0.1278?"
Examples of Claude Interactions:

Claude searching for recipes

Claude finding points of interest

Claude retrieving weather information

Claude displaying available tools

4. Example Tool Responses

Here are some examples of successful tool calls and their responses.

`getSupportedPoiTypes`

Response:

[
  "restaurant",
  "cafe",
  "hotel",
  "hospital",
  "pharmacy",
  "bank",
  "atm",
  "gas_station",
  "parking",
  "park",
  "museum",
  "school",
  "university",
  "shopping_mall",
  "supermarket",
  "cinema",
  "theater",
  "gym",
  "library",
  "police",
  "post_office",
  "place_of_worship",
  "tourist_attraction",
  "bar",
  "nightclub",
  "pub",
  "fast_food",
  "bus_station",
  "train_station",
  "subway_entrance",
  "airport",
  "taxi"
]

🚀 Advanced Configuration

Silent Mode for Claude Desktop

For optimal performance with Claude Desktop, the server can be run in silent mode with all logging disabled. This prevents any log output from interfering with the JSON-RPC communication.

Use the provided run-mcp-silent.sh script: This script disables all logging and configures the server for clean JSON-RPC communication.

MCP Configuration File for Silent Mode:

{
  "mcpServers": {
    "mcp-doksanbir": {
      "command": "/bin/bash",
      "args": [
        "/path/to/your/project/run-mcp-silent.sh"
      ]
    }
  }
}

Script Configuration: The run-mcp-silent.sh script uses the following JVM arguments to disable all logging:

-Dspring.profiles.active=stdio
-Dspring.main.banner-mode=off
-Dlogging.level.root=OFF
-Dlogging.level.org=OFF
-Dlogging.pattern.console=
-Dspring.jpa.show-sql=false
-Dhibernate.show_sql=false
-Dorg.hibernate.SQL=false

This ensures a clean communication channel between Claude Desktop and the MCP server.

📊 Monitoring & Management

Health Checks

When running in HTTP mode, the server exposes health endpoints at /actuator/health.

# Check overall health
curl http://localhost:8080/actuator/health

# Check specific components
curl http://localhost:8080/actuator/health/db
curl http://localhost:8080/actuator/health/redis

Managing Data

The server uses Flyway for database migrations. To reset the database:

# Clean and migrate
mvn flyway:clean flyway:migrate

🔒 Security Considerations

The server is designed for local use or in a secure internal network
No authentication is implemented in the basic version
For production deployment, consider adding:
- API authentication
- Rate limiting
- Input validation
- Data sanitization

For more information on Docker deployment security, see the .

🤝 Contributing

Contributions are welcome! Please follow these steps:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

ylcn91/mcp-server-project

MCP Server - Spring AI

✨ Features

🎯 Quick Start

Prerequisites

1. Clone and Build

2. Start Dependencies with Docker

3. Run the MCP Server

🛠️ Available Tools

1. getRecipe

2. getRecentRecipes

3. findPoi

4. getSupportedPoiTypes

5. getWeather

6. isWeatherAvailable

7. getWeatherDataAttribution

🏗️ Architecture

🔧 Configuration

Environment Variables

Profile-Specific Configurations

STDIO Profile (application-stdio.yml)

HTTP Profile (application-http.yml)

🐳 Docker Deployment

Complete Stack with Docker Compose

STDIO Mode in Docker

🧪 Testing

1. Local Database Setup

2. Running with MCP Inspector

3. Running with Claude Desktop

4. Example Tool Responses

getSupportedPoiTypes

🚀 Advanced Configuration

Silent Mode for Claude Desktop

📊 Monitoring & Management

Health Checks

Managing Data

🔒 Security Considerations

🤝 Contributing

STDIO Profile (`application-stdio.yml`)

HTTP Profile (`application-http.yml`)

`getSupportedPoiTypes`