Agentic MCP Weather System

# Agentic MCP Weather Intelligence System 🌤️🤖 A comprehensive **Agentic Model Context Protocol (MCP)** system that provides intelligent weather services through orchestrated multi-agent architecture. Built for scalable agentic applications with **full Docker support** and **Streamlit Web UI** for easy deployment and interaction. ## 🌟 Key Features ### 🌐 **Web Interface** - **Streamlit Chat UI**: ChatGPT-like interface at `http://localhost:8501` - **Real-time Interactions**: Direct communication with weather agents - **Visual Dashboard**: System health monitoring and agent status - **Mobile Responsive**: Works on desktop, tablet, and mobile devices ### 🤖 **Multi-Agent Coordination** - **Smart Alert Agent**: Proactive weather monitoring and personalized alerts - **Weather Intelligence Agent**: Multi-source data aggregation and analysis - **Travel Agent**: Location-based weather planning and recommendations - **Agent Coordination Hub**: Centralized orchestration of all weather agents ### 🐳 **Docker-First Architecture** - **Complete Containerization**: Weather server + Ollama LLM + Streamlit UI + Setup automation - **Multi-Service Orchestration**: Production-ready microservices architecture - **Production Ready**: Optimized Dockerfile with security best practices and health checks - **One-Command Deployment**: Full system startup with `./start-docker.sh` ### 🔧 **Modular Architecture** - **Server Registry**: Automatic discovery and management of MCP servers - **Agent Orchestrator**: Intelligent workflow coordination with local LLM - **Multi-Agent Support**: Extensible framework for specialized weather agents - **Health Monitoring**: Real-time status tracking with comprehensive health endpoints - **API-First Design**: RESTful APIs with interactive documentation at `/docs` ### 🤖 **Advanced Agentic Capabilities** - **Natural Language Processing**: Understand complex weather queries through LLM integration - **Intelligent Task Routing**: Automatically delegate queries to specialized agents - **Multi-Location Coordination**: Compare and analyze weather across multiple cities simultaneously - **Proactive Alert System**: Smart monitoring with personalized notifications and thresholds - **Local LLM Integration**: Ollama-powered reasoning and decision making - **Context-Aware Responses**: Maintain conversation history and learning ### 🌐 **Comprehensive Weather Services** - **Real-Time Weather**: Current conditions for any city worldwide via multiple APIs - **Advanced Forecasting**: Detailed predictions using National Weather Service API - **Smart Alert System**: Weather warnings, emergency notifications, and custom thresholds - **Multi-Source Intelligence**: Data fusion from weather.gov, wttr.in, and additional sources - **Travel Planning**: Location-based weather analysis for trip planning and recommendations ## 🏗️ **System Architecture** ``` ┌─────────────────────────────────────────────────────────────────────────────┐ │ Docker Network: weather-mcp-network │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────┐ │ │ │ Streamlit UI │ │ Weather MCP │ │ Ollama LLM │ │ Setup │ │ │ │ :8501 │ │ Server :8000 │ │ Server :11434 │ │ Agent │ │ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ ┌─────────────┐ │ │ (Init) │ │ │ │ │ Chat UI │ │ │ │ MCP API │ │ │ │ Models: │ │ │ ┌─────┐ │ │ │ │ │ Dashboard │◄┼──┼─┤ Health │◄┼──┼─┤ - llama3 │ │ │ │Auto │ │ │ │ │ │ Monitoring│ │ │ │ Agent Hub │ │ │ │ - phi3 │ │ │ │Setup│ │ │ │ │ └─────────────┘ │ │ └─────────────┘ │ │ └─────────────┘ │ │ └─────┘ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────┘ │ │ │ │ │ │ │ └───────────┼─────────────────────┼─────────────────────┼──────────────┼──────┘ │ │ │ │ │ │ │ │ ┌───────────▼─────────────────────▼─────────────────────▼──────────────▼──────┐ │ Host System │ │ 🌐 http://localhost:8501 (Streamlit Chat Interface) │ │ 🔧 http://localhost:8000 (Weather API + Agent Coordination) │ │ 🤖 http://localhost:11434 (Ollama LLM Engine) │ │ 📚 http://localhost:8000/docs (Interactive API Documentation) │ └───────────────────────────────────────────────────────────────────────────────┘ ``` ### **Agent Coordination Flow** ``` User Query ─► Streamlit UI ─► Agent Coordination Hub ─► Specialized Agents │ │ │ │ │ ┌─────────────┐ │ └──────────────┤Smart Alert │ │ │Agent │ │ ┌───────┤Weather Intel│ │ │ │Travel Agent │ │ │ └─────────────┘ │ │ │ │ ▼ ▼ │ Ollama LLM ──► API Results │ │ │ └──────────── Response ◄───────┴──────────────┘ ``` ## ⚡ **TL;DR - Get Started in 3 Commands** ```bash git clone <your-repo-url> && cd weather chmod +x *.sh && ./start-docker.sh # ✅ Chat Interface: http://localhost:8501 # ✅ API Server: http://localhost:8000 # ✅ System ready with Streamlit UI! ``` **What you get instantly:** - 🌐 **Streamlit Chat Interface** at `http://localhost:8501` - ChatGPT-like weather assistant - 🔧 **Weather API** at `http://localhost:8000` - Full MCP server with agent coordination - 📚 **API Docs** at `http://localhost:8000/docs` - Interactive OpenAPI documentation - 🤖 **Ollama LLM** at `http://localhost:11434` - Local AI models for intelligent responses ## 📋 **Requirements** - **Docker** (20.10 or higher) with Docker Compose - **8GB+ RAM** (for Ollama LLM models: llama3 + phi3) - **15GB+ disk space** (for container images + models + logs) - **Internet connection** (for weather APIs and initial model downloads) - **Ports available**: 8000 (API), 8501 (Streamlit), 11434 (Ollama) ## 🚀 **Quick Start with Docker** ### Option 1: Complete System with Convenience Scripts (Recommended) ```bash # 1. Clone the repository git clone <your-repo-url> cd weather-mcp-agent # 2. Make scripts executable (Linux/macOS) chmod +x *.sh # 3. Validate your environment (optional but recommended) ./validate-docker.sh # 4. Start the complete system (one command!) ./start-docker.sh # 5. For verbose output and logs ./start-docker.sh --verbose # 6. Stop the system when done ./stop-docker.sh ``` ### Option 1b: Manual Docker Commands ```bash # 1. Clone the repository git clone <your-repo-url> cd weather-mcp-agent # 2. Start the complete system (Weather Server + Ollama + Models) docker-compose up -d # 3. Monitor the startup process docker-compose logs -f # 4. Wait for model downloads (first run only, may take 5-10 minutes) # You'll see: "Models ready!" when everything is set up # 5. Test the system curl http://localhost:8000/health ``` **System will be available at:** - **🌐 Streamlit Chat UI**: http://localhost:8501 (Primary Interface) - **🔧 Weather API**: http://localhost:8000 (REST API + Agent Hub) - **🤖 Ollama LLM**: http://localhost:11434 (AI Models) - **📚 API Documentation**: http://localhost:8000/docs (Interactive Docs) ### Option 2: Development Setup with Demo ```bash # Start system and run demo docker-compose --profile demo up # Or run demo separately after system is up docker-compose up -d docker-compose run weather-demo ``` ### Option 3: Local Development (Non-Docker) ```bash # 1. Install Ollama locally brew install ollama # macOS # or download from https://ollama.ai/download # 2. Start Ollama and pull models ollama serve & ollama pull llama3 ollama pull phi3 # 3. Install Python dependencies pip install -r requirements.txt # 4. Environment configuration is ready! # The .env file is already set up for local development # For production, copy .env.production.template to .env.production and customize # 5. Start the weather server python main.py server ``` ## 🐳 **Docker Management Commands** ### Convenience Scripts (Recommended) ```bash # Development/testing ./start-docker.sh # Default setup ./start-docker.sh --dev # Development mode (live reload) ./start-docker.sh --demo # Include demo client ./start-docker.sh --verbose # Show detailed logs # Production deployment ./start-docker.sh --prod # Production configuration ./start-docker.sh --prod --build # Production with fresh build # Management ./stop-docker.sh # Stop (can restart) ./stop-docker.sh --cleanup # Remove containers ./stop-docker.sh --remove-data # Remove everything including models ``` ### Manual Docker Commands ```bash # Default setup docker-compose up -d # Development mode (with live reload) docker-compose -f docker-compose.yml -f docker-compose.dev.yml up -d # Production mode (optimized settings) docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d # View logs (all services) docker-compose logs -f # View logs (specific service) docker-compose logs -f weather-server docker-compose logs -f ollama # Stop all services docker-compose down # Restart services docker-compose restart # Rebuild and restart (after code changes) docker-compose up -d --build # Pull latest images docker-compose pull ``` ### Environment Configurations | Environment | Features | Use Case | |-------------|----------|----------| | **Default** | Standard settings, API key disabled | Local development & testing | | **Development** | Live reload, debug logging, relaxed security | Active development | | **Production** | Optimized performance, security enabled, resource limits | Production deployment | ### Maintenance Commands ```bash # Check service status docker-compose ps # Access container shell docker-compose exec weather-server bash docker-compose exec ollama bash # View system resources docker-compose top # Clean up (removes containers, networks, volumes) docker-compose down -v --remove-orphans # Remove all unused Docker resources docker system prune -a ``` ### Development Commands ```bash # Run with demo profile docker-compose --profile demo up # Override environment variables ENVIRONMENT=development docker-compose up -d # Run single command in container docker-compose run weather-server python --version docker-compose run weather-server python demo.py # Mount local code for development # (uncomment volume in docker-compose.yml: - .:/app) ``` ## 📚 **Usage Examples** ### 🌐 **Primary: Streamlit Chat Interface** (Recommended) **Open http://localhost:8501 and try these:** ``` 💬 "What's the weather like in San Francisco right now?" 💬 "Set up weather alerts for New York with temperature thresholds" 💬 "Compare weather conditions in London, Paris, and Tokyo" 💬 "Plan my outdoor activities for this weekend in Seattle" 💬 "Any severe weather alerts for California today?" 💬 "What's the best time to travel to Miami this week?" ``` **Features:** - 🤖 **Natural Language Processing**: Just type like you're chatting with ChatGPT - 📊 **Visual Dashboard**: Real-time agent status and system health monitoring - 💾 **Conversation History**: Maintains context across multiple queries - 📱 **Mobile Responsive**: Works perfectly on phones and tablets ### 🔧 **API Testing (Advanced Users)** ```bash # System Health Check curl http://localhost:8000/health # Agent Coordination Status curl http://localhost:8000/info # Direct Weather Query curl -X POST http://localhost:8000/tools/get_weather \ -H "Content-Type: application/json" \ -d '{"city": "San Francisco"}' # Smart Alert Setup via API curl -X POST http://localhost:8000/tools/setup_smart_alerts \ -H "Content-Type: application/json" \ -d '{ "locations": ["New York", "Boston"], "alert_types": ["severe_weather", "temperature_extreme"], "thresholds": {"temperature_high": 85, "temperature_low": 32} }' # Multi-Location Weather Intelligence curl -X POST http://localhost:8000/tools/get_weather_intelligence \ -H "Content-Type: application/json" \ -d '{"locations": ["London", "Paris", "Rome"], "analysis_type": "comparison"}' ``` ### 🐍 **Python Integration** ```python # Direct Agent Usage from agent_coordination_hub import AgentCoordinationHub from smart_alert_agent import AlertAgent # Initialize coordination system hub = AgentCoordinationHub() result = await hub.process_request("Weather in Tokyo with travel recommendations") # Smart alerts with custom thresholds alert_agent = AlertAgent() config = { "locations": ["San Francisco", "Seattle"], "alert_types": ["severe_weather", "temperature_extreme"], "thresholds": {"temperature_high": 80, "temperature_low": 40} } alerts = await alert_agent.setup_smart_alerts(config) ``` ## 🛠️ **Docker Troubleshooting** ### Common Issues and Solutions **Issue: Ollama container fails to start** ```bash # Check if port 11434 is already in use lsof -i :11434 # If occupied, stop the local Ollama service brew services stop ollama # Check container logs docker-compose logs ollama ``` **Issue: Model download fails or times out** ```bash # Manually pull models with more verbose output docker-compose exec ollama ollama pull llama3 docker-compose exec ollama ollama pull phi3 # Check available disk space (models are 4GB+ each) docker system df ``` **Issue: Weather server can't connect to Ollama** ```bash # Check network connectivity docker-compose exec weather-server curl http://ollama:11434/api/version # Verify Ollama health curl http://localhost:11434/api/version # Check container network docker network ls docker network inspect weather-mcp-network ``` **Issue: Out of memory errors** ```bash # Check Docker memory limits docker stats # Increase Docker Desktop memory limit to 8GB+ # Docker Desktop > Settings > Resources > Memory # Monitor container memory usage docker-compose exec weather-server free -h ``` **Issue: Port conflicts** ```bash # Check what's using port 8000 lsof -i :8000 # Use different ports SERVER_PORT=8080 docker-compose up -d # Or modify docker-compose.yml ports section ``` ### Performance Optimization ```bash # Pre-pull all images docker-compose pull # Build with cache optimization DOCKER_BUILDKIT=1 docker-compose build # Limit container resources # Add to docker-compose.yml under services: # weather-server: # deploy: # resources: # limits: # memory: 2g # reservations: # memory: 1g ``` ### Logs and Debugging ```bash # Detailed logging LOG_LEVEL=DEBUG docker-compose up -d # Follow all logs with timestamps docker-compose logs -f -t # Export logs for analysis docker-compose logs > system-logs.txt # Access container filesystems docker-compose exec weather-server ls -la /app/logs/ ``` ## ⚙️ **Environment Configuration** ### Environment Files Overview This project includes a committed `.env` file optimized for local development: | File | Purpose | Committed to Git | |------|---------|------------------| | `.env` | Local development defaults | ✅ Yes | | `.env.example` | Template with all options | ✅ Yes | | `.env.production.template` | Production template | ✅ Yes | | `.env.production` | Your production config | ❌ No (create locally) | | `.env.local` | Personal overrides | ❌ No (ignored) | ### Local Development The `.env` file is **ready to use** with safe defaults: ```bash # Clone and run immediately - no .env setup needed! git clone <your-repo> cd weather-mcp-agent ./start-docker.sh ``` **Local Development Features:** - ✅ `ENVIRONMENT=development` - ✅ Debug logging enabled - ✅ CORS allows localhost origins - ✅ API key requirement disabled - ✅ High rate limits for testing - ✅ Raw data and execution logs included ### Customization Create `.env.local` for personal overrides (ignored by git): ```bash # .env.local - personal overrides LOG_LEVEL=DEBUG OLLAMA_MODEL=phi3 SERVER_PORT=8001 ``` ### Environment Variables Priority 1. **Environment variables** (highest priority) 2. **`.env.local`** (personal overrides) 3. **`.env`** (committed defaults) ## 🚀 **Production Deployment with Docker** ### Step 1: Production Environment Configuration ```bash # 1. Clone to production server git clone <your-repo-url> cd weather-mcp-agent # 2. Create production environment file cp .env.production.template .env.production # 3. Edit production settings (REQUIRED - update all sensitive values) nano .env.production ``` **Key Production Settings:** ```bash ENVIRONMENT=production API_KEY_REQUIRED=true API_KEY=your-secure-production-key ALLOWED_ORIGINS=https://yourdomain.com RATE_LIMIT_PER_MINUTE=60 LOG_LEVEL=INFO ``` ### Step 2: SSL/TLS Configuration (Optional) ```bash # Add SSL certificates to docker-compose.yml mkdir -p ./ssl # Copy your cert.pem and key.pem to ./ssl/ # Update .env.production SSL_CERT_PATH=/app/ssl/cert.pem SSL_KEY_PATH=/app/ssl/key.pem ``` ### Step 3: Production Deployment ```bash # Method 1: Using convenience script (recommended) ./start-docker.sh --build # Method 2: Manual deployment docker-compose -f docker-compose.yml --env-file .env.production up -d # Method 3: With custom configuration docker-compose up -d --build ``` ### Step 4: Production Verification ```bash # Check all services are running docker-compose ps # Verify health endpoints curl https://yourdomain.com:8000/health curl https://yourdomain.com:8000/info # Check logs for any issues docker-compose logs -f --tail=100 # Method 4: Docker with external Ollama docker build -t weather-mcp . docker run -p 8000:8000 --env-file .env --add-host=host.docker.internal:host-gateway weather-mcp ``` ### Production Endpoints: - 🏥 `GET /health` - Comprehensive health check with service validation - ⚡ `GET /health/quick` - Fast health check without external calls - 📊 `GET /info` - Server capabilities and metadata - 🌤️ `POST /tools/get_weather` - Current weather (rate limited) - 📅 `POST /tools/get_forecast` - Weather forecast (validated coordinates) - 🚨 `POST /tools/get_alerts` - Weather alerts (US states only) ### Management Commands: ```bash # Production server management python main.py start # Start production server python main.py status # System health and status python main.py config # View current configuration python main.py validate # Validate configuration # Development/testing (disabled in production) python main.py interactive # Interactive client mode python main.py demo # System demonstration python main.py servers # Server registry info ``` ## 📁 **Project Structure** ``` weather/ ├── 🌐 Web Interface │ └── streamlit_app.py # Streamlit Chat UI (Primary Interface) ├── 🤖 Agent Coordination System │ ├── agent_coordination_hub.py # Central agent coordinator │ ├── smart_alert_agent.py # Proactive weather monitoring agent │ ├── weather_intelligence_agent.py # Multi-source data analysis agent │ └── travel_agent.py # Location-based travel planning agent ├── � Core MCP Server │ ├── main.py # Production entry point & CLI management │ ├── weather.py # Weather MCP server implementation │ ├── config.py # Configuration management │ ├── server_registry.py # Server discovery & health monitoring │ └── health_server.py # Health check endpoints ├── 🚀 Orchestration & Workflows │ ├── simple_orchestrator.py # Basic agentic workflow orchestrator │ └── agent_orchestrator.py # Advanced LangGraph orchestrator ├── 🛠️ Development & Testing │ ├── mcp_client.py # Interactive client for testing │ ├── demo.py # System demonstration scripts │ └── run_server.py # Alternative server startup ├── � Docker & Deployment │ ├── Dockerfile # Production container image │ ├── docker-compose.yml # Multi-service orchestration │ ├── start-docker.sh # Comprehensive startup script │ ├── stop-docker.sh # Clean shutdown script │ └── setup-ollama.sh # Ollama model setup automation ├── 📋 Configuration & Dependencies │ ├── requirements.txt # Python dependencies │ ├── pyproject.toml # Project metadata (v0.2.0) │ ├── .env # Environment variables (Docker-ready) │ └── .env.example # Configuration template └── 📚 Documentation ├── README.md # This comprehensive guide ├── SETUP.md # Quick setup instructions ├── DOCKER.md # Docker-specific documentation ├── DEPLOYMENT.md # Production deployment guide ├── WORKING_SYSTEM_SUMMARY.md # System status & test cases ├── AGENT_COORDINATION_GUIDE.md # Agent development guide └── CONTRIBUTING.md # Contribution guidelines ``` ## 💬 **Interactive Usage Examples** ### 🌐 **Streamlit Chat Interface** (http://localhost:8501) The **primary way** to interact with your weather intelligence system: **🔮 Smart Weather Queries:** ``` 💬 "What's the weather like in London right now?" 🤖 "🌤️ London Weather Update: 🌡️ Temperature: 15°C (feels like 13°C) 🌧️ Conditions: Light drizzle 💨 Wind: 12 mph from the west 📊 Humidity: 78%" 💬 "Set up weather alerts for my commute route" 🤖 "I'll set up smart alerts for your locations. What cities should I monitor?" 💬 "Compare weather in New York, London, and Tokyo" 🤖 "🌍 Multi-City Weather Comparison: 🗽 New York: 22°C, Sunny, Perfect for outdoor activities 🇬🇧 London: 15°C, Overcast, Light jacket recommended 🗾 Tokyo: 28°C, Humid, Stay hydrated!" ``` **� Advanced Features:** - **Conversation Memory**: Maintains context across questions - **Visual Dashboard**: Real-time system health and agent status - **Mobile Responsive**: Perfect interface for phones and tablets - **Multi-Agent Coordination**: Automatic routing to specialized weather agents ### 🛠️ **API Command Examples** (Advanced Users) ```bash # System Status & Health curl http://localhost:8000/health curl http://localhost:8000/info # Agent Coordination curl -X POST http://localhost:8000/agent/coordinate \ -H "Content-Type: application/json" \ -d '{"query": "Weather alerts for California with travel advice"}' ``` ## 🛠️ **API Integration Examples** ### **Direct Server API Calls** ```bash # Get current weather curl -X POST http://localhost:8000/tools/get_weather \ -H "Content-Type: application/json" \ -d '{"city": "London"}' # Get forecast (requires coordinates) curl -X POST http://localhost:8000/tools/get_forecast \ -H "Content-Type: application/json" \ -d '{"latitude": 51.5074, "longitude": -0.1278}' # Get weather alerts (US states only) curl -X POST http://localhost:8000/tools/get_alerts \ -H "Content-Type: application/json" \ -d '{"state": "CA"}' ``` ### **Server Discovery & Health** ```bash # Check server health curl http://localhost:8000/health # Get server capabilities curl http://localhost:8000/info ``` ## 🔧 **Extending the System** ### **Adding New MCP Servers** ```python # Register a new server in server_registry.py from server_registry import registry, MCPServer # Define new server finance_server = MCPServer( name="finance-server", host="localhost", port=8001, description="Financial data and stock information", tools=["get_stock_price", "get_market_news", "analyze_portfolio"], tags=["finance", "stocks", "market"] ) # Register it registry.register_server(finance_server) ``` ### **Custom Task Types** ```python # Extend TaskType enum in simple_orchestrator.py class TaskType(Enum): WEATHER_QUERY = "weather_query" FORECAST_ANALYSIS = "forecast_analysis" ALERT_MONITORING = "alert_monitoring" MULTI_LOCATION = "multi_location" FINANCIAL_ANALYSIS = "financial_analysis" # New! GENERAL_INQUIRY = "general_inquiry" ``` ## 🎯 **Agentic Design Principles** ### **1. Modularity** - Each component has a single, clear responsibility - Easy to extend with new servers and capabilities - Loose coupling between orchestrator and servers ### **2. Intelligent Routing** - Task classification determines workflow path - Location extraction enables multi-location queries - Error handling with graceful fallbacks ### **3. Scalability** - Server registry supports dynamic server addition - Health monitoring for automatic failover - Async operations for concurrent processing ### **4. Observability** - Detailed execution logs for debugging - Performance metrics and timing - Health status monitoring ## 🔮 **Advanced Features (Optional)** ### **LangGraph Integration** For more sophisticated agentic workflows, enable the advanced orchestrator: ```python # Install additional dependencies uv add langgraph langchain-ollama # Use agent_orchestrator.py instead of simple_orchestrator.py from agent_orchestrator import WeatherOrchestrator # Requires Ollama running locally ollama serve ``` ### **Multi-Agent Coordination** The system is designed to support multi-agent scenarios: ```python # Example: Weather + Travel planning agent travel_query = "What's the weather like in my travel destinations this week?" # → Orchestrator coordinates: # 1. Extract travel destinations # 2. Get weather for each location # 3. Get forecasts for travel dates # 4. Provide travel recommendations ``` ## 📊 **Monitoring & Debugging** ### **Health Checks** ```bash # Check all servers 💬 You: servers 📊 Found 1 registered servers: ✅ Online: 1 ❌ Offline: 0 ⚠️ Error: 0 ❓ Unknown: 0 ``` ### **Execution Logs** Every query provides detailed execution tracing: ``` 🔍 Execution Log: 1. Classified task as: weather_query 2. Extracted locations: ['London'] 3. Gathered weather data for 1 locations 4. Generated response ``` ## 🔒 **Production Security** ### Environment Variables Required for production deployment: ```bash # Server Configuration SERVER_HOST=0.0.0.0 SERVER_PORT=8000 ENVIRONMENT=production # Security API_KEY_REQUIRED=true API_KEY=your-secure-api-key-here RATE_LIMIT_PER_MINUTE=100 ALLOWED_ORIGINS=https://yourdomain.com # Logging LOG_LEVEL=INFO LOG_FILE_PATH=/var/log/weather-mcp/server.log ``` ### Security Features - **Input validation** with Pydantic models - **Rate limiting** per endpoint (configurable) - **API key authentication** (optional) - **CORS protection** with configurable origins - **Request size limits** to prevent DoS - **Comprehensive logging** for audit trails - **Error sanitization** to prevent information leakage ## � **Production Monitoring** ### Health Checks ```bash # Quick health check curl http://localhost:8000/health/quick # Comprehensive health check (includes external APIs) curl http://localhost:8000/health # Server info and capabilities curl http://localhost:8000/info ``` ### Logging Production logs are structured and include: - Request/response logging - Error tracking with stack traces - Performance metrics - Security events (rate limiting, auth failures) ```bash # View logs (if using file logging) tail -f /var/log/weather-mcp/server.log # Check log level python main.py config | grep -i log ``` ### Performance Optimization - **Async request handling** with httpx - **Connection pooling** for external APIs - **Request timeout controls** - **Exponential backoff** for API retries - **Response caching** (configurable) - **Resource limits** and rate limiting ## �🚨 **Troubleshooting** ### Common Production Issues: 1. **Server won't start**: Check port availability and environment variables ```bash # Check port usage lsof -ti:8000 # Validate configuration python main.py validate # Check environment python main.py config ``` 2. **Ollama connection issues**: Ensure Ollama is running and accessible ```bash # Check if Ollama is running ollama list # If not running, start Ollama ollama serve # Test connection to Ollama curl http://localhost:11434/api/version # Verify model is available ollama run llama3 "Hello, test message" ``` 2. **High memory usage**: Adjust worker count and connection limits ```bash # Reduce workers in production uvicorn weather:app --workers 2 --max-requests 1000 ``` 3. **API timeouts**: External weather services may be slow ```bash # Check API status curl -w "%{time_total}\n" http://localhost:8000/health ``` 4. **Rate limiting issues**: Adjust limits in environment variables ```bash # In .env file RATE_LIMIT_PER_MINUTE=200 SERVER_TIMEOUT=45.0 ``` ### Log Analysis ```bash # Find errors in logs grep -i error /var/log/weather-mcp/server.log # Check API performance grep "response_time" /var/log/weather-mcp/server.log # Monitor rate limiting grep "rate.*limit" /var/log/weather-mcp/server.log ``` ## 🤝 **Contributing** We welcome contributions! Here's how to get started: 1. **Fork the repository** 2. **Create a feature branch**: `git checkout -b feature/amazing-feature` 3. **Make your changes** 4. **Add tests** for new functionality 5. **Run the test suite**: `uv run main.py test` 6. **Commit your changes**: `git commit -m 'Add amazing feature'` 7. **Push to the branch**: `git push origin feature/amazing-feature` 8. **Open a Pull Request** ### Areas for Contribution: - **New MCP Servers**: Add weather-adjacent services (traffic, events, etc.) - **Enhanced NLP**: Improve location extraction and query understanding - **Advanced Orchestration**: Implement complex multi-step workflows - **Data Sources**: Integrate additional weather APIs and services - **Documentation**: Improve guides and examples - **Production Features**: Add monitoring, caching, and performance improvements - **Security Enhancements**: Additional authentication methods and security hardening ## ✅ **Docker Deployment Checklist** ### Pre-deployment - [ ] Docker Engine 20.10+ installed - [ ] Docker Compose v2.0+ or docker-compose v1.29+ installed - [ ] System has 8GB+ RAM available - [ ] 10GB+ disk space for Ollama models - [ ] Internet connectivity for API access and model downloads ### Environment Setup - [ ] Repository cloned and scripts made executable (`chmod +x *.sh`) - [ ] Environment validated (`./validate-docker.sh`) - [ ] Production environment configured (`.env.production`) - [ ] SSL certificates configured (if using HTTPS) ### Deployment Verification - [ ] All containers started successfully (`docker-compose ps`) - [ ] Health checks passing (`curl localhost:8000/health`) - [ ] Ollama models downloaded (`docker-compose logs ollama-setup`) - [ ] Weather API endpoints responding (`curl localhost:8000/tools/get_weather`) - [ ] Logs show no errors (`docker-compose logs`) ### Production Readiness - [ ] API keys configured and secure - [ ] Rate limiting configured appropriately - [ ] CORS settings configured for your domain - [ ] Monitoring and alerting configured - [ ] Backup strategy for configuration and data - [ ] Resource limits set for containers ## 📄 **License** This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## 🎬 **Demo Scenarios** **🌐 Open http://localhost:8501 and try these intelligent weather workflows:** ### 🏃‍♂️ **Personal Planning** ``` 💬 "Plan my outdoor workout routine for San Francisco this week" 💬 "Should I bring an umbrella to my meeting in Seattle tomorrow?" 💬 "What's the best day for a picnic in Central Park this weekend?" 💬 "When should I schedule my outdoor photography session in London?" ``` ### ✈️ **Travel Intelligence** ``` 💬 "I'm flying from New York to Los Angeles tomorrow - any weather concerns?" 💬 "Compare weather conditions for my business trip: Boston, Chicago, Denver" 💬 "Best time to visit Tokyo this month based on weather patterns?" 💬 "Should I pack winter clothes for my trip to Montreal next week?" ``` ### 🚨 **Smart Monitoring** ``` 💬 "Set up weather alerts for my daily commute from Brooklyn to Manhattan" 💬 "Monitor severe weather for my company's offices in California and Texas" 💬 "Alert me if temperature drops below freezing in Chicago this week" 💬 "Watch for storm systems affecting my weekend camping trip in Yosemite" ``` ### 🏢 **Business Applications** ``` 💬 "Weather impact analysis for our retail stores in Florida, Georgia, and South Carolina" 💬 "Construction weather forecast for our project sites in Denver and Phoenix" 💬 "Event planning weather assessment for outdoor venues this month" ``` **Each query demonstrates:** - 🤖 **Multi-Agent Coordination**: Automatic routing to specialized agents - 🧠 **Context Awareness**: Understanding complex, multi-part requests - 📊 **Intelligent Analysis**: Data fusion from multiple weather sources - 💡 **Proactive Recommendations**: Actionable insights beyond raw data ## 📚 **Dependencies** See `requirements.txt` for the complete list of dependencies. Key packages: - **FastAPI**: REST API framework - **LangChain**: LLM integration (optional for advanced features) - **LangGraph**: Advanced agentic orchestration - **MCP**: Model Context Protocol implementation - **Requests/HTTPX**: HTTP client libraries - **Pydantic**: Data validation ## 🙏 **Acknowledgments** - Built on the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) framework - Weather data from [NWS API](https://www.weather.gov/documentation/services-web-api) and [wttr.in](https://wttr.in/) - Inspired by the agentic AI community ## 📊 **Current System Status** (Updated: October 16, 2025) ### **✅ Live Services** - **🌐 Streamlit Chat Interface**: http://localhost:8501 ✅ **HEALTHY** - **🔧 Weather API + Agent Hub**: http://localhost:8000 ✅ **HEALTHY** - **🤖 Ollama LLM Engine**: http://localhost:11434 ✅ **HEALTHY** - **📚 Interactive API Documentation**: http://localhost:8000/docs ✅ **AVAILABLE** ### **🤖 Active Agents** - **Smart Alert Agent**: ✅ Proactive weather monitoring with custom thresholds - **Weather Intelligence Agent**: ✅ Multi-source data analysis and forecasting - **Travel Agent**: ✅ Location-based planning and recommendations - **Agent Coordination Hub**: ✅ Central orchestration and routing system ### **💡 Try It Now** 1. **Open**: http://localhost:8501 (Streamlit Chat) 2. **Ask**: *"Set up weather alerts for San Francisco with temperature thresholds"* 3. **Watch**: Multi-agent coordination in action! ### **📈 System Health** ```json { "status": "healthy", "services": { "nws_api": "available", "wttr_in": "available", "ollama": "healthy" }, "performance": { "response_time_ms": 2135.61, "memory_usage": "available" }, "environment": "production" } ``` --- **Built with ❤️ for the agentic AI community** | **Extensible • Modular • Production-Ready** **Version 0.2.0** | **Multi-Agent Coordination** | **Docker-Native** | **Streamlit Interface**