historical-places-mcp

cafaray/historical-places-mcp

3.1

If you are the rightful owner of historical-places-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Quarkus-based MCP service for discovering historical places using multiple data sources.

Historical Places MCP

A comprehensive Quarkus-based MCP (Model Context Protocol) service for discovering historical places using multiple data sources including Google Maps, Mapbox, and OpenStreetMap APIs.

Features

  • Multi-Source Data Aggregation: Combines results from Google Maps, Mapbox, and OpenStreetMap
  • Intelligent Deduplication: Removes duplicate places across different sources
  • Distance-Based Sorting: Results sorted by proximity to search location
  • Comprehensive Place Information: Ratings, photos, opening hours, addresses, and more
  • RESTful API: Multiple endpoints for different use cases
  • Built with Quarkus and Kotlin: High performance and low memory footprint
  • Docker Support: Ready for containerized deployment
  • Cloud-Ready: Optimized for Google Cloud Run deployment

Architecture

Services

  • GoogleMapsService: Fetches historical places from Google Maps Places API with detailed information
  • MapboxService: Searches places using Mapbox Geocoding API for additional coverage
  • OSMService: Queries OpenStreetMap via Overpass API for open-source historical data

Clients

  • GoogleMapsClient: REST client for Google Maps Places API (nearby search and place details)
  • MapboxClient: REST client for Mapbox Places API

API Endpoints

Main Search Endpoint

POST /api/historical-places/search

Searches for historical places using all available data sources.

Request Body:

{
  "latitude": 41.4036,
  "longitude": 2.1744,
  "radius": 3000,
  "maxResults": 10,
  "keyword": "historical",
  "categories": ["historical", "tourist"]
}

Response:

{
  "success": true,
  "data": [
    {
      "id": "place_id_123",
      "name": "Sagrada Familia",
      "types": ["tourist_attraction", "place_of_worship"],
      "latitude": 41.4036,
      "longitude": 2.1744,
      "description": "Famous basilica designed by Antoni Gaudí",
      "address": "Carrer de Mallorca, 401, Barcelona",
      "rating": 4.7,
      "photos": [...],
      "openingHours": {...},
      "website": "https://sagradafamilia.org",
      "distance": 150.5,
      "source": "google_maps"
    }
  ],
  "error": null,
  "timestamp": 1763495605041
}

Utility Endpoints

GET /api/historical-places/health

  • Health check endpoint
  • Returns service status

GET /api/historical-places/test

  • Simple test endpoint
  • Returns "Controller is working!"

GET /api/historical-places/search-simple

  • Simple search with query parameters
  • Parameters: lat, lng, radius

Prerequisites

  • Java 17+
  • Docker (for containerized deployment)
  • Google Cloud SDK (for GCP deployment)

Configuration

Environment Variables

# Required
export GOOGLE_MAPS_API_KEY=your_google_maps_api_key

# Optional
export MAPBOX_API_KEY=your_mapbox_api_key

Application Properties

The service is configured via src/main/resources/application.properties:

# Server Configuration
quarkus.http.port=8080
quarkus.http.host=0.0.0.0

# API Configuration
google.maps.api.key=${GOOGLE_MAPS_API_KEY:}
mapbox.api.key=${MAPBOX_API_KEY:}

# REST Client URLs
quarkus.rest-client.google-maps-api.url=https://maps.googleapis.com/maps/api
quarkus.rest-client.mapbox-api.url=https://api.mapbox.com

# JSON Configuration
quarkus.jackson.fail-on-unknown-properties=false
quarkus.jackson.write-dates-as-timestamps=false

Development

Running Locally

# Set environment variables
export GOOGLE_MAPS_API_KEY=your_api_key
export MAPBOX_API_KEY=your_mapbox_key

# Run in development mode
./gradlew quarkusDev

Testing the API

# Health check
curl -X GET http://localhost:8080/api/historical-places/health

# Search near Sagrada Familia
curl -X POST http://localhost:8080/api/historical-places/search \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 41.4036,
    "longitude": 2.1744,
    "radius": 3000,
    "maxResults": 10,
    "keyword": "historical",
    "categories": ["historical", "tourist"]
  }'

Deployment

Local Docker Deployment (M1 Architecture)

The deploy-local.sh script provides comprehensive local deployment with Docker support for M1 Macs.

Features:

  • M1 Architecture Support: Uses --platform linux/arm64
  • Comprehensive Validations: Docker installation, daemon status, version format, port range
  • Time Tracking: Monitors build and deployment times
  • Container Management: Automatic cleanup and restart policies
  • Environment Variables: Automatic injection of API keys
  • Health Checks: Built-in service verification

Usage Examples:

# Build and deploy locally
./deploy-local.sh --build --deploy --version v1.0.0

# Deploy on custom port
./deploy-local.sh -bd -v latest -p 9090

# Build only
./deploy-local.sh --build --version v1.2.0

Options:

  • -v, --version VERSION: Docker image version (default: latest)
  • -b, --build: Build the application before deployment
  • -d, --deploy: Deploy the container locally
  • -p, --port PORT: Local port to expose (default: 8080)
  • -h, --help: Show help message

Google Cloud Platform Deployment

The deploy-gcp.sh script enables seamless deployment to Google Cloud Run with GCR integration.

Features:

  • Cloud Run Deployment: Targets europe-southwest1 region
  • GCR Integration: Pushes to gcr.io repository
  • Comprehensive Validations: gcloud auth, project access, required APIs
  • Auto-scaling Configuration: 0-10 instances with intelligent scaling
  • Environment Variables: Secure API key injection
  • Service URL Output: Direct links to deployed service
  • Time Tracking: Build, push, and deployment timing

Usage Examples:

# Build and deploy to GCP
./deploy-gcp.sh --build --deploy --version v1.0.0 --project my-gcp-project

# Deploy existing image
./deploy-gcp.sh -d -v latest -p my-project

# Build and push only
./deploy-gcp.sh --build --version v1.1.0 --project my-project

Options:

  • -v, --version VERSION: Docker image version (default: latest)
  • -p, --project PROJECT_ID: GCP Project ID (required)
  • -b, --build: Build and push the image to GCR
  • -d, --deploy: Deploy to Cloud Run
  • -h, --help: Show help message

Prerequisites for GCP Deployment:

  • Authenticated gcloud CLI (gcloud auth login)
  • Valid GCP project with billing enabled
  • Required APIs enabled (automatically handled by script):
    • Cloud Run API
    • Container Registry API

Script Features

Both deployment scripts include:

  1. Comprehensive Validations: Tool availability, authentication, project access
  2. Error Handling: set -euo pipefail for strict error handling
  3. Colored Output: Info, success, warning, and error messages with color coding
  4. Time Tracking: Individual operation and total execution times
  5. Environment Variables: Support for API keys and configuration
  6. Help Documentation: Detailed usage instructions and examples
  7. Flexible Options: Build-only, deploy-only, or combined operations
  8. Best Practices: Following shell scripting standards with proper error handling

Data Sources

Google Maps Places API

  • Coverage: Comprehensive global database
  • Data Quality: High-quality commercial data with ratings, photos, hours
  • Rate Limits: Based on API key quotas
  • Cost: Pay-per-request pricing

Mapbox Places API

  • Coverage: Global coverage with local insights
  • Data Quality: Commercial-grade location data
  • Rate Limits: Based on subscription plan
  • Cost: Tiered pricing model

OpenStreetMap (Overpass API)

  • Coverage: Community-driven global database
  • Data Quality: Variable, excellent for historical sites
  • Rate Limits: Fair use policy
  • Cost: Free and open source

Response Format

All API responses follow the MCPResponse format:

{
  "success": boolean,
  "data": T | null,
  "error": string | null,
  "timestamp": number
}

Error Handling

  • Service Resilience: Individual service failures don't break the entire request
  • Graceful Degradation: Returns results from available services
  • Detailed Logging: Comprehensive error tracking and debugging information
  • Input Validation: Radius limits (500-3000m) and parameter validation

Performance Considerations

  • Concurrent API Calls: Services called in parallel for optimal performance
  • Result Deduplication: Intelligent matching across data sources
  • Distance Calculation: Haversine formula for accurate distance sorting
  • Memory Optimization: Efficient data structures and garbage collection
  • Caching: Consider implementing Redis for production deployments

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

License

This project is licensed under the MIT License.

To move:

Local Deployment Script (deploy-local.sh) M1 Architecture Support: Uses --platform linux/arm64

Parameters: Version, build/deploy flags, custom port

Validations: Docker installation, daemon status, version format, port range

Timing: Tracks build and deployment times

Features: Container management, environment variables, health checks

Usage Examples:

Build and deploy locally

./deploy-local.sh --build --deploy --version v1.0.0

Deploy on custom port

./deploy-local.sh -bd -v latest -p 9090

Copy bash GCP Deployment Script (deploy-gcp.sh) Cloud Run Deployment: Targets europe-southwest1 region

GCR Integration: Pushes to gcr.io repository

Parameters: Version, project ID, build/deploy flags

Validations: gcloud auth, project access, required APIs, environment variables

Timing: Tracks build, push, and deployment times

Features: Auto-scaling, environment variables, service URL output

Usage Examples:

Build and deploy to GCP

./deploy-gcp.sh --build --deploy --version v1.0.0 --project my-gcp-project

Deploy existing image

./deploy-gcp.sh -d -v latest -p my-project

Copy bash Key Features: Comprehensive Validations: Tool availability, authentication, project access

Error Handling: set -euo pipefail for strict error handling

Colored Output: Info, success, warning, and error messages

Time Tracking: Individual and total execution times

Environment Variables: Support for API keys

Help Documentation: Detailed usage instructions

Flexible Options: Build-only, deploy-only, or combined operations

Both scripts follow shell scripting best practices with proper error handling, input validation, and user-friendly output.