MCP Travel Weather Server - LAB02

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 implementasjon for workshop LAB02. Dette er en læringsorientert versjon som demonstrerer Model Context Protocol (MCP) grunnleggende konsepter med fokus på værdata og reiseplanlegging.

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/`)

HTTP API med dynamisk tools manifest - Port 8000

GET /tools - MCP tools manifest (følger MCP spesifikasjon)
POST /weather - Værprognose for destinasjoner
GET /health - Helsesjekk

MCP Tools Manifest: Serveren eksponerer tilgjengelige verktøy via /tools endepunkt i henhold til MCP spesifikasjonen, inkludert navn, beskrivelse, input schema og endpoint informasjon.

API som brukes:

OpenWeatherMap for værdata
Nominatim (OpenStreetMap) for geocoding

2. Agent Service (`services/agent/`)

AI-orkestrering med dynamisk tools loading - Port 8001

OpenAI GPT-4o mini for intelligent respons
Dynamisk lasting av verktøy fra MCP server ved oppstart
HTTP klient med intelligent endpoint mapping
Persistent SQLite database for samtalehistorikk
Eksplisitt og konvensjonsbasert endpoint mapping
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 med dynamisk tools discovery
HTTP API: REST API arkitektur med intelligent endpoint mapping
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
MCP Spesifikasjon: Følge MCP standarder for tools manifest og endpoint eksponering

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)

Dynamisk Tools Discovery

MCP server eksponerer tilgjengelige verktøy via /tools endpoint
Agent laster verktøy dynamisk ved oppstart
Intelligent mapping mellom verktøy og HTTP endpoints
Støtte for eksplisitt endpoint spesifikasjon og konvensjonsbasert fallback

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

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

"API key not configured"
- Sjekk at miljøvariabler er riktig satt i .env
- Verifiser at API nøklene er gyldige
"Location not found"
- Prøv mer spesifikke stedsnavn
- Inkluder land (f.eks. "Oslo, Norway")
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

Definer en ny HTTP endpoint i services/mcp-server/app.py
Legg til verktøyet i tools array med endpoint og method informasjon
Agent vil automatisk laste det nye verktøyet ved restart via /tools manifest
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 MCP verktøy
curl -X POST http://localhost:8000/weather \
  -H "Content-Type: application/json" \
  -d '{"location": "Oslo, Norway"}'

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:

Fork repository
Opprett en feature branch
Commit endringene dine
Push til branch
Opprett en Pull Request

Name		Name	Last commit message	Last commit date
Latest commit History 27 Commits
.github		.github
services		services
.env.example		.env.example
.gitignore		.gitignore
LAB02_DYNAMIC_TOOLS.md		LAB02_DYNAMIC_TOOLS.md
LAB02_OPENWEBUI.md		LAB02_OPENWEBUI.md
README.md		README.md
WORKSHOP.md		WORKSHOP.md
docker-compose.yml		docker-compose.yml
marketing.html		marketing.html
requirements.txt		requirements.txt
workshop-presentation.html		workshop-presentation.html
workshop-presentation.md		workshop-presentation.md
workshop-presentation.pdf		workshop-presentation.pdf
workshop-presentation.pptx		workshop-presentation.pptx

Harlinn/mcp-ws

Folders and files

Latest commit

History

Repository files navigation

MCP Travel Weather Server - LAB02

Dokumentasjon

Workshop ressurser:

Oversikt

Workshop Arkitektur (LAB02)

Forenklet tjenestearkitektur

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

2. Agent Service (services/agent/)

3. Web Service (services/web/)

Workshop Læringsmål

Kom i gang

Forutsetninger

Docker Deployment (Anbefalt)

Miljøvariabler

Funksjoner (LAB02)

Dynamisk Tools Discovery

Værprognose

MCP Verktøy

Persistent Hukommelse

Intelligent Dialog

MCP Arkitektur

Python Avhengigheter (hvis ikke bruker Docker)

Docker Deployment (Anbefalt)

Forutsetninger

Rask start

Tjenester som startes

Bruk av tjenestene

Web Interface

API Tilgang

Manuell Docker start

Tilgjengelige tjenester

Bruk

Web Interface (Anbefalt)

Docker Commands

API Endpoints (LAB02)

MCP Tools Discovery

MCP Verktøy

get_weather_forecast

Eksempel API kall

Sikkerhet

Feilsøking

Vanlige problemer

Logging

Workshop Utvidelser

Nye MCP verktøy

Foreslåtte utvidelser

Testing

Manual testing

Lisens

Workshop Support

Bidrag

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

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

2. Agent Service (`services/agent/`)

3. Web Service (`services/web/`)

Packages