MCP Taipei Metro Month Price

TPASS计算器

台北地铁月票（TPASS）成本比较工具-MCP服务器实现。

概述

该工具可帮助台北地铁通勤者决定是购买TPASS月票（连续30天1200元新台币）还是使用常旅客折扣计划的常规票价（根据行程计算为5%-15%）。

特性

• 成本比较：使用自动折扣等级应用程序计算TPASS与常规票价
• 智能推荐：根据您的通勤模式获得个性化建议
• 票价查询：按车站名称或手动输入自动查找票价

- 模糊站名与建议匹配 - 来自台北开放数据的17000多条票价记录 - 支持常规票价和折扣票价 - 7天智能缓存

• 跨月支持：处理跨越多个日历月的TPASS期间

- 按日历月边界自动拆分计算 - 每月独立应用折扣级别 - 显示详细的月度细分，包括行程计数和成本

• 灵活的参数：自定义票价、每日行程和工作日
• 日历集成：使用台湾政府假日日历精确计算工作日
• 多个接口：MCP服务器、CLI命令和编程API

安装

先决条件

• 包子 v1.0.0或更高版本

设置

# Clone the repository
git clone 
cd mcp-taipei-metro-month-price

# Install dependencies
bun install

# Verify installation
bun run calculate --help

用法

CLI命令

计算TPASS比较

# Default calculation (today, NT$40 fare, 2 trips/day)
bun run calculate

# Custom date
bun run calculate --date 2025-02-01

# Custom fare and trips
bun run calculate --fare 50 --trips 4

# Override working days (useful for non-standard schedules)
bun run calculate --custom-days 20

# All options
bun run calculate --date 2025-02-01 --fare 50 --trips 3 --custom-days 18

查看折扣信息

# Display frequent rider discount tiers and TPASS info
bun run discount

票价查询

# Lookup fare between two stations
bun run fare:lookup -- --origin "台北車站" --destination "市政府"

# Lookup discounted fare
bun run fare:lookup -- --origin "台北車站" --destination "淡水" --fareType discounted

# Check fare cache status
bun run fare:status

# Update fare cache from Taipei Open Data
bun run fare:update

票价查询系统：

• 从台北开放数据下载17000多条票价记录
• 支持中文站名的Big5编码
• 使用模糊匹配来建议相似的电台名称
• 缓存数据7天，自动刷新
• 返回常规票价和折扣票价

日历管理

# Show calendar cache status
bun run calendar:status

# View cached holiday data
bun run calendar:view

# Update calendar cache from government open data platform
bun run calendar:update

# Update calendar cache for a specific year
bun run calendar:update 2026

日历更新命令会自动执行：

• 从开放数据源获取台湾政府假日日历
• 创建现有缓存的备份
• 更新 data/calendar-cache.json 有新数据
• 支持2020-2030年

MCP服务器

启动MCP服务器以与AI助手集成：

bun run mcp-server

可用的MCP工具：

• calculate_fare：计算TPASS与常规票价的比较（默认为下一个工作日）
• get_discount_info：获取折扣级别信息
• lookup_fare：按车站名称查找票价或验证手动票价输入

OpenAI应用集成

该项目包括一个用于OpenAI Apps SDK集成的适配器（未来）：

import { handleOpenAIFunctionCall, getOpenAIFunctions } from './src/adapters/openai/app.js';

// Register functions with OpenAI Apps
const functions = getOpenAIFunctions();

// Handle function calls
const result = await handleOpenAIFunctionCall({
  name: 'calculateTPASSComparison',
  arguments: JSON.stringify({ oneWayFare: 50, tripsPerDay: 3 })
});

可用的OpenAI功能：

• calculateTPASSComparison：计算并比较TPASS与常规票价
• getDiscountInformation：获取折扣计划信息

程序化使用

import { calculateTPASSComparison } from './src/services/calculator.js';
import { parseDate } from './src/lib/utils.js';

const result = await calculateTPASSComparison({
  startDate: parseDate('2025-02-01'),
  oneWayFare: 50,
  tripsPerDay: 2,
  customWorkingDays: 20
});

console.log(result.recommendation); // 'BUY_TPASS' or 'USE_REGULAR'
console.log(result.savingsAmount); // Savings in NTD

配置

中的默认设置 src/config.ts:

TPASS设置

• 单程票：新台币40元
• 每日行程：2（往返）
• TPASS价格：新台币1200元
• TPASS有效性：连续30天

票价查询设置

• CSV网址：台北开放数据平台票价数据
• 高速缓存文件: data/fare-cache.json
• 缓存TTL：7天
• 模糊匹配阈值: 0.3
• 最大建议: 3

验证约束条件

• 票价：1-1000新台币
• 每日行程：1-10
• 自定义工作日：0-30

常旅客折扣计划

台北地铁根据每月出行次数提供自动折扣：

折扣在每月1日重置。

例子

示例1：定期通勤

$ bun run calculate --fare 40 --trips 2

输出：

• 22个工作日×2次出行=44次出行
• 普通票价：1760元→ 新台币1496元（八五折）
• 推荐：购买TPASS（节省296新台币）

示例2：偶尔使用

$ bun run calculate --custom-days 10 --trips 2

输出：

• 10个工作日×2次出行=20次出行
• 普通票价：800元→ 新台币760元（5%折扣）
• 推荐：使用普通票价（节省440新台币）

示例3：跨月期间

$ bun run calculate --date 2024-10-31 --fare 35 --custom-days 20

输出正确地划分了10月至11月的30天期间，每月分别应用折扣：

📊 MONTHLY BREAKDOWN (Cross-Month Calculation)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Month 1: October 2024
  Date Range: Oct 31 - Oct 31
  Working Days: 1
  Trips: 2
  Base Fare: NT$35
  Original Cost: NT$70
  Discount Tier: 0%
  Discount Amount: NT$0
  Final Cost: NT$70

Month 2: November 2024
  Date Range: Nov 1 - Nov 29
  Working Days: 19
  Trips: 38
  Base Fare: NT$35
  Original Cost: NT$1330
  Discount Tier: 10%
  Discount Amount: NT$133
  Final Cost: NT$1197

TOTALS:
  Original Cost: NT$1400
  Discount Amount: NT$133
  Final Cost: NT$1267

系统会自动检测跨月期间，并显示每月的详细明细，根据每月的行程计数（而不是总数）应用正确的折扣级别。

示例4：使用车站名称查找票价

$ bun run fare:lookup -- --origin "亞東醫院" --destination "科技大樓"

输出：

✓ Fare found:
  Route: 亞東醫院 → 科技大樓
  Fare: NT$35
  Type: regular
  Distance: 15.78 km

然后使用TPASS计算票价：

$ bun run calculate --fare 35 --trips 2

示例5：模糊站名匹配

$ bun run fare:lookup -- --origin "台北" --destination "市府"

输出：

✗ Station names not found. Did you mean:

Origin suggestions for "台北":
  1. 台北車站 (confidence: 100%)
  2. 台北橋 (confidence: 100%)
  3. 台北小巨蛋 (confidence: 100%)

Destination suggestions for "市府":
  1. 市政府 (confidence: 100%)

发展

项目结构

src/
├── adapters/         # Protocol adapters (MCP, OpenAI Apps)
│   ├── mcp/         # MCP server and tool definitions
│   └── openai/      # OpenAI Apps SDK adapter
├── cli/             # CLI commands
│   ├── calculate-cmd.ts    # TPASS calculation
│   ├── discount-cmd.ts     # Discount info
│   ├── calendar-cmd.ts     # Calendar management
│   └── fare-cmd.ts         # Fare lookup (NEW)
├── lib/             # Utilities and type definitions
│   ├── csvParser.ts        # Big5 CSV parser (NEW)
│   ├── stationMatcher.ts   # Fuzzy matching (NEW)
│   └── utils.ts            # Date/format utilities
├── models/          # Domain models
│   ├── tpass.ts            # TPASS model
│   ├── discount.ts         # Discount tiers
│   ├── calendar.ts         # Calendar model
│   └── fare.ts             # Fare models (NEW)
├── services/        # Business logic services
│   ├── calculator.ts       # TPASS calculation
│   ├── calendar-service.ts # Holiday calendar
│   ├── fareService.ts      # Fare lookup logic (NEW)
│   └── fareCacheService.ts # Fare cache management (NEW)
└── config.ts        # Configuration constants

开发命令

# Type checking
bun run type-check

# Linting
bun run lint

# Formatting
bun run format

# Build
bun run build

测试

手动测试

# Test TPASS calculator
bun run tests/manual/test-calculator.ts

# Test fare lookup with CLI
bun run fare:update
bun run fare:status
bun run fare:lookup -- --origin "台北車站" --destination "市政府"

# Test fuzzy matching
bun run fare:lookup -- --origin "台北" --destination "市府"
# Expected: Returns suggestions for matching stations

自动化测试

# Run all tests
bun test

# Run specific test files
bun test tests/unit/calendar-service.test.ts
bun test tests/unit/calendar-service-multiyear.test.ts

集成测试

测试完整的工作流程：

# 1. Setup: Download fare and calendar data
bun run fare:update
bun run calendar:update

# 2. Lookup fare for your commute route
bun run fare:lookup -- --origin "亞東醫院" --destination "科技大樓"
# Note the fare amount (e.g., 35 NTD)

# 3. Calculate TPASS comparison
bun run calculate --fare 35 --trips 2
# Should default to next working day with accurate holiday calendar

# 4. Verify MCP integration
bun run mcp-server
# Test with MCP client: lookup_fare then calculate_fare

测试覆盖率

当前测试覆盖率：

• ✅ 日历服务（单元测试）
• ✅ 多年日历支持（单元测试）
• ✅ 票价查询（手动CLI测试）
• ✅ 模糊匹配（手动测试）
• ✅ 使用Big5编码的CSV解析（集成测试）
• ✅ 缓存管理（集成测试）
• ⏳ 票价服务单元测试（计划中）
• ⏳ E2E MCP工具测试（计划中）

技术细节

• 语言：TypeScript 5.9.3
• 运行时：包1.x
• 建筑：具有适配器模式的分层架构
• 日历数据：台湾政府假日日历
• 票价数据：台北开放数据平台（17000+条记录，118个站点）
• 依赖项:

- @模型上下文协议/sdk ^1.20.2-MCP服务器实现 - fuzzysort ^3.1.0-车站名称的快速模糊匹配

最新动态

v1.1.0-票价查询功能（2025-10-31）

• ✨ 新：按车站名称自动查找票价
• ✨ 新：车站名称建议的模糊匹配
• ✨ 新：支持台北开放数据17000多条票价记录
• ✨ 新：7天智能缓存系统
• ✨ 新：中文站名支持Big5编码
• ✨ 新：CLI命令： fare:lookup, fare:status, fare:update
• ✨ 新：MCP工具： lookup_fare
• 🎯 增强：默认开始日期现在使用下一个工作日（尊重节假日）
• 📝 改进的：更好的错误消息和电台建议

已知限制

当前限制：

1. 票价服务单元测试：已计划但尚未实施
2. E2E MCP测试：集成测试仅手动进行
3. 错误恢复：基本错误处理，可以增强

对于生产使用，请考虑：

• 全面的自动化测试套件
• 增强的错误处理和日志记录
• 性能监控和优化
• API调用的速率限制

CI/CD和容器部署

自动化多架构构建

该项目使用GitHub Actions自动构建多架构容器映像（amd64/arm64）并将其发布到Docker Hub和GitHub容器注册表。

自动触发器:

• 主枝：每次推送都会构建和发布 latest 标签
• 版本标签：创建标签，如 v1.2.3 构建和发布版本化图像

GitHub机密设置

在自动构建工作之前，请配置以下存储库机密：

1. 首选 设置→ 秘密和变量→ 行动
2. 添加以下机密：

备注: GITHUB_TOKEN 自动提供给GitHub容器注册表。

提取已发布的图像

# Latest from Docker Hub
podman pull docker.io//mcp-taipei-metro-month-price:latest

# Specific version from GHCR
podman pull ghcr.io//mcp-taipei-metro-month-price:1.0.0

# Run container
podman run --rm docker.io//mcp-taipei-metro-month-price:latest --help

手动工作流触发器

您还可以通过GitHub UI手动触发构建：

1. 首选 行动→ 构建多拱门图像
2. 点击 运行工作流
3. 可选择指定自定义标记或测试，而无需推送

______________________________________________________________________

许可证

麻省理工学院

支持

有关问题、疑问或贡献，请参阅存储库问题跟踪器。