SeaSense

Spoken sea-safety briefings for coastal fishermen, in English, Tamil and Hindi.

SeaSense tells a fisherman the waves, wind and rain for his usual fishing zone over the next 12 hours, and says plainly whether it's Safe, Caution or Don't go. It uses the live forecast, remembers each user's zone and language, and speaks the answer aloud.

Built for the Build, Ship, Shape: Amazon Developer Hackathon (Alexa+ track).

How it works

 Alexa+ / any MCP client ──► server.py (MCP server, 7 tools) ─┐
                                                              ├──► seasense_core.py ──► Open-Meteo Marine + Forecast APIs (live)
 Web browser ─────────────► web.py (web app + JSON API) ──────┘        │
                                                                       ├── risk.py   Safe / Caution / Don't go rules
                                                                       ├── i18n.py   English, Tamil, Hindi text
                                                                       └── zones.py  5 Tamil Nadu fishing zones

• Backend: seasense_core.py fetches the live forecast for the next 12 hours, works out the trip risk and writes the spoken text. Both front ends use it, so they always agree.

• Voice front end: server.py is an MCP server. Alexa+ (or Claude Desktop, or MCP Inspector) calls its tools.

• Visual front end: web.py serves a web app with a risk card, live metrics, 12-hour charts and a Listen button that reads the briefing aloud in the chosen language.

• One account, two front ends: users sign in with their name and a 4 to 6 digit PIN (stored as a salted PBKDF2 hash). Their zone and language are one profile: set it on the web, and Alexa+ uses it when the same person asks by name, and the reverse.

Related MCP server: Surf Forecast MCP

What makes SeaSense different

MCP tools

language accepts en, ta (Tamil) or hi (Hindi). Zone names work in any of the three languages, for example Rameswaram, ராமேஸ்வரம் or रामेश्वरम.

Read-only tools (get_sea_briefing, check_trip_risk, find_best_time, check_on_trip) carry read_only_hint, so a client like Alexa+ can call them without asking for confirmation. The tools that save something are marked as writes.

Example output:

Sea briefing for Rameswaram. Waves are 0.8 metres now, up to 1.1 metres in the next 12 hours.
Wind is 14 km/h, with gusts up to 26 km/h around 3 PM. Little chance of rain.
Trip risk: Safe, because of waves under 1.5 metres and gusts under 30 km/h.

(Illustrative format. Live numbers come from the current forecast.)

Setup

Requires Python 3.10+ (and Node.js only if you want MCP Inspector). No API keys are needed.

Windows (PowerShell)

python -m venv .venv
Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass   # only if activation is blocked
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

macOS / Linux

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run

MCP server over Streamable HTTP (MCP spec 2025-11-25, the transport the Alexa+ track requires):

python server.py --http                 # serves http://127.0.0.1:8000/mcp
python server.py --http --port 9000     # pick another port

To test it, run npx @modelcontextprotocol/inspector in a second terminal, choose Streamable HTTP, enter http://127.0.0.1:8000/mcp and click Connect.

MCP server over stdio (MCP Inspector's stdio mode, Claude Desktop):

npx @modelcontextprotocol/inspector .venv/Scripts/python.exe server.py   # Windows
npx @modelcontextprotocol/inspector .venv/bin/python server.py           # macOS / Linux

Claude Desktop: add this to claude_desktop_config.json (use your own absolute paths):

{
  "mcpServers": {
    "seasense": {
      "command": "C:\\path\\to\\seasense\\.venv\\Scripts\\python.exe",
      "args": ["C:\\path\\to\\seasense\\server.py"]
    }
  }
}

Web app:

python web.py

Then open http://127.0.0.1:8080, create an account, and you're on the dashboard. For Tamil and Hindi voices, use Microsoft Edge, which includes natural Indian-language voices. The harbour board is at http://127.0.0.1:8080/board.

Run web.py and server.py --http at the same time: they share the same accounts, saved zones and trips, stored in data/ (git-ignored).

Tests

python -m unittest discover tests -v     # or: pip install pytest && python -m pytest tests

33 automated tests, no internet needed (the forecast is replaced with fixed sample data). They cover the risk rules and their exact boundaries, zone matching in all 3 languages, reports in all 3 languages, voice tools sharing the web profile, sign-up validation, the full account flow, best-time windows, trip check-in and overdue alerts, the worse-weather warning, family links, the harbour board, PIN brute-force lockout, change PIN, delete account, damaged-file recovery, forecast failure, security headers and cookies, and 404s.

Security

• PINs are stored only as salted PBKDF2-SHA256 hashes (200,000 rounds), never as plain text.

• 5 wrong PINs within 10 minutes lock that name for 10 minutes (HTTP 429).

• Session cookie is HttpOnly and SameSite=Lax. Set SEASENSE_HTTPS=1 when serving over HTTPS to make it Secure.

• Requests that change data must be JSON, which blocks cross-site form attacks.

• Headers: Content-Security-Policy, X-Frame-Options: DENY, nosniff, Referrer-Policy, Permissions-Policy.

• Account files are written atomically. A damaged file is set aside and never silently overwritten.

Known limits: lockout is per name, so someone could deliberately lock out another user for 10 minutes. Accounts live in JSON files, which suits a demo but not thousands of users (move to SQLite or Postgres). There's no PIN reset, because there's no email or SMS channel yet. Run behind HTTPS before putting it on the internet.

Configuration

No API keys or secrets are needed, because Open-Meteo is free and keyless.

Risk rules

These are starter thresholds for a hackathon demo, not official IMD guidance. Always follow IMD and INCOIS warnings before going to sea.

The verdict uses the worst wave height and gust in the window. Thresholds live in risk.py, so they're easy to replace with validated values.

Zones

Chennai coast, Nagapattinam, Rameswaram, Thoothukudi, Kanyakumari: points a little offshore, because the marine model has no wave data on land. Partial names work too (rames matches Rameswaram; at least 3 letters are needed).

Data

Live hourly forecast from Open-Meteo (Marine API for wave height, Forecast API for wind, gusts and rain chance). It's free and needs no API key. The two API calls run in parallel with httpx, and each forecast is cached for 10 minutes. If a call fails, users hear a short apology and the error is logged to stderr.

Why we demo outside Alexa+

We couldn't test on an Alexa+ device ourselves, so we tested with MCP Inspector and Claude Desktop. The server speaks standard MCP (spec 2025-11-25) over Streamable HTTP, the transport the Alexa+ track requires.

What's next

• Alexa+ skill listing, so fishermen can just ask out loud

• SMS alerts before dawn for phones without data

• Malayalam and Telugu, and more zones along the whole Indian coast

• Official IMD and INCOIS warnings layered on top of the forecast

Team

Kanisha and Deva (B.R Devamayookha).

License

Code under the MIT License, see LICENSE. Weather and marine data from Open-Meteo; see their terms for attribution.