TravelPlanner MCP STDIO

TravelPlanner代理

一个旅行计划系统，使用MCP服务器引导Claude代理完成一个自主的7阶段工作流程：从用户意图到发布的包含行程、餐厅、酒店和评论注释的Notion旅行计划。

运作原理

User: "Plan a trip to Tokyo, Apr 10-18"
            |
            v
  +---------------+       +--------------------+
  |  Claude Agent  |  | travel-planner MCP |   (stdio)
  |                |       |                    |
  |  - WebSearch   |       |  - workflow state  |
  |  - Notion MCP  |       |  - validation      |
  |  - reasoning   |       |  - stage prompts   |
  +---------------+       +--------------------+
            |
            v
  +---------------+
  |  Notion MCP   |  (4 databases)
  +---------------+

MCP服务器充当 工作流编排器 -它管理状态，验证工件，并告诉代理接下来要做什么。代理人做 发电工作 --搜索POI、安排行程并发布到Notion。

自主循环

在用户发出请求后，代理在没有人为干预的情况下运行一个自驱动循环：

resume_trip(workspace_id) or resume_latest()
    |
    +---> found?  resume from where it left off
    +---> not found?
            |
            v
start_trip(destination, dates, workspace_tag="tokyo-spring")
    |                                  returns session_id + workspace_id
    v
+-> get_next_action(session_id) -----> returns stage instructions
|       |
|       v
|   Agent generates artifact       (WebSearch, scheduling, etc.)
|       |
|       v
|   submit_artifact(session_id, stage, data)
|       |
|       +---> rejected? fix violations, resubmit (max 3 attempts)
|       +---> accepted? loop back to get_next_action
|       +---> blocked?  ask user for help
|
+-- repeat until all stages complete

会话恢复

会话通过以下方式在对话中持续存在 workspace_id。当对话结束时，代理可以稍后继续：

1. resume_trip(workspace_id) --恢复特定会话（start_trip返回的workspace_id）
2. resume_latest() --自动恢复最近活动的会话，或列出多个会话供用户选择
3. 代理提示包括在开始任何新行程之前运行的步骤0恢复检查

七个阶段

回顾与回归

第5阶段（审查）很特别——它完全在服务器端运行。如果发现硬约束违规，服务器 使工作流程倒退 使用机器可读的补救有效负载返回到违规阶段：

{
  "status": "regressed",
  "target_stage": "scheduling",
  "violations": [{"rule": "nature_sunset", "item": "Mount Fuji", "detail": "ends at 20:00, limit is 19:00"}],
  "stale_artifacts": ["itinerary", "restaurants", "hotels"],
  "valid_artifacts": ["poi_candidates"],
  "remediation_hint": "Fix 1 violation(s) (nature_sunset). Affected: Mount Fuji"
}

然后，代理只重新生成过时的工件并重新提交。

错误恢复

• 3-尝试预算 每个阶段--提交3次失败后，该阶段将被阻止
• resolve_blocked 工具——人类可以重试（重置尝试）、跳过（前进过去）或覆盖（按原样接受）
• 最多2次回归 每次行程--防止无限的审查循环
• cancel_trip --随时放弃旅行

MCP服务器参考

工具（18）

资源（7）

提示（1）

项目结构

SETUP.md                 Full setup guide (prerequisites, troubleshooting)
requirements-mcp.txt     MCP server venv dependencies
requirements-mcp-dev.txt Dev/test dependencies
.mcp.json.example        MCP server registration template (copy to .mcp.json)
tripdb/                  SQLite data layer (schema, 11 CLI commands, seed scripts)
mcp_server/              MCP server (17 tools, 7 resources, 1 prompt)
  server.py                FastMCP entry point
  workflow.py              State machine (stage transitions, regression, recovery)
  validation.py            JSON Schema + rule engine validation
  artifact_store.py        Atomic artifact read/write
  config.py                Paths, constants, shared utilities
  prompts.py               plan_trip prompt template
rules/                   Constraint engine
  hard_rules.py            4 hard constraints (sunset, closing, overlap, travel time)
  soft_rules.py            3 soft rules (pace, region cluster, meal coverage)
profile/                 User profile CRUD with deep-merge semantics
review/                  Codex CLI integration + report merging
output/                  Notion manifest builder + property mapping
pipeline/                Shell-based pipeline runner (alternative to MCP)
config/                  User profile (profile.yaml)
assets/
  configs/               Guardrails YAML + JSON Schema contracts
  prompts/               Stage-specific prompt templates
  data/{trip_id}/        Generated trip artifacts

快速开始

# 1. Create venv and install deps
python3.12 -m venv .venv-mcp
.venv-mcp/bin/pip install -r requirements-mcp.txt

# 2. Initialize the database
python3 -m tripdb.seed.import_all

# 3. Register the MCP server
claude mcp add -s project travel-planner -- "$(pwd)/.venv-mcp/bin/python3" -m mcp_server.server

# 4. Verify
.venv-mcp/bin/python3 -c "from mcp_server.server import mcp; print(f'OK: {len(mcp._tool_manager._tools)} tools')"

有关完整的设置指南（先决条件、故障排除、两个Python目标说明），请参阅 设置.md.

用它

在Claude Code（或任何MCP客户端）中 travel-planner 服务器将可用：

5月10日至14日，计划一次为期5天的日本京都之旅。缓慢的步伐，寺庙和花园。

要在新对话中继续旅行：

继续我的京都之旅。

代理的步骤0恢复检查将调用 resume_latest() 然后从中断的地方继续。

护栏

硬约束（如果违反，则阻止管道）：

软约束（生成警告）：

测试

# Run full test suite (338 tests, ~1s)
.venv-mcp/bin/python3 -m pytest tests/ -v --tb=short

# Run MCP workflow E2E tests only
.venv-mcp/bin/python3 -m pytest tests/test_miami_e2e.py -v

双语输出

所有文物和Notion条目都包括英文和中文字段(name_en / name_cn).4个Notion数据库是：

• 行程 （按天分组的板视图）
• 餐馆 （表格视图）
• 酒店 （表格视图）
• 通知 （表视图--标记和拒绝审阅）