Workshop Guide - Komplett workshop dokumentasjon
Presentasjon - Norsk workshop presentasjon

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

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

┌─────────────────┐    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 │
└─────────────────┘            └─────────────────┘            └─────────────────┘

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

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

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

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

Du trenger API nøkler for:

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

# 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

# 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

• 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

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

• 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

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

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

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

pip install -r requirements.txt

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

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

# 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

• 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

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

# 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?"}'

# 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

• 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

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

# 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

• 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

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

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

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

# 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?"}'

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

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

# 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

LAB02 er designet for utvidelse. Deltagere kan legge til:

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.

• 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

# 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

MIT License - se LICENSE fil for detaljer.

For workshop deltagere:

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

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