smart-tra-mcp-server

lis186/smart-tra-mcp-server

3.2

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.

Tools
2
Resources
0
Prompts
0

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:

  1. 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
    
  2. Enable Required APIs

    gcloud services enable cloudbuild.googleapis.com
    gcloud services enable run.googleapis.com
    gcloud services enable containerregistry.googleapis.com
    
  3. TDX API Credentials (Required for functionality)

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
  1. Build Fails

    # Check build status
    gcloud builds list --limit=5
    
    # View specific build logs
    gcloud builds log BUILD-ID
    
  2. 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
    
  3. 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"
    
  4. 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:

  1. Small Batch Development: Single feature per commit
  2. Test-Driven: Real API testing from start
  3. Documentation First: Update docs with changes
  4. 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