# 🌩️ MCP Weather Alerts Tool using FastMCP + Claude Desktop

This project demonstrates how to build an **MCP (Model Context Protocol)** tool using the official [`FastMCP`](https://github.com/modelcontextprotocol/python-sdk) Python SDK. It integrates with **Claude Desktop** to enable an AI assistant to retrieve **weather alerts** by U.S. state via the `api.weather.gov` API.

---

## 🚀 What This Project Does

- ✅ Implements a custom MCP server with `FastMCP`
- 🌐 Uses `httpx` to call real-time weather alerts from [api.weather.gov](https://www.weather.gov/documentation/services-web-api)
- 📦 Returns structured information: event, severity, description, and instructions
- 🧠 Integrates with Claude Desktop
- 🌈 Can be tested interactively via MCP Inspector

---

## 🧱 Tech Stack

| Tool/Library | Purpose |
|--------------|---------|
| `mcp[cli]`   | MCP server toolkit with CLI tools |
| `httpx`      | Async HTTP client |
| `uv`         | Modern Python package/dependency manager |
| Claude Desktop | AI interface for LLM + MCP |
| MCP Inspector | UI to debug MCP endpoints |

---

## 📁 Project Structure

```
mcpcrashcourse/
├── server/
│   └── weather.py         # MCP server logic (get_alerts)
├── pyproject.toml         # Project metadata + dependencies
├── uv.lock                # Locked versions (auto-generated by uv)
└── README.md              # You're reading it!
```

---

## 🧠 Tool Logic: `get_alerts`

```python
@mcp.tool()
async def get_alerts(state: str) -> list[dict]:
    # Fetch weather alerts for a given U.S. state (e.g., 'CA')
    url = "https://api.weather.gov/alerts/active"
    params = {"area": state.upper()}
    async with httpx.AsyncClient() as client:
        response = await client.get(url, params=params)
        data = response.json()

    return [
        {
            "event": alert.get("event"),
            "severity": alert.get("severity"),
            "description": alert.get("description"),
            "instruction": alert.get("instruction"),
        }
        for alert in data.get("features", [])
        if alert.get("properties")
    ]
```

---

## 🛠️ Installation & Setup

### 1. Create & Configure Project

```bash
pipx install uv               # install uv if you haven't
uv init mcpcrashcourse        # start new project
cd mcpcrashcourse
uv add "mcp[cli]" httpx       # add dependencies
```

### 2. Add Your Tool

Place your `weather.py` in the `server/` folder, containing the logic for `get_alerts`.

---

## 🧪 Run & Inspect

### Launch with MCP Inspector

```bash
uv run mcp dev server/weather.py
```

Then open [http://localhost:6757](http://localhost:6757) to:
- View your `get_alerts` tool
- Try calling it with input like `"TX"`

---

## 🤖 Claude Desktop Integration

1. Update your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "<your-project-directory>/server/weather.py"
      ]
    }
  }
}
```

2. Restart Claude Desktop
3. Prompt:  
   > "What are the weather alerts for Texas?"

Claude will call your MCP tool and display structured output.

---

## 💡 What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) standardizes how apps send **context** (data, tools, prompts) to LLMs. It separates the **"context provider"** from the LLM layer.

**Three core primitives:**
| Type     | Use Case              | Analogy           |
|----------|-----------------------|-------------------|
| Tools    | Execute functions     | POST endpoint     |
| Resources| Provide static data   | GET endpoint      |
| Prompts  | Reusable interactions | LLM templates     |

---

## 📎 Credits

- [FastMCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [api.weather.gov](https://www.weather.gov/documentation/services-web-api)
- [Claude Desktop](https://claude.ai/)
- Project structure based on examples from the [official MCP docs](https://modelcontextprotocol.io)

---

## 📄 License

This project is open-sourced under the MIT License.