🌍 Concieragent

Your Multilingual AI Travel Concierge for Hologram

Orchestrating complex travel planning through MCP (Model Context Protocol) with multi-LLM support

🇬🇧 English • 🇪🇸 Español • 🇫🇷 Français

Features • Quick Start • Configuration • Architecture • Deployment • API Reference

🎯 What is Concieragent?

Concieragent is a production-ready, multilingual AI travel assistant that runs on the Hologram platform. It demonstrates the power of MCP (Model Context Protocol) by orchestrating 6 specialized travel planning servers with your choice of LLM backend.

✨ Key Highlights

Feature	Description
🤖 Multi-LLM Support	Switch between OpenAI, Claude, or Ollama
🌍 Multilingual	Automatic detection & responses in EN/ES/FR
🛠️ 30 MCP Tools	Real-time flights, hotels, weather, events, finance
💬 Context-Aware	Remembers conversation history & user preferences
⚡ Smart Truncation	Handles large API responses gracefully
🔒 Private & Secure	End-to-end encrypted via Hologram

✨ Features

🛫 Comprehensive Travel Planning

✈️ Flights

Real-time flight search via SerpAPI
Filter by price, airline, duration
Multi-city and round-trip support

🏨 Hotels

Global hotel search with ratings
Filter by amenities, price, class
Property details and reviews

🎭 Events

Local events and activities
Filter by date, type, venue
Concert, sports, cultural events

🌤️ Weather

Current conditions (OpenWeatherMap)
5-day forecasts
Works worldwide

📍 Geocoding

Location to coordinates
Distance calculations
Batch geocoding

💰 Finance

Real-time currency conversion
Stock lookups
Market overview

🤖 Multi-LLM Support

Choose your preferred AI backend:

Provider	Model	Best For
OpenAI	GPT-4o	Production demos, best tool calling
Claude	Claude Sonnet	Alternative cloud option
Ollama	Llama 3.1, Mistral	Local/private, no API costs

🌍 Internationalization (i18n)

The bot automatically detects and responds in the user's language:

🇬🇧 English - Default language
🇪🇸 Spanish - "Hola, ¿qué tiempo hace en Barcelona?"
🇫🇷 French - "Bonjour, je cherche un hôtel à Paris"

Language detection happens automatically based on the user's message patterns.

🧠 Smart Context Management

Conversation Memory - Remembers destinations, dates, preferences
No Repetitive Questions - Uses context from previous messages
Token Management - Automatic truncation of large responses
Rate Limit Handling - Graceful retry with context trimming

🚀 Quick Start

Prerequisites

Requirement	Purpose	Get It
Docker	VS Agent container	Install
Node.js 18+	Bot server	Install
Python 3.12+	MCP servers	Install
UV	Python packages	Install
ngrok	Public URL tunnel	Get free
Hologram App	Mobile client	Download

💡 Windows Users: See WINDOWS_SETUP.md for Windows-specific setup instructions and PowerShell scripts.

API Keys Needed

Service	Purpose	Free Tier
OpenAI	LLM orchestration	Pay-as-you-go
SerpAPI	Flights, hotels, events	100 searches/mo
OpenWeatherMap	Weather data	Unlimited

Installation

# 1. Clone the repository
git clone https://github.com/your-org/concieragent.git
cd concieragent

# 2. Install Node.js dependencies
pnpm install

# 3. Install Python dependencies for all MCP servers
for server in flight hotel event geocoder weather finance; do
  cd mcp_travelassistant/servers/${server}_server && uv sync && cd ../../..
done

# 4. Configure environment
cp .env.example .env
# Edit .env with your API keys

Running

You need 3 terminals:

On macOS/Linux:

# Terminal 1: Start ngrok
ngrok http 3001
# Note the URL: https://xxxxx.ngrok-free.app

# Terminal 2: Start bot server
pnpm start
# Wait for: ✅ Travel Agent ready!

# Terminal 3: Start VS Agent
./scripts/docker-run.sh xxxxx.ngrok-free.app

On Windows (PowerShell):

# Terminal 1: Start ngrok
ngrok http 3001
# Note the URL: https://xxxxx.ngrok-free.app

# Terminal 2: Start bot server
pnpm run dev
# Wait for: ✅ Travel Agent ready!

# Terminal 3: Start VS Agent (PowerShell)
.\scripts\docker-run.ps1 xxxxx.ngrok-free.app

# OR use Batch file (Command Prompt)
scripts\docker-run.bat xxxxx.ngrok-free.app

Connect & Test

Open http://localhost:3001/invitation
Scan QR code with Hologram app
Send: "What's the weather in Tokyo?" 🎉

⚙️ Configuration

Environment Variables

Create a .env file in the project root:

# ═══════════════════════════════════════════════════════════════
# LLM PROVIDER CONFIGURATION
# ═══════════════════════════════════════════════════════════════

# Choose: 'openai', 'claude', or 'ollama'
LLM_PROVIDER=openai

# ───────────────────────────────────────────────────────────────
# OpenAI (default)
# ───────────────────────────────────────────────────────────────
OPENAI_API_KEY=sk-your-key-here
# OPENAI_MODEL=gpt-4o  # Optional, defaults to gpt-4o

# ───────────────────────────────────────────────────────────────
# Anthropic Claude
# ───────────────────────────────────────────────────────────────
ANTHROPIC_API_KEY=sk-ant-your-key-here
# CLAUDE_MODEL=claude-sonnet-4-20250514  # Optional

# ───────────────────────────────────────────────────────────────
# Ollama (Local - no API key needed)
# ───────────────────────────────────────────────────────────────
# OLLAMA_BASE_URL=http://localhost:11434  # Optional
# OLLAMA_MODEL=llama3.1  # Optional

# ═══════════════════════════════════════════════════════════════
# MCP SERVER API KEYS
# ═══════════════════════════════════════════════════════════════

# SerpAPI - Flights, Hotels, Events, Finance
SERPAPI_KEY=your-serpapi-key-here

# OpenWeatherMap - Weather data
OPENWEATHER_API_KEY=your-openweather-key-here

# ═══════════════════════════════════════════════════════════════
# VS AGENT
# ═══════════════════════════════════════════════════════════════
VS_AGENT_URL=http://localhost:3000

Switching LLM Providers

Simply change LLM_PROVIDER in your .env:

# Use Claude instead of OpenAI
LLM_PROVIDER=claude
ANTHROPIC_API_KEY=sk-ant-xxxxx

# Use local Ollama (free!)
LLM_PROVIDER=ollama
OLLAMA_MODEL=llama3.1

For Ollama, make sure it's running:

# Install from https://ollama.ai
ollama pull llama3.1
ollama serve

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                    📱 Hologram Mobile App                        │
│                    (iPhone / Android)                            │
└───────────────────────────┬─────────────────────────────────────┘
                            │ 🔐 DIDComm (E2E Encrypted)
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│                  🐳 VS Agent (Docker)                            │
│            Protocol Handler • Connection Manager                 │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTP Webhooks
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│              🤖 Concieragent Bot Server (Node.js)               │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │                    TravelAgent                             │  │
│  │  • Multi-LLM Provider (OpenAI/Claude/Ollama)              │  │
│  │  • Context Management & Memory                             │  │
│  │  • i18n Language Detection                                 │  │
│  │  • Token Management & Truncation                           │  │
│  └─────────────────────────┬─────────────────────────────────┘  │
│                            │ MCP Protocol                        │
│  ┌─────────────────────────▼─────────────────────────────────┐  │
│  │                    McpClient                               │  │
│  │           Spawns & manages Python MCP servers              │  │
│  └─────────────────────────┬─────────────────────────────────┘  │
└────────────────────────────┼────────────────────────────────────┘
                             │
       ┌─────────────────────┼─────────────────────┐
       │                     │                     │
┌──────▼──────┐  ┌──────────▼──────────┐  ┌──────▼──────┐
│ ✈️ Flights   │  │ 🏨 Hotels           │  │ 🎭 Events   │
│ (SerpAPI)   │  │ (SerpAPI)           │  │ (SerpAPI)   │
└─────────────┘  └────────────────────┘  └─────────────┘
       │                     │                     │
┌──────▼──────┐  ┌──────────▼──────────┐  ┌──────▼──────┐
│ 📍 Geocoder  │  │ 🌤️ Weather          │  │ 💰 Finance  │
│ (Nominatim) │  │ (OpenWeatherMap)    │  │ (SerpAPI)   │
└─────────────┘  └────────────────────┘  └─────────────┘

Technology Stack

Layer	Technology	Purpose
Frontend	Hologram App	Encrypted mobile messaging
Protocol	DIDComm	Decentralized identity & encryption
Gateway	VS Agent	Protocol handler (Docker)
Server	Node.js + TypeScript	Application logic
AI	OpenAI / Claude / Ollama	LLM orchestration
Tools	MCP Protocol	External service integration
Servers	Python 3.12 + FastMCP	6 specialized MCP servers

Kubernetes Deployment Architecture

While Kubernetes is not mandatory, here's an example architecture for production deployments:

┌─────────────────────────────────────────────────────────────────┐
│                    Kubernetes Cluster                            │
│  ┌─────────────────────────────────────────────────────────┐    │
│  │                    demos namespace                       │    │
│  │  ┌─────────────┐         ┌─────────────┐                │    │
│  │  │ Concieragent│◀────────│  VS Agent   │                │    │
│  │  │   (Bot)     │  HTTP   │  (DIDComm)  │                │    │
│  │  │  Port 4001  │         │  Port 3000  │                │    │
│  │  └─────────────┘         └─────────────┘                │    │
│  │        │                        │                        │    │
│  │        │     ┌──────────────────┘                       │    │
│  │        ▼     ▼                                           │    │
│  │  ┌─────────────────────────────────────────────┐        │    │
│  │  │              Ingress (nginx)                 │        │    │
│  │  │  concieragent.domain.com                    │        │    │
│  │  │  concieragent.domain.com/invitation         │        │    │
│  │  └─────────────────────────────────────────────┘        │    │
│  └─────────────────────────────────────────────────────────┘    │
└─────────────────────────────────────────────────────────────────┘
                              │
                              ▼
                    ┌──────────────┐
                    │   Hologram   │
                    │   Mobile App │
                    └──────────────┘

For Kubernetes deployment, use the provided Helm charts in the charts/ directory. See doc/deployment.md for detailed deployment instructions.

📡 API Reference

Endpoints

Method	Endpoint	Description
`POST`	`/message-received`	Webhook for incoming messages
`POST`	`/connection-established`	Handle new connections with welcome
`GET`	`/welcome?lang=es`	Get localized welcome message
`GET`	`/health`	Health check
`GET`	`/invitation`	QR code for Hologram connection
`GET`	`/logo.png`	Bot logo

MCP Tools Available (30 total)

✈️ Flight Tools (4)

Tool	Description
`search_flights`	Search flights by origin, destination, dates
`get_flight_details`	Get detailed info for a specific flight
`filter_flights_by_price`	Filter results by max price
`filter_flights_by_airline`	Filter results by airline

🏨 Hotel Tools (7)

Tool	Description
`search_hotels`	Search hotels by location, dates
`get_hotel_details`	Get detailed hotel info
`get_property_details`	Extended property information
`filter_hotels_by_price`	Filter by price range
`filter_hotels_by_rating`	Filter by star rating
`filter_hotels_by_amenities`	Filter by amenities
`filter_hotels_by_class`	Filter by hotel class

🎭 Event Tools (5)

Tool	Description
`search_events`	Search local events
`get_event_details`	Get event details
`filter_events_by_date`	Filter by date range
`filter_events_by_type`	Filter by event type
`filter_events_by_venue`	Filter by venue

🌤️ Weather Tools (3)

Tool	Description
`get_current_conditions`	Current weather for location
`get_weather_forecast`	5-day weather forecast
`get_weather_data_details`	Extended weather data

📍 Geocoder Tools (5)

Tool	Description
`geocode_location`	Address to coordinates
`reverse_geocode`	Coordinates to address
`batch_geocode`	Multiple locations at once
`calculate_distance`	Distance between points
`search_locations`	Search for places

💰 Finance Tools (6)

Tool	Description
`convert_currency`	Real-time currency conversion
`lookup_stock`	Stock price lookup
`get_market_overview`	Market summary
`get_finance_details`	Extended finance data
`filter_stocks_by_price_movement`	Filter stocks
`get_historical_data`	Historical prices

💬 Usage Examples

English

User: "What's the weather like in Paris this week?"
Bot: 🌤️ Using OpenWeatherMap MCP tool...

     Current weather in Paris, France:
     Temperature: 18°C (feels like 17°C)
     Conditions: Partly cloudy
     Humidity: 65%
     Wind: 12 km/h

     5-Day Forecast:
     - Monday: 19°C, Sunny
     - Tuesday: 17°C, Light rain
     ...

Spanish 🇪🇸

User: "Hola, busco vuelos de Madrid a Tokyo para la próxima semana"
Bot: ¡Hola! Voy a buscar vuelos de Madrid a Tokyo...

     ✈️ He encontrado 5 opciones de vuelos:
     
     1. Iberia - $892 USD
        Duración: 14h 30m (1 escala)
        Salida: 10:30 → Llegada: 07:00+1
     ...

French 🇫🇷

User: "Bonjour, je cherche un hôtel à Nice pour le week-end prochain"
Bot: Bonjour ! Je recherche des hôtels à Nice...

     🏨 J'ai trouvé 8 hôtels correspondant à vos critères:
     
     1. Hôtel Negresco ⭐⭐⭐⭐⭐
        Prix: 320€/nuit
        Note: 4.8/5 (1,234 avis)
     ...

🔧 Troubleshooting

Common Issues

❌ "No MCP tools available"

Cause: Python MCP servers failed to start

Fix:

# Check each server can start
cd mcp_travelassistant/servers/flight_server
uv sync
uv run python flight_server.py
# Should show "Processing request..." when working

❌ Rate limit exceeded (429)

Cause: Too many tokens or requests to OpenAI

Fix:

The bot automatically retries with trimmed context
Wait a few seconds between requests
Consider using Ollama for unlimited local usage

❌ VS Agent won't start

Fix:

# Check Docker is running
docker ps

# Remove old container and restart
docker stop vs-agent && docker rm vs-agent
./scripts/docker-run.sh your-ngrok-url

❌ Weather/flights returning errors

Cause: Missing or invalid API keys

Fix: Check your .env file has valid keys:

OPENWEATHER_API_KEY=your-key  # Get from openweathermap.org
SERPAPI_KEY=your-key          # Get from serpapi.com

🚀 Deployment Environments

Local Development

# 1. Install dependencies
pnpm install

# 2. Set up environment
cp .env.example .env
# Edit .env with your API keys

# 3. Install MCP server dependencies
for server in flight hotel event geocoder weather finance; do
  cd mcp_travelassistant/servers/${server}_server && uv sync && cd ../../..
done

# 4. Start ngrok (in separate terminal)
ngrok http 3001

# 5. Start bot server
pnpm run dev

# 6. Start VS Agent
./scripts/docker-run.sh your-ngrok-url

Docker Local Testing

# Build image
pnpm run docker:build

# Run with environment file
pnpm run docker:run

# Or with explicit env vars
docker run -p 4001:4001 \
  -e OPENAI_API_KEY=sk-xxx \
  -e SERPAPI_KEY=xxx \
  -e OPENWEATHER_API_KEY=xxx \
  concieragent:local

Kubernetes Deployment

For production deployments, use the provided Helm charts:

# Dry run
helm template concieragent ./charts \
  --set global.domain=your-domain.com

# Install
helm upgrade --install concieragent ./charts \
  --namespace demos \
  --create-namespace \
  --set global.domain=your-domain.com \
  --set existingSecret=concieragent-api-keys

See doc/deployment.md for detailed API documentation and deployment instructions.

🌐 Accessing Your Deployment

URLs

After successful deployment:

URL	Purpose
`https://concieragent.{domain}/invitation`	QR code for Hologram connection
`https://concieragent.{domain}/health`	Health check endpoint
`https://concieragent.{domain}/welcome`	Welcome message API

Connecting with Hologram

Open your browser to https://concieragent.{domain}/invitation
Open the Hologram app on your phone
Scan the QR code
Start chatting!

Checking Deployment Status

# View pods (Kubernetes)
kubectl get pods -n demos -l app=concieragent
kubectl get pods -n demos -l app=concieragent-vsa

# View logs
kubectl logs -n demos -l app=concieragent -f
kubectl logs -n demos -l app=concieragent-vsa -f

# View ingress
kubectl get ingress -n demos | grep concieragent

📁 Project Structure

concieragent/
├── 📄 src/
│   ├── bot.ts                    # Express server entry point
│   ├── agent/
│   │   ├── TravelAgent.ts        # Main orchestration logic
│   │   └── McpClient.ts          # MCP protocol client
│   ├── providers/
│   │   ├── types.ts              # Provider interfaces
│   │   ├── openai-provider.ts   # OpenAI adapter
│   │   ├── claude-provider.ts    # Claude adapter
│   │   ├── ollama-provider.ts    # Ollama adapter
│   │   └── index.ts              # Provider factory
│   ├── controllers/              # Route handlers
│   │   ├── health.controller.ts  # Health check endpoint
│   │   ├── message.controller.ts # Message webhook handler
│   │   ├── connection.controller.ts # Connection webhook handler
│   │   └── index.ts              # Controller exports
│   ├── config/                   # Configuration modules
│   │   ├── app.config.ts         # Application configuration
│   │   └── index.ts              # Config exports
│   ├── dto/                      # Data Transfer Objects
│   │   └── index.ts              # DTO definitions
│   ├── common/                   # Shared utilities
│   │   ├── enums/                # Enum definitions
│   │   └── index.ts              # Common exports
│   └── i18n/                     # Internationalization
│       ├── en/msg.json           # English messages
│       ├── es/msg.json           # Spanish messages
│       └── fr/msg.json           # French messages
├── 🐍 mcp_travelassistant/
│   └── servers/
│       ├── flight_server/        # ✈️ Flight search
│       ├── hotel_server/         # 🏨 Hotel search
│       ├── event_server/         # 🎭 Event discovery
│       ├── geocoder_server/      # 📍 Geocoding
│       ├── weather_server/       # 🌤️ Weather
│       └── finance_server/       # 💰 Finance
├── 📜 scripts/
│   ├── docker-run.sh             # VS Agent startup
│   └── entrypoint.sh             # Docker entrypoint script
├── 🐳 docker-dev/                # Development Docker setup
│   ├── docker-compose.yml        # Docker compose config
│   ├── ngrok-config.yml          # Ngrok configuration
│   └── README.md                 # Dev setup instructions
├── 📋 package.json               # Dependencies
├── ⚙️ tsconfig.json              # TypeScript config
├── ⚙️ tsconfig.build.json        # Build-specific TypeScript config
├── 📝 .eslintrc.js               # ESLint configuration
├── 📝 .prettierrc                # Prettier configuration
├── 📝 .npmrc                     # pnpm configuration
└── 📖 README.md                  # You are here!

🛣️ Roadmap

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

📄 License

MIT License - see LICENSE for details.

🙏 Acknowledgments

Hologram - Decentralized messaging platform
Anthropic - MCP protocol specification
OpenAI - GPT-4o and function calling
Ollama - Local LLM runtime
2060 OÜ - VS Agent infrastructure

Built with ❤️ for the Hologram ecosystem by Maxime Mansiet

⬆️ Back to Top

Name		Name	Last commit message	Last commit date
Latest commit History 11 Commits
.github/workflows		.github/workflows
assets		assets
charts		charts
doc		doc
docker-dev		docker-dev
mcp_travelassistant		mcp_travelassistant
scripts		scripts
src		src
.dockerignore		.dockerignore
.env.example		.env.example
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.npmrc		.npmrc
.prettierrc		.prettierrc
.release-please-manifest.json		.release-please-manifest.json
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
refresh.md		refresh.md
release-please-config.json		release-please-config.json
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json

License

2060-io/hologram-concieragent-demo-vs

Folders and files

Latest commit

History

Repository files navigation

🌍 Concieragent

🎯 What is Concieragent?

✨ Key Highlights

✨ Features

🛫 Comprehensive Travel Planning

🤖 Multi-LLM Support

🌍 Internationalization (i18n)

🧠 Smart Context Management

🚀 Quick Start

Prerequisites

API Keys Needed

Installation

Running

Connect & Test

⚙️ Configuration

Environment Variables

Switching LLM Providers

🏗️ Architecture

Technology Stack

Kubernetes Deployment Architecture

📡 API Reference

Endpoints

MCP Tools Available (30 total)

💬 Usage Examples

English

Spanish 🇪🇸

French 🇫🇷

🔧 Troubleshooting

Common Issues

🚀 Deployment Environments

Local Development

Docker Local Testing

Kubernetes Deployment

🌐 Accessing Your Deployment

URLs

Connecting with Hologram

Checking Deployment Status

📁 Project Structure

🛣️ Roadmap

🤝 Contributing

📄 License

🙏 Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Contributors 3

Uh oh!

Languages

Packages