Aloha Fyi Hawaii

aloha.fyi MCP 服务 🌺

首个专为夏威夷旅游打造的 MCP 服务。 为 AI 助手提供夏威夷旅游活动、事件和优惠——现已支持 AAAK 结构化响应，让消费级 Agent 无需重新解析文本即可读取结果。

当有人问 Claude、ChatGPT 或任何 AI“我在夏威夷应该做些什么？”时，这个 MCP 服务会返回真实且可预订的数据：

• 来自合作预订平台的 2,500+ 项可预订体验（实时数量：/health）
• 涵盖 Oahu、Maui、Big Island 和 Kauai 的实时活动，每周更新
• 涵盖各岛屿的 600+ 家精选餐厅
• 夏威夷四大岛的实时天气（OpenMeteo）
• 每日行程，包含上午／午餐／下午／晚餐推荐
• 为每个预订链接提供联盟跟踪
• 真正的 MCP 协议——Streamable HTTP、无状态、规范版本 2025-03-26
• AAAK v0.1——在便于人类阅读的文本旁提供类型化的 structuredContent 封装。请参阅 docs/aaak-spec.md。

由 aloha.fyi 提供支持——夏威夷的 AI 礼宾服务。

关于权威源的说明。 本仓库是生产环境中 baphometnxg/Nani-V3 内 mcp-server 目录的公开镜像。生产部署由该仓库驱动；本仓库作为独立参考供社区使用，也方便任何想要自托管的人使用。你可以在这里或上游仓库提交问题，两处均可。

---

托管端点

生产环境 MCP 服务（无需安装或设置）：

https://mcp.aloha.fyi/mcp

• 传输方式：Streamable HTTP（无状态）
• 协议版本：2025-03-26
• 身份验证：无（公开、只读）
• 健康状态：GET /health — 返回 aaak: { protocol, enabled, allowlist_size }，以便查看部署状态
• 服务发现：GET /.well-known/mcp/server.json

---

AAAK — 结构化响应约定

默认情况下，MCP 工具结果以文本形式返回——希望以编程方式使用数据的 Agent 必须重新解析 Markdown，才能提取价格、预订 URL、岛屿等信息。AAAK 解决了这个问题。

启用 AAAK 后（且调用方客户端在允许列表中），每个工具结果都会包含类型化的 structuredContent 字段，以机器可解析的形式承载数据，并从 text 中移除营销尾注以节省令牌。关闭 AAAK 时，传输格式与 v1.0.0 按字节完全一致——未选择启用的客户端不会遇到意外变化。

无损不变量——每条带来收入的记录均会保留：

• booking_url（联盟收入）
• source（合规性 + 归属信息）
• price_cents（用户决策所依据的唯一数值字段）
• island（每条推荐都对应特定岛屿）

示例（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 }
}

完整规范：docs/aaak-spec.md。生成的 JSON Schema：docs/aaak.schema.json。

供自托管用户和贡献者使用的验证脚本：

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

---

连接到 Claude Desktop

将以下内容添加到 Claude Desktop 配置文件（macOS 上为 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "aloha-fyi-hawaii": {
      "url": "https://mcp.aloha.fyi/mcp"
    }
  }
}

重启 Claude Desktop。你应该会在工具选择器中看到六个夏威夷工具。试试：

帮我找找 Oahu 上 100 美元以下的浮潜之旅

这个周末 Honolulu 有什么活动？

规划一天 Big Island 家庭探险行程——选择最便宜的项目

---

连接到任何兼容 MCP 的客户端

任何支持 Streamable HTTP MCP 的客户端都可以直接连接到：

https://mcp.aloha.fyi/mcp

无需 API 密钥、OAuth 或注册。

手动协议测试

curl -X POST https://mcp.aloha.fyi/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

---

工具

search_hawaii_tours

按关键词、岛屿和价格范围搜索 2,500 多种可预订的夏威夷旅游和活动。返回包含预订链接的旅游项目；可通过 source 按平台筛选。

参数	类型	描述
query	string（必填）	例如：“浮潜”“直升机观光”“家庭 luau”
island	oahu | maui | big_island | kauai | any	默认为 any
max_price_dollars	number	每人最高价格（美元）
source	viator | gyg | klook | groupon | any	按预订平台筛选
limit	number	结果数量（最多 20 个，默认为 5 个）

get_hawaii_deals

查找经济实惠的优惠和折扣。返回打折和低价选项，并按价格从低到高排序。

参数	类型	描述
activity	string（必填）	例如：“浮潜”“直升机观光”“luau”
max_price_dollars	number	默认为 100
limit	number	结果数量（最多 20 个，默认为 5 个）

search_hawaii_events

查找夏威夷所有岛屿即将举行的活动、音乐会、节庆和夜生活项目。每周根据场馆和主办方来源更新。

参数	类型	描述
query	string	例如：“现场音乐”“luau”“音乐会”
island	oahu | maui | big_island | kauai | any	默认为 any
days_ahead	number	搜索未来多少天（默认为 7 天）

---

自行运行

git clone https://github.com/baphometnxg/aloha-fyi-mcp.git
cd aloha-fyi-mcp
npm install
npx tsc
DATABASE_URL="postgresql://..." PORT=9624 node dist/http.js

需要：

• Node.js 20+
• DATABASE_URL 环境变量（使用 PostgreSQL，并包含 experiences 表——架构见 schema.sql）

---

隐私

此 MCP 服务不会收集个人身份信息（PII）。无状态模式——不保存会话，也不跨请求建立用户档案。仅为防止滥用而记录标准请求元数据。

完整隐私政策：aloha.fyi/privacy

---

关于

由 Michael Crain 构建——他是夏威夷居民、电影摄影师，也是 aloha.fyi 的创始人。

aloha.fyi 是一款 AI 驱动的多语言旅游礼宾服务，面向夏威夷旅游业。礼宾 Agent“Nani”支持 5 种语言（英语、日语、韩语、中文、西班牙语），并可访问多个合作平台上的 2,500 多种可预订体验。

此 MCP 服务将其中部分能力提供给任何支持模型上下文协议的 AI 助手。

• 网站：https://aloha.fyi
• 联系方式：[email protected]
• 许可证：MIT

---

以 aloha 为初心构建。由 AI 驱动。扎根于夏威夷文化。 🌺