# Open-Meteo AI Assistant using Model Context Protocol (MCP)

## Overview

The **Open-Meteo AI Assistant** is a production-style Python project demonstrating how to build an **AI application using the Model Context Protocol (MCP)**.

Unlike a traditional CRUD application, this project exposes weather capabilities through an **MCP Server** while an **AI-powered MCP Client** discovers available tools, lets an LLM decide which tool to invoke, executes the selected tool, and transforms structured responses into natural language.

The project also demonstrates **Server-Initiated LLM Sampling**, where the MCP server requests the connected AI client to generate content while executing a tool.

---

# Architecture

```text
                              User
                                │
                                ▼
                      OpenAI Responses API
                                │
                                ▼
                  assistant/ai_client.py
                     (AI Assistant / MCP Client)
                                │
                                ▼
                     MCP Protocol (stdio)
                                │
                                ▼
                  Open-Meteo MCP Server
                          (main.py)
                                │
            ┌───────────────────┼────────────────────┐
            │                   │                    │
            ▼                   ▼                    ▼
      get_weather       compare_weather     generate_packing_advice
                                                    │
                                                    ▼
                                          weather_client.py
                                                    │
                                                    ▼
                                            Open-Meteo REST API
                                                    │
                                                    ▼
                                      Live weather / forecast data
                                                    │
                                                    ▼
                                   Server-Initiated LLM Sampling
                                                    │
                                                    ▼
                                     assistant/ai_client.py
                                      (sampling callback)
                                                    │
                                                    ▼
                                               OpenAI Model
```

---

# Project Structure

```text
open-meteo-mcp/
│
├── assistant/
│   ├── client.py
│   ├── ai_client.py
│   └── test_llm.py
│
├── tests/
│
├── main.py
├── weather_client.py
├── weather_models.py
├── errors.py
│
├── .env.example
├── .gitignore
├── pyproject.toml
├── uv.lock
└── README.md
```

---

# Features

The MCP server currently exposes the following tools:

| Tool | Description |
|------|-------------|
| `search_city` | Search for a city |
| `get_weather` | Retrieve current weather |
| `get_weather_forecast` | Retrieve multi-day weather forecast |
| `compare_weather` | Compare weather between two cities |
| `find_warmest_day` | Find the warmest forecast day |
| `get_packing_context` | Return forecast data for packing recommendations |
| `generate_packing_advice` | Demonstrates Server-Initiated LLM Sampling |

---

# Technologies

- Python 3.14
- Model Context Protocol (MCP)
- OpenAI Responses API
- Open-Meteo REST API
- httpx
- Pydantic
- pytest
- uv

---

# Installation

Clone the repository:

```bash
git clone <repository-url>
cd open-meteo-mcp
```

Install dependencies:

```bash
uv sync
```

Activate the virtual environment:

```bash
source .venv/bin/activate
```

Create a `.env` file:

```text
OPENAI_API_KEY=your-api-key
OPENAI_MODEL=gpt-4.1-mini
```

---

# Running the Project

## Start the MCP Inspector

```bash
uv run mcp dev main.py
```

The Inspector allows you to:

- Discover available MCP tools
- Execute tools manually
- Inspect schemas
- Debug tool responses

---

## Run the AI Assistant

```bash
uv run python assistant/ai_client.py
```

Example:

```text
You:
Compare the weather in Tunis and Munich

Assistant:
Tunis is currently warmer than Munich by 7.5°C.
```

Example:

```text
You:
What should I pack for three days in Rome?

Assistant:
For your three-day trip to Rome...
```

---

# Application Workflow

## Standard MCP Tool Calling

```text
User
    │
    ▼
OpenAI selects an MCP tool
    │
    ▼
MCP Client
    │
    ▼
MCP Server
    │
    ▼
Open-Meteo API
    │
    ▼
Structured response
    │
    ▼
OpenAI generates the final answer
```

---

# Server-Initiated LLM Sampling

This project includes an educational implementation of **Server-Initiated LLM Sampling**.

Instead of the AI client generating all responses itself, the MCP server can request the connected client to invoke an LLM while executing a tool.

Workflow:

```text
User
    │
    ▼
OpenAI selects generate_packing_advice
    │
    ▼
MCP Client
    │
    ▼
MCP Server
    │
    ▼
Open-Meteo API
    │
    ▼
Forecast retrieved
    │
    ▼
ctx.session.create_message(...)
    │
    ▼
Sampling Callback
    │
    ▼
OpenAI generates packing advice
    │
    ▼
Result returned to the MCP Server
    │
    ▼
Final response returned to the user
```

> **Note:** Server-Initiated LLM Sampling is deprecated in the MCP 2026-07-28 specification. It is included here for educational purposes to demonstrate advanced MCP capabilities.

---

# Example Queries

```text
What's the weather in Paris?

Compare the weather between Tunis and Munich.

Find the warmest day in Rome this week.

What should I pack for five days in Rome?
```

---

# Running Tests

Run the complete test suite:

```bash
uv run pytest -v
```

Compile all Python files:

```bash
uv run python -m py_compile \
main.py \
weather_client.py \
weather_models.py \
errors.py \
assistant/client.py \
assistant/ai_client.py
```

---

# Learning Outcomes

This project demonstrates:

- Building an MCP Server
- Building an MCP Client
- MCP Tool Discovery
- MCP Tool Execution
- OpenAI Tool Calling
- OpenAI Responses API
- Server-Initiated LLM Sampling
- Async Python
- REST API Integration
- Pydantic Validation
- Error Handling
- Modular Software Architecture
- Separation of Concerns

---

# Future Improvements

Possible enhancements include:

- Air Quality API
- Weather Alerts
- Historical Weather
- Docker Support
- GitHub Actions CI/CD
- Structured Logging
- Response Caching
- GitHub MCP Server
- Gitea MCP Server
- PostgreSQL MCP Server
- Filesystem MCP Server

---

# License

This project is intended for educational and portfolio purposes.