diff --git a/docs/Caddyfile.prod b/docs/Caddyfile.prod
index 918fad7..f9b0754 100644
--- a/docs/Caddyfile.prod
+++ b/docs/Caddyfile.prod
@@ -1,8 +1,6 @@
:4321 {
encode gzip
- redir / /getting-started/ permanent
-
handle {
root * /usr/share/caddy
try_files {path} {path}/index.html
diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
index 9e3c248..b82048f 100644
--- a/docs/astro.config.mjs
+++ b/docs/astro.config.mjs
@@ -21,7 +21,12 @@ export default defineConfig({
],
social: [
{
- icon: "github",
+ icon: "seti:git",
+ label: "Source",
+ href: "https://git.supported.systems/MCP/mcnoaa-tides",
+ },
+ {
+ icon: "seti:python",
label: "PyPI",
href: "https://pypi.org/project/mcnoaa-tides/",
},
diff --git a/docs/src/content/docs/getting-started/index.mdx b/docs/src/content/docs/getting-started/index.mdx
index 390f9cf..bcacb6b 100644
--- a/docs/src/content/docs/getting-started/index.mdx
+++ b/docs/src/content/docs/getting-started/index.mdx
@@ -7,16 +7,17 @@ sidebar:
import { Card, CardGrid } from '@astrojs/starlight/components';
-**mcnoaa-tides** is an MCP server that connects language models to the
+**mcnoaa-tides** is an [MCP](https://modelcontextprotocol.io/) server that
+connects AI assistants to the
[NOAA CO-OPS Tides and Currents API](https://tidesandcurrents.noaa.gov/api/).
It exposes tide predictions, observed water levels, and meteorological
-observations from approximately 301 U.S. coastal stations -- all through a
+observations from approximately 301 U.S. coastal stations — all through a
clean tool interface that any MCP-compatible client can call.
Built for marine planning. Whether you are timing a fishing trip around an
incoming tide, checking wind and pressure before launching a boat, deploying
crab pots at the right tidal phase, or just confirming it is safe to get on
-the water -- mcnoaa-tides gives your assistant direct access to the same
+the water — mcnoaa-tides gives your assistant direct access to the same
federal data mariners and forecasters rely on.
## Capabilities
@@ -60,29 +61,38 @@ The fastest path is `uvx`, which runs the server without a permanent install:
uvx mcnoaa-tides
```
-To register it as a tool server in Claude Code:
+Register it as a tool server in your MCP client. For example, in Claude Code:
```bash
-# Add to Claude Code
claude mcp add mcnoaa-tides -- uvx mcnoaa-tides
```
+Most MCP clients accept a JSON config block — add this to your client's
+MCP settings:
+
+```json
+{
+ "mcnoaa-tides": {
+ "command": "uvx",
+ "args": ["mcnoaa-tides"]
+ }
+}
+```
+
If you want tide charts and conditions dashboards, install with visualization
support:
```bash
-# With visualization support (matplotlib + plotly)
uv pip install mcnoaa-tides[viz]
```
For HTTP transport (useful in Docker or multi-client setups):
```bash
-# Streamable HTTP endpoint
MCP_TRANSPORT=streamable-http MCP_PORT=8000 uvx mcnoaa-tides
```
-See the [deployment docs](/how-to/) for full Docker and production configuration.
+See the [Quickstart](/getting-started/quickstart/) for step-by-step setup.
## Next steps
diff --git a/docs/src/content/docs/how-to/beach-activities.mdx b/docs/src/content/docs/how-to/beach-activities.mdx
new file mode 100644
index 0000000..4afdae1
--- /dev/null
+++ b/docs/src/content/docs/how-to/beach-activities.mdx
@@ -0,0 +1,175 @@
+---
+title: Beach Activities
+description: Plan snorkeling, tide pooling, beachcombing, and paddle sports around the tides
+sidebar:
+ order: 4
+---
+
+import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';
+
+The ocean doesn't care about your schedule — but with tide data, you can find the windows that work. This guide covers four beach activities where timing around the tides makes the difference between a great outing and a wasted trip.
+
+## Snorkeling at low tide
+
+> "When's the next good low tide for snorkeling near La Jolla?"
+
+The assistant finds La Jolla's nearest station (La Jolla, 9410230) and pulls a week of high/low predictions. It's looking for the lowest tides — those are the windows when reefs, kelp beds, and rocky structure are most exposed and shallow water visibility is at its best.
+
+From the predictions, Thursday morning stands out: a −0.8 ft low at 06:42. That negative value means the water drops below the average low-water mark, exposing areas that are normally submerged.
+
+But a low tide alone isn't enough. The assistant checks water temperature (62°F — comfortable without a full wetsuit) and wind (4 knots from the west — calm enough for flat surface conditions and good underwater visibility).
+
+
+
+ The assistant called `get_tide_predictions` for station 9410230 with a 168-hour (7-day) window and `hilo` interval to find extreme lows. Then it called `get_meteorological_data` for wind and water temperature to verify conditions would be snorkel-friendly.
+
+
+ ```json title="get_tide_predictions"
+ {
+ "station_id": "9410230",
+ "hours": 168,
+ "interval": "hilo"
+ }
+ ```
+ ```json title="get_meteorological_data (wind)"
+ {
+ "station_id": "9410230",
+ "product": "wind",
+ "hours": 24
+ }
+ ```
+ ```json title="get_meteorological_data (water temp)"
+ {
+ "station_id": "9410230",
+ "product": "water_temperature",
+ "hours": 24
+ }
+ ```
+
+
+
+
+
+
+
+## Tide pooling with kids
+
+> "Find the lowest tide this week near Monterey for tide pooling"
+
+The assistant finds Monterey station (9413450) and scans a full week of predictions. It's hunting for the single deepest low — that's when the most tide pools are exposed and accessible.
+
+Wednesday has a −1.2 ft low at 07:18. That's an excellent tide-pooling tide. The assistant also checks wind (6 knots — safe for walking on slippery rocks) and air temperature (58°F — pack a light jacket).
+
+
+
+ The assistant called `get_tide_predictions` for 168 hours to scan the full week, identified the most extreme low, then used `marine_conditions_snapshot` for the target day to verify wind and temperature conditions would be family-friendly.
+
+
+ ```json title="get_tide_predictions"
+ {
+ "station_id": "9413450",
+ "hours": 168,
+ "interval": "hilo"
+ }
+ ```
+ ```json title="marine_conditions_snapshot"
+ {
+ "station_id": "9413450",
+ "hours": 24
+ }
+ ```
+
+
+
+
+
+
+
+## Beachcombing after a storm
+
+> "When's the next low tide at Cannon Beach? I want to look for agates after this storm."
+
+Storm events push interesting debris, shells, and semi-precious stones onto beaches. The best beachcombing combines two things: a recent storm (to deposit material) and a low tide (to expose the wrack line and sand flats).
+
+The assistant finds Cannon Beach's nearest station (Astoria, 9439040 — about 20 nm south) and checks recent conditions. Barometric pressure dropped 12 mb over the past 24 hours — confirming a significant weather system just passed through. The next low tide is tomorrow morning at 07:54, reaching 0.8 ft.
+
+
+
+ The assistant called `find_nearest_stations` for Cannon Beach coordinates, then `get_meteorological_data` for air pressure to confirm recent storm activity (looking for a pressure drop of 6+ mb). Finally, `get_tide_predictions` for the next 48 hours to find the first good low-tide window after the storm.
+
+
+ ```json title="find_nearest_stations"
+ {
+ "latitude": 45.8918,
+ "longitude": -123.9615,
+ "limit": 3
+ }
+ ```
+ ```json title="get_meteorological_data (pressure)"
+ {
+ "station_id": "9439040",
+ "product": "air_pressure",
+ "hours": 48
+ }
+ ```
+ ```json title="get_tide_predictions"
+ {
+ "station_id": "9439040",
+ "hours": 48,
+ "interval": "hilo"
+ }
+ ```
+
+
+
+
+
+## Kayak and paddleboard timing
+
+> "I want to paddle out from Morro Bay tomorrow morning. When's the calmest window?"
+
+For paddle sports, the key is *slack water* — the brief transition between flood and ebb when current is minimal. Strong tidal currents through narrow bay mouths can make launching or returning dangerous for paddlers.
+
+The assistant finds Morro Bay station (9412110) and uses `tidal_phase` to identify the next slack windows. Tomorrow there's a slack-high at 09:12 (the tide just finished rising and hasn't started falling yet) and a slack-low at 15:48.
+
+The morning slack is the better option — wind typically builds through the afternoon on the Central Coast, and the morning window offers calmer air on top of calmer water. The assistant confirms: wind forecast is 3 knots at 09:00, building to 12 knots by 15:00.
+
+
+
+ The assistant called `get_tide_predictions` with `hilo` interval to find the turning points (slack water occurs at these transitions), then `get_meteorological_data` for wind to compare morning vs. afternoon conditions. A turning point from rising-to-falling is "slack high" — minimal current and maximum depth.
+
+
+ ```json title="get_tide_predictions"
+ {
+ "station_id": "9412110",
+ "hours": 36,
+ "interval": "hilo"
+ }
+ ```
+ ```json title="get_meteorological_data (wind)"
+ {
+ "station_id": "9412110",
+ "product": "wind",
+ "hours": 36
+ }
+ ```
+
+
+
+
+
+
diff --git a/docs/src/content/docs/how-to/fishing-trip.mdx b/docs/src/content/docs/how-to/fishing-trip.mdx
index badad81..e36bf4e 100644
--- a/docs/src/content/docs/how-to/fishing-trip.mdx
+++ b/docs/src/content/docs/how-to/fishing-trip.mdx
@@ -5,139 +5,144 @@ sidebar:
order: 1
---
-import { Aside } from '@astrojs/starlight/components';
+import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';
-A productive day on the water starts with knowing what the tide is doing and what the weather has in store. This guide walks through using mcnoaa-tides to find the best fishing windows at any coastal location.
+A productive day on the water starts with knowing what the tide is doing and what the weather has in store. This guide shows a typical conversation — ask your assistant to plan a trip, and it handles the station lookups, tide analysis, and weather checks behind the scenes.
-## 1. Find stations near your fishing spot
+## Finding your spot
-Start by locating the nearest NOAA tide stations. Pass your approximate GPS coordinates and the tool returns stations sorted by distance in nautical miles.
+> "I'm planning to fish near Seattle this weekend. When should I go?"
-```json title="Tool call"
-{
- "tool": "find_nearest_stations",
- "arguments": {
- "latitude": 47.6062,
- "longitude": -122.3321,
- "limit": 5
- }
-}
-```
+The assistant starts by finding the nearest NOAA tide stations to your location. Seattle has a primary station (9447130) right on Elliott Bay, plus secondary stations at Shilshole Bay and other nearby points. It picks the closest one automatically.
-```json title="Sample response"
-[
- {
- "id": "9447130",
- "name": "Seattle",
- "state": "WA",
- "lat": 47.6026,
- "lng": -122.3393,
- "is_tidal": true,
- "distance_nm": 0.3
- },
- {
- "id": "9447110",
- "name": "Shilshole Bay",
- "state": "WA",
- "lat": 47.6648,
- "lng": -122.4085,
- "is_tidal": true,
- "distance_nm": 4.1
- }
-]
-```
+
+
+ The assistant called `find_nearest_stations` with Seattle's coordinates and got back a ranked list sorted by distance. Station 9447130 (Seattle) is just 0.3 nautical miles away — close enough for accurate predictions.
+
+
+ ```json title="find_nearest_stations"
+ {
+ "latitude": 47.6062,
+ "longitude": -122.3321,
+ "limit": 5
+ }
+ ```
+ ```json title="Response (truncated)"
+ [
+ { "id": "9447130", "name": "Seattle", "state": "WA", "distance_nm": 0.3 },
+ { "id": "9447110", "name": "Shilshole Bay", "state": "WA", "distance_nm": 4.1 }
+ ]
+ ```
+
+
-## 2. Check tide predictions
+## Reading the tides
-Use the closest tidal station to pull high/low predictions. The default `hilo` interval gives you the turning points -- the times when the tide changes direction -- which is what matters most for fishing.
+Next, the assistant pulls 48 hours of high/low predictions from the Seattle station. These are the turning points — the times when the tide switches from rising to falling or vice versa.
-```json title="Tool call"
-{
- "tool": "get_tide_predictions",
- "arguments": {
- "station_id": "9447130",
- "hours": 48,
- "interval": "hilo"
- }
-}
-```
+The response shows four events over the first day:
-```json title="Sample response"
-{
- "predictions": [
- { "t": "2026-02-22 03:18", "v": "10.21", "type": "H" },
- { "t": "2026-02-22 09:42", "v": "2.14", "type": "L" },
- { "t": "2026-02-22 15:54", "v": "11.87", "type": "H" },
- { "t": "2026-02-22 22:06", "v": "-0.32", "type": "L" }
- ]
-}
-```
+| Time | Level (ft) | Type |
+|------|-----------|------|
+| 03:18 | 10.21 | High |
+| 09:42 | 2.14 | Low |
+| 15:54 | 11.87 | High |
+| 22:06 | −0.32 | Low |
-**Reading the predictions:**
-- `type: "H"` = high tide, `type: "L"` = low tide
-- `v` = predicted water level in feet above MLLW (Mean Lower Low Water)
-- Negative values indicate the water drops below the average low-tide mark
+That afternoon high at 15:54 (11.87 ft) is the biggest of the day — the flood tide leading into it will be strong. Water moving shoreward pushes baitfish into structure and triggers feeding.
+
+
+
+ The assistant called `get_tide_predictions` for station 9447130 with a 48-hour window and `hilo` interval. All levels are in feet above MLLW (Mean Lower Low Water). Negative values mean the water drops below the average low-tide mark.
+
+
+ ```json title="get_tide_predictions"
+ {
+ "station_id": "9447130",
+ "hours": 48,
+ "interval": "hilo"
+ }
+ ```
+ ```json title="Response"
+ {
+ "predictions": [
+ { "t": "2026-02-22 03:18", "v": "10.21", "type": "H" },
+ { "t": "2026-02-22 09:42", "v": "2.14", "type": "L" },
+ { "t": "2026-02-22 15:54", "v": "11.87", "type": "H" },
+ { "t": "2026-02-22 22:06", "v": "-0.32", "type": "L" }
+ ]
+ }
+ ```
+
+
-## 3. Check weather conditions
+## Checking the weather
-A good tide window is wasted if the wind is howling. Use `marine_conditions_snapshot` to pull tide predictions, observed water levels, wind, temperature, and pressure in a single call.
+A good tide window is wasted if the wind is howling. The assistant pulls a marine conditions snapshot — tide predictions, observed water levels, wind, temperature, and pressure — all in one call.
-```json title="Tool call"
-{
- "tool": "marine_conditions_snapshot",
- "arguments": {
- "station_id": "9447130",
- "hours": 24
- }
-}
-```
+For this Saturday it finds:
+- **Wind:** 8 knots sustained from the NW, gusts to 12 — comfortable for small-boat fishing
+- **Barometric pressure:** 1016 mb and falling slightly — a gentle drop often improves bite rates
+- **Water temperature:** 48°F — right in the sweet spot for salmon
+- **Air temperature:** 52°F — dress in layers
-The response includes multiple products fetched in parallel. The fields most relevant for fishing:
-
-| Product | Key fields | What to look for |
-|---------|-----------|-----------------|
-| `wind` | `s` (speed kn), `g` (gust kn), `dr` (direction) | Sustained under 15 kn for comfortable small-boat fishing |
-| `air_pressure` | `v` (millibars) | Falling pressure often correlates with improved bite rates |
-| `water_temperature` | `v` (degrees F) | Species-dependent -- cold water slows metabolism and feeding |
-| `air_temperature` | `v` (degrees F) | Personal comfort and safety planning |
+
+
+ The assistant called `marine_conditions_snapshot` for station 9447130 with a 24-hour window. This fetches tide predictions, observed water, wind, air/water temperature, and pressure in parallel. Products not available at a station appear under `unavailable` rather than causing errors.
+
+
+ ```json title="marine_conditions_snapshot"
+ {
+ "station_id": "9447130",
+ "hours": 24
+ }
+ ```
+
+
-## 4. Use the prompt template
+## The recommendation
-For a guided experience, use the `plan_fishing_trip` prompt. It orchestrates all of the above steps and produces a structured recommendation.
+Putting it all together, the assistant recommends a fishing window:
-```json title="Prompt call"
-{
- "prompt": "plan_fishing_trip",
- "arguments": {
- "location": "Seattle, WA",
- "target_species": "chinook salmon",
- "date": "2026-02-22"
- }
-}
-```
+> **Saturday 13:30–16:30** — fish the last two hours of the flood tide through the first hour of ebb. Wind is manageable, pressure is falling (fish tend to feed more actively before a front), and water temperature is in range for salmon.
-The prompt walks through station discovery, tide analysis, and conditions assessment, then recommends a fishing window that aligns favorable tide phase with manageable weather. It includes the best tide window, expected water levels, a weather summary, and any safety concerns.
+That's three tool calls and a recommendation, all from a single question.
-Both `target_species` and `date` are optional. If omitted, the prompt defaults to general advice for the current day.
+## Using the prompt template
+
+For a more structured experience, ask your assistant to use the `plan_fishing_trip` prompt. It orchestrates the same workflow — station discovery, tide analysis, conditions assessment — and produces a formatted recommendation with the best window, expected water levels, weather summary, and safety notes.
+
+
+
+ The `plan_fishing_trip` prompt accepts `location`, `target_species`, and `date` as optional parameters. If omitted, it defaults to general advice for the current day at the nearest station.
+
+
+ ```json title="plan_fishing_trip"
+ {
+ "location": "Seattle, WA",
+ "target_species": "chinook salmon",
+ "date": "2026-02-22"
+ }
+ ```
+
+
## Tips for better results
-**Water temperature drives species behavior.** Most gamefish have a preferred temperature band. Salmon feed aggressively in the 48-56 F range. Striped bass slow down below 50 F. If the water temperature is outside a species' comfort zone, even perfect tide timing may not help.
+**Water temperature drives species behavior.** Most gamefish have a preferred temperature band. Salmon feed aggressively in the 48–56°F range. Striped bass slow down below 50°F. If the water temperature is outside a species' comfort zone, even perfect tide timing may not help.
-**Falling barometric pressure is your friend.** Fish sense pressure changes through their swim bladders. A steady drop of 2-4 mb over several hours often triggers feeding activity, particularly in the hour or two before a front arrives. After the front passes and pressure stabilizes, the bite usually slows.
+**Falling barometric pressure is your friend.** Fish sense pressure changes through their swim bladders. A steady drop of 2–4 mb over several hours often triggers feeding, particularly in the hour or two before a front arrives. After the front passes and pressure stabilizes, the bite usually slows.
-**Tidal range matters as much as timing.** Spring tides (around new and full moons) produce stronger currents and more water movement, which can concentrate bait and trigger aggressive feeding. Neap tides move less water and may produce slower fishing in current-dependent spots.
-
-**Check the datum.** All water level values default to MLLW (Mean Lower Low Water). If you need levels relative to a different reference, pass the `datum` parameter -- for example, `datum: "MSL"` for mean sea level or `datum: "NAVD"` for the North American Vertical Datum.
+**Tidal range matters as much as timing.** Spring tides (around new and full moons) produce stronger currents and more water movement, which concentrates bait and triggers aggressive feeding. Neap tides move less water and may produce slower fishing in current-dependent spots.
diff --git a/docs/src/content/docs/how-to/smartpot.mdx b/docs/src/content/docs/how-to/smartpot.mdx
index 6adda31..f40341e 100644
--- a/docs/src/content/docs/how-to/smartpot.mdx
+++ b/docs/src/content/docs/how-to/smartpot.mdx
@@ -5,237 +5,220 @@ sidebar:
order: 2
---
-import { Aside } from '@astrojs/starlight/components';
+import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';
-SmartPot tools bridge NOAA tide data with autonomous crab pot operations. This guide covers the full deployment lifecycle: assessing conditions, deploying at the right tidal phase, monitoring for anomalies during soak, and enriching catch records with tidal context for long-term analysis.
+SmartPot tools bridge NOAA tide data with autonomous crab pot operations. This guide walks through a typical deployment conversation — from checking conditions before you head out, through monitoring a multi-day soak, to analyzing catch patterns over time.
-## 1. Check tidal phase at your location
+## Checking conditions before you go
-Before heading to the deployment site, determine what the tide is doing right now. The `tidal_phase` tool accepts GPS coordinates and automatically finds the nearest NOAA tidal station.
+> "I want to deploy crab pots near Anacortes. Is now a good time?"
-```json title="Tool call"
-{
- "tool": "tidal_phase",
- "arguments": {
- "latitude": 48.3928,
- "longitude": -122.6775
- }
-}
-```
+The assistant starts by figuring out what the tide is doing right now at your location. It finds the nearest NOAA station (Anacortes, 9448576) and classifies the current tidal phase.
-```json title="Sample response"
-{
- "station": {
- "id": "9448576",
- "name": "Anacortes",
- "lat": 48.5117,
- "lng": -122.618
- },
- "station_distance_nm": 7.2,
- "timestamp_utc": "2026-02-22T14:30:00+00:00",
- "phase": "flood",
- "description": "Tide is rising (flood) -- water moving shoreward",
- "previous": { "type": "low", "time": "2026-02-22 11:48", "level_ft": -0.42 },
- "next": { "type": "high", "time": "2026-02-22 17:54", "level_ft": 9.87 },
- "minutes_since_previous": 162,
- "minutes_to_next": 204,
- "progress_pct": 44.3,
- "latest_observed": { "time": "2026-02-22 14:24", "level_ft": 4.61 }
-}
-```
+Right now it's mid-flood — the tide has been rising for about 2.5 hours since a −0.42 ft low, heading toward a 9.87 ft high in about 3.5 hours. That's 44% through the flood phase.
-The response tells you the current phase (ebb, flood, slack_high, or slack_low), how far through the phase you are, and the bracketing high/low events.
+
+
+ The assistant called `tidal_phase` with your GPS coordinates. It automatically found the nearest tidal station (Anacortes, 7.2 nm away) and classified the current phase as "flood" with 44.3% progress. The response includes the bracketing high/low events and the latest observed water level.
+
+
+ ```json title="tidal_phase"
+ {
+ "latitude": 48.3928,
+ "longitude": -122.6775
+ }
+ ```
+ ```json title="Response"
+ {
+ "station": { "id": "9448576", "name": "Anacortes" },
+ "station_distance_nm": 7.2,
+ "phase": "flood",
+ "description": "Tide is rising (flood) — water moving shoreward",
+ "previous": { "type": "low", "time": "2026-02-22 11:48", "level_ft": -0.42 },
+ "next": { "type": "high", "time": "2026-02-22 17:54", "level_ft": 9.87 },
+ "progress_pct": 44.3,
+ "latest_observed": { "time": "2026-02-22 14:24", "level_ft": 4.61 }
+ }
+ ```
+
+
-You can also pass a `station_id` directly if you already know your reference station:
+## Getting a deployment assessment
-```json
-{
- "tool": "tidal_phase",
- "arguments": {
- "station_id": "9448576"
- }
-}
-```
+The assistant then runs a full deployment briefing — evaluating wind, water temperature, pressure, and tide schedule against safety thresholds to produce a GO, CAUTION, or NO-GO recommendation.
-## 2. Get a deployment assessment
+For a 48-hour soak starting now, the briefing comes back **GO**:
+- **Wind:** 8.2 knots sustained, gusts to 12.4 from the NW
+- **Water temperature:** 46.3°F
+- **Pressure:** 1018.4 mb, stable
+- **Tidal cycles during soak:** 4 complete cycles
+- **Advisories:** none
-The `deployment_briefing` tool evaluates current conditions against safety thresholds and produces a GO, CAUTION, or NO-GO recommendation.
+
+
+ The assistant called `deployment_briefing` with your coordinates and a 48-hour soak window. It automatically found the nearest station, fetched the tide schedule for the full soak period, pulled current weather conditions, and applied threshold logic to produce the assessment.
+
+
+ ```json title="deployment_briefing"
+ {
+ "latitude": 48.3928,
+ "longitude": -122.6775,
+ "soak_hours": 48
+ }
+ ```
+ ```json title="Response (abbreviated)"
+ {
+ "station": { "id": "9448576", "name": "Anacortes" },
+ "soak_window": { "hours": 48, "tidal_cycles": 4 },
+ "conditions": {
+ "wind": { "speed_kn": 8.2, "gust_kn": 12.4, "direction": "NW" },
+ "water_temperature_f": 46.3,
+ "air_pressure_mb": 1018.4
+ },
+ "assessment": "GO",
+ "advisories": []
+ }
+ ```
+
+
-```json title="Tool call"
-{
- "tool": "deployment_briefing",
- "arguments": {
- "latitude": 48.3928,
- "longitude": -122.6775,
- "soak_hours": 48
- }
-}
-```
+### Assessment thresholds
-```json title="Sample response (abbreviated)"
-{
- "station": { "id": "9448576", "name": "Anacortes" },
- "station_distance_nm": 7.2,
- "soak_window": {
- "begin_utc": "20260222 14:30",
- "end_utc": "20260224 14:30",
- "hours": 48,
- "tidal_cycles": 4
- },
- "tide_schedule": [
- { "type": "high", "time_utc": "2026-02-22 17:54", "level_ft": 9.87 },
- { "type": "low", "time_utc": "2026-02-23 00:12", "level_ft": 3.21 },
- { "type": "high", "time_utc": "2026-02-23 06:36", "level_ft": 8.44 }
- ],
- "conditions": {
- "wind": { "speed_kn": 8.2, "gust_kn": 12.4, "direction": "NW" },
- "water_temperature_f": 46.3,
- "air_pressure_mb": 1018.4
- },
- "assessment": "GO",
- "advisories": []
-}
-```
-
-### Assessment criteria
-
-The briefing applies these thresholds automatically:
+The briefing applies these criteria automatically:
| Condition | GO | CAUTION | NO-GO |
|-----------|-----|---------|-------|
-| Sustained wind | Under 15 kn | 15-20 kn | Over 20 kn |
-| Wind gusts | Under 25 kn | 25-30 kn | Over 30 kn |
-| Water temperature | Above 40 F | -- | -- (advisory below 40 F) |
-| Barometric pressure | Stable or rising | -- | -- (advisory if falling >3 mb) |
+| Sustained wind | Under 15 kn | 15–20 kn | Over 20 kn |
+| Wind gusts | Under 25 kn | 25–30 kn | Over 30 kn |
+| Water temperature | Above 40°F | — | — (advisory below 40°F) |
+| Barometric pressure | Stable or rising | — | — (advisory if falling > 3 mb) |
-## 3. Monitor for anomalies during soak
+## Monitoring during the soak
-During a multi-day soak, conditions can change. The `water_level_anomaly` tool compares observed water levels against predictions to detect storm surge, seiche events, or unusual deviations that might affect pot stability or recovery.
+A day into the soak, you check in:
-```json title="Tool call"
-{
- "tool": "water_level_anomaly",
- "arguments": {
- "station_id": "9448576",
- "window_hours": 6,
- "threshold_ft": 0.5
- }
-}
-```
+> "How are conditions looking at my pot deployment site? Any anomalies?"
-```json title="Sample response"
-{
- "station_id": "9448576",
- "window_hours": 6,
- "threshold_ft": 0.5,
- "risk_level": "normal",
- "explanation": "Water levels within 0.5 ft of predictions -- conditions as expected",
- "max_deviation_ft": 0.31,
- "mean_deviation_ft": 0.14,
- "direction": "above",
- "sample_count": 60
-}
-```
+The assistant compares observed water levels against predictions to detect storm surge, seiche events, or unusual deviations. For the past 6 hours, everything is tracking normally — max deviation is 0.31 ft, well within the 0.5 ft threshold.
-Risk levels are based on the deviation threshold (default 0.5 ft):
+
+
+ The assistant called `water_level_anomaly` for station 9448576, comparing the last 6 hours of observed water levels against predictions. A deviation under the threshold (0.5 ft default) means conditions are tracking the forecast — no action needed.
+
+
+ ```json title="water_level_anomaly"
+ {
+ "station_id": "9448576",
+ "window_hours": 6,
+ "threshold_ft": 0.5
+ }
+ ```
+ ```json title="Response"
+ {
+ "risk_level": "normal",
+ "explanation": "Water levels within 0.5 ft of predictions — conditions as expected",
+ "max_deviation_ft": 0.31,
+ "mean_deviation_ft": 0.14,
+ "direction": "above",
+ "sample_count": 60
+ }
+ ```
+
+
-| Risk level | Deviation | Meaning |
-|-----------|-----------|---------|
-| **normal** | Under threshold | Conditions tracking predictions -- no action needed |
-| **elevated** | 1x to 2x threshold | Moderate deviation -- monitor conditions more frequently |
-| **high** | Over 2x threshold | Possible storm surge or seiche -- consider early recovery |
+### Risk levels
+
+| Risk | Deviation | What it means |
+|------|-----------|---------------|
+| **normal** | Under threshold | Tracking predictions — no action needed |
+| **elevated** | 1× to 2× threshold | Moderate deviation — monitor more frequently |
+| **high** | Over 2× threshold | Possible storm surge or seiche — consider early recovery |
-## 4. Analyze historical catch data
+## Analyzing catch patterns
-After collecting catch records over multiple deployments, use `catch_tidal_context` to enrich each event with the tidal phase at the time and location of retrieval. This reveals whether certain tidal conditions consistently produce better catches.
+After several deployments, you have catch records to analyze:
-```json title="Tool call"
-{
- "tool": "catch_tidal_context",
- "arguments": {
- "events": [
- {
- "timestamp": "2026-02-18T10:30:00Z",
- "latitude": 48.3928,
- "longitude": -122.6775,
- "catch_count": 14,
- "species": "dungeness"
- },
- {
- "timestamp": "2026-02-19T16:15:00Z",
- "latitude": 48.3895,
- "longitude": -122.6810,
- "catch_count": 22,
- "species": "dungeness"
+> "I've been logging my catches. Can you tell me if tidal conditions affect my numbers?"
+
+Pass your catch events to the assistant and it enriches each one with the tidal phase at that time and location. Over time, patterns emerge — maybe mid-flood retrievals consistently outperform ebb retrievals, or catches peak during spring tides.
+
+
+
+ The assistant called `catch_tidal_context` with your batch of events. Each event is returned with a `tidal` key showing the phase, progress percentage, and reference station at the time of retrieval. All your original fields (catch_count, species, bait_type, etc.) pass through unchanged.
+
+
+ ```json title="catch_tidal_context"
+ {
+ "events": [
+ {
+ "timestamp": "2026-02-18T10:30:00Z",
+ "latitude": 48.3928,
+ "longitude": -122.6775,
+ "catch_count": 14,
+ "species": "dungeness"
+ },
+ {
+ "timestamp": "2026-02-19T16:15:00Z",
+ "latitude": 48.3895,
+ "longitude": -122.6810,
+ "catch_count": 22,
+ "species": "dungeness"
+ }
+ ]
+ }
+ ```
+ ```json title="Enriched event (one of two)"
+ {
+ "timestamp": "2026-02-19T16:15:00Z",
+ "catch_count": 22,
+ "species": "dungeness",
+ "tidal": {
+ "station_id": "9448576",
+ "phase": "flood",
+ "progress_pct": 62.4,
+ "previous": { "type": "low", "time": "2026-02-19 12:30", "level_ft": 0.81 },
+ "next": { "type": "high", "time": "2026-02-19 18:48", "level_ft": 10.12 }
}
- ]
- }
-}
-```
-
-Each event is returned with a `tidal` key containing the phase classification, progress percentage, and reference station:
-
-```json title="Enriched event (one of two)"
-{
- "timestamp": "2026-02-19T16:15:00Z",
- "latitude": 48.3895,
- "longitude": -122.6810,
- "catch_count": 22,
- "species": "dungeness",
- "tidal": {
- "station_id": "9448576",
- "station_distance_nm": 7.35,
- "phase": "flood",
- "description": "Tide is rising (flood) -- water moving shoreward",
- "progress_pct": 62.4,
- "previous": { "type": "low", "time": "2026-02-19 12:30", "level_ft": 0.81 },
- "next": { "type": "high", "time": "2026-02-19 18:48", "level_ft": 10.12 }
- }
-}
-```
-
-All original fields (catch_count, species, pot_id, bait_type, or anything else you include) are passed through unchanged.
+ }
+ ```
+
+
-Over time, patterns emerge. You might find that mid-flood retrievals consistently outperform ebb retrievals, or that catches peak during spring tides. Use the `crab_pot_analysis` prompt to get a structured summary of these correlations.
+## The orchestrated workflow
-## 5. Use the orchestrated workflow
+For a complete deployment assessment in one shot, ask your assistant to use the `smartpot_deployment` prompt. It ties together station discovery, tidal phase, deployment briefing, and anomaly detection into a single guided workflow — producing an overall recommendation with optimal timing, expected tidal cycles, safety concerns, and a suggested recovery window.
-The `smartpot_deployment` prompt ties all of the above into a single guided workflow. It walks through station discovery, tidal phase check, deployment briefing, anomaly detection, and produces a synthesized deployment recommendation.
-
-```json title="Prompt call"
-{
- "prompt": "smartpot_deployment",
- "arguments": {
- "latitude": "48.3928",
- "longitude": "-122.6775",
- "soak_hours": "48"
- }
-}
-```
-
-The prompt produces:
-- An overall GO/CAUTION/NO-GO with reasoning
-- The optimal deployment window within the next 6 hours
-- Expected tidal cycles during the soak period
-- Safety or recovery concerns
-- A recommended recovery time based on the tide schedule
+
+
+ The `smartpot_deployment` prompt accepts `latitude`, `longitude`, and `soak_hours` as parameters. It walks through each assessment step and synthesizes the results into a deployment plan.
+
+
+ ```json title="smartpot_deployment"
+ {
+ "latitude": "48.3928",
+ "longitude": "-122.6775",
+ "soak_hours": "48"
+ }
+ ```
+
+
diff --git a/docs/src/content/docs/how-to/visualization.mdx b/docs/src/content/docs/how-to/visualization.mdx
index 8e95e31..2808f16 100644
--- a/docs/src/content/docs/how-to/visualization.mdx
+++ b/docs/src/content/docs/how-to/visualization.mdx
@@ -5,35 +5,45 @@ sidebar:
order: 3
---
-import { Aside } from '@astrojs/starlight/components';
+import { Tabs, TabItem, Aside } from '@astrojs/starlight/components';
-mcnoaa-tides includes two visualization tools that render NOAA data into charts -- a tide prediction plot and a multi-panel conditions dashboard. Both support PNG (inline image) and HTML (interactive Plotly) output formats.
+mcnoaa-tides includes two visualization tools that render NOAA data into charts — a tide prediction plot and a multi-panel conditions dashboard. Both produce PNG (inline image) or HTML (interactive Plotly) output.
## Prerequisites
-The visualization tools require optional dependencies that are not installed by default. Install the `viz` extras:
+The visualization tools require optional dependencies:
```bash
uv pip install mcnoaa-tides[viz]
```
-This adds `matplotlib` (for PNG rendering) and `plotly` (for interactive HTML charts). If the extras are missing, the tools return a clear error message with the install command.
+This adds `matplotlib` (PNG rendering) and `plotly` (interactive HTML). If the extras are missing, the tools return a clear error with the install command.
## Tide chart
-The `visualize_tides` tool renders a water level curve with high and low tide markers. It fetches 6-minute interval predictions for a smooth line and overlays observed water levels as a dashed comparison trace.
+> "Show me the tides for Seattle over the next 48 hours"
-```json title="Tool call"
-{
- "tool": "visualize_tides",
- "arguments": {
- "station_id": "9447130",
- "hours": 48,
- "include_observed": true,
- "format": "png"
- }
-}
-```
+The assistant generates a tide chart for station 9447130. The chart plots a smooth water-level curve from 6-minute predictions, marks each high (**H**) and low (**L**) turning point, and overlays observed water levels as a dashed comparison trace.
+
+
+
+The observed overlay shows how actual conditions compare to the forecast — useful for spotting storm surge or wind-driven deviations. Since NOAA only provides observations for the past, you'll see the dashed line for the first portion of the chart and predictions alone for the remainder.
+
+
+
+ The assistant called `visualize_tides` for station 9447130 with a 48-hour window, observed overlay enabled, and PNG format. The chart appears inline in the conversation.
+
+
+ ```json title="visualize_tides"
+ {
+ "station_id": "9447130",
+ "hours": 48,
+ "include_observed": true,
+ "format": "png"
+ }
+ ```
+
+
### Parameters
@@ -41,81 +51,75 @@ The `visualize_tides` tool renders a water level curve with high and low tide ma
|-----------|---------|-------------|
| `station_id` | required | 7-digit NOAA station ID |
| `hours` | `48` | Time window for the chart |
-| `include_observed` | `true` | Overlay actual water level readings as a dashed line |
-| `format` | `"png"` | Output format: `png` or `html` |
-
-The chart marks each high tide (**H**) and low tide (**L**) on the prediction curve so you can see turning points at a glance. When `include_observed` is enabled, the dashed observed line shows how actual conditions compare to the forecast -- useful for spotting storm surge or wind-driven deviations.
-
-
-
-
+| `include_observed` | `true` | Overlay actual readings as a dashed line |
+| `format` | `"png"` | `png` (inline image) or `html` (interactive Plotly) |
## Conditions dashboard
-The `visualize_conditions` tool creates a multi-panel dashboard with up to four panels showing different marine data products side by side.
+> "Give me a full conditions dashboard for Seattle — I want to see everything"
-```json title="Tool call"
-{
- "tool": "visualize_conditions",
- "arguments": {
- "station_id": "9447130",
- "hours": 24,
- "format": "png"
- }
-}
-```
-
-### Parameters
-
-| Parameter | Default | Description |
-|-----------|---------|-------------|
-| `station_id` | required | 7-digit NOAA station ID |
-| `hours` | `24` | Time window for the dashboard |
-| `format` | `"png"` | Output format: `png` or `html` |
-
-### Dashboard panels
-
-The dashboard renders up to four panels depending on what the station supports:
-
-1. **Tides** -- Predicted water levels with observed overlay and high/low markers
-2. **Wind** -- Speed and gust readings in knots with direction
-3. **Temperature** -- Air and water temperature traces
-4. **Pressure** -- Barometric pressure with trend indication
+The assistant generates a multi-panel dashboard showing up to four marine data products side by side: tides, wind, temperature, and barometric pressure.
+Each panel draws from a different NOAA data product. If a station doesn't have a particular sensor (some lack wind gauges, for example), that panel is simply omitted rather than showing empty space.
+
+
+
+ The assistant called `visualize_conditions` for station 9447130 with a 24-hour window. This fetches tide predictions, observed water, wind speed/direction/gusts, air and water temperature, and barometric pressure — then renders them into a 4-panel layout.
+
+
+ ```json title="visualize_conditions"
+ {
+ "station_id": "9447130",
+ "hours": 24,
+ "format": "png"
+ }
+ ```
+
+
+
+### Dashboard panels
+
+1. **Tides** — Predicted water levels with observed overlay and H/L markers
+2. **Wind** — Speed and gust readings in knots with direction
+3. **Temperature** — Air and water temperature traces
+4. **Pressure** — Barometric pressure with trend indication
+
-## Output formats
+## Choosing a format
-### PNG
+### PNG — quick visual check
-PNG format returns an inline image directly in the MCP response. This is the default and works well for quick visual checks during a conversation -- the chart appears immediately without needing to open a separate file.
+PNG returns an inline image directly in the conversation. No files to manage, no browser to open. Best for quick checks during a planning conversation.
-### HTML
+### HTML — interactive exploration
-HTML format saves an interactive Plotly chart to `artifacts/charts/` and returns the file path. The filename includes the station ID, chart type, and UTC timestamp:
+> "Can I get that as an interactive chart instead?"
+
+HTML format saves a Plotly chart to `artifacts/charts/` and returns the file path. The filename includes the station ID, chart type, and UTC timestamp:
```
artifacts/charts/9447130_tides_20260222_143000.html
```
-Interactive charts support panning, zooming, hovering for exact values, and toggling individual traces on and off. They are useful when you need to examine a specific time window closely or share the chart with someone who wants to explore the data.
+Interactive charts support panning, zooming, hovering for exact values, and toggling individual traces. They're useful when you need to examine a specific time window closely or share the chart with someone.
## Combining charts with analysis
-Charts pair well with the data-fetching tools. A common workflow:
+A common workflow:
-1. Run `marine_conditions_snapshot` to get the raw numbers and identify anything notable
-2. Generate a `visualize_conditions` dashboard to see the full picture
-3. If the tide panel shows an interesting pattern, generate a focused `visualize_tides` chart with a longer time window
+> "Check conditions at Seattle and give me a visual summary"
+
+1. The assistant runs `marine_conditions_snapshot` to get raw numbers and spot anything notable
+2. It generates a `visualize_conditions` dashboard so you can see the full picture
+3. If the tide panel shows something interesting, it follows up with a focused `visualize_tides` chart over a longer window
For fishing trip planning, a 48-hour tide chart with the observed overlay gives you both the forecast and a visual check on how well predictions have tracked reality over the past day.
diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
new file mode 100644
index 0000000..7af975a
--- /dev/null
+++ b/docs/src/content/docs/index.mdx
@@ -0,0 +1,176 @@
+---
+title: mcnoaa-tides
+template: splash
+hero:
+ tagline: Real-time NOAA tide and marine data for AI assistants
+ image:
+ html: |
+
+ actions:
+ - text: Get Started
+ link: /getting-started/quickstart/
+ icon: right-arrow
+ variant: primary
+ - text: View Tools
+ link: /reference/tools/
+ variant: minimal
+ icon: open-book
+sidebar:
+ hidden: true
+---
+
+import { Card, CardGrid, LinkCard } from '@astrojs/starlight/components';
+
+
+
+## What's inside
+
+
+
+ Station discovery, tide predictions, water levels, weather data, marine
+ condition snapshots, tidal phase classification, deployment intelligence,
+ chart visualization, and diagnostics.
+
+
+ Guided workflows for fishing trip planning, marine safety checks,
+ crab pot deployment assessment, and catch-to-tide correlation analysis.
+
+
+ Station catalog, station detail, and nearby station lookup — structured
+ context that any MCP client can read directly.
+
+
+ Tide charts and multi-panel conditions dashboards rendered as PNG images
+ or interactive HTML with Plotly.
+
+
+
+
+
+
+
+## What can you do with it?
+
+Ask your assistant a question. It calls the right tools and comes back with an answer grounded in real NOAA data.
+
+
+
+ *"When's the best time to fish near Newport this weekend?"*
+
+ Finds nearby stations, pulls tide turning points, checks wind and
+ barometric pressure, and identifies the optimal incoming-tide window.
+
+
+ *"Is it safe to take the boat out from Seattle today?"*
+
+ Runs a marine safety check — wind speed, gust, visibility, water
+ temperature, and pressure trend — returns a GO / CAUTION / NO-GO.
+
+
+ *"When's the next good low tide for snorkeling at La Jolla?"*
+
+ Finds extreme low tides that expose reefs, checks water temperature
+ and wind to confirm conditions are worth the trip.
+
+
+ *"Find the lowest tide this week near Monterey for tide pooling"*
+
+ Scans 7 days of predictions for the deepest lows — negative values
+ mean water drops below the average low-water mark, exposing more pools.
+
+
+ *"Should I deploy pots near Anacortes right now?"*
+
+ Checks tidal phase, runs a deployment briefing with wind/temp/pressure
+ thresholds, and recommends an optimal soak window.
+
+
+ *"When will the tide be low enough to reach the tidepools at Cannon Beach?"*
+
+ Finds the next low-tide window, checks for post-storm debris potential
+ by looking at recent pressure drops and wind events.
+
+
+
+
+
+
+
+## Install
+
+The fastest way to run the server — no permanent install needed:
+
+```bash
+uvx mcnoaa-tides
+```
+
+Register it with your MCP client. For example, in Claude Code:
+
+```bash
+claude mcp add mcnoaa-tides -- uvx mcnoaa-tides
+```
+
+Or add to any MCP client's JSON config:
+
+```json
+{
+ "mcnoaa-tides": {
+ "command": "uvx",
+ "args": ["mcnoaa-tides"]
+ }
+}
+```
+
+
+
+