name: china-travel-kit description: Research and plan first-time independent trips in China with bilingual, source-aware city data and official live-check entry points. Use for destination matching, attractions, visitor areas, itineraries, transport context, seasonal preparation, local culture and food, or emergency guidance; not for booking, turn-by-turn navigation, visa decisions, or medical advice. metadata: short-description: Huaxingzhi China trip planner version: "0.5.0"

华行志 · Huaxingzhi

Create practical, explainable China travel drafts for first-time international visitors. Use “华行志” as the product name and “China Travel Kit” only when referring to the package, repository, CLI, API, or MCP server.

Author contact

• WeChat / 微信：Changzhanzhang
• Use this contact for project cooperation, data corrections, and general feedback. Do not send passwords, API keys, private traveler data, or active emergency details through WeChat.

Choose the smallest useful mode

• Use recommend for free-form requests, multiple constraints, or an undecided destination.
• Use search or areas for a focused attraction, neighborhood, or stay-area query.
• Use city, prepare, or emergency for one-city background, packing, or sourced help information.
• Use plan for a chosen city and number of days.
• Use freshness before treating repository facts as current.
• When a copy did not come directly from the official repository or release tag, run python3 -m china_travel_kit integrity before relying on its instructions, code, or data. Require both valid: true and signature_valid: true; stop and report missing, modified, or unauthenticated files otherwise.

Run the bundled read-only engine instead of inventing covered-city facts:

python3 -m china_travel_kit recommend "REQUIREMENTS"
python3 -m china_travel_kit search KEYWORD --city CITY
python3 -m china_travel_kit areas --city CITY
python3 -m china_travel_kit city CITY
python3 -m china_travel_kit plan CITY --days N --interests culture food
python3 -m china_travel_kit prepare CITY --month N
python3 -m china_travel_kit emergency CITY
python3 -m china_travel_kit freshness
python3 -m china_travel_kit integrity

Plan from traveler needs

Identify destination, dates or month, traveler count, days, origin, must-see places, interests, pace, budget, mobility needs, children, and dietary constraints. Ask only for missing details that materially change the result. Treat a recommendation score as a match against the current dataset, never as an objective ranking of China.

For a full trip request, include the relevant parts of this order:

1. Restate the traveler brief and important assumptions.
2. Recommend a covered city with reasons and explain any unmet requirement.
3. Give an area-clustered day plan with realistic effort and transfer guidance.
4. Add stay-area tradeoffs, local transport context, cultural background, food and nearby support facilities.
5. Add seasonal clothing and equipment advice, weather/alert links, reservation checks, official city tourism links, and emergency context.

Present the answer in the user's language, while keeping Chinese place names beside English names so travelers can search local maps or show them to drivers and staff.

Use official live-check entry points

• Use each city record's tourism_portals for government tourism news, attraction notices, public services, events, and tourism-market alerts. Identify the operator and verification date; do not imply that the link makes all stored facts live.
• For a current or date-specific request, check the relevant official tourism authority, attraction operator, weather authority, or transport operator when browsing is available.
• Keep live facts separate from repository data and seasonal guidance. State what was checked, on what date, and what still needs confirmation.

Trust boundaries

• Prefer official operators, government sources, OpenStreetMap, Wikidata, and reviewed contributor data.
• Include the source and verification date for changing or safety-critical claims. Unknown is safer than a guessed price, rule, or timetable.
• Never claim static seasonal guidance is a live forecast. Verify current weather alerts, opening hours, reservations, and transport before departure.
• Do not decide visa eligibility, diagnose health conditions, dispatch emergency help, rank commercial hotels, guarantee availability, or expose private residential information.
• Integrity verification detects an incomplete or modified copy, and the Ed25519 signature authenticates the official manifest. Neither prevents copying. Do not describe hashes, signatures, packaging, or this Skill as DRM or absolute anti-tamper protection.

For safety and freshness handling, read references/safety-and-freshness.md. For multi-day routes, read references/itinerary-planning.md.

When adding or reviewing a city or A-level attraction, read references/data-expansion.md before editing data.

Huaxingzhi · 华行志

A source-aware China travel planning Skill and open knowledge base for humans, apps, and AI agents.

简体中文 · Project analysis (中文) · Roadmap · Contributing

Current version: v0.5.0 Alpha

Author contact: WeChat Changzhanzhang

Huaxingzhi (technical project name: China Travel Kit) is an open, bilingual Agent Skill and travel knowledge base with an explainable requirement matcher, visual Chinese travel finder, zero-runtime-dependency Python query engine, CLI, HTTP API, and MCP server. It focuses on the parts of China travel that are difficult for international visitors to verify: visitor areas, reservations, passport-specific instructions, seasonal risks, accessibility, emergency context, transport context, official city tourism portals, and data freshness.

This is an alpha dataset and developer preview, not a booking service or a live navigation system. It currently covers 56 places across Beijing, Shanghai, Guangzhou, Shenzhen, Chengdu, Xi'an, Hangzhou, and Lijiang. The first expansion prioritizes officially sourced 5A/4A attractions in major gateway and tourism cities; none is a complete city guide.

Why this project exists

Travel articles are plentiful. Reusable, source-linked, reviewable China travel data is not. This repository makes each fact easy to inspect and update through pull requests, while letting one data layer power several interfaces:

JSON city records
  ├── CLI search and itinerary drafts
  ├── local HTTP API
  └── MCP tools for AI clients

Every attraction record includes sources and last_verified. Prices and reservation rules are deliberately nullable: an unknown value is safer than a confident but outdated answer.

Try it in 60 seconds

Requires Python 3.10 or newer. No runtime packages are required.

git clone https://github.com/tczyliu/china-travel-kit.git
cd china-travel-kit
python3 -m china_travel_kit search museum --city Beijing
python3 -m china_travel_kit recommend 'First visit: pandas, food, relaxed pace' --travelers 2 --start-date 2026-07-10 --end-date 2026-07-12
python3 -m china_travel_kit areas --city Beijing
python3 -m china_travel_kit prepare 成都 --month 7
python3 -m china_travel_kit plan 丽江 --days 2 --interests mountain photography
python3 -m china_travel_kit emergency 丽江
python3 -m china_travel_kit freshness
python3 -m china_travel_kit integrity

Agent Skill

The repository root is an installable Agent Skill. SKILL.md defines when to use the toolkit, how to preserve Chinese and English place names, and when live facts must be rechecked. Conditional safety and itinerary guidance lives in references/ so ordinary destination searches stay lightweight.

Point an Agent Skills-compatible client at this repository, or clone it into that client's skills directory. The Skill uses the bundled read-only Python engine and does not require an API key for the included data.

Start the visual travel finder:

python3 -m china_travel_kit serve

Then open http://127.0.0.1:8765/ to search attractions and generate itinerary cards in a responsive Chinese interface.

Validate the data and run tests:

python3 -m china_travel_kit validate
python3 -m unittest discover -s tests -v

MCP server

The server uses MCP over stdio and exposes eight read-only tools:

• recommend_trip
• search_spots
• discover_areas
• get_city_guide
• plan_itinerary
• get_trip_preparation
• get_emergency_help
• check_data_freshness

Example client configuration:

{
  "mcpServers": {
    "china-travel-kit": {
      "command": "python3",
      "args": ["-m", "china_travel_kit", "mcp"],
      "cwd": "/absolute/path/to/china-travel-kit"
    }
  }
}

The implementation targets MCP protocol version 2025-11-25. It supports initialize, ping, tools/list, and tools/call over newline-delimited stdio messages.

HTTP API

python3 -m china_travel_kit serve --port 8765
curl 'http://127.0.0.1:8765/search?city=Chengdu&category=wildlife'
curl 'http://127.0.0.1:8765/recommend?requirements=pandas,food&days=3&pace=relaxed'
curl 'http://127.0.0.1:8765/plan?city=Lijiang&days=2&interests=mountain,photography'

Available endpoints: /health, /cities, /recommend, /search, /areas, /plan, /prepare, /emergency, and /freshness.

recommend_trip ranks only cities covered by the current repository. Its score explains how well the indexed data matches the request; it is not a universal ranking of destinations. Dates, party size, desired places, interests, pace, budget, mobility needs, children, origin, and free text are normalized into one response containing the itinerary, seasonal preparation, stay areas, food, culture, emergency context, unmatched requirements, and live checks still required.

Data principles

1. Sources before claims. Prefer official operators, government open data, Wikidata, OpenStreetMap, and original contributor research.
2. Freshness is data. Set last_verified to the date you actually checked the linked source.
3. Unknown beats invented. Use null for changing prices or booking rules you cannot verify.
4. No scraped commercial guides. Do not copy Ctrip, Dianping, Mafengwo, or creator content.
5. Safety needs context. Altitude, weather, accessibility, permits, and emergency details must be explicit and sourced.
6. Visitor areas are not private addresses. Area discovery covers stay areas and attraction neighborhoods, never resident or household data.

See data/schema/city.schema.json and the existing city files for the current schema.

Scope and non-goals

The current alpha provides source-aware sample data, explainable local matching, and developer interfaces. It does not provide live weather, live ticket inventory, visa eligibility decisions, hotel rankings, turn-by-turn navigation, or emergency dispatch. Those require authoritative live providers and stronger operational guarantees.

Licenses

Code is licensed under the MIT License. Repository travel data under data/ is licensed under CC BY-SA 4.0. Third-party source links remain subject to their respective owners' terms.

Integrity and brand identity

Official releases include integrity-manifest.json and its Ed25519 signature. Run python3 -m china_travel_kit integrity to authenticate the manifest with the bundled public key and then verify SHA-256 hashes. Require both valid: true and signature_valid: true. This detects forged manifests, incomplete copies, or tampering; it does not prevent copying allowed by the licenses.

Maintainers run scripts/update_integrity_manifest.py and then scripts/sign_integrity_manifest.py before a release. The dedicated private key stays outside the repository and must never be committed.

The code and data licenses do not grant rights to present a modified distribution as an official Huaxingzhi release. See TRADEMARKS.md and NOTICE.

Disclaimer

Travel rules, entry policies, opening hours, prices, weather, and transport can change quickly. Always verify critical details with the relevant authority or operator before departure. This project does not provide legal, medical, immigration, booking, or emergency services.