mcpbridge

package
v0.2.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 8, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package mcpbridge relays MCP JSON-RPC messages between a stdio client and an MCP HTTP endpoint: termcp's streamable-HTTP /stream (the default) or its SSE transport (/sse), or any other MCP server speaking either one.

It is deliberately a dumb relay: every stdin line is POSTed verbatim, every reply is written to stdout verbatim, and no MCP semantics are interpreted — the client sees exactly what the server answers. stdout therefore carries nothing but MCP messages; diagnostics go to stderr.

Package mcpbridge relays MCP JSON-RPC messages between a stdio client and an MCP HTTP endpoint: termcp's streamable-HTTP /stream (the default) or its SSE transport (/sse), or any other MCP server speaking either one.

It is deliberately a dumb relay: every stdin line is POSTed verbatim, every reply is written to stdout verbatim, and no MCP semantics are interpreted — the client sees exactly what the server answers. stdout therefore carries nothing but MCP messages; diagnostics go to stderr.

Package mcpbridge relays MCP JSON-RPC messages between a stdio client and an MCP HTTP endpoint: termcp's streamable-HTTP /stream (the default) or its SSE transport (/sse), or any other MCP server speaking either one.

It is deliberately a dumb relay: every stdin line is POSTed verbatim, every reply is written to stdout verbatim, and no MCP semantics are interpreted — the client sees exactly what the server answers. stdout therefore carries nothing but MCP messages; diagnostics go to stderr.

Index

Constants

View Source
const BuiltinCommand = "termcp-mcp-bridge"

BuiltinCommand is the name a client execs to get Run in-process instead of a process. The internal SSH server intercepts the name before any exec, so it never reaches a PATH lookup: a caller that asks for it gets this relay, and what it relays is entirely in the arguments.

The point is the shape of the call, not the name. `termcp stdio <url>` is a second process reading its own stdin, which is what an extension template had to spawn to reach an HTTP MCP server; this is the same relay running inside the termcp that already owns the channel, so a template reaches a remote MCP server with no second binary, no PATH question, and no credential on a command line.

Variables

This section is empty.

Functions

func CommandHandler added in v0.2.8

func CommandHandler(ctx context.Context, in io.Reader, out io.Writer, errOut io.Writer, argv []string, via ViaDialer) int

CommandHandler parses BuiltinCommand's argv and runs the relay against the caller's stdio, returning the exit status the session should report.

argv is everything after the command name: the endpoint URL, then zero or more `--header Name=Value` pairs. It is a plain io-based function — no ssh types — so the only package that knows both the transport and the relay is the one wiring them together.

func RegisterBuiltin added in v0.2.8

func RegisterBuiltin(s *sshserver.Server, via ViaDialer)

RegisterBuiltin teaches an internal SSH server to serve BuiltinCommand in-process: a session that asks for it is handed to this relay, and the relay's own stdin/stdout/stderr are the SSH channel's. No process is spawned and no PATH is consulted, which is the whole reason an extension can reach an HTTP MCP server without a second binary to install.

via gives `--via <profile>` its meaning. A nil via refuses the flag rather than ignoring it: silently dialling from this machine when the caller asked to dial from there is how a template ends up talking to the wrong server.

func Run

func Run(ctx context.Context, cfg Config) error

Run bridges Config.In to the MCP endpoint until stdin reaches EOF, the server fails, or ctx is canceled. A nil return is a clean shutdown (stdin EOF, once in-flight replies have been flushed, or ctx cancellation); any other error is terminal for the bridge process.

Types

type Config

type Config struct {
	// URL is the full URL of the MCP HTTP endpoint, e.g.
	// http://127.0.0.1:18765/stream, or .../sse with SSE set.
	URL string
	// SSE selects the SSE transport: one GET event stream carries the message
	// endpoint (its first `endpoint` event), every reply, and server-initiated
	// messages; stdin lines are POSTed to the discovered message URL.
	SSE   bool
	Token string    // optional bearer credential: a plaintext token, or the hash string a hash-configured instance accepts
	In    io.Reader // MCP stdio input: newline-delimited JSON
	Out   io.Writer // MCP stdio output: MCP messages only
	Err   io.Writer // diagnostics; never carries protocol messages

	// Headers are extra request headers sent on every request. Token is the
	// conventional Authorization: Bearer case and stays a field of its own
	// because the command line has a flag for it; this is for the servers that
	// want something else (X-Api-Key, a tenant header). A name given here is
	// applied after the transport's own headers, so an explicit value wins.
	Headers map[string]string

	// KeepAlive, when > 0 on the streamable transport, is how often the bridge
	// pings the instance while it has no MCP session yet. The bridge process
	// itself is a client presence: an instance behind an idle countdown must
	// see an attached-but-silent bridge as a connection, or it exits under a
	// bridge that has simply not sent a message yet. Once initialize has
	// minted a session the listening GET stream is the presence and the pings
	// stop. The SSE transport needs none — its event stream is opened before
	// anything else.
	KeepAlive time.Duration

	// DialContext, when set, is the network dialer used for HTTP and SSE requests.
	// Used when the endpoint is reached through a remote host's network via an
	// SSH client dialer, rather than dialed directly from this machine.
	DialContext func(ctx context.Context, network, addr string) (net.Conn, error)

	// Via, when set, is the SSH profile name whose network carries the requests.
	// Parsed from `--via <profile>` on BuiltinCommand's argv.
	Via string
}

Config describes one bridge run. In and Out are required.

func ParseArgs added in v0.2.8

func ParseArgs(argv []string) (Config, error)

ParseArgs turns BuiltinCommand's argv into a Config. The endpoint is the one positional argument; every flag is a header, because a header is the only thing this form needs beyond the URL. An endpoint whose path ends in /sse selects the SSE transport, the same rule the CLI applies to a pasted URL, so the two forms cannot disagree about what a URL means.

A header is written either as `--header Name=Value` or as `--header=Name=Value`.

type ViaDialer added in v0.2.9

type ViaDialer func(ctx context.Context, profile string) (dial func(network, addr string) (net.Conn, error), release func(), err error)

ViaDialer turns a profile name into a dialer whose connections leave from that host, plus the release that ends the lease when the bridge does.

The lease is held for the bridge's whole lifetime rather than per request: a bridge issues many requests over one MCP session, and reacquiring per request would pay a handshake each time to reach the same host.

It is a function rather than the session manager so this package stays a relay — what a profile means and how its connection is kept warm is not this package's business. main supplies it, which is also where the dependency becomes visible in one line.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
⌂ 换网址