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

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev4}/.gitignore

@@ -11,3 +11,5 @@ dist/
 .env
 result
 result-*
+.direnv/
+hub/mcp-switchboard-hub

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: mcp-switchboard-client
-Version: 0.2.0
+Version: 0.3.0.dev4
 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,34 @@ 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.
+
+The client also collects the instruction files your repository carries for coding
+agents (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`,
+also at any depth, capped at 8 files / 64 KiB) from the start directory and ships them
+to the hub, which puts them into the agent's system prompt; it re-sends them whenever
+they change, so an edit to `AGENTS.md` reaches a running session. Turn it off with
+`--no-instructions` or `MCP_SWITCHBOARD_INSTRUCTIONS=false`.
+
+A push is treated as what it is: the harness marks `git_push` irreversible in its tool `_meta`, so
+the hub asks for approval before any agent can run it — even one set to `approval=never`. If that
+friction is wrong for your deployment, that is a decision to make deliberately, not by silence.
+
+Alongside them the client ships a short environment brief of the host your tools run
+on — user, hostname, git branch/dirtiness (remote with credentials redacted), what the
+file tools may write, tool presence; sudo is reported only if provable without a
+prompt, and network reachability is never probed — refreshed like the instruction
+files and marked stale by the hub if a client vanishes. Turn it off with
+`--no-env-brief` or `MCP_SWITCHBOARD_ENV_BRIEF=false`.
+
 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.3.0.dev4/README.md

@@ -0,0 +1,76 @@
+# 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 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
+
+```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. It is optional:
+without one, the client tunnels just the built-in coding harness (see below):
+
+```json
+{
+  "mcpServers": {
+    "git": { "command": "uvx", "args": ["mcp-server-git", "--repository", "."] }
+  }
+}
+```
+
+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.
+
+The client also collects the instruction files your repository carries for coding
+agents (`AGENTS.md`, `CLAUDE.md`, `.cursorrules`, `.github/copilot-instructions.md`,
+also at any depth, capped at 8 files / 64 KiB) from the start directory and ships them
+to the hub, which puts them into the agent's system prompt; it re-sends them whenever
+they change, so an edit to `AGENTS.md` reaches a running session. Turn it off with
+`--no-instructions` or `MCP_SWITCHBOARD_INSTRUCTIONS=false`.
+
+A push is treated as what it is: the harness marks `git_push` irreversible in its tool `_meta`, so
+the hub asks for approval before any agent can run it — even one set to `approval=never`. If that
+friction is wrong for your deployment, that is a decision to make deliberately, not by silence.
+
+Alongside them the client ships a short environment brief of the host your tools run
+on — user, hostname, git branch/dirtiness (remote with credentials redacted), what the
+file tools may write, tool presence; sudo is reported only if provable without a
+prompt, and network reachability is never probed — refreshed like the instruction
+files and marked stale by the hub if a client vanishes. Turn it off with
+`--no-env-brief` or `MCP_SWITCHBOARD_ENV_BRIEF=false`.
+
+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 → mcp_switchboard_client-0.3.0.dev4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "mcp-switchboard-client"
-version = "0.2.0"
+version = "0.3.0.dev4"
 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.dev4}/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.dev4}/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,15 @@ 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
+    instruction_root: Optional[str] = None  # cwd by default; None disables shipping
+    env_brief: bool = True  # host brief in hello + context_update
 
     def tunnel_settings(self) -> TunnelSettings:
         return TunnelSettings(
@@ -58,6 +64,9 @@ class Settings:
             label=self.label,
             reconnect_delay=self.reconnect_delay,
             max_retries=self.max_retries,
+            environment=self.environment,
+            instruction_root=self.instruction_root,
+            env_brief=self.env_brief,
         )
 
 
@@ -92,6 +101,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,12 +140,36 @@ 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,
         default=None,
         help=f"Log level (default {DEFAULT_LOG_LEVEL}, or {envconf.PREFIX}LOG_LEVEL)",
     )
+    parser.add_argument(
+        "--no-instructions",
+        action="store_true",
+        help=(
+            "Do not collect instruction files (AGENTS.md, CLAUDE.md, ...) from the working "
+            f"directory and send them to the hub (or set {envconf.PREFIX}INSTRUCTIONS=false)"
+        ),
+    )
+    parser.add_argument(
+        "--no-env-brief",
+        action="store_true",
+        help=(
+            "Do not send the host environment brief (identity, host, git state, writable set, "
+            f"tool presence) to the hub (or set {envconf.PREFIX}ENV_BRIEF=false)"
+        ),
+    )
     return parser
 
 
@@ -168,9 +209,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 +244,19 @@ 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),
+        instruction_root=(
+            None
+            if args.no_instructions or not envconf.get_bool("INSTRUCTIONS", True)
+            else str(Path.cwd())
+        ),
+        env_brief=not args.no_env_brief and envconf.get_bool("ENV_BRIEF", True),
     )
 
 
@@ -210,12 +264,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
@@ -230,7 +297,8 @@ def setup_logging(level: str) -> None:
     )
 
 
-async def _run(settings: Settings, specs: List[ServerSpec]) -> None:
+async def _run(settings: Settings, specs: List[ServerSpec]) -> Optional[str]:
+    """Run the tunnel; returns a failure message if it gave up, else None."""
     connection = HubConnection(specs, settings.tunnel_settings(), version=__version__)
 
     def request_stop() -> None:
@@ -254,8 +322,19 @@ 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))
+    if settings.instruction_root:
+        found = environment.collect_instructions(Path(settings.instruction_root))
+        LOGGER.info(
+            "instruction files: %s",
+            ", ".join(f["path"] for f in found) if found else "none found",
+        )
+    if settings.env_brief:
+        LOGGER.info("environment brief: enabled (turn off with --no-env-brief)")
     await connection.run()
     LOGGER.info("shutdown complete")
+    return connection.failure
 
 
 def main(argv: Optional[Sequence[str]] = None) -> None:
@@ -269,13 +348,22 @@ 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)
 
     try:
-        asyncio.run(_run(settings, specs))
+        failure = asyncio.run(_run(settings, specs))
+        if failure:
+            print(f"{PROG}: error: {failure}", file=sys.stderr)
+            sys.exit(1)
     except KeyboardInterrupt:
         pass
     except TunnelError as e:

{mcp_switchboard_client-0.2.0 → mcp_switchboard_client-0.3.0.dev4}/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"])