mcp-switchboard-client 0.2.0__py3-none-any.whl

mcp_switchboard_client/__init__.py

@@ -0,0 +1,9 @@
+"""mcp-switchboard-client: tunnels local stdio MCP servers to a switchboard hub.
+
+A dumb pipe by design - it speaks no MCP and has no `mcp` dependency. It spawns
+the local servers listed in mcp.json and shuttles their stdin/stdout over one
+outbound WebSocket, tagged with the server name. Every MCP concern lives in the
+hub. See docs/PROTOCOL.md.
+"""
+
+__version__ = "0.2.0"

mcp_switchboard_client/__main__.py

@@ -0,0 +1,6 @@
+"""``python -m mcp_switchboard_client``."""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

mcp_switchboard_client/cli.py

@@ -0,0 +1,288 @@
+"""Console-script entry point: ``mcp-switchboard-client``.
+
+Settings come from the environment (prefix ``MCP_SWITCHBOARD_``), optionally
+seeded from a .env file, and every one of them can be overridden by a command
+line flag. Real environment variables win over the .env file; flags win over
+both.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import signal
+import socket
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import List, Optional, Sequence
+
+from . import envconf, protocol
+from .config import ConfigError as McpConfigError
+from .config import ServerSpec, load_config
+from .envconf import ConfigError
+from .tunnel import (
+    DEFAULT_MAX_RETRIES,
+    DEFAULT_RECONNECT_DELAY,
+    HubConnection,
+    TunnelError,
+    TunnelSettings,
+    normalize_hub_url,
+)
+from . import __version__
+
+PROG = "mcp-switchboard-client"
+DEFAULT_CONFIG_NAME = "mcp.json"
+DEFAULT_ENV_FILE_NAME = ".env"
+DEFAULT_LOG_LEVEL = "INFO"
+LOG_LEVELS = ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
+
+LOGGER = logging.getLogger("mcp_switchboard_client")
+
+
+@dataclass
+class Settings:
+    hub_url: str
+    token: str
+    label: str
+    config_path: Path
+    reconnect_delay: float = DEFAULT_RECONNECT_DELAY
+    max_retries: int = DEFAULT_MAX_RETRIES
+    log_level: str = DEFAULT_LOG_LEVEL
+
+    def tunnel_settings(self) -> TunnelSettings:
+        return TunnelSettings(
+            hub_url=self.hub_url,
+            token=self.token,
+            label=self.label,
+            reconnect_delay=self.reconnect_delay,
+            max_retries=self.max_retries,
+        )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog=PROG,
+        description=(
+            "Tunnel local stdio MCP servers to an mcp-switchboard hub over a single "
+            "outbound, authenticated WebSocket."
+        ),
+        allow_abbrev=False,
+    )
+    parser.add_argument("--version", action="version", version=f"{PROG} {__version__}")
+    parser.add_argument(
+        "--hub-url",
+        default=None,
+        help=f"Hub URL, e.g. wss://hub.example.com (or {envconf.PREFIX}HUB_URL)",
+    )
+    parser.add_argument(
+        "--token",
+        default=None,
+        help=(
+            f"Tunnel token, or the path to a file holding it "
+            f"(or {envconf.PREFIX}TUNNEL_TOKEN)"
+        ),
+    )
+    parser.add_argument(
+        "--label",
+        default=None,
+        help=(
+            f"Name this machine is tagged with in the hub, default the hostname "
+            f"(or {envconf.PREFIX}LABEL)"
+        ),
+    )
+    parser.add_argument(
+        "--config",
+        default=None,
+        help=(
+            f"MCP server config file, resolved against the current directory "
+            f"(default ./{DEFAULT_CONFIG_NAME}, or {envconf.PREFIX}CONFIG)"
+        ),
+    )
+    parser.add_argument(
+        "--env-file",
+        default=None,
+        help=f"Env file to load settings from (default ./{DEFAULT_ENV_FILE_NAME} if present)",
+    )
+    parser.add_argument(
+        "--reconnect-delay",
+        type=float,
+        default=None,
+        help=(
+            "Initial reconnect delay in seconds, doubling up to 60s "
+            f"(default {DEFAULT_RECONNECT_DELAY}, or {envconf.PREFIX}RECONNECT_DELAY)"
+        ),
+    )
+    parser.add_argument(
+        "--max-retries",
+        type=int,
+        default=None,
+        help=(
+            "Maximum reconnect attempts, 0 = infinite "
+            f"(default {DEFAULT_MAX_RETRIES}, or {envconf.PREFIX}MAX_RETRIES)"
+        ),
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=LOG_LEVELS,
+        default=None,
+        help=f"Log level (default {DEFAULT_LOG_LEVEL}, or {envconf.PREFIX}LOG_LEVEL)",
+    )
+    return parser
+
+
+def parse_args(argv: Optional[Sequence[str]] = None) -> argparse.Namespace:
+    # argparse rejects unknown arguments with a usage message and exit code 2,
+    # which is what we want: the shell installer forwards its args blindly.
+    return build_parser().parse_args(argv)
+
+
+def load_settings(args: argparse.Namespace) -> Settings:
+    """Resolve flags + env + .env into Settings, or raise ConfigError."""
+    env_file = Path(args.env_file) if args.env_file else Path.cwd() / DEFAULT_ENV_FILE_NAME
+    if args.env_file and not env_file.is_file():
+        raise ConfigError(f"env file not found: {env_file}")
+    envconf.load_env_file(env_file)
+
+    hub_url = args.hub_url or envconf.get("HUB_URL")
+    if not hub_url:
+        raise ConfigError(
+            f"no hub URL: pass --hub-url or set {envconf.PREFIX}HUB_URL"
+        )
+    try:
+        hub_url = normalize_hub_url(hub_url)
+    except TunnelError as e:
+        raise ConfigError(str(e)) from e
+
+    token = args.token or envconf.get("TUNNEL_TOKEN", secret=True)
+    if not token:
+        raise ConfigError(
+            f"no tunnel token: pass --token or set {envconf.PREFIX}TUNNEL_TOKEN "
+            "(either the token itself or the path to a file holding it)"
+        )
+
+    label = args.label or envconf.get("LABEL") or socket.gethostname()
+    try:
+        protocol.validate_name(label, "label")
+    except protocol.ProtocolError as e:
+        raise ConfigError(str(e)) from e
+
+    # The config path is resolved strictly against the current directory;
+    # there is no upward search for an mcp.json.
+    raw_config = args.config or envconf.get("CONFIG") or DEFAULT_CONFIG_NAME
+    config_path = Path(raw_config)
+    if not config_path.is_absolute():
+        config_path = Path.cwd() / config_path
+
+    reconnect_delay = (
+        args.reconnect_delay
+        if args.reconnect_delay is not None
+        else envconf.get_float("RECONNECT_DELAY", DEFAULT_RECONNECT_DELAY)
+    )
+    if reconnect_delay < 0:
+        raise ConfigError("reconnect delay must not be negative")
+
+    max_retries = (
+        args.max_retries
+        if args.max_retries is not None
+        else envconf.get_int("MAX_RETRIES", DEFAULT_MAX_RETRIES)
+    )
+    if max_retries < 0:
+        raise ConfigError("max retries must not be negative (0 means retry forever)")
+
+    log_level = (args.log_level or envconf.get("LOG_LEVEL") or DEFAULT_LOG_LEVEL).upper()
+    if log_level not in LOG_LEVELS:
+        raise ConfigError(f"unknown log level {log_level!r} (one of {', '.join(LOG_LEVELS)})")
+
+    return Settings(
+        hub_url=hub_url,
+        token=token,
+        label=label,
+        config_path=config_path,
+        reconnect_delay=reconnect_delay,
+        max_retries=max_retries,
+        log_level=log_level,
+    )
+
+
+def build_settings(argv: Optional[Sequence[str]] = None) -> Settings:
+    return load_settings(parse_args(argv))
+
+
+def load_servers(path: Path) -> List[ServerSpec]:
+    """Load the MCP config, rejecting names the hub could never accept."""
+    specs = load_config(path)
+    for spec in specs:
+        try:
+            protocol.validate_name(spec.name, "server name")
+        except protocol.ProtocolError as e:
+            raise McpConfigError(f"{e} (in {path})") from e
+    return specs
+
+
+def setup_logging(level: str) -> None:
+    logging.basicConfig(
+        level=getattr(logging, level, logging.INFO),
+        format="%(asctime)s %(name)s %(levelname)s: %(message)s",
+        datefmt="%Y-%m-%dT%H:%M:%S",
+        stream=sys.stderr,
+    )
+
+
+async def _run(settings: Settings, specs: List[ServerSpec]) -> None:
+    connection = HubConnection(specs, settings.tunnel_settings(), version=__version__)
+
+    def request_stop() -> None:
+        LOGGER.info("shutdown signal received")
+        connection.request_stop()
+
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        try:
+            loop.add_signal_handler(sig, request_stop)
+        except (NotImplementedError, RuntimeError, ValueError):
+            # Windows event loops, and loops not running on the main thread.
+            try:
+                signal.signal(sig, lambda *_a: request_stop())
+            except (ValueError, OSError):
+                LOGGER.debug("cannot install a handler for %s", sig)
+
+    LOGGER.info(
+        "tunneling %d server(s) as %s: %s",
+        len(specs),
+        settings.label,
+        ", ".join(spec.name for spec in specs),
+    )
+    await connection.run()
+    LOGGER.info("shutdown complete")
+
+
+def main(argv: Optional[Sequence[str]] = None) -> None:
+    args = parse_args(argv)
+    try:
+        settings = load_settings(args)
+    except ConfigError as e:
+        print(f"{PROG}: error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    setup_logging(settings.log_level)
+
+    try:
+        specs = load_servers(settings.config_path)
+    except McpConfigError as e:
+        print(f"{PROG}: error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        asyncio.run(_run(settings, specs))
+    except KeyboardInterrupt:
+        pass
+    except TunnelError as e:
+        print(f"{PROG}: error: {e}", file=sys.stderr)
+        sys.exit(1)
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

mcp_switchboard_client/config.py

@@ -0,0 +1,145 @@
+"""Load and normalize MCP server configs into a uniform list of ServerSpec.
+
+Two config shapes are supported (see README.md for the full discriminator rule):
+
+1. Plain ``mcpServers`` entries: ``{"command": ..., "args": [...], "env": {...}}``.
+   Spawned directly as the local stdio subprocess.
+2. FastMCP-style entries: any entry (or the whole config file, if it has no
+   ``mcpServers`` wrapper) that contains a top-level ``source`` key is treated
+   as a FastMCP config (https://gofastmcp.com/public/schemas/fastmcp.json/v1.json)
+   and launched via ``fastmcp run <generated-config>`` instead of being spawned
+   directly. The discriminator is exactly: presence of a ``source`` key.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+LOGGER = logging.getLogger("mcp_switchboard_client.config")
+
+
+class ConfigError(Exception):
+    """Raised for any problem loading or interpreting the config file."""
+
+
+@dataclass
+class ServerSpec:
+    """A single local MCP server to launch and tunnel."""
+
+    name: str
+    argv: List[str]
+    env: Dict[str, str] = field(default_factory=dict)
+    cwd: Optional[str] = None
+    # Set when this spec was materialized from a FastMCP-style entry, so the
+    # generated temp config file can be cleaned up on shutdown.
+    fastmcp_tempfile: Optional[Path] = None
+
+
+def load_config(path: Path) -> List[ServerSpec]:
+    """Load ``path`` and return the list of servers to tunnel.
+
+    Raises:
+        ConfigError: if the file is missing, not valid JSON, or doesn't match
+            either supported shape.
+    """
+    if not path.is_file():
+        raise ConfigError(
+            f"config file not found: {path} "
+            "(pass --config, or create ./mcp.json in the current directory)"
+        )
+
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise ConfigError(f"config file {path} is not valid JSON: {e}") from e
+
+    if not isinstance(raw, dict):
+        raise ConfigError(f"config file {path} must contain a JSON object at the top level")
+
+    if "mcpServers" in raw:
+        servers = raw["mcpServers"]
+        if not isinstance(servers, dict) or not servers:
+            raise ConfigError(f"'mcpServers' in {path} must be a non-empty object")
+        return [_build_spec(name, entry, path) for name, entry in servers.items()]
+
+    if "source" in raw:
+        # Whole file is a single bare FastMCP config.
+        name = raw.get("name") or path.stem or "fastmcp-server"
+        return [_build_fastmcp_spec(name, raw)]
+
+    raise ConfigError(
+        f"config file {path} matches neither the 'mcpServers' shape nor the "
+        "FastMCP single-server shape (missing both 'mcpServers' and 'source' keys)"
+    )
+
+
+def _build_spec(name: str, entry: Any, config_path: Path) -> ServerSpec:
+    if not isinstance(entry, dict):
+        raise ConfigError(f"mcpServers.{name} in {config_path} must be an object")
+
+    if "source" in entry:
+        return _build_fastmcp_spec(name, entry)
+
+    command = entry.get("command")
+    if not command or not isinstance(command, str):
+        raise ConfigError(
+            f"mcpServers.{name} in {config_path} must have a string 'command' "
+            "(or a 'source' key to be treated as a FastMCP-style server)"
+        )
+
+    args = entry.get("args", [])
+    if not isinstance(args, list) or not all(isinstance(a, str) for a in args):
+        raise ConfigError(f"mcpServers.{name}.args in {config_path} must be a list of strings")
+
+    env = entry.get("env", {})
+    if not isinstance(env, dict):
+        raise ConfigError(f"mcpServers.{name}.env in {config_path} must be an object")
+
+    cwd = entry.get("cwd")
+    if cwd is not None and not isinstance(cwd, str):
+        raise ConfigError(f"mcpServers.{name}.cwd in {config_path} must be a string")
+
+    return ServerSpec(name=name, argv=[command, *args], env={k: str(v) for k, v in env.items()}, cwd=cwd)
+
+
+def _build_fastmcp_spec(name: str, entry: Dict[str, Any]) -> ServerSpec:
+    """Materialize a FastMCP-style entry into a runnable ServerSpec.
+
+    We write the entry out verbatim (minus a forced transport override) as its
+    own fastmcp.json-shaped file and launch it with ``fastmcp run <file>``,
+    letting FastMCP itself handle the uv-based environment/source setup.
+
+    Only stdio transport can be tunneled by this tool (the wire protocol only
+    bridges stdin/stdout), so ``deployment.transport`` is forced to "stdio"
+    regardless of what the entry declares, with a warning if it was set to
+    something else.
+    """
+    fastmcp_config = dict(entry)
+    deployment = dict(fastmcp_config.get("deployment") or {})
+    original_transport = deployment.get("transport")
+    if original_transport and original_transport != "stdio":
+        LOGGER.warning(
+            "server %r declares deployment.transport=%r, but this tool only "
+            "tunnels stdio; overriding to stdio",
+            name,
+            original_transport,
+        )
+    deployment["transport"] = "stdio"
+    fastmcp_config["deployment"] = deployment
+
+    fd, tmp_name = tempfile.mkstemp(prefix=f"fastmcp-{name}-", suffix=".json")
+    tmp_path = Path(tmp_name)
+    with open(fd, "w", encoding="utf-8") as f:
+        json.dump(fastmcp_config, f)
+
+    return ServerSpec(
+        name=name,
+        argv=["uvx", "fastmcp", "run", str(tmp_path)],
+        env={},
+        fastmcp_tempfile=tmp_path,
+    )

mcp_switchboard_client/envconf.py

@@ -0,0 +1,117 @@
+"""Settings from the process environment and an optional .env file.
+
+This module is duplicated byte-for-byte into mcp_switchboard_client and
+mcp_switchboard_hub so neither package depends on the other.
+hub/tests/test_protocol_sync.py fails if the two copies drift.
+
+Path indirection: any value that starts with "/" and resolves to an existing
+regular file is replaced by that file's contents. That lets a secret be given
+either literally or as a path to a sops/systemd-provisioned file, with no
+separate *_FILE variants:
+
+    MCP_SWITCHBOARD_TUNNEL_TOKEN=literal-value
+    MCP_SWITCHBOARD_TUNNEL_TOKEN=/run/secrets/mcp-switchboard/tunnel-token
+
+Only regular files are substituted, never directories, so a genuine path value
+like MCP_SWITCHBOARD_DATA_DIR=/var/lib/mcp-switchboard survives untouched.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Optional
+
+PREFIX = "MCP_SWITCHBOARD_"
+
+
+class ConfigError(Exception):
+    """Raised for a malformed or unusable setting."""
+
+
+def load_env_file(path: Path) -> None:
+    """Populate os.environ from a KEY=VALUE file. Real env vars always win.
+
+    Lines that are blank, start with '#', or contain no '=' are ignored. There
+    is no interpolation and no 'export' keyword support - this is intentionally
+    minimal, matching the .env files people hand-write for this tool.
+    """
+    try:
+        lines = path.read_text(encoding="utf-8").splitlines()
+    except FileNotFoundError:
+        return
+    except OSError as e:
+        raise ConfigError(f"cannot read env file {path}: {e}") from e
+
+    for line in lines:
+        line = line.strip()
+        if not line or line.startswith("#") or "=" not in line:
+            continue
+        key, _, value = line.partition("=")
+        key = key.strip()
+        value = value.strip().strip("'\"")
+        if key and key not in os.environ:
+            os.environ[key] = value
+
+
+def resolve(value: str, *, secret: bool = False, name: str = "") -> str:
+    """Apply path indirection to a single value."""
+    if not value.startswith("/"):
+        return value
+
+    path = Path(value)
+    if path.is_file():
+        try:
+            return path.read_text(encoding="utf-8").strip()
+        except OSError as e:
+            raise ConfigError(f"cannot read {name or 'value'} from {value}: {e}") from e
+
+    if secret:
+        # Far more likely to be a secret that failed to materialize than a
+        # token that happens to look like an absolute path. Fail loudly rather
+        # than authenticating with the literal string "/run/secrets/...".
+        raise ConfigError(
+            f"{name or 'setting'} looks like a file path ({value}) but no readable file is there"
+        )
+    return value
+
+
+def get(name: str, default: Optional[str] = None, *, secret: bool = False) -> Optional[str]:
+    """Read PREFIX+name from the environment, with path indirection applied."""
+    key = PREFIX + name
+    raw = os.environ.get(key)
+    if raw is None or raw == "":
+        return default
+    return resolve(raw, secret=secret, name=key)
+
+
+def get_int(name: str, default: int) -> int:
+    raw = get(name)
+    if raw is None:
+        return default
+    try:
+        return int(raw)
+    except ValueError as e:
+        raise ConfigError(f"{PREFIX}{name} must be an integer, got {raw!r}") from e
+
+
+def get_float(name: str, default: float) -> float:
+    raw = get(name)
+    if raw is None:
+        return default
+    try:
+        return float(raw)
+    except ValueError as e:
+        raise ConfigError(f"{PREFIX}{name} must be a number, got {raw!r}") from e
+
+
+def get_bool(name: str, default: bool) -> bool:
+    raw = get(name)
+    if raw is None:
+        return default
+    lowered = raw.strip().lower()
+    if lowered in ("1", "true", "yes", "on"):
+        return True
+    if lowered in ("0", "false", "no", "off"):
+        return False
+    raise ConfigError(f"{PREFIX}{name} must be a boolean, got {raw!r}")

mcp_switchboard_client/protocol.py

@@ -0,0 +1,93 @@
+"""Tunnel protocol v1 frames. Spec: docs/PROTOCOL.md.
+
+This module is duplicated byte-for-byte into mcp_switchboard_client and
+mcp_switchboard_hub so that neither package has to depend on the other - the
+client deliberately carries no MCP dependency. hub/tests/test_protocol_sync.py
+fails if the two copies drift.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+PROTOCOL_VERSION = 1
+
+TUNNEL_PATH = "/tunnel/v1"
+
+HELLO = "hello"
+HELLO_ACK = "hello_ack"
+MCP = "mcp"
+SERVER_STATE = "server_state"
+RESTART = "restart"
+ERROR = "error"
+
+STATE_STARTING = "starting"
+STATE_RUNNING = "running"
+STATE_EXITED = "exited"
+STATE_FAILED = "failed"
+
+# Tools are exposed to consumers as {label}__{server}__{tool}, so neither a
+# machine label nor a server name may contain the separator.
+NAME_SEPARATOR = "__"
+
+
+class ProtocolError(Exception):
+    """Raised for a frame that cannot be acted on."""
+
+
+def validate_name(name: str, kind: str) -> str:
+    if not name:
+        raise ProtocolError(f"{kind} must not be empty")
+    if NAME_SEPARATOR in name:
+        raise ProtocolError(f"{kind} {name!r} must not contain {NAME_SEPARATOR!r}")
+    return name
+
+
+def hello(
+    client_name: str,
+    version: str,
+    instance: str,
+    label: str,
+    servers: List[Dict[str, Any]],
+) -> Dict[str, Any]:
+    return {
+        "type": HELLO,
+        "protocol": PROTOCOL_VERSION,
+        "client": {"name": client_name, "version": version, "instance": instance, "label": label},
+        "servers": servers,
+    }
+
+
+def hello_ack(connection_id: str, hub_name: str, hub_version: str) -> Dict[str, Any]:
+    return {
+        "type": HELLO_ACK,
+        "connectionId": connection_id,
+        "hub": {"name": hub_name, "version": hub_version},
+    }
+
+
+def mcp(server: str, payload: Any) -> Dict[str, Any]:
+    return {"type": MCP, "server": server, "payload": payload}
+
+
+def server_state(
+    server: str,
+    state: str,
+    exit_code: Optional[int] = None,
+    error: Optional[str] = None,
+) -> Dict[str, Any]:
+    return {
+        "type": SERVER_STATE,
+        "server": server,
+        "state": state,
+        "exitCode": exit_code,
+        "error": error,
+    }
+
+
+def restart(server: str) -> Dict[str, Any]:
+    return {"type": RESTART, "server": server}
+
+
+def error(message: str, server: Optional[str] = None) -> Dict[str, Any]:
+    return {"type": ERROR, "message": message, "server": server}

mcp_switchboard_client/supervisor.py

@@ -0,0 +1,219 @@
+"""One local stdio MCP server subprocess: spawn, pipe, supervise.
+
+This module knows nothing about MCP or about the tunnel. It owns a subprocess,
+hands every stdout line to a callback, writes lines to stdin on request, and
+reports lifecycle transitions (``starting`` / ``running`` / ``exited`` /
+``failed``) through a second callback so the tunnel can turn them into
+``server_state`` frames.
+
+A server that exits on its own is reported and left down: there is deliberately
+no automatic respawn, because a server that fails on startup would otherwise be
+restarted in a hot loop. It comes back on an explicit ``restart`` frame or on
+the next reconnect.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from contextlib import suppress
+from typing import Awaitable, Callable, Optional
+
+from . import protocol
+from .config import ServerSpec
+
+LOGGER = logging.getLogger("mcp_switchboard_client.supervisor")
+
+# How long a server gets to exit after SIGTERM before it is killed.
+TERMINATE_TIMEOUT = 5.0
+
+# asyncio's default StreamReader limit is 64 KiB, and readline() raises once a
+# line exceeds it. MCP tool results routinely do, so give stdout real headroom.
+STDOUT_LIMIT = 4 * 1024 * 1024
+
+# (server name, line)
+StdoutCallback = Callable[[str, str], Awaitable[None]]
+# (server name, state, exit code, error)
+StateCallback = Callable[[str, str, Optional[int], Optional[str]], Awaitable[None]]
+
+
+class LocalServer:
+    """A single local MCP server process."""
+
+    def __init__(
+        self,
+        spec: ServerSpec,
+        on_stdout: Optional[StdoutCallback] = None,
+        on_state: Optional[StateCallback] = None,
+    ) -> None:
+        self.spec = spec
+        self._on_stdout = on_stdout
+        self._on_state = on_state
+        self.log = logging.getLogger(f"mcp_switchboard_client.server.{spec.name}")
+
+        self._process: Optional[asyncio.subprocess.Process] = None
+        self._stdout_task: Optional[asyncio.Task] = None
+        self._state: Optional[str] = None
+
+    @property
+    def name(self) -> str:
+        return self.spec.name
+
+    @property
+    def state(self) -> Optional[str]:
+        return self._state
+
+    @property
+    def running(self) -> bool:
+        return self._process is not None and self._process.returncode is None
+
+    @property
+    def descriptor(self) -> dict:
+        """The entry this server contributes to the ``hello`` frame."""
+        return {"name": self.name, "command": " ".join(self.spec.argv)}
+
+    async def start(self) -> None:
+        """Spawn the process. A no-op if one is already claimed."""
+        if self._process is not None:
+            return
+
+        await self._emit_state(protocol.STATE_STARTING)
+
+        env = os.environ.copy()
+        env.update(self.spec.env)
+
+        self.log.info("starting: %s", " ".join(self.spec.argv))
+        try:
+            process = await asyncio.create_subprocess_exec(
+                *self.spec.argv,
+                stdin=asyncio.subprocess.PIPE,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=None,  # inherit, so the server's own logs reach our stderr
+                env=env,
+                cwd=self.spec.cwd,
+                limit=STDOUT_LIMIT,
+            )
+        except (OSError, ValueError) as e:
+            self.log.error("failed to start: %s", e)
+            await self._emit_state(protocol.STATE_FAILED, error=str(e))
+            return
+
+        self._process = process
+        self._stdout_task = asyncio.create_task(
+            self._read_stdout(process), name=f"stdout-{self.name}"
+        )
+        self.log.info("started (pid %d)", process.pid)
+        await self._emit_state(protocol.STATE_RUNNING)
+
+    async def stop(self, *, remove_tempfile: bool = True) -> None:
+        """Terminate the process, escalating to SIGKILL after TERMINATE_TIMEOUT.
+
+        ``remove_tempfile`` is false for a restart: a FastMCP-derived spec is
+        launched from a generated config file that the respawn still needs.
+        """
+        # Claim self._process/_stdout_task synchronously - no await before the
+        # null-out - so two concurrent stop() calls can't both tear the same
+        # process down.
+        process = self._process
+        self._process = None
+        stdout_task = self._stdout_task
+        self._stdout_task = None
+
+        if process is None:
+            if remove_tempfile:
+                self._remove_tempfile()
+            return
+
+        if stdout_task is not None:
+            stdout_task.cancel()
+            with suppress(asyncio.CancelledError):
+                await stdout_task
+
+        if process.returncode is None:
+            self.log.info("stopping (pid %d)", process.pid)
+            with suppress(ProcessLookupError):
+                process.terminate()
+            try:
+                await asyncio.wait_for(process.wait(), timeout=TERMINATE_TIMEOUT)
+            except asyncio.TimeoutError:
+                self.log.warning("did not exit after %.0fs, killing", TERMINATE_TIMEOUT)
+                with suppress(ProcessLookupError):
+                    process.kill()
+                await process.wait()
+
+        if remove_tempfile:
+            self._remove_tempfile()
+
+    async def restart(self) -> None:
+        await self.stop(remove_tempfile=False)
+        await self.start()
+
+    async def send(self, line: str) -> None:
+        """Write one line to the server's stdin."""
+        process = self._process
+        if process is None or process.stdin is None or process.returncode is not None:
+            self.log.warning("not running, dropping message")
+            return
+        try:
+            process.stdin.write(line.rstrip("\n").encode("utf-8") + b"\n")
+            await process.stdin.drain()
+        except (BrokenPipeError, ConnectionResetError) as e:
+            self.log.warning("stdin closed, dropping message: %s", e)
+
+    # -- internals -----------------------------------------------------
+
+    async def _read_stdout(self, process: asyncio.subprocess.Process) -> None:
+        assert process.stdout is not None
+        try:
+            while True:
+                line = await process.stdout.readline()
+                if not line:
+                    break
+                text = line.decode("utf-8", errors="replace").strip()
+                if not text:
+                    continue
+                if self._on_stdout is not None:
+                    try:
+                        await self._on_stdout(self.name, text)
+                    except asyncio.CancelledError:
+                        raise
+                    except Exception as e:  # noqa: BLE001 - one bad line must not kill the reader
+                        self.log.error("failed to forward stdout line: %s", e)
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:  # noqa: BLE001
+            self.log.error("error reading stdout: %s", e)
+            return
+
+        # EOF: the server closed stdout, so it is on its way out. Reap it and
+        # report; do not respawn here (see module docstring).
+        code = await process.wait()
+        self.log.warning("exited with code %s", code)
+        await self._emit_state(protocol.STATE_EXITED, exit_code=code)
+
+    async def _emit_state(
+        self,
+        state: str,
+        exit_code: Optional[int] = None,
+        error: Optional[str] = None,
+    ) -> None:
+        self._state = state
+        if self._on_state is None:
+            return
+        try:
+            await self._on_state(self.name, state, exit_code, error)
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:  # noqa: BLE001 - reporting must never break supervision
+            self.log.warning("could not report state %r: %s", state, e)
+
+    def _remove_tempfile(self) -> None:
+        if self.spec.fastmcp_tempfile is None:
+            return
+        try:
+            self.spec.fastmcp_tempfile.unlink()
+        except FileNotFoundError:
+            pass
+        except OSError as e:
+            self.log.warning("could not remove %s: %s", self.spec.fastmcp_tempfile, e)

mcp_switchboard_client/tunnel.py

@@ -0,0 +1,390 @@
+"""The outbound tunnel: one WebSocket to the hub, every local server on it.
+
+One process opens exactly one connection (``wss://<hub>/tunnel/v1``) and
+multiplexes every configured MCP server over it, tagging each frame with the
+server name. See docs/PROTOCOL.md - this is the client half of it.
+
+The client is a dumb pipe: it never interprets an MCP payload, it only moves
+lines between a subprocess and the socket.
+
+Liveness is WebSocket ping/pong only (20s interval, 10s timeout). There is
+deliberately no application-level heartbeat frame; the protocol this replaces
+had both sides answer ``heartbeat`` with ``heartbeat``, which is an infinite
+loop. Do not add one.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import uuid
+from contextlib import suppress
+from dataclasses import dataclass
+from typing import Any, Dict, Iterable, List, Optional
+from urllib.parse import urlsplit, urlunsplit
+
+import websockets
+from websockets.exceptions import ConnectionClosed
+
+from . import protocol
+from .config import ServerSpec
+from .supervisor import LocalServer
+
+LOGGER = logging.getLogger("mcp_switchboard_client.tunnel")
+
+CLIENT_NAME = "mcp-switchboard-client"
+
+DEFAULT_RECONNECT_DELAY = 1.0
+DEFAULT_MAX_RETRIES = 0  # 0 = infinite
+MAX_BACKOFF_DELAY = 60.0
+
+PING_INTERVAL = 20
+PING_TIMEOUT = 10
+
+_WS_SCHEMES = {"ws": "ws", "wss": "wss", "http": "ws", "https": "wss"}
+
+
+class TunnelError(Exception):
+    """Raised for an unusable hub URL or tunnel setting."""
+
+
+class FatalTunnelError(TunnelError):
+    """The hub refused this client; retrying cannot help."""
+
+
+def _header_kwarg() -> str:
+    """Name of the extra-headers keyword for the installed websockets version.
+
+    websockets >= 14 makes the asyncio client the top-level ``connect`` and
+    calls it ``additional_headers``; 12 and 13 still export the legacy client,
+    which calls it ``extra_headers``.
+    """
+    try:
+        major = int(str(websockets.__version__).split(".")[0])
+    except (AttributeError, ValueError):
+        return "additional_headers"
+    return "additional_headers" if major >= 14 else "extra_headers"
+
+
+def normalize_hub_url(url: str) -> str:
+    """Turn a user-supplied hub URL into the WebSocket URL to dial.
+
+    ``hub.example.com`` and ``https://hub.example.com`` both become
+    ``wss://hub.example.com/tunnel/v1``; an explicit path is left alone, so a
+    hub mounted under a prefix can be reached as ``wss://host/prefix/tunnel/v1``.
+    """
+    raw = (url or "").strip()
+    if not raw:
+        raise TunnelError("hub URL must not be empty")
+
+    if "://" not in raw:
+        raw = "wss://" + raw
+
+    parts = urlsplit(raw)
+    scheme = _WS_SCHEMES.get(parts.scheme.lower())
+    if scheme is None:
+        raise TunnelError(
+            f"unsupported hub URL scheme {parts.scheme!r} (use wss://, ws://, https:// or http://)"
+        )
+    if not parts.netloc:
+        raise TunnelError(f"hub URL {url!r} has no host")
+
+    path = parts.path
+    if path in ("", "/"):
+        path = protocol.TUNNEL_PATH
+
+    return urlunsplit((scheme, parts.netloc, path, parts.query, ""))
+
+
+@dataclass
+class TunnelSettings:
+    hub_url: str
+    token: str
+    label: str
+    reconnect_delay: float = DEFAULT_RECONNECT_DELAY
+    max_retries: int = DEFAULT_MAX_RETRIES
+
+
+class HubConnection:
+    """One WebSocket to the hub, multiplexing every local MCP server."""
+
+    def __init__(
+        self,
+        specs: Iterable[ServerSpec],
+        settings: TunnelSettings,
+        *,
+        version: str = "0.0.0",
+        connect: Any = None,
+        server_factory: Any = None,
+    ) -> None:
+        self.settings = settings
+        self.url = normalize_hub_url(settings.hub_url)
+        self.instance = uuid.uuid4().hex
+        self.version = version
+
+        self._connect = connect if connect is not None else websockets.connect
+        factory = server_factory if server_factory is not None else LocalServer
+        self._servers: Dict[str, Any] = {}
+        for spec in specs:
+            self._servers[spec.name] = factory(
+                spec,
+                on_stdout=self._on_server_stdout,
+                on_state=self._on_server_state,
+            )
+
+        self._ws: Any = None
+        self._acked = False
+        self._session_ok = False
+        self._stopping = False
+        self._stop_event: Optional[asyncio.Event] = None
+
+    @property
+    def servers(self) -> Dict[str, Any]:
+        """The local servers, keyed by name, in config order."""
+        return self._servers
+
+    # -- lifecycle -----------------------------------------------------
+
+    async def run(self) -> None:
+        """Connect, serve, and reconnect until stopped or out of retries."""
+        self._stop_event = asyncio.Event()
+        if self._stopping:
+            self._stop_event.set()
+
+        attempt = 0
+        try:
+            while not self._stopping:
+                try:
+                    await self._connect_and_serve()
+                except asyncio.CancelledError:
+                    raise
+                except FatalTunnelError as e:
+                    LOGGER.error("%s", e)
+                    break
+                except Exception as e:  # noqa: BLE001 - every connection error is retryable
+                    LOGGER.error("connection error: %s: %s", type(e).__name__, e)
+
+                if self._stopping:
+                    break
+
+                if self._session_ok:
+                    # A session that got as far as hello_ack starts backoff over.
+                    attempt = 0
+
+                attempt += 1
+                if 0 < self.settings.max_retries <= attempt:
+                    LOGGER.error(
+                        "giving up after %d attempt(s)", self.settings.max_retries
+                    )
+                    break
+
+                delay = min(
+                    self.settings.reconnect_delay * (2 ** (attempt - 1)),
+                    MAX_BACKOFF_DELAY,
+                )
+                LOGGER.info("reconnecting in %.1fs (attempt %d)", delay, attempt)
+                if await self._sleep_or_stop(delay):
+                    break
+        finally:
+            await self._stop_servers()
+
+    def request_stop(self) -> None:
+        """Ask the tunnel to shut down. Safe to call from a signal handler."""
+        self._stopping = True
+        if self._stop_event is not None:
+            self._stop_event.set()
+
+    async def _sleep_or_stop(self, delay: float) -> bool:
+        """Sleep, returning True if a stop was requested instead."""
+        assert self._stop_event is not None
+        try:
+            await asyncio.wait_for(self._stop_event.wait(), timeout=max(delay, 0.0))
+        except asyncio.TimeoutError:
+            return False
+        return True
+
+    async def _stop_servers(self) -> None:
+        if not self._servers:
+            return
+        LOGGER.info("stopping %d local server(s)", len(self._servers))
+        results = await asyncio.gather(
+            *(server.stop() for server in self._servers.values()),
+            return_exceptions=True,
+        )
+        for server, result in zip(self._servers.values(), results):
+            if isinstance(result, BaseException):
+                LOGGER.warning("error stopping %s: %s", server.name, result)
+
+    # -- one connection ------------------------------------------------
+
+    async def _connect_and_serve(self) -> None:
+        self._acked = False
+        self._session_ok = False
+        kwargs = {
+            _header_kwarg(): {"Authorization": f"Bearer {self.settings.token}"},
+            "ping_interval": PING_INTERVAL,
+            "ping_timeout": PING_TIMEOUT,
+        }
+
+        LOGGER.info("connecting to %s", self.url)
+        async with self._connect(self.url, **kwargs) as ws:
+            self._ws = ws
+            closer = asyncio.create_task(self._close_when_stopped(ws))
+            try:
+                await self._send(
+                    protocol.hello(
+                        CLIENT_NAME,
+                        self.version,
+                        self.instance,
+                        self.settings.label,
+                        self._descriptors(),
+                    )
+                )
+                async for raw in ws:
+                    await self._handle_frame(raw)
+            except ConnectionClosed as e:
+                LOGGER.warning("hub connection closed: %s", e)
+            finally:
+                closer.cancel()
+                with suppress(asyncio.CancelledError):
+                    await closer
+                self._ws = None
+                self._acked = False
+                LOGGER.info("tunnel down")
+
+    async def _close_when_stopped(self, ws: Any) -> None:
+        assert self._stop_event is not None
+        await self._stop_event.wait()
+        with suppress(Exception):
+            await ws.close()
+
+    def _descriptors(self) -> List[Dict[str, str]]:
+        return [server.descriptor for server in self._servers.values()]
+
+    # -- inbound -------------------------------------------------------
+
+    async def _handle_frame(self, raw: Any) -> None:
+        if isinstance(raw, (bytes, bytearray)):
+            raw = bytes(raw).decode("utf-8", errors="replace")
+        try:
+            data = json.loads(raw)
+        except (json.JSONDecodeError, TypeError):
+            LOGGER.error("non-JSON frame from hub, dropping")
+            return
+        if not isinstance(data, dict):
+            LOGGER.error("frame from hub is not an object, dropping")
+            return
+
+        frame_type = data.get("type")
+        if frame_type == protocol.MCP:
+            await self._handle_mcp(data)
+        elif frame_type == protocol.RESTART:
+            await self._handle_restart(data)
+        elif frame_type == protocol.HELLO_ACK:
+            await self._handle_hello_ack(data)
+        elif frame_type == protocol.ERROR:
+            self._handle_error(data)
+        else:
+            LOGGER.warning("ignoring unknown frame type %r from hub", frame_type)
+
+    async def _handle_hello_ack(self, data: Dict[str, Any]) -> None:
+        hub = data.get("hub") or {}
+        LOGGER.info(
+            "tunnel up: connection %s to %s %s",
+            data.get("connectionId"),
+            hub.get("name", "hub"),
+            hub.get("version", "?"),
+        )
+        self._acked = True
+        self._session_ok = True
+        # The hub opens a fresh MCP session per connection, and a server that
+        # already completed `initialize` would reject a second one, so every
+        # (re)connect restarts every local server. See docs/PROTOCOL.md.
+        await self._restart_all()
+
+    def _lookup(self, name: Any) -> Any:
+        if not isinstance(name, str):
+            return None
+        return self._servers.get(name)
+
+    async def _handle_mcp(self, data: Dict[str, Any]) -> None:
+        name = data.get("server")
+        server = self._lookup(name)
+        if server is None:
+            LOGGER.warning("mcp frame for unknown server %r, dropping", name)
+            return
+        payload = data.get("payload")
+        if payload is None:
+            LOGGER.warning("mcp frame for %r has no payload, dropping", name)
+            return
+        await server.send(json.dumps(payload))
+
+    async def _handle_restart(self, data: Dict[str, Any]) -> None:
+        name = data.get("server")
+        server = self._lookup(name)
+        if server is None:
+            LOGGER.warning("restart requested for unknown server %r", name)
+            return
+        LOGGER.info("restart requested for %s", name)
+        await server.restart()
+
+    def _handle_error(self, data: Dict[str, Any]) -> None:
+        message = data.get("message") or "unspecified error"
+        server = data.get("server")
+        if not self._acked:
+            # Before hello_ack an error means the hub refused this client -
+            # unsupported protocol version, illegal server name. Retrying with
+            # exactly the same hello will never succeed.
+            raise FatalTunnelError(f"hub rejected the connection: {message}")
+        if server:
+            LOGGER.error("hub error for server %s: %s", server, message)
+        else:
+            LOGGER.error("hub error: %s", message)
+
+    async def _restart_all(self) -> None:
+        if not self._servers:
+            LOGGER.warning("no local servers configured")
+            return
+        LOGGER.info("(re)starting %d local server(s)", len(self._servers))
+        results = await asyncio.gather(
+            *(server.restart() for server in self._servers.values()),
+            return_exceptions=True,
+        )
+        for server, result in zip(self._servers.values(), results):
+            if isinstance(result, BaseException):
+                LOGGER.error("failed to restart %s: %s", server.name, result)
+
+    # -- outbound ------------------------------------------------------
+
+    async def _on_server_stdout(self, name: str, line: str) -> None:
+        try:
+            payload = json.loads(line)
+        except json.JSONDecodeError:
+            LOGGER.warning("%s wrote a non-JSON stdout line, dropping: %s", name, line[:200])
+            return
+        await self._try_send(protocol.mcp(name, payload))
+
+    async def _on_server_state(
+        self,
+        name: str,
+        state: str,
+        exit_code: Optional[int],
+        error: Optional[str],
+    ) -> None:
+        await self._try_send(protocol.server_state(name, state, exit_code, error))
+
+    async def _send(self, frame: Dict[str, Any]) -> None:
+        ws = self._ws
+        if ws is None:
+            raise TunnelError("not connected to the hub")
+        await ws.send(json.dumps(frame))
+
+    async def _try_send(self, frame: Dict[str, Any]) -> None:
+        """Send a frame, dropping it if the tunnel is down."""
+        try:
+            await self._send(frame)
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:  # noqa: BLE001 - a dropped frame must not kill a server
+            LOGGER.debug("dropping %s frame, tunnel unavailable: %s", frame.get("type"), e)

mcp_switchboard_client-0.2.0.dist-info/METADATA

@@ -0,0 +1,64 @@
+Metadata-Version: 2.5
+Name: mcp-switchboard-client
+Version: 0.2.0
+Summary: Tunnels local stdio MCP servers to an mcp-switchboard hub over one outbound WebSocket
+Project-URL: Homepage, https://github.com/AkosPapp/mcp-switchboard
+Project-URL: Repository, https://github.com/AkosPapp/mcp-switchboard
+Author: Akos Papp
+License: MIT
+Keywords: mcp,model-context-protocol,reverse-proxy,switchboard,tunnel
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: websockets>=14
+Provides-Extra: test
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mcp-switchboard-client
+
+The client half of [mcp-switchboard](https://github.com/AkosPapp/mcp-switchboard).
+
+It reads an `mcp.json`, spawns the local stdio MCP servers it describes, and
+opens a single **outbound** WebSocket to an `mcp-switchboard-hub`, multiplexing
+every server over that one connection. No inbound port is ever opened, so it
+works from behind NAT with nothing forwarded.
+
+The client speaks no MCP itself — it is a pipe, shuttling each server's
+stdin/stdout across the tunnel. All MCP logic lives in the hub. That is why its
+only dependency is `websockets`.
+
+## Running
+
+```sh
+uvx mcp-switchboard-client --hub-url wss://switchboard.example.com --token "$TOKEN"
+```
+
+or bootstrap `uvx`/`npx` first with the installer:
+
+```sh
+curl -fsSL https://akospapp.github.io/mcp-switchboard/install.sh | sh -s -- \
+  --hub-url wss://switchboard.example.com --token "$TOKEN"
+```
+
+`mcp.json` uses the familiar shape, resolved from the current directory:
+
+```json
+{
+  "mcpServers": {
+    "git": { "command": "uvx", "args": ["mcp-server-git", "--repository", "."] }
+  }
+}
+```
+
+Settings can also come from `MCP_SWITCHBOARD_*` environment variables or a
+`.env` file (`HUB_URL`, `TUNNEL_TOKEN`, `LABEL`, `CONFIG`, …). Any value that
+starts with `/` and points at an existing regular file is read from that file, so
+a token can be passed as a path.
+
+`LABEL` defaults to the machine's hostname and is how the hub tags this
+machine's tools, so consumers can tell which host a tool lives on.
+
+See the [main README](../README.md) for the full picture.

mcp_switchboard_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+mcp_switchboard_client/__init__.py,sha256=nFlVoZtrB54fwBnDY7Qjnp-CmE2vG7lyomALct8q5aM,374
+mcp_switchboard_client/__main__.py,sha256=RUFXS_35UXObXLHJD-pEu6c5DApldc_9HKckqDMiAPk,106
+mcp_switchboard_client/cli.py,sha256=zLM4fEvkvshYHe3jhMzlCEH5wFRuPAmawMs76CG-osw,8963
+mcp_switchboard_client/config.py,sha256=yce5oPd7-AHld7dl7odQfCF1LyX3Vsc9VCNYSGHYDHY,5532
+mcp_switchboard_client/envconf.py,sha256=sGDp5nu_wC0Y3uPNfQtCGmTi_EdpUYC-T-II3lBV9Y4,3931
+mcp_switchboard_client/protocol.py,sha256=nIoXnOmAQvlZ-uei5IbIfCx9jCxlOotB_AIw8sPKKAo,2408
+mcp_switchboard_client/supervisor.py,sha256=0Sla4wuBSifeHhuZP19E-OeJ6ga4DlTZswaPnz0G-k8,8069
+mcp_switchboard_client/tunnel.py,sha256=TE1-AUIXwbSdsW8td_tsBEJMeFoxjVOsbP6kGDomeBw,13997
+mcp_switchboard_client-0.2.0.dist-info/METADATA,sha256=OaF6pXApTvaPbb7HHbFwYEeYwGkounC2-g15CgWCcn0,2301
+mcp_switchboard_client-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+mcp_switchboard_client-0.2.0.dist-info/entry_points.txt,sha256=GDtmUrMrsmKu0eHHB-YsdLH4atD7FcC6c2-4_tXYJ7s,75
+mcp_switchboard_client-0.2.0.dist-info/RECORD,,

mcp_switchboard_client-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

mcp_switchboard_client-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-switchboard-client = mcp_switchboard_client.cli:main