mcp_bridge.cpp File Reference

entropic mcp-bridge — stdio↔unix-socket relay for MCP. More...

#include <poll.h>
#include <sys/socket.h>
#include <sys/un.h>
#include <unistd.h>
#include <cerrno>
#include <cstdio>
#include <cstring>
#include <filesystem>
#include <string>

Include dependency graph for mcp_bridge.cpp:

Go to the source code of this file.

Namespaces
namespace	entropic
	Activate model on GPU (WARM → ACTIVE).

Functions
std::filesystem::path	entropic::compute_socket_path (const std::filesystem::path &project_dir)
	Compute project-unique Unix socket path for self-detection.
int	entropic::cli::run_mcp_bridge (int argc, char *argv[])
	Entry point for the mcp-bridge subcommand.

Detailed Description

entropic mcp-bridge — stdio↔unix-socket relay for MCP.

Pure protocol adapter. Connects to a running engine's external MCP unix socket and shuttles JSON-RPC 2.0 bytes between the local stdio pair (read from an MCP client like Claude Code) and the socket pair (read by the engine's ExternalBridge). The bridge:

• Never creates an engine handle. Never loads a model. Owns no state beyond two file descriptors.
• Discovers the socket path by hashing the canonicalized project directory (same compute_socket_path used by the engine), so .mcp.json consumers do not have to know the path.
• Fails fast with a diagnostic naming cwd, canonical path, hash, and computed socket path when no socket exists.

The relay is byte-transparent: it does not parse JSON-RPC at all, so server-initiated progress notifications, streaming, and out-of-order responses all pass through unmodified. Both sides use newline-framed messages (the wire convention established by the engine's ExternalBridge).

Usage in .mcp.json:

{"mcpServers": {"entropic": {
  "type": "stdio",
  "command": "entropic",
  "args": ["mcp-bridge"]
}}}

An engine must already be running for the same project directory (TUI, consumer app, or a future headless server). The bridge is an optional service on top of that engine — never a substitute for it.

MCP transport compliance

• Stdio framing: MCP stdio transport is newline-delimited JSON-RPC 2.0 (one message per line, UTF-8, no embedded newlines). The relay is byte-transparent and preserves framing because both the client (e.g. Claude Code) and the engine's ExternalBridge emit complete \n-terminated frames; the relay merely shuttles bytes in order.
• Stdout discipline: stdout is reserved for relayed JSON-RPC bytes only. All diagnostics go to stderr (per the MCP spec's stdio transport contract). The bridge writes nothing to stdout itself — no banners, no log lines, no flush noise.
• Bidirectional traffic: a poll(2) loop handles both directions independently, so server-initiated frames (notifications/progress, streaming partial results, etc.) reach the client even when no request is in flight. The pre-2.1.7 mcp-connect did synchronous request→response and would have stalled server-pushed frames.
• **initialize / notifications/initialized handshake**: the bridge is transparent — the handshake occurs end-to-end between the MCP client and the engine, exactly as the spec describes.
• **shutdown / exit**: handled by the engine's dispatch. On stdin EOF (client went away) the bridge half-closes the socket write side via shutdown(SHUT_WR), which the engine's serve_client observes as an empty read and uses to tear down the per-client thread cleanly.
• No protocol coupling: the bridge does not parse JSON-RPC at all, so future MCP protocol revisions ride through without needing changes here. The contract sits with the engine's ExternalBridge::dispatch.

Version

2.1.7

Definition in file mcp_bridge.cpp.

Function Documentation

run_mcp_bridge()

int entropic::cli::run_mcp_bridge	(	int	argc,
		char *	argv[]
	)

Entry point for the mcp-bridge subcommand.

Resolves the project dir, computes the engine's unix socket path via the same deterministic hash the engine uses, connects, then relays bytes between stdio and the socket until either side closes.

Parameters

argc	Argument count (after the "mcp-bridge" subcommand).
argv	Argument vector. argv[0] is "mcp-bridge".

Returns

0 on clean exit, 1 if no engine is reachable.

Definition at line 275 of file mcp_bridge.cpp.