lis186/smart-tra-mcp-server
If you are the rightful owner of smart-tra-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
The Smart TRA MCP Server is an intelligent query server for Taiwan Railway Administration, designed to provide train schedules, real-time information, fare queries, and trip planning through natural language interfaces.
Smart TRA MCP Server
An intelligent Taiwan Railway Administration (TRA) query server following the Model Context Protocol (MCP) design philosophy. This project integrates TDX (Transport Data eXchange) Taiwan railway APIs through natural language interfaces, providing train schedules, real-time information, fare queries, and trip planning.
โจ Features
๐ search_trains - Intelligent Train Search โ Complete
- Natural Language Queries: "ๆๆฉ8้ปๅฐๅๅฐๅฐไธญๆๅฟซ็่ชๅผท่"
- Train Number Direct Search: "152", "1234่ๅ่ป" with smart completion
- Real-time Status: Live train positions and delay information
- Delay Time Adjustment: Automatic calculation of adjusted arrival/departure times
- Visual Status System: ๐ขๆบ้ป ๐ก่ผๅพฎ่ชค้ป ๐ดๅด้่ชค้ป
- Modern Transit Icons: ๐้ฒ็ซไธญ ๐ๅ้ ไธญ โก๏ธๅทฒ้ข็ซ
- Comprehensive Data: Timetables, fares, and live status from TDX APIs
๐ข search_station - Station Discovery โ Complete
- Fuzzy Matching: Handles abbreviations and typos (ๅ่ป โ ่บๅ)
- Confidence Scoring: 0.0-1.0 confidence system with alternatives
- 244 TRA Stations: Complete station database with detailed information
- Smart Suggestions: Multiple candidate matches for ambiguous queries
๐บ๏ธ plan_trip - Trip Planning โ Complete
- Journey Planning: Multi-segment routes with transfers
- Non-station Destinations: Tourist spot mapping (ไนไปฝโ็่ณ, ๅขพไธโๆๅฏฎ)
- Branch Line Support: Pingxi, Jiji, Neiwan line transfers
- TRA-only Scope: Clear boundaries with actionable advice
๐๏ธ Architecture
MCP Design Philosophy
- Maximum 3 Tools: Following Shopify Storefront MCP design
- User-Intent Naming: Tools named by user goals, not technical functions
- Unified Parameters: All tools use
query
(required) +context
(optional) - Business Value Focus: Every tool solves real user problems
Technology Stack
- Runtime: Node.js 18+ with TypeScript 5.0+
- MCP SDK: @modelcontextprotocol/sdk for protocol implementation
- APIs: TDX Taiwan Railway v3 APIs with OAuth 2.0 authentication
- Transport: Dual support - STDIO (Claude Desktop) + Streamable HTTP (web/n8n)
- Deployment: Google Cloud Run ready with Docker containerization
๐ Getting Started
Prerequisites
- Node.js 18 or higher
- TDX API credentials (register at TDX)
Installation
# Clone the repository
git clone <repository-url>
cd smart-tra-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
Configuration
Copy and configure environment variables:
# Copy example configuration
cp .env.example .env
# Edit with your TDX API credentials
TDX_CLIENT_ID=your-client-id
TDX_CLIENT_SECRET=your-client-secret
Running the Server
# STDIO mode (Claude Desktop)
npm run dev:stdio
npm run start:stdio
# HTTP mode (web clients, n8n)
npm run dev:http
npm run start:http
# Default mode (STDIO)
npm run dev
npm start
๐ Deployment to Google Cloud Run
Deployment Prerequisites
Before deploying, ensure you have:
-
Google Cloud Account & Project
# Install Google Cloud CLI (if not already installed) # Visit: https://cloud.google.com/sdk/docs/install # Login and set your project gcloud auth login gcloud config set project YOUR-PROJECT-ID
-
Enable Required APIs
gcloud services enable cloudbuild.googleapis.com gcloud services enable run.googleapis.com gcloud services enable containerregistry.googleapis.com
-
TDX API Credentials (Required for functionality)
- Register at: https://tdx.transportdata.tw/
- Create an application and get your
TDX_CLIENT_ID
andTDX_CLIENT_SECRET
Method 1: Quick Deployment (Recommended)
Use the provided deployment script for fastest setup:
# 1. Make deployment script executable (already done in repo)
chmod +x deploy-cloudrun.sh
# 2. Deploy with your project ID and region
./deploy-cloudrun.sh YOUR-PROJECT-ID asia-east1
# 3. Set TDX credentials after deployment
gcloud run services update smart-tra-mcp-server \
--set-env-vars TDX_CLIENT_ID=your_actual_client_id \
--set-env-vars TDX_CLIENT_SECRET=your_actual_client_secret \
--region asia-east1
What the script does:
- Builds container using Google Cloud Build
- Deploys to Cloud Run with optimized settings
- Configures memory (1GB), CPU (1 core), scaling (0-10 instances)
- Sets up health checks and production environment
- Outputs service URL and test endpoints
Method 2: Step-by-Step Manual Deployment
For full control over the deployment process:
# 1. Build and push container to Google Container Registry
echo "Building container..."
gcloud builds submit --tag gcr.io/YOUR-PROJECT-ID/smart-tra-mcp-server
# 2. Deploy to Cloud Run with full configuration
echo "Deploying to Cloud Run..."
gcloud run deploy smart-tra-mcp-server \
--image gcr.io/YOUR-PROJECT-ID/smart-tra-mcp-server \
--platform managed \
--region asia-east1 \
--allow-unauthenticated \
--port 8080 \
--memory 1Gi \
--cpu 1 \
--min-instances 0 \
--max-instances 10 \
--timeout 300 \
--concurrency 80 \
--set-env-vars NODE_ENV=production \
--set-env-vars TDX_CLIENT_ID=your_actual_client_id \
--set-env-vars TDX_CLIENT_SECRET=your_actual_client_secret
# 3. Get the service URL
SERVICE_URL=$(gcloud run services describe smart-tra-mcp-server \
--platform managed \
--region asia-east1 \
--format 'value(status.url)')
echo "Service deployed at: $SERVICE_URL"
Method 3: Using YAML Configuration
For infrastructure-as-code deployment:
# 1. Update the YAML file with your project ID
sed -i 's/PROJECT_ID/YOUR-PROJECT-ID/g' cloudrun-service.yaml
# 2. Build container
gcloud builds submit --tag gcr.io/YOUR-PROJECT-ID/smart-tra-mcp-server
# 3. Deploy using YAML configuration
gcloud run services replace cloudrun-service.yaml --region=asia-east1
# 4. Set credentials (YAML doesn't include secrets for security)
gcloud run services update smart-tra-mcp-server \
--set-env-vars TDX_CLIENT_ID=your_actual_client_id \
--set-env-vars TDX_CLIENT_SECRET=your_actual_client_secret \
--region asia-east1
Environment Configuration
Required Environment Variables
NODE_ENV=production # Automatically set for Cloud Run
PORT=8080 # Automatically set by Cloud Run
TDX_CLIENT_ID=your_id # Set during deployment
TDX_CLIENT_SECRET=your_secret # Set during deployment
Optional Environment Variables
HOST=0.0.0.0 # Default for Cloud Run
GOOGLE_CLOUD_PROJECT=... # Auto-detected in Cloud Run
Verification & Testing
After deployment, verify your service is working:
# Get your service URL
SERVICE_URL=$(gcloud run services describe smart-tra-mcp-server \
--platform managed \
--region asia-east1 \
--format 'value(status.url)')
# Test health endpoint
curl "${SERVICE_URL}/health"
# Expected: {"status":"healthy","timestamp":"...","service":"smart-tra-mcp-server"...}
# Test root endpoint (shows available tools)
curl "${SERVICE_URL}/"
# Test with actual MCP client
# Your service is now ready for HTTP-based MCP clients like n8n
Service Endpoints
Your deployed service will be available at:
- Health Check:
https://your-service-url/health
- For monitoring and load balancer checks - MCP Endpoint:
https://your-service-url/mcp
- For HTTP-based MCP clients (n8n, web apps) - Service Info:
https://your-service-url/
- Shows available tools and configuration
Security Best Practices
1. Use Secret Manager (Recommended for Production)
# Store credentials securely in Google Secret Manager
echo -n "your_actual_client_id" | gcloud secrets create tdx-client-id --data-file=-
echo -n "your_actual_client_secret" | gcloud secrets create tdx-client-secret --data-file=-
# Update service to use secrets instead of environment variables
gcloud run services update smart-tra-mcp-server \
--remove-env-vars TDX_CLIENT_ID,TDX_CLIENT_SECRET \
--set-secrets TDX_CLIENT_ID=tdx-client-id:latest \
--set-secrets TDX_CLIENT_SECRET=tdx-client-secret:latest \
--region asia-east1
2. Restrict Access (Optional)
# Remove public access (requires authentication)
gcloud run services remove-iam-policy-binding smart-tra-mcp-server \
--member="allUsers" \
--role="roles/run.invoker" \
--region=asia-east1
# Allow specific users
gcloud run services add-iam-policy-binding smart-tra-mcp-server \
--member="user:yourname@example.com" \
--role="roles/run.invoker" \
--region=asia-east1
Monitoring & Maintenance
Check Logs
# View recent logs
gcloud run services logs read smart-tra-mcp-server --region=asia-east1
# Tail logs in real-time
gcloud run services logs tail smart-tra-mcp-server --region=asia-east1
Update Service
# Update environment variables
gcloud run services update smart-tra-mcp-server \
--set-env-vars NEW_VAR=value \
--region asia-east1
# Update resource allocation
gcloud run services update smart-tra-mcp-server \
--memory 2Gi \
--cpu 2 \
--region asia-east1
Troubleshooting
Common Issues
-
Build Fails
# Check build status gcloud builds list --limit=5 # View specific build logs gcloud builds log BUILD-ID
-
Service Won't Start
# Check service status gcloud run services describe smart-tra-mcp-server --region=asia-east1 # Check recent logs gcloud run services logs read smart-tra-mcp-server --region=asia-east1 --limit=50
-
TDX API Connection Issues
# Test your credentials locally first curl -X POST "https://tdx.transportdata.tw/auth/realms/TDXConnect/protocol/openid-connect/token" \ -H "Content-Type: application/x-www-form-urlencoded" \ -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
-
Performance Issues
# Check current resource usage gcloud run services describe smart-tra-mcp-server \ --region=asia-east1 \ --format="value(spec.template.spec.containers[0].resources)"
Cost Optimization
Google Cloud Run charges only for actual usage:
- CPU/Memory: Only while handling requests
- Requests: $0.40 per million requests
- Networking: Minimal for typical usage
With min-instances=0
, costs approach zero when not in use.
Cost-saving tips:
- Use
min-instances=0
for development - Set appropriate
max-instances
to control scaling - Monitor usage in Google Cloud Console
- Consider
min-instances=1
only for production with consistent traffic
๐ Usage Examples
Train Search Examples
{
"name": "search_trains",
"arguments": {
"query": "ๆๆฉ8้ปๅฐๅๅฐๅฐไธญๆๅฟซ็็ญๆฌก",
"context": "็ตๆไธ้5๏ผๅซ็ฅจๅน"
}
}
{
"name": "search_trains",
"arguments": {
"query": "152",
"context": "้กฏ็คบ่ฉณ็ดฐๆๅป่กจ"
}
}
Station Search Examples
{
"name": "search_station",
"arguments": {
"query": "ๆพๅฑฑ็ซ",
"context": "ๅๅบๅ้ธ3ๅ๏ผ็น้ซไธญๆ"
}
}
Response Features
Real-time Status Display
๐ ่ปๆฌก 152 ่ฉณ็ดฐ่ณ่จ
๐ ๅณๆ็ๆ
(20:30 ๆดๆฐ)
๐ก ็ฎๅ่ชค้ป 5 ๅ้
๐ฏ ๅ็พฉ ๐ ๅ้ ไธญ
๐ก ๅณๆ่ณๆ่ฆ่: 25/50 ็ซ (50%)
โญ๏ธ ไธไธ็ซ: ๆๅ
ญ ้ ไผฐ 20:52 ๅฐ้
๐ ๆฑๆญข ้ ไผฐ 00:28 ๅฐ้ (ๅๅฎ 00:23)
Adjusted Time Display
โฐ ไปๆฅๆๅป่กจ
๐ฉ ๆฝฎๅท 18:31็ผ (ๅๅฎ18:26)๐ก ่ผๅพฎ่ชค้ป5ๅ
ๅฑๆฑ 18:43ๅฐ (ๅๅฎ18:38) โ 18:45็ผ (ๅๅฎ18:40) (2ๅ)
้ซ้ 19:08ๅฐ (ๅๅฎ19:03) โ 19:10็ผ (ๅๅฎ19:05) (2ๅ)
๐ ๆฑๆญข 00:28ๅฐ (ๅๅฎ00:23)
๐ง Development
Project Structure
smart-tra-mcp-server/
โโโ src/ # Source code
โ โโโ unified-server.ts # Main server entry point (dual transport)
โ โโโ server.ts # Core MCP server class
โ โโโ core/ # Core modules
โ โ โโโ express-server.ts # HTTP server for Cloud Run
โ โ โโโ auth-manager.ts # TDX authentication
โ โ โโโ data-manager.ts # Station data management
โ โ โโโ error-handler.ts # Error categorization
โ โโโ services/ # Business logic
โ โ โโโ train-service.ts # Train search service
โ โ โโโ trip-planner.ts # Trip planning service
โ โโโ types/ # TypeScript definitions
โ โโโ utils/ # Utility functions
โโโ dist/ # Compiled JavaScript
โโโ tests/ # Comprehensive test suite
โโโ Dockerfile # Container configuration
โโโ deploy-cloudrun.sh # Cloud Run deployment script
โโโ cloudrun-service.yaml # Cloud Run service config
โโโ README.md # This file
Development Principles
- Deploy Fast First: Small, verifiable changes
- Critical Risk First: Address unknowns early
- Fail Fast: 3-attempt rule, then reassess
- Production-Like Testing: Real APIs from day one
- Continuous Learning: Document lessons learned
Testing
# Build project
npm run build
# Run comprehensive test suite
npm test
# Run specific test categories
npm run test:unit # Unit tests
npm run test:integration # Integration tests
npm run test:e2e # End-to-end tests
Current Test Results: 96.4% success rate (54/56 tests passing)
- โ Unit Tests: 35/35 (100%) - Core logic validation
- โ Integration Tests: 9/9 (100%) - Tool boundary enforcement
- โ Delegation Tests: 4/6 (67%) - Minor display format issues
- โ E2E Tests: 6/6 (100%) - User journey validation
๐ Current Status
โ Production Ready - All Core Stages Complete
Stage 1-10.1: All development stages completed
- โ Stage 1-6: Foundation through search_trains tool
- โ Stage 7: HTTP transport & Google Cloud Run deployment
- โ Stage 8: Response size optimization (60-85% reduction)
- โ Stage 9: plan_trip tool with transfer support
- โ Stage 10-10.1: Complete TypeScript type safety
๐ฏ Current Capabilities
- All 3 MCP Tools: search_trains, search_station, plan_trip
- Dual Transport: STDIO (Claude Desktop) + HTTP (Cloud Run, web clients)
- Real-time Data: Live train status with delay adjustments
- Production Deployment: Docker containerization with Cloud Run support
- Comprehensive Testing: 96.4% test success rate
๐ Ready For
- โ Claude Desktop Integration (STDIO transport)
- โ Google Cloud Run Deployment (HTTP transport)
- โ Web Client Integration (n8n, custom HTTP clients)
- โ Production Traffic (error handling, monitoring, scaling)
๐ฏ Key Achievements
Technical
- Real TDX Integration: Production API connectivity with OAuth 2.0
- MCP Protocol: Full compliance with Model Context Protocol
- Type Safety: Complete TypeScript implementation
- Error Handling: Comprehensive error management and user guidance
User Experience
- Natural Language: Intuitive query interface
- Real-time Data: Live train positions and delays
- Visual Design: Modern emoji system for status indication
- Delay Awareness: Automatic time adjustments for accurate planning
Performance
- Response Optimization: Context-efficient responses for AI agents
- Caching Strategy: Smart caching for frequently accessed data
- Rate Limiting: Respectful API usage with proper throttling
๐ Documentation
- : Product Requirements Document
- : Technical Specifications
- : Development Stages
- : Development Guidelines
- : Version History
๐ค Contributing
This project follows strict development principles:
- Small Batch Development: Single feature per commit
- Test-Driven: Real API testing from start
- Documentation First: Update docs with changes
- Type Safety: All code must compile without errors
See for detailed development guidelines.
๐ License
This project is licensed under the MIT License - see the LICENSE file for details.
๐ Acknowledgments
- TDX (Transport Data eXchange): Taiwan's open transportation data platform
- Model Context Protocol: Protocol specification and SDK
- Taiwan Railway Administration: Railway system and data
Project Status: ๐ Production Ready - All Core Stages Complete (1-10.1)
Last Updated: August 24, 2025
Current Milestone: โ
Google Cloud Run Deployment Ready (Stage 7 Complete)
Deployment: Ready for production deployment to Google Cloud Run