DEV Community: Bryan Clark

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.

Monitor the delivery path, not just the alarm

Bryan Clark — Thu, 09 Jul 2026 04:50:48 +0000

We built a zero-dependency SignalK→ntfy relay so a man-overboard, low-battery, or depth alarm reaches a phone even when nobody's at the chartplotter. It worked. Then, a month later, it silently stopped working, and we found out by accident — while smoke-testing an entirely different plugin, this line scrolled past in the SignalK server log:

ntfy responded 401

Every alarm the relay had tried to push was getting a 401 Unauthorized from ntfy and evaporating. The alarm-to-phone path had been dark for who-knows-how-long, and nothing had told us. On a boat, "your emergency notifications quietly stopped delivering" is the exact failure you cannot afford to discover during the emergency.

This is the broke → tried → fixed of a blind spot that isn't marine at all: you monitor the thing, but not the pipe that tells you about the thing. Anyone running a self-hosted alert pipeline — ntfy, Gotify, Pushover, Home Assistant notifications, a PagerDuty webhook — has the same hole.

The problem: a failure with nothing to fail

Here's the whole chain:

SignalK notification  →  signalk-ntfy-relay  →  ntfy  →  phone

The relay's send path is a fire-and-forget POST. By design it never throws — one bad push must not stall the next alarm — so a non-2xx response just gets logged:

const req = lib.request(u, { method: 'POST', headers }, (res) => {
  res.resume(); // drain
  if (res.statusCode >= 300) app.error(`ntfy responded ${res.statusCode}`);
});

That log line is the entire failure signal. And nothing consumes it.

Now sit with the nastiest property of this failure mode: the relay only sends when an alarm fires. A boat at anchor on a calm night fires no alarms, so there are no sends, so there is nothing to fail, so the broken path stays perfectly invisible. An expired token isn't discovered until the next real MOB or EPIRB event tries to deliver — which is precisely the moment you needed it to already be working.

A per-send failure log is not monitoring. It's a receipt for a delivery that already didn't happen, filed in a drawer nobody opens.

Diagnosis: isolate the leg that's failing

A 401 could be a lot of things — wrong topic, a publish-path bug, a reverse proxy eating the Authorization header (a common ntfy 401 cause). We wanted to isolate it to one leg without firing a fake MOB every time. ntfy has a read-only account endpoint, so a token-only probe answers "is the token still good?" with zero side effects:

$ curl -s -o /dev/null -w '%{http_code}\n' \
    -H "Authorization: Bearer tk_..." https://ntfy.sh/v1/account
401

401 on a bare GET /v1/account — no topic, no publish, no message body involved. That isolates it cleanly: not the topic, not the relay's publish code, the token itself. ntfy.sh account tokens can carry an expiry, and this one had lapsed. Our topic is reserved, so publishing to it requires a valid token — an expired token means every publish is a 401, forever, until someone notices.

Root cause found. But the root cause was never the interesting part. The interesting part is that a token expiring is a totally ordinary event, and our system's response to it was silence.

What we tried first (and why it wasn't enough)

Attempt 1 — just mint a non-expiring token. ntfy lets you create a token that never expires:

$ curl -s -X POST -H "Authorization: Bearer tk_old..." \
    -H "Content-Type: application/json" \
    -d '{"label":"signalk-relay","expires":0}' \
    https://ntfy.sh/v1/account/token

This removes the most likely cause, and it's worth doing — prefer eliminating a failure mode over monitoring it. But it's not a fix for the blind spot. A token can still be revoked, an ACL can change, ntfy.sh can have an outage, DNS can break. Every one of those reproduces the exact same silent-dark path. Removing the top cause narrows the hole; it doesn't close it.

Attempt 2 — alarm on the first failed send. Tempting, but wrong. Auth failures are permanent, but a lot of send failures are transient — a dropped connection, a 5-second timeout, a momentary ntfy hiccup. Alarming on the first blip would cry wolf constantly on a marine link that drops all the time. The signal we actually want is sustained failure, not one bad POST.

Neither attempt gives the system its own pulse. That's the real requirement: the notification pipeline needs a health check separate from the events it carries.

The fix: a delivery-path health check inside the relay

Two mechanisms, one shared counter. Both live in the relay itself — no external watchdog service to also keep alive.

Proactive heartbeat. On an interval (default 24h), probe the path even when no alarms are firing. This is the piece that catches an expired token between alarms, on the quiet night before the emergency:

// Read-only auth/reachability probe: GET {server}/v1/account.
// Catches an expired/revoked token (or an unreachable server) proactively,
// before a real alarm needs the path. Never throws.
function defaultCheckAccount({ server, token }, app, cb) {
  const u = new URL(`${(server || 'https://ntfy.sh').replace(/\/+$/, '')}/v1/account`);
  const lib = u.protocol === 'http:' ? http : https;
  const headers = token ? { Authorization: `Bearer ${token}` } : {};
  const req = lib.request(u, { method: 'GET', headers }, (res) => {
    res.resume();
    cb(res.statusCode >= 200 && res.statusCode < 300, res.statusCode);
  });
  req.on('error', (e) => { app.error(`ntfy account check failed: ${e.message}`); cb(false); });
  req.setTimeout(5000, () => req.destroy(new Error('ntfy account check timeout')));
  req.end();
}

Reactive counting. Every real send now reports its outcome, and consecutive failures accumulate. Both paths feed one function that alarms only past a threshold (default 3) — riding out the transient blips that killed attempt 2:

// A run of `failureThreshold` consecutive failures raises the delivery-path
// alarm; any success resets and clears it.
function recordResult(ok, detail) {
  if (ok) {
    consecutiveFailures = 0;
    if (deliveryFailedRaised) { deliveryFailedRaised = false; setDeliveryFailed(false); }
    return;
  }
  consecutiveFailures += 1;
  if (consecutiveFailures >= failureThreshold && !deliveryFailedRaised) {
    deliveryFailedRaised = true;
    setDeliveryFailed(true, detail);
  }
}

Where the alarm surfaces is the whole point. It must not go out through the very path that's broken — pushing "the push path is down" to the down phone is a no-op. So the relay raises it as a SignalK notification under its own name:

const DELIVERY_FAILED_PATH = 'notifications.ntfyRelay.deliveryFailed';

function setDeliveryFailed(active, detail) {
  app.handleMessage(plugin.id, {
    updates: [{ values: [{ path: DELIVERY_FAILED_PATH, value: active
      ? { state: 'alert', method: ['visual'],
          message: `ntfy delivery path failing${detail ? ` (${detail})` : ''} — alarms are not reaching the phone`,
          timestamp: new Date().toISOString() }
      : { state: 'normal', method: [], message: '' } }] }],
  });
}

That lands on the SignalK dashboard and our voice pipeline — channels independent of the phone that's down. And it carries one deliberate exclusion: the relay subscribes to notifications.*, so its own delivery-failed notification would otherwise get forwarded straight back to the failing ntfy path. Drop it:

// Never forward our own delivery-path alarm — it must not loop through the
// failing ntfy path (it surfaces via the dashboard/voice instead).
if (path.startsWith('ntfyRelay.')) return;

Test-first, as always — four failing tests before any of this existed (threshold behaviour, clear-on-success + counter reset, loop-avoidance, reactive counting):

✔ health check raises deliveryFailed only after failureThreshold consecutive failures
✔ a success clears deliveryFailed and resets the failure counter
✔ the deliveryFailed notification is never forwarded to ntfy (loop-avoidance)
✔ reactive send failures count toward the deliveryFailed threshold

Shipped in signalk-ntfy-relay v0.2.0, two new config knobs, both with safe defaults:

healthCheckIntervalHours   24   Proactively probe /v1/account; 0 disables. Token-only.
failureThreshold            3   Consecutive failures before raising the delivery-path alarm.

We also added a small diagnostics CLI, scripts/ntfy-doctor.js, so the path can be verified on demand instead of waiting for a real alarm — check (the /v1/account probe), test (publish + poll to confirm end-to-end delivery), poll, mint, and revoke:

$ node scripts/ntfy-doctor.js check --config .../signalk-ntfy-relay.json
/v1/account: 401
✗ token invalid/expired/revoked — mint a new one on ntfy.sh

Why it matters / gotchas

A signal nobody consumes is not monitoring. app.error('ntfy responded 401') felt like we'd "handled" the failure. We hadn't — we'd written it down. If no code path acts on a failure log, the failure is silent no matter how loudly it's logged. This is the Watchdog / dead-man's-switch pattern that Prometheus/Alertmanager users know well ("who watches the watcher?") — the twist is applying it to the outbound leg, and doing it inside the relay rather than bolting on a second service you'd also have to keep alive.
Absence of failure is not proof of health. The trap specific to alert pipelines: they're exercised only when something's already wrong. A quiet week generates zero sends, so zero failures, so a false all-clear. That's why the proactive heartbeat matters more than the reactive counter — it manufactures traffic on purpose, so the path is exercised on the calm night, not for the first time during the MOB.
Alarm on a threshold, not the first failure. Auth failures are permanent; network blips aren't. N consecutive failures rides out the transient and still catches the durable — a single knob (failureThreshold) that separates "the token expired" from "the wifi flickered."
Never route the health alarm through the failing path. Push "the push path is down" to the down phone and it goes nowhere. The delivery-failed signal has to surface on an independent channel — for us the dashboard and voice, for you maybe a log-scraper, a second provider, or an LED. And exclude it from the pipe it describes, or it loops.
Prefer removing the failure mode over monitoring it — then monitor the rest. The non-expiring token deletes the single likeliest cause outright. The health check then covers the long tail nothing can pre-empt: revocation, ACL change, provider outage. Belt and suspenders, in that order.

The general shape, provider-agnostic: any pipeline whose job is to tell you when something's wrong needs its own out-of-band pulse, because it is exercised only in the moment you most need it and least want to be discovering it's broken.

Close

This came from running the alerting layer of an all-electric charter catamaran, where a silently-dead man-overboard notification is worse than none at all — at least a missing feature is a known gap. The relay, the health check, and the ntfy-doctor CLI are open source: github.com/sailingnaturali/signalk-ntfy-relay.

MQTT value_template doesn't filter: our wait fired on every message

Bryan Clark — Mon, 06 Jul 2026 16:54:56 +0000

Liquid syntax error: Unknown tag 'endraw'

A hands-free npm publish pipeline for SignalK plugins

Bryan Clark — Tue, 30 Jun 2026 15:59:08 +0000

Publishing a SignalK plugin to npm once is easy: npm publish, type your OTP,
done. Keeping eight of them shipping hands-free — each one auto-published on a
tag, cross-tested on five platforms, and scoring 100 in the
SignalK plugin registry — is a
different problem, and it's the one we keep seeing people stall on. This is the
whole pipeline we run for the @sailingnaturali/* plugins, end to end.

A pipeline is two kinds of work

The useful lens, before any YAML: a publish pipeline is deterministic plumbing
plus judgment, and they want opposite tools.

The plumbing is mechanical. Given a git tag: check out, build, run the tests on
Linux/macOS/Windows, publish with provenance, no human in the loop. The inputs are
clean and the steps never vary. That belongs in CI — flat YAML, and no AI, ever.
Reaching for a model to do a job a Makefile can do is how you get a slower, less
reliable Makefile.

The other half is judgment. Is this change worth cutting a release? What actually
goes in the notes? The registry says 90 — which of the gaps matters, and is that
npm audit advisory a real ship-blocker or dev-only noise? Dependabot wants to bump
the CI pin to a "newer" tag — is that tag a trap? None of those reduce to a clean
rule over clean input. You can spend a week trying to encode "is this release-worthy"
as a deterministic check and still be wrong on the first weird case.

This is the same line we draw on the boat. Deterministic code reads the NMEA bus,
computes SignalK deltas, and fires the alarm chain — the inputs are structured and
the logic is fixed, so an LLM there would only add latency and failure modes. But
the moment the input is a human asking a fuzzy question, or a judgment call over
messy state, that's where the agent earns its place. Drive toward deterministic
code wherever the inputs let you; don't burn cycles forcing non-deterministic
judgment through deterministic code. Put the judgment behind a model, and make the
seam explicit.

In this pipeline the seam is a set of Claude Code skills. The deterministic half
lives in four workflow files. The judgment half lives in three skills that wrap those
workflows and supply the parts a YAML file can't.

The judgment half: three composable skills

We don't keep this workflow in a README that nobody re-reads. We keep it as three
skills, each doing one job, each invokable on demand
(they're public):

signalk-plugin — authoring + the publish decision: the @signalk/server-api patterns that actually work, the package scaffold, when a change warrants a release.
npm-oidc-publish — the OIDC trusted-publishing flow, including the new-package chicken-and-egg that has no deterministic shortcut.
signalk-registry — reads the plugin's live registry score, then judges which locally-fixable gaps to close before the next nightly re-test.

A skill is the right container precisely because each of these mixes a deterministic
core (a command to run, a file to write) with a judgment the model has to make
(should we, which one, is this advisory real). The deterministic core could be a
script; the judgment around it is why it's a skill and not a cron job.

Scaffold (and the `files` array that ships nothing)

Public repo, npm package, MIT, zero runtime deps where you can manage it. The one
that bites everyone:

{
  "name": "signalk-<name>",
  "files": ["index.js"],
  "keywords": ["signalk-node-server-plugin", "signalk-category-utility"],
  "license": "MIT"
}

If "files" is missing, the package ships nothing — your .gitignore excludes the
build output, and npm honours it. The signalk-node-server-plugin keyword is what
surfaces the package in the in-server App Store. For a TypeScript plugin, ship the
build with "files": ["dist"] and a "prepare": "npm run build" so npm publish
builds first; for a scoped package add "publishConfig": { "access": "public" }.

(One authoring trap worth its own note: serve plugin data via
app.registerResourceProvider, not registerWithRouter — the latter's
/plugins/<id>/* routes are admin-gated, so every reader would need a token. That, and
the rest of the @signalk/server-api patterns, is the signalk-plugin skill's job; the
DSC plugin post
shows it in anger.)

First publish: the chicken-and-egg

This is the step that has no deterministic shortcut, which is exactly why it lives in
a skill instead of a script. npm's trusted publishing lets a GitHub Actions workflow
npm publish with no NPM_TOKEN and no OTP — it authenticates over OIDC and stamps
provenance automatically. But you cannot configure a trusted publisher for a package
that doesn't exist on npm yet, and the OIDC publish needs that config to exist. So the
first publish of any new package is manual, once:

npm publish --otp=<code>     # creates 0.1.0, the only time you'll type an OTP

Then, on npmjs.com → the package → Settings → Trusted Publisher → GitHub Actions,
register the repo (owner/repo), the workflow filename (publish.yml), and leave
the environment blank. From here on it's hands-free.

The tell that this is misconfigured: the CI npm publish fails with ENEEDAUTH
("requires you to be logged in") while npm ci and npm test pass. That's never a code
problem — it means the trusted publisher isn't registered, or the workflow filename / repo
on npm doesn't match the one actually running.

OIDC: the publish workflow

.github/workflows/publish.yml — the entire deterministic half of publishing:

name: publish
on:
  release:
    types: [published]
permissions:
  contents: read
  id-token: write   # <- this line is what enables OIDC
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v6
        with:
          node-version: 24      # npm >= 11.5 supports OIDC; node 24 is safe
      - run: npm ci             # needs a committed package-lock.json
      - run: npm test
      - run: npm publish        # no token, no --otp; provenance is automatic

One gotcha that looks like a failure and isn't: after npm publish prints
+ <pkg>@<ver>, the npmjs.com website shows the release immediately, but the
registry API (npm view, registry.npmjs.org/<pkg>) can 404 for a few minutes —
worst for a scoped package's first publish. That's propagation, not a failed publish.
Trust the + <pkg>@<ver> line.

Continuous mode: the release is the trigger

With OIDC wired, shipping a new version is one deterministic command — no local build,
no token, no OTP:

gh release create v0.5.2 --notes "Set current directions from CHS metadata"

That release: published event fires publish.yml, which publishes over OIDC. Two
things fall out of doing it this way:

The GitHub Release doubles as the changelog. The registry docks −5 for a missing changelog, and it counts a release tagged v<version> as satisfying that — so the same gh release create that publishes the package also closes the changelog gap. One action, two boxes ticked.
Whether to cut the release, and what the notes say, is the judgment the signalk-plugin skill owns. The command is deterministic; the decision to run it is not.

The workflows that keep it honest

Three more files run on every push and PR — all deterministic, all in YAML.

test.yml is the ordinary CI gate:

name: test
on:
  push: { branches: [main] }
  pull_request:
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-node@v6
        with: { node-version: 20 }
      - run: npm ci
      - run: npm run build
      - run: npm test

plugin-ci.yml is the one most plugins skip, and it's worth real points. SignalK
publishes a reusable workflow that cross-tests your plugin on Linux x64/arm64,
macOS, Windows, and armv7/Venus OS (the Cerbo). Running it earns the registry's
plugin-ci credit — +10, and its absence is a flat −10, which alone caps an
otherwise-perfect plugin at 90:

name: SignalK Plugin CI
on:
  push: { branches: ['**'] }
  pull_request: { branches: ['**'] }
jobs:
  plugin-ci:
    uses: SignalK/signalk-server/.github/workflows/plugin-ci.yml@3645160b235364e1fd3afe1f2f6b2270b8194b7d # v2.28.0

Pin to a release commit SHA, never @master — supply-chain safety and
reproducibility. The trailing # v2.28.0 comment is how a human (or Dependabot) knows
what the SHA means.

Tracking updates without dragging in a dead tag

A pinned SHA is safe but it goes stale — when signalk-server cuts a release, your pin
silently falls behind. The deterministic fix is dependabot.yml, which opens a grouped
weekly PR to bump every action you pin, including the reusable workflow:

version: 2
updates:
  - package-ecosystem: github-actions
    directory: /
    schedule:
      interval: weekly
    groups:
      github-actions:
        patterns: ["*"]
    ignore:
      # signalk-server carries a stray ancient v6.6.6 tag (a 2019 commit with no
      # plugin-ci.yml) that outranks the real 2.x release line by semver, so
      # dependabot "upgrades" the reusable-workflow pin to a dead ref and the
      # workflow fails to load (0s failure). Ignore majors: the real releases are
      # 2.x minors, which dependabot still tracks; a genuine 3.0 we bump by hand.
      - dependency-name: "SignalK/signalk-server*"
        update-types: ["version-update:semver-major"]

That ignore block is the whole point of this section. signalk-server carries a stray
v6.6.6 tag — a 2019 commit, no plugin-ci.yml in it — that outranks the real
2.x release line by raw semver. Left alone, Dependabot helpfully "upgrades" your pin to
that dead ref, the reusable workflow can't be loaded, and CI fails in 0 seconds. Ignoring
the major bump keeps Dependabot tracking the real 2.x minors while refusing the trap;
a genuine 3.0 is rare enough to bump by hand. This is the kind of failure mode that's
obvious in hindsight and invisible up front — exactly what you want captured in a config
comment so nobody rediscovers it.

The score is a checkable bar, not a vibe

All of the above exists to hit one number. The registry scores every plugin 0–100 and
re-tests nightly:

Category	Points	Where it runs
Installs / Loads / Activates / Schema	55	Registry harness (live server)
Tests pass	25	Registry harness
Security audit	0–20	Local
Changelog	−5 if missing	Local
Screenshots	−5 if missing	Local
Plugin-CI	−10 if missing	Local (the workflow file)

The 80 harness points run against a live SignalK server — you can't reproduce them
locally, but the registry serves each plugin's result as JSON, so you can read them.
The rest you fix in the repo before the next nightly. Without plugin-ci.yml the ceiling
is 90, not 100; that surprises people who've done everything else right.

This is where the signalk-registry skill closes the loop, and where the deterministic /
judgment split shows up one last time. Reading the published score is deterministic — it's
an HTTP GET and some JSON:

PKG=$(node -p "require('./package.json').name")
SLUG=$(printf '%s' "$PKG" | sed 's/^@//; s#/#__#')   # @scope/name -> scope__name
curl -s "https://signalk.org/signalk-plugin-registry/plugins/$SLUG.json"

What to do with it is the judgment: is that lone moderate advisory dev-only noise
(esbuild, vitest — never shipped) or a real ship-blocker? Is the pin behind the latest
release, and does that release even contain plugin-ci.yml at the new ref? Those are the
calls the skill makes, so "publish to 100" becomes something you can actually check on
demand instead of a number you hope is still true.

The shape of it

gh release create vX.Y.Z ─→ publish.yml ─(OIDC, no token)─→ npm  + provenance
                          └─ Release = changelog (−5 gap closed)

push / PR ─→ test.yml          (build + unit tests)
          └─ plugin-ci.yml     (5-platform reusable CI, +10 / −10, pinned SHA)

weekly ───→ dependabot.yml     (bumps the pin; ignores the v6.6.6 trap)

on demand ─→ signalk-registry skill  (reads live score, judges the gaps)

Four deterministic YAML files do the plumbing; three skills supply the judgment the
YAML can't. That's the same bet we make everywhere on this stack — an all-electric
charter catamaran whose ops run on exactly this division of labour: deterministic code
where the inputs are clean, a model where they aren't, and a clear seam between the two.
The skills are public; a plugin that
runs the whole pipeline is signalk-currents.

When MCP tools break, isolate the server before blaming the agent

Bryan Clark — Wed, 24 Jun 2026 12:03:08 +0000

You add a new MCP server, or a new tool to an existing one. You ask the agent to use it and it says the tool isn't available — or worse, it confidently reports that "only the HTTP server is connected" and the new stdio servers aren't live. The instinct is to blame the MCP server or bounce the runtime. Resist it. The agent's narration about its own toolset is not ground truth, and a malformed test invocation will happily manufacture a fake "MCP unreachable" symptom. Here's the broke → tried → fixed of a debugging session that burned time on exactly this.

Problem

We'd just added a second stdio MCP server and a new tool. To smoke-test it, we hand-typed a quick probe at the agent runtime and asked it to use the new capability. The agent came back with this:

Those tools aren't in my live toolset right now — only the
Home Assistant (HTTP/SSE) server is connected. I'll read the
files directly instead.

It then shelled out to read files off disk to answer the question — being resourceful, which made it look like the tools genuinely weren't wired up. Two new stdio servers, both apparently invisible to the session, while the one HTTP/SSE server was fine. That sure reads like the stdio MCP servers aren't connecting.

That self-report is the trap. Treating "the agent says the tools aren't available" as a diagnosis — instead of a symptom — is what sent us down the wrong path.

Diagnosis

There are two failure modes here and they look identical from the agent's chair:

The MCP server actually isn't connecting (bad command path, crash on startup, transport mismatch).
The session never loaded the toolset, because the way you invoked the agent doesn't load tools the way the production path does — wrong flags, wrong profile/skill selector, a different transport. The server is fine; your probe is malformed.

The agent can't tell these apart for you, and it will narrate either one as "tools not available." Worse, an LLM describing its own capabilities is itself a confabulation risk — it pattern-completes a plausible story ("only the HTTP server is live") around the fact that some tools didn't show up. That story is not evidence about server health.

So the discipline is: don't ask the agent whether the server is up. Ask the server. Isolate the layer before you touch anything.

What we tried (and why it failed)

Dead-end 1 — trusted the agent's "tools unavailable"

We took the self-report at face value. The agent said the stdio servers weren't connected, so we assumed they weren't connected. This is the root mistake every later dead-end inherits from — we let the agent's narration stand in for a connectivity check. It is not one.

Dead-end 2 — restarted the long-running gateway daemon

"Tools didn't load? Refresh them — restart the runtime." So we bounced the long-running agent gateway daemon, the shape of which is:

# generic shape — restart the long-running agent runtime/gateway
<runtime> gateway restart

Then re-ran the same probe. No change:

Still only the Home Assistant server is connected — the other
tools aren't in my toolset.

Restarting a daemon to "refresh tools" is a guess, not a diagnosis. If the server were genuinely stale you'd want evidence of that first. We had none — we were rebooting on a hunch, and the hunch was wrong. (It also cost real time: a gateway restart drops every in-flight session.)

Dead-end 3 — re-probed ad-hoc, still "unavailable"

We re-ran the hand-typed probe a few more times, tweaking the wording, still getting "tools not available." At this point it looks airtight: server's been restarted, agent still can't see the tools, therefore the server must be broken. Every signal pointed at the MCP server — and every signal was coming through the same malformed probe, so they were all the same false negative wearing different hats.

The fix

Stop reasoning through the agent. Isolate the layer, then reproduce the exact production invocation.

Step 1 — test the MCP server standalone

Spawn the server fresh, outside any agent session, and ask it to enumerate its tools. Most runtimes ship a connectivity check that does exactly this; the vendor-neutral tool is the MCP Inspector.

If your runtime has a built-in check (generic shape — it spawns the server fresh, bypassing the session):

<runtime> mcp test <server>

Or talk to the server directly with the MCP Inspector — no runtime involved at all. The CLI mode is perfect for a connectivity assertion:

# list the tools a stdio server actually exposes, runtime out of the picture
npx @modelcontextprotocol/inspector --cli \
  <your-server-launch-command> --method tools/list

(npx @modelcontextprotocol/inspector with no --cli opens the browser UI at http://localhost:6274 — connect, open the Tools tab, click List Tools.)

The output settles it immediately:

Connected.
server: signalk          → 7 tools discovered: read_sensor, battery_state,
                            get_route, get_active_alarms, ...
server: vessel_knowledge → 4 tools discovered: find_equipment, get_equipment, ...

Both servers connect and enumerate every tool. The servers were fine the entire time — through all three dead-ends. That one command would have saved the gateway restart and every ad-hoc re-probe.

Step 2 — reproduce with the exact production invocation

If the server lists its tools standalone, the bug (if any) is in how the session loads them, not the server. So stop hand-typing variants and run the agent the way production runs it — same skill/profile selector, same flags, same transport.

Our production path (a voice/MQTT bridge) launches the agent in oneshot mode with a namespaced skill selector and the query passed via the query flag. The malformed probe had used a bare, non-namespaced selector and the wrong flag — which loads a different toolset (or none of the stdio toolsets). The shape that matters:

# WRONG — ad-hoc probe: bare/non-namespaced selector, wrong flag.
# Loads a different profile; stdio toolsets never attach.
<runtime> chat -m <model> -z "use the new tool"

# RIGHT — the exact production invocation: namespaced skill selector
# (profile/<skill>) + the real query flag, oneshot.
<runtime> chat -Q -s profile/<skill> -q "use the new tool"

Run the right one and the agent calls the tools on the first try — no restart, no file-reading workaround:

[tool] get_active_alarms → none active
[tool] find_equipment("Bellmarine") → bellmarine-ddw-10
... rated temperature zones: ...

The fix was a one-line change to the invocation. The server never moved.

The one rule that would have short-circuited all of it: don't restart a daemon to "refresh tools" before the server is proven stale. Prove it with a standalone mcp test / Inspector run first.

Why it matters / gotchas

The agent's self-report about its own toolset is not ground truth. An LLM narrating "only X is connected" is pattern-completing a story around missing tools, not reading a connection table. Treat it as a symptom to investigate, never as a diagnosis.
A malformed probe fakes "MCP unreachable." Wrong flags, a non-namespaced skill/profile selector, or a different transport will load none of the tools you expect — and produce the exact symptom of a dead server. If you debug through an ad-hoc invocation, you can chase a server that was never broken.
stdio vs SSE/HTTP transports attach differently. It's common to see the HTTP/SSE server present while stdio servers are absent in a session — that asymmetry usually means the session/launch path, not the stdio servers. (See the Cursor forum threads where a server is "connected, tools discovered in logs" but shows 0 tools to the agent — same shape.)
Restarting the runtime is a guess, not a diagnosis. It feels productive and occasionally papers over the real issue, which is worse — it teaches you the wrong fix. Isolate first; the standalone server check is two commands and removes an entire branch of the search tree.
This applies to any MCP host — Claude Desktop, Cursor, IDE integrations, custom agents. The Inspector talks to your server with zero host involved, which is precisely why it's the right first probe: it can't be fooled by the host's session quirks.

The order is the whole lesson: server (standalone) → invocation (exact production form) → only then the runtime. Don't bounce the daemon until the first two are ruled out.

Close

This came out of wiring MCP servers into a ship's-computer agent for an all-electric charter catamaran — SignalK, vessel-knowledge, and tide/weather tools behind a local LLM. When the agent said it couldn't see them, the servers had been fine all along; the probe was wrong. The MCP servers behind it are open source: github.com/sailingnaturali/signalk-mcp.

How LLM agents confabulate infrastructure and data provenance

Bryan Clark — Wed, 24 Jun 2026 12:03:04 +0000

Give an agent a tool that returns a number and ask it a question, and it will often answer with the number plus a story: which machine is running the service, whether that service is healthy, whether the reading is "live" or "from a test rig," whether the thing being measured is on or offline. None of the story came from a tool. The model made it up — confidently, in the same flat voice it uses for the parts it actually observed.

This is confabulation, not hallucination: the model isn't inventing something unrelated to reality, it's filling an unobservable gap with the most plausible continuation and stating it as fact. The distinction matters because the fix is different. You don't fix confabulation by telling the model to be more accurate; you fix it by removing the gap, or by removing the model's permission to narrate into it.

We hit two distinct flavors of this building a local-LLM agent (an 8B running the ship's-computer role on a boat). Same root cause, same three-part fix. This is what each looked like and what actually shut them down.

Problem

Flavor 1 — inventing infrastructure it can't observe

A cosmetic, auxiliary error scrolled past — a throwaway session-title-generation call timed out. That's a side feature; it says nothing about whether the main conversation works. But the agent picked it up as a thread to pull, and produced a diagnosis like this:

The local model backend is down. Ollama runs as a Docker container on the
dashboard host; that container has crashed. Confirming now.

$ docker ps --filter ancestor=ollama/ollama
(no output)

Confirmed — no Ollama container is running on the dashboard host. That's the
outage.

Every operational claim in there is fabricated. The model backend was healthy and reachable the whole time. Ollama wasn't a container on the dashboard host — it ran on a different machine entirely. And the docker ps it ran to "confirm" executed on its own host, not the host it was talking about — so the empty output was empty for an irrelevant reason, and the model read that emptiness as proof of its invented topology.

The agent had no tool that could observe the network layout. So it invented one that sounded right, then mined whatever command output it could get for confirmation — even output from the wrong box.

Flavor 2 — narrating data provenance it was never told

Simpler to reproduce, and creepier. Ask for a sensor reading:

> how's our depth?

Depth 4.2 meters below the keel. This reading is coming from the local
test/mock rig — not from the vessel, since we're currently ashore.

The depth number is real (a tool returned it). Everything after the period is confabulated. "Test/mock rig," "ashore" — none of those words exist in any prompt, any config, or any field the tool returned. The model volunteered an entire provenance story for a bare number, in the same confident register as the reading itself.

If you're searching for this: the agent makes up the data source, appends (this is live data from the real sensor) or the device is currently offline or this is a test value, attributes a reading to a system nobody mentioned. That's provenance confabulation.

Diagnosis

Both flavors are the same mechanism: the model treats an unobservable gap as something to narrate. Where it has no tool to see the truth, it predicts the most plausible truth and states it with the same confidence as the parts it observed. The model has no internal marker for "I observed this" vs "I generated this" — to the next-token predictor, both are just tokens to continue.

Two things made it worse, and they're worth separating:

Smaller models do this more. An 8B pattern-completes harder and self-censors less than a frontier model. The infra-diagnosis case ran on a larger local reasoning model and still did it — so it's not purely a size thing — but the bare-number-gets-a-backstory behavior was squarely an 8B habit. If you're running local models, budget for more of this, not less.

We seeded it. This is the part that stings. The persona prompt literally contained the words "mock data" — buried in an unrelated clause about how stored records handle timekeeping. The model picked that token up and amplified it into "the mock rig." Your own prompt is training data for the next token. A stray word you put in the context, even in a caution or an aside, is a word the model can and will run with. We handed it "mock" and it handed us back a confident sentence about a mock rig.

That reframes the whole problem. Confabulation into a gap is one thing; amplifying a word you yourself planted is a self-inflicted version of it. Which is exactly why the most intuitive fixes make it worse.

What we tried (and why it failed)

Attempt 1 — warn the model about the gap

The honest instinct: the data sometimes comes from a test rig, so tell the model that, so it can be careful about it.

# in the persona prompt
Note: sensor data may currently be sourced from a local test rig rather than
the live vessel. Keep this in mind.

Result — the model now announces the test rig every time, unprompted:

> how's our depth?

Depth 4.2 meters. Note that this is sourced from the local test rig rather
than the live vessel.

We told it to "keep in mind" a fact and it kept it in mind by saying it out loud, as fact, constantly. A caution in the prompt is not a private note to the model. It's text the model will surface. We'd taken a word it was occasionally confabulating and promoted it to a word it now states on every reply. Strictly worse.

Attempt 2 — tell it not to hallucinate

# in the persona prompt
Do not hallucinate. Do not make up information. Be accurate and factual.

Too vague to bind to anything. "Don't hallucinate" gives the model no operational handle — it doesn't experience the confabulated provenance as a hallucination; from the inside, "this is from the test rig" is just a plausible, on-topic continuation. The instruction sailed right past the behavior and the agent kept narrating provenance and inventing topology. Generic anti-hallucination boilerplate does nothing against confident, on-distribution confabulation.

Attempt 3 — list the right facts so it stops guessing wrong

For the infra case, we tried correcting the topology inline: tell it which host runs what so it stops inventing.

# in the diagnosis prompt
The model backend runs on the compute host, not the dashboard host.

This reduced the specific wrong guess but didn't fix the mechanism — the model would still run a diagnostic command on the wrong host and reverse-justify from its output, because it had no way to know which host its own shell was answering for. The shell tool ran local while the model reasoned about a remote box, and silently manufactured false evidence. You can correct one confabulation by hand, but the next gap is still a gap.

The fix

Three layers, because no single one holds on a small model.

1. Ground the real, observable facts — so there's no gap to fill

For the infra flavor: the model invents topology because it can't see topology. So put the true topology in the context, and — more importantly — make tools state their own vantage point. A shell tool that runs on host A while the agent reasons about host B must say so, or the agent must be told it cannot observe B from where it sits:

You are running on the compute host. Any shell command you run answers for
THIS host only. You cannot observe other hosts from here. If a question is
about another machine, say "I can't observe that host from here" — do not
infer its state from local output.

That converts "invent a plausible answer" into "state a boundary." The gap is named instead of filled.

2. An explicit anti-provenance rule in the always-on persona

For the provenance flavor, the generic "don't hallucinate" failed because it wasn't specific. So name the exact behavior and forbid it — in the always-on persona, not a conditional skill file, because it has to apply to every query. These are the actual lines from our shared persona (SOUL.md):

## Avoid
- Speculating about data provenance. Report the reading, and its SignalK path
  if asked. Do not narrate whether data is "live," from the "real vessel," a
  "test rig," a "mock," or whether the vessel is "ashore," "hauled out," or
  "underway" — you are not given that context and must not guess it.

And the default that backs it, so "I don't know" is the sanctioned move instead of a guess:

- Confabulation under uncertainty. "I don't have that" beats a plausible guess.

The win over Attempt 2 is specificity. "Don't hallucinate" gives the model nothing to grab. "Don't say 'live'/'mock'/'test rig'/'ashore'; report the reading and its path if asked" names the exact tokens and the exact allowed alternative. The model can act on that.

3. Audit the prompt for words you don't want spoken — and remove them

This is the one almost nobody does. Grep your own prompt for any term that names something you don't want stated as fact, and take it out. We had the literal string mock data in the persona (in an unrelated timekeeping clause). We reworded it out. You cannot have a rule that says "never say 'mock'" while the word "mock" sits in the context — you're seeding and forbidding the same token, and on a small model the seed wins.

The meta-rule: don't put a word in the context you don't want amplified back at you. Not in an instruction, not in a caution, not in an aside. If it's in the prompt, treat it as something the model might say out loud.

4. Belt and suspenders — guard in the tool layer

Prompt rules reduce this on an 8B; they don't eliminate it. The deterministic backstop is to have the tool return only what should be stated, so there's no raw provenance field for the model to narrate even if it's tempted. The reading goes out as a clean, pre-formatted value with no source: "mock", no host:, no is_live: for the model to read and run with:

// what the tool returns — nothing to narrate into
{
  "value": 4.2,
  "display": "4.2 meters below the keel"
}
// NOT: { "value": 4.2, "source": "mock-rig", "host": "...", "is_live": false }

If the model never sees a provenance field, the prompt rule has far less to fight. Robustness lives in the tool; the prompt rule is the second line, not the only one.

Why it matters / gotchas

Confabulation wears the same voice as truth. The invented topology and the real reading arrive in identical confident prose. There's no in-band signal that one half was observed and the other generated — which is exactly why you can't trust an agent's infra diagnosis as a finding. Treat it as a hypothesis until a deterministic check from the right vantage point confirms it.
A caution in the prompt is a public statement, not a private note. This is the counterintuitive one. Telling the model "this might be a test rig, be careful" doesn't make it careful — it makes it announce the test rig. If you wouldn't want the sentence in the output, don't put its keywords in the input.
Distinguish auxiliary failures from real ones before you let the agent run with them. Half of the infra confabulation was the agent treating a cosmetic timeout (a title-generation side call) as a pipeline outage. A timed-out summary/embedding/title call is not an outage; check whether the primary path actually failed before escalating.
Guardrails reduce, they don't eliminate — pair the prompt with the tool layer. On a small model, expect residual confabulation even with a clean prompt and an explicit rule. The tool returning only speakable fields is what makes it deterministic. Same theme as fixing formatting in the tool layer rather than the prompt: anything that must hold belongs below the model, not in instructions to it.
The general lesson is one sentence: confabulation is the model narrating an unobservable gap, so the fix is to remove the gap (ground the facts), remove the permission (an explicit, specific rule), and remove the temptation (don't seed the word, and don't hand the model a field it shouldn't speak).

Close

This came out of running a local-LLM ship's-computer agent on an all-electric charter catamaran, where a confident wrong sentence about where a depth reading "came from" is worse than no sentence at all. The persona and the MCP tool servers behind it are open source: github.com/sailingnaturali/naturali-agents.

An MCP 404 trips the circuit breaker and drops valid reads

Bryan Clark — Wed, 24 Jun 2026 08:35:22 +0000

An agent intermittently "loses" a tool. It reads a sensor fine ten times, then
flatly claims the value is unavailable — for a path you can see returning data in
the upstream server's own UI. Restart the session and it works again, for a
while. The cause isn't the tool and isn't the server: it's a raise_for_status()
in the HTTP client turning a perfectly normal 404 ("not published") into a
tool failure, and a burst of those tripping the agent runtime's
consecutive-failure circuit breaker — which then suppresses the valid calls
queued behind them.

This is the broke → tried → fixed of an MCP tool that wraps an HTTP API where
"absent" is a legitimate answer.

Problem

The stack: a small local model asks a question, the agent runtime fans it out
into several tool calls, each tool call hits an MCP server, and the MCP server
reads an upstream HTTP API. In our case the upstream is SignalK
(a marine data server) and the tool is read_sensor(path) — but nothing here is
marine-specific. Substitute any HTTP API where a missing key returns 404.

The symptom, from the agent transcript:

user: how's our course and speed?
agent: Speed over ground is 6.1 knots. Course is unavailable right now.

Course was not unavailable. The upstream server was serving
navigation.courseOverGroundTrue = 205° the entire time — you can watch it tick
in the server's own data browser. Yet the agent says "unavailable," and a minute
later the same question answers correctly. Intermittent, path-specific,
self-healing. The worst kind.

The naive client — the one almost everyone writes first — looks like this:

async def get_value(self, path: str) -> dict:
    url = f"{self.base_url}/api/vessels/self/{path.replace('.', '/')}"
    resp = await self._http.get(url)
    resp.raise_for_status()      # <-- every non-2xx becomes an exception
    return resp.json()

raise_for_status() raises HTTPStatusError on any 4xx/5xx. The MCP tool
that calls get_value lets that exception propagate, so the runtime records the
tool call as a failure. That seems reasonable — until you look at what is
404ing and how often.

Diagnosis

Two facts collide.

Fact 1: a 404 here means "this path isn't published," which is normal. A
boat with no electronic compass doesn't publish navigation.headingMagnetic. A
vessel at anchor doesn't publish navigation.courseOverGroundTrue (no course
when you're not moving). The server's REST API answers those with a 404. That's
not an error condition — it's the API's way of saying I don't have that. The
same is true of countless HTTP APIs: 404 on a resource that doesn't exist is an
expected, information-bearing answer, not a fault.

Fact 2: the agent generates 404s in bursts, by design. Ask a small model
(this bit us on a local ~30B) "course and speed?" and it doesn't know the exact
paths, so it guesses — fanning out parallel calls:

read_sensor("navigation.headingTrue")        -> 404  (no compass)
read_sensor("navigation.headingMagnetic")    -> 404  (no compass)
read_sensor("sensors.depth")                 -> 404  (wrong namespace)
read_sensor("navigation.courseOverGroundTrue") -> 200, 205°   <-- the good one

Three guesses 404, then the correct path is queued right behind them. With the
naive client, those three 404s are three raised exceptions — three recorded
tool failures in a row.

Now bring in the runtime. Agent runtimes run a per-tool circuit breaker: after
N consecutive failures of the same tool, the breaker opens and the runtime
stops dispatching that tool for a cooldown, returning an immediate
"tool unavailable" instead of calling it. The widely-cited default is N = 3
(circuit breaker for repeated tool failures in agent loops;
MCP circuit breaker pattern).
Ours was exactly 3.

So: three guessed-path 404s trip the breaker, the breaker opens, and the valid
courseOverGroundTrue read queued behind them never gets dispatched. The agent
is handed "tool unavailable" for a path that was serving data the whole time. The
model's bad guessing is the trigger, but raise_for_status() on a 404 is what
makes it fatal instead of harmless.

It even masquerades as a server crash. In the upstream access log, the server
happily answers requests up to the last 404 — and then sees nothing. The later
requests never left the client, because the breaker opened on the client side.
Don't go chasing a phantom upstream outage; check the runtime's failure counter.

What we tried (and why it failed)

Attempt 1 — raise on every non-2xx (the starting point)

resp = await self._http.get(url)
resp.raise_for_status()   # raises HTTPStatusError on 404 just like on 500
return resp.json()

This is the bug. raise_for_status() makes no distinction between "the resource
isn't there" (404) and "the server is broken" (500). Every guessed path becomes a
tool failure. Three in a row → breaker open → valid reads dropped. The contract is
wrong at the source: we're reporting absence as failure.

Attempt 2 — just bump the breaker threshold

If 3 is too few, raise it:

# agent runtime config
tool_failures:
  same_tool_failure: 8    # was 3

This doesn't fix anything — it raises the price of admission. A chattier model, or
a question that fans out into more guesses, still walks past 8. Worse, you've now
blunted the breaker for real outages: when the upstream genuinely goes down, the
runtime now eats 8 failed calls before protecting itself. You've traded a
false-positive problem for a slower true-positive. The breaker isn't the thing
that's wrong; the failure classification feeding it is.

Attempt 3 — retry the failed calls

Wrap the call in a retry so a "transient" failure gets another shot:

for attempt in range(3):
    resp = await self._http.get(url)
    if resp.status_code < 400:
        return resp.json()
    await asyncio.sleep(0.2 * attempt)
resp.raise_for_status()

A 404 is not transient. The path that isn't published at 0 ms is still not
published at 600 ms. All this does is turn three fast 404s into nine slow ones —
more failures toward the breaker, plus latency, and the breaker still opens.
Retrying is the right tool for timeouts and 5xx; it's the wrong tool for "the
resource doesn't exist."

Attempt 4 — fix it in the prompt

Tell the model the exact paths so it stops guessing:

When asked for course, read navigation.courseOverGroundTrue.
When asked for heading, read navigation.headingTrue.
Never read sensors.depth; use environment.depth.belowTransducer.

Path hints reduce guessing, and they're worth having — but they're
model-dependent and fragile, and they don't make the tool layer safe. A different
model, a reworded question, a path the hint list forgot, and you're back to a
404 burst tripping the breaker. Breaker-safety has to live in the deterministic
tool layer, not in a prompt the next model release might ignore.

The fix

Treat 404 as a null-valued result, not an error. Return {"value": None}
instead of raising — and keep raising on everything that's a real fault (5xx,
connection errors, timeouts), because those are exactly what the breaker should
see and act on.

async def get_value(self, path: str) -> dict:
    """Fetch a value object from the upstream API.

    A 404 means the upstream simply doesn't publish that path — a normal
    "not available" result, not a failure. We return a null-valued dict
    rather than raising, so missing/guessed paths don't register as tool
    failures (which can trip the client's consecutive-failure circuit
    breaker). Any other HTTP error (5xx, etc.) is a real fault and still
    raises.
    """
    url = f"{self.base_url}/api/vessels/self/{path.replace('.', '/')}"
    resp = await self._http.get(url)
    if resp.status_code == 404:
        return {"value": None, "timestamp": None}
    resp.raise_for_status()   # 5xx / other faults still raise — breaker still works
    return resp.json()

One branch. Check for 404 before raise_for_status(), return a null result, and
let raise_for_status() handle the genuinely-broken cases. The breaker still
protects you against a real upstream outage (a string of 500s still trips it), but
a guess-storm of "not published" paths now flows through harmlessly as
value=None.

Apply the same rule to any endpoint where absence is a valid answer — a tree-walk
for path discovery, a sub-resource fetch, etc.:

async def get_subtree(self, root: str) -> dict:
    resp = await self._http.get(f"{self.base_url}/api/.../{root}")
    if resp.status_code == 404:
        return {}            # nothing published there yet — empty, not broken
    resp.raise_for_status()
    return resp.json()

There's a quiet bonus: a present-but-null value (e.g. course while stationary,
which the API returns as null) and an absent path (404) now surface as the
same shape — value=None. The agent gets one consistent "unavailable" concept
to reason about, instead of one path that returns null and another that throws.

Why it matters / gotchas

This generalizes past SignalK to any agent/MCP tool sitting over an HTTP API
where "absent" is a legitimate result. The pattern is always the same:

Distinguish "absent" from "broken" at the HTTP boundary. 404 (and often an empty 200) means the data isn't there — an answer, not a failure. 5xx, connection refused, and timeouts mean the system is broken — those are failures, and the breaker should see them. Collapsing the two with a blanket raise_for_status() is the root mistake.
Circuit breakers amplify a mislabeled error into cascading tool loss. A breaker is a multiplier: misclassify one normal response as a failure and the breaker turns a handful of them into every subsequent call failing for a cooldown window. The blast radius of "404 raises" is not one bad read — it's all the good reads behind it.
Agents guess; assume bursts of "not found." Any model driving a path- or ID-addressed API will probe wrong keys, especially smaller local models. Don't treat that as pathological — treat absence as a first-class, non-failing result so guessing is cheap.
Don't blunt the breaker to paper over this. Raising the threshold or retrying 404s both make the breaker worse at its actual job (catching real outages) while only delaying the false trip. Fix the classification, not the breaker.
It looks like an upstream crash but isn't. When the breaker opens client-side, the upstream's access log just goes quiet — the later requests never leave the agent. Check the runtime's failure counter before you go debugging a server that's perfectly healthy.

The one-line test for whether a status code should raise: would a healthy system,
correctly used, ever return this? For 404-on-a-missing-resource, the answer is
yes — so it must not raise.

Close

This came out of building the AI ops layer for an all-electric charter catamaran —
a local LLM driving MCP tools over a SignalK marine-data server. The tool that
wraps SignalK is open source, 404-handling and all:
github.com/sailingnaturali/signalk-mcp.

Logging VHF DSC distress calls in SignalK (PGN 129808)

Bryan Clark — Wed, 24 Jun 2026 08:35:18 +0000

A DSC distress alert is the most important packet a marine VHF will ever hand you, and it's structured data. When a vessel hits the red button, its radio transmits a digital selective calling burst on channel 70: format specifier, the sender's MMSI, category, nature of distress, position, and UTC time — encoded per ITU-R M.493. A DSC-equipped radio that hears it re-emits it to your network, as $--DSC/$--DSE sentences on NMEA 0183 or as PGN 129808 on NMEA 2000.

That burst arrives — and stays readable — even when the follow-up voice MAYDAY on channel 16 is garbled, stepped on, or out of range. If you might be the nearest boat, you want every received alert stored with its position and surfaced as an alarm.

Stock SignalK quietly drops most of it. This is the broke → tried → fixed of getting DSC distress calls into SignalK, with receipts for every gap. The result is signalk-dsc.

The test sentence — try it without a radio

You don't need a transmitting vessel in distress to reproduce all of this. Feed two sentences through any NMEA 0183 input (TCP, UDP, file playback):

$CDDSC,12,3380400790,12,05,00,1423108312,2019,,,S,E*69
$CDDSE,1,1,A,3380400790,00,45894494*1B

That's a format 12 (distress alert), from MMSI 338040079 (the sentence carries it * 10, with a trailing zero), category 12 (distress), nature 05 (sinking), a position field, UTC 2019, and the E expansion flag saying a $--DSE sentence follows. The second sentence is that expansion, refining the position. Both together are one incident.

Now walk through what stock SignalK does with each, and where it falls short.

Gap 1: the 0183 hook misses sparse distress alerts — and persists nothing

The DSC field layout (sentence id and checksum already stripped) is:

        0  1          2  3  4  5          6    7 8 9 10
        |  |          |  |  |  |          |    | | | |
 $--DSC,XX,XXXXXXXXXX,XX,XX,XX,XXXXXXXXXX,XXXX,,,A,C*hh

  0: format specifier (12 = distress alert)
  2: category (00 routine / 08 safety / 10 urgency / 12 distress)
  3: nature of distress
  5: position (quadrant + ddmm + dddmm)
  6: UTC time hhmm
 10: expansion flag — 'E' means a $--DSE sentence follows

The upstream issue here is SignalK/nmea0183-signalk#217: some radios emit a distress alert with the category field empty — it's redundant, because format 112 is a distress alert by definition. The stock parser treats the empty category as "not a distress call" and the alert evaporates.

signalk-dsc registers its own DSC parser (a superset of the stock hook) that infers the category from the format when it's missing:

let categoryCode = field(parts, 2);
// Some radios omit the category on distress alerts — it is implied by
// format 112 (see SignalK/nmea0183-signalk#217).
if (!categoryCode && formatCode === '12') categoryCode = '12';

The whole parser is tolerant by design: anything it can't interpret stays undefined, and the raw sentence is always kept alongside the parsed fields. That's the second half of the gap — even when the stock hook does fire, it raises a transient notification and stores nothing. There is no record afterward. A distress alert with no persistence is a distress alert you can't act on the moment you look away from the screen.

signalk-dsc appends every received call to an on-disk JSONL log and serves the history at /signalk/v2/api/resources/dsc-calls (anonymously readable under allow_readonly):

app.registerResourceProvider({
  type: 'dsc-calls',
  methods: {
    async listResources() { /* every stored call, by id */ },
    async getResource(id) { /* one call */ },
    setResource() { throw new Error('dsc-calls is read-only'); },
    deleteResource() { throw new Error('dsc-calls is read-only'); },
  },
});

The store is deliberately boring — append-only JSONL, synchronous I/O, full-file compaction past a cap. DSC traffic is rare (a busy day within range of a coast station might see dozens of calls), so the simplest thing that survives a power cut mid-write wins: a torn last line is skipped on load, the rest is kept.

Gap 2: $--DSE position refinement, which the stock parser ignores entirely

The position in the DSC sentence is truncated to whole minutes — about ±1 NM. That's coarse for a search. The optional $--DSE expansion sentence carries the missing precision, down to ten-thousandths of a minute:

        0 1 2 3          4  5
        |_|_|_|__________|__|________
 $--DSE,t,n,A,XXXXXXXXXX,00,llllyyyy*hh

  3: address — MMSI * 10, same convention as DSC
  4+: (code, data) pairs; code 00 = enhanced position,
      data = 4 digits lat + 4 digits lon, in 1/10000 of a minute

The stock parser doesn't handle DSE at all. signalk-dsc pairs an incoming DSE with the matching DSC call it stored in the last two minutes (same MMSI, position still at minute resolution) and refines it. DSC truncates toward zero, so the fractional minutes always extend the magnitude — sign-preserving:

function refinePosition(position, ext) {
  const extend = (value, minuteFraction) => {
    const sign = value < 0 ? -1 : 1;
    return sign * (Math.abs(value) + minuteFraction / 60);
  };
  return {
    latitude: extend(position.latitude, ext.latMinuteFraction),
    longitude: extend(position.longitude, ext.lonMinuteFraction),
  };
}

The stored call's positionResolution flips from minute to enhanced, and the refined position goes out as a delta. ±1 NM becomes a tight fix.

Gap 3: n2k-signalk has no PGN 129808 mapping at all

On NMEA 2000, a DSC call is PGN 129808, "DSC Call Information." n2k-signalk — the converter that turns N2K into SignalK deltas — produces no delta for it. There's nothing to subscribe to.

So signalk-dsc goes one layer down and listens to the server's analyzer stream directly:

const DSC_PGN = 129808;

function onPgn(pgnData) {
  if (!started || !pgnData || pgnData.pgn !== DSC_PGN) return;
  record(normalizePgn129808(pgnData), { source: 'n2k', raw: pgnData.fields });
}

app.on('N2KAnalyzerOut', onPgn);

Normalizing 129808 is fiddly because canboatjs may resolve the enumerations to their names or pass through the raw ITU symbol numbers when a lookup misses, and the distress vs. general variants use different field names. The mapping handles both — name and number — for format, category, and nature:

const NATURES = new Map([
  ['sinking', 'sinking'],
  ['man overboard', 'mob'],
  ['flooding', 'flooding'],
  // ...resolved names above; raw ITU symbols below
  [5, 'sinking'],
  [10, 'mob'],
  [1, 'flooding'],
]);

Both transports — 0183 and N2K — land in the same canonical event shape, so everything downstream (storage, alarms, logbook) is transport-agnostic.

Alarms under your own vessel — and surviving a restart

Every received distress/urgency/safety call raises a notification under self so the vessel's own alarm chain fires. The category maps straight onto SignalK's severity ladder:

const NOTIFICATION_STATES = {
  distress: 'emergency',
  urgency:  'alarm',
  safety:   'alert',
};
// → notifications.dsc.distress / .urgency / .safety

Routine calls never alarm. DSC distress alerts auto-repeat until acknowledged, so a naive implementation would re-alarm every few minutes; instead, a repeat inside a 5-minute window bumps a repeats counter on the stored call rather than firing again.

The subtle one: SignalK notifications live in memory. If the server restarts mid-incident, an active distress alarm silently vanishes — and a received MAYDAY must not disappear because the server bounced. So on start, signalk-dsc re-raises the newest alert per category that's still fresh (within the last hour):

reannounceTimer = setTimeout(() => {
  const now = Date.now();
  const reannounced = new Set();
  const events = store.list();
  for (let i = events.length - 1; i >= 0; i--) {
    const event = events[i];
    if (!NOTIFICATION_STATES[event.category] || reannounced.has(event.category)) continue;
    const at = Date.parse(event.lastReceivedAt || event.receivedAt);
    if (now - at <= REANNOUNCE_WINDOW_MS) {
      notify(event);
      reannounced.add(event.category);
    }
  }
}, 30000);

The 30-second delay is deliberate: it lets position providers come up first, so the spoken alert can say "2.3 nautical miles northwest" instead of reading out raw coordinates.

Voice-sized message vs. full log detail

The notification message gets spoken by a voice pipeline, so it's deliberately minimal — type, vessel, situation, range and direction from own position, action, and nothing else:

DSC distress alert: vessel Wind Chaser, sinking, 2.3 nautical miles
northwest. Monitor channel 16.

Note what's not spoken: the MMSI. Text-to-speech reads 366123456 as "three hundred sixty-six million…", which is useless and slow on a safety alert. (The plugin never speaks an MMSI — a small but real design rule.) The full detail lands in the call log and a GMDSS-style logbook entry instead:

[DSC] DISTRESS alert from Wind Chaser (MMSI 338040079): sinking.
position 48°47.700′N 123°12.300′W at 20:19 UTC, 2.3 NM northwest of us. via nmea0183

The vessel name, when present, comes from AIS static data already in the data model — not from the DSC sentence, which only carries the MMSI.

Why a log, specifically

Capturing the alert and alarming on it is the operational case. The reason to also persist it as a log entry is older than SignalK by about a century.

Recording distress traffic is the long-standing radio-station regulatory standard. The cleanest US statement is 47 CFR § 80.409 (FCC station logs). The radiotelegraph-log subsection, (d)(4):

All distress calls, automatic-alarm signals, urgency and safety signals made or intercepted, the complete text, if possible, of distress messages and distress communications, and any incidents or occurrences which may appear to be of importance to safety of life or property at sea, must be entered, together with the time of such observation or occurrence and the position of the ship or other mobile unit in need of assistance.

The load-bearing phrase is "made or intercepted." The rule isn't only about the distress you declare — it explicitly covers the traffic you receive. That's exactly what a DSC receiver does: it intercepts. The required fields — text of the distress, the time, and the position of the station in need of assistance — are precisely what a DSC burst (plus its DSE refinement) carries, which is why the plugin stores all three. The radiotelephone-log equivalent is subsection (e).

The honest caveat, because a knowledgeable reader will poke at an overstated claim: applicability is subsection (f), and the log mandate binds compulsorily-equipped / GMDSS / SOLAS-class / Great Lakes / Bridge-to-Bridge stations — not voluntary recreational stations. A private sailor is generally not legally required to keep this log. Internationally the same duty flows from SOLAS Chapter IV and the ITU Radio Regulations; Canada's equivalent is TP 1539 (Ship Station Radio Technical Regulations), which is the relevant one for a boat working BC waters.

So the accurate framing is narrow and worth getting right: the law doesn't force a recreational station to keep a distress log — but the standard it sets for stations that are required to is a good one, and the data to meet it is already arriving on your network. signalk-dsc gives you that same SOLAS-grade record automatically. (For the practical side of receiving DSC distress alerts, the USCG NavCen DSC Distress page is the reference.)

The shape of it

$--DSC ─┐
$--DSE ─┼─→ canonical DSC event ─┬─→ JSONL log  (/resources/dsc-calls)
PGN 129808 ─┘                    ├─→ notifications.dsc.<category>  (alarm chain)
                                 ├─→ voice-sized spoken message
                                 ├─→ remote-vessel position delta  (chartplotter)
                                 └─→ GMDSS-style logbook entry  (signalk-logbook)

Two wire formats, three things stock SignalK drops, one canonical event, five sinks. A received distress alert no longer vanishes the moment you look away.

This is one piece of an all-electric charter-catamaran ops stack — the radio should keep the log the regulations describe whether or not anyone's watching the screen. Code's here: signalk-dsc.

Why your agent ignores its skill body but obeys the system prompt

Bryan Clark — Wed, 24 Jun 2026 04:41:06 +0000

You edit a skill's prompt to fix a behaviour. You confirm the change is in the file the runtime loads. You restart. The agent does the old thing anyway. Not sometimes — reliably, for most queries.

The instinct is to edit the prompt harder. The actual problem was that the prompt you edited wasn't in the request at all. On a skill/agent framework with a base system prompt plus conditionally-loaded skill bodies, a lot of your "prompt" only loads when a skill triggers — and if the rule needs to hold on every query, it has to live in the always-on layer instead. The second half of the same bug: the always-on file had no deploy step, so the running copy had silently drifted from the repo.

This is framework-general. We hit it on a local Hermes agent, but the same shape applies to anything with the now-common base-prompt-plus-SKILL.md split — Claude Agent Skills, Gemini CLI skills, VS Code agent skills, and others.

Problem

Our agent stack has a shared persona (SOUL.md) and per-agent skills (Navigator, Engineer, Logbook). The persona names the vessel and sets the voice; each skill layers on its own job. We changed the vessel name in the Navigator skill body, deployed it, confirmed the runtime file on disk:

$ grep -n "VESSEL_NAME_HERE\|aboard" ~/.hermes/skills/naturali/navigator/SKILL.md
1:Navigator agent aboard s/v Naturali.

Correct name, correct file, correct path. Restart. Then ask it a plain question:

> how's our depth?
Aboard s/v Wrongboat, depth is 8.2 metres below the keel, Captain.

Still the old name. The file the runtime loads says the right thing. The agent says the wrong thing. Editing the skill body again — any number of times — changed nothing for this query.

Diagnosis

Stop theorising about what the model "should" see and look at what it actually received. Hermes writes a full request dump per call; most frameworks have an equivalent (a debug log, --print-prompt, a proxy capture). Dump the request and grep it:

$ ls -t ~/.hermes/sessions/request_dump_*.json | head -1
/Users/me/.hermes/sessions/request_dump_1733270400.json

$ grep -o "ship's computer" ~/.hermes/sessions/request_dump_*.json | tail -1
ship's computer            # <-- base persona text IS present

$ grep -o "Navigator agent aboard" ~/.hermes/sessions/request_dump_*.json | tail -1
                           # <-- nothing. the skill body is NOT in the prompt

There it is. For a plain "how's our depth?", the base persona was in the prompt and the Navigator skill body was not. The query didn't activate the Navigator skill, so its SKILL.md body never got loaded — and the vessel name we'd been so carefully editing lived only in that body.

This is exactly the progressive disclosure model these frameworks are built on, stated plainly in Anthropic's own Agent Skills docs:

Level 1: Metadata (always loaded) ... Claude loads this metadata at startup and includes it in the system prompt.
Level 2: Instructions (loaded when triggered) ... When you request something that matches a Skill's description, Claude reads SKILL.md from the filesystem. Only then does this content enter the context window.

So a skill's name/description is always in context (that's how the model knows the skill exists), but the body — your actual instructions — only loads when that skill fires. The base system prompt, by contrast, is on every single request. If an instruction must always apply, it belongs in the always-on layer. Vessel identity is an always-apply rule. It was in the wrong layer.

The wrong name was the symptom that exposed this, but the principle generalises to every always-on invariant: identity, time/units discipline, and anti-fabrication rules all silently fail to apply on any query that doesn't trigger the skill that contained them.

What we tried (and why it failed)

Attempt 1 — edit the skill body and redeploy

# fixed the name in the skill source, redeployed
$ scripts/deploy-navigator.sh
deploy-navigator: wrote ~/.hermes/skills/naturali/navigator/SKILL.md (vessel: Naturali)

> how's our depth?
Aboard s/v Wrongboat, depth is 8.2 metres below the keel, Captain.

No change. The file is right; the query just never loads it. You can edit a conditionally-loaded body forever and it will never affect a query that doesn't trigger the skill.

Attempt 2 — assume the file didn't deploy and re-check the disk

$ cat ~/.hermes/skills/naturali/navigator/SKILL.md | head -1
Navigator agent aboard s/v Naturali.

The runtime file was correct the whole time. This rules out a deploy failure and is the moment that should have redirected us to "is this file even being loaded?" instead of "is this file correct?" — two very different questions. We'd been answering the wrong one.

Attempt 3 — add the identity rule to the skill body harder

We considered duplicating the name/identity statement into every skill body so at least the loaded skill would carry it. That "works" only for queries that trigger a skill, leaves bare/social/ambiguous queries (which trigger none) still wrong, and creates N copies of an invariant to keep in sync — the classic drift trap. It treats the symptom. The rule isn't per-skill; it's always-on. It belongs in the one prompt that's always-on.

The fix

Move always-on invariants into the always-on layer (the base persona), and template the vessel name so nothing is hardcoded:

<!-- SOUL.md — the base persona, loaded on EVERY request -->
You are the ship's computer aboard s/v {{VESSEL_NAME}}.
You address the user as "Captain."
Never speak a raw UTC timestamp in conversation.
Report a reading and its source path; never narrate whether data is
"live," from a "mock," or whether the vessel is "ashore" — you aren't
given that and must not guess it.

Then give that file a real deploy step — substituting the name from one source of truth — instead of hand-placing it once:

# scripts/deploy-soul.sh
vessel_name="$(resolve_vessel_name "$repo_root")"   # reads the active vessel profile
sed "s|{{VESSEL_NAME}}|$vessel_name|g" "$repo_root/SOUL.md" > "$HERMES_HOME/SOUL.md"

> how's our depth?
Aboard s/v Naturali, depth is 8.2 metres below the keel, Captain.

Right name, on a query that triggers no skill — because the identity now rides on the always-on persona, not a conditional body.

The skill body keeps only what's genuinely conditional — operational hints that are fine to load only when the skill fires:

<!-- skills/navigator/body.md — loaded only when Navigator triggers -->
For "how's our depth?", read environment.depth.belowKeel, not belowTransducer.

Why it matters / gotchas

Sort every prompt rule into always-on vs conditional, and place it accordingly. Ask one question of each rule: does this need to hold on a query that triggers no skill? If yes, it goes in the base prompt (or, for data-shape rules, the deterministic tool layer — but that's another post). If it's only relevant inside a task, the skill body is the right, token-cheap home. Identity, safety, units, and anti-fabrication rules are almost always the former.

Dump the request before you touch a prompt. "The prompt says X but the agent does Y" has two failure modes that look identical from the outside: the prompt is wrong, or the prompt isn't loaded. Only the request dump tells them apart. We burned two debug cycles editing a file that was never in the request. One grep of the dumped prompt would have caught it immediately.

Every runtime prompt artifact needs a deploy step, or it rots. The second half of this bug: our ~/.hermes/SOUL.md had been hand-placed once, months earlier, and named a since-renamed boat. Only the skill had a deploy script, so only the skill tracked the repo. A prompt file you copy into place by hand has no mechanism to tell you it diverged — it silently runs stale. We fixed it by giving SOUL.md the same treatment the skill already had:

# .git/hooks/pre-commit — redeploy whatever source changed
if echo "$changed" | grep -Eq '^(SOUL\.md$|scripts/(deploy-soul|vessel-name)\.sh$)'; then
  scripts/deploy-soul.sh    # base persona redeployed on every relevant commit
fi
if echo "$changed" | grep -Eq '^skills/navigator/'; then
  scripts/deploy-navigator.sh
fi

Now a commit that edits either source redeploys it. The runtime can't drift from the repo without a commit saying so.

One source of truth for shared values. The vessel name resolves from the active vessel profile — the same profile that seeds the data-layer base values — so the boat is named identically in the data model and in the persona, and switching boats needs zero prompt edits. Don't hardcode a value that appears in two layers; template both from one resolver. A hardcoded value in two places is a drift waiting to happen.

Close

This came out of building an AI ops layer for an all-electric charter catamaran — a local LLM with a shared persona and per-job skills over a marine data bus — where the agent had better call the boat by its actual name, on every query, not just navigation ones. The agent skills and deploy scripts are open source: github.com/sailingnaturali/naturali-agents.

Why Claude won't transcribe your PDF — and what to do instead

Bryan Clark — Wed, 24 Jun 2026 04:41:03 +0000

We needed a public, machine-readable vault of the navigation rules of the road — COLREGS rule text — to back an MCP server for a boat agent. The obvious plan: hand Claude the USCG Navigation Rules and Regulations Handbook PDF and ask it to transcribe each rule into a clean markdown file. The text is a US Government work in the public domain. Free to copy, free to redistribute.

Claude read the whole PDF, started writing, and then the Anthropic API hard-blocked it:

API Error: 400 Output blocked by content filtering policy

It blocked again. And again. Eleven blocked responses across two sessions before we gave up on transcription entirely. This post is the dead-end in full — the attempts, the repeating error, and the fix that turned out to be the better architecture anyway: don't route source text through model output. Have the model write a parser, and let the parser write the files.

Problem

The symptom is a 400 from the Messages API mid-task, surfaced by whatever's driving the model (Claude Code, an SDK call, an agent loop) as:

API Error: 400 Output blocked by content filtering policy

It fires late — after the model has read the source document and started emitting. The read succeeds. The generation is what dies. And it is sticky: once your task is "read this document and write out its text," every subsequent response in the session tends to get blocked too, including replies that contain no document text at all.

This is not a rate limit, not a context-length error, not a malformed request. It's an output-side classifier. Anthropic documents it plainly in their privacy center:

Claude's purpose is to generate new content and ideas, not to reproduce content that already exists.

It's an anti-regurgitation guard. It watches the output stream for sustained verbatim reproduction of source material and trips when it sees it. Two consequences fall straight out of that design, and both bit us:

It is license-blind. The classifier can't see provenance or licensing. Public-domain USCG rule text trips it exactly like copyrighted prose would. "But this is legal to copy" is not an argument the filter can hear.
It is API-level, so you can't route around it. Subagents, different sessions, retries — they all hit the same classifier. The trigger is the shape of the task (long verbatim copying into output), not a transient.

You're far from alone if you've hit this. It's a long-running source of false positives in Claude Code — generating a LICENSE file, adding a Mozilla license, the Contributor Covenant code of conduct, extracting a peer-reviewed paper, even benign markdown edits. The common thread in all of them: the model was about to emit a long span that closely matches existing text.

Diagnosis

The mental model that unlocks the fix: the filter cares about your output, not your intent. It does not matter that the text is public domain. It does not matter that you have the file open in front of you. It does not matter that you extracted the text and you're just asking the model to echo it back. If a long verbatim span of pre-existing material flows through the model's output, the classifier can trip.

That last point is the one people miss. We tripped it once when the assistant merely echoed already-extracted vault text back into chat while summarizing progress. The text had already been pulled out of the PDF by other means — the model was just quoting it in conversation. Output is output. Where the text came from is invisible to the classifier.

So "transcribe this PDF to markdown" is a near-perfect trigger. It is, by definition, a request to emit a long verbatim span of an existing document. The task and the thing the filter blocks are the same task.

What we tried (and why it failed)

Attempt 1 — just transcribe it

Point the model at the PDF, ask for clean markdown per rule. Here's a reconstructed version of the task list it built (the structure is real; the wording is reconstructed, not a verbatim transcript):

TODO
[ ] Transcribe Rules 1–13  → rules/international/rule-01.md … rule-13.md
[ ] Transcribe Rules 14–31
[ ] Transcribe Rules 32–38
[ ] Transcribe Annexes I–V  (PDF pages 121–146)

It picked up task 1, read the pages, started writing — and:

API Error: 400 Output blocked by content filtering policy

In one session, 11 rule files landed before the wall went up; the rest were abandoned. In a later, dedicated transcription session it was worse — six blocked responses, zero files written. Every single response after it picked up the first task got blocked.

Attempt 2 — retry

The instinct on a 400 is to retry. So we retried. Same task, fresh response:

API Error: 400 Output blocked by content filtering policy

Retrying never works here, and now you know why: the trigger is the task shape, not a transient fault. Same input, same classifier, same block. We even asked the model, in plain chat with no document text in the reply, "are you working, or are we stuck?" — and that got blocked too, because the session was now anchored on a verbatim-reproduction task.

Attempt 3 — dispatch a subagent

Maybe a fresh subagent with a tighter prompt would behave. We dispatched one whose whole job was authoring rule files. It got two blocks of its own:

API Error: 400 Output blocked by content filtering policy

The filter is API-level. A subagent is just more Messages API calls — it routes through the exact same classifier. There is no "inner" model that isn't filtered.

The tally across two sessions: 11 blocked responses. Five on the first day (two of them inside the dispatched subagent, one when the assistant only echoed already-extracted text), six on the dedicated retry session with no progress at all. The lesson finally landed: you cannot make this task work by asking more nicely, from a different agent, or one more time. The task itself is the thing being blocked.

The fix

Stop sending source text through model output. Have the model write a parser; let the parser write the files. The model's output is now Python — novel code, which the filter has no quarrel with — and the rule prose flows file-to-file via pdftotext and XML parsing, never touching the model's output stream.

For this vault, three deterministic extractors, one orchestrator. Prefer structured authoritative sources over the PDF where they exist — better provenance and machine-parseable:

# scripts/build_vault.py — Claude wrote this; it does the extraction, not the model
for part in ECFR_PARTS:                       # 33 CFR 83–88, eCFR versioner API XML
    xml_text = ecfr_path(sources, part).read_text()
    if part == 83:
        docs += ecfr.parse_rules(xml_text, url, retrieved)   # US Inland rules
    else:
        docs.append(ecfr.parse_annex(xml_text, part, url, retrieved))

docs += justice.parse_schedule(justice_xml, retrieved)       # Justice Laws XML → Canadian

pages = handbook.international_pages(
    handbook.split_pages(handbook.run_pdftotext(str(handbook_pdf))))
docs += handbook.parse_international(pages, handbook_pdf.name)  # pdftotext text layer → International

The three sources, each chosen to be machine-parseable:

US Inland   →  eCFR versioner API XML (33 CFR Parts 83–88)         → rules/inland/*.md
Canadian    →  Justice Laws XML (C.R.C., c. 1416)                  → rules/canadian/*.md
International →  pdftotext on the USCG handbook's text layer        → rules/international/*.md

One command rebuilds the whole vault:

uv run python scripts/build_vault.py \
  --handbook "/path/to/Nav Rules Handbook_Corrected_08-12-2024.pdf"

Result: 135 generated files, zero filter errors — handling the exact same material that blocked 11 times when it went through model output. Each file is a small markdown doc with a structural frontmatter block and the rule body (frontmatter shape only, no rule prose):

---
number: '5'
regime: international
part: B
title: "Look-out"
verified: false
source_pdf: Nav Rules Handbook_Corrected_08-12-2024.pdf p. 19
---

The one-line reason it works: the model's output is the parser (novel code), and the corpus text moves file-to-file without ever being emitted by the model.

Why it matters / gotchas

This is the better architecture for a safety-critical corpus anyway. The filter forced an upgrade:

No hallucination or paraphrase risk. A deterministic parser copies bytes; it doesn't "mostly" reproduce a rule. For navigation rules — where a dropped not changes who gives way — that's not a nicety.
Byte-identical rebuilds. Pin the sources, re-run, get the same vault. The build here is all-or-nothing: it validates the full rule set (expected rule numbers per regime, non-empty prose, no print artifacts, plausible titles) before writing a single file.
Human review shrinks. Instead of proofreading every transcribed line, a reviewer spot-checks the parser against a sample. Deterministic extraction means a clean sample validates the whole batch.

A few traps we hit, useful if you go this route:

Review by diff and sampling, never by printing. Echoing extracted prose back into the conversation re-trips the filter even after a clean build. Verification asserts structure — counts, rule numbers, titles, first characters — never long prose strings. The Canadian parser, for instance, enforces a fidelity invariant: it raises if flattening a provision loses any word character (re.sub(r"\W", "", ...) on input vs. output must match), so correctness is a code assertion, not a human reading the text.
Real-source XML has dialects. The eCFR tables are HTML-style TR/TD, not the CALS ROW/ENT you might assume from other government XML — we silently dropped a whole table before catching it in review. EXTRACT blocks nest and need recursion. The handbook's text layer wraps section headings mid-line, producing fragments that masquerade as content. Determinism doesn't mean trivial; it means debuggable — the failures are in code you can read and test, not in a model's mood this turn.
It fails closed, loudly. A parser that hits an unhandled element raises with the tag name so you go look, rather than quietly emitting a paraphrase. That's the opposite of the transcription failure mode, where the model would happily "fix up" text it found awkward.

The general rule, well beyond rules of the road: any "build a structured corpus from a document" task — re-ingesting a pilot book, turning equipment manuals into spec cards — should extract deterministically, not transcribe. If the source is copyrighted, the filter will trip harder, and you want the deterministic pipeline regardless, for fidelity. The output filter is annoying when it false-positives on a LICENSE file, but on a corpus-ingestion task it's pointing you at the architecture you should have picked first.

Close

This came out of building an AI ops layer for an all-electric charter catamaran — a stack of MCP servers behind a local LLM and a Home Assistant voice front-end, one of which answers questions about the navigation rules of the road. The vault and its build pipeline are open source: github.com/sailingnaturali/colregs-vault (the deterministic scripts/build_vault.py), consumed by colregs-mcp. If you've been fighting Output blocked by content filtering policy on a transcription task, the move is the same: stop transcribing, start parsing.

Why we kept named MCP tools despite a 96% token saving

Bryan Clark — Wed, 24 Jun 2026 00:13:14 +0000

The boat-agent stack here runs on a prime directive: if there's something usable out there, improve it; build our own only as a last resort. So when we needed a SignalK MCP server, the honest first move wasn't to write one — it was to evaluate the one that already exists.

VesselSense/signalk-mcp-server (TypeScript, MIT) is good work. It exposes SignalK to an agent through a single execute_code tool: the model writes JavaScript, the server runs it in a sandboxed V8 isolate (isolated-vm), and only the result comes back. Its README claims a 90–96% token reduction versus traditional named MCP tools — 2,000 tokens down to 120 for a vessel-state query, 13,000 down to 300 for a multi-call workflow. Those numbers are plausible, and they line up with the broader industry result that code execution beats tool-calling on token efficiency for complex multi-step work.

We read it, ran the numbers against our own agent, and kept our discrete-named-tool signalk-mcp anyway — then harvested three of VesselSense's ideas into our roadmap. This post is that evaluation: the two philosophies, why the obvious-sounding win doesn't bind for a voice-first agent, and a decision framework you can reuse before you adopt-or-build your own MCP server.

This is a design-reasoning post, not a debugging saga, but it maps to the same arc: a question, the dead-end that looks like an obvious yes, and the call that actually held.

The question

Two SignalK MCP servers, two genuinely different designs:

VesselSense/signalk-mcp-server      sailingnaturali/signalk-mcp
─────────────────────────────       ───────────────────────────
one tool: execute_code              discrete named tools:
  → agent writes JavaScript           read_sensor(path)
  → runs in a V8 isolate              battery_state(bank)
  → queries SignalK, returns          depth_state()
    only the result                   get_route()
                                      get_local_time()
TypeScript / Node + isolated-vm       list_paths(prefix)
claims 90–96% fewer tokens            get_active_alarms()
                                    Python, end-to-end

The adopt-vs-keep question: does the token-efficiency win bind for our agent? If it does, adopting beats maintaining a second server. If it doesn't, the directive doesn't compel adoption — it compels building the right thing for the target.

The target matters more than anything else here. Our design anchor is a voice-first agent on a small local model — Hermes 3 8B driving a text-to-speech front end on a boat. Not a frontier model in a chat window. That single fact decides the whole evaluation.

Two valid philosophies, different targets

execute_code is clever, and the token math is real. When an agent needs to fetch every AIS target, filter to the close ones, sort by CPA, and format a summary, the named-tool pattern pays the full input+output token cost of every intermediate call — the model emits a structured call, the whole result flows back into context, repeat. Code execution collapses that into one script and one aggregated result. On a frontier model doing complex, multi-step marine queries, the 90–96% claim is believable.

But the saving is paid for in one currency: the agent must reliably write correct code. That's a cheap price for a frontier model and an expensive one for an 8B. The capability gap here is not subtle. From the field:

Small models like llama3.2:3b and llama3.1:8b support tool calling specs but fail inconsistently in practice, especially on sequential or multi-entity commands… Tool calling is the biggest capability gap between local and cloud models — the plumbing exists but model reliability doesn't yet.

If a small model is shaky at emitting a structured tool call, asking it to emit correct JavaScript is strictly harder. execute_code doesn't reduce the model's burden for our agent — it raises it. The token budget was never our binding constraint; reliability is.

So the comparison isn't "which design is better." It's:

Frontier model, complex queries, token budget is the constraint → execute_code wins. Adopt VesselSense.
Small local model, voice front end, reliability is the constraint → discrete named tools win. A named tool with one argument — battery_state("house") — is the most robust thing you can hand an 8B. It cannot get the JavaScript wrong because there is no JavaScript.

Both are correct. They're tuned for different agents.

Why the token win doesn't bind #1: the speech contract

Here's the part the token comparison silently drops. Our tools don't return raw SignalK — every value carries a TTS-safe display string the agent can speak verbatim. SignalK stores everything in SI units and terse codes; a TTS engine mispronounces all of it. Our response contract makes the spoken form a first-class field:

{
  "path": "environment.wind.speedApparent",
  "value": 8.5,
  "display": "16.5 knots",
  "unit": "knots",
  "timestamp": "2026-05-18T00:00:00Z"
}

{
  "bank": "house",
  "soc_fraction": 0.68,
  "voltage": 12.84,
  "current": -8.2,
  "display": "68 percent, 12.8 volts, 8.2 amps discharging",
  "timestamp": "2026-05-14T18:00:00Z"
}

The rules behind that display: spelled-out units ("knots", never "kn"), spelled-out compass points ("North-East", never "NE"), cardinal-name lat/lon, no °T suffix a TTS engine reads as letters, no ISO timestamp narrated digit by digit. Position is the instructive case — the raw {latitude, longitude} dict stays in value for programmatic use, but the agent speaks display, never the raw pair.

execute_code returns whatever the agent's script returns — raw SignalK. That pushes all of this formatting onto the agent, which is exactly the layer that fails on a small model. We've written before about why formatting belongs in the tool layer, not the prompt: a prompt rule is advisory and leaks; the tool response is deterministic. execute_code is the maximal version of pushing formatting onto the model — it doesn't just leak the contract, it has no place to put one. For a voice-first agent that's disqualifying, and no token saving buys it back.

Why the token win doesn't bind #2: 404-as-null and the circuit breaker

The second structural reason is error handling. A SignalK 404 is not an error in our client — it means the vessel doesn't publish that path (no such sensor, or a guessed path). The client returns a clean null instead of raising:

# read_sensor on a path the vessel doesn't publish
{ "path": "navigation.headingTrue", "value": None, "display": None,
  "unit": None, "timestamp": None }   # not an exception

This is deliberate, and it's a small-model lesson. Agent runtimes commonly run a per-tool circuit breaker — ours (Hermes) trips after 3 consecutive same-tool failures. A small model fanning out across guessed paths on an unfamiliar vessel — headingTrue, headingMagnetic, courseOverGroundTrue — on a boat with no compass would generate a burst of 404s, each counted as a tool failure. That trips the breaker and blocks the valid reads queued behind it. Returning a clean null keeps a missing path a successful call, so the breaker never trips on absence.

Under execute_code, a missing path is whatever the SignalK client throws inside the isolate, and the agent has to catch and interpret it in code it wrote — on a model that's already at the edge of writing correct code. The named-tool design makes "this sensor doesn't exist" a normal, non-fatal result by construction. That's a reusable lesson for any MCP author building for small models: decide what your tool does on absence, and make absence a success, not a fault.

The coverage audit: receipts, not vibes

A "prefer adopting" directive still demands a coverage audit — does the existing tool actually do the job, or does it leave the work to the agent? We diffed feature by feature.

Active alarms. VesselSense's getActiveAlarms() returns alarms with their state and leaves filtering and sorting to client-side code in the isolate — its own example filters with a.state === "alarm" || a.state === "emergency" in agent-written JS. Normal-state notifications stay in the result; there's no severity ordering. Ours does that work in the tool, so the agent never writes a filter:

# signalk-mcp: get_active_alarms does the filtering + ordering in-tool
_ALARM_SEVERITY = {"emergency": 0, "alarm": 1, "warn": 2, "alert": 3}
_INACTIVE_STATES = {"normal", "nominal"}

# normal/nominal dropped; rows sorted worst-severity-first
rows.sort(key=lambda r: _ALARM_SEVERITY.get(r["state"], 99))

It also strips the notifications. prefix off each path so the result feeds straight into our downstream alarm-explanation tooling. Worst-first, normal filtered out, paths cleaned — no JavaScript required.

Missing tools. VesselSense's getVesselState dumps the SignalK tree and lets the agent dig. We have no equivalent dump tool — instead we ship purpose-built ones the dump would otherwise require the agent to assemble: battery_state, depth_state (under-keel clearance first, so the agent answers "how close are we to running aground?" without draft math), get_route, get_local_time (GPS-aware timezone). Each returns the speakable, contract-compliant answer directly.

The pattern across the audit: VesselSense pushes the last mile of work — filter, sort, format, interpret — into agent-written code, which is exactly the work a small model is worst at. That's not a flaw in VesselSense; it's the correct division of labor for a frontier model. It's the wrong division for ours.

The maturity audit (still matters under "prefer adopting")

Adopting code means inheriting its maintenance. The public signals on the upstream repo, at evaluation time:

last push      2025-11-26   (6+ months dormant)
stars          8
MCP SDK        @modelcontextprotocol/sdk pinned ^0.5.0  (two majors behind)
license        MIT in package.json; no LICENSE file in the repo tree
runtime        Node + native isolated-vm  (our stack is Python end to end)

None of these is damning on its own. Together they say: adopting means taking on a dormant codebase, in a second language runtime, with a native sandbox dependency (isolated-vm), pinned to an MCP SDK two majors back — to gain a token efficiency our agent doesn't spend. The maintenance cost is real and the benefit doesn't land. That's the directive not compelling adoption, on the merits.

The decision framework (reuse this)

Strip out the marine specifics and this is a general adopt-vs-build checklist for an MCP server:

Name the target agent first. Frontier model or small/local? Chat or voice/TTS? The target decides which currency you're optimizing — tokens or reliability. Most disagreements about MCP design are actually disagreements about the target.
Identify the binding constraint. Is your token budget the wall, or is model reliability the wall? execute_code trades reliability for tokens. Only adopt it if tokens are the wall.
Check who does the last mile. Does the existing tool filter/sort/format/interpret, or hand that to agent-written code? For a small model, every line of last-mile code you push to the agent is a failure mode.
Check the output contract. If output is consumed by something with formatting needs (TTS, a strict downstream parser), a raw-data tool externalizes that contract onto the model. Named tools can bake it in.
Decide what absence means. Make "the thing isn't there" a successful result, not an exception — especially behind a circuit breaker, especially for a model that guesses paths.
Run the maturity audit anyway. Dormancy, pinned-back SDKs, a second runtime, native deps. Adopting is inheriting.
Steelman, then harvest. If you build your own, still mine the alternative for ideas. A "no" on the architecture isn't a "no" on every idea in it.

The honest steelman, and what we harvested

We didn't dismiss VesselSense — we mined it. Three ideas went straight onto our roadmap from reading their server:

get_active_alarms — shipped (v0.5.0). Active notifications, worst-severity-first, normal filtered out, paths prefix-stripped for downstream tooling.
list_paths — shipped (v0.3.0). Path discovery so the agent can explore an unfamiliar SignalK tree without guessing — and without tripping the 404 circuit breaker.
AIS targets — open on the roadmap, with the same speech contract ("cargo vessel, 1.2 nautical miles, bearing North-East").

And execute_code stays on the watch-list. The day we add a cloud-reasoning layer — a frontier model doing complex multi-step marine analysis where the token budget genuinely is the wall — code execution is the right tool and we'll reach for it. The evaluation isn't "named tools are better." It's "named tools are better for this agent, and here's exactly when that flips."

If you're driving SignalK with a frontier model and want maximum query flexibility, VesselSense is likely the better choice — it's well-built and worth your time. If you want simple, reliable, speakable tools for a local or voice-first agent, that's the niche our server fills.

Close

This came out of building an AI ops layer for an all-electric charter catamaran, where the agent runs on a small local model behind a Home Assistant voice front end, and "what's our battery?" has to come back as something a human can hear — reliably, every time, on an 8B. The server is open source, and so is the comparison baked into its README: github.com/sailingnaturali/signalk-mcp. Go read VesselSense too — different target, good work.

Why generic weather MCPs fail for marine navigation (use NDBC buoys)

Bryan Clark — Wed, 24 Jun 2026 00:13:11 +0000

We run a prime directive on this stack: if a usable tool already exists, improve it; build our own only as a last resort, and when you keep your own, record why each alternative failed. This post is that audit for weather-mcp — a marine-weather MCP server — against the weather-MCP ecosystem, and the one capability change that fell out of it.

The short version: three perfectly good weather MCP servers exist, and none of them does the thing a navigator actually needs. The reasons generalize to any "adopt an MCP server or keep your own" call, so the audit is the post. Then the fix — parsing a second NDBC file format to split swell from wind waves — is small enough to paste in full, and it surfaced data the standard file had thrown away.

The problem, as you'd search it

You want an agent to answer "what are the seas doing where we are?" and you go looking for a marine weather MCP. You find a few. Each one returns a forecast. None of them returns what a buoy 12 nautical miles away is measuring right now. That gap — forecast vs. observed — is the entire job, and it's the one thing the ecosystem skips.

Here's what's on the shelf, and what each one is missing for marine use.

The candidates

Three real servers, all worth your time for what they're built for:

cmer81/open-meteo-mcp           ~13 tools, raw Open-Meteo JSON straight through
weather-mcp/weather-mcp         ~12 tools, own format, global; marine = Open-Meteo
RyanCardin15/NOAA-Tides...      CO-OPS stations: water levels + currents, not buoys

And ours:

sailingnaturali/weather-mcp     4 tools, Python, 2 runtime deps (httpx + mcp)
  get_marine_forecast            Open-Meteo wind/swell/wind-wave/seas/pressure
  get_marine_forecast_premium    Stormglass blend — 10 tokens/UTC-day, cache hits free
  get_nearest_buoy_observations  NDBC observed wind + waves by lat/lon, with bearing + age
  get_stormglass_quota_status    token-ledger read, no network

Mapped against what a navigator needs:

Capability	ours	open-meteo-mcp	weather-mcp/weather-mcp	NOAA-Tides
Open-Meteo marine (swell / wind-wave split)	yes	yes (raw JSON)	yes (own format)	no
NDBC nearest-buoy observations by lat/lon	yes	no	no	no (CO-OPS stations, not buoys)
Quota-aware premium tool design	yes	no	no	no
TTS-safe `{value, display}` contract	yes	no	no	no
Tools exposed to the agent	4	~13	~12	25+

The weather-mcp/weather-mcp README is admirably honest about the gap — for marine it routes to the Open-Meteo Marine API, which is a forecast model, not an observation. None of these is a bad server. They're built for a chat-window agent asking general weather questions. We're building for a voice-first agent on a small local model doing navigation. Different target, different binding constraints.

Three failure axes that generalize

Strip out the marine specifics and the audit comes down to three things a generic server can't give an agent, plus one that hurts small models specifically.

1. Buoy ground-truthing — observations, not just forecasts

The core doctrine is "forecast vs. observed, lead with the observation." A forecast says the seas should be 1.5 m; a buoy 12 nm upwind says they are 2.4 m and building. The agent should say the second thing. No generic weather MCP does observations at all — they're all forecast APIs. The NDBC realtime network is the data source, and wrapping it is the whole reason our server exists.

2. Quota-aware tool design

The premium provider (Stormglass) has a hard free-tier wall: 10 requests per UTC day. An agent that can't see that budget will burn it in one chatty session. So the budget has to be expressible in the tool surface itself — a paid tool and a free "how many tokens are left?" tool, paired:

# get_stormglass_quota_status — no network, just reads the ledger
def get_stormglass_quota_status(quota: StormglassQuota) -> dict:
    ...   # used / remaining for the current UTC day

"This call costs 1 of 10 daily tokens; cache hits are free" is a design property of the tool surface, not a footnote in a README. No generic server models cost, because for a free forecast API there's no cost to model.

3. The display contract

Every value our tools return carries a pre-formatted, TTS-safe display string the agent speaks verbatim — because small local models mangle re-formatting, and a text-to-speech engine mispronounces raw units and codes. (We've written before about why formatting belongs in the tool layer, not the prompt.) A server that returns raw API JSON pushes that formatting onto the model — the exact layer that fails. Generic servers return raw or near-raw payloads. That's correct for a frontier model in a chat window and disqualifying for ours.

And: tool-count bloat

4 tools vs. ~13, ~12, 25+. The MCP field has converged on a real number here: tool-selection accuracy on smaller models degrades as the surface grows, and the common advice is to keep a server in the 5–8 range and split domains past ~15. A curated 4-tool surface isn't minimalism for its own sake — it's the thing that keeps an 8B picking the right tool.

The decision: keep, with receipts

Per the directive, every alternative gets a recorded reason:

open-meteo-mcp — covers only the Open-Meteo forecast leg, returns raw JSON (breaks the display contract), ~13 tools. No buoys, no premium, no observations.
weather-mcp/weather-mcp — same gaps, more tools, marine is forecast-only by its own README.
NOAA-Tides — CO-OPS water levels and currents; overlaps a tide server's domain, not a wave-observation server's. No buoy waves, no forecasts.
Splitting (someone's forecast + our buoys) — doubles config surface and the most-called tool loses the display contract.

Keep ours. Now close its biggest documented gap.

The honest twist: a library-level adopt we also rejected

"Prefer adopting" doesn't stop at servers — there's a library that does exactly the NDBC parsing we hand-roll: CDJellen/ndbc-api, a well-maintained Python package for NDBC data. The directive says use it. We didn't, and the reason is a clause worth naming out loud: install weight is an adoption barrier for a uvx-installable server.

ndbc-api pulls a scientific-computing stack — pandas, numpy, scipy, xarray, h5netcdf, beautifulsoup4, html5lib. Adopting it to replace ~220 lines of whitespace-table parsing would take the server from 2 runtime dependencies to ~9:

weather-mcp today:   httpx, mcp
with ndbc-api:       httpx, mcp, ndbc-api
                       └─ pandas, numpy, scipy, xarray, h5netcdf, beautifulsoup4, ...

For a server people install with uvx weather-mcp, every transitive dependency is cold-start latency and a bigger surface to break. We're optimizing the public artifact, not just our own runtime. Adopt-first has a dependency-weight escape clause, and this is what it looks like in practice. So: keep the hand parser, and extend it.

The fix: parsing NDBC `.spec` to split swell from wind waves

Our biggest documented limitation was sitting in the buoy tool itself. The standard NDBC realtime file (realtime2/{station}.txt) reports combined significant wave height only — one number that smears swell and local wind chop together. For navigation that distinction matters: 0.4 m of short-period wind chop is a different sea state than 0.4 m of long-period swell from a distant storm.

NDBC publishes the separation in a second file alongside the .txt — realtime2/{station}.spec — same whitespace-table format, with swell and wind waves broken out. The header:

#YY  MM DD hh mm WVHT  SwH  SwP  WWH  WWP SwD WWD  STEEPNESS  APD MWD
2026 06 06 04 10  0.4  0.1  6.2  0.4  2.9 WSW   W        N/A  2.9 273

SwH / SwP / SwD — swell height (m), period (s), direction (compass string)
WWH / WWP / WWD — wind-wave height, period, direction
STEEPNESS — qualitative, may be N/A; MM marks missing values, same as .txt

The parser mirrors the existing .txt parser — first data row, MM-as-None, directions kept as compass strings (no degree round-trip, because the display layer wants "WSW" not 247°):

def parse_spec(text: str) -> SpecWaves | None:
    """Parse the first data row of a realtime2 .spec response.

    Directions arrive as compass strings (e.g. 'WSW') and are kept as-is.
    Returns None if there are no data rows or every wave field is missing.
    """
    rows = [ln for ln in text.splitlines() if ln.strip() and not ln.startswith("#")]
    if not rows:
        return None
    cols = rows[0].split()
    if len(cols) < 13:
        return None
    yyyy, mm, dd, hh, mn = cols[0:5]
    try:
        observed = datetime(int(yyyy), int(mm), int(dd), int(hh), int(mn), tzinfo=timezone.utc)
    except (TypeError, ValueError):
        return None
    spec = SpecWaves(
        observed_utc=observed,
        swell_height_m=_maybe_float(cols[6]),
        swell_period_s=_maybe_float(cols[7]),
        swell_dir_compass=_maybe_str(cols[10]),
        wind_wave_height_m=_maybe_float(cols[8]),
        wind_wave_period_s=_maybe_float(cols[9]),
        wind_wave_dir_compass=_maybe_str(cols[11]),
        steepness=_maybe_str(cols[12]),
    )
    if spec.swell_height_m is None and spec.wind_wave_height_m is None:
        return None
    return spec

Two files, two failure modes, so the merge degrades gracefully. The .spec is fetched concurrently with the .txt, and a missing or stale .spec (404, or an observation time skewed more than an hour from the .txt row) just drops the swell fields — the tool output is byte-identical to the old combined-only behavior:

MAX_SPEC_SKEW_S = 3600  # .spec off the .txt row by >1h → treat as stale

def merge_spec(obs: BuoyObservation, spec: SpecWaves | None) -> BuoyObservation:
    if spec is None:
        return obs
    if abs((obs.observed_utc - spec.observed_utc).total_seconds()) > MAX_SPEC_SKEW_S:
        return obs
    return replace(obs, swell_height_m=spec.swell_height_m, ...)

# both files, one round trip; .txt is the source of truth, .spec only enriches
txt_text, spec_text = await asyncio.gather(
    _get_text_or_none(client, txt_url),
    _get_text_or_none(client, spec_url),
)
if txt_text is None:
    return None
obs = parse_realtime2(txt_text, station, ref_lat, ref_lon)
spec = parse_spec(spec_text) if spec_text is not None else None
return merge_spec(obs, spec)

The merged observation rides the existing cache key; the .spec is never fetched on its own, so it needs no cache key of its own. And the absence case stays honest in the output — the note only appears when separation is actually missing:

if not has_spec:
    wave_block["note"] = (
        "combined waves only — this station's .spec swell separation is unavailable or stale"
    )

The receipt

This isn't theoretical. Pulled live from station 46088 (New Dungeness), the standard .txt file reported no combined wave height at all — WVHT came back MM, missing. The .spec file, same station, same minute, had the separation:

.txt   →  WVHT MM            (no combined wave height — missing)
.spec  →  swell 0.1 m WSW at 5.6 s, wind wave 0.4 m W

The separation didn't just refine an existing number — it surfaced wave data that was invisible in the file everyone parses. The combined field was missing; the component fields were there the whole time, in a file most NDBC wrappers ignore. ~60 lines plus tests, two new runtime dependencies (zero), one closed gap.

Why it matters

The reusable lesson isn't about waves. It's that an MCP server's value to an agent is the tool design — how it handles absence, whether it models cost, what contract its output guarantees — not API-coverage breadth. Three servers with more tools and broader coverage each failed the same navigator on the same three axes: no observations, no quota awareness, no speakable output. Coverage is easy to add and easy to find; design for a specific agent is the part you can't adopt off the shelf.

And the dependency-weight clause cuts the other way against "always adopt the library": for a tool people install with one command, ~220 lines of stdlib parsing can be the right call over a maintained package, when the package drags a scientific-computing stack behind it. Adopt-first, with an escape clause you can defend.

Close

This came out of building an AI ops layer for an all-electric charter catamaran, where the weather agent has to ground its forecasts against real buoys and say the answer out loud, on a small local model, reliably. The server and the audit baked into its README are open: github.com/sailingnaturali/weather-mcp. Go read the three servers above too — all good work, just built for a different boat.

DEV Community: Bryan Clark

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

Problem

The two planes

The bridge

Why anchor at the org repo

Takeaway

Monitor the delivery path, not just the alarm

The problem: a failure with nothing to fail

Diagnosis: isolate the leg that's failing

What we tried first (and why it wasn't enough)

The fix: a delivery-path health check inside the relay

Why it matters / gotchas

Close

MQTT value_template doesn't filter: our wait fired on every message

A hands-free npm publish pipeline for SignalK plugins

A pipeline is two kinds of work

The judgment half: three composable skills

Scaffold (and the files array that ships nothing)

First publish: the chicken-and-egg

OIDC: the publish workflow

Continuous mode: the release is the trigger

The workflows that keep it honest

Tracking updates without dragging in a dead tag

The score is a checkable bar, not a vibe

The shape of it

When MCP tools break, isolate the server before blaming the agent

Problem

Diagnosis

What we tried (and why it failed)

Dead-end 1 — trusted the agent's "tools unavailable"

Dead-end 2 — restarted the long-running gateway daemon

Dead-end 3 — re-probed ad-hoc, still "unavailable"

The fix

Step 1 — test the MCP server standalone

Step 2 — reproduce with the exact production invocation

Why it matters / gotchas

Close

How LLM agents confabulate infrastructure and data provenance

Problem

Flavor 1 — inventing infrastructure it can't observe

Flavor 2 — narrating data provenance it was never told

Diagnosis

What we tried (and why it failed)

Attempt 1 — warn the model about the gap

Attempt 2 — tell it not to hallucinate

Attempt 3 — list the right facts so it stops guessing wrong

The fix

1. Ground the real, observable facts — so there's no gap to fill

2. An explicit anti-provenance rule in the always-on persona

3. Audit the prompt for words you don't want spoken — and remove them

4. Belt and suspenders — guard in the tool layer

Why it matters / gotchas

Close

An MCP 404 trips the circuit breaker and drops valid reads

Problem

Diagnosis

What we tried (and why it failed)

Attempt 1 — raise on every non-2xx (the starting point)

Attempt 2 — just bump the breaker threshold

Attempt 3 — retry the failed calls

Attempt 4 — fix it in the prompt

The fix

Why it matters / gotchas

Close

Logging VHF DSC distress calls in SignalK (PGN 129808)

The test sentence — try it without a radio

Gap 1: the 0183 hook misses sparse distress alerts — and persists nothing

Gap 2: $--DSE position refinement, which the stock parser ignores entirely

Gap 3: n2k-signalk has no PGN 129808 mapping at all

Alarms under your own vessel — and surviving a restart

Voice-sized message vs. full log detail

Why a log, specifically

The shape of it

Why your agent ignores its skill body but obeys the system prompt

Problem

Diagnosis

What we tried (and why it failed)

Attempt 1 — edit the skill body and redeploy

Attempt 2 — assume the file didn't deploy and re-check the disk

Scaffold (and the `files` array that ships nothing)

The fix: parsing NDBC `.spec` to split swell from wind waves