# Parking Helper MCP Server (Python)

MCP server koji pomaže da vodiš evidenciju parking sesija i dobiješ kontekst (lokacija + trenutni weather).

## Zašto je ovo dobar use case?
- Realan problem: lako zaboraviš kada parking ističe.
- Ima pravi datastore (SQLite) + pravi REST integracije (geocoding + weather).
- Claude može čitati resurse (Markdown izvještaj) i zvati tool-ove.

---

## Funkcionalnosti (Minimalni zahtjevi zadatka)
- ✅ **3+ MCP tools**:
  1) `start_parking` – kreira sesiju (SQLite) + geocoding (Nominatim) + weather (Open‑Meteo)  
  2) `list_parking_sessions` – lista sesije iz baze  
  3) `end_parking` – završava sesiju  
  4) `check_expiring` – (extra) šta ističe uskoro
- ✅ **1+ MCP resource**:
  - `parking://active` (aktivne sesije kao Markdown)
  - `parking://expiring` (sesije koje ističu uskoro)
- ✅ **Eksterna integracija**:
  - SQLite (lokalna baza)  
  - REST: Nominatim + Open‑Meteo
- ✅ **Claude Desktop integracija**:
  - `claude_desktop_config.json` primjer (copy/paste)
- ✅ **README + arhitektura + upute**
- ✅ **Testovi**: `pytest` (unit testovi za DB logiku)
- ⭐ Bonus: **API key** (opciono) + JSON structured logging

---

## Arhitektura (ASCII)

Claude Desktop
   │  (MCP stdio)
   ▼
Python MCP Server (FastMCP)
   ├─ Tools
   │   ├─ start_parking → SQLite + Nominatim + Open‑Meteo
   │   ├─ list_parking_sessions → SQLite
   │   ├─ end_parking → SQLite
   │   └─ check_expiring → SQLite
   └─ Resources
       ├─ parking://active → Markdown report (SQLite)
       └─ parking://expiring → Markdown report (SQLite)

---

## Instalacija

> Preporuka: Python 3.10+ (idealno 3.11/3.12)

```bash
cd parking-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

Pokreni server lokalno (ručno):

```bash
python3 server.py
```

---

## Claude Desktop setup

1) Otvori **Claude Desktop** → Settings → Developer → MCP
2) U `claude_desktop_config.json` dodaj (ili kopiraj iz našeg fajla):

```json
{
  "mcpServers": {
    "parking-helper": {
      "command": "python3",
      "args": ["server.py"],
      "env": {
        "PARKING_DB_PATH": "./data/parking.db",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}
```

3) Restartuj Claude Desktop.

### Screenshotovi (za predaju)
Napravi 2–3 screenshot-a:
- Claude vidi server “parking-helper” u MCP listi
- Pozoveš `start_parking`
- Pozoveš `list_parking_sessions` / `check_expiring`
- Claude pročita resource `parking://active`

---

## Tool opis (schema + ponašanje)

### 1) start_parking
**Input:**
- `plate` (string) – tablice
- `address` (string) – adresa/lokacija
- `duration_minutes` (int 1..1440)
- `note` (string, optional)
- `api_key` (string, optional – bonus)

**Output:**
- `id`, `plate`, `address`, `duration_minutes`, `lat`, `lon`, `weather`

**Error handling:**
- loš input (`duration_minutes <= 0`) → ValueError
- geocode fail → GeocodeError → tool vrati error
- weather fail → ne ruši tool, samo vrati bez `weather`

### 2) list_parking_sessions
**Input:** `status` (active|ended|all), `limit` (1..500)  
**Output:** lista sesija

### 3) end_parking
**Input:** `session_id`  
**Output:** `id`, `status`, `end_time_utc`

### 4) check_expiring
**Input:** `within_minutes` (0..1440), `limit`  
**Output:** lista sesija koje ističu uskoro

---

## Resources

- `parking://active` → Markdown tabela aktivnih sesija  
- `parking://expiring` → Markdown tabela sesija koje ističu u 15 min

---

## Bonus: API key (opciono)

Ako želiš, zaključaj server:

```bash
export MCP_API_KEY="moja-tajna"
```

Onda u tool pozivima proslijedi `api_key`.

---

## Testovi

```bash
pip install pytest
pytest
```

---

## GitHub
Kad uploaduješ:
- napravi repo public
- commitaj često (init → tools → resources → tests → readme)