tanweiping1012-source/travel-planner
travel-planner-mvp
VerifiedCreate evidence-backed, read-only travel plans using Amap, a community 12306 rail MCP, and approved browser research. Use for 行程规划、路线安排、景点取舍、高铁或机票比较、酒店住宿比价、预算分析、旅行可行性检查,以及中国境内多城市旅行规划(境外目的地降级为浏览器辅助规划)。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.5 KB |
| agents/openai.yaml | config | 344 B |
| examples/final_plan.json | config | 2.6 KB |
| examples/itinerary.json | config | 1020 B |
| examples/rail_query.json | config | 2.9 KB |
| examples/social_research.json | config | 1.3 KB |
| examples/trip_request.json | config | 1.1 KB |
| references/browser-use.md | markdown | 14.8 KB |
| references/client-compatibility.md | markdown | 5.4 KB |
| references/data-contracts.md | markdown | 26.6 KB |
| references/intake-template.md | markdown | 4.9 KB |
| references/rail-mcp.md | markdown | 4.3 KB |
| references/script-tools.md | markdown | 3.5 KB |
| references/workflow.md | markdown | 13.3 KB |
| scripts/audit_release.shexecutable | script | 3.4 KB |
| scripts/prepare_release.shexecutable | script | 1.8 KB |
| scripts/setup_amap_key.shexecutable | script | 828 B |
| scripts/setup_rail_mcp.shexecutable | script | 3.8 KB |
| scripts/travel_planner.pyexecutable | script | 11.8 KB |
| scripts/validate_skill.pyexecutable | script | 5.5 KB |
references/rail-mcp.md
View on GitHub# Rail MCP
## Selected Project
Use `drfccv/mcp-server-12306` at the pinned commit recorded by
`scripts/setup_rail_mcp.sh`.
The connector is a community project. It directly calls public endpoints used by
the 12306 website. It is not an official developer API or an authorized sales
channel.
## Data Flow
```text
Agent
-> local MCP over stdio
-> kyfw.12306.cn public query endpoints
-> local normalization
-> Agent
```
It does not need a user account. It creates an anonymous HTTP session by loading
the public left-ticket page before each query.
## Allowed Tools
- `search-stations`
- `query-tickets`
- `query-ticket-price`
- `query-transfer`
- `get-train-route-stations`
- `get-train-no-by-train-code`
- `get-current-time`
Never add login, order, passenger, purchase, refund, or waitlist operations.
## Local Configuration
Run:
```bash
bash <SKILL_ROOT>/scripts/setup_rail_mcp.sh
```
The script installs the runtime under the user's data directory, not inside the
Skill. Set `TRAVEL_PLANNER_DATA_DIR` to override that absolute location. It
prints the absolute MCP configuration after setup. Use stdio mode. Do not expose
the optional HTTP transport or bind a network port.
For Codex, pass `--register-codex`, run `codex mcp list`, and restart Codex.
For Claude Code, add the stdio server to the `mcpServers` object in
`~/.claude.json` and restart the client:
```json
{
"mcpServers": {
"12306": {
"type": "stdio",
"command": "/absolute/path/to/uv",
"args": ["--directory", "<CHECKOUT_DIR>", "run", "mcp-server-12306"]
}
}
}
```
`<CHECKOUT_DIR>` is the path printed by the setup script. Confirm the result
with `travel_planner.py doctor`, which detects the running client on its own.
`doctor` distinguishes three registration outcomes, because they need
different fixes:
| Status | Meaning |
|---|---|
| `READY` | The entry exists and carries a `command` that could start |
| `INCOMPLETE` | The entry exists but has no usable `command` — it cannot start, so restarting the client will not help |
| `MISSING` | No entry for the server at all |
`INCOMPLETE` is what a partially hand-written entry produces. Re-run the setup
script and copy the `command` and `args` exactly as printed.
## Interpreting Results
`query-tickets` reports seat availability the way 12306 does, mixing integers
with words in a single field: an exact count while twenty or fewer remain,
`有` once supply is comfortable, and `无` when a class is sold out. Never call
`int()` on these values directly. Route every payload through
`travel_planner.py normalize-rail`, which turns each value into a record
carrying `status`, `count`, and `at_least` so candidates stay comparable.
`query-tickets` carries **no fare**. A price must come from the separate
`query-ticket-price` tool, and a plan may not state a fare that was never
looked up.
A city query returns every co-located station, so do not filter by station
name. A neighbouring station is often faster than the one the traveller named.
## Security Patch
The setup process must:
- Pin a reviewed upstream commit.
- Enable TLS certificate verification.
- Remove raw response bodies from error logs.
- Avoid logging complete tool arguments.
- Keep execution local.
Do not replace the patched checkout with an unpinned `uvx` package invocation.
## Query Sequence
For each origin, destination, and date:
1. Resolve stations.
2. Query direct tickets.
3. Query prices for viable trains.
4. Query transfers only when needed.
5. Normalize to `RailOption`.
6. Refresh selected options before final output.
## Rate Policy
- At most one new 12306 request per second.
- Cache identical station/date queries for one to five minutes.
- Retry network failures at most twice with backoff.
- Stop on CAPTCHA, block, or repeated non-JSON responses.
## Limitations
- Query dates are constrained by the 12306 sale/query window.
- Station data is bundled by the upstream package and can become stale.
- Endpoint paths and response formats can change without notice.
- The upstream license is MIT, but its README disclaims commercial use.
- Production or commercial use requires separate legal and platform review.
## Provenance
Every normalized result must include:
```json
{
"provider": "12306",
"connector": "drfccv/mcp-server-12306",
"connector_type": "community_mcp",
"official_connector": false,
"read_only": true,
"checked_at": "ISO-8601 timestamp"
}
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |