mcp-switchboard-client 0.2.0__tar.gz → 0.3.0.dev3__tar.gz

mcp_switchboard_client-0.3.0.dev3/.gitignore

@@ -0,0 +1,18 @@
+__pycache__/
+*.pyc
+*.egg-info/
+.venv/
+venv/
+build/
+dist/
+# ...except the console's, which is committed on purpose: the hub embeds it, so
+# `go build` has to work without npm (spec.md U1). CI rebuilds it and fails if
+# this copy is stale.
+!hub/web/dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.env
+result
+result-*
+.direnv/

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-switchboard-client
-Version: 0.2.0
+Version: 0.3.0.dev3
 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
@@ -11,8 +11,11 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.10
+Requires-Dist: certifi>=2024.2.2
+Requires-Dist: mcp-switchboard-server-harness
 Requires-Dist: websockets>=14
 Provides-Extra: test
+Requires-Dist: httpx; extra == 'test'
 Requires-Dist: pytest; extra == 'test'
 Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
 Description-Content-Type: text/markdown
@@ -28,7 +31,9 @@ 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`.
+only own dependencies are `websockets` and `certifi` (plus the harness package,
+which brings the `mcp` SDK) (a bundled CA bundle, because
+`uvx`'s portable Pythons often cannot find a system certificate store).
 
 ## Running
 
@@ -43,7 +48,8 @@ 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:
+`mcp.json` uses the familiar shape, resolved from the current directory. It is optional:
+without one, the client tunnels just the built-in coding harness (see below):
 
 ```json
 {
@@ -53,6 +59,16 @@ curl -fsSL https://akospapp.github.io/mcp-switchboard/install.sh | sh -s -- \
 }
 ```
 
+An entry may set `"project"` to group it under a project name (a top-level
+`"project"` is the default for all entries). The client sends it to the hub, which
+uses it in tool names and project-scoped endpoints. Names must not contain `__`.
+
+A first-party [coding harness](../servers/harness) (file, search, git and shell
+tools) is added as a server named `harness` by default, confined to the directory you start
+the client in. Turn it off with
+`--no-harness` or `MCP_SWITCHBOARD_HARNESS=false`; an `mcp.json` entry named
+`harness` replaces it.
+
 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

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/README.md

@@ -9,7 +9,9 @@ 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`.
+only own dependencies are `websockets` and `certifi` (plus the harness package,
+which brings the `mcp` SDK) (a bundled CA bundle, because
+`uvx`'s portable Pythons often cannot find a system certificate store).
 
 ## Running
 
@@ -24,7 +26,8 @@ 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:
+`mcp.json` uses the familiar shape, resolved from the current directory. It is optional:
+without one, the client tunnels just the built-in coding harness (see below):
 
 ```json
 {
@@ -34,6 +37,16 @@ curl -fsSL https://akospapp.github.io/mcp-switchboard/install.sh | sh -s -- \
 }
 ```
 
+An entry may set `"project"` to group it under a project name (a top-level
+`"project"` is the default for all entries). The client sends it to the hub, which
+uses it in tool names and project-scoped endpoints. Names must not contain `__`.
+
+A first-party [coding harness](../servers/harness) (file, search, git and shell
+tools) is added as a server named `harness` by default, confined to the directory you start
+the client in. Turn it off with
+`--no-harness` or `MCP_SWITCHBOARD_HARNESS=false`; an `mcp.json` entry named
+`harness` replaces it.
+
 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

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcp-switchboard-client"
-version = "0.2.0"
+version = "0.3.0.dev3"
 description = "Tunnels local stdio MCP servers to an mcp-switchboard hub over one outbound WebSocket"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -16,13 +16,31 @@ classifiers = [
     "License :: OSI Approved :: MIT License",
     "Operating System :: OS Independent",
 ]
-# Deliberately no `mcp` dependency: the client is a dumb pipe and speaks no MCP.
+# The client itself speaks no MCP (it is a dumb pipe). The `mcp` SDK arrives only
+# via the built-in coding harness server, which the client spawns by default.
 dependencies = [
+    "mcp-switchboard-server-harness",
     "websockets>=14",
+    # A bundled CA bundle for the TLS handshake, not just for convenience: this
+    # client is typically run via `uvx` with astral's portable CPython builds,
+    # which often can't find a usable system cert store (NixOS's is at a
+    # nonstandard path), causing every wss:// connection to fail with
+    # CERTIFICATE_VERIFY_FAILED regardless of the host actually being fine.
+    "certifi>=2024.2.2",
 ]
 
 [project.optional-dependencies]
-test = ["pytest", "pytest-asyncio>=0.23"]
+test = [
+    "pytest",
+    "pytest-asyncio>=0.23",
+    # Not used by the client itself - only by tests/test_end_to_end.py, which
+    # calls the hub's console API and MCP endpoint over real HTTP. It lives here
+    # rather than in its own workspace member because tests/ isn't packaged.
+    "httpx",
+]
+
+[tool.uv.sources]
+mcp-switchboard-server-harness = { workspace = true }
 
 [project.urls]
 Homepage = "https://github.com/AkosPapp/mcp-switchboard"

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/src/mcp_switchboard_client/__init__.py

@@ -6,4 +6,4 @@ outbound WebSocket, tagged with the server name. Every MCP concern lives in the
 hub. See docs/PROTOCOL.md.
 """
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/src/mcp_switchboard_client/cli.py

@@ -16,11 +16,11 @@ import socket
 import sys
 from dataclasses import dataclass
 from pathlib import Path
-from typing import List, Optional, Sequence
+from typing import Any, Dict, List, Optional, Sequence
 
-from . import envconf, protocol
+from . import envconf, environment, protocol
 from .config import ConfigError as McpConfigError
-from .config import ServerSpec, load_config
+from .config import HARNESS_NAME, ServerSpec, harness_spec, load_config
 from .envconf import ConfigError
 from .tunnel import (
     DEFAULT_MAX_RETRIES,
@@ -47,9 +47,13 @@ class Settings:
     token: str
     label: str
     config_path: Path
+    config_explicit: bool = False  # --config / MCP_SWITCHBOARD_CONFIG was given
     reconnect_delay: float = DEFAULT_RECONNECT_DELAY
     max_retries: int = DEFAULT_MAX_RETRIES
     log_level: str = DEFAULT_LOG_LEVEL
+    harness: bool = True
+    project_name: Optional[str] = None
+    environment: Optional[Dict[str, Any]] = None  # detected at load_settings
 
     def tunnel_settings(self) -> TunnelSettings:
         return TunnelSettings(
@@ -58,6 +62,7 @@ class Settings:
             label=self.label,
             reconnect_delay=self.reconnect_delay,
             max_retries=self.max_retries,
+            environment=self.environment,
         )
 
 
@@ -92,6 +97,14 @@ def build_parser() -> argparse.ArgumentParser:
             f"(or {envconf.PREFIX}LABEL)"
         ),
     )
+    parser.add_argument(
+        "--project-name",
+        default=None,
+        help=(
+            "Project name shown next to this client in the hub; default is detected "
+            f"(devcontainer name, git root, or directory name) (or {envconf.PREFIX}PROJECT_NAME)"
+        ),
+    )
     parser.add_argument(
         "--config",
         default=None,
@@ -123,6 +136,14 @@ def build_parser() -> argparse.ArgumentParser:
             f"(default {DEFAULT_MAX_RETRIES}, or {envconf.PREFIX}MAX_RETRIES)"
         ),
     )
+    parser.add_argument(
+        "--no-harness",
+        action="store_true",
+        help=(
+            "Do not add the built-in coding harness server (file, search, git and shell "
+            f"tools), which is on by default (or set {envconf.PREFIX}HARNESS=false)"
+        ),
+    )
     parser.add_argument(
         "--log-level",
         choices=LOG_LEVELS,
@@ -168,9 +189,12 @@ def load_settings(args: argparse.Namespace) -> Settings:
     except protocol.ProtocolError as e:
         raise ConfigError(str(e)) from e
 
+    project_name = (args.project_name or envconf.get("PROJECT_NAME") or "").strip() or None
+
     # 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
+    explicit_config = args.config or envconf.get("CONFIG")
+    raw_config = explicit_config or DEFAULT_CONFIG_NAME
     config_path = Path(raw_config)
     if not config_path.is_absolute():
         config_path = Path.cwd() / config_path
@@ -200,9 +224,13 @@ def load_settings(args: argparse.Namespace) -> Settings:
         token=token,
         label=label,
         config_path=config_path,
+        config_explicit=bool(explicit_config),
         reconnect_delay=reconnect_delay,
         max_retries=max_retries,
         log_level=log_level,
+        harness=not args.no_harness and envconf.get_bool("HARNESS", True),
+        project_name=project_name,
+        environment=environment.detect(project_override=project_name),
     )
 
 
@@ -210,12 +238,25 @@ 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)
+def load_servers(path: Path, harness: bool = False, config_required: bool = True) -> List[ServerSpec]:
+    """Load the MCP config, rejecting names the hub could never accept.
+
+    With ``harness``, the built-in coding harness is appended, unless the config
+    already defines a server of that name (then the user's entry wins). If the
+    config file is absent and not ``config_required``, the harness alone is used.
+    """
+    if harness and not config_required and not path.is_file():
+        LOGGER.info("no config at %s: tunnelling only the built-in harness", path)
+        specs: List[ServerSpec] = []
+    else:
+        specs = load_config(path)
+    if harness and all(spec.name != HARNESS_NAME for spec in specs):
+        specs.append(harness_spec())
     for spec in specs:
         try:
             protocol.validate_name(spec.name, "server name")
+            if spec.project is not None:
+                protocol.validate_name(spec.project, "project name")
         except protocol.ProtocolError as e:
             raise McpConfigError(f"{e} (in {path})") from e
     return specs
@@ -254,6 +295,8 @@ async def _run(settings: Settings, specs: List[ServerSpec]) -> None:
         settings.label,
         ", ".join(spec.name for spec in specs),
     )
+    if settings.environment is not None:
+        LOGGER.info("%s", environment.summarize(settings.environment))
     await connection.run()
     LOGGER.info("shutdown complete")
 
@@ -269,7 +312,13 @@ def main(argv: Optional[Sequence[str]] = None) -> None:
     setup_logging(settings.log_level)
 
     try:
-        specs = load_servers(settings.config_path)
+        specs = load_servers(
+            settings.config_path,
+            settings.harness,
+            # A file the user named must exist; the default ./mcp.json is optional
+            # as long as the harness gives the client something to tunnel.
+            config_required=settings.config_explicit,
+        )
     except McpConfigError as e:
         print(f"{PROG}: error: {e}", file=sys.stderr)
         sys.exit(1)

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/src/mcp_switchboard_client/config.py

@@ -9,11 +9,17 @@ Two config shapes are supported (see README.md for the full discriminator rule):
    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.
+
+A server entry may also carry a ``"project"``, grouping it under that name in
+the hub's tool naming and scoped endpoints (e.g. ``host/legion5/project/nix/
+server/lsp``). A top-level ``"project"`` in the config file sets the default
+for every entry that does not specify its own.
 """
 
 from __future__ import annotations
 
 import json
+import sys
 import logging
 import tempfile
 from dataclasses import dataclass, field
@@ -35,6 +41,7 @@ class ServerSpec:
     argv: List[str]
     env: Dict[str, str] = field(default_factory=dict)
     cwd: Optional[str] = None
+    project: 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
@@ -50,7 +57,7 @@ def load_config(path: Path) -> List[ServerSpec]:
     if not path.is_file():
         raise ConfigError(
             f"config file not found: {path} "
-            "(pass --config, or create ./mcp.json in the current directory)"
+            "(pass --config, create ./mcp.json in the current directory, or leave the built-in harness enabled)"
         )
 
     try:
@@ -61,16 +68,18 @@ def load_config(path: Path) -> List[ServerSpec]:
     if not isinstance(raw, dict):
         raise ConfigError(f"config file {path} must contain a JSON object at the top level")
 
+    default_project = _read_project(raw, path, "top-level 'project'")
+
     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()]
+        return [_build_spec(name, entry, path, default_project) 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)]
+        return [_build_fastmcp_spec(name, raw, default_project)]
 
     raise ConfigError(
         f"config file {path} matches neither the 'mcpServers' shape nor the "
@@ -78,12 +87,24 @@ def load_config(path: Path) -> List[ServerSpec]:
     )
 
 
-def _build_spec(name: str, entry: Any, config_path: Path) -> ServerSpec:
+def _read_project(entry: Dict[str, Any], config_path: Path, where: str) -> Optional[str]:
+    """Read and normalize an optional ``"project"`` key. Blank counts as absent."""
+    project = entry.get("project")
+    if project is None:
+        return None
+    if not isinstance(project, str):
+        raise ConfigError(f"{where} in {config_path} must be a string")
+    return project.strip() or None
+
+
+def _build_spec(name: str, entry: Any, config_path: Path, default_project: Optional[str] = None) -> 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)
+        return _build_fastmcp_spec(name, entry, default_project)
+
+    project = _read_project(entry, config_path, f"mcpServers.{name}.project") or default_project
 
     command = entry.get("command")
     if not command or not isinstance(command, str):
@@ -104,10 +125,12 @@ def _build_spec(name: str, entry: Any, config_path: Path) -> ServerSpec:
     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)
+    return ServerSpec(
+        name=name, argv=[command, *args], env={k: str(v) for k, v in env.items()}, cwd=cwd, project=project
+    )
 
 
-def _build_fastmcp_spec(name: str, entry: Dict[str, Any]) -> ServerSpec:
+def _build_fastmcp_spec(name: str, entry: Dict[str, Any], default_project: Optional[str] = None) -> ServerSpec:
     """Materialize a FastMCP-style entry into a runnable ServerSpec.
 
     We write the entry out verbatim (minus a forced transport override) as its
@@ -119,7 +142,13 @@ def _build_fastmcp_spec(name: str, entry: Dict[str, Any]) -> ServerSpec:
     regardless of what the entry declares, with a warning if it was set to
     something else.
     """
+    raw_project = entry.get("project")
+    if raw_project is not None and not isinstance(raw_project, str):
+        raise ConfigError(f"mcpServers.{name}.project must be a string")
+    project = (raw_project.strip() if isinstance(raw_project, str) else None) or default_project
+
     fastmcp_config = dict(entry)
+    fastmcp_config.pop("project", None)  # not a FastMCP config key
     deployment = dict(fastmcp_config.get("deployment") or {})
     original_transport = deployment.get("transport")
     if original_transport and original_transport != "stdio":
@@ -141,5 +170,18 @@ def _build_fastmcp_spec(name: str, entry: Dict[str, Any]) -> ServerSpec:
         name=name,
         argv=["uvx", "fastmcp", "run", str(tmp_path)],
         env={},
+        project=project,
         fastmcp_tempfile=tmp_path,
     )
+
+
+HARNESS_NAME = "harness"
+
+
+def harness_spec() -> ServerSpec:
+    """The built-in coding harness, run with this interpreter.
+
+    It is a dependency of this package, so it is always importable here and
+    needs no separate install or network fetch at startup.
+    """
+    return ServerSpec(name=HARNESS_NAME, argv=[sys.executable, "-m", "mcp_switchboard_server_harness"])

mcp_switchboard_client-0.3.0.dev3/src/mcp_switchboard_client/environment.py

@@ -0,0 +1,202 @@
+"""Detect where the client runs, for the ``hello`` frame's ``client.environment``.
+
+Pure and best-effort: :func:`detect` never raises, reads only a small fixed set of
+signals, and reports paths and names, never environment variable values beyond the
+documented details (docs/AGENT_MODEL_API.md, "Connections: environment detection").
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any, Dict, List, Mapping, Optional
+
+LOGGER = logging.getLogger("mcp_switchboard_client.environment")
+
+_CGROUP_MARKERS = ("docker", "kubepods", "containerd", "podman")
+_MAX_STR = 256
+_MAX_WALK = 64
+
+
+def _cap(value: str) -> str:
+    return value[:_MAX_STR]
+
+
+def strip_jsonc(text: str) -> str:
+    """Remove ``//`` and ``/* */`` comments and trailing commas, leaving strings intact."""
+    out: List[str] = []
+    i, n = 0, len(text)
+    while i < n:
+        c = text[i]
+        if c == '"':
+            j = i + 1
+            while j < n and text[j] != '"':
+                j += 2 if text[j] == "\\" else 1
+            out.append(text[i : j + 1])
+            i = j + 1
+        elif text.startswith("//", i):
+            while i < n and text[i] != "\n":
+                i += 1
+        elif text.startswith("/*", i):
+            end = text.find("*/", i + 2)
+            i = n if end < 0 else end + 2
+        else:
+            out.append(c)
+            i += 1
+    cleaned = "".join(out)
+    # Trailing commas: a comma followed only by whitespace and a closer. Strings
+    # were already tokenised above, but the regex could match inside one, so redo
+    # it string-aware.
+    result: List[str] = []
+    i, n = 0, len(cleaned)
+    while i < n:
+        c = cleaned[i]
+        if c == '"':
+            j = i + 1
+            while j < n and cleaned[j] != '"':
+                j += 2 if cleaned[j] == "\\" else 1
+            result.append(cleaned[i : j + 1])
+            i = j + 1
+        elif c == "," and re.match(r"\s*[}\]]", cleaned[i + 1 :]):
+            i += 1
+        else:
+            result.append(c)
+            i += 1
+    return "".join(result)
+
+
+def _read(path: Path, limit: int = 1_000_000) -> Optional[str]:
+    try:
+        with open(path, "r", encoding="utf-8", errors="replace") as f:
+            return f.read(limit)
+    except OSError:
+        return None
+
+
+def _parents(cwd: Path) -> List[Path]:
+    return [cwd, *cwd.parents][:_MAX_WALK]
+
+
+def find_devcontainer_name(cwd: Path) -> Optional[str]:
+    """``name`` from the nearest devcontainer.json at or above ``cwd``."""
+    for directory in _parents(cwd):
+        for candidate in (
+            directory / ".devcontainer" / "devcontainer.json",
+            directory / ".devcontainer.json",
+        ):
+            text = _read(candidate)
+            if text is None:
+                continue
+            try:
+                data = json.loads(strip_jsonc(text))
+            except ValueError:
+                continue
+            name = data.get("name") if isinstance(data, dict) else None
+            if isinstance(name, str) and name.strip():
+                return _cap(name.strip())
+    return None
+
+
+def find_git_root(cwd: Path) -> Optional[Path]:
+    """The nearest directory at or above ``cwd`` containing ``.git`` (dir or file)."""
+    for directory in _parents(cwd):
+        try:
+            if (directory / ".git").exists():
+                return directory
+        except OSError:
+            continue
+    return None
+
+
+def _in_container(root: Path) -> bool:
+    for marker in ("/.dockerenv", "/run/.containerenv"):
+        try:
+            if Path(marker).exists():
+                return True
+        except OSError:
+            pass
+    cgroup = _read(Path("/proc/1/cgroup"), 65536) if root == Path("/") else None
+    return bool(cgroup) and any(m in cgroup.lower() for m in _CGROUP_MARKERS)
+
+
+def detect(
+    cwd: Optional[Path] = None,
+    env: Optional[Mapping[str, str]] = None,
+    project_override: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Return the ``environment`` object for ``hello``. Never raises."""
+    try:
+        return _detect(cwd, env, project_override)
+    except Exception:  # noqa: BLE001 - detection must never break the client
+        LOGGER.debug("environment detection failed", exc_info=True)
+        return {"kinds": []}
+
+
+def _detect(
+    cwd: Optional[Path], env: Optional[Mapping[str, str]], project_override: Optional[str]
+) -> Dict[str, Any]:
+    env = os.environ if env is None else env
+    cwd = Path(os.getcwd() if cwd is None else cwd).absolute()
+    kinds: List[str] = []
+    details: Dict[str, str] = {}
+
+    container = _in_container(Path("/"))
+    devcontainer = any(
+        env.get(k) for k in ("REMOTE_CONTAINERS", "DEVCONTAINER", "CODESPACES", "VSCODE_REMOTE_CONTAINERS_SESSION")
+    ) or (container and str(cwd).startswith("/workspaces/"))
+    dc_name = find_devcontainer_name(cwd) if devcontainer else None
+
+    if devcontainer:
+        kinds.append("devcontainer")
+        if dc_name:
+            details["devcontainerName"] = dc_name
+        image = env.get("DEVCONTAINER_IMAGE") or env.get("CONTAINER_IMAGE")
+        if image:
+            details["image"] = _cap(image)
+    if container:
+        kinds.append("container")
+    if env.get("DIRENV_DIR") or env.get("DIRENV_FILE") or env.get("DIRENV_DIFF"):
+        kinds.append("direnv")
+        direnv_dir = env.get("DIRENV_DIR", "").lstrip("-")
+        if direnv_dir:
+            details["direnvDir"] = _cap(direnv_dir)
+    in_nix = env.get("IN_NIX_SHELL")
+    if in_nix or env.get("NIX_BUILD_TOP") or "/nix/store/" in env.get("PATH", ""):
+        kinds.append("nix-shell")
+        if in_nix in ("pure", "impure"):
+            details["nixShell"] = in_nix
+        elif in_nix:
+            details["nixShell"] = "impure"
+    venv = env.get("VIRTUAL_ENV")
+    if venv or sys.prefix != getattr(sys, "base_prefix", sys.prefix):
+        kinds.append("venv")
+        name = os.path.basename((venv or sys.prefix).rstrip("/\\"))
+        if name:
+            details["venv"] = _cap(name)
+
+    project = (project_override or "").strip() or None
+    if project is None and dc_name:
+        project = dc_name
+    if project is None:
+        root = find_git_root(cwd)
+        project = (root or cwd).name or None
+
+    result: Dict[str, Any] = {"kinds": kinds}
+    if project:
+        result["project"] = _cap(project)
+    result["workspace"] = _cap(str(cwd))
+    if details:
+        result["details"] = details
+    return result
+
+
+def summarize(environment: Mapping[str, Any]) -> str:
+    kinds = ",".join(environment.get("kinds", [])) or "none"
+    return (
+        f"environment: kinds={kinds} project={environment.get('project', '-')} "
+        f"workspace={environment.get('workspace', '-')}"
+    )

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/src/mcp_switchboard_client/protocol.py

@@ -49,11 +49,15 @@ def hello(
     instance: str,
     label: str,
     servers: List[Dict[str, Any]],
+    environment: Optional[Dict[str, Any]] = None,
 ) -> Dict[str, Any]:
+    client: Dict[str, Any] = {"name": client_name, "version": version, "instance": instance, "label": label}
+    if environment is not None:
+        client["environment"] = environment
     return {
         "type": HELLO,
         "protocol": PROTOCOL_VERSION,
-        "client": {"name": client_name, "version": version, "instance": instance, "label": label},
+        "client": client,
         "servers": servers,
     }
 

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/src/mcp_switchboard_client/supervisor.py

@@ -71,7 +71,10 @@ class LocalServer:
     @property
     def descriptor(self) -> dict:
         """The entry this server contributes to the ``hello`` frame."""
-        return {"name": self.name, "command": " ".join(self.spec.argv)}
+        entry = {"name": self.name, "command": " ".join(self.spec.argv)}
+        if self.spec.project:
+            entry["project"] = self.spec.project
+        return entry
 
     async def start(self) -> None:
         """Spawn the process. A no-op if one is already claimed."""

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/src/mcp_switchboard_client/tunnel.py

@@ -18,12 +18,14 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
+import ssl
 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 certifi
 import websockets
 from websockets.exceptions import ConnectionClosed
 
@@ -53,6 +55,25 @@ class FatalTunnelError(TunnelError):
     """The hub refused this client; retrying cannot help."""
 
 
+def _tls_context() -> ssl.SSLContext:
+    """A TLS context trusting the system store *and* certifi's CA bundle.
+
+    Built once and reused. This client typically runs under `uvx`, whose
+    portable CPython builds frequently can't find a system cert store (NixOS
+    keeps its trust root at a nonstandard path), so certifi is the floor that
+    makes public certificates verify on any OS. The system store (and
+    SSL_CERT_FILE / SSL_CERT_DIR) stays in the mix on purpose: a private or
+    corporate CA installed there must keep working, which `cafile=` alone
+    would silently drop.
+    """
+    context = ssl.create_default_context()
+    context.load_verify_locations(cafile=certifi.where())
+    return context
+
+
+_TLS_CONTEXT = _tls_context()
+
+
 def _header_kwarg() -> str:
     """Name of the extra-headers keyword for the installed websockets version.
 
@@ -104,6 +125,8 @@ class TunnelSettings:
     label: str
     reconnect_delay: float = DEFAULT_RECONNECT_DELAY
     max_retries: int = DEFAULT_MAX_RETRIES
+    # Detected once at startup (see environment.detect); sent in every hello.
+    environment: Optional[Dict[str, Any]] = None
 
 
 class HubConnection:
@@ -226,6 +249,8 @@ class HubConnection:
             "ping_interval": PING_INTERVAL,
             "ping_timeout": PING_TIMEOUT,
         }
+        if urlsplit(self.url).scheme == "wss":
+            kwargs["ssl"] = _TLS_CONTEXT
 
         LOGGER.info("connecting to %s", self.url)
         async with self._connect(self.url, **kwargs) as ws:
@@ -239,6 +264,7 @@ class HubConnection:
                         self.instance,
                         self.settings.label,
                         self._descriptors(),
+                        self.settings.environment,
                     )
                 )
                 async for raw in ws:

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/tests/test_config.py

@@ -75,3 +75,52 @@ def test_neither_shape_is_an_error(tmp_path):
     cfg = write_json(tmp_path / "mcp.json", {"unrelated": True})
     with pytest.raises(ConfigError):
         load_config(cfg)
+
+
+def test_empty_mcp_servers_is_rejected(tmp_path):
+    cfg = write_json(tmp_path / "mcp.json", {"mcpServers": {}})
+    with pytest.raises(ConfigError, match="non-empty"):
+        load_config(cfg)
+
+
+def test_project_is_read_per_entry_and_from_top_level_default(tmp_path):
+    cfg = write_json(
+        tmp_path / "mcp.json",
+        {
+            "project": "nix",
+            "mcpServers": {
+                "a": {"command": "x"},
+                "b": {"command": "y", "project": "other"},
+                "c": {"command": "z", "project": "  "},
+            },
+        },
+    )
+    projects = {s.name: s.project for s in load_config(cfg)}
+    assert projects == {"a": "nix", "b": "other", "c": "nix"}
+
+
+def test_harness_is_added_by_default_and_can_be_disabled(tmp_path):
+    from mcp_switchboard_client.cli import load_servers
+
+    cfg = write_json(tmp_path / "mcp.json", {"mcpServers": {"git": {"command": "x"}}})
+    assert [s.name for s in load_servers(cfg, harness=True)] == ["git", "harness"]
+    assert [s.name for s in load_servers(cfg, harness=False)] == ["git"]
+
+
+def test_user_defined_harness_wins(tmp_path):
+    from mcp_switchboard_client.cli import load_servers
+
+    cfg = write_json(tmp_path / "mcp.json", {"mcpServers": {"harness": {"command": "mine"}}})
+    specs = load_servers(cfg, harness=True)
+    assert [(s.name, s.argv) for s in specs] == [("harness", ["mine"])]
+
+
+def test_missing_default_config_falls_back_to_the_harness_alone(tmp_path):
+    from mcp_switchboard_client.cli import load_servers
+
+    absent = tmp_path / "mcp.json"
+    assert [s.name for s in load_servers(absent, harness=True, config_required=False)] == ["harness"]
+    with pytest.raises(ConfigError, match="not found"):  # an explicitly named file must exist
+        load_servers(absent, harness=True, config_required=True)
+    with pytest.raises(ConfigError, match="not found"):  # nothing to tunnel without the harness
+        load_servers(absent, harness=False, config_required=False)

mcp_switchboard_client-0.3.0.dev3/tests/test_envconf_cases.py

@@ -0,0 +1,73 @@
+"""envconf is checked against docs/envconf-cases.json, the fixture the Go hub also runs.
+
+envconf.py stays Python-only; the hub reimplements the same two rules in Go
+(spec.md P3). This shared table is what stops the two implementations from
+disagreeing about, say, whether an empty file substitutes to an empty string
+(spec.md V4).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+import pytest
+
+from mcp_switchboard_client import envconf
+
+
+def fixture() -> dict:
+    here = Path(__file__).resolve()
+    for candidate in here.parents:
+        path = candidate / "docs" / "envconf-cases.json"
+        if path.is_file():
+            return json.loads(path.read_text(encoding="utf-8"))
+    pytest.skip("not running from a source checkout")
+
+
+FIXTURE = fixture()
+
+
+@pytest.fixture(scope="module")
+def sandbox(tmp_path_factory: pytest.TempPathFactory) -> Path:
+    root = tmp_path_factory.mktemp("envconf")
+    for name, content in FIXTURE["files"].items():
+        (root / name).write_text(content, encoding="utf-8")
+    for name in FIXTURE["dirs"]:
+        (root / name).mkdir()
+    return root
+
+
+def expand(value: Any, root: Path) -> Any:
+    return value.replace("{{dir}}", str(root)) if isinstance(value, str) else value
+
+
+def test_prefix_matches_the_fixture() -> None:
+    assert envconf.PREFIX == FIXTURE["prefix"]
+
+
+@pytest.mark.parametrize("case", FIXTURE["cases"], ids=lambda c: c["name"])
+def test_case(case: dict, sandbox: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    for key in list(__import__("os").environ):
+        if key.startswith(FIXTURE["prefix"]):
+            monkeypatch.delenv(key, raising=False)
+    for key, value in case["env"].items():
+        monkeypatch.setenv(key, expand(value, sandbox))
+
+    spec = case["get"]
+    getter = {
+        "str": lambda: envconf.get(
+            spec["name"], spec.get("default"), secret=spec.get("secret", False)
+        ),
+        "int": lambda: envconf.get_int(spec["name"], spec["default"]),
+        "float": lambda: envconf.get_float(spec["name"], spec["default"]),
+        "bool": lambda: envconf.get_bool(spec["name"], spec["default"]),
+    }[spec["kind"]]
+
+    expected = case["expect"]
+    if isinstance(expected, dict) and expected.get("error"):
+        with pytest.raises(envconf.ConfigError):
+            getter()
+    else:
+        assert getter() == expand(expected, sandbox)

mcp_switchboard_client-0.3.0.dev3/tests/test_environment.py

@@ -0,0 +1,128 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from mcp_switchboard_client import cli, environment, protocol
+
+
+@pytest.fixture(autouse=True)
+def _no_host_container(monkeypatch):
+    monkeypatch.setattr(environment, "_in_container", lambda root: False)
+    monkeypatch.setattr(environment.sys, "base_prefix", environment.sys.prefix)
+
+
+def detect(tmp_path, env=None, **kw):
+    return environment.detect(cwd=tmp_path, env=env or {}, **kw)
+
+
+def test_plain_environment(tmp_path):
+    result = detect(tmp_path)
+    assert result["kinds"] == []
+    assert result["workspace"] == str(tmp_path)
+    assert result["project"] == tmp_path.name
+    assert "details" not in result
+
+
+def test_container(tmp_path, monkeypatch):
+    monkeypatch.setattr(environment, "_in_container", lambda root: True)
+    assert detect(tmp_path)["kinds"] == ["container"]
+
+
+def test_devcontainer_env_and_jsonc_name(tmp_path):
+    (tmp_path / ".git").mkdir()
+    dc = tmp_path / ".devcontainer"
+    dc.mkdir()
+    (dc / "devcontainer.json").write_text(
+        '// c\n{\n /* x */ "name": "My // Proj",\n "image": "a",\n "list": [1, 2,],\n}\n'
+    )
+    sub = tmp_path / "src" / "deep"
+    sub.mkdir(parents=True)
+    result = detect(sub, {"REMOTE_CONTAINERS": "true"})
+    assert result["kinds"] == ["devcontainer"]
+    assert result["project"] == "My // Proj"
+    assert result["details"]["devcontainerName"] == "My // Proj"
+
+
+def test_devcontainer_via_workspaces_path(tmp_path, monkeypatch):
+    monkeypatch.setattr(environment, "_in_container", lambda root: True)
+    ws = tmp_path / "workspaces" / "p"
+    ws.mkdir(parents=True)
+    # cwd does not start with /workspaces/ here, so only "container"
+    assert detect(ws)["kinds"] == ["container"]
+    monkeypatch.setattr(environment, "find_devcontainer_name", lambda cwd: None)
+    result = environment.detect(cwd=Path("/workspaces/p"), env={})
+    assert result["kinds"] == ["devcontainer", "container"]
+
+
+def test_bad_devcontainer_json_falls_back_to_git_root(tmp_path):
+    (tmp_path / ".git").write_text("gitdir: x")
+    (tmp_path / ".devcontainer.json").write_text("{not json")
+    sub = tmp_path / "a"
+    sub.mkdir()
+    result = detect(sub, {"CODESPACES": "true"})
+    assert result["kinds"] == ["devcontainer"]
+    assert result["project"] == tmp_path.name
+
+
+def test_direnv_and_nix(tmp_path):
+    result = detect(tmp_path, {"DIRENV_DIR": "-/home/x/p", "IN_NIX_SHELL": "pure", "PATH": "/bin"})
+    assert result["kinds"] == ["direnv", "nix-shell"]
+    assert result["details"] == {"direnvDir": "/home/x/p", "nixShell": "pure"}
+
+
+def test_nix_from_path_marker(tmp_path):
+    result = detect(tmp_path, {"PATH": "/nix/store/abc-x/bin:/bin"})
+    assert result["kinds"] == ["nix-shell"]
+    assert "nixShell" not in result.get("details", {})
+
+
+def test_venv_basename_only(tmp_path):
+    result = detect(tmp_path, {"VIRTUAL_ENV": "/secret/place/.venv"})
+    assert result["kinds"] == ["venv"]
+    assert result["details"] == {"venv": ".venv"}
+
+
+def test_git_root_project(tmp_path):
+    root = tmp_path / "repo"
+    (root / ".git").mkdir(parents=True)
+    sub = root / "x" / "y"
+    sub.mkdir(parents=True)
+    assert detect(sub)["project"] == "repo"
+
+
+def test_override_wins(tmp_path):
+    assert detect(tmp_path, project_override=" mine ")["project"] == "mine"
+
+
+def test_never_raises(tmp_path, monkeypatch):
+    def boom(*a, **k):
+        raise RuntimeError("x")
+
+    monkeypatch.setattr(environment, "find_git_root", boom)
+    assert environment.detect(cwd=tmp_path, env={}) == {"kinds": []}
+
+
+def test_strip_jsonc_keeps_strings():
+    text = '{"a": "x,]", "b": [1,], // t\n}'
+    assert json.loads(environment.strip_jsonc(text)) == {"a": "x,]", "b": [1]}
+
+
+def test_hello_carries_environment():
+    env = {"kinds": ["direnv"], "workspace": "/w"}
+    assert protocol.hello("c", "1", "i", "l", [], env)["client"]["environment"] == env
+    assert "environment" not in protocol.hello("c", "1", "i", "l", [])["client"]
+
+
+def test_project_name_setting(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setenv("MCP_SWITCHBOARD_HUB_URL", "wss://h.example")
+    monkeypatch.setenv("MCP_SWITCHBOARD_TUNNEL_TOKEN", "t")
+    s = cli.build_settings([])
+    assert s.environment["project"] == tmp_path.name
+    monkeypatch.setenv("MCP_SWITCHBOARD_PROJECT_NAME", "fromenv")
+    assert cli.build_settings([]).environment["project"] == "fromenv"
+    assert cli.build_settings(["--project-name", "flag"]).environment["project"] == "flag"
+    assert cli.build_settings([]).tunnel_settings().environment["project"] == "fromenv"

mcp_switchboard_client-0.3.0.dev3/tests/test_protocol_conformance.py

@@ -0,0 +1,97 @@
+"""protocol.py is checked against docs/protocol.json, not against another copy.
+
+Byte-identity between the hub's and the client's copy (hub/tests/test_protocol_sync.py)
+only works while both are Python. The Go hub cannot participate in that check, so
+docs/protocol.json is the manifest both languages assert against instead: this file
+is the Python half, hub/internal/protocol/protocol_test.go is the Go half. Drift in
+either direction fails CI (spec.md P1/P2).
+"""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from mcp_switchboard_client import protocol
+
+
+def manifest() -> dict:
+    here = Path(__file__).resolve()
+    for candidate in here.parents:
+        path = candidate / "docs" / "protocol.json"
+        if path.is_file():
+            return json.loads(path.read_text(encoding="utf-8"))
+    pytest.skip("not running from a source checkout")
+
+
+MANIFEST = manifest()
+
+
+def test_constants_match_the_manifest() -> None:
+    assert protocol.PROTOCOL_VERSION == MANIFEST["protocolVersion"]
+    assert protocol.TUNNEL_PATH == MANIFEST["tunnelPath"]
+    assert protocol.NAME_SEPARATOR == MANIFEST["nameSeparator"]
+
+
+def test_server_states_match_the_manifest() -> None:
+    declared = {
+        protocol.STATE_STARTING,
+        protocol.STATE_RUNNING,
+        protocol.STATE_EXITED,
+        protocol.STATE_FAILED,
+    }
+    assert declared == set(MANIFEST["serverStates"])
+
+
+def test_frame_type_constants_match_the_manifest() -> None:
+    declared = {
+        protocol.HELLO,
+        protocol.HELLO_ACK,
+        protocol.MCP,
+        protocol.SERVER_STATE,
+        protocol.RESTART,
+        protocol.ERROR,
+    }
+    assert declared == set(MANIFEST["frames"])
+
+
+# One builder call per frame, with arguments chosen so that every optional field is
+# populated - a builder that silently dropped a field would otherwise pass.
+BUILDERS = {
+    "hello": lambda: protocol.hello(
+        "c", "0.0.0", "i", "lab", [{"name": "git"}], {"kinds": ["direnv"], "workspace": "/w"}
+    ),
+    "hello_ack": lambda: protocol.hello_ack("cid", "hub", "0.0.0"),
+    "mcp": lambda: protocol.mcp("git", {"jsonrpc": "2.0"}),
+    "server_state": lambda: protocol.server_state("git", protocol.STATE_EXITED, 1, "boom"),
+    "restart": lambda: protocol.restart("git"),
+    "error": lambda: protocol.error("bad", "git"),
+}
+
+
+@pytest.mark.parametrize("frame_type", sorted(MANIFEST["frames"]))
+def test_builder_emits_exactly_the_declared_fields(frame_type: str) -> None:
+    declared = MANIFEST["frames"][frame_type]
+    frame = BUILDERS[frame_type]()
+
+    assert frame["type"] == frame_type
+    allowed = set(declared["required"]) | set(declared["optional"])
+    assert set(frame) <= allowed, f"{frame_type} emits undeclared fields"
+    for field in declared["required"]:
+        assert field in frame, f"{frame_type} is missing required field {field}"
+        assert frame[field] is not None, f"required field {field} must not be null"
+
+
+def test_every_builder_is_covered() -> None:
+    """A frame added to the manifest without a builder here would not be checked."""
+    assert set(BUILDERS) == set(MANIFEST["frames"])
+
+
+def test_hello_client_optional_fields_are_declared_and_emitted() -> None:
+    declared = MANIFEST["frames"]["hello"]["clientOptional"]
+    assert "environment" in declared
+    client = protocol.hello("c", "0.0.0", "i", "lab", [], {"kinds": []})["client"]
+    assert set(client) <= {"name", "version", "instance", "label"} | set(declared)
+    assert "environment" in client

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/tests/test_settings.py

@@ -177,3 +177,17 @@ def test_settings_normalizes_the_hub_url(tmp_path, monkeypatch):
     settings = build_settings(["--hub-url", "https://hub.example.com", "--token", "t"])
     assert settings.hub_url == "wss://hub.example.com/tunnel/v1"
     assert settings.tunnel_settings().hub_url == settings.hub_url
+
+
+def test_harness_defaults_on_and_can_be_switched_off(monkeypatch):
+    assert build_settings(BASE).harness is True
+    assert build_settings(BASE + ["--no-harness"]).harness is False
+    monkeypatch.setenv("MCP_SWITCHBOARD_HARNESS", "false")
+    assert build_settings(BASE).harness is False
+
+
+def test_config_explicit_only_when_asked_for(monkeypatch):
+    assert build_settings(BASE).config_explicit is False
+    assert build_settings(BASE + ["--config", "x.json"]).config_explicit is True
+    monkeypatch.setenv("MCP_SWITCHBOARD_CONFIG", "y.json")
+    assert build_settings(BASE).config_explicit is True

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev3}/tests/test_tunnel.py

@@ -290,3 +290,30 @@ async def test_max_retries_gives_up():
     await connection.run()
 
     assert len(connect.calls) == 3
+
+
+def test_tls_context_trusts_certifi_even_without_a_system_store(monkeypatch, tmp_path):
+    """The NixOS case: no usable system CA file, so certifi alone must supply roots."""
+    from mcp_switchboard_client import tunnel
+
+    monkeypatch.setenv("SSL_CERT_FILE", str(tmp_path / "missing.pem"))
+    monkeypatch.setenv("SSL_CERT_DIR", str(tmp_path / "missing-dir"))
+    context = tunnel._tls_context()
+    assert len(context.get_ca_certs()) > 0
+    assert context.verify_mode.name == "CERT_REQUIRED" and context.check_hostname
+
+
+def test_tls_context_keeps_the_system_store_too(monkeypatch, tmp_path):
+    """A private CA supplied via SSL_CERT_FILE must still be trusted alongside certifi."""
+    import certifi
+
+    from mcp_switchboard_client import tunnel
+
+    pem = tmp_path / "extra.pem"
+    with open(certifi.where()) as f:
+        first = f.read().split("-----END CERTIFICATE-----")[0] + "-----END CERTIFICATE-----\n"
+    pem.write_text(first)
+    baseline = len(tunnel._tls_context().get_ca_certs())
+    monkeypatch.setenv("SSL_CERT_FILE", str(pem))
+    assert len(tunnel._tls_context().get_ca_certs()) >= 1
+    assert baseline >= 1

mcp_switchboard_client-0.2.0/.gitignore

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