# 🌤️ NWS Weather MCP Server & Agentic Client

A fully functional **Model Context Protocol (MCP) server and custom LLM client** that enables dynamic, real-time weather querying through the **National Weather Service (NWS) API**.

This project demonstrates an end-to-end **AI agentic workflow using the ReAct pattern**, where an LLM dynamically discovers available tools, determines the required parameters, executes tool calls through an MCP server, retrieves live weather data, and synthesizes the results into a natural-language response.

---

## ✨ Key Features

* **Model Context Protocol (MCP):** Implements the MCP server/client architecture for tool discovery and standardized communication over `stdio`.
* **Dynamic Tool Discovery:** The client discovers available MCP tools at runtime rather than relying on hardcoded tool definitions.
* **Zero-Shot Tool Calling:** Dynamically translates MCP Pydantic schemas into Gemini `FunctionDeclaration` objects, allowing the LLM to understand and invoke available tools.
* **National Weather Service Integration:** Retrieves real-time weather alerts and forecast information from the NWS API.
* **Dynamic Coordinate Resolution:** Weather information is retrieved based on dynamically determined geographic coordinates.
* **Decoupled Architecture:** Separates the tool execution environment from the LLM reasoning engine.
* **Pydantic Validation:** Uses Pydantic models to validate structured weather data returned by the MCP server.
* **Agentic Reasoning Loop:** Demonstrates how an LLM can determine when additional contextual information or tool execution is required before generating a final response.

---

## 🏗️ Architecture

```text
                         ┌─────────────────────┐
                         │        User         │
                         │ Natural Language    │
                         │      Request       │
                         └──────────┬──────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │    Gemini Client    │
                         │   LLM Reasoning     │
                         │    / ReAct Loop     │
                         └──────────┬──────────┘
                                    │
                         MCP Tool Discovery
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │     MCP Client      │
                         │ Tool Schema Mapping │
                         └──────────┬──────────┘
                                    │
                             JSON-RPC / stdio
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │     MCP Server      │
                         │   Weather Tools     │
                         └──────────┬──────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │   NWS Weather API   │
                         │  Live Weather Data  │
                         └──────────┬──────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │ Structured Weather  │
                         │       Data          │
                         └──────────┬──────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │       Gemini        │
                         │ Response Synthesis  │
                         └──────────┬──────────┘
                                    │
                                    ▼
                         ┌─────────────────────┐
                         │   Natural Language  │
                         │      Response       │
                         └─────────────────────┘
```

---

## 🧠 How It Works

The application follows an agentic workflow where the LLM can dynamically discover and execute tools provided by the MCP server.

### 1. Tool Discovery

The Gemini client starts the weather MCP server and requests the tools exposed by the server.

Available tools include:

* `get_alerts`
* `get_forecast`

The MCP client receives the tool definitions and their associated schemas.

### 2. Schema Translation

The MCP tool schemas are dynamically converted into Gemini-compatible `FunctionDeclaration` objects.

This allows Gemini to understand:

* What tools are available
* What each tool does
* What parameters each tool expects
* What information needs to be supplied for execution

### 3. Agentic Reasoning

The user provides a natural-language weather request.

Gemini analyzes the request and determines whether a tool needs to be called.

For example:

```text
User:
What's the weather forecast for my location?

        ↓

Gemini determines:
I need geographic coordinates to retrieve the forecast.

        ↓

MCP Tool Call:
get_forecast(latitude, longitude)

        ↓

NWS API:
Returns forecast information.

        ↓

Gemini:
Synthesizes the weather data into a natural-language response.
```

### 4. Tool Execution

The MCP server receives the requested tool call and executes the corresponding Python function.

The weather tool communicates with the National Weather Service API and retrieves the required information.

### 5. Data Validation

The returned data is validated using Pydantic models before being passed back to the client.

This provides a structured and predictable interface between the external API and the LLM.

### 6. Response Synthesis

Gemini receives the tool output and uses the retrieved information to generate a conversational response for the user.

---

## 🛠️ Tech Stack

| Technology                       | Purpose                                             |
| -------------------------------- | --------------------------------------------------- |
| **Python 3.11**                  | Application development                             |
| **MCP SDK**                      | Model Context Protocol server/client implementation |
| **Gemini**                       | LLM reasoning and tool calling                      |
| **google-genai**                 | Gemini API integration                              |
| **httpx**                        | HTTP communication with the NWS API                 |
| **Pydantic**                     | Data validation and structured models               |
| **asyncio**                      | Asynchronous execution                              |
| **uv**                           | Python package and environment management           |
| **National Weather Service API** | Live weather data                                   |

---

## 📁 Project Structure

```text
weather-mcp-server/
│
├── weather.py
│   └── MCP weather server
│
├── client_gemini.py
│   └── Gemini-powered MCP client and agentic reasoning loop
│
├── pyproject.toml
│   └── Project configuration and dependencies
│
├── uv.lock
│   └── Locked dependency versions
│
└── README.md
    └── Project documentation
```

---

## 🚀 Getting Started

### Prerequisites

Make sure you have the following installed:

* **Python 3.11+**
* **uv package manager**
* A valid **Google Gemini API key**

---

### 1. Clone the Repository

```bash
git clone https://github.com/ShriniTechie/weather-mcp-server.git
cd weather-mcp-server
```

---

### 2. Install Dependencies

Initialize the environment and install the project dependencies using `uv`:

```bash
uv sync
```

---

### 3. Configure the Gemini API Key

Set your Gemini API key as an environment variable.

#### Windows PowerShell

```powershell
$env:GEMINI_API_KEY="your_actual_api_key_here"
```

#### Linux / macOS

```bash
export GEMINI_API_KEY="your_actual_api_key_here"
```

> ⚠️ **Security:** Never commit your API key to GitHub. Use environment variables or another secure secrets-management approach.

---

### 4. Run the Agentic Client

Start the integrated Gemini client:

```bash
uv run client_gemini.py
```

The client will:

1. Start the MCP weather server.
2. Establish communication with the server.
3. Discover the available MCP tools.
4. Convert MCP schemas into Gemini function declarations.
5. Send the available tools to Gemini.
6. Process the user's request.
7. Execute the required weather tools.
8. Retrieve live data from the NWS API.
9. Return the tool results to Gemini.
10. Generate the final natural-language response.

---

## 🔄 Agentic Execution Flow

```text
User Request
     │
     ▼
Gemini LLM
     │
     │ Determines required tool
     ▼
MCP Client
     │
     │ Sends tool request
     ▼
MCP Server
     │
     │ Executes Python function
     ▼
NWS API
     │
     │ Returns weather data
     ▼
MCP Server
     │
     │ Validates response
     ▼
MCP Client
     │
     │ Returns tool result
     ▼
Gemini LLM
     │
     │ Synthesizes response
     ▼
Final Answer
```

---

## 🔧 MCP Tools

### `get_alerts`

Retrieves active weather alerts from the National Weather Service.

The tool can be used by the LLM when the user asks about active weather warnings or alerts.

---

### `get_forecast`

Retrieves forecast information from the National Weather Service based on geographic coordinates.

The tool provides forecast information that can then be interpreted and summarized by Gemini.

---

## 💡 Example Interaction

```text
User:
What is the weather forecast for the requested location?

Agent:
I need to retrieve the forecast information.

MCP:
get_forecast(latitude=<latitude>, longitude=<longitude>)

NWS:
Returns structured forecast information.

Gemini:
The forecast is retrieved and synthesized into a
natural-language response for the user.
```

The important aspect of this workflow is that the LLM is not simply generating an answer from its existing knowledge. It can **discover and invoke external tools to retrieve live information** before producing the final response.

---

## 🎯 Project Goals

This project was built to demonstrate practical concepts around:

* Model Context Protocol (MCP)
* LLM tool calling
* Agentic AI workflows
* ReAct-style reasoning
* Dynamic tool discovery
* Function calling
* API integration
* Structured data validation
* Python asynchronous programming
* Separation of reasoning and tool execution
* LLM integration with external services

---

## 🔍 Key Takeaways

This project demonstrates how an LLM application can be structured into separate components:

**Reasoning Layer**

Gemini is responsible for understanding the user's request, determining what information is required, and deciding which tools to invoke.

**Tool Layer**

The MCP server exposes weather-related capabilities through standardized tools.

**Data Layer**

The National Weather Service API provides live weather information.

**Validation Layer**

Pydantic provides structured validation of returned data.

This separation makes the architecture easier to understand, extend, and maintain.

---

## 🔐 Security

Do not commit secrets or API keys to the repository.

For example, avoid committing:

```text
GEMINI_API_KEY=your_actual_api_key
```

Instead, configure the API key through your environment.

You should also ensure sensitive configuration files are included in `.gitignore`.

Example:

```gitignore
.env
.venv/
__pycache__/
*.pyc
```

---

## 📌 Future Improvements

Potential extensions for this project include:

* Adding additional weather-related MCP tools.
* Supporting more external APIs.
* Adding automated tests for MCP tools.
* Improving error handling and retry logic.
* Adding logging and observability.
* Supporting multiple LLM providers.
* Adding a web-based user interface.
* Extending the agent with additional tool capabilities.

---

## 📚 References

* **Model Context Protocol (MCP)** — Protocol for connecting LLM applications with external tools and data sources.
* **National Weather Service API** — Provides weather forecasts and alerts.
* **Google Gemini API** — Provides LLM capabilities and function/tool calling.
* **uv** — Python package and environment management.

---

## ⭐ Why This Project?

The goal of this project is to demonstrate a practical implementation of an **LLM-powered agent that can discover tools, reason about when to use them, execute external operations, and incorporate live API data into its responses**.

It serves as a hands-on example of combining **Python, MCP, LLM tool calling, APIs, structured data validation, and agentic workflows** into a single application.