Metadata-Version: 2.4
Name: travel-agent-mcp
Version: 1.1.0
Summary: 旅行特工队 - MCP工具集（地图/空间计算/评价分析/攻略生成/预约购票）
Home-page: https://example.com
Author: 旅行特工队
Author-email: 旅行特工队 <travel@example.com>
License: MIT
Keywords: mcp,travel,amap,trip-planner,agent
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: http
Requires-Dist: fastapi>=0.100.0; extra == "http"
Requires-Dist: uvicorn>=0.23.0; extra == "http"
Provides-Extra: full
Requires-Dist: fastapi>=0.100.0; extra == "full"
Requires-Dist: uvicorn>=0.23.0; extra == "full"
Requires-Dist: reportlab>=4.0.0; extra == "full"
Dynamic: author
Dynamic: home-page
Dynamic: requires-python

# 旅行特工队 - 工具层

> 华为ICT创新赛参赛作品 · 多智能体旅行规划系统的工具层

---

## 项目简介

「旅行特工队」是一个面向追求极致时间利用率和性价比的年轻群体的智能旅行规划系统。本项目为系统架构中的**工具层**，提供7大类、20+个核心工具，以标准MCP（Model Context Protocol）协议对外提供服务，可直接接入华为智果(AgentArts)等智能体平台。

### 系统架构

```
┌─────────────────────────────────────────────────────────┐
│                     接入层（用户输入）                     │
├─────────────────────────────────────────────────────────┤
│                   编排协调层（统筹调度智能体）               │
├─────────────────────────────────────────────────────────┤
│                   智能体执行层（6大专业智能体）             │
├─────────────────────────────────────────────────────────┤
│  🔧 工具层（本项目）  ｜  记忆与知识层  ｜  模型推理层      │
└─────────────────────────────────────────────────────────┘
```

### 工具层模块

| 模块 | 核心功能 | 对应智能体 |
|------|----------|------------|
| 🗺️ 地图MCP | POI搜索、路线规划、地理编码、周边搜索 | 路线编排智能体 |
| 📐 空间计算MCP | 距离计算、通勤估算、顺道景点、路径优化 | 路线编排智能体 |
| 📊 数据采集工具 | 多平台评价抓取、清洗、分析、排序 | 口碑清洗智能体 |
| 🌐 HTML生成工具 | 攻略页面、打卡清单、拍照指南、分享卡片 | 内容渲染智能体 |
| 📄 PDF生成工具 | 打印版清单、行程手册、拍照指南 | 内容渲染智能体 |
| 🔗 接口跳转工具 | 预约链接、抢票倒计时、状态聚合 | 预约监控智能体 |
| 🎫 抢票步骤生成器 | 多平台购票步骤、最佳平台推荐 | 预约监控智能体 |

---

## 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 配置环境变量

```bash
copy .env.example .env
# 编辑 .env，填入高德地图API Key等配置
```

### 3. 运行服务

```bash
# 查看所有可用工具
python server.py --list

# HTTP模式（用于测试）
python server.py --http --port 8000

# stdio模式（MCP标准，生产使用）
python server.py
```

### 4. 测试工具

```bash
# 测试POI搜索
python server.py --test "search_poi:keyword=故宫,city=北京"

# 测试距离计算
python server.py --test "calculate_distance:lat1=39.9163,lng1=116.3972,lat2=39.9999,lng2=116.2755"
```

---

## 目录结构

```
travel-agent-tools/
├── server.py                 # MCP服务入口
├── requirements.txt          # Python依赖
├── .env.example              # 环境变量模板
├── README.md                 # 项目说明
├── config/
│   └── settings.py           # 全局配置管理
├── tools/                    # 工具模块
│   ├── __init__.py
│   ├── map_mcp/              # 地图MCP工具
│   ├── spatial_mcp/          # 空间计算MCP工具
│   ├── data_collector/       # 数据采集工具
│   ├── html_generator/       # HTML生成工具
│   ├── pdf_generator/        # PDF生成工具
│   ├── booking_link/         # 预约链接工具
│   └── ticket_steps/         # 抢票步骤生成器
├── mcp_server/
│   └── __init__.py           # MCP服务核心实现
├── templates/                # HTML模板
│   ├── travel_guide.html     # 旅行攻略模板
│   ├── checklist.html        # 打卡清单模板
│   ├── photo_spots.html      # 拍照点位模板
│   └── share_card.html       # 分享卡片模板
└── deploy/
    └── 智果平台部署指南.md    # 智果平台部署文档
```

---

## 工具清单

### 地图工具（5个）

| 工具名 | 功能 |
|--------|------|
| `search_poi` | 搜索兴趣点（景点、餐厅、酒店等） |
| `planning_route` | 驾车路线规划 |
| `geocode` | 地址转经纬度 |
| `search_nearby` | 周边POI搜索 |
| `walking_route` | 步行路线规划 |

### 空间计算工具（6个）

| 工具名 | 功能 |
|--------|------|
| `calculate_distance` | 两点直线距离计算 |
| `calculate_distance_manhattan` | 曼哈顿距离计算 |
| `estimate_travel_time` | 通勤时间估算 |
| `find_nearby_along_route` | 沿路线顺道景点查找 |
| `optimize_route_order` | 途经点顺序优化（TSP近似解） |
| `find_central_point` | 多点中心点计算 |

### 数据采集工具（5个）

| 工具名 | 功能 |
|--------|------|
| `fetch_reviews` | 获取多平台评价数据 |
| `clean_reviews` | 评价清洗与去重 |
| `analyze_reviews` | 评价综合分析 |
| `prioritize_pois` | POI优先级排序（必去/可选/避雷） |
| `suggest_visiting_time` | 错峰到访建议 |

### HTML生成工具（4个）

| 工具名 | 功能 |
|--------|------|
| `generate_travel_guide_html` | 生成旅行攻略页面 |
| `generate_checklist_html` | 生成打卡清单页面 |
| `generate_photo_spots_guide` | 生成拍照点位指南 |
| `generate_share_card` | 生成分享卡片 |

### PDF生成工具（3个）

| 工具名 | 功能 |
|--------|------|
| `generate_checklist_pdf` | 生成打印版打卡清单 |
| `generate_itinerary_pdf` | 生成详细行程手册 |
| `generate_photo_guide_pdf` | 生成拍照指南PDF |

### 预约链接工具（4个）

| 工具名 | 功能 |
|--------|------|
| `generate_booking_links` | 生成多渠道预约链接 |
| `get_ticket_countdown` | 获取抢票倒计时 |
| `check_booking_status` | 查询预约状态 |
| `batch_check_booking` | 批量查询预约状态 |

### 抢票步骤生成器（3个）

| 工具名 | 功能 |
|--------|------|
| `generate_ticket_guide` | 生成详细购票步骤指南 |
| `generate_multi_platform_guide` | 生成多平台购票指南 |
| `generate_recommended_platform` | 推荐最佳购票平台 |

---

## 部署到智果平台

详细部署步骤请参考 [智果平台部署指南](deploy/智果平台部署指南.md)

### 快速部署流程

1. 将项目打包为 ZIP 文件
2. 在智果平台创建 MCP 连接器
3. 上传代码包，配置启动命令 `python server.py`
4. 配置环境变量（高德地图API Key等）
5. 部署并验证工具列表
6. 在智能体中绑定连接器使用

---

## 技术特点

- ✅ **标准MCP协议**：兼容所有支持MCP的智能体平台
- ✅ **模块化设计**：7大工具模块独立，易于扩展
- ✅ **双运行模式**：支持 stdio 和 HTTP 两种运行方式
- ✅ **中文支持完善**：HTML/PDF均完美支持中文字体
- ✅ **配置灵活**：通过环境变量灵活配置各项参数
- ✅ **日志完善**：完整的日志系统，便于问题排查

---

## 后续规划

- [ ] 接入更多地图服务（百度地图、腾讯地图）
- [ ] 增加小红书、抖音等平台真实数据API对接
- [ ] 支持更多文件格式导出（Word、Excel）
- [ ] 增加图片识别出片率功能
- [ ] 接入更多预约平台
- [ ] 支持用户偏好记忆

---

## 参赛信息

- **赛事**：第十一届华为ICT大赛 · 创新赛
- **作品**：旅行特工队 - 智能旅行规划多智能体系统
- **模块**：工具层（MCP工具集）
- **版本**：v1.0.0
