mcp-switchboard-hub 0.2.0__tar.gz

mcp_switchboard_hub-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_hub-0.2.0/PKG-INFO

@@ -0,0 +1,62 @@
+Metadata-Version: 2.5
+Name: mcp-switchboard-hub
+Version: 0.2.0
+Summary: Aggregating MCP gateway for outbound tunnels, with a web console, call log, and Prometheus/Loki export
+Project-URL: Homepage, https://github.com/AkosPapp/mcp-switchboard
+Project-URL: Repository, https://github.com/AkosPapp/mcp-switchboard
+Author: Akos Papp
+License: MIT
+Keywords: gateway,mcp,model-context-protocol,n8n,reverse-proxy
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.2
+Requires-Dist: prometheus-client>=0.20
+Requires-Dist: uvicorn>=0.30
+Requires-Dist: websockets>=12
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# mcp-switchboard-hub
+
+The server half of [mcp-switchboard](https://github.com/AkosPapp/mcp-switchboard).
+
+It accepts outbound WebSocket tunnels from machines running local stdio MCP
+servers, speaks MCP to each tunnelled server, and re-serves every tool from one
+place:
+
+- **`/mcp`** — Streamable HTTP MCP endpoint for consumers (n8n, agents), also
+  available scoped per machine (`/mcp/host/{label}`) or per server
+  (`/mcp/host/{label}/server/{server}`).
+- **`/`** — a web console to browse connections, servers and tools, call any tool
+  by hand, and read back every call.
+- **`/api/*`** — the JSON API behind the console.
+- **`/metrics`** — Prometheus.
+- Loki export and a SQLite call log.
+
+## Running
+
+```sh
+pip install mcp-switchboard-hub
+MCP_SWITCHBOARD_TUNNEL_TOKEN=... mcp-switchboard-hub
+```
+
+It listens on two ports on purpose: the tunnel endpoint (default
+`127.0.0.1:8097`) is the only thing meant to face the internet and always
+requires a bearer token, while the console, API, `/mcp` and `/metrics` live on a
+second listener (default `127.0.0.1:8099`) that binds loopback and is
+unauthenticated by default.
+
+Everything is configured through `MCP_SWITCHBOARD_*` environment variables, read
+from the environment or a `.env` file. Any value that starts with `/` and points
+at an existing regular file is replaced by that file's contents, so secrets can
+be passed as paths without separate `*_FILE` variables.
+
+See the [main README](../README.md) for the full picture, and
+[docs/PROTOCOL.md](../docs/PROTOCOL.md) for the tunnel wire format.

mcp_switchboard_hub-0.2.0/README.md

@@ -0,0 +1,37 @@
+# mcp-switchboard-hub
+
+The server half of [mcp-switchboard](https://github.com/AkosPapp/mcp-switchboard).
+
+It accepts outbound WebSocket tunnels from machines running local stdio MCP
+servers, speaks MCP to each tunnelled server, and re-serves every tool from one
+place:
+
+- **`/mcp`** — Streamable HTTP MCP endpoint for consumers (n8n, agents), also
+  available scoped per machine (`/mcp/host/{label}`) or per server
+  (`/mcp/host/{label}/server/{server}`).
+- **`/`** — a web console to browse connections, servers and tools, call any tool
+  by hand, and read back every call.
+- **`/api/*`** — the JSON API behind the console.
+- **`/metrics`** — Prometheus.
+- Loki export and a SQLite call log.
+
+## Running
+
+```sh
+pip install mcp-switchboard-hub
+MCP_SWITCHBOARD_TUNNEL_TOKEN=... mcp-switchboard-hub
+```
+
+It listens on two ports on purpose: the tunnel endpoint (default
+`127.0.0.1:8097`) is the only thing meant to face the internet and always
+requires a bearer token, while the console, API, `/mcp` and `/metrics` live on a
+second listener (default `127.0.0.1:8099`) that binds loopback and is
+unauthenticated by default.
+
+Everything is configured through `MCP_SWITCHBOARD_*` environment variables, read
+from the environment or a `.env` file. Any value that starts with `/` and points
+at an existing regular file is replaced by that file's contents, so secrets can
+be passed as paths without separate `*_FILE` variables.
+
+See the [main README](../README.md) for the full picture, and
+[docs/PROTOCOL.md](../docs/PROTOCOL.md) for the tunnel wire format.

mcp_switchboard_hub-0.2.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "mcp-switchboard-hub"
+version = "0.2.0"
+description = "Aggregating MCP gateway for outbound tunnels, with a web console, call log, and Prometheus/Loki export"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Akos Papp" }]
+keywords = ["mcp", "model-context-protocol", "gateway", "reverse-proxy", "n8n"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "mcp>=2.2,<3",
+    "fastapi>=0.115",
+    "uvicorn>=0.30",
+    "websockets>=12",
+    "prometheus-client>=0.20",
+    "aiosqlite>=0.20",
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/AkosPapp/mcp-switchboard"
+Repository = "https://github.com/AkosPapp/mcp-switchboard"
+
+[project.scripts]
+mcp-switchboard-hub = "mcp_switchboard_hub.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_switchboard_hub"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

mcp_switchboard_hub-0.2.0/src/mcp_switchboard_hub/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

mcp_switchboard_hub-0.2.0/src/mcp_switchboard_hub/api.py

@@ -0,0 +1,321 @@
+"""HTTP API and web console for the hub.
+
+Everything here is a thin shell over ``request.app.state.service``: this module
+holds no state of its own, so it can be mounted by whatever composes the app
+without an initialisation order to get wrong.
+
+Two deliberate choices worth knowing about:
+
+* A tool that answers with an MCP error is a **successful call that returned an
+  error**: 200 with ``status: "error"`` in the body. Only an unknown
+  connection/server/tool (``LookupError``) is a 404. Folding the two together
+  would make the console report transport failures as tool bugs.
+* The console is served from ``web/`` through ``importlib.resources``, not from
+  a path relative to the source tree, so it works the same from a wheel, a Nix
+  store path, or a git checkout.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+from contextlib import suppress
+from importlib import resources
+from typing import Any, Dict, Optional, Tuple
+
+from fastapi import APIRouter, Depends, HTTPException, Request, Response
+from fastapi.responses import HTMLResponse, StreamingResponse
+from pydantic import BaseModel, Field
+
+LOG = logging.getLogger(__name__)
+
+#: How long the SSE stream may stay silent before it emits a comment. Proxies
+#: and browsers drop idle connections well before a quiet hub would otherwise
+#: say anything.
+KEEPALIVE_SECONDS = 15.0
+
+#: Events buffered per SSE client before the oldest are dropped. A reader that
+#: falls this far behind has lost history either way; staying live matters more.
+EVENT_QUEUE_SIZE = 1000
+
+DEFAULT_CALL_LIMIT = 100
+MAX_CALL_LIMIT = 1000
+
+CALL_SOURCE_CONSOLE = "console"
+
+_STREAM_END = object()
+
+_SAFE_SEGMENT = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]*$")
+
+_CONTENT_TYPES = {
+    ".html": "text/html; charset=utf-8",
+    ".js": "text/javascript; charset=utf-8",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json",
+    ".map": "application/json",
+    ".svg": "image/svg+xml",
+    ".png": "image/png",
+    ".ico": "image/x-icon",
+    ".woff2": "font/woff2",
+    ".txt": "text/plain; charset=utf-8",
+}
+
+
+# --------------------------------------------------------------------------
+# service access
+# --------------------------------------------------------------------------
+
+
+def get_service(request: Request) -> Any:
+    """The live service object, or 503 while the app is still starting."""
+    service = getattr(request.app.state, "service", None)
+    if service is None:
+        raise HTTPException(status_code=503, detail="hub service is not ready")
+    return service
+
+
+ServiceDep = Depends(get_service)
+
+
+def record_json(record: Any) -> Any:
+    """Normalise a CallRecord to its JSON form, passing dicts through."""
+    to_json = getattr(record, "to_json", None)
+    return to_json() if callable(to_json) else record
+
+
+def _clean(value: Optional[str]) -> Optional[str]:
+    """Treat an empty query parameter as an absent filter."""
+    if value is None:
+        return None
+    value = value.strip()
+    return value or None
+
+
+# --------------------------------------------------------------------------
+# static assets
+# --------------------------------------------------------------------------
+
+
+def web_root():
+    """Traversable root of the bundled console."""
+    return resources.files(__package__ or "mcp_switchboard_hub").joinpath("web")
+
+
+def content_type_for(name: str) -> str:
+    suffix = name[name.rfind(".") :].lower() if "." in name else ""
+    return _CONTENT_TYPES.get(suffix, "application/octet-stream")
+
+
+def read_web_asset(relative: str) -> Tuple[bytes, str]:
+    """Read ``web/<relative>``; 404 on anything that is not a plain asset."""
+    parts = [part for part in relative.split("/") if part]
+    if not parts or not all(_SAFE_SEGMENT.match(part) for part in parts):
+        raise HTTPException(status_code=404, detail="not found")
+    node = web_root()
+    for part in parts:
+        node = node.joinpath(part)
+    try:
+        payload = node.read_bytes()
+    except (FileNotFoundError, NotADirectoryError, IsADirectoryError, PermissionError, OSError):
+        raise HTTPException(status_code=404, detail="not found") from None
+    return payload, content_type_for(parts[-1])
+
+
+# --------------------------------------------------------------------------
+# SSE
+# --------------------------------------------------------------------------
+
+
+def sse_message(event: Any) -> str:
+    payload = json.dumps(event, separators=(",", ":"), default=str)
+    return f"data: {payload}\n\n"
+
+
+async def _pump(source: Any, queue: "asyncio.Queue[Any]") -> None:
+    """Drain the service subscription into a per-client queue."""
+    try:
+        async for event in source:
+            if queue.full():
+                with suppress(asyncio.QueueEmpty):
+                    queue.get_nowait()
+            queue.put_nowait(event)
+    except asyncio.CancelledError:
+        raise
+    except Exception:  # a broken subscription ends the stream, not the process
+        LOG.exception("event subscription failed")
+    finally:
+        with suppress(asyncio.QueueFull):
+            queue.put_nowait(_STREAM_END)
+
+
+async def event_stream(request: Request, service: Any):
+    """Yield SSE frames from ``service.subscribe()`` until either side stops."""
+    queue: "asyncio.Queue[Any]" = asyncio.Queue(maxsize=EVENT_QUEUE_SIZE)
+    source = service.subscribe()
+    pump = asyncio.ensure_future(_pump(source, queue))
+    try:
+        # Flush headers immediately so the browser reports the stream as open.
+        yield ": connected\n\n"
+        while True:
+            try:
+                event = await asyncio.wait_for(queue.get(), timeout=KEEPALIVE_SECONDS)
+            except asyncio.TimeoutError:
+                if await request.is_disconnected():
+                    break
+                yield ": keepalive\n\n"
+                continue
+            if event is _STREAM_END:
+                break
+            yield sse_message(event)
+    finally:
+        pump.cancel()
+        with suppress(asyncio.CancelledError, Exception):
+            await pump
+        aclose = getattr(source, "aclose", None)
+        if callable(aclose):
+            with suppress(Exception):
+                await aclose()
+
+
+# --------------------------------------------------------------------------
+# request bodies
+# --------------------------------------------------------------------------
+
+
+class ToolCallRequest(BaseModel):
+    arguments: Dict[str, Any] = Field(default_factory=dict)
+
+
+# --------------------------------------------------------------------------
+# router
+# --------------------------------------------------------------------------
+
+
+def create_api_router() -> APIRouter:
+    """Build the hub's HTTP surface: JSON API, metrics, and the web console."""
+    router = APIRouter()
+
+    @router.get("/api/connections")
+    async def connections(service: Any = ServiceDep) -> Any:
+        return service.snapshot()
+
+    @router.post("/api/connections/{connection_id}/servers/{server}/tools/{tool}/call")
+    async def call_tool(
+        connection_id: str,
+        server: str,
+        tool: str,
+        body: ToolCallRequest = ToolCallRequest(),
+        service: Any = ServiceDep,
+    ) -> Any:
+        try:
+            record = await service.execute_tool_call(
+                connection_id=connection_id,
+                server=server,
+                tool=tool,
+                arguments=body.arguments,
+                source=CALL_SOURCE_CONSOLE,
+            )
+        except LookupError as exc:
+            raise HTTPException(status_code=404, detail=str(exc) or "unknown tool") from exc
+        return record_json(record)
+
+    @router.post(
+        "/api/connections/{connection_id}/servers/{server}/restart",
+        status_code=204,
+        response_class=Response,
+    )
+    async def restart_server(connection_id: str, server: str, service: Any = ServiceDep) -> Response:
+        try:
+            await service.restart_server(connection_id, server)
+        except LookupError as exc:
+            raise HTTPException(status_code=404, detail=str(exc) or "unknown server") from exc
+        return Response(status_code=204)
+
+    @router.get("/api/calls")
+    async def list_calls(
+        limit: int = DEFAULT_CALL_LIMIT,
+        offset: int = 0,
+        server: Optional[str] = None,
+        tool: Optional[str] = None,
+        status: Optional[str] = None,
+        label: Optional[str] = None,
+        service: Any = ServiceDep,
+    ) -> Any:
+        # Clamped rather than rejected: a console asking for too much should get
+        # a page of results, not a validation error.
+        limit = max(1, min(int(limit), MAX_CALL_LIMIT))
+        offset = max(0, int(offset))
+        records = await service.calls.list(
+            limit=limit,
+            offset=offset,
+            server=_clean(server),
+            tool=_clean(tool),
+            status=_clean(status),
+            label=_clean(label),
+        )
+        return {
+            "calls": [record_json(record) for record in records],
+            "stats": await service.calls.stats(),
+            "limit": limit,
+            "offset": offset,
+        }
+
+    @router.get("/api/calls/{call_id}")
+    async def get_call(call_id: str, service: Any = ServiceDep) -> Any:
+        record = await service.calls.get(call_id)
+        if record is None:
+            raise HTTPException(status_code=404, detail="unknown call")
+        return record_json(record)
+
+    @router.get("/api/events")
+    async def events(request: Request, service: Any = ServiceDep) -> StreamingResponse:
+        return StreamingResponse(
+            event_stream(request, service),
+            media_type="text/event-stream",
+            headers={
+                "Cache-Control": "no-cache, no-transform",
+                "Connection": "keep-alive",
+                # nginx buffers streamed responses unless told not to.
+                "X-Accel-Buffering": "no",
+            },
+        )
+
+    @router.get("/metrics")
+    async def metrics(service: Any = ServiceDep) -> Response:
+        rendered = service.metrics.render()
+        if asyncio.iscoroutine(rendered):
+            rendered = await rendered
+        payload, content_type = rendered
+        return Response(content=payload, media_type=content_type)
+
+    @router.get("/", response_class=HTMLResponse, include_in_schema=False)
+    async def console() -> HTMLResponse:
+        payload, _ = read_web_asset("index.html")
+        return HTMLResponse(content=payload.decode("utf-8"), headers={"Cache-Control": "no-cache"})
+
+    @router.get("/static/{path:path}", include_in_schema=False)
+    async def static_asset(path: str) -> Response:
+        payload, content_type = read_web_asset(path)
+        return Response(
+            content=payload,
+            media_type=content_type,
+            headers={"Cache-Control": "no-cache"},
+        )
+
+    return router
+
+
+__all__ = [
+    "CALL_SOURCE_CONSOLE",
+    "DEFAULT_CALL_LIMIT",
+    "KEEPALIVE_SECONDS",
+    "MAX_CALL_LIMIT",
+    "ToolCallRequest",
+    "create_api_router",
+    "get_service",
+    "read_web_asset",
+    "record_json",
+    "web_root",
+]

mcp_switchboard_hub-0.2.0/src/mcp_switchboard_hub/app.py

@@ -0,0 +1,120 @@
+"""Builds the two listeners.
+
+They are separate apps on separate ports for a deliberate reason: only the tunnel
+endpoint is meant to be reachable from the internet, and it always requires a
+token. The console, the API, the MCP endpoint and /metrics live on a second
+listener that binds loopback, so they are not protected by a password - they are
+simply not reachable. That is a stronger guarantee than a shared secret, and it
+is why the private listener is unauthenticated by default.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import logging
+from dataclasses import dataclass
+from typing import AsyncIterator
+
+from fastapi import FastAPI, Request, WebSocket
+from fastapi.responses import JSONResponse
+
+from . import protocol
+from .api import create_api_router
+from .calls import CallStore
+from .config import Settings
+from .loki import LokiExporter
+from .mcp_endpoint import McpEndpoint
+from .metrics import Metrics
+from .registry import Registry
+from .service import Service
+from .tunnel import TunnelHandler
+
+LOGGER = logging.getLogger("mcp_switchboard_hub.app")
+
+
+@dataclass
+class Hub:
+    settings: Settings
+    service: Service
+    mcp: McpEndpoint
+    tunnel_app: FastAPI
+    private_app: FastAPI
+
+    @contextlib.asynccontextmanager
+    async def lifespan(self) -> AsyncIterator["Hub"]:
+        """Own everything process-wide, rather than per-app.
+
+        The MCP session manager's run() must be entered exactly once, and both
+        apps share one Service, so the lifecycle belongs here and not in either
+        app's own lifespan.
+        """
+        async with contextlib.AsyncExitStack() as stack:
+            await self.service.start()
+            stack.push_async_callback(self.service.close)
+            await stack.enter_async_context(self.mcp.run())
+            yield self
+
+
+def build_hub(settings: Settings) -> Hub:
+    registry = Registry()
+    metrics = Metrics()
+    calls = CallStore(settings.db_path, retention_days=settings.retention_days, max_rows=settings.max_rows)
+    loki = LokiExporter(
+        url=settings.loki_url,
+        labels=settings.loki_labels,
+        enabled=settings.loki_enabled,
+        metrics=metrics,
+    )
+
+    service = Service(settings, registry, calls, metrics, loki)
+    mcp = McpEndpoint(registry, service)
+    service.mcp = mcp
+
+    handler = TunnelHandler(
+        registry,
+        token=settings.tunnel_token,
+        tools_timeout=settings.tools_timeout,
+        on_change=service.on_topology_change,
+        metrics=metrics,
+    )
+
+    tunnel_app = FastAPI(title="mcp-switchboard tunnel", docs_url=None, redoc_url=None)
+
+    @tunnel_app.websocket(protocol.TUNNEL_PATH)
+    async def tunnel_endpoint(websocket: WebSocket) -> None:  # pragma: no cover - exercised end to end
+        await handler.handle(websocket)
+
+    @tunnel_app.get("/health")
+    async def tunnel_health() -> dict:
+        return {"status": "ok"}
+
+    private_app = FastAPI(title="mcp-switchboard", docs_url=None, redoc_url=None)
+    private_app.state.service = service
+
+    if settings.private_token:
+        _require_token(private_app, settings.private_token)
+
+    private_app.include_router(create_api_router())
+    for route in mcp.routes():
+        private_app.router.routes.append(route)
+
+    @private_app.get("/health")
+    async def private_health() -> dict:
+        return {"status": "ok"}
+
+    return Hub(settings=settings, service=service, mcp=mcp, tunnel_app=tunnel_app, private_app=private_app)
+
+
+def _require_token(app: FastAPI, token: str) -> None:
+    """Optional bearer auth for the private listener, for when it is exposed anyway."""
+    import hmac
+
+    @app.middleware("http")
+    async def check_token(request: Request, call_next):
+        if request.url.path == "/health":
+            return await call_next(request)
+        header = request.headers.get("authorization", "")
+        supplied = header[len("Bearer ") :].strip() if header.startswith("Bearer ") else ""
+        if not hmac.compare_digest(supplied, token):
+            return JSONResponse({"detail": "unauthorized"}, status_code=401)
+        return await call_next(request)