w33ble/mcp-ferryman
Watch
1
0
Fork
You've already forked mcp-ferryman
 0
Code Issues Pull requests Projects Releases 2 Packages Wiki Activity Actions
2 releases 2 tags
  • v0.2.0 ff8d6fbd2b

    v0.2.0
    All checks were successful
    CI / Build, vet, test, lint (push) Successful in 2m40s
    Details
    release / release (push) Successful in 1m6s
    Details
    Stable

    hijynx released this 2026-09-29 12:07:27 -06:00 | 1 commits to main since this release

    Resilient bridge: automatic reconnect, opt-in heartbeat liveness, and fail-fast connection errors.

    What's new

    • Reconnect with backoff (#3): retries initial connect and post-connect drops with 1x/2x/4x/8x backoff via --initial-retry-interval (default 5s, MCP_BRIDGE_INITIAL_RETRY_INTERVAL). Replays the stored initialize, sends notifications/initialized, then flushes stdin lines buffered while down. --max-disconnected-time (MCP_BRIDGE_MAX_DISCONNECTED_TIME, empty/0 = retry forever) caps how long to keep retrying. Per-call ErrRejected failures no longer kill the connection.
    • Opt-in heartbeat liveness (#4): --heartbeat (MCP_BRIDGE_HEARTBEAT, default off) sends an MCP ping after --heartbeat-interval (default 30s) with no traffic in either direction; a pong missing past --heartbeat-timeout (default 10s) drops into the normal reconnect path. Ping responses are never forwarded to stdout. With --heartbeat off, behavior is unchanged: no ticker, no pings.
    • Fail fast instead of hanging (#4): probe 401/403 is a fatal auth error, probe 404 reports endpoint-not-found, probe 5xx reports remote server error; auth failures on write/replay paths bypass the retry loop. Any failure before the first live session exits non-zero with a clear stderr message (previously: logged connected, retried forever on Forbidden, client timed out appearing hung).
    • Fix: flags placed after the positional URL are now honored (parseTrailingFlags was a no-op).

    Usage

    # Retry forever (default), 5s initial backoff
mcp-ferryman https://example.com/mcp

# Bound reconnect window, faster first retry
mcp-ferryman --max-disconnected-time 5m --initial-retry-interval 2s https://example.com/mcp

# Opt-in liveness detection on idle connections
mcp-ferryman --heartbeat --heartbeat-interval 30s --heartbeat-timeout 10s https://example.com/mcp

    Install

    Download a binary for your platform from the assets below (linux/darwin, amd64/arm64) and verify it against checksums.txt:

    sha256sum -c checksums.txt --ignore-missing

    macOS note: the darwin builds are unsigned, so Gatekeeper will block first launch. Clear the quarantine flag after downloading:

    xattr -d com.apple.quarantine ./mcp-ferryman-darwin-arm64

    Full diff: https://git.w33ble.com/w33ble/mcp-ferryman/compare/v0.1.0...v0.2.0

    Downloads