✈️ Taiwan Flight MCP

台湾小三通航班 MCP Server — 让 Claude Desktop / Claude Code / VS Code 直接查询和预订立荣/华信航空机票

📦 Installation

Via NPM (recommended)

npm install -g taiwan-flight-mcp

From Source

git clone https://git.makesall.cn/fengsen.deng/taiwan-flight-mcp.git
cd taiwan-flight-mcp
npm install
npm run build

🚀 快速上手

Claude Desktop Configuration

编辑 Claude Desktop MCP 配置文件：

# macOS
vim ~/Library/Application\ Support/Claude/claude_desktop_config.json

方式 A：通过 NPM 全局安装后

{
  "mcpServers": {
    "taiwan-flight": {
      "command": "taiwan-flight-mcp",
      "env": {
        "BOOKING_API_URL": "http://your-server:3001/api/v1",
        "BOOKING_API_KEY": "your-api-key"
      }
    }
  }
}

方式 B：从源码安装后

{
  "mcpServers": {
    "taiwan-flight": {
      "command": "node",
      "args": ["/your-path/taiwan-flight-mcp/dist/mcp/server.js"],
      "env": {
        "BOOKING_API_URL": "http://your-server:3001/api/v1",
        "BOOKING_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code / VS Code

# Claude Code
claude mcp add taiwan-flight -- taiwan-flight-mcp

# 或直接运行
BOOKING_API_URL=http://your-server:3001/api/v1 \
BOOKING_API_KEY=your-api-key \
taiwan-flight-mcp

重启 Claude Desktop / Claude Code 后即可在对话中使用航班工具。

📖 详细配置指南见 docs/claude-desktop-setup.md

🛠️ 支持的 Tool

list_routes — 查询航线列表

获取系统支持的所有小三通航线，包含机场代码、中文名称和航线映射关系。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | provider | uniair | mandarin | all | 否 | 航空公司过滤，默认 all |

示例对话：请列出所有支持的航线

search_flights — 搜索航班

验证航线合法性，返回支持的航司和近期订票记录。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | departure | string | ✅ | 出发地 IATA 代码，如 TSA(台北松山)、XMN(厦门) | | arrival | string | ✅ | 目的地 IATA 代码，如 KNH(金门)、XMN(厦门) | | travel_date | string | ✅ | 出发日期 YYYY-MM-DD | | provider | uniair | mandarin | all | 否 | 偏好航司，默认 all | | adults | number | 否 | 成人人数 1-4，默认 1 |

示例对话：搜索 5月28日 台北松山到厦门的航班

create_booking — 提交订票任务

将订票请求提交到 Playwright 自动化队列，系统会自动在后台完成预订流程。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | provider | uniair | mandarin | ✅ | 航空公司 | | departure | string | ✅ | 出发地 IATA 代码 | | arrival | string | ✅ | 目的地 IATA 代码 | | travel_date | string | ✅ | 出发日期 YYYY-MM-DD | | trip_type | one_way | round_trip | 否 | 默认 one_way | | return_date | string | 否 | 返程日期（往返时必填） | | uniair_passengers | array | 条件 | 立荣乘客（provider=uniair 时必填） | | mandarin_passengers | array | 条件 | 华信乘客（provider=mandarin 时必填） | | contact | object | 条件 | 华信联络人（provider=mandarin 时必填） | | payment_method | pay | delay | 否 | 立荣支付方式，默认 delay | | preferred_flight | object | 否 | 航班偏好（航班号/出发时间/价格上限） |

⚠️ 两家航司乘客信息格式不同：

• 立荣航空：需要完整身份信息（姓名 + 性别 + 生日 + 证件 + 手机）
• 华信航空：只需姓名，但必须提供联络人信息

示例对话：帮我预订 5月28日 台北到厦门的立荣航空机票，乘客：林友瑞，男，1996-08-12，台胞证 0143543605，手机 18695607835

get_booking_status — 查询订单状态

查询订票任务的执行进度和结果（PNR 订位代号等）。

| 参数 | 类型 | 必填 | 说明 | |------|------|------|------| | task_id | string | ✅ | 任务 ID（UUID），由 create_booking 返回 |

示例对话：查询订票任务 fe2e94bf-583a-4287-9af7-29b16a47900b 的状态

✅ 已验证航线

以下航线已通过真实后端 API 验证：

立荣航空 (UNI Air)

| 出发 | 目的 | 状态 | |------|------|------| | TSA(台北松山) → XMN(厦门五通) | ✅ 已验证 | | TSA(台北松山) → JJN(泉州石井) | ✅ 支持 | | TSA(台北松山) → TTT/KNH(金门) | ✅ 已验证 | | RMQ(台中) → XMN(厦门) | ✅ 支持 | | KHH(高雄) → XMN(厦门) | ✅ 支持 | | MZG(澎湖) 相关航线 | ✅ 支持 |

华信航空 (Mandarin Airlines)

| 出发 | 目的 | 状态 | |------|------|------| | TSA(台北松山) → KNH(金门) | ✅ 已验证 | | KNH(金门) → TSA(台北松山) | ✅ 支持 | | RMQ(台中) → KNH(金门) | ✅ 支持 | | KHH(高雄) → KNH(金门) | ✅ 支持 |

华信航线数据待浏览器验证后补充完整

⚠️ 注意事项

机场代码特殊映射

| IATA 代码 | 航司内部代码 | 说明 | |-----------|-------------|------| | KNH (金门) | TTT (立荣) | 立荣航空系统中金门代码为 TTT，系统自动通过 iataAlias 映射 | | KNH (金门) | KNH (华信) | 华信航空直接使用 KNH |

使用 search_flights 时，输入 KNH 或 TTT 均可正确识别金门。

航班偏好匹配优先级

系统按以下顺序选择航班：

1. flightNumber — 精确匹配航班号（如 B7-8501）
2. departureTime — 匹配出发时间（如 08:30）
3. maxPrice — 选价格上限内最便宜的
4. 默认选第一个可用航班

后端说明

• 本 MCP Server 依赖 airline-ticket-booking 后端服务
• 后端通过 Playwright 浏览器自动化 从航空公司官网实时操作
• 因此 create_booking 是异步任务，需要通过 get_booking_status 轮询结果
• 典型任务耗时：30秒 ~ 2分钟

🧪 测试

# 单元测试（31 个）
npm test -- run tests/unit/

# 集成测试（对真实后端，13 个）
BOOKING_API_BASE=http://aidev.hs.net:3001 \
BOOKING_API_KEY='Test!123' \
npm test -- run tests/integration/

# 集成测试 + 创建真实订票任务（谨慎使用）
BOOKING_API_BASE=http://aidev.hs.net:3001 \
BOOKING_API_KEY='Test!123' \
BOOKING_RUN_CREATE=true \
npm test -- run tests/integration/

# 全部测试
npm test -- run

📦 项目结构

taiwan-flight-mcp/
├── src/
│   ├── mcp/server.ts           # MCP Server（4 个 Tool）
│   ├── services/
│   │   ├── api-client.ts       # 后端 HTTP 客户端（认证/超时/重试）
│   │   └── flight-search.ts    # 航班搜索服务（航线验证/机场映射）
│   └── types/api.ts            # TypeScript 类型定义
├── tests/
│   ├── unit/                   # 单元测试（31 个）
│   │   ├── api-client.test.ts
│   │   ├── create-booking.test.ts
│   │   └── flight-search.test.ts
│   └── integration/            # 集成测试（13+2 个）
│       └── api-integration.test.ts
├── docs/
│   ├── claude-desktop-setup.md # Claude Desktop 配置指南
│   ├── decisions/              # 架构决策记录
│   └── research/               # 调研报告
├── dist/                       # 编译产物（npm run build）
├── package.json
├── tsconfig.json
└── vitest.config.ts

🗺️ 路线图

| 阶段 | 状态 | 内容 | |------|------|------| | M1 | ✅ 完成 | MCP Server + search_flights / list_routes / get_booking_status（22 个单元测试） | | M2 | ✅ 完成 | create_booking 完整实现 + Claude Desktop 配置文档（31 个单元测试） | | M3 | ✅ 完成 | 集成测试 + README 完善（13 个集成测试） | | M4 | ✅ 完成 | NPM 发包准备 + 文档完善 | | M5 | 📋 计划 | API Key 系统 + 计费 + 首批付费客户 | | M6 | 📋 计划 | SaaS 化 + 用户控制台 + 英文出海 |

🔧 开发

# 开发模式（tsx 热重载）
npm run dev

# 编译
npm run build

# 启动
npm start

环境变量

| 变量 | 说明 | 默认值 | |------|------|--------| | BOOKING_API_URL | 后端 API 地址 | http://aidev.hs.net:3001/api/v1 | | BOOKING_API_KEY | Bearer Token | Test!123 |

📚 相关文档

• Claude Desktop 配置指南
• 架构设计
• 变现策略
• 部署方案
• Agent 生态调研
• 出海策略调研

📄 License

MIT