MTA API v4

Real-time NYC subway arrivals API - serverless/edge deployment.

Key Differences from v2/v3

• TypeScript with Hono framework
• Stateless: No server-side caching, each request fetches fresh data
• CDN-cacheable: Returns Cache-Control: max-age=30 headers
• Portable: Runs on Cloudflare Workers, Node.js, Bun, Deno

Quick Start

Node.js

npm install
npm run build
npm start

Cloudflare Workers

npm install
npx wrangler dev    # Local development
npx wrangler deploy # Deploy to Cloudflare

Docker

docker build -t mta-api-v4 .
docker run -p 8000:8000 mta-api-v4

Testing

The project uses Vitest for testing.

Run All Tests

npm test

Unit Tests

Test individual modules (config, cache, validation, stations, service):

# All unit tests
npm test -- tests/config.test.ts tests/cache.test.ts tests/validation.test.ts tests/stations.test.ts tests/mta-service.test.ts

# Individual test file
npm test -- tests/validation.test.ts

Integration Tests

Tests against the deployed API at https://mta-api-v4.reichertjalex.workers.dev/:

npm test -- tests/integration.test.ts

These tests verify:

• All API endpoints return expected data
• Station search and location queries work
• Real-time arrival data is present and valid
• Response times are acceptable

Watch Mode

Re-run tests on file changes:

npm run test:watch

Type Checking

Run TypeScript compiler without emitting:

npx tsc --noEmit

API Endpoints

Same as v2/v3:

| Endpoint | Description | | ------------------------- | ----------------- | | GET / | API info | | GET /api/stations | Query stations | | GET /api/stations/{id} | Get station by ID | | GET /api/routes | List routes | | GET /api/routes/{route} | Stations on route |

Trade-offs

| Aspect | Benefit | Cost | | --------------- | -------------------------- | ---------------------------- | | No server state | Simple ops, infinite scale | Each request hits MTA | | CDN caching | Fast responses globally | Slightly stale data possible | | TypeScript | Type safety | No nyct-gtfs equivalent |

Deploy to Cloudflare Workers

Cloudflare Workers is the recommended deployment for v4 since it's designed for edge/serverless.

First-time setup

# Install wrangler (if not already)
npm install -g wrangler

# Login
wrangler login

# Deploy
cd mta-api-v4
npm run build
wrangler deploy

wrangler.toml

Already configured in the repo:

name = "mta-api-v4"
main = "dist/index.js"
compatibility_date = "2024-01-01"

To add a custom domain, update wrangler.toml:

routes = [
  { pattern = "mta-api.yourdomain.com/*", zone_name = "yourdomain.com" }
]

Useful commands

wrangler dev              # Local development
wrangler deploy           # Deploy to production
wrangler tail             # Stream live logs
wrangler secret put NAME  # Set secret environment variable

Alternative: Deploy to Fly.io

v4 can also run on Fly.io using the Dockerfile:

fly launch --name mta-api-v4 --region ewr
fly deploy

CLI

Query subway data from the command line. Output is JSON by default.

Install from npm

# Using npx (no install needed)
npx mta-subway stations

# Or install globally
npm install -g mta-subway

Usage

# List all stations
mta-subway stations

# Search stations by name
mta-subway stations -q "Times Square"

# Get station by ID (with arrivals)
mta-subway stations 127

# Get multiple stations
mta-subway stations 127,A32

# Search by location
mta-subway stations --lat 40.7580 --lon -73.9855

# List all routes
mta-subway routes

# Get stations on a route
mta-subway routes A

# Find next trains from a station
mta-subway find "Times Square"

# Find specific route from a station
mta-subway find "Times Square" -r A

# Human-readable output (--pretty goes before the command)
mta-subway --pretty stations 127

Development

npm run build
npm run cli -- stations

MCP Server

Run as a Model Context Protocol server for AI assistants. Supports both local (stdio) and remote (HTTP) transports.

Available Tools

| Tool | Description | | -------------- | ----------------------------------- | | get_stations | Search stations by name or location | | get_station | Get station(s) by ID with arrivals | | get_routes | List all active subway routes | | get_route | Get all stations on a route | | find_train | Find next trains from a station |

Local (stdio) Transport

For local AI assistants.

Claude Code (CLI)

# Using npx (no install needed)
claude mcp add mta-subway -- npx mta-subway-mcp

# Or with globally installed package
claude mcp add mta-subway -- mta-subway-mcp

# Or from source
claude mcp add mta-subway -- node dist/mcp.js --directory /path/to/mta-api-v4

Claude Desktop / Settings JSON

Add to ~/.claude/settings.json (Claude Code) or ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop):

{
  "mcpServers": {
    "mta-subway": {
      "command": "npx",
      "args": ["mta-subway-mcp"]
    }
  }
}

Or from source:

{
  "mcpServers": {
    "mta-subway": {
      "command": "node",
      "args": ["dist/mcp.js"],
      "cwd": "/path/to/mta-api-v4"
    }
  }
}

HTTP Transport

Connect to a deployed MCP server. No local setup required.

Claude Code (CLI)

# Use the deployed instance (Cloudflare Workers)
claude mcp add mta-subway --transport http https://mta-api-v4.alexreichert.workers.dev/mcp

# Or use a local server
claude mcp add mta-subway --transport http http://localhost:8787/mcp

Or add to ~/.claude/settings.json:

{
  "mcpServers": {
    "mta-subway": {
      "type": "http",
      "url": "https://mta-api-v4.alexreichert.workers.dev/mcp"
    }
  }
}

Running the HTTP Server Locally

npx wrangler dev
# MCP endpoint: http://localhost:8787/mcp

The HTTP transport includes OAuth endpoints for Claude Code's authentication flow.