# 🌤️ Local Weather & International Time MCP Agent

A high-performance, real-time Weather and International Time Dashboard built on **Model Context Protocol (MCP)** using **Python**, **FastMCP / MCPServer**, **Streamlit**, **Open-Meteo API**, and **TimeAPI.io**.

---

## 🏛️ System Architecture & Workflow

The application leverages a decoupled client-server architecture powered by the **Model Context Protocol (MCP)** over Standard Input/Output (`stdio`) JSON-RPC 2.0 communication.

```mermaid
graph TD
    subgraph UI_Layer["🖥️ Frontend UI Layer (Streamlit)"]
        UI["app.py (Streamlit Web Dashboard)"]
        CSS["Dynamic Glassmorphism Theme Engine"]
        Cache["@st.cache_data (5-Min Caching Layer)"]
    end

    subgraph MCP_Client_Layer["⚡ MCP Client IPC Layer"]
        ClientSession["mcp.Client (Stdio Client Session)"]
        ProcessParams["StdioServerParameters (sys.executable server.py)"]
    end

    subgraph MCP_Server_Layer["🔌 MCP Server Layer (server.py)"]
        MCPServer["mcp.server.MCPServer"]
        ToolWeather["@mcp.tool() weather"]
        ToolTime["@mcp.tool() time_info"]
        ToolGeocode["@mcp.tool() geocode"]
    end

    subgraph Backend_Services["⚙️ External Services & Logic Layer"]
        WeatherEngine["weather.py (Open-Meteo Integration)"]
        TimeEngine["time_service.py (TimeAPI.io & ZoneInfo)"]
    end

    subgraph External_APIs["🌐 External REST APIs"]
        OpenMeteo["Open-Meteo Forecast & Geocoding API"]
        TimeAPI["TimeAPI.io REST API Service"]
    end

    UI --> Cache
    Cache --> ClientSession
    ClientSession -->|JSON-RPC 2.0 via Stdio| ProcessParams
    ProcessParams --> MCPServer
    MCPServer --> ToolWeather
    MCPServer --> ToolTime
    MCPServer --> ToolGeocode

    ToolWeather --> WeatherEngine
    ToolTime --> TimeEngine

    WeatherEngine -->|Async HTTP GET| OpenMeteo
    TimeEngine -->|Async HTTP GET| TimeAPI
```

---

## 🔄 High-Level Sequence Workflow

```mermaid
sequenceDiagram
    autonumber
    actor User
    participant Dashboard as Streamlit UI (app.py)
    participant Client as MCP Client Session
    participant Server as MCP Server (server.py)
    participant ExternalAPIs as External REST APIs (Open-Meteo & TimeAPI)

    User->>Dashboard: Search City (e.g. "Berlin")
    Dashboard->>Client: Request Weather & International Time
    Client->>Server: Call MCP Tools (weather & time_info)
    Server->>ExternalAPIs: Fetch Live Weather & Time Data
    ExternalAPIs-->>Server: Return Data Payloads
    Server-->>Client: Return Structured MCP Tool Response
    Client-->>Dashboard: Deliver Formatted Weather & Time Data
    Dashboard-->>User: Render Dynamic Glassmorphic UI Dashboard
```

---

## 📁 File Significance & Responsibilities

| File | Type | Significance & Responsibility |
| :--- | :--- | :--- |
| **[`app.py`](file:///c:/Users/Aditya%20Verma/OneDrive/Desktop/My%20Work/Weather_App_MCP/app.py)** | Streamlit Frontend Application | Main web interface. Implements the dynamic glassmorphism design system using native `st.html()`, interactive Plotly 24-hour forecast trends, 7-day extended daily forecast cards, sidebar quick-search city pills, metric/imperial unit toggles, sub-50ms data caching layer (`@st.cache_data`), and an interactive MCP Protocol Inspector. |
| **[`server.py`](file:///c:/Users/Aditya%20Verma/OneDrive/Desktop/My%20Work/Weather_App_MCP/server.py)** | MCP Server Entrypoint | Exposes model tools over Model Context Protocol (`MCPServer`) stdio IPC transport. Registers `@mcp.tool()` endpoints: `weather`, `time_info`, and `geocode`. |
| **[`weather.py`](file:///c:/Users/Aditya%20Verma/OneDrive/Desktop/My%20Work/Weather_App_MCP/weather.py)** | Weather Processing Engine | Handles asynchronous HTTP GET requests to Open-Meteo REST APIs. Maps WMO weather codes to emojis and categories, converts wind direction degrees to cardinal directions (`N/NE/E/SE/S/SW/W/NW`), handles unit conversions (`°C` vs `°F`, `km/h` vs `mph`), and returns structured current, 24-hour hourly, and 7-day daily forecasts. |
| **[`time_service.py`](file:///c:/Users/Aditya%20Verma/OneDrive/Desktop/My%20Work/Weather_App_MCP/time_service.py)** | International Time Service | Manages international time and date resolution. Queries the TimeAPI.io REST API and features a native `zoneinfo` standard library fallback for zero-downtime date/time calculation, UTC offsets (`UTC+02:00`), timezone abbreviations (`CEST`), and DST status. |
| **[`client.py`](file:///c:/Users/Aditya%20Verma/OneDrive/Desktop/My%20Work/Weather_App_MCP/client.py)** | CLI Testing & Verification | Independent command-line client script that demonstrates full MCP stdio client initialization, protocol handshaking, tool listing, and execution testing via command line arguments. |
| **[`requirements.txt`](file:///c:/Users/Aditya%20Verma/OneDrive/Desktop/My%20Work/Weather_App_MCP/requirements.txt)** | Package Manifest | Declares project dependencies: `mcp>=1.0.0`, `httpx>=0.27.0`, `streamlit>=1.35.0`, `plotly>=5.20.0`, and `pandas>=2.0.0`. |

---

## ✨ Key Features & Capabilities

1. **Dual MCP Tool Pipeline**: Seamlessly orchestrates multiple MCP tools (`weather` + `time_info` + `geocode`) over JSON-RPC 2.0 standard.
2. **Glassmorphism Aesthetic UI**: Custom dynamic background gradients that respond live to weather conditions (Clear Day, Clear Night, Rain, Storm, Cloud, Snow, Fog).
3. **International Date & Time Comparison**: Bottom-right hero badge displaying live formatted date, 12-hour clock time, timezone abbreviation, and UTC offset for instant side-by-side global comparison.
4. **Interactive 24-Hour Plotly Forecast Chart**: Interactive splined temperature curve combined with rain probability bar charts.
5. **7-Day Extended Daily Forecast**: Card grid displaying daily high/low temperatures, weather icons, and rain accumulation totals.
6. **Unit Switching**: Toggle between Metric (`°C`, `km/h`, `mm`) and Imperial (`°F`, `mph`, `in`).
7. **10-Minute Response Caching**: Fast `@st.cache_data(ttl=300)` caching for instant sub-50ms repeat searches.
8. **Interactive MCP Protocol Inspector**: Expanded debug tab showing protocol architecture flow, tool schemas, query latency breakdown, and raw structured JSON responses.

---

## 🚀 How to Run

1. **Install Dependencies**:
   ```bash
   pip install -r requirements.txt
   ```

2. **Test MCP Server via CLI**:
   ```bash
   python client.py "Berlin"
   ```

3. **Launch Web Application**:
   ```bash
   streamlit run app.py
   ```