Travel Weather Server

Dokumentasjon

Workshop Guide - Komplett workshop dokumentasjon
Presentasjon - Norsk workshop presentasjon

Workshop ressurser:

• Workshop Guide - Detaljert lab guide for workshop deltagere
• Presentasjon - Slide deck for workshop
• PowerPoint - PowerPoint versjon av presentasjon

Oversikt

MCP Travel Weather Server er en forenklet implementasjon for workshop LAB02. Dette er en læringsorientert versjon som demonstrerer Model Context Protocol (MCP) grunnleggende konsepter med fokus på værdata.

Arkitektur: Systemet består av tre hovedkomponenter:

• Web Service: Frontend brukergrensesnitt
• AI Agent: OpenAI-basert agent som orkestrerer forespørsler
• MCP Server: HTTP API med værfunksjonalitet

Workshop Arkitektur (LAB02)

Forenklet tjenestearkitektur

┌─────────────────┐    HTTP    ┌─────────────────┐    HTTP    ┌─────────────────┐
│   Web Service   │ ─────────► │  Agent Service  │ ─────────► │  MCP Server     │
│   (Port 8080)   │            │   (Port 8001)   │            │   (Port 8000)   │
│                 │            │                 │            │                 │
│ • Frontend UI   │            │ • AI Logic      │            │ • Weather Tool  │
│ • User Interface│            │ • OpenAI GPT-4o │            │ • OpenWeatherMap│
│ • Examples      │            │ • Conversation  │            │ • Geocoding     │
│ • Health Checks │            │ • Memory        │            │ • Health Checks │
└─────────────────┘            └─────────────────┘            └─────────────────┘

1. MCP Server (services/mcp-server/)

MCP-compliant HTTP API - Port 8000

• GET /tools - MCP tools manifest (MCP spec 2025-06-18)
• POST /weather - Værprognose (returnerer MCP result format)
• GET /health - Helsesjekk

MCP Tools Manifest: Serveren følger MCP spesifikasjonen og eksponerer verktøy med:

• name: Unikt verktøynavn
• title: Human-readable visningsnavn
• description: Funksjonalitetsbeskrivelse
• inputSchema: JSON Schema for input validering
• outputSchema: JSON Schema for output validering
• endpoint: HTTP endpoint for verktøyet
• method: HTTP metode (GET, POST, etc.)

MCP Result Format: Alle verktøy returnerer MCP-compliant responses:

{
  "content": [{"type": "text", "text": "..."}],
  "structuredContent": {...},
  "isError": false
}

API som brukes:

• OpenWeatherMap for værdata
• Nominatim (OpenStreetMap) for geocoding

2. Agent Service (services/agent/)

AI-orkestrering med MCP-compliant tool handling - Port 8001

• OpenAI GPT-4o mini for intelligent respons
• Dynamisk lasting av verktøy fra MCP server ved oppstart
• MCP-compliant response parsing (content array, structuredContent, isError)
• HTTP klient med endpoint mapping fra tools manifest
• Persistent SQLite database for samtalehistorikk
• POST /query - Prosesser brukerforespørsler
• GET /health - Helsesjekk med agent status

3. Web Service (services/web/)

Frontend web-grensesnitt - Port 8080

• HTML/JavaScript grensesnitt
• HTTP klient for agent kommunikasjon
• Eksempel spørsmål og interaktiv chat
• Real-time helsestatusindikator
• GET / - Hovedside
• POST /query - Proxy til agent service
• GET /examples - Foreslåtte spørsmål
• GET /health - Helsesjekk

Workshop Læringsmål

Denne LAB02-versjonen er designet for å lære:

• MCP Protocol: Implementering av Model Context Protocol (spec 2025-06-18)
• MCP Tools: Verktøydefinisjon med inputSchema og outputSchema
• MCP Results: Strukturerte responses med content array og structuredContent
• Tools Integration: Dynamisk kobling av AI agent med MCP server verktøy
• OpenAI Function Calling: Strukturert verktøybruk med dynamic tool loading
• Docker Deployment: Containerisert mikroservice deployment
• Error Handling: MCP-compliant error responses med isError flag

Kom i gang

Forutsetninger

Du trenger API nøkler for:

• OpenAI: For GPT AI → platform.openai.com
• OpenWeatherMap: For værdata → openweathermap.org/api

Docker Deployment (Anbefalt)

# Klon repository
git clone <repository-url>
cd agent

# Sett opp miljøvariabler
cp .env.example .env
# Rediger .env med dine API nøkler

# Start alle tjenester
docker-compose up -d

# Sjekk status
docker-compose ps

Tilgang:

• Hovedside: http://localhost:8080
• Agent API: http://localhost:8001
• MCP API: http://localhost:8000

Miljøvariabler

# Kreves for LAB02
OPENAI_API_KEY=your_openai_api_key_here
OPENWEATHER_API_KEY=your_openweather_api_key_here  

# Service URLs (auto-konfigurert i Docker)
MCP_SERVER_URL=http://mcp-server:8000

Funksjoner (LAB02)

MCP-Compliant Tools Discovery

• MCP server eksponerer tilgjengelige verktøy via /tools endpoint
• Agent laster verktøy dynamisk ved oppstart
• Følger MCP spesifikasjon 2025-06-18
• Tools returnerer strukturerte responses med content, structuredContent og isError
• Støtte for inputSchema og outputSchema validering

Værprognose

• Detaljert værprognose for enhver destinasjon
• Temperatur, nedbør, vind og luftfuktighet
• Basert på OpenWeatherMap API

MCP Verktøy

• get_weather_forecast: Hent værprognose for destinasjoner
• ping: Test verktøy for tilkoblingskontroll
• get_status: Server status informasjon
• Alle verktøy følger MCP spesifikasjon

Persistent Hukommelse

• Husker samtalehistorikk på tvers av sesjoner
• SQLite database for lokal lagring
• Administrering av flere samtalesesjoner

Intelligent Dialog

• OpenAI GPT-4o mini for naturlig språkforståelse
• Dynamic function calling basert på MCP tools manifest
• Kontekstbevisst samtaler

MCP Arkitektur

Workshop LAB02 demonstrerer MCP (Model Context Protocol) arkitektur med dynamisk tools discovery:

Web Service → AI Agent ←→ MCP Server → External APIs
             ↓ (dynamic)   ↓ (/tools)
         Tools Loading  Tools Manifest

Arkitektur komponenter:

• Web Service: Frontend brukergrensesnitt og API proxy
• AI Agent: OpenAI GPT-4o mini med dynamisk tools loading og intelligent endpoint mapping
• MCP Server: HTTP API som eksponerer MCP tools manifest og implementerer verktøy
• Tools Manifest: MCP-kompatibel manifest med endpoint og method informasjon
• Memory: Persistent samtalehukommelse

MCP Protocol Implementation:

• MCP server følger MCP spesifikasjon for tools eksponering
• Agent implementerer dynamisk tools discovery ved oppstart
• Intelligent endpoint mapping med både eksplisitt og konvensjonsbasert støtte
• HTTP method routing (GET, POST, PUT, DELETE) basert på tools manifest

For detaljert workshop guide, se WORKSHOP.md

Python Avhengigheter (hvis ikke bruker Docker)

pip install -r requirements.txt

Docker Deployment (Anbefalt)

Systemet er optimalisert for Docker deployment med alle komponenter i separate containere.

Forutsetninger

• Docker og Docker Compose installert
• API nøkler konfigurert (se over)

Rask start

# Klon repository og naviger til mappen
cd travel-weather-mcp

# Kopier og rediger miljøvariabler
cp .env.example .env
# Rediger .env med dine API nøkler:
# - OPENAI_API_KEY (kreves)
# - OPENWEATHER_API_KEY (kreves)

# Bygg og start alle tjenester
docker-compose up -d

# Sjekk at alt kjører
docker-compose ps

Tjenester som startes

• travel-weather-mcp-server: MCP server med værverktøy
• travel-weather-agent: AI agent service
• travel-weather-web: Web interface på http://localhost:8080

Bruk av tjenestene

Web Interface

Åpne http://localhost:8080 i nettleseren for enkel bruk.

API Tilgang

# REST API kall
curl -X POST http://localhost:8080/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Hvordan er været i Oslo i dag?"}'

Manuell Docker start

# Bygg og start alle tjenester
docker-compose up -d

# Eller start kun spesifikke tjenester
docker-compose up -d mcp-server travel-agent

# Se logfiler
docker-compose logs -f mcp-server
docker-compose logs -f travel-agent

# Stopp tjenester
docker-compose down

Tilgjengelige tjenester

• Web Interface: http://localhost:8080 - Enkel web-grensesnitt for agenten
• Agent API: http://localhost:8001 - REST API for agenten
• MCP Server: http://localhost:8000 - MCP server API

Bruk

Web Interface (Anbefalt)

Gå til http://localhost:8080 i nettleseren din for et enkelt brukergrensesnitt.

Docker Commands

# Se alle kjørende tjenester
docker-compose ps

# Restart spesifikk tjeneste
docker-compose restart mcp-server

# Se logfiler live
docker-compose logs -f travel-agent

API Endpoints (LAB02)

MCP Tools Discovery

• GET /tools: Hent MCP tools manifest med alle tilgjengelige verktøy
• Returner: JSON array med verktøy inkludert navn, beskrivelse, input schema, endpoint og HTTP method

MCP Verktøy

get_weather_forecast

• location: Stedsnavn (f.eks. "Oslo, Norway")
• Endpoint: POST /weather
• Returner: Værprognose med temperatur, vind, fuktighet og beskrivelse

ping

• message: Melding å sende til ping verktøy
• Endpoint: POST /ping
• Returner: Bekreftelses-melding

get_status

• Ingen parametere kreves
• Endpoint: GET /status
• Returner: Server status informasjon

Eksempel API kall

# Hent tools manifest fra MCP server
curl http://localhost:8000/tools

# Direkte verktøy kall til MCP server
curl -X POST http://localhost:8000/weather \
  -H "Content-Type: application/json" \
  -d '{"location": "Oslo, Norway"}'

# Via Agent med dynamisk tools loading (anbefalt)
curl -X POST http://localhost:8001/query \
  -H "Content-Type: application/json" \
  -d '{"query": "Hvordan er været i Oslo?"}'

Sikkerhet

• API nøkler lagres som miljøvariabler
• Ingen sensitive data logges
• Input validering på alle endpoints
• Rate limiting gjennom OpenWeatherMap API

Feilsøking

Vanlige problemer

1. "API key not configured"

   • Sjekk at miljøvariabler er riktig satt i .env
   • Verifiser at API nøklene er gyldige

2. "Location not found"

   • Prøv mer spesifikke stedsnavn
   • Inkluder land (f.eks. "Oslo, Norway")

3. Containerproblemer

   • Kjør docker-compose down && docker-compose up -d
   • Sjekk logfiler med docker-compose logs

Logging

# Se agent logfiler
docker-compose logs -f travel-agent

# Se MCP server logfiler
docker-compose logs -f mcp-server

# Se alle logfiler
docker-compose logs -f

Workshop Utvidelser

LAB02 er designet for utvidelse. Deltagere kan legge til:

Nye MCP verktøy

1. Definer en ny HTTP endpoint i services/mcp-server/app.py
2. Legg til verktøyet i tools array med endpoint og method informasjon
3. Agent vil automatisk laste det nye verktøyet ved restart via /tools manifest
4. Test med web interface

Merk: Agent laster verktøy dynamisk, så ingen hardkoding kreves i agent koden.

Foreslåtte utvidelser

• Ruteplanlegging: Legg til OpenRouteService API
• Hotell booking: Integrer booking API
• Transport: Legg til public transport API
• Oversettelse: Legg til språkoversettelse

Se WORKSHOP.md for detaljerte instruksjoner

Testing

Manual testing

# Test health endpoints
curl http://localhost:8000/health
curl http://localhost:8001/health
curl http://localhost:8080/health

# Test MCP tools manifest
curl http://localhost:8000/tools

# Test alle MCP verktøy
curl -X POST http://localhost:8000/weather \
  -H "Content-Type: application/json" \
  -d '{"location": "Oslo, Norway"}'

curl -X POST http://localhost:8000/ping \
  -H "Content-Type: application/json" \
  -d '{"message": "test"}'

curl http://localhost:8000/status

Lisens

MIT License - se LICENSE fil for detaljer.

Workshop Support

For workshop deltagere:

• Dokumentasjon: WORKSHOP.md
• Presentasjon: workshop-presentation.html
• Teknisk support: Spør workshopleder

Bidrag

Bidrag er velkomne! Vennligst:

1. Fork repository
2. Opprett en feature branch
3. Commit endringene dine
4. Push til branch
5. Opprett en Pull Request