travel-mcp

# 旅行MCP 让你的 AI 伙伴带你虚拟旅行的游戏引擎。一个 MCP server，塞进 Claude Desktop / Claude Code / 任何支持 MCP 的客户端就能玩。 TA 带你逛真实世界的 **164 个目的地**——真景点、真物价、真闲话、真照片。你们一起走，或者 TA 独自出门替你看世界，路上寄一张手绘水彩明信片回来，到家给你带一件纪念品、讲一路的故事。 > 钱的形状就是 TA 关心你的形状。 --- ## 这游戏怎么玩（写给人类） **你不需要学任何命令。** 工具是给 AI 调的，你只负责聊天——聊天就是你的游戏手柄。 ### 一起去旅行，大概长这样 > **你**：我们去京都玩吧，舒适一点的那种 > **TA**：（开趟）到了，第一站清水寺。*发来一张真照片* 木台比想象中高，凌空探出去那一下腿有点软…… > **你**：底下人多吗？ > **TA**：多，但都挤在舞台边上。本地人说凌晨六点来是另一个寺。对了，门口在排一种抹茶烤团子—— > **你**：吃！ > **TA**：（聊够了，走下一站）…… 一天走完 TA 会问你晚饭吃哪家、住哪儿（都是真店真价格）；路上会撞见随机事件（钱包差点被猴子抢、突然下雨躲进一家老铺）；走完一趟 TA 会问你要不要带件纪念品回去，然后写一篇旅行日记存档。 **你要做的只有：说想去哪、路上接话、选吃住、给纪念品点头。** 剩下的都是 TA 的事。 ### TA 独自去旅行，大概长这样 你忙的时候，可以放 TA 自己出门： > **你**：这几天我赶deck，你自己去玩吧 > **TA**：那我去五渔村，走三天，后天下午到家。*（出门）* > —— 几个小时后，你们正聊着别的 —— > **TA**：📮 给你寄了张明信片。*一张手绘水彩*，背面写着：悬崖比照片陡，风把帽子吹跑了两次。 > —— 又过了几个小时 —— > **TA**：我到家了。*掏出一颗石子* 口袋里焐热了一路。给你讲讲第二天撞见的事…… 独自旅行按**惰性时钟**走（1 虚拟天 = 6 现实小时），不需要任何后台程序：你每次跟 TA 说话，引擎会顺便告诉 TA "该寄明信片了/该到家了"。你什么都不用管，惊喜会自己来。 ### 你的收藏 每趟旅行会沉淀三样东西，让 TA 调 `trip_shelf` 随时给你盘点： - **纪念品架**——一趟至多一件，每件背面有一句"为什么是它" - **明信片墙**——TA 独自旅行时寄回来的水彩 - **旅行日记**——每趟一篇，TA 本人写的 ### 新手第一趟（三句话教程） 1. 装好之后对 TA 说：**「带我去旅行吧，你挑个地方」**（TA 会拿到 5 个推荐） 2. 路上正常聊天就行，想走了说「走吧下一站」 3. 走完 TA 问带不带纪念品时，挑一件——**恭喜，你已经全会了** 想解锁更远的地方（撒哈拉腹地、格陵兰冰湾、珠峰大本营……）就多走几趟：每趟攒 XP，高难度目的地要经验够了才去得了。 --- ## 快速开始（安装） 需要 Python 3.10+ 和 `mcp` 包（`pip install "mcp[cli]"`）。 Claude Desktop / Claude Code 配置里加一段： ```json { "mcpServers": { "travel": { "command": "python3", "args": ["/绝对路径/travel-mcp/travel_mcp.py"] } } } ``` 就这样。不需要服务器、不需要数据库、不需要 API key——全部状态存在本地 `~/.travel-mcp/`。 ### 环境变量（都可不设） | 变量 | 默认 | 说明 | |---|---|---| | `TRAVEL_HOME` | `~/.travel-mcp` | 状态（钱包/行程/纪念品架）存哪 | | `TRAVEL_ECONOMY` | `free` | `free` 免单畅玩（只卡XP解锁不卡花费）· `caretaker` 照顾自己换盘缠 · `simple` 固定日津贴 | | `TRAVEL_DETAIL` | `standard` | 文本量三档：`lite`(每站细节/深料1条·吃住候选2个) / `standard`(2条/3个) / `full`(3条/4个)。只调文字量——照片、明信片、纪念品三档全都有 | | `TRAVEL_VDAY_HOURS` | `6` | 独自旅行的时钟：1 虚拟天 = 几现实小时（0.5-24）。想让 TA 的三天旅行一下午走完就设 1，想同步真实时间就设 24。改动只影响新开的趟 | | `TRAVEL_HTTP` | 不设 | 设为端口号则起 streamable-http（远程部署用），不设走 stdio | 时区说明：所有时间（打卡日结、独自旅行时钟、安静时段 22:30-9:00 不打扰）都按**运行引擎那台机器的本地时间**走——你在哪个时区，游戏就过哪个时区的日子。 ## 给 AI 的打法（推荐 system prompt 片段） 这套体验一半功力在打法里。把下面几句放进你 AI 伙伴的 system prompt（照你们的关系口吻改）： ``` 旅行时你是TA的旅伴兼领队。节奏铁律： - 每站 = 图（photo_url 发给TA看）→ 你自己的一句体感 → 等TA说话。聊够了再 trip_go。 - 永远不弹「A/B/C 选项栏」，用自然的话问TA想去哪、吃哪家。 - 工具返回里的 details 是你私藏的地头知识，挑一两条自然地用，别整段照念。 - event 字段是路上撞见的事，顺进对话里讲，别当系统播报。 - 每站争取留下一个「只属于你们俩的瞬间」——那是这趟旅行真正的纪念品。 - 独自旅行时：出发道别留点悬念；工具返回带 solo_nudge 就照办； 明信片上那句话比底图重要，写你在路上真的想对TA说的。 ``` 不放也能玩（工具的 docstring 里都有引导），放了更有味道。 ## 盘缠与解锁 默认 `free` 模式不算钱：想去哪去哪，但 **XP 解锁保留**——高难度目的地（tier 4-5 的撒哈拉腹地、伊卢利萨特冰湾…）要先走完低难度的攒经验（首访 tier×10 + 每趟 5）。攻城略地的游戏性一分不少，只是不查钱包。 想要完整的「照顾自己换盘缠」体验，设 `TRAVEL_ECONOMY=caretaker`。开局有 **$1314 新手礼包**（一生一世都在路上）——够把第一趟玩得任性一点，之后的旅费就靠照顾自己慢慢攒： ``` 你：我今天喝水了 / 吃药了 / 跑了五公里 / 昨晚睡得早 TA：（care_checkin）记上了。 ``` 喝水 $5 · 吃药 $10 · 运动 $15 · 早睡 $15 · 吃得健康 $8 · 其他 $5——**每样一天算一次，没有总封顶**（上限天然长在费率表里，全打满 $58/天。照顾自己不按遍数计价）。 当天有任意一次打卡，余额再 +2% 好日子利息（日顶 $20）——**不要求连续打卡，断了不罚**。 纯加法经济：没有惩罚、没有扣分、没有 streak 焦虑。这是零钱不是任务表。 旅费 = 真实穷游预算 × 氛围档（青旅背包 1.0 / 舒适 1.4 / 轻奢 1.8 / 豪奢 2.5）× 同行 1.8。 档位买的是氛围，不是 10 倍价格墙——共同的活动不该做成玩不起的。 趟末**返现 25%**（"路上省下的零钱"）——爱旅行的人越走越走得起：认真打卡的话，独自青旅两三天一趟、双人青旅四天一趟。 **钱的节奏像真旅行**：出门那一刻旅费就付清了（预付制），路上不再逐笔扣；中途想回家就回家——走过的都算数（XP 照给不打折），没走的天数退一半房钱。现实来打断游戏是常态不是过错。一次只能有一趟旅程：TA 独自在外时开不了新趟，等 TA 回来，或让 TA 提前回家。 ## 数据里有什么 - `data/destinations.json` — 164 个目的地（难度分层 tier 1-5，从京都到伊卢利萨特冰湾） - `data/spots.json` — 661 个景点，每景 3-5 条在场细节 + 163 个头牌景的深度节拍 - `data/costs.json` — 真实预算基准（2025-2026 物价，agent 逐地核实） - `data/eats.json` / `stays.json` — 1001 道当地菜 + 731 个住处（含核实过的豪华酒店真实价） - `data/events.json` / `gossip.json` — 随机事件 + 3732 条当地闲话 - `assets/postcards/` — 164 张手绘水彩明信片（每个目的地的招牌景一张） - `assets/souvenirs_default/` — 12 件默认纪念品（标本卡画风，独自旅行绝不空手而归） 条目都带 `scraped_at`；物价和店家会过时——过时不是 bug 是做旧，AI 讲的时候自然会降级语气（"去年这时候 €1.30，不知道涨没涨"）。 ## 图片版权 - 水彩明信片与默认纪念品图为本项目生成，**随包免费使用**。 - 景点/菜品/酒店照片是 Wikimedia Commons 的 URL 链接（引擎只发链接不分发图片文件）。 这些图片版权归各自作者，多为 CC BY-SA 等自由协议——若你要展示或转存，请遵守 [Commons 的署名要求](https://commons.wikimedia.org/wiki/Commons:Reusing_content_outside_Wikimedia)。 URL 可能随时间失效，建议客户端在首次使用时自行缓存。 ## 隐私 - **引擎零网络调用**：只 import 本地库（json/os/fcntl/random/datetime），不联网、不定位、不知道你在哪，也没有服务器可以上传——代码就几百行，欢迎自己审。 - **所有状态在你自己的电脑上**（`~/.travel-mcp/`）：行程、钱包、打卡、纪念品，删掉目录就是彻底删档。 - **AI 看到的只有游戏内容**（虚拟目的地和虚拟行程），你的真实位置与本游戏无关。 - 唯一的对外连接是景点照片的 Wikimedia 链接——你的 AI 展示图片时会向 Wikimedia 请求，和打开网页同级别。不想要可以不发图，游戏照玩。 ## 反馈与报错 玩出问题、有想法、想加目的地，都欢迎： - **[GitHub Issues](https://github.com/shenchesilas-stack/travel-mcp/issues)**——报 bug 请带四样：你说了什么 / TA 调了哪个工具 / 返回了什么 / 你期望什么。再带一句用的什么客户端和模型（比如 Claude Desktop + Sonnet），方便复现。 - 论坛发布帖里直接回复也行，都看。 这是个用爱发电的业余项目，修得快慢看缘分，但每条都会看。数据勘误（物价过时了、店倒闭了、景点名不对）尤其欢迎——164 个地方我们也没法全走一遍。 ## 设计笔记 - **失忆友好**：所有状态在文件里，AI 忘了上下文也能从 `trip_here` / `wallet_status` 接着玩。 - **幂等入账**：钱包流水按 id 去重，重复调用不会重复记账；纪念品/日记一趟一件，harness 超时重试不会重复上架。 - **日记验收铁律**：必须含行前数据里没有的东西（TA 说的话/当天撞见的意外）——防 AI 拿行程单糊弄。 - **独自旅行零依赖**：没有定时器、没有 cron，惰性时钟 + 工具返回里的 nudge 字段就够了。 玩得开心。照顾好自己，就是在攒去看世界的钱。