china-travel-kit README

The project's README from github.com/tczyliu/china-travel-kit. As one markdown file: README.md.

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:

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.

china-travel-kit (tczyliu/china-travel-kit)

Searching Database…

194 ·GitHub
China-travel-kit
What is this?China Travel Kit (Huaxingzhi) is a source-aware, bilingual open knowledge base and Agent Skill for China inbound travel, covering 56 attractions across 8 cities with explainable recommendations, delivered via CLI, HTTP API, and MCP server.
Is this a dataset, a library, or an app?It is all three at once: a licensed travel data layer (JSON city files) powering a zero-runtime-dependency Python query engine, which is then exposed through a CLI, an HTTP API, an MCP server, and an installable Agent Skill.
How do I try it?Clone the repo and launch the bundled visual travel finder locally to search attractions and build itinerary cards in a responsive Chinese/English interface, or run the data validator and tests directly.
Do I need Python packages or an API key to run it?Just Python 3.10 or newer; no runtime packages and no API key are required to use the bundled data and engine.
What can't it do yet?This is an alpha covering only 56 places in 8 cities, with no live weather, ticket inventory, visa decisions, hotel rankings, turn-by-turn navigation, or emergency dispatch — it's a developer preview, not a booking or navigation service.
Which cities and attractions does it currently cover?56 places across Beijing, Shanghai, Guangzhou, Shenzhen, Chengdu, Xi'an, Hangzhou, and Lijiang, focused on officially sourced 5A/4A attractions rather than full city guides.
What tools does the MCP server expose?Eight read-only MCP stdio tools (protocol 2025-11-25): recommend_trip, search_spots, discover_areas, get_city_guide, plan_itinerary, get_trip_preparation, get_emergency_help, and check_data_freshness.
Why doesn't it just scrape sites like Ctrip or Mafengwo?Its data principles require sourcing from official operators, government open data, Wikidata, and OpenStreetMap, and explicitly forbid copying from Ctrip, Dianping, Mafengwo, or creator content, so every fact stays verifiable and dated.
What is the integrity-manifest.json for?Official releases ship an Ed25519-signed integrity-manifest.json; running the bundled integrity command verifies SHA-256 hashes to confirm a copy hasn't been tampered with or forged.
What are similar projects?context7, overmind, chubbyskills, DoveVannoINostriSoldi, gpt4free, rea, 3d-asset-server, open-seo-mcp-skills
Which topics is it in?dataset, agent-skill, model-context-protocol, knowledge-base, json, china, rest-api, mcp-server, agent-skills, command-line-tool, mcp, api
Creator
tczyliu
Size
0.2 MB
Stars
194
Updated
CommitAug 25
Age
1mo
Commits · 90 Days