cafaray/historical-places-mcp-client

Historical Places MCP Client

A comprehensive Go-based MCP (Model Context Protocol) client for the Historical Places service. This client implements the MCP specification and provides both MCP server functionality and HTTP API endpoints for interacting with the historical places service.

Features

• MCP Protocol Implementation: Full MCP 2024-11-05 specification support
• Dual Mode Operation: Run as MCP server or HTTP API server
• Multi-Source Integration: Connects to historical places service with Google Maps, Mapbox, and OSM data
• Robust Error Handling: Graceful degradation and comprehensive error reporting
• Cloud-Ready: Optimized for both local development and cloud deployment
• Structured Logging: JSON-formatted logs with configurable levels
• Health Checks: Built-in health and readiness endpoints
• Docker Support: Multi-stage builds for efficient containerization

Architecture

Components

• MCP Server: Implements MCP protocol for AI model integration
• HTTP Client: Communicates with the historical places service
• Places Service: Business logic and validation layer
• HTTP Handlers: REST API endpoints for direct HTTP access
• Models: Shared data structures and response formats

Design Patterns

• Clean Architecture: Separation of concerns with clear boundaries
• Dependency Injection: Loosely coupled components
• Interface-Based Design: Testable and maintainable code
• Error Wrapping: Contextual error information

API Endpoints

MCP Protocol

The client implements the following MCP methods:

• initialize: Initialize the MCP session
• tools/list: List available tools
• tools/call: Execute tool calls

Available Tools

search_historical_places

Search for historical places near a given location.

Parameters:

• latitude (required): Latitude coordinate (-90 to 90)
• longitude (required): Longitude coordinate (-180 to 180)
• radius (optional): Search radius in meters (500-3000, default: 1000)
• maxResults (optional): Maximum results to return (1-50, default: 10)
• keyword (optional): Search keyword (default: "historical")
• categories (optional): Categories to search for (default: ["historical", "tourist"])

HTTP API Endpoints

When running in HTTP mode:

POST /api/mcp-client/search

• Search for historical places with JSON request body

GET /api/mcp-client/search

• Search with query parameters: latitude, longitude, radius, maxResults

GET /health

• Health check endpoint

GET /ready

• Readiness check endpoint

Prerequisites

• Go 1.22+
• Docker (for containerized deployment)
• Access to Historical Places service
• Google Cloud SDK (for GCP deployment)

Configuration

Environment Variables

# Historical Places service URL
export HISTORICAL_PLACES_BASE_URL=http://localhost:8080

# Log level (debug, info, warn, error)
export LOG_LEVEL=info

Command Line Options

# Run as MCP server (default)
./main -mode=mcp

# Run as HTTP server
./main -mode=http -port=8081

# Set upstream service URL
./main -base-url=http://localhost:8080

# Set log level
./main -log-level=debug

Development

Building Locally

# Download dependencies
go mod download

# Build the application
go build -o main ./cmd/main.go

# Run in MCP mode
./main -mode=mcp

# Run in HTTP mode
./main -mode=http -port=8081

Testing the Client

MCP Mode Testing

# Start MCP server
./main -mode=mcp

# Send MCP requests via stdin (example)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | ./main -mode=mcp

HTTP Mode Testing

# Start HTTP server
./main -mode=http -port=8081

# Health check
curl -X GET http://localhost:8081/health

# Search places
curl -X POST http://localhost:8081/api/mcp-client/search \
  -H "Content-Type: application/json" \
  -d '{
    "latitude": 41.4036,
    "longitude": 2.1744,
    "radius": 3000,
    "maxResults": 10,
    "keyword": "historical"
  }'

Deployment

Local Docker Deployment

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

Features:

• ARM64 Architecture Support: Optimized for M1 Macs
• Dual Mode Support: Deploy as MCP server or HTTP API
• Comprehensive Validations: Docker installation, version format, port validation
• Time Tracking: Monitors build and deployment times
• Container Management: Automatic cleanup and restart policies
• Flexible Configuration: Upstream URL and mode configuration

Usage Examples:

# Build and deploy HTTP server
./deploy-local.sh --build --deploy --version v1.0.0 --mode http

# Deploy MCP server with custom upstream
./deploy-local.sh -bd -v latest -m mcp -u http://host.docker.internal:8080

# Deploy on custom port
./deploy-local.sh -bd -v latest -p 8082 -m http

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: 8081)
• -m, --mode MODE: Run mode: 'mcp' or 'http' (default: http)
• -u, --upstream URL: Upstream service URL (default: http://localhost:8080)
• -h, --help: Show help message

Google Cloud Platform Deployment

The deploy-gcp.sh script enables deployment to Google Cloud Run.

Features:

• Cloud Run Deployment: Targets europe-southwest1 region
• GCR Integration: Pushes to gcr.io repository
• HTTP Mode Only: MCP mode not supported in Cloud Run
• Comprehensive Validations: gcloud auth, project access, required APIs
• Auto-scaling Configuration: 0-10 instances with intelligent scaling
• Environment Variables: Upstream service URL configuration
• Service URL Output: Direct links to deployed service

Usage Examples:

# Build and deploy to GCP
./deploy-gcp.sh --build --deploy --version v1.0.0 --project my-gcp-project --upstream https://my-service.run.app

# Deploy existing image
./deploy-gcp.sh -d -v latest -p my-project -u https://historical-places.run.app

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
• -u, --upstream URL: Upstream service URL (required for deployment)
• -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 configuration via environment
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

MCP Integration

Using with AI Models

The MCP client can be integrated with AI models that support the MCP protocol:

1. Start the MCP server:

   ./main -mode=mcp -base-url=http://your-historical-places-service
   

2. Configure your AI model to use the MCP client as a tool provider

3. Available capabilities:

   • Search historical places by location
   • Get detailed place information
   • Multi-source data aggregation

MCP Protocol Flow

1. Initialize: AI model initializes MCP session
2. List Tools: AI model discovers available tools
3. Call Tools: AI model executes search operations
4. Results: Formatted historical places data returned

Error Handling

• Service Resilience: Graceful handling of upstream service failures
• Input Validation: Comprehensive parameter validation
• Detailed Logging: Structured logs for debugging and monitoring
• Error Propagation: Contextual error information preserved

Performance Considerations

• HTTP Client Pooling: Efficient connection reuse
• Timeout Management: Configurable request timeouts
• Memory Optimization: Efficient data structures
• Concurrent Safety: Thread-safe operations

Contributing

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

Troubleshooting

Build Issues

Unused Import Error

If you encounter an error like "fmt" imported and not used during build:

# Remove unused imports from the code
# The fmt package import should be removed from cmd/main.go if not used

Missing Dependencies

If build fails due to missing dependencies:

# Download all required dependencies
go mod download

# Verify go.mod and go.sum are present
go mod tidy

Runtime Issues

Connection Refused

If the client cannot connect to the historical places service:

1. Verify the upstream service is running
2. Check the base URL configuration:

   # Set correct upstream URL
   export HISTORICAL_PLACES_BASE_URL=http://your-service:8080
   ./main -mode=http
   

Port Already in Use

If HTTP server fails to start due to port conflict:

# Use a different port
./main -mode=http -port=8082

Permission Denied

If you get permission errors:

# Make the binary executable
chmod +x main

Quick Start Commands

# Complete setup and run
go mod download
go build -o main ./cmd/main.go
./main -mode=http -port=8081

# Test the service
curl http://localhost:8081/health

License

This project is licensed under the MIT License.