🌤️ 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.

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

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:

   pip install -r requirements.txt
   

2. Test MCP Server via CLI:

   python client.py "Berlin"
   

3. Launch Web Application:

   streamlit run app.py