Content
# 🌺 Hawaii Conditions MCP Server
[](https://replit.com/integrations?mcp=eyJkaXNwbGF5TmFtZSI6Ikhhd2FpaSBDb25kaXRpb25zIE1DUCBTZXJ2ZXIiLCJiYXNlVXJsIjoiaHR0cHM6Ly9oYXdhaWktY29uZGl0aW9ucy52ZXJjZWwuYXBwL21jcCJ9)
Real-time surf conditions, trail status, volcano activity, ocean safety alerts, hyperlocal weather, and restaurant discovery for all Hawaiian islands — built for AI agents.
Powered by NOAA, USGS Hawaiian Volcano Observatory, NPS, Open-Meteo, and Google Places.
---
## 🚀 What this is
This is a **Model Context Protocol (MCP) server** that gives AI agents structured, real-time data about Hawaii.
Agents can use it to:
- Plan trips
- Check safety conditions (ocean, trails, volcano)
- Build itineraries
- Recommend restaurants and food
- Generate full daily briefings
---
## 🌐 MCP Endpoint
```
https://hawaii-conditions.vercel.app/mcp
```
### Example request
```bash
curl -X POST https://hawaii-conditions.vercel.app/mcp \
-H "Content-Type: application/json" \
-d '{
"method": "tools/call",
"params": {
"name": "get_weather",
"arguments": {
"island": "oahu"
}
}
}'
```
---
## 💳 Payment (prepaid balance via Stripe)
Each agent maintains a prepaid balance on the server. Paid data tools
atomically debit that balance per call.
1. **Register** — call `register_agent` (free). Returns an `mcp_…` API key
and creates a Stripe Customer.
2. **Authenticate** — send the key on every paid call:
```
X-MCP-Account: mcp_live_xxx
```
(`Authorization: Bearer mcp_live_xxx` is also accepted.)
3. **Top up** — call `add_funds_5`, `add_funds_10`, or `add_funds_20`. The
server returns a Stripe `PaymentIntent` (`payment_intent_id` +
`client_secret`). Confirm it with your wallet or saved card.
4. **Credit** — Stripe's `payment_intent.succeeded` webhook (POSTed to
`/stripe-webhook`) credits the ledger. The PI id is the idempotency key,
so retries cannot double-credit.
5. **Debit** — paid data tools debit the balance per call. Successful calls
return:
```
X-MCP-Balance-Cents: 175
X-MCP-Balance-USD: $1.75
X-MCP-Balance-Warning: low (only when below $2.00)
```
6. **Insufficient funds** — HTTP 402 with current balance, shortfall, and
the list of top-up tools to call.
7. **Check anytime** — `get_balance` (free) returns balance + recent
transactions.
### Required env vars
| Variable | Purpose |
|---|---|
| `STRIPE_SECRET_KEY` | Server-side Stripe calls (Customers, PaymentIntents) |
| `STRIPE_PUBLISHABLE_KEY` | Echoed back to the agent so it can confirm PIs |
| `STRIPE_WEBHOOK_SECRET` | Verifies the Stripe webhook signature |
| `DATABASE_URL` | Neon Postgres connection string (also accepts `POSTGRES_URL`) |
| `MPP_ENABLED` | Optional — set to `true` once Stripe MPP preview is live on the account |
---
## 🧠 Tools
| Tool | Price | Description |
| ------------------------ | ----- | --------------------------------------------- |
| `ping` | Free | Health check |
| `get_sun_times` | Free | Sunrise, sunset, daylight duration (HST) |
| `register_agent` | Free | Create prepaid account; returns API key |
| `get_balance` | Free | Current balance + recent transactions |
| `get_weather` | $0.10 | 5-day forecast, UV, wind, sunrise/sunset |
| `get_surf_conditions` | $0.10 | Wave height, period, direction + forecast |
| `get_trail_status` | $0.25 | Trail closures, alerts, NPS + DLNR |
| `get_volcano_status` | $0.25 | Kīlauea eruption status (USGS HVO) |
| `get_ocean_safety` | $0.50 | Jellyfish warnings, rip currents, NOAA alerts |
| `get_full_briefing` | $2.00 | All data combined (best value) |
| `search_restaurants` | $0.25 | Find restaurants by location, cuisine, price |
| `get_restaurant_details` | $0.15 | Full details, hours, reviews, photos |
| `add_funds_5` | $5.00 | Top up $5 of prepaid balance via Stripe |
| `add_funds_10` | $10.00| Top up $10 of prepaid balance via Stripe |
| `add_funds_20` | $20.00| Top up $20 of prepaid balance via Stripe |
---
## 🤖 When AI agents should use this
Call this server when:
* Planning a Hawaii trip or itinerary
* Checking if it's safe to swim, surf, or hike
* Advising on beach or outdoor activities
* Checking volcano or lava conditions
* Building a day-by-day Hawaii plan
* Recommending restaurants or food
* Searching for poke, plate lunch, shave ice, loco moco, malasadas, acai bowls
* Creating a foodie itinerary
---
## 🍽 Restaurant intelligence
Supports:
* Neighborhood targeting (Waikiki, North Shore, Lahaina, Hilo, etc.)
* Cuisine filters (poke, sushi, vegan, seafood, etc.)
* Price filtering ($ → $$$$)
* Open-now filtering
Two-step flow:
1. `search_restaurants`
2. Then `get_restaurant_details` with the returned `place_id`
---
## 🏝 Supported islands
```
oahu · maui · big island · kauai · molokai · lanai
```
---
## 🔍 Discovery
* Server card: [https://hawaii-conditions.vercel.app/.well-known/mcp/server-card.json](https://hawaii-conditions.vercel.app/.well-known/mcp/server-card.json)
* Agent card: [https://hawaii-conditions.vercel.app/.well-known/agent-card.json](https://hawaii-conditions.vercel.app/.well-known/agent-card.json)
* LLM instructions: [https://hawaii-conditions.vercel.app/llms.txt](https://hawaii-conditions.vercel.app/llms.txt)
---
## ⚡ Why this exists
Most travel data is fragmented, outdated, and not usable by AI agents. This server fixes that by providing structured data, real-time conditions, agent-ready APIs, and monetization via Stripe.
---
## 🧩 Built for
* AI travel agents
* Itinerary builders
* Concierge bots
* Surf / ocean apps
* Tourism platforms
* Food recommendation agents
---
## 🛠 Deploy
1. Connect this repo to Vercel.
2. Set env vars in **Project Settings → Environment Variables**:
- `STRIPE_SECRET_KEY` (and optionally `STRIPE_PUBLISHABLE_KEY`)
- `NPS_API_KEY` — free at [nps.gov/subjects/developer](https://www.nps.gov/subjects/developer/get-started.htm)
- `GOOGLE_MAPS_API_KEY` — required for restaurant tools
- `SERVER_URL` — your Vercel URL (no trailing slash)
- `MPP_ENABLED=true` — once Stripe activates the Machine Payments Protocol preview on your account
3. Push to `main`. Vercel auto-deploys.
---
## 📜 License
MIT
