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
  • v0.1.0 eb68e69fd8

    v0.1.0
    All checks were successful
    CI / Build, vet, test, lint (pull_request) Successful in 1m30s
    Details
    CI / Build, vet, test, lint (push) Successful in 2m31s
    Details
    release / release (push) Successful in 5m7s
    Details
    Stable

    Ghost released this 2026-09-25 19:56:17 -06:00 | 3 commits to main since this release

    First release of mcp-ferryman.

    mcp-ferryman is a Go CLI that bridges MCP over STDIO to a remote HTTP MCP server (streamable HTTP or SSE). It's launched by an MCP client as a STDIO server and proxies all traffic to the remote endpoint — with support for custom HTTP headers, so authenticated remote servers work with any STDIO-only MCP client.

    Features

    • MCP STDIO ↔ streamable HTTP / SSE proxying (built on the official Go SDK github.com/modelcontextprotocol/go-sdk)
    • Custom HTTP headers for auth against remote MCP servers
    • Debug logging to stderr behind --debug

    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

    CI / Release automation

    • CI workflow — build, vet, test, and golangci-lint on pushes to main and PRs
    • Release workflow — on v* tags: cross-compiles static binaries (linux/darwin × amd64/arm64), generates SHA-256 checksums, and publishes them to the release

    Pre-release tags (e.g. v0.2.0-rc1) are automatically marked as prereleases.

    Downloads