Metadata-Version: 2.4
Name: mta-subway
Version: 1.0.0
Summary: Real-time NYC subway arrivals CLI and MCP server
Project-URL: Homepage, https://github.com/reichertjalex/mta-subway
Project-URL: Repository, https://github.com/reichertjalex/mta-subway
Author: Alex Reichert
License-Expression: MIT
Keywords: cli,gtfs,mcp,mta,nyc,subway,transit
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: nyct-gtfs>=1.3.0
Requires-Dist: pydantic>=2.0
Description-Content-Type: text/markdown

# MTA API v3

Real-time NYC subway arrivals API with async concurrent feed fetching.

## Key Differences from v2

- **Concurrent fetching**: All 8 MTA feeds fetched in parallel using `asyncio.to_thread()`
- **Async cache**: Uses `asyncio.Lock` to prevent concurrent refresh storms
- **Lazy refresh**: Cache updates on first request after expiry

## Performance

- Sequential fetch (v2): ~2-4 seconds
- Concurrent fetch (v3): ~500ms-1s

## Quick Start

```bash
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload
```

## API Endpoints

Same as v2 - see `/docs` for OpenAPI documentation.

## Docker

```bash
docker build -t mta-api-v3 .
docker run -p 8000:8000 mta-api-v3
```

## Deploy to Fly.io

[Fly.io](https://fly.io) is recommended for v3 since it supports persistent servers with the async caching model.

### First-time setup

```bash
# Install flyctl
curl -L https://fly.io/install.sh | sh

# Login
fly auth login

# Launch app (creates fly.toml)
cd mta-api-v3
fly launch --name mta-api-v3 --region ewr --no-deploy

# Deploy
fly deploy
```

### fly.toml

If you need to create it manually:

```toml
app = "mta-api-v3"
primary_region = "ewr"  # Newark, close to MTA servers

[build]
  dockerfile = "Dockerfile"

[http_service]
  internal_port = 8000
  force_https = true

[[http_service.checks]]
  path = "/"
  interval = "30s"
  timeout = "5s"
```

### Useful commands

```bash
fly status              # Check app status
fly logs                # View logs
fly ssh console         # SSH into the container
fly scale count 2       # Scale to 2 instances
fly secrets set KEY=val # Set environment variables
```

## CLI

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

```bash
# Setup
source venv/bin/activate

# List all stations
python -m mta.cli stations

# Search stations by name
python -m mta.cli stations -q "Times Sq"

# Get station by ID (with arrivals)
python -m mta.cli stations 127

# Get multiple stations
python -m mta.cli stations 127,A32

# Search by location
python -m mta.cli stations --lat 40.7580 --lon -73.9855

# List all routes
python -m mta.cli routes

# Get stations on a route
python -m mta.cli routes A

# Find next trains from a station
python -m mta.cli find "Times Sq"

# Find specific route from a station
python -m mta.cli find "Times Sq" -r A

# Human-readable output (--pretty goes before the command)
python -m mta.cli --pretty stations 127
```

## MCP Server

Run as a Model Context Protocol server for AI assistants:

```bash
python -m mta.mcp
```

### 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     |

### Claude Desktop Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "mta-subway": {
      "command": "python",
      "args": ["-m", "mta.mcp"],
      "cwd": "/path/to/mta-api-v3"
    }
  }
}
```
