Content
# Tool List
One sentence, easy to go.
Xixi Travel is an open-source project for intelligent travel agents for scenarios such as taxi calling, route planning, and travel services. The project includes an independent React/MapLibre demo interface, a LibreChat-based agent entrance, a Spring Boot ride-hailing business service, a Spring AI MCP tool, and a Milvus knowledge base initialization script.
## Online Experience
- Public Demo: [https://yinpeng04.github.io/xixi-travel-agent/](https://yinpeng04.github.io/xixi-travel-agent/)
- Source Code: [https://github.com/YINPENG04/xixi-travel-agent](https://github.com/YINPENG04/xixi-travel-agent)
## Direct Experience
Open the public demo address to directly use it without logging in, installing software, or configuring model keys:
[Enter Xixi Travel Online Demo →](https://yinpeng04.github.io/xixi-travel-agent/)
| Function | Operation Method |
|---|---|
| Route Planning | Enter destination or select quick locations like Beijing South Railway Station, Capital Airport |
| Car Quotation | Switch between light, comfortable, and six-seat, view prices and estimated pick-up time |
| Simulate Call Car | Select car type and confirm, view driver, vehicle, and pick-up countdown |
| Trip Management | Open "Trip" to view current orders and historical records, can cancel or complete demo trips |
| Invoice Demo | After completing the trip, open "Invoice" to register receipt and receive email |
| Real-time Time | The page top displays continuously updated Beijing time |
Demo data is only saved in the current browser and will not create real orders, deductions, or send invoice emails.
## Project Positioning
This repository provides two usage methods:
1. **Front-end Interaction Demo**: Run `app/` directly, no database, model key, or back-end service required, can experience map, car quotation, call car, driver countdown, trip, and invoice pages.
2. **Complete Agent Link**: Start LibreChat and Spring Boot services, use large models to call inquiry, create orders, query status, and cancel orders through MCP.
The two paths are currently independent. The online demo interface's quotation, route, and driver information are front-end demo data, and have not directly called `ride-service`; real business rules and MCP tools are located in the Spring Boot service.
## Three-minute Local Experience
The local interface does not require a ChatGPT account, map key, or back-end service. Install Git and Node.js 22.13 or higher, then execute:
```bash
git clone https://github.com/YINPENG04/xixi-travel-agent.git
cd xixi-travel-agent
npm ci
npm run dev
```
Open [http://localhost:3000](http://localhost:3000).
Trip and invoice demo data are saved in the current browser's `localStorage`, will not upload to the author's server. Different browsers and devices' data are independent, clear browser site data to reset the demo.
## Overall Architecture
```mermaid
flowchart LR
U["User"]
subgraph Demo["Entrance 1: Independent Interaction Demo"]
UI["React + Vinext<br/>Xixi Travel Interface"]
MAP["MapLibre GL JS"]
OSM["OpenStreetMap<br/>Public Tiles"]
LS["Browser localStorage<br/>Trip and Invoice Demo Data"]
UI --> MAP --> OSM
UI <--> LS
end
subgraph Agent["Entrance 2: Complete Agent Link"]
LC["LibreChat<br/>Account, Session, Conversation, and Agent"]
LLM["User-configured<br/>Large Model Service"]
MCP["Spring AI MCP Server<br/>SSE"]
RS["Spring Boot Ride Service<br/>REST + Domain Logic"]
MEM["Current Implementation: In-memory Storage"]
LC <--> LLM
LC -->|"MCP Tool Call"| MCP
MCP --> RS
RS <--> MEM
end
subgraph Infra["Optional Local Infrastructure"]
MONGO["MongoDB<br/>LibreChat Data"]
REDIS["Redis<br/>Cache Infrastructure"]
MEILI["Meilisearch<br/>Full-text Retrieval"]
PG["PostgreSQL<br/>Planned Transaction Persistence"]
MILVUS["Milvus<br/>Vector Knowledge Base"]
ETCD["etcd"]
MINIO["MinIO"]
MILVUS --> ETCD
MILVUS --> MINIO
end
subgraph Knowledge["Knowledge Base Initialization"]
JSONL["Location, Car Type, Rules, Policies<br/>JSONL Data"]
EMB["sentence-transformers"]
SEED["PyMilvus Write Script"]
JSONL --> EMB --> SEED --> MILVUS
end
U --> UI
U --> LC
LC --> MONGO
LC --> REDIS
LC --> MEILI
RS -. Subsequent Access .-> PG
RS -. Subsequent Access .-> REDIS
LC -. To be supplemented retrieval tool .-> MILVUS
```
## Layer Description
### 1. Interaction Display Layer
Path: `app/`
Technology Stack: TypeScript, React 19, Vinext, MapLibre GL JS.
Main Capabilities:
- Chinese Travel Workbench, destination input, and quick locations.
- OpenStreetMap base map, simulated route, start and end point markers.
- Light, comfortable, and six-seat car type quotation cards.
- Call car, driver pick-up countdown, and demo trip completion.
- Trip list, order status, electronic invoice registration.
- Beijing time real-time update.
- Save demo trip in current device through `localStorage`.
This layer uses browser local state for easy demonstration, does not depend on Spring Boot service. Map coordinates, quotations, and driver data are demo data, do not represent real scheduling results.
### 2. Agent and Session Layer
The project uses LibreChat as a fixed baseline for conversation, user, session, model access, and Agent/MCP framework:
- Upstream Repository: `danny-avila/LibreChat`
- Fixed Commit: `8e5ef1fb31e9d63b735c089b21cbc82c50acce46`
- Checkout Script: `scripts/bootstrap-librechat.ps1`
- Xixi Configuration: `librechat.xixi.yaml`
LibreChat source code is not directly submitted to this repository, but is checked out to ignored `vendor/LibreChat/`. In complete mode, LibreChat connects to Xixi Travel MCP service through `http://ride-service:8081/sse`.
The repository does not contain any large model API keys. To conduct real Agent dialogue, configure your own model service according to LibreChat upstream documentation.
### 3. MCP Tool Layer
Path: `services/ride-service/src/main/java/cn/xixitravel/ride/mcp/`
Spring AI registers Java methods as MCP tools:
| Tool | Purpose | Key Constraints |
|---|---|---|
| `rideQuote` | Returns car type, estimated pick-up time, and quotation | Must inquire before ordering |
| `rideCreate` | Create order using valid quotation | Requires user ID, idempotency key, and user confirmation |
| `rideStatus` | Query current order status | Isolate orders by user ID |
| `rideCancel` | Cancel unstarted orders | Requires user confirmation before calling |
MCP Server uses synchronous tool mode to provide capabilities to LibreChat through SSE. The requirements for confirmation before creating and canceling orders are currently written in the Agent/MCP tool description, and the business interface has not been forcibly verified through an independent confirmation token.
### 4. Ride Business Layer
Path: `services/ride-service/`
Technology Stack: Java 21, Spring Boot 3.4.5, Spring AI 1.0.1.
Core Rules:
- Quotation is valid for five minutes.
- Quotation is calculated by base price, mileage unit price, and car type multiplier.
- Creating an order must carry `Idempotency-Key`.
- Idempotency key is isolated by "user ID + idempotency key".
- Query and cancel orders verify the order's belonging user.
- Illegal state transitions are rejected.
- Parameter errors and business errors are returned as RFC 9457 `ProblemDetail`.
Current orders, quotations, and idempotency keys are saved in in-process concurrent maps and will be lost after service restart. Although Docker Compose provides PostgreSQL and Redis, the current Java code has not connected to them.
### 5. Order Status Machine
```mermaid
stateDiagram-v2
[*] --> CREATED
CREATED --> DRIVER_ASSIGNED
DRIVER_ASSIGNED --> DRIVER_ARRIVING
DRIVER_ARRIVING --> DRIVER_ARRIVED
DRIVER_ARRIVED --> IN_PROGRESS
IN_PROGRESS --> COMPLETED
CREATED --> CANCELLED
DRIVER_ASSIGNED --> CANCELLED
DRIVER_ARRIVING --> CANCELLED
DRIVER_ARRIVED --> CANCELLED
COMPLETED --> [*]
CANCELLED --> [*]
```
`COMPLETED` and `CANCELLED` are terminal states, and trips cannot be canceled through existing interfaces after they start.
### 6. Knowledge Base Layer
Path: `knowledge/`
Knowledge base samples include:
- Location names and aliases.
- Car type passenger capacity and applicable scenarios.
- Quotation validity period.
- Agent security confirmation rules.
- Trip invoice instructions.
`seed_milvus.py` uses `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` to generate normalized vectors, creates HNSW/COSINE index through PyMilvus, and writes to Milvus.
The script deletes and rebuilds the `xixi_travel_knowledge` collection each time it is executed, suitable for initialization and demonstration, but not suitable for directly saving production data that needs to be maintained manually. The current MCP tool has not connected to Milvus retrieval results.
### 7. Infrastructure Layer
`docker-compose.xixi.yml` provides the following containers:
| Service | Role | Current Access Status |
|---|---|---|
| `ride-service` | Quotation, order, REST API, and MCP tool | Already connected |
| `mongodb` | LibreChat user, session, and application data | Used in LibreChat mode |
| `meilisearch` | LibreChat full-text retrieval | Used in LibreChat mode |
| `redis` | LibreChat cache; plans to bear business idempotency and short-term status | Partially connected |
| `postgres` | Plans to store orders, quotation snapshots, trips, and invoices | Container provided, business code not connected |
| `milvus` | Vector knowledge base | Initialization script can write |
| `etcd` | Milvus metadata coordination | Used by Milvus |
| `minio` | Milvus object storage | Used by Milvus |
The `db/`, `drizzle/`, and `examples/d1/` in the root directory are reserved for D1/Drizzle scaffolding for site operation environment, and the current Xixi Travel business does not use D1.
## Two Key Data Flows
### Front-end Demo Data Flow
1. User inputs destination on React page.
2. Front-end displays route and car quotation based on built-in data.
3. User confirms to call car, browser generates demo order.
4. Countdown, status change, trip, and invoice are saved in `localStorage`.
5. MapLibre loads map from OpenStreetMap public tile service.
This process does not require login, back-end, or large model, suitable for product demonstration and front-end development.
### Agent Tool Call Data Flow
1. User logs in to local LibreChat and proposes travel needs.
2. Large model understands departure, destination, mileage, and estimated time.
3. Agent calls `rideQuote` to obtain three car type quotations.
4. User confirms explicitly, Agent uses quotation ID and idempotency key to call `rideCreate`.
5. Agent queries status using `rideStatus`, or calls `rideCancel` after confirmation.
6. Spring Boot service is responsible for quotation validity period, user isolation, idempotency, and state transition.
## Project Directory
```text
.
├─ app/ React/MapLibre interaction demo
│ ├─ XixiTravelApp.tsx Page state, map, trip, and invoice interaction
│ ├─ globals.css Visual style and responsive layout
│ ├─ layout.tsx Page metadata
│ └─ page.tsx Home page entrance
├─ services/ride-service/ Spring Boot business and MCP service
│ ├─ src/main/java/.../api/ REST interface and exception handling
│ ├─ src/main/java/.../domain/ Quotation, order, car type, and state machine
│ ├─ src/main/java/.../mcp/ Spring AI MCP tool
│ └─ src/main/java/.../service/ Business rules and in-memory storage
├─ knowledge/ Milvus initialization script and knowledge samples
├─ scripts/ LibreChat fixed baseline checkout script
├─ tests/ Front-end build product testing
├─ worker/ Vinext/Cloudflare Worker entrance
├─ docker-compose.xixi.yml Local complete dependency orchestration
├─ librechat.xixi.yaml LibreChat and MCP configuration
├─ OPEN_SOURCE_USAGE.md Open source affiliation and license description
└─ THIRD_PARTY_NOTICES.md Third-party project hints
```
## Local Run
### Mode A: Run Interaction Interface Only
Requirements:
- Node.js 22.13 or higher
- npm
```bash
npm ci
npm run dev
```
Access [http://localhost:3000](http://localhost:3000).
### Mode B: Run Spring Boot Service Only
Requirements:
- JDK 21 or higher
- Maven 3.9 or higher
```bash
cd services/ride-service
mvn test
mvn spring-boot:run
```
Service address:
- REST API: `http://localhost:8081/api/v1`
- MCP SSE: `http://localhost:8081/sse`
- Health check: `http://localhost:8081/actuator/health`
### Mode C: Start Infrastructure
Copy environment variable sample:
```bash
cp .env.example .env
```
Windows PowerShell:
```powershell
Copy-Item .env.example .env
```
Modify example password and start:
```bash
docker compose -f docker-compose.xixi.yml up -d
```
### Mode D: Start LibreChat + MCP Complete Link
First, checkout fixed LibreChat baseline.
Windows PowerShell:
```powershell
.\scripts\bootstrap-librechat.ps1
```
macOS or Linux:
```bash
git clone --filter=blob:none --no-checkout https://github.com/danny-avila/LibreChat.git vendor/LibreChat
git -C vendor/LibreChat fetch --depth=1 origin 8e5ef1fb31e9d63b735c089b21cbc82c50acce46
git -C vendor/LibreChat checkout --detach 8e5ef1fb31e9d63b735c089b21cbc82c50acce46
```
Then, configure your own model service in `.env` according to LibreChat upstream documentation, and start:
```bash
docker compose -f docker-compose.xixi.yml --profile librechat up -d
```
Access [http://localhost:3080](http://localhost:3080), can register independent account on local. Account and session are saved in local MongoDB, not connected to online demo site.
### Initialize Milvus Knowledge Base
Start Milvus dependencies:
```bash
docker compose -f docker-compose.xixi.yml up -d etcd minio milvus
```
Install Python dependencies and write sample data:
macOS or Linux:
```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -r knowledge/requirements.txt
python knowledge/seed_milvus.py
```
Windows PowerShell:
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r knowledge/requirements.txt
python knowledge/seed_milvus.py
```
First run will download vector model. Can override default configuration through environment variables:
| Environment Variable | Default Value | Description |
|---|---|---|
| `MILVUS_HOST` | `localhost` | Milvus address |
| `MILVUS_PORT` | `19530` | Milvus port |
| `XIXI_MILVUS_COLLECTION` | `xixi_travel_knowledge` | Collection name |
| `XIXI_EMBEDDING_MODEL` | `sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2` | Vector model |
## REST API
| Method | Path | Description |
|---|---|---|
| `POST` | `/api/v1/quotes` | Generate vehicle quotes based on route mileage and duration |
| `POST` | `/api/v1/rides` | Create an order using a valid quote |
| `GET` | `/api/v1/rides/{orderId}` | Query the current user's order |
| `POST` | `/api/v1/rides/{orderId}/cancel` | Cancel an order that allows cancellation |
| `PATCH` | `/api/v1/internal/rides/{orderId}/status/{status}` | Internal state promotion interface for demonstration purposes |
Inquiry:
```bash
curl -X POST http://localhost:8081/api/v1/quotes \
-H "Content-Type: application/json" \
-d '{"origin":"Palace Museum","destination":"Beijing South Railway Station","distanceKilometers":12.6,"durationMinutes":28}'
```
Create Order:
```bash
curl -X POST http://localhost:8081/api/v1/rides \
-H "Content-Type: application/json" \
-H "X-Xixi-User: demo-user" \
-H "Idempotency-Key: demo-order-001" \
-d '{"quoteId":"Q-XXXXXXXX","origin":"Palace Museum","destination":"Beijing South Railway Station"}'
```
Where `quoteId` must be replaced with the quote ID returned by the inquiry interface and not yet expired.
## Testing and Continuous Integration
Frontend build and key page inspection:
```bash
npm test
```
Spring Boot testing:
```bash
cd services/ride-service
mvn test
```
`.github/workflows/ci.yml` will run web and Java tests separately when pushing and pulling requests.
## Deployment Instructions
The public demonstration is built as a pure static frontend through `vite.github-pages.config.ts` and automatically published to GitHub Pages by GitHub Actions. This version does not require login and does not run Java, LibreChat, or MCP backend.
The repository also retains the Vinext/Cloudflare Worker build method. `worker/index.ts` is the Worker entry, and `build/sites-vite-plugin.ts` packages site metadata after building.
The complete agent chain includes MongoDB, Redis, Meilisearch, Spring Boot, Milvus, etcd, and MinIO, which is different from the single-page demonstration site and requires separate deployment using Docker Compose or equivalent infrastructure.
## Current Boundaries and Production Notes
- The current system is an MVP and does not include real vehicle scheduling, payment, SMS, real-name authentication, location reporting, or production-level risk control.
- The frontend demonstration interface has not yet called the Spring Boot REST/MCP service.
- Backend orders and quotes use in-memory storage, and data is lost after service restart.
- `X-Xixi-User` is a demonstration identity header and not a production-level authentication mechanism.
- The internal state promotion interface currently does not have independent authentication and is only suitable for controlled demonstration environments.
- The agent's "confirmation before creation or cancellation" mainly relies on tool description and orchestration rules, and the backend has not yet forced verification of confirmation credentials.
- The invoice function only registers locally in the browser and does not generate real invoices or send emails.
- Milvus data can be initialized but has not yet been connected to the agent's retrieval tool.
- The privacy policy and service terms address in `librechat.xixi.yaml` are placeholder addresses and must be replaced before public deployment.
- Public OpenStreetMap tile services should not be used as commercial map CDNs without quota or guarantee.
- During production, orders, quote snapshots, trips, and invoices should be written to PostgreSQL, and idempotent keys, quote expiration times, and short-term states should be migrated to Redis or compatible components.
## Suggested Evolution Route
1. Connect the frontend quote, order, and trip pages to the Spring Boot REST API.
2. Implement order, quote, trip, and invoice storage using PostgreSQL.
3. Implement distributed idempotence, quote TTL, and short-term state using Redis or Valkey.
4. Add standard login authentication and securely pass user identity to REST and MCP tools.
5. Encapsulate Milvus retrieval as location alias, vehicle description, and rule query MCP tools.
6. Add verifiable confirmation tokens and audit logs for important operations.
7. Add route services, map supplier adaptation layers, and production-level current limiting.
8. Generate SBOM, vulnerability reports, and third-party license lists.
## Open Source Projects and Licenses
- The code developed in this repository uses the MIT License shown in the root directory `LICENSE`.
- LibreChat uses the MIT License and is checked out through a fixed submission script.
- Namma Yatri is only used for business process and domain modeling reference, and its source code has not been copied, modified, or packaged.
- Redis 7.4, MongoDB, and MinIO authorization conditions need to be evaluated separately.
- OpenStreetMap data uses ODbL, and the interface must retain attribution.
See the complete code attribution, version, license, and distribution boundaries:
- [OPEN_SOURCE_USAGE.md](./OPEN_SOURCE_USAGE.md)
- [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md)
## Contribution
Welcome to submit improvements through issues or pull requests. Please run frontend and Java tests before submission; if third-party code or resources are introduced, please also record the source, version, modification content, and license.
## Disclaimer
This project is only for technical research, work display, and architecture verification and does not provide real ride-hailing services. The open-source attribution statement in the repository does not constitute legal advice.
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available