Weather Bot Server

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

Python FastAPI Docker MCP

---

🎯 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.

---

✨ 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

Component	What It Does	Where to Access
🖥️ Chat Interface	Where you type and see responses	http://localhost:8501
⚙️ AI Server	The brain that handles your requests	http://localhost:8000
🗄️ Database	Stores your data	http://localhost:7474

---

🛠️ 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:

Service	URL	What It's For
💬 Chat Interface	http://localhost:8501	Talk to the AI
🔧 API Server	http://localhost:8000	Backend server
📊 API Docs	http://localhost:8000/docs	Interactive API documentation
🗄️ Database Browser	http://localhost:7474	View stored data visually

🔐 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

---