🌤️ Weather Bot with AI-Powered Research

An intelligent AI assistant that combines real-time weather data, smart web research, and graph database capabilities - all through a simple chat interface.

🎯 What is This?

Weather Bot is a smart AI assistant that can:

• 🌡️ Tell you the weather - Current conditions and forecasts for any city

• 🔍 Research topics - Searches the web and gives you intelligent, grounded answers

• 🗄️ Store data - Saves information in a graph database (Neo4j)

• 💬 Chat naturally - Just ask questions in plain English

Built using the Model Context Protocol (MCP), it demonstrates how AI can seamlessly interact with multiple tools and data sources.

Related MCP server: Neo4j MCP Server

✨ Features at a Glance

🌡️ Weather Information

• Current weather for any city worldwide

• Multi-day weather forecasts

• Temperature, humidity, and detailed conditions

🧠 Intelligent Research

• Automatically searches the web using Firecrawl

• Analyzes content with Ragie (RAG technology)

• Generates smart answers using OpenRouter AI

• All answers are based on real, up-to-date information

🗄️ Data Storage

• Uses Neo4j graph database

• Store and connect information

• Query your data anytime

🎨 Beautiful Interface

• Clean Streamlit chat UI

• No coding required - just chat!

• Works in your web browser

🏗️ How It Works

graph TB
    User[👤 You] -->|Chat| UI[🖥️ Beautiful Chat Interface]
    UI -->|Sends Request| Server[⚙️ AI Brain]
    Server -->|Gets Weather| Weather[🌤️ Weather API]
    Server -->|Searches Web| Web[🔍 Web Scraper]
    Server -->|Analyzes| RAG[📚 Smart Retrieval]
    Server -->|Generates Answer| AI[🤖 AI Model]
    Server -->|Stores Data| DB[(🗄️ Database)]
    
    style UI fill:#4CAF50,stroke:#333,stroke-width:2px,color:#fff
    style Server fill:#2196F3,stroke:#333,stroke-width:2px,color:#fff
    style DB fill:#FF9800,stroke:#333,stroke-width:2px,color:#fff

Three Main Parts

🛠️ Technologies Used

AI & APIs

• 🤖 OpenRouter - Powers the AI responses (supports GPT, Claude, etc.)

• 🔥 Firecrawl - Searches and scrapes the web

• 📚 Ragie - Smart document retrieval (RAG)

• 🌤️ OpenWeatherMap - Real-time weather data

Core Tech

• 🚀 FastMCP - Model Context Protocol framework

• ⚡ FastAPI - High-performance backend

• 🎨 Streamlit - Interactive user interface

• 🗄️ Neo4j - Graph database

Infrastructure

• 🐳 Docker - Easy setup and deployment

• 🐍 Python - Programming language

📦 What You Need

Before starting, you'll need:

Required Software

• ✅ Docker Desktop - Download here

API Keys (All Free to Start!)

You'll need to sign up for these services and get free API keys:

1. 🌤️ OpenWeatherMap - Get free key

2. 🔥 Firecrawl - Get free key

3. 📚 Ragie - Get free key

4. 🤖 OpenRouter - Get key (Pay-as-you-go, very cheap)

💡 Don't worry! All services have free tiers or are very inexpensive to use.

🚀 Quick Start

Step 1: Get the Project

Download or clone this project to your computer.

Step 2: Set Up Your Keys

1. Find the file named .env.example

2. Make a copy and rename it to .env

3. Open .env in any text editor

4. Add your API keys where indicated:

OPENWEATHER_API_KEY=paste_your_key_here
FIRECRAWL_API_KEY=paste_your_key_here
RAGIE_API_KEY=paste_your_key_here
OPENROUTER_API_KEY=paste_your_key_here
NEO4J_PASSWORD=choose_a_strong_password

Step 3: Start Everything

Open your terminal/command prompt in the project folder and run:

docker-compose up

⏳ Wait 1-2 minutes for everything to start...

Step 4: Start Chatting!

Open your web browser and go to:

http://localhost:8501

That's it! 🎉

💬 What Can You Ask?

Weather Questions

• "What's the weather in Paris?"

• "Give me a 5-day forecast for Tokyo"

• "Is it raining in London right now?"

Research Questions

• "What are the latest developments in AI?"

• "Research quantum computing advancements"

• "Tell me about climate change solutions"

Database Commands

• "Store this: Person named Alice, age 30"

• "Show me all the people in the database"

• "Create a connection between Alice and Bob"

💡 Pro Tip: Just ask naturally! The AI will figure out which tool to use.

🎯 The 4 Smart Tools

1️⃣ Current Weather

Tells you what the weather is like right now in any city.

Ask: "What's the weather in New York?"

2️⃣ Weather Forecast

Shows you the weather for the next few days.

Ask: "Give me a 3-day forecast for Paris"

3️⃣ Web Research

This is the smart one! It:

1. Searches the web for information

2. Reads and understands the content

3. Gives you a clear, accurate answer

Ask: "Research the benefits of meditation"

4️⃣ Database Storage

Stores information in a graph database (great for connected data).

Ask: "Store a person named Alice who knows Bob"

📂 Project Files

weather_bot_gg/
├── 🎨 client.py              # Chat interface
├── ⚙️ server.py              # AI brain with all the tools
├── 🐳 docker-compose.yml     # Starts everything together
├── 📄 requirements.txt       # Python packages needed
├── 🔒 .env                   # Your API keys (keep secret!)
└── 📖 README.md              # This guide

🌐 Access Points

Once everything is running, you can access:

🔐 For Neo4j Browser, login with username neo4j and your password from .env

🐛 Common Issues

❌ Port Already in Use

Problem: Another program is using the same port.

Fix: Close other applications or change the port in docker-compose.yml

❌ API Key Errors

Problem: "API key not set" message appears.

Fix:

1. Check your .env file exists

2. Make sure all keys are filled in

3. No extra spaces or quotes around keys

4. Restart Docker: docker-compose restart

❌ Can't Connect to Database

Problem: Neo4j errors or connection refused.

Fix: Wait! Neo4j takes 30-60 seconds to fully start. Check if it's ready:

docker-compose logs neo4j

Look for "Started" message.

❌ Docker Won't Start

Fix: Try a clean restart:

docker-compose down
docker-compose up --build

📊 Viewing Your Database

1. Go to http://localhost:7474

2. Login with:

   • Username: neo4j

   • Password: (what you set in .env)

3. You'll see a visual interface to explore your data!

🧪 Testing

Quick Health Check

Make sure everything works:

1. Chat Interface: Go to http://localhost:8501 - You should see the chat

2. Server: Go to http://localhost:8000/health - Should say "healthy"

3. Database: Go to http://localhost:7474 - Should load the login page

Try These Questions

1. "What's the weather in London?" → Should get actual weather

2. "Research artificial intelligence" → Should search and answer

3. Simple questions work best at first!

💡 Tips & Best Practices

For Best Results

• ✅ Be specific in your questions

• ✅ One question at a time works best

• ✅ Weather: Use city names (not coordinates)

• ✅ Research: Ask clear, focused questions

Cost Management

• 💰 Most API calls cost less than $0.01

• 💰 OpenWeatherMap is free (up to 1000 calls/day)

• 💰 Research tool is the most expensive (uses AI generation)

• 💰 Monitor your usage in each service's dashboard

Performance

• ⚡ Weather queries: ~1 second

• ⚡ Research queries: 10-30 seconds (lots of processing!)

• ⚡ Database queries: ~1 second

🔒 Security Notes

Keep These Private

• ❌ Never share your .env file

• ❌ Never commit API keys to GitHub

• ❌ Change default Neo4j password

• ✅ The .gitignore file protects your .env automatically

🎓 Learn More

About the Technology

• Model Context Protocol: https://modelcontextprotocol.io/

• RAG (Retrieval-Augmented Generation): AI technique for grounded answers

• Neo4j: Graph database for connected information

• Docker: Containerization for easy deployment

Useful Resources

• FastMCP Documentation

• Streamlit Docs

• Neo4j Cypher Guide

🤝 Contributing

Want to improve this project?

1. Fork the repository

2. Make your changes

3. Test everything works

4. Submit a pull request

Ideas for contributions:

• 🎨 Improve the UI design

• 🔧 Add new tools

• 📚 Better documentation

• 🐛 Fix bugs

📝 License

MIT License - Free to use and modify!

🙏 Credits

Built with:

• Model Context Protocol by Anthropic

• FastMCP by Marvin

• All the amazing open-source communities

Special Thanks:

• OpenAI, Anthropic, and the AI community

• Docker and Python communities

• Everyone who contributed to the libraries used

Built with ❤️ using the Model Context Protocol

Combining AI, Real-Time Data, and Smart Research

⭐ Star this repo if you found it useful!

📧 Questions? Open an issue on GitHub

🚀 Happy Chatting!