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)

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

Pokreni server lokalno (ručno):

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):

{
  "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:

export MCP_API_KEY="moja-tajna"

Onda u tool pozivima proslijedi api_key.

---

Testovi

pip install pytest
pytest

---

GitHub

Kad uploaduješ:

• napravi repo public
• commitaj često (init → tools → resources → tests → readme)