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.

Related MCP server: Weather MCP Server

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)