DEV Community: Bryan Clark

MCP server or a curl recipe in AGENTS.md? Measure the breakeven

Bryan Clark — Sun, 02 Aug 2026 15:30:03 +0000

The current consensus is that MCP is a token tax and you should just tell the agent to curl the API from its AGENTS.md. I measured both, for the same capability, against the same server. The tool schemas cost +408 tokens standing and save ~340–420 tokens per read, so the breakeven is roughly one tool call per turn — and with prompt caching (measured, not assumed: a 0.175× effective multiplier across 3,782 real requests) it moves to one read every five or six turns. But the tokens are the easy half and they nearly cancel. What actually decided it was a minus sign. Jump to the breakeven formula.

There's a good argument going around that MCP servers are a context-window tax — tool schemas at ~550–1,400 tokens each, benchmarks putting MCP at 4–32× the token cost of an equivalent CLI, a spec issue open on the overhead itself. The conclusion people draw is: skip the server, describe the API in your agent file, let the model shell out.

I have the same capability implemented both ways, so I measured it instead of arguing about it.

Two ways to let an agent read a boat

The job: an agent that can answer "how much water under the keel?" and "how's the house bank?" from a SignalK server — the open marine data server that normalises NMEA 2000/0183 into one JSON tree.

Option A — an MCP server. signalk-mcp exposes seven named tools. The schemas sit in the prompt every turn:

types.Tool(
    name="depth_state",
    description=(
        "Use this for 'what's our depth?' / 'how much under the keel?' / "
        "'how close are we to running aground?' — returns water depth with "
        "under-keel clearance first. below_keel_m IS the clearance under the "
        "hull (no draft math needed). Do NOT read depth via read_sensor: the "
        "raw transducer path (environment.depth.belowTransducer) is NOT "
        "under-keel depth and will mislead. Do not guess depth paths or "
        "compute clearance yourself; call this."
    ),
    inputSchema={"type": "object", "properties": {}},
),

Seven of those: get_active_alarms, read_sensor, get_route, battery_state, depth_state, get_local_time, list_paths.

Option B — a prose recipe in the agent file. No server, no schemas. The agent gets shell access and a section in its always-on AGENTS.md:

## Reading the boat (SignalK)

Boat data lives in SignalK on `http://localhost:3000` (anonymous reads, no auth).
Use the exec tool with `curl`. `jq` is available for filtering.

- One value: `curl -s http://localhost:3000/signalk/v1/api/vessels/self/<path> | jq '.value'`
  where the SignalK dotted path becomes slashes.
- A whole group at once (fewer calls):
  `curl -s http://localhost:3000/signalk/v1/api/vessels/self/electrical | jq`
- Top-level groups: `navigation`, `environment`, `electrical`, `propulsion`,
  `tanks`, `watermaker`, `communication`, `design`, `notifications`.
- **Units are SI:** speed m/s, angles **radians**, depth meters, temperature
  **Kelvin**. Convert for the Captain — knots, degrees, °C.
  (m/s→kn ×1.94384; rad→deg ×57.2958; K→°C −273.15.)
- **Battery current sign: positive = charging** (Victron convention).
- History (`/signalk/v2/history/…`) is not available — answer "now."
- **Never fabricate.** If curl fails or a path is missing, say so.

Both are always-on. Both answer the same questions. Now the receipts.

Round 1 — standing cost, the part everyone measures

This is what you pay every turn, including turns where nobody asks about the boat.

	tokens/turn
MCP: seven tool schemas	874
Agent file: the SignalK section	466
Δ — agent file wins	−408

How I counted — tiktoken, cl100k_base, pulling the tool definitions straight out of the source with ast so there's no hand-transcription:

import ast, tiktoken
enc = tiktoken.get_encoding("cl100k_base")
src = open("src/signalk_mcp/server.py").read()
tools = [{kw.arg: ast.literal_eval(kw.value) for kw in node.keywords}
         for node in ast.walk(ast.parse(src))
         if isinstance(node, ast.Call)
         and getattr(node.func, "attr", None) == "Tool"]
print(len(enc.encode(open("AGENTS.md").read())))

One honest note on the 874: that's the _list_tools() definition block as written. Serialised to JSON it's 845; namespaced the way a client renders it (mcp__signalk__depth_state) it's 887. So call it 845–890 depending on your client — the spread doesn't move anything below.

So far the MCP-is-a-tax crowd is right. 408 tokens a turn, forever, is a real cost.

Round 2 — the part the benchmarks skip

The CLI benchmarks usually stop at the schema. But a tool call has a result, and the result also lands in the context window.

Here is what curl gets back for depth — the whole reason the recipe exists:

{
    "transducerToKeel": {
        "meta": {
            "description": "Depth from the transducer to the bottom of the keel",
            "units": "m",
            "displayUnits": {
                "category": "depth",
                "targetUnit": "m",
                "formula": "value",
                "inverseFormula": "value",
                "symbol": "m",
                "displayFormat": "0.0"
            }
        },
        "value": -1.12,
        "$source": "defaults",
        "timestamp": "2026-08-01T13:35:02.076Z"
    },
    "surfaceToTransducer": { ...same meta block again... },
    "belowTransducer":     { ...same meta block again... },
    "belowKeel":           { ...plus alarmMethod, warnMethod, three zones... },
    "belowSurface":        { ...same meta block again... }
}

515 tokens, of which the five value fields are about a dozen. Everything else is meta — description, units, and a displayUnits object carrying formula, inverseFormula, symbol and displayFormat — repeated per leaf. The agent pays for all of it and then has to find the numbers inside.

The MCP tool returns this instead:

{
  "below_keel_m": 36.42532195742289,
  "below_surface_m": 37.795321957422885,
  "below_transducer_m": 37.545321957422885,
  "display": "36.4 metres under the keel, 37.8 metres total depth",
  "timestamp": "2026-08-01T18:37:26.629Z"
}

92 tokens. Same numbers, plus a TTS-safe sentence the voice pipeline can read out verbatim.

read	raw `curl` response	MCP tool result	ratio
`environment/depth`	515	92	5.6×
`electrical`	431	93	4.6×
`navigation`	627	~92	6.8×

You can't jq your way out of most of this, either. Piping to jq '.value' works for a single leaf, but the recipe's own advice — grab the whole subtree in one call to save round trips — is exactly the case where the meta bloat arrives in full.

The breakeven formula

Two levers pulling opposite directions. Set them against each other.

Let ΔS = the standing-cost difference (schemas − prose) and ΔR = the per-read saving (raw response − tool result). Cost per turn at k reads:

agent file:   P + k · raw
MCP server:   S + k · tool

MCP is cheaper when   S + k·tool  <  P + k·raw
                             k    >  (S − P) / (raw − tool)
                             k*   =  ΔS / ΔR

For this pair: k* = 408 / ~400 ≈ 1.02 reads per turn.

That's the finding. Not "MCP good" or "MCP is a tax" — it pays for itself at roughly one tool call per turn.

Which cuts cleanly in both directions:

A general-purpose agent that touches the boat on one turn in twenty: the agent file is cheaper, and it isn't close.
An agent whose entire job is the boat, where essentially every turn is a read: the MCP wins outright.

My constants aren't yours. Run the same three measurements on your own server — schema tokens, prose tokens, and a representative raw-vs-tool response pair — and divide. If your API returns lean JSON, ΔR collapses and the prose recipe wins at almost any k. If your API is as metadata-heavy as SignalK's, ΔR is large and k* drops below 1.

Prompt caching moves k*, and I measured by how much

The standing cost is the MCP's only loss — and it's the exact part that caches. Tool schemas are a stable prefix. The per-read saving is on churny tokens that never cache. So caching should shrink ΔS and leave ΔR alone, which moves k* down.

The tempting shortcut is to call cached tokens "10% of input" and be done. That's wrong, because it only counts the read side. A cache entry has to be written first, and writes cost more than uncached input.

So rather than assume a hit rate, I aggregated the usage field across the 40 most recent agent session transcripts for this project — 3,782 billed requests on a real runtime with signalk-mcp attached:

cache READ    698,670,375 tokens   94.33% of input-side
cache WRITE    41,945,413 tokens    5.66%
uncached input     29,139 tokens    ~0.00%

cold requests (zero cache read):  150 / 3,782  =  4.0%

Every write in that sample was 1-hour TTL (ephemeral_1h_input_tokens; ephemeral_5m was zero), which matters — the price multiplier depends on TTL. Per the prompt-caching docs: cache read 0.1× base input, 5-minute write 1.25×, 1-hour write 2×.

A standing block gets written on cold turns and read on warm ones, so its effective multiplier is cold × write + warm × read:

	measured
cold turns	4.0%
warm turns	96.0%
standing-block effective multiplier (1h TTL — what we ran)	0.175×
the same block at 5-minute TTL	0.146×
blended multiplier across all input-side tokens	0.208×

Apply that to the 408-token standing delta and re-run the formula:

408 × 0.175  =  ~72 effective tokens

k* = 72 / 400  ≈  0.18 reads per turn

About one boat read every five or six turns. Not the one-in-ten you get from the flat-10% shortcut — the write side is the expensive half and at 1-hour TTL it costs 2×.

Caching still makes the MCP case stronger, just less dramatically than the naive math suggests. And it's conservative in the MCP's favour for a second reason the formula doesn't capture: a tool result is uncached only on the turn it arrives. After that it joins the cached prefix at 0.175× for the rest of the session. The ~400-tokens-per-read saving counts only the first turn; the MCP's leaner results keep paying rent afterwards.

Three things to be honest about before you reuse the 0.175×:

That's a hot session. 96% warm is what sustained back-to-back work produces. A boat agent DM'd over Telegram with minutes between messages cold-starts far more often — the 5-minute TTL expiring between turns is a problem I've hit before. So 0.175× is the favourable end. A bursty agent lands nearer the uncached case — which widens the MCP's advantage rather than narrowing it: the standing penalty grows back toward 408, but so does the value of never re-sending 500-token blobs.
Runtime attribution: these are Claude Code sessions carrying the MCP, not the boat agent itself. Real cache behaviour of a real agent holding these schemas — but I didn't instrument the boat agent, and I'm not claiming I did.
The 1-hour TTL is a property of this session, not a universal default. On the 5-minute default the multiplier is 0.146× and the standing penalty is ~59 tokens, a slightly cheaper MCP.

One takeaway for reading other people's numbers: the MCP-vs-CLI benchmarks I can find quote schema cost uncached. On this measured multiplier that overstates the standing penalty by about 5.7×.

The half that tokens don't measure

Here's the thing that actually decided it, live off the boat's environment.depth tree:

environment.depth.belowTransducer   =  38.5187
environment.depth.transducerToKeel  =  -1.12      <-- stored NEGATIVE

The keel offset is stored as a negative number. Under-keel clearance is therefore an addition:

belowTransducer + transducerToKeel  =  38.5187 + (-1.12)  =  37.40 m   ✅

An agent reading the raw tree and doing the obvious thing — depth below the transducer, minus the keel offset — gets:

38.5187 - (-1.12)  =  39.64 m   ❌

It reports 2.24 metres more clearance than the boat actually has, and the error points toward grounding. In 38 m of water that's a rounding error. In 3 m it's the whole margin, delivered in a confident voice.

Nothing in the token comparison sees this. The wrong answer costs the same as the right one.

The MCP does the arithmetic in Python, where it can't be dropped:

below_keel = below_keel_obj.get("value")   # SignalK's own belowKeel leaf
...
"display": _depth_display(below_keel, below_surface, below_transducer),

— and the tool description spends tokens specifically to stop the model freelancing: "Do NOT read depth via read_sensor: the raw transducer path is NOT under-keel depth and will mislead. Do not guess depth paths or compute clearance yourself; call this." That instruction is part of the 874. It's not schema bloat; it's the thing being bought.

What the prose recipe is really asking for

Look back at the agent file with this in mind. Every bullet is a rule the model has to remember and apply by hand, on every read, forever:

m/s → knots          × 1.94384
radians → degrees    × 57.2958
Kelvin → °C          − 273.15
battery current      positive = charging (Victron convention)

Four conversions, plus a sign convention, plus the keel-offset sign that isn't even in the list because nobody thought to write it down. Each is a coin flip on a bad turn — a long context, a distracting question, a smaller model. And the failure is silent: the model returns a number, not an error. "38 degrees" when the value was radians reads perfectly plausibly.

In Python those are five lines that execute the same way every time:

if tail in _SPEED_KEYS:
    return f"{value * 1.94384:.1f} knots", "knots"
if tail in _BEARING_KEYS:
    deg = math.degrees(value) % 360
    return f"{deg:.1f}° ({_degrees_to_compass(deg)})", "°"
if tail == "temperature":
    return f"{value - 273.15:.1f}°C", "°C"

So the summary is: the agent file is cheaper to carry and more expensive to be wrong with. The token comparison is the easy half and it nearly cancels. The deciding factor is where the domain knowledge lives — in prose the model may skip, or in code it can't.

Caveats, before you quote my numbers

The vessel is ashore. This is Phase 0; the SignalK server runs a mock vessel plugin. The token counts, response shapes and the transducerToKeel sign convention are all real. The readings are synthetic — nobody is in 38 m of water off Boundary Pass right now.
cl100k_base is a proxy. Your model's tokenizer will give slightly different numbers. The ratios hold; the absolutes won't.
874 vs 466 is my seven-tool server against my recipe. The formula generalises. The constants absolutely do not.
This is not a controlled A/B. The two setups differ in more than MCP-vs-file — different runtimes, Python vs curl. It's a like-for-like cost comparison of two ways to give an agent the same capability, not a single-variable experiment.

Where it lands

I kept the MCP server, and the reason isn't the tokens — on tokens it's a coin flip that caching tips slightly my way. I kept it because depth_state cannot get the sign wrong, and a prose bullet can.

The rule of thumb I'd offer: compute k* = ΔS / ΔR before you argue about it, and then ask the question the tokens can't answer — is there any arithmetic in this domain that the model must not get wrong? If yes, that decides it regardless of which side of the breakeven you land on.

The server is signalk-mcp (MIT), part of the agent stack I'm building for an all-electric charter catamaran that doesn't exist yet.

Related: Why we kept named MCP tools despite a 96% token saving — the same tradeoff one level down, inside the MCP server; Running OpenClaw on a Raspberry Pi alongside SignalK — where the curl recipe comes from, plus AGENTS.md vs SKILL.md measured the same way; and Why your agent ignores its skill body but obeys the system prompt — always-on vs conditional, the first axis of this question.

A persistent-queue HTTP reporter for distress traffic over flaky internet

Bryan Clark — Sat, 01 Aug 2026 16:05:03 +0000

TL;DR — Don't fetch()-and-forget safety-relevant reports over marine internet. signalk-distress-core ships a generic persistent-queue HTTP reporter: every payload is appended to a JSONL file before the POST, delivered sequentially in order, retried forever on network errors, retried with a cap on 5xx, and dropped immediately on 400/404. The queue survives crashes and restarts. Jump to the response policy.

Why this matters for safety at sea

When a vessel in trouble hits the red distress button on a DSC VHF radio — or an EPIRB, SART, or MOB beacon starts transmitting on AIS — every receiver in range gets a copy. Shore stations hear most of it. But VHF is line-of-sight: behind an island, deep in a fjord, or simply far enough offshore, a distress burst can be heard by a nearby boat and missed by every shore station. The copy your radio captured may be the only one with a position in it that made it anywhere.

That's the case for relaying received distress traffic to a shore-side aggregation service: a crowd of receivers extends coverage beyond what any single station — afloat or ashore — can hear. DSCWatch is one such network: it aggregates received DSC traffic from stations around the world into coverage maps and distress logs, and signalk-dsc can submit every call it hears.

But now look at the chain: radio → boat server → boat internet → aggregation service. On a boat, the uplink is the least reliable link in that chain. Cellular dies in exactly the remote places where your copy of a distress call matters most. Satellite drops in rain, in swell, behind terrain. The server power-cycles with the house bank. If the reporting code is a bare fetch(), every one of those blinks silently discards a heard distress call — and "we dropped a MAYDAY on the floor because the internet blinked" is not an acceptable failure mode.

So the delivery requirements write themselves:

Write-through persisted — the report is on disk before the first delivery attempt, so a crash mid-flight loses nothing.
Restart-proof — whatever was undelivered at shutdown is delivered after startup.
In-order — DSC position refinements ($--DSE) must arrive after the alerts they refine.
Offline catch-up — hours of outage queue up and drain when connectivity returns.

That's a generic problem, not a DSC problem. So it lives in signalk-distress-core (v0.5.0) as a payload-agnostic module — signalk-dsc maps its events onto DSCWatch report bodies and calls report(); signalk-ais-distress can reuse it as-is. The rest of this post is the engineering.

The naive versions, and why each one fails

Fire-and-forget is where everyone starts:

// Looks fine on shore wifi. On a boat it's a data shredder.
fetch(url, { method: 'POST', body: JSON.stringify(report) }).catch(() => {});

Offline for six hours crossing a strait? Six hours of received calls are gone. Process restarts? Anything in flight is gone. And on a boat both of those are routine, not exceptional.

Retry in memory is the next instinct — keep an array, retry on failure:

const queue = [];
function report(payload) { queue.push(payload); flushSoon(); }

Better, until the process exits — SignalK restarts whenever you save any plugin's configuration, and the whole server power-cycles with the boat's electrical system. Everything queued is gone.

Batch to disk on a timer is the classic telemetry answer: buffer, flush every N seconds. But the window between "received" and "persisted" is exactly the crash window, and for distress traffic the acceptable size of that window is zero.

Write-through, not batching

The reporter appends the payload to a JSONL queue file first, then immediately kicks the flusher. A healthy network still sees the POST within milliseconds; the disk write just happens to come before it.

return {
  /** Enqueue and kick the flusher. Fire-behind: never throws. */
  report(payload) {
    try {
      queue.push({ payload, attempts: 0 });
      if (queue.length > maxQueue) {
        queue = queue.slice(-maxQueue);
        persist();
      } else {
        fs.mkdirSync(path.dirname(queueFile), { recursive: true });
        fs.appendFileSync(queueFile, JSON.stringify(payload) + '\n');
      }
      flush();
    } catch (err) {
      log(`reporter: enqueue failed: ${err.message}`);
    }
  },
  start() { started = true; flush(); },
  stop()  { started = false; clearTimeout(timer); timer = null; },
};

Three deliberate choices in those few lines:

appendFileSync, one JSON object per line. Append is the cheapest durable write there is, and JSONL means a partial write corrupts one line, not the file (more on that below).
Fire-behind, never throws. The caller is a hot path handling a distress alert — raising alarms, writing the logbook. Reporting must never take that path down.
attempts is in-memory only. The disk format is just payloads. Retry accounting resets on restart, which is fine — a restart is a fresh chance, not a continuation of a grudge.

Delivery is sequential and in order — one POST at a time, head of the queue first — so a $--DSE position refinement can never overtake the distress alert it refines.

The response policy: what each HTTP answer means

The core design decision is that "the POST failed" is three different situations, and each one gets a different answer:

Outcome	Meaning	Action
`2xx`	Delivered (200 merged / 201 created)	Dequeue, persist, reset backoff
`400` / `404`	Bad body or rejected receiver key — a retry cannot fix it	Drop it, move on (404 also signals the plugin once)
`5xx`	Server reachable but erroring	Retry with backoff, capped per entry
Network error / timeout	Offline — the marine normal	Keep everything, back off, catch up later

Here's the flush loop that implements it:

async function flush() {
  if (!started || flushing) return;
  flushing = true;
  try {
    while (started && queue.length) {
      const entry = queue[0];
      let res;
      try {
        res = await fetchImpl(url, {
          method: 'POST',
          headers: { 'Content-Type': 'application/json', 'User-Agent': userAgent },
          body: JSON.stringify(entry.payload),
          signal: AbortSignal.timeout(fetchTimeoutMs),
        });
      } catch (err) {
        // Network down (the offline-passage case): keep everything —
        // whatever is behind the head is failing for the same reason,
        // so in-order blocking costs nothing. Retry on a growing timer.
        if (!started) return;
        log(`reporter: network error (${err.message}) — ${queue.length} queued`);
        backoff();
        return;
      }
      if (!started) return;
      if (res.ok) {
        queue.shift();
        persist();
        backoffMs = backoffBaseMs;
        permanentSignaled = false;
        continue;
      }
      if (res.status === 400 || res.status === 404) {
        // A retry cannot fix a bad body or a rejected receiver key.
        queue.shift();
        persist();
        log(`reporter: dropped report (HTTP ${res.status})`);
        if (res.status === 404 && !permanentSignaled) {
          permanentSignaled = true;
          onPermanentError(res.status);
        }
        continue;
      }
      // Server reachable but erroring (5xx): retry with backoff, but cap
      // per entry — one poison payload must not block the queue behind it.
      entry.attempts += 1;
      if (entry.attempts >= maxAttempts) {
        queue.shift();
        persist();
        log(`reporter: dropped report after ${maxAttempts} attempts (HTTP ${res.status})`);
        continue;
      }
      backoff();
      return;
    }
  } finally {
    flushing = false;
  }
}

The asymmetry is the point:

Network errors never consume retry attempts. Being offline for a nine-hour passage is not the payload's fault, so nothing is dropped for it, ever (up to maxQueue). Head-of-line blocking is free here — everything behind the head would fail for the same reason.
5xx retries are capped per entry (maxAttempts, default 10). Without the cap, one poison payload that reliably 500s would block every report behind it forever. With it, in-order delivery yields to liveness after a bounded effort.
400/404 are dropped on the first response. A malformed body or an unknown receiver key will be exactly as malformed on attempt fifty. Retrying a permanent rejection just hammers someone else's server.
404 signals the plugin exactly once (onPermanentError → app.setPluginStatus in signalk-dsc), and a later success resets the once-guard. Reports keep being attempted, so fixing the receiver key or the endpoint URL in config heals delivery without a restart — no "notification spam" and no "silently wedged until reboot".

That last point is the same lesson as our ntfy 401 incident: a delivery path that fails must say so somewhere a human looks, exactly once, and recover by itself when the config is fixed.

Surviving restarts: reload, torn lines, and the trim

On construction the reporter reloads whatever the last process left behind:

try {
  for (const line of fs.readFileSync(queueFile, 'utf8').split('\n')) {
    if (!line.trim()) continue;
    try {
      queue.push({ payload: JSON.parse(line), attempts: 0 });
    } catch {
      // torn/corrupt line — skip it, keep the rest
    }
  }
} catch {
  // no queue yet
}

The torn-line skip is why the disk format is JSONL and not one big JSON array: if the power died mid-append, exactly one line is unparseable. JSON.parse per line means that line is skipped and every intact report before and after it still delivers. A JSON array with a torn tail would lose the whole file.

Rewrites (dequeue, trim) go through a temp-file-and-rename persist() so the queue file is never observed half-written:

function persist() {
  const tmp = `${queueFile}.tmp`;
  fs.mkdirSync(path.dirname(queueFile), { recursive: true });
  fs.writeFileSync(tmp, queue.map((e) => JSON.stringify(e.payload)).join('\n') + '\n');
  fs.renameSync(tmp, queueFile);
}

And maxQueue (default 5000) drops oldest first when a long outage overflows it. Newest-wins is the right policy for distress relay: the most recent calls are the ones a shore-side service can still act on, and 5000 queued reports is weeks of traffic for most stations anyway.

The bug that shipped in v0.5.0: the stale-flusher restart race

v0.5.0 shipped with the design above and a green test suite — and a race that could destroy the queue file. It was caught the same morning, reviewing the shutdown path, and fixed in v0.5.1.

The scenario: SignalK restarts a plugin whenever its configuration is saved. That calls stop() on the old reporter instance and constructs a new one — which loads the queue file and starts appending to it. But stop() can land while the old instance's POST is still in flight. The old flusher is parked on await fetchImpl(...). When that stale fetch finally resolves:

// v0.5.0 — the resolving await charges ahead:
if (res.ok) {
  queue.shift();
  persist();   // rewrites the queue file from the OLD instance's memory
  ...

persist() rewrites the whole file from the old instance's in-memory queue — silently deleting every report the new instance had appended since. A config tweak at the wrong millisecond erases a heard distress call from the queue. Exactly the failure mode this module exists to prevent, reintroduced by its own cleanup path.

The fix is two guards — re-check started after every await boundary before touching shared state:

      } catch (err) {
        // Network down ...
+       if (!started) return;
        log(`reporter: network error (${err.message}) — ${queue.length} queued`);
        backoff();
        return;
      }
+     if (!started) return;
      if (res.ok) {
        queue.shift();
        persist();

The catch-branch guard matters too: without it, a network error resolving on a stopped reporter schedules a fresh backoff timer — a zombie instance that wakes up later and races the live one.

Two consequences worth naming:

The in-flight entry stays queued for the new instance, so it may be POSTed twice. That's deliberate: the DSCWatch backend deduplicates repeated submissions of the same call (DSC alerts auto-repeat on air anyway, and every repeat is reported), so at-least-once is the correct choice over at-most-once. For distress traffic, a duplicate is noise; a loss is the failure.
This is the generic async shutdown lesson, nothing marine about it: any await in a loop is a suspension point where the world can change — including "you were stopped and replaced". Every resumption that mutates shared state (a file, a socket, a DB row) has to re-validate that it still owns that state.

And the race got a test — a gated fetch that holds the POST in flight across a stop():

test('stop() during an in-flight POST: the stale flusher never touches the queue file', async () => {
  const queueFile = tmpQueue();
  let resolveFetch;
  const gate = new Promise((r) => (resolveFetch = r));
  const impl = async (url, opts) => {
    calls.push(JSON.parse(opts.body));
    await gate; // hold the POST in flight
    return { ok: true, status: 201 };
  };
  const reporter = createReporter({ url: 'u', userAgent: 'ua', queueFile, fetchImpl: impl });
  reporter.start();
  reporter.report({ seq: 0 });
  await eventually(() => assert.equal(calls.length, 1)); // fetch is in flight
  reporter.stop(); // plugin restart: a new instance may now own the file
  fs.appendFileSync(queueFile, JSON.stringify({ seq: 99 }) + '\n'); // new instance's append
  resolveFetch(); // stale POST finally resolves
  await new Promise((r) => setTimeout(r, 50));
  const onDisk = fs.readFileSync(queueFile, 'utf8').trim().split('\n').map((l) => JSON.parse(l).seq);
  assert.deepEqual(onDisk, [0, 99]); // stale flusher must NOT have shifted/persisted
});

Fetch timeouts: a black-holed link must not wedge the flusher

v0.5.1 also added the one thing a default Node fetch won't give you — a deadline:

res = await fetchImpl(url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json', 'User-Agent': userAgent },
  body: JSON.stringify(entry.payload),
  signal: AbortSignal.timeout(fetchTimeoutMs),   // default 30 s
});

Marine links don't just go down — they black-hole: a satellite terminal that accepts the TCP connection and then says nothing more, sometimes for minutes. Without a timeout, the single sequential flusher sits parked on that await indefinitely, and the whole queue stalls behind a connection that will never answer. AbortSignal.timeout() (stdlib since Node 17.3, no AbortController boilerplate needed) turns that into an abort error, which takes the existing network-error path: keep the entry, back off, retry.

Tests pin the policy, not the implementation

The response policy is the contract, so the tests assert it directly against a scriptable fetch stand-in — no HTTP server, no mocking framework, just node:test:

test('400 is dropped without retry; the next report still delivers', async () => {
  const { impl, calls } = mockFetch((call) =>
    call.body.bad ? { ok: false, status: 400 } : { ok: true, status: 201 }
  );
  const reporter = createReporter({ url: 'u', userAgent: 'ua', queueFile: tmpQueue(), fetchImpl: impl });
  reporter.start();
  reporter.report({ bad: true });
  reporter.report({ good: true });
  await eventually(() => {
    assert.equal(calls.length, 2); // bad tried exactly once
    assert.equal(calls[1].body.good, true);
  });
  reporter.stop();
});

test('5xx retries are capped per entry, then the entry drops and the queue moves on', async () => {
  const { impl, calls } = mockFetch((call) =>
    call.body.poison ? { ok: false, status: 500 } : { ok: true, status: 201 }
  );
  const reporter = createReporter({
    url: 'u', userAgent: 'ua', queueFile: tmpQueue(), fetchImpl: impl,
    maxAttempts: 3, backoffBaseMs: 5, backoffMaxMs: 10,
  });
  reporter.start();
  reporter.report({ poison: true });
  reporter.report({ after: true });
  await eventually(() => {
    const poisonTries = calls.filter((c) => c.body.poison).length;
    assert.equal(poisonTries, 3); // exactly maxAttempts, then dropped
    assert.equal(calls[calls.length - 1].body.after, true);
  });
  reporter.stop();
});

The full suite pins every row of the policy table: 200-and-201 both accepted, in-order delivery, offline catch-up resuming in order with nothing dropped, restart recovery from the JSONL file, torn-line skip, maxQueue oldest-first trim, the 404 signal-once-reset-on-success behaviour, and the stale-flusher race above. fetchImpl is injectable for exactly this reason — the only seam the module needs.

Two small design notes riding along in the same release:

The receiver key is minted once and persisted (loadOrCreateReceiverKey): DSCWatch has no registration call — the first report for a new key creates the receiver record — so the only rule is reuse the same value forever. A UUID written to a file in the plugin data directory does that; a station that wants attribution can configure its own key instead.
What leaves the boat is a pick-list, not a filter. The report builder in signalk-dsc copies an explicit allow-list of parsed call fields; local-only data (own-ship weather snapshots, spoken alert text, internal IDs) is never sent because it is never picked. Privacy boundaries built as "copy what's allowed" don't rot the way "strip what's forbidden" does. Reporting is on by default with a single toggle to keep all data on the boat — see the plugin README for the exact field list.

Gotchas if you build one of these

Append-before-POST, always. If the durable write isn't strictly first, there is a crash window, and on a boat the crash window gets hit.
Classify responses; don't treat "not ok" as one case. Permanent rejections (400/404) retried forever are abuse; transient errors (5xx, timeouts) dropped immediately are data loss. The policy needs both, explicitly, with tests.
Cap retries per entry, not globally. The cap exists to defeat poison-payload head-of-line blocking; a global cap would let one bad payload spend the whole budget.
Re-check ownership after every await. stop() + in-flight I/O + shared file = the stale-flusher race. Guard every resumption that touches shared state.
timer.unref() the backoff timer so a pending retry never keeps the host process alive past shutdown.
JSONL over a JSON array for any on-disk queue: torn writes cost one record, not the file.

Close

This runs on the same all-electric-catamaran SignalK stack as the rest of this blog, relaying what the radio hears toward people who can use it. The reporter is payload-agnostic and MIT-licensed: @sailingnaturali/signalk-distress-core (lib/reporter.js, ~180 lines, tests included), consumed by signalk-dsc for DSCWatch reporting.

Related: how the DSC calls get captured in the first place — Logging VHF DSC distress calls in SignalK (PGN 129808) — and the delivery-path-monitoring lesson this reporter inherits — Monitor the delivery path, not just the alarm.

Offline tidal currents from harmonic constituents — and when not to trust them

Bryan Clark — Fri, 31 Jul 2026 16:05:43 +0000

TL;DR — signalk-currents v0.7.0 keeps publishing tidal-current predictions when the boat loses internet: it bundles public-domain NOAA harmonic constituents and synthesizes slack/flood/ebb events offline with Neaps. But every fallback reading is labeled source: "harmonic", live: false, and — at constricted passes — unreliableForTransit: true, because harmonic slack timing at a tidal rapids can be off by tens of minutes. While the network is up, the plugin logs harmonic-vs-live discrepancies locally so the error is measured, not guessed. Jump to the build.

Marine software has one non-negotiable requirement that most connected software gets to ignore: it has to keep working when the internet doesn't. A tidal-currents plugin that answers "when is slack at the pass?" only while the LTE link is up is worse than a paper tide book — because you'll have built your habits around asking it.

This post is the deeper look promised in the signalk-currents README: how the offline harmonic fallback works, why it deliberately announces its own unreliability at constricted passes instead of silently degrading, and how it measures itself against live data while it still can.

Problem

signalk-currents publishes environment.current and a /currents resource by fetching live predictions from the CHS (Canada) and NOAA (US) tides-and-currents APIs, one fetch per station per UTC day. Every poll needs connectivity. Kill the uplink and the failure looks like this in the server log:

signalk-currents: station Seymour Narrows live fetch failed: fetch failed
signalk-currents: station Boundary Pass live fetch failed: fetch failed

The per-day cache papers over short outages — per-day predictions are immutable, so anything already fetched keeps serving — but it's an in-memory Map scoped to the process. Restart the server while offline, or sail past the configured horizonDays, and currents go dark. On a boat, "restart while offline" is not an edge case; it's Tuesday.

What we tried (and why it failed)

Attempt 1: just serve the cache harder. Persist the day cache to disk, fetch a longer horizon. This helps (and is a good idea anyway), but it's not synthesis — it can never answer beyond the last fetched day, and it does nothing for a station you never fetched. A cache is a memory, not a model.

Attempt 2: bundle harmonic constituents for every gate. This is the obvious move: tide clocks have synthesized predictions from harmonic constituents for a century, entirely offline. It works — for exactly half the cruising ground:

NOAA (US) current constituents:  public domain, freely redistributable ✓
CHS (Canada) current constituents: not redistributable ✗

CHS harmonic constants are licensed non-commercial, non-redistributable, and not-for-navigation — you cannot ship them in an MIT-licensed npm package. And the Salish Sea's strong narrows — Seymour, Dodd, Gillard, Dent, Arran, Active, Porlier — are all CHS waters. The licensing wall lands precisely on the stations that matter most.

Attempt 3: WebTide. DFO's WebTide model has Salish-wide current constituents, but it's Crown copyright (redistribution needs written permission) and carries only 8 constituents with no shallow-water overtides — and overtides are exactly what constricted channels need (more on that below).

So v1 bundles what's legal: nine public-domain NOAA current stations covering the US Salish passes — Deception Pass, Rosario Strait, Admiralty Inlet, San Juan Channel, Haro Strait (two bins), Guemes Channel (two bins), and Boundary Pass. The Canadian rapids stay API-only, and the plugin says so out loud rather than pretending otherwise.

The build

A tide-height engine, repurposed for currents

There was no currents-capable harmonic synthesis library on npm. But Neaps (@neaps/tide-predictor, MIT) does the hard part — the astronomical argument and node-factor machinery behind summing constituents — for tide heights. The trick: Neaps doesn't care what the scalar is. Feed it amplitudes in knots instead of meters and its "water level" is the signed major-axis current velocity. Positive level = flood, negative = ebb, zero crossing = slack:

// src/sources/harmonic.ts
export function synthesizeEvents(hs: HarmonicStation, start: Date, end: Date): CurrentEvent[] {
  const predictor = createTidePredictor(
    hs.constituents.map((c) => ({ name: c.name, amplitude: c.amplitudeKn, phase: c.phaseDeg })),
  );

  // Flood/ebb peaks come straight from the extremes predictor.
  const extremes = predictor.getExtremesPrediction({ start, end });
  // ponytail: assumes mean-zero constituents (no Z0/DC-offset term) — a level-curve max
  // is a positive (flood) peak; adding a Z0 constituent would shift the baseline and could flip labels.
  const events: CurrentEvent[] = extremes.map((x) =>
    eventFromParts(x.time.toISOString(), x.high ? 'flood' : 'ebb', Math.abs(x.level)),
  );

  // Slack = sign change on a 1-minute timeline; linear-interpolate the crossing.
  const line = predictor.getTimelinePrediction({ start, end, timeFidelity: 60 });
  for (let i = 1; i < line.length; i++) {
    const a = line[i - 1], b = line[i];
    if ((a.level <= 0 && b.level > 0) || (a.level >= 0 && b.level < 0)) {
      const frac = a.level === b.level ? 0 : a.level / (a.level - b.level);
      const t = a.time.getTime() + frac * (b.time.getTime() - a.time.getTime());
      events.push(eventFromParts(new Date(t).toISOString(), 'slack', 0));
    }
  }

  events.sort((x, y) => x.utc.localeCompare(y.utc));
  return events;
}

"High tide" becomes a flood peak, "low tide" an ebb peak, and the output is the same CurrentEvent[] (slack/flood/ebb) shape the live CHS/NOAA sources emit — a drop-in third source, no restructuring downstream.

Note the ponytail: comment: classifying an extremum as flood because Neaps called it a high only works if the constituent sum is mean-zero. There's no Z0 (mean flow) term in the bundled data, so the baseline sits at zero and the labels hold. Add a mean-flow offset — say, a channel with persistent river outflow — and a weak "flood" maximum can sit entirely below zero: still ebbing, just less. The assumption is documented where it lives, because it's the first thing a future constituent refresh could silently break.

Bundling the constituents

Constituents are fetched at build time from NOAA CO-OPS mdapi harcon metadata, converted, and committed — never fetched at runtime:

// scripts/refresh-constituents.ts (excerpt)
const CM_S_PER_KNOT = 51.4444;

const constituents = rows
  .filter((c) => NEAPS_KNOWN.has(c.constituentName) && Number(c.majorAmplitude) > 0)
  .map((c) => ({
    name: c.constituentName as string,
    amplitudeKn: Number(c.majorAmplitude) / CM_S_PER_KNOT, // cm/s -> knots
    phaseDeg: Number(c.majorPhaseGMT),                     // Greenwich phase, degrees
  }));

Three gotchas live in those six lines:

Units. NOAA harcon major-axis amplitudes are cm/s; Neaps just sums whatever you hand it. Divide by 51.4444 once at generation time and every downstream level is already knots.
Phase reference. Store majorPhaseGMT (Greenwich phase, degrees). Neaps evaluates in UTC, so local-phase constants would shift every event by the timezone offset.
Silent drops. A constituent name Neaps doesn't know is silently ignored — no error, just a subtly wrong prediction. The refresh script filters against an explicit NEAPS_KNOWN set so anything unexpected is excluded deliberately at generation time, not accidentally at runtime.

NOAA's own disclaimer applies and is carried in the data file's provenance header: the data is public domain, and predictions derived from it are unofficial.

Aligning the horizon with the live path

The live path fetches per UTC day. The harmonic path must synthesize the same window, or the two series cover different spans and both fallback handoff and discrepancy comparison get skewed:

// Synthesize the whole horizon in one pass, aligned to UTC-day boundaries so the
// event window matches the live path (fetch.ts iterates UTC days from the same start).
export function synthesizeHorizon(hs: HarmonicStation, start: Date, horizonDays: number): HarmonicDayData {
  const base = new Date(Date.UTC(start.getUTCFullYear(), start.getUTCMonth(), start.getUTCDate()));
  const end = new Date(base.getTime() + horizonDays * 86400000);
  return { events: synthesizeEvents(hs, base, end), floodDir: hs.floodDir, ebbDir: hs.ebbDir };
}

Selection: live wins, fallback declares itself

The refresh loop synthesizes harmonic data for every station with bundled constituents on every cycle — not just offline ones — then selects:

// src/select.ts
export function selectData(
  liveData: DirData | undefined,
  harmonicData: DirData | undefined,
  provider: 'chs' | 'noaa',
): Selected | undefined {
  if (liveData) return { data: liveData, source: provider, live: true };
  if (harmonicData) return { data: harmonicData, source: 'harmonic', live: false };
  return undefined;
}

Every reading that leaves the plugin carries provenance. In the /currents resource:

{
  "stationId": "PUG1701",
  "label": "Deception Pass",
  "source": "harmonic",
  "live": false,
  "unreliableForTransit": true,
  "events": [
    { "utc": "2026-07-16T14:02:00.000Z", "kind": "slack", "speedKn": 0 },
    { "utc": "2026-07-16T17:10:00.000Z", "kind": "ebb", "speedKn": 5.8 }
  ]
}

And on the environment.current delta, as SignalK meta:

meta: [{
  path: 'environment.current' as Path,
  value: {
    source: entry.source,                  // 'chs' | 'noaa' | 'harmonic'
    live: entry.live,                      // false when synthesized offline
    unreliableForTransit: station.requiresLive === true && !entry.live,
  } as unknown as object,
}],

requiresLive is a per-station config flag, pre-set on the constricted passes in the default station list. The design rule: the plugin states facts; it never suppresses a value and never editorializes. A harmonic slack estimate at Deception Pass is still useful for rough planning — deciding whether to look, not when to go. Whatever consumes the data (a chart plotter, an agent, a human reading JSON) decides what to do with unreliableForTransit: true. Silently degrading — serving a synthesized number in the same shape as an authoritative one — is how someone times a rapids transit on a model that's 25 minutes wrong.

Why harmonic predictions fall short at constricted passes

This is the part the README promises and defers, so here it is. Harmonic prediction is a linear model: the current is a sum of fixed sinusoids at astronomical frequencies,

v(t) = Σᵢ Aᵢ · cos(ωᵢ·t − φᵢ)

with amplitudes and phases fitted to a historical current-meter record. That model is excellent where the tide behaves like a superposition of long waves — open coast, wide straits. A constricted pass breaks each of its assumptions:

1. The flow is hydraulic, not wavelike. At a narrows like Seymour (which routinely exceeds 15 knots) the current is driven by the water-level difference between the basins at each end. The velocity responds roughly as the square root of that head difference, through quadratic bottom/form friction. A square root of a sum of sinusoids is not a sum of sinusoids — the response is nonlinear by construction.

2. Nonlinearity pumps energy into overtides the bundle truncates. The nonlinear terms generate shallow-water constituents — M4, M6, MS4 and friends, at multiples and sums of the astronomical frequencies — which is what makes real rapids curves asymmetric: fast-rising floods, long-tailed ebbs, double-humped peaks. The bundled stations carry 23–29 constituents each (only the ones Neaps knows); the residual distortion the fit couldn't capture doesn't vanish, it lands in the error — concentrated where the curve shape matters.

3. The error concentrates at slack — the only moment you care about. At peak flow, a 10% amplitude error changes nothing about your decision; you weren't going through Dent Rapids at max ebb anyway. Near slack, the head difference across the pass is small, so everything the constituents don't model — wind setup, atmospheric pressure gradients, river discharge in freshet, the truncated overtides — shifts the zero crossing directly. The steeper, shorter slack window at a strong narrows means a modest phase error translates to arriving with real current already running. That's the mechanism behind "off by tens of minutes," and it's why the flag is named unreliableForTransit and not something politer.

4. The fit itself is weaker. Height constituents come from decades-long water-level records at permanent gauges. Current constituents come from comparatively short current-meter deployments in turbulent, stratified water, resolved per depth bin. The inputs are noisier before the model's structural limits even apply.

None of this makes the harmonic fallback useless — Boundary Pass under harmonic synthesis is a perfectly serviceable planning baseline. It makes the fallback conditionally trustworthy, and the condition is knowable per station in advance. That's exactly what a config flag is for.

Measure the fallback while you still have ground truth

The claim above — "off by tens of minutes" — deserves numbers, per station. The trick is that the best time to measure an offline fallback is when you're online: every poll cycle where a station has both live and harmonic data, the plugin diffs them and appends a line to a local JSONL log:

// src/compare.ts — deltas are signed (harmonic − live):
// +slackDeltaMin = harmonic slack is later
export function computeDiscrepancy(
  stationId: string, label: string, live: CurrentEvent[], harmonic: CurrentEvent[], now: Date,
): Discrepancy {
  const ls = nextSlackAfter(live, now), hs = nextSlackAfter(harmonic, now);
  const lp = peakRate(live), hp = peakRate(harmonic);
  return {
    utc: now.toISOString(), stationId, label,
    slackDeltaMin: ls !== undefined && hs !== undefined ? (hs - ls) / 60000 : null,
    peakRateDeltaKn: lp !== undefined && hp !== undefined ? hp - lp : null,
  };
}

<SignalK dataDir>/signalk-currents-discrepancies.jsonl

One row per station per poll: how far off the harmonic next-slack estimate is (signed minutes) and how far off the peak rate is (signed knots). Local file only — nothing is phoned home. The write is best-effort and swallowed on failure, because diagnostics must never take down the data path they're diagnosing.

The design intent: when someone eventually asks "how wrong is the fallback at this station?", the answer is a jq one-liner over months of accumulated rows, not a shrug. The follow-up post with a season of measured deltas is the plan; this post is the mechanism.

Gotchas

NOAA harcon amplitudes are cm/s — convert to knots (÷ 51.4444) at generation time, not runtime.
Neaps silently drops constituent names it doesn't know. Filter against an explicit known set when generating the bundle, or you'll ship a prediction missing constituents with no error anywhere.
Flood/ebb labels assume mean-zero constituents. A Z0/mean-flow term would shift the baseline and can flip extremum labels.
Align synthesis windows to UTC-day boundaries to match a per-day live fetch path, or fallback handoffs jump.
You may not be able to redistribute your local constituents. NOAA is public domain; CHS is not. Check before bundling anything Canadian — the licensing boundary decides your offline coverage map, not your code.
Provenance is part of the data model, not a log line. source / live / unreliableForTransit ride on the resource payload and the SignalK meta, so every consumer sees them — not just whoever reads the server log.

Close

This plugin is part of the open-source navigation stack for an all-electric charter catamaran that will spend its life transiting exactly these passes — which is why the fallback that keeps currents flowing offline also has to be honest about where it can't be trusted. Code, bundled constituents, and the refresh script: github.com/sailingnaturali/signalk-currents.

Related: why generic weather MCPs fail for marine navigation — the same verify-against-reality instinct, with NDBC buoys as ground truth — and LLM agents confabulating data provenance, the failure mode provenance fields exist to prevent.

Running OpenClaw on a Raspberry Pi alongside SignalK

Bryan Clark — Wed, 29 Jul 2026 12:50:26 +0000

Running OpenClaw — a self-hosted, multi-channel agent gateway — on a Raspberry Pi 5 next to SignalK, so you can DM the boat over Telegram and get live vessel readings back. The traps that cost me time are up front — the gateway.mode start-block, SI-unit conversion, no history without InfluxDB, and a Chesterton's-fence with the ollama plugin — then the walkthrough, then what I found tuning the standing prompt down. Jump to the gotchas.

There's no existing writeup for this combination anywhere I could find, so here's the whole thing: what to know before you start, the setup that actually works, and the token-cost tuning that made it cheap enough to leave running.

The build

OpenClaw is a Node/TypeScript daemon you run on your own hardware; you talk to an LLM-backed agent over chat channels (Telegram, Slack, etc.). SignalK is the open marine data server that normalises NMEA 2000/0183 into one JSON model. Put them on the same Pi and you get a boat assistant you DM from your phone that can read live vessel state.

They share the box but stay in their own lanes. OpenClaw reads SignalK over HTTP — it does not run inside the marine stack:

  Raspberry Pi 5 (8 GB)
  ┌─────────────────────────────────────────────┐
  │  SignalK (Docker)          OpenClaw (native) │
  │  localhost:3000  ◀── HTTP ──  gateway daemon │
  │  + InfluxDB/Grafana           (systemd user) │
  └─────────────────────────────────────────────┘
            ▲                          ▲
       NMEA 2000/0183            Telegram DM

SignalK is typically already running in Docker on localhost:3000 next to InfluxDB and Grafana. OpenClaw installs natively alongside it. No MCP server, no plugin inside SignalK — the agent just curls the SignalK REST API.

Gotchas first

These are the ones that don't show up until you hit them.

1. The gateway won't start without `gateway.mode`

If the config is missing gateway.mode, the daemon refuses to start:

Gateway start blocked: set gateway.mode=local

Onboarding sets this for you. But if you hand-edit the config and drop the key — or a tool rewrites it — OpenClaw treats the missing key as suspicious/clobbered config and blocks the start rather than guessing. The fix is one command:

openclaw config set gateway.mode local

(Or re-run onboarding with openclaw onboard --mode local.) See the gateway troubleshooting docs.

2. SignalK values are SI — the agent must convert

SignalK stores everything in SI units. A raw read looks fine and is silently wrong for a human:

speed      → m/s     (× 1.94384 for knots)
angles     → radians (× 57.2958 for degrees)
temperature→ Kelvin  (− 273.15 for °C)
depth      → metres

So environment.wind.speedApparent comes back as 8.5 — that's 8.5 m/s, i.e. ~16.5 knots, not 8.5 knots. If you don't tell the agent to convert, it will happily report the SI number as if it were the human unit. Bake the conversions into the agent's instructions (or a skill), and spell out the target units.

3. No history without InfluxDB

SignalK's REST API serves live values fine anonymously. But the history endpoint returns a 404 unless the InfluxDB-backed history plugin is running:

$ curl -s http://localhost:3000/signalk/v2/history/values?paths=electrical.batteries.house.stateOfCharge
# 404 unless signalk-to-influxdb (+ history API) is installed and running

Without it the agent is live-only — it answers "what's the depth now," not "what was the minimum overnight." If you want the agent to reason over trends, stand up the history plugin first; otherwise scope its instructions to present-tense questions.

4. `jq` isn't installed by default

Raspberry Pi OS ships without jq. If your agent instructions pipe curl through jq, they'll fail on a fresh box:

$ curl -s http://localhost:3000/signalk/v1/api/vessels/self/environment/depth/belowTransducer | jq .value
bash: jq: command not found

Two options: sudo apt install jq, or just don't — hand the agent the raw JSON and let it parse. An LLM reads { "value": 4.2, "timestamp": "…" } without help. I went with raw JSON; one fewer moving part on the boat.

5. Chesterton's fence — the `ollama` plugin does more than you think

I disabled the ollama plugin assuming it was only a (dead, for me) web-search provider. Later a local Ollama model failed to load:

No API provider registered for api: ollama

The ollama plugin also registers the Ollama API runtime — the thing that lets you use Ollama as a model backend, not just a search tool. Disabling it pulled the backend out from under the model. The lesson is the old one: don't disable a plugin until you know everything it provides. (Re-enabling it fixed the load.)

The walkthrough

Install (native)

OpenClaw supports Docker, but on a Pi that's already running SignalK's own Docker stack I installed OpenClaw natively and let it manage its own daemon — it keeps the marine containers isolated and the agent's lifecycle separate. The installer targets Node 24 by default (the supported range is Node 22.22.3+, 24.15+, or 25.9+) and handles the runtime for you:

curl -fsSL https://openclaw.ai/install.sh | bash
# or: npm install -g openclaw@latest

Then the guided setup — it walks you through auth (an Anthropic API key, or an OAuth login), model choice, and the daemon:

openclaw onboard
openclaw onboard --install-daemon   # installs a systemd user service

On a headless Pi, the user service dies at logout unless you enable lingering:

sudo loginctl enable-linger "$USER"

That's the piece that makes it survive a reboot. See the install docs.

Make a bot with @BotFather, then point OpenClaw at the token — either in config or via env:

openclaw config set channels.telegram.botToken "<BOT_TOKEN>"
# or export TELEGRAM_BOT_TOKEN=<BOT_TOKEN>

Keep DMs gated with pairing so a stranger who finds the bot can't drive your boat:

// channels.telegram
{ "dmPolicy": "pairing" }

DM the bot, then approve the code it gives you (codes expire after an hour):

openclaw pairing approve telegram <CODE>

Details in the Telegram channel docs.

Reading SignalK over HTTP — no MCP needed

SignalK's REST API is anonymous when allow_readonly is on, so you don't need a custom SignalK MCP server for reads. Give the agent the exec tool and let it curl. A SignalK dotted path maps straight to URL slashes:

# environment.depth.belowTransducer  →  .../environment/depth/belowTransducer
curl -s http://localhost:3000/signalk/v1/api/vessels/self/environment/depth/belowTransducer

{ "value": 4.2, "timestamp": "2026-07-27T00:00:00Z", "meta": { "units": "m" } }

Grab a whole subtree in one call:

curl -s http://localhost:3000/signalk/v1/api/vessels/self/electrical

The one prerequisite: exec only exists in certain tool profiles — which is the first tuning finding below.

Tuning finding 1 — skill vs the agent file

OpenClaw injects workspace files into context every turn: a SOUL.md persona and an AGENTS.md instruction/memory file. Skills live at workspace/skills/<name>/SKILL.md — the skill's name+description is advertised every turn, but its body loads on demand when the skill fires.

So where do the SignalK-reading instructions belong — always-on in AGENTS.md, or in a SKILL.md? Intuition says the skill: pay for the body only when you use it. I measured prompt tokens per turn both ways:

Turn	in AGENTS.md (always-on)	as a skill (on-demand)	Δ
No-tool question	13,808	13,380	−428 (skill wins)
Single boat read	14,070	14,427	+357 (skill loses)
Multi boat read	16,134	16,628	+494 (skill loses)

Counterintuitive but consistent: for an agent whose whole job is this domain, the always-on agent file is slightly cheaper. The skill's description still sits in context every turn (alongside every other skill's), and loading its body on a domain turn costs more than the tiny always-on snippet it replaced. The skill only wins when most turns don't touch the domain — and for a boat agent, most turns do.

(This is the same always-on-vs-conditional split we hit on a different framework — see the related post below.)

Tuning finding 2 — cutting the ~14k standing prompt

Every turn, even a no-tool question, carries a ~14k-token standing prompt: base preamble + tool schemas + workspace files. That's structural to a general-purpose gateway. Three things I tried to shrink it, in order of what actually worked.

What worked — the tool profile

OpenClaw gates tools by tools.profile: minimal (just session_status), coding (filesystem + runtime/exec + web + more), messaging, and full. Only coding grants both exec and filesystem — which is why the SignalK-over-curl approach needs it.

But coding also drags in a pile of dev-tool schemas a boat agent never calls. If all you need is shell + file read/write, drop to minimal and additively re-allow just those two groups:

// tools
{
  "profile": "minimal",
  "alsoAllow": ["group:runtime", "group:fs"]
}

group:runtime is exec/process; group:fs is read/write/edit. That cut ~5,000 tokens/turn (~25%) — pure schema for tools the agent never uses — with zero functional loss. See the tool-profile docs.

What did NOT work — disabling plugins

I assumed the loaded plugins (browser, canvas, phone-control, talk-voice…) were bloating the prompt. Disabling four of them saved ~270 tokens — nothing.

Why: tool schemas are gated by tool policy, not plugin state. Once the minimal profile excludes a tool, its schema is already gone whether or not the plugin loads. So:

Disabling a plugin does not save prompt tokens if the profile already denies its tools.

(Still disable unused plugins — for the Pi's RAM, CPU, and boot time. Just don't expect a token win.)

The real lever — caching, not token count

The standing prompt bills at full price only on a cold turn. OpenClaw auto-injects Anthropic cache_control on the stable prefix, so the ~14k reads from cache at ~10% on warm turns. I watched it in one session: the cold turn wrote ~14k tokens to cache; the next same-session turn read ~14k from cache and wrote only ~150.

For bursty use — messages minutes apart, which is exactly how you DM a boat — the default 5-minute cache TTL keeps cold-starting. Bump it:

// long cache retention → 1h TTL
{ "cacheRetention": "long" }

One version caveat: OpenClaw is careful to order the stable context files ahead of the churny heartbeat file so heartbeat updates don't bust the cached prefix — but older builds had a cache-busting bug where a per-message value landed inside the cached block and re-wrote the whole prefix every turn. If your "cached" reads look like full-price writes, check your version. See the prompt-caching docs.

Bonus — a watch that stays quiet

Once the agent can read SignalK, a natural next step is a scheduled check that only speaks when something's wrong. OpenClaw's cron supports a deterministic --trigger-script gate: the script inspects SignalK (any non-normal notification, or a battery/depth/tank threshold), returns { fire, message?, state? }, and the agent only composes a Telegram heads-up when fire is true — de-duped on state so it alerts on change, not every tick. A watch that's silent when all's well. That's its own post; the cron docs have the shape.

Close

This came out of building an AI ops layer for an all-electric charter catamaran, where "what's our depth?" should be a Telegram DM away and the standing prompt cheap enough to leave running on a Pi. If you're standing this up yourself, the two references worth bookmarking are the OpenClaw docs and signalk.org — the rest is the six lines of gotchas above.

Related: Why your agent ignores its skill body but obeys the system prompt — the always-on-vs-conditional split behind tuning finding 1; and Why we kept named MCP tools despite a 96% token saving — the tokens-vs-reliability tradeoff for boat agents.

httpx async requests to a .local hostname time out on macOS

Bryan Clark — Tue, 28 Jul 2026 16:57:19 +0000

TL;DR — On macOS, httpx.AsyncClient requests to a .local (mDNS/Bonjour)
hostname raise httpx.ConnectTimeout even though the host is up and curl
works instantly. getaddrinfo puts an IPv6 candidate first, and the async
connect burns the whole connect timeout on that unroutable path before IPv4
gets a turn. Resolve the .local host to IPv4 yourself, once, at the URL
boundary — the system resolver handles mDNS fine — and rewrite the URL.
Jump to the fix.

Our boat's AI agent talks to a SignalK server on a
Raspberry Pi through a fleet of MCP servers — vessel data, logbook, tidal
currents, weather. All of them are thin Python services that reach the Pi over
HTTP with httpx.AsyncClient, and all of them address it by its mDNS name,
boat-server.local. One day, running the fleet from a Mac, every single tool
call timed out. Not one server — all of them, silently, the same way.

Problem

The client code is as plain as HTTP gets:

import httpx

client = httpx.AsyncClient(timeout=5.0)
resp = await client.get("http://boat-server.local:3000/signalk/v1/api/vessels/self")

And every call dies like this:

  File ".../httpx/_transports/default.py", line 101, in map_httpcore_exceptions
    raise mapped_exc(message) from exc
httpx.ConnectTimeout

Five seconds per request, every request, httpx.ConnectTimeout at the end of
it. From the agent's point of view the whole tool surface is just... gone. It
answers questions with "I couldn't reach the vessel data server" while the
server sits there, healthy, twenty feet away.

The part that sends you down the wrong path: everything else can reach it.

$ curl -s http://boat-server.local:3000/signalk/v1/api/vessels/self | head -c 60
{"name":"Naturali","mmsi":"368...
$ ping boat-server.local
64 bytes from 192.168.1.20: icmp_seq=0 ttl=64 time=4.2 ms

Instant. So the server is fine, mDNS resolution is fine, the network is fine —
only the async Python path fails.

Diagnosis

Ask the resolver what it actually returns for the name:

$ python3 -c "import socket; \
    [print(ai[0].name, ai[4][0]) for ai in \
     socket.getaddrinfo('boat-server.local', 3000, type=socket.SOCK_STREAM)]"
AF_INET6 fe80::dea6:32ff:fe12:3456
AF_INET  192.168.1.20

There it is. On macOS, getaddrinfo for the .local name returns an IPv6
candidate first — here a link-local fe80:: address — and the IPv4 address
second. The IPv6 candidate is not usefully routable from the client (a
link-local address needs a scope/zone ID to be connectable, and the resolved
candidate doesn't carry a working one), so connecting to it goes nowhere: no
refusal, no reset, just silence until the timeout.

Modern clients are supposed to shrug this off. That's the whole point of
Happy Eyeballs (RFC 8305):
start with the first address family, and if it hasn't connected within a couple
hundred milliseconds, race the other one in parallel. curl does exactly this,
which is why it never blinks. The async Python stack is supposed to do it too
— anyio implements Happy Eyeballs in connect_tcp()
with a 250 ms stagger.

What we observed instead: the async connect sat on the dead IPv6 attempt for
the full connect timeout before IPv4 ever got a useful turn — so with a 5 s
timeout, every request was ConnectTimeout, 100% reproducible. Whatever the
stagger did under the hood, the practical behaviour on macOS with a .local
name was "wait out IPv6, then die."

And it hit every MCP server in the fleet at once, because they all shared
the same idiom: SIGNALK_URL=http://boat-server.local:3000 in the environment,
httpx.AsyncClient in the client. We found it because an agent benchmark run
suddenly scored terribly — the model was doing everything right and the tools
were timing out underneath it.

What we tried (and why it failed)

Blame the server. Restarted SignalK, checked its logs, hit the REST API
from three other machines. All fine — of course it was; curl from the same
Mac already proved that. Time spent anyway: too much.

Raise the timeout.

client = httpx.AsyncClient(timeout=30.0)

This just moves the pain. The connect still burns the IPv6 attempt first, so
every cold request eats seconds before doing anything useful — and this stack
answers voice queries with a hard latency budget of a few seconds total. A
"fix" that spends the entire budget waiting on a dead address family is a
failure with extra steps.

Hardcode the IP.

SIGNALK_URL=http://192.168.1.20:3000

Works instantly — which confirms the diagnosis: connect to the IPv4 address and
there's nothing wrong at all. But the Pi's address comes from DHCP, and the
entire reason the config says boat-server.local is so nobody maintains an IP
address by hand. Hardcoding it trades a bug for a chore.

Force IPv4 in the transport. httpx has a
documented knob for
exactly this:

transport = httpx.AsyncHTTPTransport(local_address="0.0.0.0")
client = httpx.AsyncClient(transport=transport)

Binding the local side to 0.0.0.0 restricts connections to IPv4, and it does
work. But it has to be threaded through every AsyncClient construction
site, in every service — including ones where the client is built deep inside a
helper. And it turns off IPv6 for all destinations that client touches, not
just the one broken .local name. We wanted the fix at the one place all the
services already share: the URL.

The fix

Resolve the .local host to its IPv4 address once, at the URL boundary,
and hand httpx a URL with the IP already in it. The synchronous system resolver
handles mDNS perfectly well — the problem was never resolution, it was which
candidate the async connect tried first.

import socket
from urllib.parse import urlsplit, urlunsplit


def resolve_local_host(base_url: str) -> str:
    """Resolve a .local (mDNS) host in base_url to its IPv4 address.

    Non-.local hosts, empty input, and resolution failures are returned
    unchanged so httpx still gets its normal shot.
    """
    parts = urlsplit(base_url)
    host = parts.hostname
    if not host or not host.endswith(".local"):
        return base_url
    try:
        infos = socket.getaddrinfo(host, parts.port, socket.AF_INET,
                                   socket.SOCK_STREAM)
    except (socket.gaierror, OSError):
        return base_url
    if not infos:
        return base_url
    ip = infos[0][4][0]
    netloc = ip if parts.port is None else f"{ip}:{parts.port}"
    return urlunsplit((parts.scheme, netloc, parts.path, parts.query,
                       parts.fragment))

Call it where the URL enters the process:

base_url = resolve_local_host(os.environ.get("SIGNALK_URL",
                                             "http://boat-server.local:3000"))
client = httpx.AsyncClient(base_url=base_url, timeout=5.0)

Passing socket.AF_INET to getaddrinfo asks for IPv4 candidates only, so
there is no IPv6 address to trip over. Every request connects in milliseconds.

Two properties made this the right shape:

It's a pass-through. Non-.local hosts come back untouched. Resolution failures come back untouched — httpx gets its normal shot and produces its normal error, instead of this helper inventing a new failure mode.
It's at the boundary. One call where config becomes a client, instead of a transport flag threaded through every constructor.

One fix, five repos: when a patch becomes a library

The first version of that function was pasted inline into the SignalK MCP
server, with a docstring and a small test file. Then the logbook server needed
it. Then currents. Then weather. Same commit message four times:

fix(client): resolve .local mDNS host to IPv4 (macOS httpx async/IPv6 hang)

Copy-pasting a fix across a fleet is fine exactly once — it's how you learn the
fix is actually cross-cutting. The fourth paste is the signal: this is a shared
library now. Ours is
naturali-mcp-netutil
— one function, stdlib-only, MIT, with the whole why in the README.

We deliberately did not publish it to PyPI. Consumers pull it as a
uv git source
pinned to a tag:

dependencies = ["naturali-mcp-netutil>=0.1.0"]

[tool.uv.sources]
naturali-mcp-netutil = { git = "https://github.com/sailingnaturali/naturali-mcp-netutil", tag = "v0.1.0" }

The reasoning: this package has exactly four consumers, all ours. A PyPI
release adds packaging ceremony, a public namespace entry, and an implied
support surface — for a 30-line function nobody outside the fleet should
depend on. The git source gets pinned in each consumer's uv.lock, so builds
are just as reproducible, and if the helper ever grows a real audience,
publishing it properly later costs nothing. Publish when someone else needs
it, not when you do.

Why it matters / gotchas

The failure is silent at the layer you're watching. An MCP tool that times out doesn't crash anything — the agent just reports it can't get the data, which reads like a model problem or a server problem. If every tool backed by the same host degrades at once, suspect the network path before either.
"curl works" localizes the bug better than any log. Same URL, same machine, different HTTP stack → the bug lives in the stack, not the server. That one console line should have saved the first hour.
getaddrinfo order is the whole game. Async connect logic believes the resolver's ordering. When the first candidate is unroutable-but-silent (no RST, just a black hole), timeouts get charged to whoever is first in line.
The fix outlived the problem. We later retired mDNS naming entirely — the fleet now reaches the boat server by a stable DNS name on a private tailnet, and .local no longer appears in any config. The resolver stayed: because it passes every non-.local URL through unchanged, it costs nothing, and it still guards anyone who points a config at a Bonjour name. A fix that's a pass-through survives its own obsolescence.

Close

This came out of building the AI ops layer for an all-electric charter
catamaran — a stack of open-source MCP servers between the agent and the boat's
SignalK data. The resolver and the servers it guards are public:
naturali-mcp-netutil,
signalk-mcp, and the rest at
github.com/sailingnaturali.

Related: launchd's minimal PATH breaks MCP servers: uv command not found — the other way an environment silently kills an MCP fleet — and when MCP tools break, isolate the server before blaming the agent for the debugging discipline that finds this class of bug.

Where a received distress call belongs in the SignalK data model

Bryan Clark — Sun, 26 Jul 2026 16:04:48 +0000

TL;DR — a distress alert heard from another vessel is not your boat's own alarm state, so don't raise it as plain notifications.* on self. The convention we landed on (signalk-dsc v0.9.0, signalk-ais-distress v0.5.0): raise the self-side alarm under notifications.received.* ("received about another vessel"), and also write the state record into the source vessel's own context — vessels.<mmsi>.notifications.mob for MOB, notifications.distress for SART/EPIRB. Jump to the convention.

Our stack has two plugins that hear other people's emergencies. signalk-dsc receives VHF DSC calls — a MAYDAY on channel 70 arrives as $--DSC sentences or PGN 129808. signalk-ais-distress alerts on AIS survival beacons — SART, MOB, and EPIRB devices, recognizable by their MMSI prefixes (970 / 972 / 974). Both are built on a shared library, signalk-distress-core.

Both plugins originally did the obvious thing: raise a notification under your own vessel.

# signalk-dsc ≤ 0.6.x — a received MAYDAY, raised on self
vessels.self.notifications.dsc.distress                state: emergency

# signalk-ais-distress ≤ 0.2.x — a heard MOB beacon, raised on self
vessels.self.notifications.ais.distress.mob            state: emergency

That fires the alarm chain, which is the point. But it puts someone else's emergency in the same subtree as your own vessel's alarm state, and that conflation bites.

The problem: `notifications.*` on self means "something is wrong with MY boat"

In the SignalK data model, notifications are per-context. vessels.self.notifications.mob means your crew is in the water. vessels.self.notifications.grounding means you are aground. The spec's alarm vocabulary (mob, fire, sinking, flooding, collision, grounding, listing, adrift, piracy, abandon) describes the vessel the notification hangs off.

Everything downstream is built on that reading:

Annunciators and dashboards render vessels.self.notifications.* as own-vessel health. With the old paths, a boat sinking three miles away shows up looking like your hull alarm.
Muting and acknowledgment are own-vessel operations. "Silence my alarms" should not be able to swallow a stranger's MAYDAY — and conversely, a received alert you've assessed shouldn't keep tripping logic that watches self state.
Automations keying on self notifications (shutdowns, all-hands triggers) must be able to tell "we are in distress" from "we heard distress."

notifications.dsc.distress under self says the first thing when it means the second. This came up in discussion with the SignalK community, and talking it through made the distinction crisp: a distress heard from another MMSI is data about that vessel, received by you — not your state.

What we considered

Leave it on self under notifications.dsc.* (status quo). Fires the alarm chain, but conflates own-vessel and other-vessel state — the whole problem above.

Write it only into the source vessel's context. The spec-pure answer: a notification under vessels.<mmsi> is that vessel's alarm. But nothing on your boat subscribes to arbitrary other-vessel notification paths, so your own annunciator never fires — a MAYDAY you heard and silently filed is worse than the conflation. And it doesn't even cover every case: a SART or personal EPIRB isn't necessarily a vessel at all.

Invent device-type leaves in the target context (notifications.sart, notifications.epirb). Not spec natures, and a beacon with a 972 MMSI may be a crew-worn personal device — a device-type leaf misdescribes what's happening (a person in the water, a station in distress), and consumers would have to learn our invented vocabulary.

None of the single-write options work, which is the actual finding: actuation and state are different consumers, and they want the record in different places.

The convention: two writes

Write 1 — self, under notifications.received.*. This is the actuation layer: the path your own alarm chain, voice pipeline, and annunciators subscribe to. The received segment says exactly what it is — received about another vessel. Each call raises its own per-call path — the leaf is <transport>-<id>, so two concurrent MAYDAYs never stomp one key:

# signalk-dsc 0.9.0 — one alarm per call, at its own path
vessels.self.notifications.received.distress.dsc-<id>     state: emergency
vessels.self.notifications.received.urgency.dsc-<id>      state: alarm
vessels.self.notifications.received.safety.dsc-<id>       state: warn

# signalk-ais-distress 0.5.0 — SART, MOB, and EPIRB all raise under distress
vessels.self.notifications.received.distress.ais-<id>     state: emergency
vessels.self.notifications.received.<category>.ais-<id>   # AIS Msg 14 relays

<id> is <receivedAt>-<mmsi> with the ISO timestamp's . and : stripped, so the whole id stays a single path segment instead of splitting into extra ones.

Clearing now has two levels:

Per-call ack — a PUT to the exact per-call path you see (notifications.received.distress.ais-<id>) clears that one call and stamps the store so a restart re-raise skips it. This is SignalK's standard notification-ack: you acknowledge the alarm in front of you, and only it.
Bulk clear-by-category — a PUT to a fixed control path drops every live call of that category at once:

# control paths — PUT clears all live calls of that type (transport-first)
vessels.self.notifications.received.dsc.<category>            # dsc.distress / .urgency / .safety
vessels.self.notifications.received.ais.distress.<beacon>     # ais.distress.sart / .mob / .epirb
vessels.self.notifications.received.ais.broadcast.<category>  # AIS Msg 14 relays

Note the segment order flips: a raised alarm is category-first (received.distress.dsc-<id>); a control path is transport-first (received.dsc.distress). Either way you're managing your response to someone else's emergency, not your own vessel's condition.

Write 2 — the source's own context. This is the interoperable state record: the distress hung on the vessel it's actually about, exactly as if that vessel had raised it — which, over the radio, it did. From signalk-ais-distress:

// Mirror signalk-dsc: besides the self alarm, surface the distress in the
// *source vessel's* context, so a consumer reading that AIS target sees its
// emergency — as if the vessel raised it. The self notifications.received.*
// alarm is the actuation layer our own annunciator subscribes to; this is
// the interoperable state record.
function notifyTarget(event) {
  if (!event.mmsi) return;
  const leaf = event.deviceBeacon === 'mob' ? 'mob' : 'distress';
  const value = { state: 'emergency', method: ['visual', 'sound'], message: event.message };
  if (event.receivedAt) value.timestamp = event.receivedAt;
  app.handleMessage(plugin.id, {
    context: `vessels.urn:mrn:imo:mmsi:${event.mmsi}`,
    updates: [{ values: [{ path: `notifications.${leaf}`, value }] }],
  });
  // Also feed the flat legacy self-key so existing MOB subscribers (e.g.
  // meshtastic waypoint minting) keep firing until they migrate to the
  // received.* / per-vessel scheme (SK spec thread 2026-07-15). Default
  // context is self — this is the one deliberate own-vessel double-write.
  if (leaf === 'mob') {
    app.handleMessage(plugin.id, {
      updates: [{ values: [{ path: 'notifications.mob', value }] }],
    });
  }
}

So a heard MOB beacon (fake MMSI for illustration) produces three writes — the per-call self alarm, the source-context state record, and the legacy self-key shim:

vessels.self.notifications.received.distress.ais-<id>     ← your alarm fires
vessels.urn:mrn:imo:mmsi:972999999.notifications.mob      ← the beacon's own state
vessels.self.notifications.mob                            ← legacy self-key (back-compat)

Why those leaves

MOB → notifications.mob. It's a real spec nature, and it's what existing consumers key on — signalk-meshtastic-style bridges watch other-vessel notifications.mob to mint a MOB waypoint on the mesh. Using the spec leaf means those consumers work with no knowledge of our plugin.

SART/EPIRB → notifications.distress. These beacons carry no nature-of-distress, and the source may be a personal device rather than a vessel — so neither a nature leaf nor a device-type leaf is honest. distress states the one thing actually known: this station is in distress.

DSC → notifications.<nature> under the caller. A DSC distress alert does carry a nature-of-distress code, and the ITU table maps almost one-to-one onto the spec's alarm vocabulary — sinking, fire, flooding, grounding, mob, and so on. So signalk-dsc writes the caller-context record at the real nature:

vessels.self.notifications.received.distress.dsc-<id>      ← your alarm fires
sar.urn:mrn:imo:mmsi:366999999.notifications.sinking       ← the caller's own state

Note the context prefix: a DSC distress caller is emitted under the Search-and-Rescue context (sar. instead of vessels.), which chartplotters like Freeboard-SK render as a distress/SaR target rather than an ordinary AIS contact. Urgency and safety callers stay under vessels. like any other contact.

Two more beats from the same release train

Received alerts survive a restart. SignalK notifications are in-memory — a server bounce mid-incident would silently drop an active MAYDAY. Both plugins re-raise every still-fresh, un-acked call on startup, each at its own per-call path (details in the original signalk-dsc post); a per-call ack stamps the store so the re-raise skips one you've already handled.

Distress relays get attributed to the casualty, not the relaying station. A coast station retransmitting a distress alert puts the casualty's MMSI, nature, and position in different sentence fields than a first-hand alert — the stock parser read the relay's fields as if they were the casualty's, pinning the emergency on the coast station. Fixed upstream in SignalK/nmea0183-signalk#344.

The shape of it

Heard	Self (actuation, one per call)	Source's own context (state)
DSC distress (Ch 70 / PGN 129808)	`notifications.received.distress.dsc-<id>`	`sar.<mmsi>` → `notifications.<nature>`
DSC urgency / safety	`notifications.received.<category>.dsc-<id>`	`vessels.<mmsi>` → position only
AIS SART / EPIRB (970 / 974)	`notifications.received.distress.ais-<id>`	`vessels.<mmsi>` → `notifications.distress`
AIS MOB (972)	`notifications.received.distress.ais-<id>`	`vessels.<mmsi>` → `notifications.mob` (+ legacy `notifications.mob` on self)
AIS Msg 14 broadcast	`notifications.received.<category>.ais-<id>`	—

The "Self" column is the raised per-call path; a PUT there acks that one call. The matching bulk clear-by-category control paths are transport-first and category-tailed — notifications.received.dsc.<category>, notifications.received.ais.distress.<beacon>, notifications.received.ais.broadcast.<category> — and a PUT to one drops every live call of that type.

One rule underneath all of it: a notification's context names whose emergency it is. Self gets the received.* alarm because you need to act; the source context gets the spec-native record because they are the ones in distress. The one deliberate exception is MOB: alongside the source-context notifications.mob, both plugins also write a flat notifications.mob on self — a back-compat shim so existing MOB subscribers (meshtastic waypoint minting) keep firing until they migrate to the received.* / per-vessel scheme. It bends the rule on purpose, and it's the one place a received alarm still lands on a bare self path.

This is one piece of an all-electric charter-catamaran ops stack — when the radio hears someone in trouble, the data model should say so without claiming the trouble is yours. Code: signalk-dsc, signalk-ais-distress, shared signalk-distress-core.

When AI agents write the ship's log, record who wrote what

Bryan Clark — Fri, 24 Jul 2026 17:22:29 +0000

TL;DR — When humans, vessel automation, and an AI agent all write the
same logbook, you need per-entry provenance. We added an optional
origin: manual | auto | agent field upstream in
signalk-logbook
(PR #88,
released in 0.11.0), made consumers derive it from author conventions for
legacy entries, and put the EU's recommended AI label on agent-written
lines. Jump to the design.

Our ship's log has three kinds of writers. A human types (or dictates) a
line. The logbook plugin itself writes unattended entries — hourly underway
logs, notification state changes, crew changes. And our voice agent writes
entries through the REST API: "log this moment", drill summaries, distress
receptions. All three land in the same per-day YAML files.

The question this post answers: six months from now, reading a day back,
how do you know which lines a human actually wrote?

Problem

Here's a day file from our archive before this work. Three entries, three
different writers — and the only provenance is accidental:

- datetime: '2026-06-11T08:01:00.000Z'
  text: 'Motoring at 6.1kt'
  author: ''                    # plugin's own hourly writer
- datetime: '2026-06-11T09:14:00.000Z'
  text: 'MOB drill completed, 4 min recovery [drill:mob]'
  author: 'hermes'              # the agent's API token principal
- datetime: '2026-06-11T10:02:00.000Z'
  text: 'Sail change, reefed main'
  author: 'bryan'               # a person, via the web UI

The empty author means "the plugin wrote it" only because the plugin's
unattended writers happen to call stateToEntry(state, text) without an
author. The agent entries say hermes only because that's the name on the
authentication token the MCP server holds. Nothing in the data model says
this line was composed by an AI. Readers — agents summarizing a passage,
a morning briefing, a human reviewing the log — cannot reliably tell a
human-authored line from machine output.

That used to be a nice-to-have. It increasingly isn't: agent-written records
need labeling. The EU has published
recommended icons for labelling AI-generated content,
and a logbook is exactly the kind of record where "who wrote this" matters
for trust and for corrections.

Designs we rejected

Overloading author. Stuffing provenance into the author string
(author: "bryan (via agent)") destroys the one clean signal the archive
already has, and every consumer grows a parser.

A structured source object. source: {kind: agent, model: …, version: …} is the flexible version nobody asked for. One enum answers the
actual question; a nested object is schema surface you maintain forever.

Asking the speaker to identify themselves. For voice entries, "who is
this?" before every log line is terrible ergonomics, and our STT stack
(Whisper) has no speaker recognition anyway. Assume-and-confirm beats
interrogate (more below).

The design

One optional enum, and a sharp rule for what it means:

author = who is responsible. origin = who composed the words.

This is the watchkeeper model from paper logbooks: the officer on watch
signs the page even when the instruments took the reading. Responsibility
and authorship are different columns.

manual — a person composed the text. Typed or dictated: a voice-dictated line is manual, because the voice pipeline is just the pen.
agent — an AI composed the text (drill summaries, mark_moment phrasings).
auto — unattended machinery (hourly logs, notification triggers).

The dictation point is the subtle one. If you classify by transport
(API-written = machine), every voice entry becomes machine output and the
label loses its meaning. Classify by who chose the words.

Forward-compatible rollout

The archive had 72 entries and zero explicit provenance. We refused to
migrate files, and we didn't want to block on the upstream release either.
So the rollout is two-sided:

Writers stamp origin now. Our MCP server started sending origin: "agent" in POST bodies before upstream knew the field existed — the server's field whitelist silently dropped it, a harmless no-op. The day the upstream release landed on the boat server, the stamps became effective. No coordination needed.
Consumers derive origin for legacy entries from the author conventions the archive already encodes. Explicit field wins when present; heuristics fill the past.

Upstream: PR #88

PR #88 (merged,
released in signalk-logbook 0.11.0) adds the field end to end. The core is
one parameter:

// plugin/format.js
module.exports = function stateToEntry(state, text, author = '', origin = 'manual') {
  const data = {
    datetime: state['navigation.datetime'] || new Date().toISOString(),
    text,
    author,
    origin,
  };
  // …

The unattended writers — notification entries, trigger entries (autopilot,
crew, sail changes), the hourly underway log — pass origin: 'auto'.
POST /logs accepts both author and origin in the body:

// plugin/entryFields.js
if (typeof body.author === 'string' && body.author.length >= 1) {
  // Delegation: an authenticated client (voice assistant, crew app) writes
  // the line on behalf of the person who authored it.
  entry.author = body.author;
}
if (['manual', 'auto', 'agent'].includes(body.origin)) {
  entry.origin = body.origin;
}

The author half matters as much as the origin half: it lets an
authenticated client write a line on someone's behalf and sign it for
them. PUT already honored a body-supplied author; this made POST
consistent. Invalid origins are ignored rather than erroring — an optional
provenance field should never bounce a log entry.

Two improvements came out of review with the maintainer:

Legacy entries get a definite origin at read time. Rather than making
every consumer handle "field absent", the plugin defaults it when reading —
same pattern as its read-time category default:

// plugin/Log.js — reading a stored day file
origin: entry.origin || (entry.author ? 'manual' : 'auto'),

Stored origins are preserved; authorless legacy entries read as auto
(they were the plugin's own), authored ones as manual. Consumers always
see a definite value.

Agent entries get the EU AI label in the UI. The maintainer pointed at
the EU's AI-content labelling icons;
the badge renders next to the author on agent entries in the logbook
table, timeline, and entry viewer:

// src/components/OriginBadge.jsx
function OriginBadge(props) {
  if (props.origin !== 'agent') {
    return null;
  }
  return (
    <svg role="img" aria-label="AI-generated entry" /* inlined EU "AI" icon */>
      <title>AI-generated entry</title>
      {/* … */}
    </svg>
  );
}

The tooltip text is deliberate — the EU's own testing found icon + text
label beats the icon alone. manual and auto entries render untouched:
the label marks AI output, it doesn't decorate everything.

A companion PR,
#92, rounds out
the responsibility side: it snapshots communication.skipperName into every
entry next to the existing crewNames, and logs skipper handoffs
automatically. With authorship (origin), responsibility (author), and
command (skipperName) each in their own field, you can derive things like
skipper-vs-crew days for sea-service records straight from the log.

Consumer side: deriving origin in the MCP server

logbook-mcp is the tool
surface our agents use. Its read path implements the legacy heuristic —
explicit field first, then author conventions:

def derive_origin(
    entry: dict,
    agent_authors: frozenset[str] = DEFAULT_AGENT_AUTHORS,   # {"hermes", "poseidon"}
    auto_authors: frozenset[str] = frozenset(),
) -> str:
    origin = entry.get("origin")
    if origin in ORIGINS:
        return origin            # explicit field wins (post-upstream entries)
    author = entry.get("author") or ""
    if not author:
        return "auto"            # the plugin's own unattended writers
    if author in agent_authors:
        return "agent"           # a known agent token principal
    if author in auto_authors:
        return "auto"            # a known automation token principal
    return "manual"              # any other author is a person

The principal lists are configuration, because they're deployment facts:
your agent tokens have your names. Every entry returned by
read_entries carries a derived origin, and the tool grew an origin
filter so "show me only the human entries from Tuesday" is one call.

The write path stamps by composition, per the manual-vs-agent rule:

# mark_moment: default origin="agent" — the agent composed the phrasing.
# A dictated line passes origin="manual" — the human composed it.
await client.post_entry(text, category=category, origin=origin)

And signalk-distress-core
— the shared library behind our DSC and AIS-distress plugins, which writes
received distress traffic into the logbook — stamps auto:

// lib/logbook.js — a DSC reception is a plugin-automatic reaction,
// not agent reasoning. Ignored by signalk-logbook until its
// origin-field PR ships, then explicit.
origin: 'auto',

That last classification is worth pausing on. The distress writer runs
inside an "AI stack", but no model composes those lines — a parser does.
origin describes the composer, not the vibe of the system it lives in.

Voice attribution: assume, confirm, correct

The author delegation in POST unlocked the piece users actually feel.
When someone dictates a log entry, the stack has no speaker ID — so the
agent assumes the author (the person on watch; solo default today) and
says the assumption out loud. mark_moment's return value is a
ready-to-speak confirmation that ends with the attribution:

Logged. Entry 4. 14:32. 48.76°N 123.2°W. Logged as Bryan.

If the assumption is wrong, the speaker just says so, and the correction
path is its own tool:

async def amend_entry_author(client, entry_id: str, author: str) -> dict:
    """Reattribute an existing entry — the voice-correction path."""
    # fetch the day, find the entry, PUT it back with the corrected author
    ...
    return {
        "id": entry_id,
        "author": author,
        "confirmation": f"Corrected. Entry now logged as {author}.",
    }

"No, that was Sarah" → amend_entry_author → "Corrected. Entry now logged
as Sarah." Assume-and-confirm costs one spoken clause; interrogating the
speaker before every entry would cost the feature.

One implementation wrinkle: at the time we shipped this, upstream POST
couldn't set author yet (only PUT honored it), so mark_moment POSTs
the entry and then PUTs it back with the body-supplied author. That
two-step still works against older servers — same forward-compatibility
posture as the origin stamps.

Why it matters / gotchas

Provenance you don't record at write time is provenance you reconstruct forever. Our 72-entry archive is small enough that author heuristics recover it. At 10,000 entries with rotated token names, it wouldn't be. Writers stamp going forward; heuristics are strictly for the past.
Classify by composer, not transport. API-written ≠ machine-written (dictation), and inside-an-AI-stack ≠ AI-composed (the DSC parser). Get this wrong and the AI label becomes noise.
Absent optional fields should default at read time, in one place. The read-time default (entry.origin || (entry.author ? 'manual' : 'auto')) means no consumer ever branches on "field missing". Cheap in the plugin, expensive everywhere else.
Ship writers before the schema lands. A field the server's whitelist drops is a free forward-compatibility bet: harmless today, effective the day the upstream release deploys — with no lockstep upgrade.
Labeling agent output is becoming table stakes. The EU publishes ready-made icons for exactly this; wiring one into a hobby-scale marine plugin took ~30 lines. If your agents write records humans later trust, there's little excuse not to.

We run this stack on the boat-agent system behind an all-electric charter
catamaran project — the ship's log is on the ship, and now it tells you who
held the pen. The MCP side lives at
sailingnaturali/logbook-mcp.

Related: how the logbook ended up on the SignalK server in the first
place — Adopt vs build: why we deleted our working logbook for SignalK.

Two false walls in NOAA's currents API: empty constituents and "not available"

Bryan Clark — Thu, 23 Jul 2026 17:28:49 +0000

This one started with a snap judgment, and the snap judgment was wrong in the most
useful way. I was looking at XTide, the reference-grade
open-source tide and current predictor, and my first reaction was: this website looks
like it was built in 1998, I wouldn't trust something this poorly put together. That
reaction is unfair — XTide's data is impeccable, and the crustiness of a maintainer's
homepage tells you nothing about the quality of the harmonic constants underneath it.
But being wrong about XTide's site pushed me to the right question about XTide's
role: do I even need to harvest XTide's data, or can I go straight to the source it
ultimately derives from — NOAA? Chasing that question cost me two full days walking into
walls that both looked like the end of the road. Neither was.

TL;DR — I wanted US tidal-current harmonic constituents for an offline engine.
Wall 1: NOAA's harcon.json returned an empty constituent list for current
stations, so I concluded NOAA doesn't publish current constituents. Wrong — it's empty
only at bin=0; query the station's currbin and you get 26 real constituents
(Deception Pass M2 = 5.418 kn @ 241.2° GMT). Empty ≠ absent. Wall 2:
currents_predictions returned "not available from the requested station" for every
station — including NOAA's own documented example — so it looked like a dead product.
Wrong again: browser User-Agent + a real prediction station + its currbin and it
returns data. The service was never down; my request was. Outcome: XTide dropped
entirely, 855 harmonic + ~1,700 subordinate stations straight from NOAA, validated to
9.7 min / 0.055 kn against NOAA's own predictions.
Jump to the validation.

Plan A, and why it wasn't Plan A for long

The engine already predicted tides from NOAA harmonic constants, offline and validated
to a few minutes against CO-OPS. Currents are the same math — a sum of cosines that
happens to produce signed velocity instead of height — so the only new input was
current constituents. The obvious source was XTide's Harmbase2 (via libtcd): US current
stations, public-domain-derived, exactly the constants I needed.

But routing through XTide means adopting XTide's snapshot of the constants, its naming,
its extraction toolchain, and its update cadence. If NOAA publishes the same constituents
directly, I'd rather consume them at the source and skip the middleman entirely. So before
committing to Harmbase2, I spent an hour poking at NOAA's metadata API to see whether the
current constituents were there.

They appeared not to be. That's Wall 1.

Wall 1: "NOAA doesn't publish current constituents"

NOAA's CO-OPS metadata API (mdapi) serves harmonic constituents for a station at:

https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations/<id>/harcon.json?units=english

For a tide station this returns the full constituent set. For a current station —
Deception Pass, Rosario Strait, the passes I actually cared about — it returned a valid
JSON envelope with an empty constituent array. Not a 404, not an error. Just: here is
your station, and it has zero harmonic constituents.

The natural read is that current stations simply don't carry published constituents —
that NOAA serves current predictions as a finished product but keeps the underlying
harmonics private, the way some hydrographic services do. I wrote that down as a finding
and started building the XTide extractor for real.

That conclusion was wrong, and the tell was sitting in the station metadata the whole
time. Current stations are three-dimensional in a way tide stations aren't: a current is
measured at a depth bin, and each station has a reference bin — the depth the
published predictions are computed for. That field is currbin, and it's right there in
the station-list record:

https://api.tidesandcurrents.noaa.gov/mdapi/prod/webapi/stations.json?type=currentpredictions&units=english

Each record carries id, name, lat/lng, type (H = harmonic, S = subordinate,
W = weak/rotary), and crucially currbin. The harcon.json endpoint takes a bin
parameter, and it defaults to bin=0. Bin 0 is above the reference depth for these
stations — there's no harmonic solution published there, so the array is legitimately
empty. Ask for the right bin and the data pours out:

harcon.json?units=english&bin=<currbin>

Deception Pass Narrows (PUG1701, currbin=18) returns 26 constituents, and they're
exactly what a current predictor needs — richer than the tide equivalent:

constituentName   "M2"
majorAmplitude    5.418      // knots, major-axis semi-amplitude
majorPhaseGMT     241.2      // Greenwich-referenced phase, degrees
majorMeanSpeed   -0.619      // mean flow along the axis (Z0), knots
azi               92.9       // major-axis azimuth, degrees true
minorAmplitude / minorPhase  // the rotary (cross-axis) component
binNbr / binDepth / constNum

That's the whole model: majorAmplitude and majorPhaseGMT drive the sum, azi gives
the flood axis (ebb is azi+180), and majorMeanSpeed is the Z₀ offset for a station
whose flow doesn't average to zero. The empty array wasn't NOAA telling me the data
didn't exist. It was NOAA answering a question I hadn't meant to ask — what are the
constituents at the surface? — and me reading the answer as there are no constituents.

Empty is not absent. An empty result to a query with a defaulted parameter is a
statement about your query, not about the data. That cost me the better part of a day and
an entire wrong architecture.

Wall 2: "the predictions API is down"

With constituents in hand I needed an oracle — NOAA's own predicted slack/max events —
to validate the engine against. That lives on the older Data Retrieval API:

https://api.tidesandcurrents.noaa.gov/api/prod/datagetter
  ?product=currents_predictions&interval=max_slack&bin=<currbin>
  &station=<id>&begin_date=...&end_date=...&units=english&time_zone=gmt&format=json

Every station I tried came back with:

{ "error": { "message": "Currents predictions are not available from the requested station" } }

Every one. Including the station NOAA uses in its own API documentation as the worked
example. When even the documented example fails, the honest inference is that the product
is down — CO-OPS was mid cloud-migration that week, so a dead endpoint was entirely
plausible. I nearly wrote it off and shipped with structural validation only.

It wasn't down. There were three separate things wrong, stacked, each one enough on
its own to produce a failure that looked like an outage:

(a) NOAA 404s the default User-Agent. Plain curl and Node's fetch send a
default UA (curl/8.x, node), and NOAA's edge returns a bare 404 for it. The exact
same request from a browser — same machine, same residential IP — returns data. Send a
browser User-Agent header and this failure vanishes:

User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) ...

(b) Transient rate-limiting that looks like an IP block. My probing volume (I was
hammering the endpoint trying to figure out why it failed) tripped NOAA's throttle, which
also returns bare 404s. I spent an embarrassing stretch convinced NOAA was blocking
datacenter IPs — I'd seen mdapi 404 from cloud egresses before — until the same box that
was 404ing from a script served the request fine in a browser. That's not an IP block;
an IP block would fail in the browser too. The variable that changed between the two was
the User-Agent (and the request pacing), not the IP. Slow down and send a real UA and the
404s stop.

(c) Wrong stations at the wrong bin. Some of the stations I was hammering are
observation / survey stations, not published-prediction stations — currents_predictions
genuinely isn't served for those, correctly. My actual target passes (PUG1701 Deception
Pass, PUG1717 Turn Point) are survey stations NOAA doesn't publish predictions for. But
hundreds of other harmonic stations are served — PUG1741 (Bellingham Channel),
PUG1612 (Clinton Ferry), SFB1222 — and only when queried at their currbin.

Fix all three — browser UA, polite pacing, a served station at its reference bin — and
currents_predictions returns clean data. It was never down. Every failure I saw was my
own request.

The turn: verify against a known-good client

What actually broke the logjam wasn't a NOAA status page. It was reading someone else's
working code.

I found the Perigee-Tides MCP, a
third-party client that talks to the same CO-OPS endpoints, and diffed its request
construction (src/services/data-api.ts, metadata-api.ts) against mine. Byte for byte,
the URL shape, the parameters, the field names — identical. My request format was
correct. It had been correct the whole time.

That's the pivot the whole debugging session turned on, and it generalizes:

When your request matches a known-good client and it still fails, the variable is the
target, not the syntax. Stop editing the request and start changing what you point
it at — the station, the bin, the headers, the rate.

Once the format was ruled out, the remaining differences could only be the station, the
bin, the UA, and the request rate — which is exactly where the three real problems were.
I'd spent hours suspecting my URL. The URL was fine.

Outcome: XTide dropped entirely

Both walls fell, and on the far side of them the original question answered itself: I
don't need XTide at all. Everything comes straight from NOAA CO-OPS, public domain:

Constituents — harcon.json at the station's currbin.
Flood/ebb axis — azi (flood) and azi+180 (ebb).
Mean flow — majorMeanSpeed as the Z₀ offset.
Subordinate stations — currentpredictionoffsets.json, giving time and speed offsets against a reference harmonic station.

The build-time extractor sweeps NOAA's station list and pulls each station's harcon (at
its currbin) and offsets, producing a bundled currents.json computed offline at runtime
— 855 harmonic + ~1,700 subordinate stations, all of US waters, including the US Salish
Sea passes I set out for: Deception Pass, Rosario, San Juan Channel, Turn Point. No XTide
data, no tide binary, no libtcd, at build time or run time.

The receipt: vs NOAA's own predictions

Once currents_predictions was serving, it became the oracle it was always meant to be —
the independent authority check. Feed the engine a station's published constituents,
predict its slack/max events, and compare to NOAA's own published events for the same
station and days.

Harmonic station — PUG1741 (Bellingham Channel), a clean ~2.8 kn reversing station:
max flood/ebb events match NOAA to 9.7 min / 0.055 kn across 11 events — on par with
the tide engine's Phase-0 (7.9 min / 3.5 cm). The fixture is captured offline so the check
runs in CI without the network.

Subordinate reduction — PCT0236 (reference SFB1201): 6.1 min / 0.05 kn over 11
events. Subordinate stations were subtler than tides because NOAA publishes two slack
offsets — slack-before-flood (sbfTimeAdjMin) and slack-before-ebb (sbeTimeAdjMin) —
not one. A slack takes the offset for the phase it precedes. Model it with a single slack
offset and half your slacks land at the wrong minute.

One labeling insight fell out of matching NOAA at weak stations: classify max flood vs
max ebb by the sign of the velocity, not by slope high/low. At a strong reversing pass,
a velocity peak (slope zero) that's positive is a flood and negative is an ebb, and
high/low slope gives the same answer. But at a weak, non-reversing station a relaxation
peak never crosses zero — a −0.3 kn local maximum during a long ebb is slope-high but
it's still an ebb. Label it by sign and you match NOAA's max_slack exactly.

The bugs only a batch caught

Validating one station passed clean. Then I validated a diverse batch — different regions,
offset signs, speed ratios, harmonic and subordinate — and it broke in two different ways the
single-station test had walked right past. Both are the same shape: a category I'd treated as
monolithic turned out to have a second variety, and only the second variety triggered the bug.

A reference is (station, bin), not just a station. A subordinate references a specific
bin of its reference station (refStationBin) — because, same lesson as Wall 1, a current
reference is depth-keyed. My extractor stored one bin's constituents per reference. That's
fine until a reference publishes multiple bins with different constituents. SFB1201
publishes bins [26, 20, 10], each with its own harmonic set. Storing one silently resolved
half the subordinates against the wrong constituents — ~50 min and ~0.6 kn off. The
single-station test had happened to hit the bin I'd stored, so it passed and told me nothing.
Fix: resolve each reference at its exact refStationBin.

"Subordinate" doesn't always mean subordinate. Some NOAA type: S stations carry their
own harmonic constituents, and NOAA predicts those harmonically — the offset reduction is
only for stations that have none. PUG1716 (which references San Juan Channel) is type S but
has its own 25-constituent harcon; reducing it from San Juan Channel over-shot it by 89 min
/ 0.7 kn. Predicted from its own constituents: 6.8 min / 0.06 kn. Fix: for a type-S
station, fetch its own harcon first; fall back to the reduction only when it's empty. With
both fixes, nine genuinely-subordinate stations match NOAA to 0.9–7.7 min.

The lesson keeps recurring in this engine: n=1 validation hides class bugs. One passing
station proves one station. Validate across the diversity of the data — regions, bins, ratios,
harmonic and subordinate — and the class of bug that only shows up at the second variety finally
has somewhere to show up.

The passes I set out for turned out served

There's a fitting last twist. This whole project started to get currents for my home passes —
Deception Pass, Rosario Strait, San Juan Channel, Turn Point. Early on those returned
"not available", so I filed them as survey stations NOAA doesn't predict and validated them
only transitively — engine-correct-on-other-stations plus faithful constituents. That was Wall
2 in miniature, and I'd quietly surrendered to it.

Re-checked with the right bin and a browser User-Agent: every one is served. They validate
directly against NOAA's own predictions now — Deception Pass to 14 min, Admiralty Inlet to 3.5,
Race Rocks to 6.0, on the significant currents. (The weak sub-¾-knot relaxation extrema at the
mixed-tide stations disagree by tens of minutes — but those are ill-conditioned in NOAA's
computation too, and a boat doesn't care when a third of a knot peaks.) The premise that my home
water was unreachable was, like every wall in this story, my request being wrong — not the data
being absent.

Five things I'm keeping

Empty ≠ absent. An empty result to a query with a defaulted parameter (bin=0) is a fact about your query, not about the data. Check what you defaulted before you conclude the data doesn't exist.
"The service is down" is usually your request. Three stacked causes — User-Agent, rate, target — each looked like an outage. The endpoint was serving the whole time.
An ugly UI is not evidence about data quality. XTide's 1998 homepage says nothing about its constants. The reaction was wrong, but interrogating it led to the better architecture — go to the source.
Verify against a known-good client before you touch your request. When your request matches a working client and still fails, the variable is the target, not the syntax.
Validate at scale, not n=1. One passing station hid two bugs here, each triggered only by a second kind of station. Test across the diversity of the data — and the passes you gave up on may turn out served all along.

The engine is MIT-licensed and the currents fixtures are reproducible from NOAA's own
predictions: slackwater-engine.
If it's off at your home pass, the golden generator points at any served NOAA station — run
it and send a number back.

Not for navigation. Current predictions are astronomical estimates and don't account
for wind, freshet, or local effects. Carry official current tables and charts.

The marine SignalK + MCP landscape: what exists, what's actually novel

Bryan Clark — Tue, 21 Jul 2026 16:03:40 +0000

TL;DR — We shipped seven marine MCP servers, then ran the ecosystem
scan we should have run first. The good news: the niche is sparse, and the
capabilities we bet on (NDBC buoy reality-check, tidal currents, COLREGs
rule text, anchorage comfort ranking) turned out to have no prior art
anywhere in the MCP ecosystem. The bad news: a one-evening scan would still
have changed several decisions. Jump to the map.

This stack runs on a prime directive: use or improve existing tools before
building your own. We applied it per-component — it's why we
deleted our working logbook for signalk-logbook
and why the
weather server got audited against three existing weather MCPs.
What we never did was scan the whole ecosystem at once: every marine MCP
server, every SignalK AI integration, every plugin adjacent to what we were
building.

When we finally ran that scan — seven servers deep — the honest question was:
how much did we just rebuild? This post is the answer, published as the map
we wish we'd found.

The map

Everything here is public; links go to the repos. "Novel" means we found no
prior art doing the capability, in any MCP server, as of the scan.

Ours	Nearest prior art	Verdict
currents-mcp + signalk-currents (tidal currents, gates, slack windows)	openwatersio/signalk-tides — tide height only	Novel. Nobody else does tidal currents. We forked the right tide base and contributed upstream.
weather-mcp (marine forecast + NDBC buoy reality-check)	weather-mcp/weather-mcp (generic, 17 tools); NOAA-TidesAndCurrents-MCP	NDBC reality-check is novel — no MCP anywhere ingests NDBC observations and diffs them against the forecast. The generic ones were worth studying as tool-design baselines, though.
pilotbook-mcp (anchorage search + comfort ranking)	itemir/signalk-console (ActiveCaptain POI display)	Novel. No searchable pilot-book with conditions-aware comfort ranking exists; the closest thing is a passive POI widget.
colregs-mcp (nav-rules reference + compliance)	VladimirKalachikhin/collision-detector (geometric CPA, no rule text)	Novel. The only other collision-reasoning attempt is pure geometry — nobody else encodes the COLREGs rule text for agents.
logbook-mcp (over signalk-logbook)	PostgSail + postgsail-mcp-server	Should have found PostgSail pre-build. Complementary in the end — it's historical-DB analytics, ours is live capture — but this is the one a scan would have flagged first.
vessel-knowledge-mcp (equipment spec cards, alarm explain)	joelkoz/signalk-hour-meter (engine hours off SignalK paths)	Knowledge-cards-as-MCP is novel; hour-meter is direct prior art for one planned sub-feature (engine-hours) — see below for why it's reference-only.
signalk-ntfy-relay (push notifications)	itemir/signalk-notifications (Pushover); sbender9/signalk-push-notifications (SNS)	ntfy backend is novel — everyone else routes through Pushover or SNS. Same job, different (self-hostable, zero-account) delivery path.
signalk-mcp (live vessel data + alarms for agents)	VesselSense (the one serious SignalK-MCP peer, code-execution architecture); SignalK/signalk-server#1867 (native MCP endpoint — open, unassigned)	Peer exists with an opposite tool philosophy — we compared discrete named tools vs execute-code at length. Upstream native MCP is still an open issue, so the space is genuinely unclaimed.

Also on the map, outside the fleet's footprint:

d3kOS — a Raspberry Pi AI helm computer: offline voice, engine-diagnostics RAG over PDF manuals, bow-camera object detection. The manual-RAG and bow-cam pieces are ahead of anything we run; worth watching.
Windward MAI Expert — commercial, fleet-scale "alarm → agentic enrichment → narrative brief." Not something a cruiser can run, but it independently validates the alarm-triage agent pattern.
Saillogger's AIS MCP — a narrow stub today, from the same author as signalk-console.

What the scan actually found

1. We didn't wholesale rebuild — the niche really is sparse. Four of
seven servers had no prior art. That surprised us: MCP servers exist for
seemingly everything, but "marine + operational + agent-facing" is nearly
empty. If you're building here, the ecosystem-scan cost is one evening and
the field is still mostly unclaimed.

2. The one real miss was PostgSail. An Apache-2.0 voyage database with
its own actively maintained MCP server — voyage history, trip summaries,
monitoring, maintenance notes — and we found it after shipping our logbook
integration. The post-hoc assessment landed on "don't adopt the stack, borrow
the tool design" (it's a whole Postgres/Timescale/Grafana tier, aimed at
dashboards; our log lives on the vessel as YAML). But that's a verdict we got
lucky on. A pre-build scan makes it a decision instead of a coin flip.

3. Licensing is part of prior art. signalk-hour-meter looked like an
adopt candidate for engine-hours — until the scan showed it dormant for
years and, critically, unlicensed. No license means all-rights-reserved:
you can read the pattern, you cannot ship the code. That single check
converted "adopt" into "pattern reference only" in one minute. Check the
license before you get attached.

4. A name collision is not a collaboration target. There's an active,
polished, generic weather-mcp org whose README states its marine data is
"not suitable for navigation" — the exact opposite of an on-boat operational
tool, and no buoy observations at all. Same name, disjoint philosophy. The
practical lesson: when your repo name is saturated (8+ unrelated
weather-mcps exist), always qualify yours by org in docs and cross-refs.

5. The people map is half the value. The scan's most useful output
wasn't code at all — it was discovering we were already running several
ecosystem authors' work without having realized it: the logbook plugin we
adopted, the Victron plugin on our eval list, the radar server we assessed.
A prior-art scan doubles as a map of whose work you depend on, which is
exactly who you should be talking to, contributing back to, and crediting.

The lesson, operationalized

The scan cost one evening of agent-assisted searching across GitHub topics,
the SignalK plugin registry, and the MCP directories. In a sparse niche it
still: flagged one should-have-assessed project, killed one adoption on
licensing, mapped a peer's opposite architecture, and revealed three upstream
dependencies we hadn't consciously chosen.

So it's now a checklist step, not a retrospective:

New build domain?
1. Scan first: GitHub topic search + MCP directories + the
   SignalK plugin registry (appstore), BEFORE the design doc.
2. For each hit: license, last commit, maintainer posture,
   philosophy fit (operational vs informational).
3. Record the verdict per alternative — adopt / borrow the
   design / pattern-reference-only / novel, with reasons.
4. Re-run the audit when you know the ecosystem better.
   (Verdicts age: one "stalled" project on our June map
   shipped new releases within a month.)

Step 3 is the part that compounds: the recorded verdicts are what let us
answer "how much did we rebuild?" with a table instead of a feeling — and
they're what this post is made of.

Everything above ships from github.com/sailingnaturali,
built for an all-electric sailboat's agent stack — if you're building in the
marine-MCP space, the map says there's plenty of open water.

Two tidal libraries disagreed: diff their internals, not their outputs

Bryan Clark — Tue, 21 Jul 2026 13:37:24 +0000

Two tide libraries gave different answers and bisecting by ablation found nothing, because the difference was spread thin across a dozen small terms. Both libraries expose their own per-constituent astronomical argument and nodal factors — comparing those instead of the predictions localized it in one probe. Jump to the fix. Second lesson, nearly as valuable: ask which regime your discrepancy was measured in. Ours was measured without re-fitting, and the shipped pipeline re-fits, which made the headline number 4x too scary.

I have a small tool, chs-constituents, that fits tidal-current harmonic constituents from Canadian Hydrographic Service published predictions so a chartplotter or SignalK server can predict currents offline. It started in Python on utide. I ported it to TypeScript on @neaps/tide-predictor, kept the Python running alongside as an oracle, and validated one against the other before deleting the Python.

Most of the port validated clean. One number would not.

Problem

Nineteen Salish Sea current stations, a 180-day training window, validated out-of-sample against CHS's own published events for the following week. Both implementations got byte-identical input samples, so any difference is the fit, not the fetch.

Extremum timing — peak flood, peak ebb — came out at parity everywhere. Worst difference in either direction was 1.0 minute, which is the resolution of the measure.

Slack did not. Median absolute slack-timing error against ground truth, minutes:

station              TS (neaps)   Python (utide)
Juan de Fuca East          17.7              9.5
Race Passage                8.1              5.5

Slack water is where a current prediction earns its keep — it's the number you plan a transit around. Two stations, both weak and slow-reversing, both worse in the port.

Two hypotheses died fast:

mean/offset term  → agrees to 4 decimal places at every station. Not it.
basis degeneracy  → refit both at 240 days (clears more Rayleigh pairs).
                    Gap unchanged. Not it.

That leaves the synthesis engine itself. To prove it, feed the Python's own fitted constituents through neaps' synthesis and compare against the Python's own predicted events. Now nothing differs except the engine:

median slack difference, utide constituents → neaps synthesis
  Juan de Fuca East   24.6 min
  Tillicum Bridge      8.1 min
  Race Passage         5.0 min
  everywhere else     < 2.5 min
  extrema             ≤ 6 min throughout

24.6 minutes between two respectable open-source tide engines given the same constituents. Which one is wrong, and where?

What I tried, and why it failed

The obvious move is to bisect: the disagreement lives in some constituent, so drop them one at a time and watch the number move.

Juan de Fuca East, median slack difference after dropping one constituent

  baseline (all)   24.6 min
  drop K2          19.4 min   ← largest single effect
  drop 2N2         ~22   min
  drop M3          ~22   min
  drop MU2, MSF, MF, J1, T2 each moved it by less than 5 min

Nothing is guilty. K2 is the biggest single contributor and removing it entirely accounts for a fifth of the gap. There is no culprit constituent because there is no culprit constituent — the disagreement is spread across 2N2, M2, MM, J1 and N2 with no dominant term.

This is the failure mode worth naming. Ablation is a bisection, and bisection assumes the thing you're hunting is localized. When a discrepancy is a sum of many small contributions, every removal moves the number a little and nothing ever looks responsible. You can run that loop for a long time and learn only that you've run it.

I also had two known convention differences on file and neither explained the magnitude alone:

utide encodes M3's 180° offset as semi=-0.5; neaps encodes it as an extended-Doodson digit 7.
2N2 phase differed by a consistent ~5°.

Two suspicious details, one dead-end search, and a 24.6-minute number nobody could source.

The fix

Stop comparing outputs. Compare internals.

A tide engine's prediction is a sum over constituents of

v(t) = Z0 + SUM_j  f_j(t) * A_j * cos( w_j*t + V0_j + u_j(t) - phi_j )

A and phi are fitted. Everything else — the speed w, the equilibrium/astronomical argument V0, and the nodal correction pair f (amplitude factor) and u (phase offset) — is astronomy the library computes for you. Both libraries expose all of it. So instead of diffing 24.6 minutes of predicted slack, diff the four intermediate values, per constituent, at one instant.

neaps side — constituents[name].value(astro(t)) gives V in degrees, .correction(astro(t)) gives {f, u}:

import { astro, constituents } from "@neaps/tide-predictor";

const NAMES = ["M2", "S2", "N2", "2N2", "MU2", "NU2", "K2", "T2",
               "K1", "O1", "P1", "Q1", "J1", "M3", "MM", "MSF", "MF"];

const t = new Date("2025-12-28T00:00:00Z");
const a = astro(t);

for (const name of NAMES) {
  const c = constituents[name];
  const { f, u } = c.correction(a);
  console.log([
    name,
    c.speed.toFixed(7),        // deg/hour
    c.value(a).toFixed(4),     // V, degrees
    f.toFixed(6),
    u.toFixed(4),              // degrees
  ].join("\t"));
}

utide side — FUV returns all three at once. Note the units: utide returns U and V in cycles, and freq in cycles/hour, so multiply by 360 to land in neaps' degrees:

from datetime import datetime, timezone

import numpy as np
from utide import ut_constants
from utide.harmonics import FUV

NAMES = ["M2", "S2", "N2", "2N2", "MU2", "NU2", "K2", "T2",
         "K1", "O1", "P1", "Q1", "J1", "M3", "MM", "MSF", "MF"]

table = [n.strip() for n in ut_constants.const.name]
lind = np.array([table.index(n) for n in NAMES])


def datenum(d):
    """utide counts days from the proleptic year 0.

    Do NOT reach for matplotlib.dates.date2num here — it changed epoch in
    matplotlib 3.3 and now returns days since 1970-01-01, which is 719163
    days short. FUV accepts it happily and prints a plausible, entirely
    wrong table.
    """
    return d.toordinal() + (d.hour * 3600 + d.minute * 60 + d.second) / 86400.0


t = np.array([datenum(datetime(2025, 12, 28, tzinfo=timezone.utc))])
# ngflgs = [nodsatlint, nodsatnone, gwchlint, gwchnone] — all zero means
# exact nodal/satellite corrections and exact Greenwich phase, no shortcuts.
F, U, V = FUV(t, t[0], lind, 48.5, [0, 0, 0, 0])

for i, name in enumerate(NAMES):
    print("\t".join([
        name,
        f"{ut_constants.const.freq[lind[i]] * 360:.7f}",  # deg/hour
        f"{V[0, i] * 360:.4f}",                           # V, degrees
        f"{F[0, i]:.6f}",
        f"{U[0, i] * 360:.4f}",                           # u, degrees
    ]))

Validate the mapping before you trust the diff. The first run produced utide values that looked wrong, and the honest first question is not "which library is broken" but "is my comparison harness lining up the same waves?" A name-keyed lookup across two independent constituent tables is exactly the place an off-by-one index bug hides, and it will happily produce a beautiful, entirely fictional disagreement. So check identity by a quantity that doesn't depend on your mapping being right — frequency:

speed match, neaps vs utide, all 17 constituents:  <= 1e-7 deg/hour

Same waves. Now the diff means something — and the frequency match doubles as a check on the unit conversion, since a wrong factor on utide's cycles would have thrown the speeds off by exactly that factor.

Diagnosis

Three findings, in the order they landed.

1. It is not the astronomical argument. V agrees between the engines to 0.00° on every constituent in the basis. The single exception is M3's known 180° offset, which lives in V, not u. Whatever the 24.6 minutes is, the two libraries agree exactly on where the sun and moon are.

2. It is not the linear-phase shortcut either — a hypothesis the original ablation never got around to testing. neaps evaluates V once at the start of the series and carries phase forward as V0 + wt rather than re-evaluating the astronomy at every sample. That's an approximation, and approximations are suspects. So check whether neaps' own tabulated speed actually equals the time derivative of its own value():

d/dt value()  vs  tabulated speed:       agree to ~1e-8 deg/hour
accumulated phase drift over 187 days:   < 0.0002 deg, every constituent

Sound. Testing a hypothesis and clearing it is real progress even though it moves no numbers — it permanently removes a thing you'd otherwise keep circling back to.

3. It is the nodal corrections, and it is a convention difference, not a bug in either library. The nodal pair f/u corrects for the 18.6-year regression of the lunar nodes, and there are two schools:

neaps applies grouped factors: it groups constituents by their IHO Annex B nodal-correction code, and constituents sharing a code share f/u exactly — M2, N2, 2N2, MU2 and NU2 agree to nine decimal places. O1 and Q1 share another code.
utide applies Foreman's satellite-derived per-constituent factors, where each constituent gets its own, derived from the satellite lines around each main line.

The largest split:

constituent     f (neaps)     f (utide)     utide vs neaps
2N2             0.965         1.110         +15%   (+ ~3.6 deg in u)

utide's 2N2 nodal factor comes out 15% higher than neaps'.

These are also the values at one instant — 2025-12-28, the validation-window date both probes above use. f and u are not constants; they track the 18.6-year regression of the lunar nodes, which is the entire reason they exist. Evaluate the same comparison six months earlier and 2N2 reads 0.964 against 1.075, +11.5% rather than +15%. So pin your date when you quote a nodal factor, and pin the same date on both sides of a cross-library comparison — otherwise you are diffing the calendar, not the libraries.

neaps' 0.965 for 2N2 is just M2's value, because in the grouped scheme 2N2 is in M2's group. utide computes 2N2's own. Neither is wrong: grouping is the classical approximation — the tradition Schureman codified and the one IHO's tables carry forward — and satellite-Foreman is the refined one. (Historical nicety for anyone in these waters: Foreman's manual came out of the Institute of Ocean Sciences at Patricia Bay, which is about ten miles from the stations that surfaced this.)

And that is exactly why the ablation was doomed. The disagreement is a grouped-vs-per-constituent scheme difference, so it touches every constituent whose group has structure — a little bit each, no dominant term, nothing to bisect onto.

One asymmetry does look like a genuine gap rather than a convention: utide returns f = 1.0 and u = 0.0 exactly for MM, MSF and MF — no nodal correction at all on the long-period constituents, where neaps applies real factors. That is the one place I'd say neaps is more likely correct. It barely matters for currents, where those amplitudes are small.

Check the default before you blame the library

Be careful with the label here, because I nearly got it wrong in a way that would have been quietly wrong forever.

neaps ships two fundamentals sets, iho and schureman, and they are selectable:

createTidePredictor(constituents, { nodeCorrections: "schureman" });

The default is iho — correction(astro, fundamentals = ...) resolves to the IHO set for any falsy argument — and iho is what the fit path and every number above actually used. I had originally written this up as "neaps applies Schureman factors," which is a reasonable guess from the fact that a schureman export exists, and it is wrong.

It matters, because the two sets are not interchangeable:

switching neaps from iho to schureman
  J1   moves 7.2%
  MF   moves 5.5%

Sit that next to the thing this whole post is about. J1 differs by 7.2% between neaps' own two modes, against 1.5% between neaps and utide. The intra-library spread is wider than the inter-library spread I spent a day characterizing. "Which nodal convention" turns out to be a bigger lever than "which library" — and if you attribute a discrepancy to a library without checking which convention it defaulted to, you can produce a confident, well-measured, completely misattributed finding.

The only reason I caught it is that the default was spelled out in the type signature. Read it.

The regime question — and why 24.6 minutes was 4x too scary

Here's the part that changed the verdict.

The 24.6-minute figure was measured by feeding utide's constituents into neaps' synthesis. Nothing is re-fitted in that setup, so the entire f/u disagreement lands directly in the output.

The shipped pipeline does not work that way. It fits and synthesizes in neaps. A least-squares fit solves for amplitude and phase against the same f/u the synthesis will later apply — so any constant offset in f/u is absorbed into the fitted A and phi and cancels exactly. What survives is only the drift in f/u across the training-to-validation span.

Weighted by fitted amplitude at Dodd Narrows:

raw cross-engine  (the regime 24.6 min was measured in)   2.9%  of M2
post-fit residual (the regime that actually ships)        0.72% of M2

0.72% of M2 is roughly 0.85 minutes at an ordinary zero crossing. Multiply by the ~7x amplification a slow reversal gives — a weak, lazily-reversing station spends a long time near zero, so a small velocity error moves the crossing a long way in time — and you land on the 8.2-minute slack gap actually observed at Juan de Fuca East. Mechanism and magnitude both check out, and the headline number overstated the shipped impact by about 4x.

Same logic retires M3. Its scary-looking 180° convention difference drifts by 0.03° over the span — it is constant, so the fit absorbs it completely. Pure bookkeeping, zero effect on output.

Verdict: not worth fixing. The residual sits below the CHS validation floor and neither engine wins against ground truth — utide is closer at Juan de Fuca East and Race Passage, neaps is closer at Blackney, Tillicum, Sechelt and Hole in the Wall. Adopting Foreman factors in neaps would be real work with no evidence it improves anything. The whole stack is neaps-based, so agreeing with neaps is the more useful consistency. The characterization goes upstream as a documentation note, not a defect report.

Why it matters

Five transferable pieces, none of them about tides.

1. Ablation cannot find a distributed cause. Dropping one input at a time is a bisection, and bisection needs the target to be localized. If the true cause is a scheme-level difference touching many terms, ablation returns a flat, uninformative gradient — every removal moves the number a little, nothing is guilty, and you conclude "no single X explains it" without ever learning what does. Recognize that flat gradient as a signal, not a stalemate: it's telling you to stop bisecting.

2. When two implementations disagree, diff their intermediates. Both of these libraries expose their internal astronomy. Comparing V, f and u took one probe and split the problem into "identical" and "the entire difference is here" in a single step, after the output-space search had run out of ideas. Almost any pair of libraries computing the same thing has this surface — parsers expose tokens, ML frameworks expose layer activations, numeric code exposes every stage. Diffing outputs tells you that you disagree; diffing intermediates tells you where.

3. Validate the identity mapping before trusting a cross-library comparison. A name-to-index lookup between two independent tables is a great place for a silent bug, and it produces a diff that looks like a real finding. Verify with something the mapping can't fake — here, matching frequencies to 1e-7 °/h.

4. Check which convention your library defaulted to before blaming the library. neaps' own two nodal sets differ by more on J1 (7.2%) than neaps and utide differ (1.5%). A library is not one implementation — it's a default plus a set of options, and "library A disagrees with library B" is only meaningful once you know which mode each one was in. The default is usually right there in the type signature.

5. Ask which regime your number was measured in. A difference measured in an artificial setup is not the difference your users see if the shipped path is different. Ours was measured with no re-fitting; the pipeline re-fits, and a fit absorbs any constant offset in a correction factor. That distinction was worth a 4x correction to the severity, and it's the difference between "chase this for a week" and "document it and move on."

One practical bonus: the event-comparison harness that produced the 24.6 minutes can never live in that repo, because it needs CHS-derived data and the CHS licence forbids redistributing it. The f/u probe above has that property inverted — it uses no station data at all, only the two libraries' own astronomy. Both snippets run standalone. That's a nice general property of internals-diffing: it's usually cheaper to reproduce and share than the output comparison it replaces.

I'm building an all-electric charter catamaran's software stack in the open, and offline current prediction for the Salish Sea's tidal gates is a piece of it — the pipeline is chs-constituents, and the SignalK plugin that consumes it is signalk-currents.

References: Schureman, Manual of Harmonic Analysis and Prediction of Tides, Special Publication 98 (1958) · Foreman, Manual for Tidal Heights Analysis and Prediction, Pacific Marine Science Report 77-10 · UTide (Python) · neaps

The commented-out code was a to-do, not a bug: finishing waves in SignalK's Open-Meteo plugin

Bryan Clark — Thu, 16 Jul 2026 16:04:24 +0000

Our boat's weather comes from a chain we didn't fully own. Open-Meteo
serves a free forecast; the SignalK Open-Meteo provider plugin
pulls it into the boat's own weather API at /signalk/v2/api/weather/forecasts/point;
and our weather-mcp reads that — so the
voice agent gets sea state from the boat's canonical weather surface instead of every tool
hitting the internet on its own.

Except the sea state never arrived.

A consumer with nothing to consume

weather-mcp has a signalk provider whose whole job is to map the SignalK weather response
into our forecast model. It was written to read the water block:

water = wd.get("water") or {}
# ...
swell=_wave(water, "swellHeight", "swellDirection", "swellPeriod"),
combined_wave=_wave(water, "waveSignificantHeight", "waveDirection", "wavePeriod"),

That or {} is doing a lot of quiet work. Every forecast hour came back with no water key
at all, so the map produced None for every wave field, and the provider dutifully reported
a forecast with wind and pressure but no waves. No error, no warning — just a hole shaped
exactly like the data we wanted.

The hole wasn't in our code. It was upstream: the plugin's getForecasts returned wind and
atmospheric fields only. The WeatherData.water fields were never populated. We had built
the consumer before the producer existed.

Chesterton's fence: why was the marine code commented out?

The obvious move when you find the gap is to fork the plugin and add the marine fetch. The
less obvious — and correct — move is to ask why it isn't there already.

It turned out the plumbing mostly was there: getMarineUrl existed, and a water.*
mapping sat in the source, commented out. Easy to read that as "broken, disabled in a
hurry." Git history said otherwise. The marine URL builder had been fleshed out in a later
commit, but the fetch, merge, and mapping around it were never wired — the marine path was
unfinished from the initial scaffold, not broken and switched off. That distinction
changes everything: there was no regression to be careful around, just a to-do someone left
in the open.

The history surfaced one real constraint, though. Open-Meteo is free and rate-limited, and
the plugin already carried scars from request-throttling —
caching and request frequency were live concerns, not hypotheticals. Reintroducing a second
network call per forecast naively was exactly the kind of thing that fence was guarding
against. Knowing that shaped the fix.

Finishing it

The PR is one file and three
moves:

Merge the marine series. Open-Meteo serves marine data from a separate subdomain
(marine-api.open-meteo.com, distinct from api.open-meteo.com). We fetch it inside the
same cache-miss path as the atmospheric forecast, so it's cached alongside it — one more
request per cache miss, not per call, which is the number the throttling history actually
cares about. And the marine fetch is optional: if it fails, the catch degrades to a
wind-and-atmospheric forecast rather than failing the whole response. A boat with no wave
data is fine; a boat with no forecast is not.

Fix the units the draft got wrong. The commented-out mapping multiplied wave periods by

SignalK is an SI data model — periods are seconds, not milliseconds. The disabled draft would have reported every swell period off by three orders of magnitude. This is the case for finishing commented code rather than just uncommenting it: the draft wasn't correct-but-disabled, it was a sketch.

Align the horizon. The marine query defaulted to 8 hours; the hourly forecast defaults to

We bumped the marine default to match, so waves cover the same window as the wind.

Verified live against Boundary Pass — every forecast hour now carries water:

{"waveSignificantHeight":0.28,"waveDirection":4.05,"wavePeriod":3.55,
 "swellHeight":0.24,"swellDirection":3.72,"swellPeriod":2.9}

One caveat we documented rather than fought: the SignalK water spec carries combined
significant-wave height and swell, but no separate wind-wave component. Open-Meteo's
marine API has it; the SignalK surface has nowhere to put it. So a forecast sourced through
SignalK reports combined-plus-swell, and our provider sets wind_wave to None on that
path. A consumer that needs the wind-wave split goes direct to Open-Meteo. That's a spec
limit, not a bug, and the right place for it is a comment in the mapper.

The payoff: the loop closed without a fork

The moment the PR merged, nothing in our codebase changed — and the thing we wanted started
working. weather-mcp's SignalK provider had been reading water.* all along; the upstream
plugin simply started putting data there. The producer and the consumer live in different
GitHub orgs, maintained by different people, and they met at a documented API contract.

This is the adopt-before-build rule playing out at the
seam. We could have forked the plugin, or added a private marine fetch to weather-mcp and
duplicated what Open-Meteo's plugin almost did. Either would have worked and both would have
been ours to carry forever. Instead the gap got filled where it belonged — in the shared
plugin every SignalK boat installs — and our side stayed a thin reader of a standard API.

The cost was reading enough history to know the fence was a to-do and not a load-bearing
wall. That's most of the work in contributing upstream: not the diff, but earning the right
to make it.

Your remote coding agent has the repo, not the machine — Tailscale is the missing half

Bryan Clark — Sat, 11 Jul 2026 16:04:55 +0000

You can now run a coding agent as a remote session — a cloud sandbox that clones your repo, edits across every package, runs the tests, and opens the PR, all driven from a phone app while you're nowhere near a desk. It's genuinely good. Then you ask it to show you the proof-of-concept actually running, and nothing happens.

That's not a bug. The session has your repo. It never had your machine. The repo is portable — it travels into any sandbox as a git clone. The running system — your dev server on localhost, the service on your LAN, the device behind your home router — does not. Most of the time the repo is all the agent needs. The exception is the one that matters: anything you want to look at running.

This is framework-general. It applies to any cloud-hosted agent session — Claude Code remote sessions, cloud dev environments, an agent in a CI runner. The shape is always the same: portable code, stranded runtime.

Problem

Our org is ~20 repos — SignalK plugins, MCP servers, Home Assistant config, the web app. A remote session anchored at the top-level repo, with a workspace CLAUDE.md that the sibling repos inherit, gives the agent cross-repo context for free. Reading, refactoring, testing, PRs — none of that needs anything but the code. It works beautifully from the dock.

Then the work produces something you have to see:

a web POC whose dev server you actually want to click through
a live service to hit — in our case the boat's SignalK server on the Pi, plus Home Assistant
anything bound to localhost on the real box

The cloud sandbox can reach none of it. The Pi is the sharp version: it sits behind Starlink, which is CGNAT — there is no inbound route to it from the public internet at all. But even the Studio in the next room is unreachable from a sandbox that only has your source tree. Different distances, same wall.

The two planes

The fix starts as a naming exercise. Stop treating "the work" as one thing. There are two planes:

Driving the work — repo-bounded, runs anywhere. Phone app, cloud session, no machine required.
The running system — a real host plus its network. The dev server, the LAN service, the device.

The remote agent owns plane 1 completely. Plane 2 needs an actual box. The mistake is expecting the cloud session to deliver both — it structurally can't, and editing prompts won't change that. What you need is a path from where you are back to the machine that runs things.

The bridge

A per-host tailnet puts the real machines and your phone on one private network. No subnet routes, no public exposure, no port-forwarding — each host joins individually and gets a stable address and a MagicDNS name:

$ tailscale status
100.126.222.111  studio         clarkbw@  macOS  -
100.104.78.15    homeassistant  clarkbw@  linux  -
100.92.194.27    iphone181      clarkbw@  iOS    -
100.115.37.115   naturalaspi    clarkbw@  linux  -

Now the POC runs on the real machine — the Studio — and you reach it from the phone. Bind the dev server to all interfaces and hit the MagicDNS name:

# on the Studio
$ python3 -m http.server 8911 --bind 0.0.0.0

# from the phone (or anywhere on the tailnet)
$ curl http://studio.tailb19444.ts.net:8911/
<h1>POC reachable over the tailnet</h1>

That's the whole trick. The cloud session does the repo work and lands the branch; the Studio runs it; the tailnet carries the one hop from your phone to the running thing. Same tunnel reaches naturalaspi — the SignalK server the public internet can't touch — because to the tailnet, CGNAT isn't there. The boat being unreachable from the outside was never a special case; it's just the most extreme point on the same line, and the bridge that fixes the Studio fixes the boat too.

Why anchor at the org repo

One detail makes the remote half pull its weight: anchor the session at the top-level org repo, not an individual package. A workspace CLAUDE.md there — inherited by every sibling via a symlink — means one session reasons across all ~20 repos instead of one. The agent that just edited a plugin already knows where the MCP server and the HA config live. Without the anchor you're back to one-repo-at-a-time, and the remote session stops being worth driving from a phone.

Takeaway

A remote coding agent is two things welded together, and it only ships one of them to the cloud. Give it the repo and a tunnel home — anchor the session at the org repo so it spans everything, and put your machines plus your phone on a tailnet so "go look at it running" is one hop away. Do both and dev-from-the-dock stops being a demo. Do only the first and you'll keep hitting the wall where the code is right there and the running system is nowhere.

DEV Community: Bryan Clark

MCP server or a curl recipe in AGENTS.md? Measure the breakeven

Two ways to let an agent read a boat

Round 1 — standing cost, the part everyone measures

Round 2 — the part the benchmarks skip

The breakeven formula

Prompt caching moves k*, and I measured by how much

The half that tokens don't measure

What the prose recipe is really asking for

Caveats, before you quote my numbers

Where it lands

A persistent-queue HTTP reporter for distress traffic over flaky internet

Why this matters for safety at sea

The naive versions, and why each one fails

Write-through, not batching

The response policy: what each HTTP answer means

Surviving restarts: reload, torn lines, and the trim

The bug that shipped in v0.5.0: the stale-flusher restart race

Fetch timeouts: a black-holed link must not wedge the flusher

Tests pin the policy, not the implementation

Gotchas if you build one of these

Close

Offline tidal currents from harmonic constituents — and when not to trust them

Problem

What we tried (and why it failed)

The build

A tide-height engine, repurposed for currents

Bundling the constituents

Aligning the horizon with the live path

Selection: live wins, fallback declares itself

Why harmonic predictions fall short at constricted passes

Measure the fallback while you still have ground truth

Gotchas

Close

Running OpenClaw on a Raspberry Pi alongside SignalK

The build

Gotchas first

1. The gateway won't start without gateway.mode

2. SignalK values are SI — the agent must convert

3. No history without InfluxDB

4. jq isn't installed by default

5. Chesterton's fence — the ollama plugin does more than you think

The walkthrough

Install (native)

Telegram

Reading SignalK over HTTP — no MCP needed

Tuning finding 1 — skill vs the agent file

Tuning finding 2 — cutting the ~14k standing prompt

What worked — the tool profile

What did NOT work — disabling plugins

The real lever — caching, not token count

Bonus — a watch that stays quiet

Close

httpx async requests to a .local hostname time out on macOS

Problem

Diagnosis

What we tried (and why it failed)

The fix

One fix, five repos: when a patch becomes a library

Why it matters / gotchas

Close

Where a received distress call belongs in the SignalK data model

The problem: notifications.* on self means "something is wrong with MY boat"

What we considered

The convention: two writes

Why those leaves

Two more beats from the same release train

The shape of it

When AI agents write the ship's log, record who wrote what

Problem

Designs we rejected

The design

Forward-compatible rollout

Upstream: PR #88

Consumer side: deriving origin in the MCP server

Voice attribution: assume, confirm, correct

Why it matters / gotchas

Two false walls in NOAA's currents API: empty constituents and "not available"

Plan A, and why it wasn't Plan A for long

Wall 1: "NOAA doesn't publish current constituents"

1. The gateway won't start without `gateway.mode`

4. `jq` isn't installed by default

5. Chesterton's fence — the `ollama` plugin does more than you think

The problem: `notifications.*` on self means "something is wrong with MY boat"