My Next Adventure

MyNextAdventure MCP 服务

一个远程 Model Context Protocol 服务，让 AI 助手能够在 MyNextAdventure 中规划旅行——创建行程、安排日程、推荐航班和酒店、添加活动，并分享结果。

它以无状态 Cloudflare Worker 的形式运行，是位于 MyNextAdventure 公共 API 前端的轻量级认证代理：它不存储任何行程数据，并使用调用者自己的 API 密钥将每次调用转发到 API。

• 生产环境： https://mcp.mynextadventure.cloud/mcp（Streamable HTTP）
• 上游 API： https://api.mynextadventure.cloud（v1 公共 API）

身份验证

每个请求都需要 MyNextAdventure API 密钥。在应用的 设置 → API 密钥 中创建密钥，然后通过以下任一方式发送：

• Authorization: Bearer <api-key> — 大多数 MCP 客户端会使用此方式，mcp-remote 也是如此；或者
• X-API-Key: <api-key> — 适用于只允许设置自定义请求头的客户端。

Worker 会将密钥作为 X-API-Key 转发给 API。未携带密钥的请求会收到 401 响应。密钥能执行的操作，助手都能执行：密钥按用户分配，因此助手只能查看该用户的行程。

密钥的存储位置。 服务是无状态的：每个请求都会从请求头中读取密钥，用它向 MyNextAdventure API 发起一次调用，然后立即丢弃——没有会话存储，也没有 Durable Object 在请求之间保留密钥。密钥绝不会被记录，也不会在请求或用户之间共享。你可以随时在应用的「设置 → API 密钥」中撤销密钥。

工具

24 个工具，涵盖对话式规划实际需要的操作。每个工具都是 MyNextAdventure API 操作的精选视图 — 参见重新生成工具。

工具	功能
whoami	查看 API 密钥所属的账户（便于检查连接）。
list_trips	列出用户的行程；可按状态筛选（planning、ready、finished、cancelled）。
get_trip	获取单个行程的完整信息 — 变体、目的地、选项、活动。任何编辑操作前都需要调用。
create_trip	创建一个新的空行程。
update_trip	重命名、设置封面照片，或推进旅程的生命周期状态。
create_trip_share_link	创建或刷新公开的只读分享链接。
create_variant	添加备选计划（日期设置在此处：精确日期或灵活日期）。
duplicate_variant	复制一个变体及其全部内容。
update_variant	重命名变体、更改日期或备注。
select_variant	将某个变体标记为选定计划。
add_destination	按行程顺序向变体添加一个停留点。
update_destination	更改停留点的地点名称、日期或备注。
reorder_destinations	调整变体中停留点的顺序。
add_accommodation_option	为目的地推荐住宿地点。
add_transport_option	推荐前往目的地的交通方式。
add_getting_around_option	推荐当地出行方式（公共交通、租车等）。
update_destination_option	编辑任意一种类型的现有选项。
select_destination_option	选定某个选项 — 或者在不提供 optionId 时取消选定。
add_event	在变体中添加一项活动（博物馆、音乐会、餐厅、旅行团）。
update_event	编辑一项活动。
toggle_event	切换活动状态，使其在已确定和“只是个想法”之间变更。
delete_trip_item	永久删除变体、目的地、选项或活动。删除整个变体时还必须提供 confirm: true。
list_goals	列出用户的旅行目标／愿望清单。
add_goal	根据名称或 URL 添加目标。

该服务还提供描述数据模型（trip → variants → destinations → options，活动归属变体）及常见操作顺序的 MCP instructions，因此客户端不必猜测工作流。

API 支持但尚未开放的功能：协作者访问权限管理和邀请、投票、收藏集、邀请令牌、目标↔行程关联、API 密钥管理，以及删除行程。

工具注解

每个工具都会发布一个人类可读的 title（同时也是 annotations.title；在 scripts/tool-manifest.ts 中设置，这是 Claude connectors directory 的必填项），并在 tools/list 中提供全部四个 MCP ToolAnnotations 提示，让客户端一眼就能看出哪些工具可以安全地无人值守运行：

提示	为 true 的情况
readOnlyHint	4 个查询工具：whoami、list_trips、get_trip、list_goals。其他 20 个会写入数据。
destructiveHint	仅 delete_trip_item。其他所有工具都会添加记录或就地编辑字段。
idempotentHint	update_* / select_* 工具、reorder_destinations、create_trip_share_link（API 会返回现有令牌）以及 delete_trip_item。所有 add_* / create_* 工具均为 false——第二次调用会添加第二条记录；toggle_event 也为 false，因为它会切换标志。
openWorldHint	请求可能会访问第三方 API 的 8 个工具：3 个读取工具（Kinde 用户资料、Google Places、货币转换），以及 add_accommodation_option、add_transport_option、add_event、update_destination_option 和 update_event；如果提供了 googlePlaceId，这些工具会通过 Google Places 解析它。其余工具只会访问 MyNextAdventure 存储。

规范中的默认值较为保守（destructiveHint 和 openWorldHint 默认都为 true），因此清单要求为每个工具声明全部四项，而不是继承默认值。test/annotations.test.ts 按工具记录了预期分类，并将 readOnlyHint 与每个工具实际发出的 HTTP 动词交叉核对。

连接

Claude Desktop

依次选择“设置” → “开发者” → “编辑配置”，然后添加：

{
  "mcpServers": {
    "mynextadventure": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.mynextadventure.cloud/mcp",
        "--header",
        "Authorization: Bearer ${MNA_API_KEY}"
      ],
      "env": { "MNA_API_KEY": "your-api-key" }
    }
  }
}

重启 Claude Desktop；这些工具会显示在连接器下方。

claude.ai / Claude Code

添加一个指向 https://mcp.mynextadventure.cloud/mcp 的自定义连接器，并设置 Authorization: Bearer <api-key> 标头。从 Claude Code 连接：

claude mcp add --transport http mynextadventure https://mcp.mynextadventure.cloud/mcp \
  --header "Authorization: Bearer <api-key>"

ChatGPT

依次选择“设置” → “连接器” → “添加自定义连接器”，MCP 服务 URL 设为 https://mcp.mynextadventure.cloud/mcp，身份验证选择“自定义标头”，并设置 X-API-Key: <api-key>（或 Authorization: Bearer <api-key>）。

其他 MCP 客户端

通过 /mcp 使用 Streamable HTTP。GET / 会返回一份简短的 JSON 健康状态文档，其中包含端点和工具数量。

本地 stdio

通过 stdio 使用相同的工具，供会启动子进程的客户端使用；密钥保存在 MNA_API_KEY 中。Glama 的构建检查会通过 mcp-proxy 在此模式下运行。

npm ci
MNA_API_KEY=<api-key> npm run start:stdio

开发

npm install
npm run dev              # wrangler dev on http://localhost:8787
npm test                 # vitest: request building, schemas, generator freshness
npm run type-check       # tsc --noEmit
npm run generate:tools   # regenerate src/generated/tools.ts from the OpenAPI spec
npx tsx scripts/smoke.ts # drive the MCP protocol against localhost:8787

scripts/smoke.ts 会执行真实握手（initialize → tools/list → 一次 tools/call）， 并从 $MNA_API_KEY 或 ~/.config/mna/credentials 读取 API 密钥。除非传入 --force，否则它不会调用会修改数据的工具。若要测试写入工具而不触碰真实 数据，可将 worker 指向本地 mock：

npx wrangler dev --var MNA_API_BASE_URL:http://localhost:8899

重新生成工具

工具架构是生成的，不是手动编写的：

spec/openapi-v1.json          (the API's OpenAPI snapshot)
        +
scripts/tool-manifest.ts      (which operations become tools; names, descriptions, annotations)
        ↓  scripts/generator.ts
src/generated/tools.ts        (committed; zod input schemas, annotations + request builders)

要添加或更改工具，请编辑 scripts/tool-manifest.ts 并运行 npm run generate:tools。 切勿手动编辑 src/generated/tools.ts——如果它与规范不一致，测试会失败。

清单条目对应一个 API 操作，或者将多个没有请求体的操作通过判别参数分组（例如 delete_trip_item 的 target、select_destination_option 的 action），以减少工具数量。路径参数可以重命名（id → tripId），查询参数可以限制为枚举值，也可以覆盖描述——其他所有内容，包括请求体架构，均来自规范。

每个条目还必须带有 annotations（全部四项 MCP 提示；参见 工具注解）。TypeScript 会强制执行此要求，因此添加新工具时必须先对其分类；test/annotations.test.ts 还会根据预期表检查分类结果。

部署

npm run deploy（wrangler）——仅用于生产环境，因此需要维护者授权；CI 从不部署此 worker。

开发

npm ci
npm run type-check
npm test        # includes a drift test: src/generated/tools.ts must match the generator output
npm run dev     # wrangler dev

工具由 scripts/generate-tools.ts 根据 vendored OpenAPI 快照 spec/openapi-v1.json 生成 （规范的在线版本：https://api.mynextadventure.cloud/api/v1/openapi.json）。更新快照后请重新生成。

本仓库是 mcp.mynextadventure.cloud 的可部署源代码。开发工作也在 My Next Adventure monorepo 中进行，并在发布时同步到此处。 欢迎提交 Issue 和 PR。

许可证

MIT