Xerkan10/MCP-Server-VELA

Marina MCP Chatbot

A comprehensive chatbot application for marina information and services built using the Model Context Protocol (MCP). This chatbot provides real-time access to marina data including weather, WiFi access, slip availability, emergency contacts, and more.

🚤 Features

The Marina MCP Chatbot includes the following tools:

Core Marina Tools

• 🌤️ Weather Information - Get current weather and forecasts for marina locations
• 📶 WiFi Access - Retrieve WiFi passwords and network information for marinas
• 🏖️ Marina Information - Access basic marina details, operating hours, and amenities
• 🌊 Tide Information - Get tide schedules and water level data for marina locations

Additional Important Tools

• 🚤 Slip Availability - Check boat slip availability and make reservations
• 🚨 Emergency Contacts - Access emergency services, security, and safety contacts
• ⛽ Fuel Prices - Get current fuel prices and station information
• 🔧 Dock Services - Information about available maintenance and repair services

🏗️ Project Structure

MCP-Server-VELA/
├── mcp_server/           # MCP Server implementation
│   ├── main.py          # Server entry point
│   ├── server.py        # Core server logic
│   ├── database.py      # MongoDB connection and operations
│   ├── config.py        # Configuration management
│   └── tools/           # Individual tool implementations
│       ├── base.py      # Base tool class
│       ├── weather.py   # Weather information tool
│       ├── wifi_access.py # WiFi access tool
│       ├── marina_info.py # Marina information tool
│       ├── tide_information.py # Tide information tool
│       ├── slip_availability.py # Slip availability tool
│       ├── emergency_contacts.py # Emergency contacts tool
│       ├── fuel_prices.py # Fuel prices tool
│       └── dock_services.py # Dock services tool
├── mcp-client/          # MCP Client for testing
│   └── test_client.py  # Test client implementation
├── mcp-host/            # MCP Host for chatbot integration
│   └── host.py         # Host implementation
├── examples/            # Example implementations
│   ├── simple_chatbot.py # Simple chatbot example
│   └── populate_mongodb.py # MongoDB population script
├── docs/               # Documentation
│   ├── API_REFERENCE.md # Detailed API documentation
│   ├── QUICK_START.md  # Quick start guide
│   └── MONGODB_SCHEMA.md # MongoDB schema documentation
├── requirements.txt     # Python dependencies
├── pyproject.toml      # Project configuration
├── env.example         # Environment variables template
└── README.md           # This file

🚀 Quick Start

Prerequisites

• Python 3.8 or higher
• MongoDB instance (local or cloud)
• OpenWeatherMap API key (for weather data)
• NOAA API access (for tide data)

Installation

1. Clone the repository:

   git clone <repository-url>
   cd MCP-Server-VELA
   

2. Create and activate virtual environment:

   python3 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Set up environment variables:

   cp env.example .env
   # Edit .env with your actual values
   

5. Set up MongoDB:

   • Ensure MongoDB is running
   • The database name is included in your MONGODB_URI (default: marina_db)
   • Optionally run the population script for sample data:

     python examples/populate_mongodb.py
     

6. Start the MCP server:

   python -m mcp_server.main
   

⚙️ Configuration

Environment Variables

Create a .env file with the following variables:

# Weather API Configuration
WEATHER_API_KEY=your_openweathermap_api_key_here
WEATHER_BASE_URL=https://api.openweathermap.org/data/2.5

# MongoDB Configuration - Single URI approach
MONGODB_URI=mongodb://localhost:27017/marina_db

# Tide API Configuration (optional)
TIDE_API_KEY=your_tide_api_key_here
TIDE_BASE_URL=https://api.tidesandcurrents.noaa.gov/api/prod/datagetter

# MCP Server Configuration
MCP_SERVER_HOST=localhost
MCP_SERVER_PORT=8000
MCP_SERVER_LOG_LEVEL=INFO

# Logging Configuration
LOG_LEVEL=INFO
LOG_FILE=marina_mcp.log

MongoDB Schema

The application uses a single marinas collection with embedded documents:

• marinas - Complete marina information including:
  • Basic marina details and contact information
  • WiFi networks and passwords
  • Slip availability and reservations
  • Emergency contacts
  • Fuel prices
  • Dock services
  • Tide information

All data is embedded within each marina document, eliminating the need for joins and following MongoDB best practices.

See docs/MONGODB_SCHEMA.md for detailed schema information.

🧪 Testing

Test Client

Use the included test client to verify tool functionality:

python -m mcp_client.test_client

Simple Chatbot

Run the example chatbot:

python examples/simple_chatbot.py

🔧 Development

Adding New Tools

1. Create a new tool class in mcp_server/tools/
2. Inherit from BaseMarinaTool
3. Implement required properties and methods
4. Register the tool in mcp_server/main.py

Database Operations

All database operations are centralized in mcp_server/database.py. Add new methods as needed for additional functionality.

📚 Documentation

• API Reference: docs/API_REFERENCE.md - Detailed tool documentation
• Quick Start: docs/QUICK_START.md - Step-by-step setup guide
• MongoDB Schema: docs/MONGODB_SCHEMA.md - Database structure and examples

🤝 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 - see the LICENSE file for details.

🆘 Support

For issues and questions:

1. Check the documentation
2. Review existing issues
3. Create a new issue with detailed information

🚀 Next Steps

• Add authentication and authorization
• Implement real-time notifications
• Add support for multiple languages
• Create web-based admin interface
• Add analytics and reporting
• Implement backup and recovery procedures