mcp-combiner 0.6.0__tar.gz

mcp_combiner-0.6.0/.gitignore

@@ -0,0 +1,19 @@
+/combiner/mcp_combiner/__pycache__
+/combiner/tests/__pycache__
+
+# Quarto docs build artifacts
+/_site/
+/.quarto/
+**/*.quarto_ipynb
+_quarto-deploy.yml
+
+# Python virtualenvs, caches, build output (combiner package)
+.venv/
+**/.venv/
+**/.venv.backup*/
+**/__pycache__/
+**/.mypy_cache/
+**/.pytest_cache/
+**/.ruff_cache/
+/combiner/dist/
+*.egg-info/

mcp_combiner-0.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 George Harker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_combiner-0.6.0/PKG-INFO

@@ -0,0 +1,66 @@
+Metadata-Version: 2.4
+Name: mcp-combiner
+Version: 0.6.0
+Summary: An MCP aggregator — fronts multiple MCP servers behind a single Streamable HTTP endpoint, shareable across clients.
+Project-URL: Homepage, https://github.com/georgeharker/mcp-companion
+Project-URL: Repository, https://github.com/georgeharker/mcp-companion
+Project-URL: Issues, https://github.com/georgeharker/mcp-companion/issues
+Author-email: George Harker <george@georgeharker.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aggregator,fastmcp,mcp,neovim,proxy
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.12
+Requires-Dist: fastmcp<4,>=3.0
+Requires-Dist: pynvim>=0.6.0
+Description-Content-Type: text/markdown
+
+# mcp-combiner
+
+An **MCP aggregator** — fronts multiple MCP servers behind a single Streamable HTTP endpoint, so
+one connection exposes every backend server's tools. Built on
+[FastMCP](https://github.com/jlowin/fastmcp). Shareable across clients (via `sharedserver`), it
+powers the [mcp-companion](https://github.com/georgeharker/mcp-companion) Neovim plugin and the
+[`claude-mcp-combiner`](https://github.com/georgeharker/claude-mcp-combiner) Claude Code plugin, and works standalone with any MCP client.
+
+> PyPI package · command · import package: **`mcp-combiner`** / `mcp-combiner` / `mcp_combiner`.
+
+> ⚠️ **Renamed from `mcp-bridge`.** If you ran an earlier build:
+> - command/import are now `mcp-combiner` / `mcp_combiner`; reinstall:
+>   `uv tool uninstall mcp-bridge` then `uv tool install …` (see Install below).
+> - config env vars `MCP_BRIDGE_*` → `MCP_COMBINER_*` (and `MCP_COMPANION_COMBINER_URL` →
+>   `MCP_COMPANION_COMBINER_URL`).
+> - OAuth token storage moved to `~/.cache/mcp-combiner/` — you'll **re-authenticate each MCP
+>   server once** (old tokens under `~/.cache/mcp-companion/` are no longer read).
+
+## Install
+
+Needs only [uv](https://docs.astral.sh/uv/) — `uvx` fetches and runs it, no venv to manage:
+
+```bash
+uvx mcp-combiner --help                                                # once published to PyPI
+# before PyPI (or to track main) — the package lives in the combiner/ subdirectory:
+uvx --from "git+https://github.com/georgeharker/mcp-companion#subdirectory=combiner" mcp-combiner
+```
+
+Or install it: `uv pip install mcp-combiner` (PyPI), or from the repo subdir
+`uv pip install "git+https://github.com/georgeharker/mcp-companion#subdirectory=combiner"`.
+
+## Usage
+
+```bash
+mcp-combiner --config /path/to/servers.json --port 9741
+```
+
+## Development
+
+```bash
+uv sync
+pytest
+```

mcp_combiner-0.6.0/README.md

@@ -0,0 +1,43 @@
+# mcp-combiner
+
+An **MCP aggregator** — fronts multiple MCP servers behind a single Streamable HTTP endpoint, so
+one connection exposes every backend server's tools. Built on
+[FastMCP](https://github.com/jlowin/fastmcp). Shareable across clients (via `sharedserver`), it
+powers the [mcp-companion](https://github.com/georgeharker/mcp-companion) Neovim plugin and the
+[`claude-mcp-combiner`](https://github.com/georgeharker/claude-mcp-combiner) Claude Code plugin, and works standalone with any MCP client.
+
+> PyPI package · command · import package: **`mcp-combiner`** / `mcp-combiner` / `mcp_combiner`.
+
+> ⚠️ **Renamed from `mcp-bridge`.** If you ran an earlier build:
+> - command/import are now `mcp-combiner` / `mcp_combiner`; reinstall:
+>   `uv tool uninstall mcp-bridge` then `uv tool install …` (see Install below).
+> - config env vars `MCP_BRIDGE_*` → `MCP_COMBINER_*` (and `MCP_COMPANION_COMBINER_URL` →
+>   `MCP_COMPANION_COMBINER_URL`).
+> - OAuth token storage moved to `~/.cache/mcp-combiner/` — you'll **re-authenticate each MCP
+>   server once** (old tokens under `~/.cache/mcp-companion/` are no longer read).
+
+## Install
+
+Needs only [uv](https://docs.astral.sh/uv/) — `uvx` fetches and runs it, no venv to manage:
+
+```bash
+uvx mcp-combiner --help                                                # once published to PyPI
+# before PyPI (or to track main) — the package lives in the combiner/ subdirectory:
+uvx --from "git+https://github.com/georgeharker/mcp-companion#subdirectory=combiner" mcp-combiner
+```
+
+Or install it: `uv pip install mcp-combiner` (PyPI), or from the repo subdir
+`uv pip install "git+https://github.com/georgeharker/mcp-companion#subdirectory=combiner"`.
+
+## Usage
+
+```bash
+mcp-combiner --config /path/to/servers.json --port 9741
+```
+
+## Development
+
+```bash
+uv sync
+pytest
+```

mcp_combiner-0.6.0/mcp_combiner/__init__.py

@@ -0,0 +1,3 @@
+"""mcp-combiner — a FastMCP MCP aggregator: fronts multiple MCP servers behind one endpoint."""
+
+__version__ = "0.6.0"

mcp_combiner-0.6.0/mcp_combiner/__main__.py

@@ -0,0 +1,434 @@
+"""CLI entry point for mcp-combiner."""
+
+import argparse
+import atexit
+import logging
+import os
+import re
+import signal
+import sys
+import types
+
+import uvicorn
+from starlette.applications import Starlette
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request as StarletteRequest
+from starlette.responses import Response
+
+from mcp_combiner.server import (
+    _pending_token_filters,
+    _token_sessions,
+    create_combiner,
+)
+from mcp_combiner.sharedserver import cleanup as cleanup_sharedservers
+from mcp_combiner.sharedserver import register_for_cleanup
+
+logger = logging.getLogger(__name__)
+
+_mcp_log = logging.getLogger("mcp-combiner.requests")
+
+# Header name the Neovim plugin sets on ACP-injected mcpServers entries.
+_ACP_TOKEN_HEADER = "x-mcp-combiner-session"
+
+# UUID pattern: validates tokens from both header and URL path.
+_TOKEN_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
+
+# Match /mcp/<uuid>[/...] in the URL path.
+_MCP_TOKEN_PATH_RE = re.compile(
+    r"^/mcp/([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})(/.*)?$"
+)
+
+
+class TokenRewriteMiddleware(BaseHTTPMiddleware):
+    """Map token -> MCP session-id and apply pending filters on connect.
+
+    Accepts the token from two sources:
+      1. URL path: /mcp/<token>[/...] — rewrites to /mcp so FastMCP sees a plain request.
+      2. HTTP header: X-MCP-Combiner-Session — fallback.
+
+    On first request carrying a token, records token->session_id from the response
+    header.  If a pending filter was stored via POST /sessions/token/<token>/filter
+    before the client connected, it is applied immediately.
+    """
+
+    async def dispatch(
+        self, request: StarletteRequest, call_next: RequestResponseEndpoint
+    ) -> Response:
+        path = request.url.path
+
+        # --- Source 1: token in URL path ---
+        url_token: str | None = None
+        path_match = _MCP_TOKEN_PATH_RE.match(path)
+        if path_match:
+            url_token = path_match.group(1)
+            remainder = path_match.group(2) or ""
+            new_path = f"/mcp{remainder}"
+            logger.info(
+                "Token in URL path: token=%s  %s -> %s",
+                url_token,
+                path,
+                new_path,
+            )
+            # Mutate scope in-place; BaseHTTPMiddleware passes the same scope dict
+            # to call_next so FastMCP receives the rewritten path.
+            request.scope["path"] = new_path
+            request.scope["raw_path"] = new_path.encode()
+            # Re-surface the URL token as a header so the FastMCP-layer
+            # middleware can build the session_id -> token reverse map (it only
+            # sees context.session_id, never the URL — see
+            # ToolProcessingMiddleware.on_request in server.py).
+            #
+            # WHY this is needed: header-sending clients (Claude Code, OpenCode,
+            # the documented ACP entry) already send X-MCP-Combiner-Session, so for
+            # them this is a redundant no-op. But URL-only transports — notably
+            # the stdio `mcp-remote` fallback, which forwards neither env nor
+            # headers, only the URL — would otherwise never get the token to the
+            # FastMCP layer, breaking neovim_* routing for that session. This
+            # injection makes /mcp/<token> a self-sufficient correlation channel.
+            # Replace any existing value so URL wins over a stale header.
+            hdr = _ACP_TOKEN_HEADER.encode()
+            headers = [(k, v) for (k, v) in request.scope["headers"] if k.lower() != hdr]
+            headers.append((hdr, url_token.encode()))
+            request.scope["headers"] = headers
+
+        # --- Source 2: token in header ---
+        header_token: str | None = request.headers.get(_ACP_TOKEN_HEADER)
+        if header_token and not _TOKEN_RE.match(header_token):
+            header_token = None
+
+        token = url_token or header_token
+
+        if token is None:
+            return await call_next(request)
+
+        already_mapped = token in _token_sessions
+        if not already_mapped:
+            logger.info(
+                "Token not yet mapped: token=%s  source=%s  method=%s",
+                token,
+                "url" if url_token else "header",
+                request.method,
+            )
+        else:
+            logger.debug(
+                "Token already mapped: token=%s  session=%s",
+                token,
+                _token_sessions[token],
+            )
+
+        response = await call_next(request)
+
+        if not already_mapped:
+            sid = response.headers.get("mcp-session-id")
+            if sid:
+                _token_sessions[token] = sid
+                logger.info(
+                    "Token mapped: token=%s  session=%s  source=%s",
+                    token,
+                    sid,
+                    "url" if url_token else "header",
+                )
+                # Apply any pending filter that was stored before the client connected
+                pending = _pending_token_filters.pop(token, None)
+                if pending:
+                    from mcp_combiner.server import _session_disabled
+
+                    _session_disabled[sid] = pending
+                    logger.info(
+                        "Pending token filter applied: token=%s  session=%s  disabled=%s",
+                        token,
+                        sid,
+                        sorted(pending),
+                    )
+            else:
+                logger.debug(
+                    "Token seen but no mcp-session-id in response: token=%s  status=%d  source=%s",
+                    token,
+                    response.status_code,
+                    "url" if url_token else "header",
+                )
+
+        return response
+
+
+class MCPRequestLogMiddleware(BaseHTTPMiddleware):
+    """Log /mcp requests: debug-level detail on every request, warnings on non-2xx."""
+
+    async def dispatch(
+        self, request: StarletteRequest, call_next: RequestResponseEndpoint
+    ) -> Response:
+        path = request.url.path
+        is_mcp = path == "/mcp" or path.startswith("/mcp/")
+        if is_mcp and _mcp_log.isEnabledFor(logging.DEBUG):
+            session_id = request.headers.get("mcp-session-id", "-")
+            acp_token_hdr = request.headers.get(_ACP_TOKEN_HEADER, "-")
+            user_agent = request.headers.get("user-agent", "-")
+            accept = request.headers.get("accept", "-")
+            _mcp_log.debug(
+                "%s %s  session=%s  acp-token-hdr=%s  ua=%s  accept=%s  all_headers=%s",
+                request.method,
+                path,
+                session_id,
+                acp_token_hdr,
+                user_agent,
+                accept,
+                dict(request.headers),
+            )
+        response = await call_next(request)
+        if is_mcp and response.status_code >= 400:
+            session_id = request.headers.get("mcp-session-id", "-")
+            user_agent = request.headers.get("user-agent", "-")
+            _mcp_log.warning(
+                "%s %s  => %d  session=%s  ua=%s",
+                request.method,
+                path,
+                response.status_code,
+                session_id,
+                user_agent,
+            )
+        return response
+
+
+def _signal_handler(signum: int, frame: types.FrameType | None) -> None:
+    """Handle termination signals."""
+    logger.info("Received signal %d, cleaning up...", signum)
+    cleanup_sharedservers()
+    sys.exit(0)
+
+
+def create_app() -> Starlette:
+    """Factory function for creating the combiner ASGI app.
+
+    Reads config from environment variables set by main().
+    """
+    config_path = os.environ["MCP_COMBINER_CONFIG"]
+    oauth_cache_str = os.environ.get("MCP_COMBINER_OAUTH_CACHE")
+    oauth_cache_tokens: bool | None = None
+    if oauth_cache_str == "True":
+        oauth_cache_tokens = True
+    elif oauth_cache_str == "False":
+        oauth_cache_tokens = False
+    oauth_token_dir = os.environ.get("MCP_COMBINER_OAUTH_TOKEN_DIR")
+    normalize_schemas = os.environ.get("MCP_COMBINER_NORMALIZE_SCHEMA") == "1"
+
+    def _tristate(name: str) -> bool | None:
+        """Read a tri-state flag from env: '1' → True, '0' → False, unset → None."""
+        v = os.environ.get(name)
+        return None if v is None else v == "1"
+
+    input_validation = _tristate("MCP_COMBINER_INPUT_VALIDATION")
+    output_validation = _tristate("MCP_COMBINER_OUTPUT_VALIDATION")
+
+    combiner, ss_manager = create_combiner(
+        config_path,
+        oauth_cache_tokens=oauth_cache_tokens,
+        oauth_token_dir=oauth_token_dir,
+        normalize_schemas=normalize_schemas,
+        input_validation=input_validation,
+        output_validation=output_validation,
+        return_ss_manager=True,
+    )
+
+    # Register manager for cleanup on exit
+    register_for_cleanup(ss_manager)
+
+    # Use streamable HTTP with stateful mode.
+    # Stateless mode doesn't support GET for SSE streams, which OpenCode needs.
+    app = combiner.http_app(
+        path="/mcp",
+        stateless_http=False,
+    )
+    app.add_middleware(MCPRequestLogMiddleware)
+    # TokenRewriteMiddleware is outermost (last-added in Starlette = outermost).
+    # It extracts the ACP token from /mcp/<token> URL paths and rewrites to /mcp
+    # before the log middleware and FastMCP see the request.
+    app.add_middleware(TokenRewriteMiddleware)
+    return app
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="mcp-combiner",
+        description="MCP combiner — aggregates multiple MCP servers behind one endpoint",
+    )
+    parser.add_argument(
+        "--config",
+        required=True,
+        help="Path to servers.json config file",
+    )
+    parser.add_argument(
+        "--port",
+        type=int,
+        default=9741,
+        help="Port to listen on (default: 9741)",
+    )
+    parser.add_argument(
+        "--host",
+        default="127.0.0.1",
+        help="Host to bind to (default: 127.0.0.1)",
+    )
+
+    # OAuth token-caching overrides (both override the config-file 'oauth' section)
+    oauth_group = parser.add_mutually_exclusive_group()
+    oauth_group.add_argument(
+        "--oauth-cache",
+        dest="oauth_cache",
+        action="store_true",
+        default=None,
+        help="Enable OAuth disk token caching (overrides config; this is the default)",
+    )
+    oauth_group.add_argument(
+        "--no-oauth-cache",
+        dest="oauth_cache",
+        action="store_false",
+        help=(
+            "Disable OAuth disk token caching — tokens kept in memory only "
+            "and lost on restart (overrides config)"
+        ),
+    )
+    parser.add_argument(
+        "--oauth-token-dir",
+        metavar="PATH",
+        default=None,
+        help=(
+            "Directory for OAuth token files "
+            "(default: ~/.cache/mcp-combiner/oauth-tokens; overrides config)"
+        ),
+    )
+    parser.add_argument(
+        "--normalize-schema",
+        dest="normalize_schema",
+        action="store_true",
+        default=False,
+        help=(
+            "Normalize tool JSON schemas to fix providers (e.g. moonshot-ai/kimi) "
+            "that reject schemas where 'type' and 'anyOf' coexist at the same level. "
+            "Applied to every tools/list response at cache-fill time."
+        ),
+    )
+    parser.add_argument(
+        "--input-validation",
+        dest="input_validation",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help=(
+            "Tri-state JSON-schema validation of tool *input* arguments. "
+            "--input-validation forces it on; --no-input-validation forces it "
+            "off; omit to leave the combiner default (off — inputs are coerced, "
+            "not strictly validated)."
+        ),
+    )
+    parser.add_argument(
+        "--output-validation",
+        dest="output_validation",
+        action=argparse.BooleanOptionalAction,
+        default=None,
+        help=(
+            "Tri-state JSON-schema validation of tool *output*. "
+            "--no-output-validation forces it off (the upstream server already "
+            "validated its structured output, so re-validating here is redundant "
+            "per-call work — measurably slow for large responses); "
+            "--output-validation forces it on; omit to leave the default (on for "
+            "tools that declare an outputSchema)."
+        ),
+    )
+    parser.add_argument(
+        "--log-file",
+        metavar="PATH",
+        default=None,
+        help="Write logs to this file in addition to stderr (default: none)",
+    )
+    parser.add_argument(
+        "--log-level",
+        choices=["trace", "debug", "info", "warn", "error"],
+        default="info",
+        help=(
+            "Verbosity for the combiner logger and httpx/mcp-client loggers "
+            "(default: info).  Use 'debug' to capture OAuth metadata-discovery, "
+            "token refresh, and httpx request/response detail."
+        ),
+    )
+
+    args = parser.parse_args()
+
+    # Set env vars for app factory
+    os.environ["MCP_COMBINER_CONFIG"] = args.config
+    if args.oauth_cache is not None:
+        os.environ["MCP_COMBINER_OAUTH_CACHE"] = str(args.oauth_cache)
+    if args.oauth_token_dir:
+        os.environ["MCP_COMBINER_OAUTH_TOKEN_DIR"] = args.oauth_token_dir
+    if args.normalize_schema:
+        os.environ["MCP_COMBINER_NORMALIZE_SCHEMA"] = "1"
+    if args.input_validation is not None:
+        os.environ["MCP_COMBINER_INPUT_VALIDATION"] = "1" if args.input_validation else "0"
+    if args.output_validation is not None:
+        os.environ["MCP_COMBINER_OUTPUT_VALIDATION"] = "1" if args.output_validation else "0"
+
+    # Resolve --log-level to a stdlib logging numeric level.
+    # "trace" is treated as DEBUG since stdlib has no TRACE.
+    _level_map = {
+        "trace": logging.DEBUG,
+        "debug": logging.DEBUG,
+        "info": logging.INFO,
+        "warn": logging.WARNING,
+        "error": logging.ERROR,
+    }
+    level = _level_map[args.log_level]
+
+    # Stderr handler on the combiner logger.  Without this only WARNING+ would
+    # appear because Python's root logger defaults to WARNING.
+    combiner_logger = logging.getLogger("mcp-combiner")
+    combiner_logger.setLevel(level)
+    if not combiner_logger.handlers:
+        stderr_handler = logging.StreamHandler()
+        stderr_handler.setLevel(level)
+        stderr_handler.setFormatter(logging.Formatter("%(levelname)s:%(name)s:%(message)s"))
+        combiner_logger.addHandler(stderr_handler)
+        combiner_logger.propagate = False  # avoid duplicate messages via root
+
+    # Configure file logging if requested.  File handler always runs at the
+    # requested level (decoupled from the file's presence so you can pick
+    # INFO+file or DEBUG+stderr-only independently).
+    if args.log_file:
+        import pathlib
+
+        log_path = pathlib.Path(args.log_file)
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+        file_handler = logging.FileHandler(log_path)
+        file_handler.setLevel(level)
+        file_handler.setFormatter(
+            logging.Formatter("%(asctime)s %(levelname)s %(name)s: %(message)s")
+        )
+        # Root catches non-combiner loggers (fastmcp, mcp.client.auth, httpx, …)
+        logging.getLogger().addHandler(file_handler)
+        logging.getLogger().setLevel(level)
+        # propagate=False on combiner_logger means the root handler won't see
+        # its messages — attach explicitly.
+        combiner_logger.addHandler(file_handler)
+        logger.info("Logging to %s at level %s", log_path, args.log_level)
+    else:
+        # No file — still apply level globally so DEBUG-on-stderr works.
+        logging.getLogger().setLevel(level)
+
+    # At DEBUG, also turn on the SDK loggers that carry the OAuth flow detail.
+    if level <= logging.DEBUG:
+        for name in ("httpx", "httpcore", "mcp.client.auth", "fastmcp.client.auth"):
+            logging.getLogger(name).setLevel(logging.DEBUG)
+
+    # Register cleanup handlers
+    atexit.register(cleanup_sharedservers)
+    signal.signal(signal.SIGTERM, _signal_handler)
+    signal.signal(signal.SIGINT, _signal_handler)
+
+    # Single worker - async handles concurrency
+    app = create_app()
+    uvicorn.run(
+        app,
+        host=args.host,
+        port=args.port,
+        log_level="info",
+    )
+
+
+if __name__ == "__main__":
+    main()