Skip to content

tanweiping1012-source/travel-planner

travel-planner-mvp

Verified

Create evidence-backed, read-only travel plans using Amap, a community 12306 rail MCP, and approved browser research. Use for 行程规划、路线安排、景点取舍、高铁或机票比较、酒店住宿比价、预算分析、旅行可行性检查,以及中国境内多城市旅行规划(境外目的地降级为浏览器辅助规划)。

FileKindSize
SKILL.mdskill md12.5 KB
agents/openai.yamlconfig344 B
examples/final_plan.jsonconfig2.6 KB
examples/itinerary.jsonconfig1020 B
examples/rail_query.jsonconfig2.9 KB
examples/social_research.jsonconfig1.3 KB
examples/trip_request.jsonconfig1.1 KB
references/browser-use.mdmarkdown14.8 KB
references/client-compatibility.mdmarkdown5.4 KB
references/data-contracts.mdmarkdown26.6 KB
references/intake-template.mdmarkdown4.9 KB
references/rail-mcp.mdmarkdown4.3 KB
references/script-tools.mdmarkdown3.5 KB
references/workflow.mdmarkdown13.3 KB
scripts/audit_release.shexecutablescript3.4 KB
scripts/prepare_release.shexecutablescript1.8 KB
scripts/setup_amap_key.shexecutablescript828 B
scripts/setup_rail_mcp.shexecutablescript3.8 KB
scripts/travel_planner.pyexecutablescript11.8 KB
scripts/validate_skill.pyexecutablescript5.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"
}
```
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: 472kUpdated Claude CodeCodexVerifiedInstall
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: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 323kUpdated Claude CodeCodexVerifiedInstall