mcp-switchboard-client 0.2.0__tar.gz

mcp_switchboard_client-0.2.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+result
+result-*

mcp_switchboard_client-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,45 @@
+# 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/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-switchboard-client"
+version = "0.2.0"
+description = "Tunnels local stdio MCP servers to an mcp-switchboard hub over one outbound WebSocket"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Akos Papp" }]
+keywords = ["mcp", "model-context-protocol", "tunnel", "reverse-proxy", "switchboard"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+# Deliberately no `mcp` dependency: the client is a dumb pipe and speaks no MCP.
+dependencies = [
+    "websockets>=14",
+]
+
+[project.optional-dependencies]
+test = ["pytest", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/AkosPapp/mcp-switchboard"
+Repository = "https://github.com/AkosPapp/mcp-switchboard"
+
+[project.scripts]
+mcp-switchboard-client = "mcp_switchboard_client.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_switchboard_client"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

mcp_switchboard_client-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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-0.2.0/src/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,
+    )