# Boston Harbor Ferries

[![PyPI version](https://img.shields.io/pypi/v/boston-harbor-ferries.svg)](https://pypi.org/project/boston-harbor-ferries/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![APRS.fi](https://img.shields.io/badge/data-APRS.fi-green.svg)](https://aprs.fi)

APRS-based Boston Harbor commuter ferry tracker with MCP server support.

Tightly scoped to track Seaport Ferry vessels operating in Boston Harbor.

**Data provided by [aprs.fi](https://aprs.fi)** - https://aprs.fi

## Features

- Track all 4 Seaport Ferry vessels in real-time
- **In-memory caching** with 120-second TTL (respects aprs.fi API terms)
- **Rate limiting**: 10 requests/minute (configurable)
- Rich CLI with beautiful terminal output
- MCP server for integration with Claude Code and other AI assistants
- Run with `uvx` (no installation required)
- Live position tracking and historical data export

## Tracked Vessels

### Seaport Ferry - North Station Route
- **PHILLIS WHEATLEY** (MMSI: 368227350)
- **SAMUEL WHITTEMORE** (MMSI: 368227370)
- **COMMONWEALTH** (MMSI: 368351390)

Route: LoveJoy Wharf (North Station) ↔ Fan Pier (Seaport) ↔ Pier 10
Travel time: ~30 minutes

### Seaport Ferry - East Boston Route
- **CRISPUS ATTUCKS** (MMSI: 368157410) - [📍 Live Position](https://www.google.com/maps?q=42.351318,-71.038918)

Route: Lewis Mall Wharf (East Boston) ↔ Fan Pier (Seaport)
Travel time: ~10 minutes

> 🚢 **Latest Position**: 42.351318°N, 71.038918°W (Course: 339°)
> 📊 **[View 24-Day Activity Analysis](visualizations/crispus_attucks_summary.md)** - Speed patterns, hourly heatmaps, route visualization
> 📍 **[Live Position Data](visualizations/crispus_attucks_latest.json)** - Real-time JSON feed

**Historical Data**: 4,777 positions over 24 days (Sep 15 - Oct 10) • Avg speed: 12.4kn • Operating hours: 05:00-19:00

#### 📊 Activity Heatmap (Last 2 Weeks)

Activity by hour - darker blocks indicate more position reports:

```
      00  04  08  12  16  20
      │   │   │   │   │   │
09-29 │    ░▓████▒ ░▒░███▓▒
09-30 │    ░▓████░  ▒▓████▒
10-01 │     ▒████▒    ████▒
10-02 │    ░▓████░    ████▒
10-03 │     ▓█████▓░▒▒████▒
10-06 │    ░▒████▓░▒▒▒████▒
10-07 │    ░▓████▒   ░████▒
10-08 │     ▓█░▓█░   ░████▒
10-09 │    ░█████▒▒█░▓████░
10-10 │    ░▓████▒
```

**Legend**: ░ Low  ▒ Medium  ▓ High  █ Peak
**Pattern**: Clear AM (06-10) and PM (15-18) commute peaks

#### 🚢 Speed Distribution

```
Speed (knots) │ Frequency
──────────────┼──────────────────────────────────────────────────
        2- 4 │ ██████ 188
        4- 6 │ ███████ 202
        6- 8 │ █████ 148
        8-10 │ ██████ 176
       10-12 │ ████████ 229
       12-14 │ ████████████ 349
       14-16 │ ███████████████████████ 673
       16-18 │ ████████████████████████████████████████ 1123
       18-20 │ ███ 93
       20-22 │  21
```

**Peak Speed**: 16-18 knots (75% of time cruising >10kn)

#### 🗺️ Route Map

```
           Boston Harbor
    ╔══════════════════════╗
    ║                      ║

  Lewis Mall Wharf    Fan Pier
   (East Boston)      (Seaport)
         │                │
         │   ~10 min      │
         │   8-12 kn      │
         └───────┬────────┘
                 │
            CRISPUS ATTUCKS
            (90 passengers)
```

**Operating**: 05:00-19:00 daily • **Peak**: 06-10, 15-18

---

## Installation

### Run with uvx (recommended)

```bash
# Set your API key
export APRS_API_KEY="your-key-from-aprs.fi"

# Run commands directly
uvx --from . harbor-ferry list-vessels
uvx --from . harbor-ferry track 368157410
uvx --from . harbor-ferry track-all
```

### Install in development mode

```bash
cd boston_harbor_ferries
pip install -e .
```

## Configuration

Get your free API key from https://aprs.fi (requires registration).

Set the API key via environment variable:

```bash
export APRS_API_KEY="your-api-key-here"
```

Or create a `.env` file:

```bash
APRS_API_KEY=your-api-key-here
APRS_CACHE_TTL_SECONDS=120
APRS_MAX_REQUESTS_PER_MINUTE=10
```

## CLI Usage

```bash
# List all known ferries
harbor-ferry list-vessels

# Show routes and schedules
harbor-ferry routes

# Track a specific ferry
harbor-ferry track 368157410

# Track all ferries
harbor-ferry track-all

# Force fresh data (bypass cache)
harbor-ferry track 368157410 --no-cache

# Cache management
harbor-ferry cache-info
harbor-ferry clear-cache
```

## MCP Server Usage

The MCP server allows AI assistants like Claude Code to track ferries in real-time.

### Quick Start

```bash
# Test the MCP server
gmake test-mcp

# Expected output:
# ✓ MCP server responding to JSON-RPC
# Tools: list_ferries, track_ferry, track_all_ferries, get_ferry_routes, clear_cache
```

### Available MCP Tools

- `list_ferries` - List all known Boston Harbor ferries with details
- `get_ferry_routes` - Get route information and schedules
- `track_ferry` - Track specific ferry by MMSI number
- `track_all_ferries` - Get all ferry positions at once
- `clear_cache` - Force fresh data (bypasses 2-minute cache)

### Claude Code/Desktop Integration

**See [docs/CLAUDE_CODE_INTEGRATION.md](docs/CLAUDE_CODE_INTEGRATION.md) for complete integration guide.**

#### Adding to Claude Code

From within this repository directory:

```bash
# Add the MCP server to Claude Code
claude mcp add-json boston-harbor-ferries \
  '{"command":"uv","args":["run","python","-m","boston_harbor_ferries.mcp_server"],"env":{"APRS_API_KEY":"'"${APRS_API_KEY}"'"}}'

# Verify it's connected
claude mcp list
# Should show: boston-harbor-ferries - ✓ Connected

# View available tools
claude mcp get boston-harbor-ferries
```

#### Claude Desktop Configuration

For global access in all Claude Desktop conversations:

**Linux**: `~/.config/Claude/claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "boston-harbor-ferries": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/full/path/to/boston-harbor-ferries",
        "python",
        "-m",
        "boston_harbor_ferries.mcp_server"
      ],
      "env": {
        "APRS_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

#### Example Questions for Claude

Once configured, you can ask Claude:
- "Where is CRISPUS ATTUCKS right now?"
- "Show me all active ferries"
- "What are the ferry routes in Boston Harbor?"
- "Clear the cache and check ferry positions again"

#### Understanding Position Data

**Operating Hours**: Ferries transmit APRS positions during service hours (05:00-19:00 daily)
- **Peak times**: 06:00-10:00 (morning) and 15:00-18:00 (evening)
- **Off-hours**: No position data when ferries are not operating
- **Data age**: Position reports update every 1-2 minutes when active

If you see old position data (>1 hour), the ferry is likely docked between runs or service has ended for the day. Check during peak commute hours for live tracking.

All 6 MCP tools tested and working ✅ (see `gmake test`)

### Bonus: FreeBSD Leave Reminder MCP Server

This repository also includes a standalone MCP server that wraps FreeBSD's `leave(1)` command for setting reminders.

**See [LEAVE_MCP.md](LEAVE_MCP.md) for complete documentation.**

Quick test:
```bash
gmake test-leave-mcp
```

Tools available:
- `set_reminder` - Set a reminder for a specific time or duration
- `check_reminders` - View active reminders
- `cancel_reminders` - Cancel all reminders

Example: "Remind me to leave in 30 minutes" → Uses `+0030` format

## Python API

```python
from boston_harbor_ferries import APRSClient, VESSELS

# Initialize client (loads API key from env)
with APRSClient() as client:
    # Track specific ferry
    position = client.get_vessel_position("368157410")
    if position:
        print(f"{position.vessel.name} at {position.latitude}, {position.longitude}")

    # Track all ferries
    positions = client.get_all_ferries()
    for pos in positions:
        print(f"{pos.vessel.name}: {pos.age_seconds:.0f}s old")
```

## API Terms Compliance

This tool complies with aprs.fi API terms of service:

- ✅ Credits aprs.fi as data source in all output
- ✅ Provides link back to aprs.fi
- ✅ Free to use for all users
- ✅ Includes User-Agent header with app name/version
- ✅ Each user uses their own API key
- ✅ Built-in rate limiting (10 req/min default)
- ✅ Intelligent caching (2 min TTL default)
- ✅ Only queries when actively needed (no background polling)

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy boston_harbor_ferries
```

## License

MIT

## Acknowledgments

Data provided by [aprs.fi](https://aprs.fi/#!lat=42.355&lng=-71.040&z=13) - Hessu's excellent APRS infrastructure service.

Ferry service operated by [Seaport Ferry](https://seaportferry.com).