aloha.fyi MCP Server 🌺

The first dedicated Hawaii tourism MCP server. Hawaii tours, events, and deals for AI assistants — now with AAAK structured-response support so consumer agents can parse results without re-parsing prose.

When someone asks Claude, ChatGPT, or any AI "what should I do in Hawaii?" — this MCP server returns real, bookable data:

• 2,583 bookable experiences from Viator, GetYourGuide, Klook, and Groupon
• 579 events across Oahu, Maui, Big Island, and Kauai
• 540+ curated restaurants in Waikiki and across Oahu
• Live weather for all four islands (OpenMeteo)
• Day-plan itineraries with morning / lunch / afternoon / dinner picks
• Affiliate tracking on every booking link
• Real MCP protocol — Streamable HTTP, stateless, spec version 2025-03-26
• AAAK v0.1 — typed structuredContent envelope alongside human-readable text. See docs/aaak-spec.md.

Powered by aloha.fyi — Hawaii's AI concierge.

Note on canonical source. This repository is the public-facing mirror of the production mcp-server directory inside baphometnxg/Nani-V3. Production deploys are driven from there; this repo is kept in sync as a standalone reference for community use and for anyone who wants to self-host. File issues here or upstream — both work.

Hosted endpoint

Production MCP server (no install, no setup):

https://mcp-server-nani-v3-20.up.railway.app/mcp

• Transport: Streamable HTTP (stateless)
• Protocol version: 2025-03-26
• Auth: none (public, read-only)
• Health: GET /health — returns aaak: { protocol, enabled, allowlist_size } so deploy state is observable
• Discovery: GET /.well-known/mcp/server.json

AAAK — structured response contract

By default, MCP tool results come back as a prose blob — agents that want to consume the data programmatically have to re-parse markdown to recover prices, booking URLs, islands, etc. AAAK fixes that.

When AAAK is enabled (and the calling client is on the allowlist), every tool result includes a typed structuredContent field carrying the data in machine-parseable form, and the marketing trailer is dropped from text to save tokens. When AAAK is off, the wire format is byte-equivalent to v1.0.0 — no surprises for clients that don't opt in.

Lossless invariants — preserved on every revenue-bearing row:

• booking_url (affiliate revenue)
• source (compliance + attribution)
• price_cents (the only numeric field user decisions hinge on)
• island (every recommendation is island-scoped)

Example (search_hawaii_tours):

{
  "ok": true,
  "kind": "result",
  "tool": "search_hawaii_tours",
  "protocol": "aaak/0.1",
  "query": { "query": "snorkeling", "island": "oahu", "limit": 1 },
  "results": [
    {
      "title": "Hanauma Bay Snorkel",
      "source": "viator",
      "island": "oahu",
      "area": "east_oahu",
      "category": "tour",
      "price_cents": 8900,
      "rating": 4.7,
      "review_count": 2341,
      "description": "Guided snorkeling at Oahu's most famous reef...",
      "booking_url": "https://aloha.fyi/r/aB3kT9pQz1",
      "is_deal": false
    }
  ],
  "meta": { "count": 1, "cached": false, "source_diversity": 1 }
}

Full spec: docs/aaak-spec.md. Generated JSON Schema: docs/aaak.schema.json.

Verification scripts for self-hosters and contributors:

npm run aaak:test    # 12 hand-written conformance fixtures
npm run aaak:smoke   # 9 adapter-output validations
npm run aaak:gate    # ~70 env-gate / trailer / allowlist invariants
npm run aaak:verify -- --expect=aaak --ua=claude-code/1.0   # live probe

Connect to Claude Desktop

Add to your Claude Desktop config (`~/Library/Applicatio

... View full README on GitHub