mcp-combiner 0.20.0.dev1__tar.gz → 0.20.0.dev2__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (97) hide show
  1. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/CHANGELOG.md +8 -0
  2. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/PKG-INFO +1 -1
  3. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/__main__.py +41 -17
  4. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/asgi.py +25 -17
  5. mcp_combiner-0.20.0.dev2/mcp_combiner/binding.py +119 -0
  6. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/config.py +5 -1
  7. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/pyproject.toml +1 -1
  8. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/conftest.py +3 -0
  9. mcp_combiner-0.20.0.dev2/tests/test_binding.py +142 -0
  10. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/uv.lock +1 -1
  11. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/.gitignore +0 -0
  12. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/.python-version +0 -0
  13. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/LICENSE +0 -0
  14. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/README.md +0 -0
  15. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/__init__.py +0 -0
  16. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/auth.py +0 -0
  17. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/authprompt.py +0 -0
  18. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/backing.py +0 -0
  19. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/connections.py +0 -0
  20. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/ctl.py +0 -0
  21. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/era.py +0 -0
  22. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/externalservers.py +0 -0
  23. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/fastvalidate.py +0 -0
  24. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/handover.py +0 -0
  25. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/heldcalls.py +0 -0
  26. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/inbound_auth.py +0 -0
  27. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/isolated.py +0 -0
  28. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/listen.py +0 -0
  29. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/meta_tools.py +0 -0
  30. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/middleware.py +0 -0
  31. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/mockserver.py +0 -0
  32. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/mounts.py +0 -0
  33. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/notifications.py +0 -0
  34. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/nvim_channel.py +0 -0
  35. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/nvim_proxy.py +0 -0
  36. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/permissions.py +0 -0
  37. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/proxyfactory.py +0 -0
  38. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/py.typed +0 -0
  39. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/resume_transport.py +0 -0
  40. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/routes.py +0 -0
  41. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/runtime.py +0 -0
  42. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/schema.py +0 -0
  43. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/schemafix.py +0 -0
  44. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/server.py +0 -0
  45. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/sharedserver.py +0 -0
  46. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/status.py +0 -0
  47. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/toolcache.py +0 -0
  48. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/ui_host/__init__.py +0 -0
  49. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/ui_host/advertise.py +0 -0
  50. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/ui_host/holder.py +0 -0
  51. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/ui_host/routes.py +0 -0
  52. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/ui_host/sessions.py +0 -0
  53. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/ui_host/static/app-bridge.bundle.js +0 -0
  54. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/ui_host/templates.py +0 -0
  55. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/upstream_era.py +0 -0
  56. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/upstream_listen.py +0 -0
  57. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/mcp_combiner/upstream_session.py +0 -0
  58. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/pyrightconfig.json +0 -0
  59. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/fakes.py +0 -0
  60. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/fixtures/servers.json +0 -0
  61. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_advertised_origin.py +0 -0
  62. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_app_meta.py +0 -0
  63. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_auth.py +0 -0
  64. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_authprompt.py +0 -0
  65. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_combiner_reconnect.py +0 -0
  66. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_config.py +0 -0
  67. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_connections.py +0 -0
  68. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_ctl_lifecycle.py +0 -0
  69. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_elicit_e2e.py +0 -0
  70. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_era.py +0 -0
  71. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_externalservers.py +0 -0
  72. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_handover.py +0 -0
  73. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_inbound_auth.py +0 -0
  74. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_isolated.py +0 -0
  75. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_isolated_lifecycle_e2e.py +0 -0
  76. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_isolated_stdio.py +0 -0
  77. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_live_claude.py +0 -0
  78. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_mockserver.py +0 -0
  79. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_mounts.py +0 -0
  80. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_notifications.py +0 -0
  81. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_notifications_e2e.py +0 -0
  82. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_nvim_channel.py +0 -0
  83. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_nvim_e2e.py +0 -0
  84. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_oauth_mock.py +0 -0
  85. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_permissions.py +0 -0
  86. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_reload_config.py +0 -0
  87. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_resume_transport.py +0 -0
  88. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_route_matrix.py +0 -0
  89. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_schema_fixes.py +0 -0
  90. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_session_filter.py +0 -0
  91. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_session_independence.py +0 -0
  92. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_sharedserver.py +0 -0
  93. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_tool_fetch_wedge.py +0 -0
  94. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_ui_host.py +0 -0
  95. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_upstream_restart.py +0 -0
  96. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_upstream_session.py +0 -0
  97. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev2}/tests/test_visibility_and_reset_e2e.py +0 -0
@@ -15,6 +15,14 @@ tagged `vX.Y.Z`.
15
15
  answer. The upstream is not called until consent is given; "Allow for
16
16
  session" is remembered per chat token as before. (Before, a 2026 client
17
17
  silently got the `elicitUnavailable` fallback.)
18
+ - **Bind to several addresses.** `bind.host` (servers.json) takes a list, and
19
+ `--host` / `MCP_COMBINER_HOST` a comma-separated one: e.g.
20
+ `["127.0.0.1", "tailscale"]` serves loopback and the tailnet but not the
21
+ LAN. `tailscale` resolves to this machine's tailnet address at startup; an
22
+ address that isn't up is skipped with a warning (startup fails only if none
23
+ bind); a wildcard covers the rest. The UI relay (port + 1) follows the same
24
+ bind. Any non-loopback bind without an inbound bearer token warns. The pi
25
+ plugin connects to the first entry (loopback for a wildcard or `tailscale`).
18
26
  - **Per-server `protocol` setting** — `auto` (default), `legacy` or `2026`:
19
27
  which MCP revision the combiner speaks to an upstream. `auto` asks the server
20
28
  (`server/discover`) before mounting it; a server listing 2026-07-28 is
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: mcp-combiner
3
- Version: 0.20.0-dev.1
3
+ Version: 0.20.0-dev.2
4
4
  Summary: An MCP aggregator — fronts multiple MCP servers behind a single Streamable HTTP endpoint, shareable across clients.
5
5
  Project-URL: Homepage, https://github.com/georgeharker/mcp-companion
6
6
  Project-URL: Repository, https://github.com/georgeharker/mcp-companion
@@ -22,7 +22,7 @@ import types
22
22
  import uvicorn
23
23
 
24
24
  from mcp_combiner import ctl
25
- from mcp_combiner.asgi import ServeOptions, create_app, resolve_bind_host
25
+ from mcp_combiner.asgi import ServeOptions, create_app, resolve_bind_hosts
26
26
  from mcp_combiner.inbound_auth import resolve_auth_token
27
27
  from mcp_combiner.schemafix import SCHEMA_FIXES
28
28
  from mcp_combiner.sharedserver import cleanup as cleanup_sharedservers
@@ -74,7 +74,10 @@ def _add_serve_args(parser: argparse.ArgumentParser) -> None:
74
74
  parser.add_argument(
75
75
  "--host",
76
76
  default=None,
77
- help="Bind host (default: $MCP_COMBINER_HOST, then the config's bind.host, then loopback)",
77
+ help=(
78
+ "Bind address(es), comma-separated; 'tailscale' = this machine's tailnet "
79
+ "address (default: $MCP_COMBINER_HOST, then the config's bind.host, then loopback)"
80
+ ),
78
81
  )
79
82
 
80
83
  # OAuth token-caching overrides (both override the config-file 'oauth' section)
@@ -257,7 +260,7 @@ def _setup_logging(log_level: str, log_file: str | None) -> None:
257
260
  def _serve(args: argparse.Namespace) -> None:
258
261
  options = ServeOptions(
259
262
  config=args.config,
260
- host=resolve_bind_host(args.host, args.config),
263
+ hosts=resolve_bind_hosts(args.host, args.config),
261
264
  port=args.port,
262
265
  oauth_cache=args.oauth_cache,
263
266
  oauth_token_dir=args.oauth_token_dir,
@@ -282,6 +285,31 @@ def _serve(args: argparse.Namespace) -> None:
282
285
  signal.signal(signal.SIGTERM, _signal_handler)
283
286
  signal.signal(signal.SIGINT, _signal_handler)
284
287
 
288
+ # Bind first: a port in use fails here, before any upstream is touched.
289
+ # Addresses that aren't up are skipped (mcp_combiner.binding).
290
+ from mcp_combiner.binding import bind_sockets, is_loopback
291
+
292
+ main_sockets = bind_sockets(options.hosts, options.port)
293
+ try:
294
+ relay_sockets = bind_sockets(options.hosts, options.port + 1)
295
+ except OSError as exc:
296
+ # The relay only serves interactive widgets; a busy port+1 must not
297
+ # keep the combiner itself from serving (it never did).
298
+ relay_sockets = []
299
+ logging.getLogger("mcp-combiner").warning(
300
+ "UI relay: can't listen on port %d (%s) — interactive widgets won't load",
301
+ options.port + 1,
302
+ exc,
303
+ )
304
+ exposed = [h for h in options.hosts if not is_loopback(h)]
305
+ if exposed and options.auth_token is None:
306
+ logging.getLogger("mcp-combiner").warning(
307
+ "bind: serving on %s with NO inbound bearer token — anyone who can reach "
308
+ "these addresses can use every upstream. Set MCP_COMBINER_AUTH_TOKEN or "
309
+ "--auth-token-file.",
310
+ ", ".join(exposed),
311
+ )
312
+
285
313
  # Single worker - async handles concurrency
286
314
  app = create_app(options)
287
315
 
@@ -296,22 +324,17 @@ def _serve(args: argparse.Namespace) -> None:
296
324
 
297
325
  from mcp_combiner.ui_host import get_relay_app
298
326
 
299
- relay_thread = threading.Thread(
300
- target=lambda: uvicorn.run(
301
- get_relay_app(options),
302
- host=options.host,
303
- port=options.port + 1,
304
- log_level="warning",
305
- ),
306
- daemon=True,
307
- name="mcp-combiner-ui-relay",
308
- )
309
- relay_thread.start()
327
+ if relay_sockets:
328
+ relay = uvicorn.Server(uvicorn.Config(get_relay_app(options), log_level="warning"))
329
+ relay_thread = threading.Thread(
330
+ target=lambda: relay.run(sockets=relay_sockets),
331
+ daemon=True,
332
+ name="mcp-combiner-ui-relay",
333
+ )
334
+ relay_thread.start()
310
335
 
311
- uvicorn.run(
336
+ config = uvicorn.Config(
312
337
  app,
313
- host=options.host,
314
- port=options.port,
315
338
  log_level="info",
316
339
  # Bound the graceful-shutdown drain. The combiner holds long-lived MCP
317
340
  # streamable-http / SSE connections that never close on their own, so the
@@ -325,6 +348,7 @@ def _serve(args: argparse.Namespace) -> None:
325
348
  # uvicorn ourselves via http_app(), so we must set it ourselves.)
326
349
  timeout_graceful_shutdown=2,
327
350
  )
351
+ uvicorn.Server(config).run(sockets=main_sockets)
328
352
 
329
353
 
330
354
  def main() -> None:
@@ -19,6 +19,7 @@ from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoin
19
19
  from starlette.requests import Request as StarletteRequest
20
20
  from starlette.responses import Response
21
21
 
22
+ from mcp_combiner.binding import DEFAULT_HOST, parse_hosts, resolve_hosts
22
23
  from mcp_combiner.inbound_auth import BearerAuthMiddleware, resolve_auth_token
23
24
  from mcp_combiner.runtime import RUNTIME
24
25
  from mcp_combiner.server import create_combiner
@@ -75,7 +76,9 @@ class ServeOptions:
75
76
  """Everything serve mode needs, resolved from CLI args (or env fallback)."""
76
77
 
77
78
  config: str
78
- host: str = "127.0.0.1"
79
+ #: The addresses to listen on, already resolved (``binding.resolve_hosts``);
80
+ #: the first is the primary, used where one address must be named.
81
+ hosts: list[str] = field(default_factory=lambda: [DEFAULT_HOST])
79
82
  port: int = 9741
80
83
  oauth_cache: bool | None = None
81
84
  oauth_token_dir: str | None = None
@@ -93,11 +96,16 @@ class ServeOptions:
93
96
  #: :func:`resolve_auth_token`.
94
97
  auth_token: str | None = None
95
98
 
99
+ @property
100
+ def host(self) -> str:
101
+ """The primary bind address."""
102
+ return self.hosts[0] if self.hosts else DEFAULT_HOST
103
+
96
104
  @classmethod
97
105
  def from_env(cls) -> ServeOptions:
98
106
  """Fallback construction from MCP_COMBINER_* env vars (factory launches).
99
107
  The bind host resolves CLI > env > config bind.host > loopback via
100
- :func:`resolve_bind_host` (the config path comes from
108
+ :func:`resolve_bind_hosts` (the config path comes from
101
109
  ``$MCP_COMBINER_CONFIG``)."""
102
110
 
103
111
  def _tristate(name: str) -> bool | None:
@@ -111,7 +119,7 @@ class ServeOptions:
111
119
  cfg_path = os.environ["MCP_COMBINER_CONFIG"]
112
120
  return cls(
113
121
  config=cfg_path,
114
- host=resolve_bind_host(None, cfg_path),
122
+ hosts=resolve_bind_hosts(None, cfg_path),
115
123
  oauth_cache=_tristate("MCP_COMBINER_OAUTH_CACHE"),
116
124
  oauth_token_dir=os.environ.get("MCP_COMBINER_OAUTH_TOKEN_DIR"),
117
125
  normalize_schema=os.environ.get("MCP_COMBINER_NORMALIZE_SCHEMA") == "1",
@@ -331,25 +339,25 @@ class MCPRequestLogMiddleware(BaseHTTPMiddleware):
331
339
  return response
332
340
 
333
341
 
334
- def resolve_bind_host(cli_host: str | None, config_path: str) -> str:
335
- """The serve bind host: CLI ``--host`` > env ``MCP_COMBINER_HOST`` > the
336
- config's ``bind.host`` (servers.json) > ``127.0.0.1``.
342
+ def resolve_bind_hosts(cli_host: str | None, config_path: str) -> list[str]:
343
+ """The addresses to serve on: CLI ``--host`` > env ``MCP_COMBINER_HOST`` >
344
+ the config's ``bind.host`` (servers.json) > ``127.0.0.1`` — the first one
345
+ set wins whole (CLI / env take comma-separated lists). Resolved: see
346
+ ``mcp_combiner.binding.resolve_hosts``.
337
347
 
338
348
  The config setting is the durable home — the sharedserver registration is
339
349
  per-running-instance and dies with every grace-stop, and env vars depend
340
350
  on the launching shell; the config file is read fresh on every start.
341
351
  """
342
- if cli_host:
343
- return cli_host
344
- env_host = os.environ.get("MCP_COMBINER_HOST", "").strip()
345
- if env_host:
346
- return env_host
347
- try:
348
- from mcp_combiner.config import CombinerConfig
349
-
350
- return CombinerConfig.load(config_path).bind.host
351
- except Exception:
352
- return "127.0.0.1"
352
+ entries = parse_hosts(cli_host) or parse_hosts(os.environ.get("MCP_COMBINER_HOST"))
353
+ if not entries:
354
+ try:
355
+ from mcp_combiner.config import CombinerConfig
356
+
357
+ entries = parse_hosts(CombinerConfig.load(config_path).bind.host)
358
+ except Exception:
359
+ entries = []
360
+ return resolve_hosts(entries) or [DEFAULT_HOST]
353
361
 
354
362
 
355
363
  def create_app(options: ServeOptions | None = None) -> Starlette:
@@ -0,0 +1,119 @@
1
+ """Which addresses the combiner listens on, and the sockets for them.
2
+
3
+ The bind setting (CLI ``--host`` > ``MCP_COMBINER_HOST`` > servers.json
4
+ ``bind.host`` > ``127.0.0.1``) is a list: ``"bind": {"host": ["127.0.0.1",
5
+ "tailscale"]}``, or comma-separated on the CLI / in the env var. Entries:
6
+
7
+ - an address (``127.0.0.1``, ``::1``, ``100.101.102.103``);
8
+ - ``tailscale`` — this machine's tailnet IPv4, looked up at startup (the same
9
+ detection the widget URLs use, ``ui_host.advertise``);
10
+ - a wildcard (``0.0.0.0`` / ``::``) — every interface; it already covers the
11
+ specific addresses, so a list containing one keeps only the wildcards.
12
+
13
+ An address that isn't up when the combiner starts (Tailscale down, an
14
+ interface gone) is skipped with a warning rather than failing startup; a
15
+ restart binds it once it's back. Startup fails only when none bind. A port in
16
+ use is still fatal.
17
+ """
18
+
19
+ from __future__ import annotations
20
+
21
+ import errno
22
+ import ipaddress
23
+ import logging
24
+ import socket
25
+ from collections.abc import Sequence
26
+
27
+ logger = logging.getLogger("mcp-combiner")
28
+
29
+ DEFAULT_HOST = "127.0.0.1"
30
+ TAILSCALE = "tailscale"
31
+ WILDCARDS = frozenset({"0.0.0.0", "::"})
32
+
33
+
34
+ def parse_hosts(value: str | Sequence[str] | None) -> list[str]:
35
+ """Bind entries from a comma-separated string or a list, in order, deduplicated."""
36
+ if value is None:
37
+ return []
38
+ items = value.split(",") if isinstance(value, str) else [str(v) for v in value]
39
+ hosts: list[str] = []
40
+ for item in items:
41
+ host = item.strip()
42
+ if host and host not in hosts:
43
+ hosts.append(host)
44
+ return hosts
45
+
46
+
47
+ def resolve_hosts(entries: Sequence[str]) -> list[str]:
48
+ """Concrete addresses for *entries*: ``tailscale`` looked up, wildcards
49
+ collapsed, unavailable aliases dropped (warned). ``[]`` → the default."""
50
+ hosts: list[str] = []
51
+ for entry in entries or [DEFAULT_HOST]:
52
+ if entry.lower() == TAILSCALE:
53
+ address = tailnet_address()
54
+ if address is None:
55
+ logger.warning(
56
+ "bind: no Tailscale address on this machine (tailscaled down?) — "
57
+ "not listening on the tailnet; restart once it's up"
58
+ )
59
+ continue
60
+ entry = address
61
+ if entry not in hosts:
62
+ hosts.append(entry)
63
+ wildcards = [h for h in hosts if h in WILDCARDS]
64
+ if wildcards and len(wildcards) < len(hosts):
65
+ logger.info("bind: %s covers every interface; ignoring the other addresses", wildcards)
66
+ return wildcards
67
+ return hosts
68
+
69
+
70
+ def tailnet_address() -> str | None:
71
+ """This machine's Tailscale IPv4, or ``None``."""
72
+ from mcp_combiner.ui_host.advertise import _interface_scan_ip, _tailscale_ip
73
+
74
+ return _tailscale_ip() or _interface_scan_ip()
75
+
76
+
77
+ def is_loopback(host: str) -> bool:
78
+ try:
79
+ return ipaddress.ip_address(host).is_loopback
80
+ except ValueError:
81
+ return host == "localhost"
82
+
83
+
84
+ def bind_sockets(hosts: Sequence[str], port: int) -> list[socket.socket]:
85
+ """Listening sockets on *port* for each of *hosts*. An address that isn't
86
+ available here is skipped (warned); any other failure — a port in use —
87
+ raises. Raises ``OSError`` when nothing bound."""
88
+ sockets: list[socket.socket] = []
89
+ try:
90
+ for host in hosts:
91
+ sock = _bind_one(host, port)
92
+ if sock is not None:
93
+ sockets.append(sock)
94
+ except BaseException:
95
+ for sock in sockets:
96
+ sock.close()
97
+ raise
98
+ if not sockets:
99
+ raise OSError(errno.EADDRNOTAVAIL, f"none of the bind addresses {list(hosts)} is available")
100
+ return sockets
101
+
102
+
103
+ def _bind_one(host: str, port: int) -> socket.socket | None:
104
+ family = socket.AF_INET6 if ":" in host else socket.AF_INET
105
+ sock = socket.socket(family, socket.SOCK_STREAM)
106
+ try:
107
+ sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
108
+ if family == socket.AF_INET6:
109
+ # Keep "::" from also claiming IPv4, so it can sit beside 0.0.0.0.
110
+ sock.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1)
111
+ sock.bind((host, port))
112
+ sock.listen(2048)
113
+ except OSError as exc:
114
+ sock.close()
115
+ if exc.errno in (errno.EADDRNOTAVAIL, errno.EAFNOSUPPORT):
116
+ logger.warning("bind: %s:%d isn't available here (%s) — skipped", host, port, exc)
117
+ return None
118
+ raise
119
+ return sock
@@ -763,9 +763,13 @@ class BindConfig(BaseModel):
763
763
  ``MCP_COMBINER_HOST`` > this setting > the ``127.0.0.1`` default. Binding
764
764
  ``0.0.0.0`` serves loopback + every interface (LAN + tailnet) — required
765
765
  for the remote widget leg (docs/designs/advertised-ui-origin.md).
766
+
767
+ ``host`` may be a list — ``["127.0.0.1", "tailscale"]`` listens on loopback
768
+ and the tailnet only (``tailscale`` resolves to this machine's tailnet
769
+ address at startup); see ``mcp_combiner.binding``.
766
770
  """
767
771
 
768
- host: str = "127.0.0.1"
772
+ host: str | list[str] = "127.0.0.1"
769
773
 
770
774
 
771
775
  class ValidationConfig(BaseModel):
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "mcp-combiner"
3
- version = "0.20.0-dev.1"
3
+ version = "0.20.0-dev.2"
4
4
  description = "An MCP aggregator — fronts multiple MCP servers behind a single Streamable HTTP endpoint, shareable across clients."
5
5
  requires-python = ">=3.12"
6
6
  license = "MIT"
@@ -150,6 +150,7 @@ def write_servers_config(
150
150
  shared_servers: dict[str, Any] | None = None,
151
151
  isolation: dict[str, Any] | None = None,
152
152
  oauth: dict[str, Any] | None = None,
153
+ bind: dict[str, Any] | None = None,
153
154
  ) -> Path:
154
155
  doc: dict[str, Any] = {"servers": servers}
155
156
  if shared_servers:
@@ -158,6 +159,8 @@ def write_servers_config(
158
159
  doc["isolation"] = isolation
159
160
  if oauth:
160
161
  doc["oauth"] = oauth
162
+ if bind:
163
+ doc["bind"] = bind
161
164
  path.write_text(json.dumps(doc, indent=2))
162
165
  return path
163
166
 
@@ -0,0 +1,142 @@
1
+ """Binding to a list of addresses (``bind.host`` / ``--host`` / ``MCP_COMBINER_HOST``)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import errno
6
+ import logging
7
+ import socket
8
+ from pathlib import Path
9
+
10
+ import httpx2
11
+ import pytest
12
+ from conftest import ProcFactory, free_port, write_servers_config
13
+
14
+ from mcp_combiner import binding
15
+ from mcp_combiner.asgi import resolve_bind_hosts
16
+
17
+ TEST_NET = "192.0.2.1" # RFC 5737: never configured on a real interface
18
+
19
+
20
+ def _has_ipv6_loopback() -> bool:
21
+ try:
22
+ with socket.socket(socket.AF_INET6, socket.SOCK_STREAM) as s:
23
+ s.bind(("::1", 0))
24
+ return True
25
+ except OSError:
26
+ return False
27
+
28
+
29
+ class TestParseAndResolve:
30
+ def test_parse_accepts_strings_lists_and_dedupes(self) -> None:
31
+ assert binding.parse_hosts("127.0.0.1, ::1,127.0.0.1") == ["127.0.0.1", "::1"]
32
+ assert binding.parse_hosts(["127.0.0.1", " tailscale "]) == ["127.0.0.1", "tailscale"]
33
+ assert binding.parse_hosts("") == []
34
+ assert binding.parse_hosts(None) == []
35
+
36
+ def test_tailscale_resolves_to_the_tailnet_address(
37
+ self, monkeypatch: pytest.MonkeyPatch
38
+ ) -> None:
39
+ monkeypatch.setattr(binding, "tailnet_address", lambda: "100.101.102.103")
40
+ assert binding.resolve_hosts(["127.0.0.1", "tailscale"]) == [
41
+ "127.0.0.1",
42
+ "100.101.102.103",
43
+ ]
44
+
45
+ def test_missing_tailscale_is_skipped_with_a_warning(
46
+ self, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
47
+ ) -> None:
48
+ monkeypatch.setattr(binding, "tailnet_address", lambda: None)
49
+ with caplog.at_level(logging.WARNING, logger="mcp-combiner"):
50
+ assert binding.resolve_hosts(["127.0.0.1", "Tailscale"]) == ["127.0.0.1"]
51
+ assert "no Tailscale address" in caplog.text
52
+
53
+ def test_a_wildcard_covers_the_rest(self) -> None:
54
+ assert binding.resolve_hosts(["127.0.0.1", "0.0.0.0", "::1"]) == ["0.0.0.0"]
55
+ assert binding.resolve_hosts(["0.0.0.0", "::"]) == ["0.0.0.0", "::"]
56
+
57
+ def test_empty_means_loopback(self) -> None:
58
+ assert binding.resolve_hosts([]) == ["127.0.0.1"]
59
+
60
+ def test_precedence_cli_env_config(
61
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
62
+ ) -> None:
63
+ config = write_servers_config(
64
+ tmp_path / "servers.json", {}, bind={"host": ["::1", "127.0.0.1"]}
65
+ )
66
+ monkeypatch.delenv("MCP_COMBINER_HOST", raising=False)
67
+ assert resolve_bind_hosts(None, str(config)) == ["::1", "127.0.0.1"]
68
+ monkeypatch.setenv("MCP_COMBINER_HOST", "127.0.0.1,::1")
69
+ assert resolve_bind_hosts(None, str(config)) == ["127.0.0.1", "::1"]
70
+ assert resolve_bind_hosts("::1", str(config)) == ["::1"]
71
+
72
+ def test_loopback_detection(self) -> None:
73
+ assert binding.is_loopback("127.0.0.1") and binding.is_loopback("::1")
74
+ assert binding.is_loopback("localhost")
75
+ assert not binding.is_loopback("100.101.102.103") and not binding.is_loopback("0.0.0.0")
76
+
77
+
78
+ class TestBindSockets:
79
+ def test_unavailable_addresses_are_skipped(self, caplog: pytest.LogCaptureFixture) -> None:
80
+ port = free_port()
81
+ with caplog.at_level(logging.WARNING, logger="mcp-combiner"):
82
+ sockets = binding.bind_sockets(["127.0.0.1", TEST_NET], port)
83
+ try:
84
+ assert [s.getsockname()[:2] for s in sockets] == [("127.0.0.1", port)]
85
+ assert f"{TEST_NET}:{port} isn't available" in caplog.text
86
+ finally:
87
+ for s in sockets:
88
+ s.close()
89
+
90
+ def test_nothing_available_is_an_error(self) -> None:
91
+ with pytest.raises(OSError) as caught:
92
+ binding.bind_sockets([TEST_NET], free_port())
93
+ assert caught.value.errno == errno.EADDRNOTAVAIL
94
+
95
+ def test_a_port_in_use_is_fatal_and_releases_what_bound(self) -> None:
96
+ port = free_port()
97
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as squatter:
98
+ squatter.bind(("127.0.0.1", port))
99
+ squatter.listen(1)
100
+ with pytest.raises(OSError) as caught:
101
+ binding.bind_sockets(["127.0.0.1"], port)
102
+ assert caught.value.errno == errno.EADDRINUSE
103
+
104
+
105
+ @pytest.mark.e2e
106
+ @pytest.mark.skipif(not _has_ipv6_loopback(), reason="no IPv6 loopback here")
107
+ async def test_a_combiner_serves_on_every_listed_address(
108
+ procs: ProcFactory, tmp_path: Path
109
+ ) -> None:
110
+ config = write_servers_config(
111
+ tmp_path / "servers.json", {}, bind={"host": ["127.0.0.1", "::1", TEST_NET]}
112
+ )
113
+ combiner = await procs.start_combiner(
114
+ config, extra_args=["--log-file", str(tmp_path / "combiner.log")]
115
+ )
116
+ async with httpx2.AsyncClient(timeout=5.0) as http:
117
+ for base in (f"http://127.0.0.1:{combiner.port}", f"http://[::1]:{combiner.port}"):
118
+ response = await http.get(f"{base}/health")
119
+ assert response.status_code == 200, base
120
+ # The UI relay (port + 1) follows the same bind.
121
+ relay = await http.get(f"http://[::1]:{combiner.port + 1}/")
122
+ assert relay.status_code < 500
123
+ assert f"{TEST_NET}:{combiner.port} isn't available" in (tmp_path / "combiner.log").read_text()
124
+
125
+
126
+ @pytest.mark.e2e
127
+ async def test_a_busy_relay_port_does_not_stop_the_combiner(
128
+ procs: ProcFactory, tmp_path: Path
129
+ ) -> None:
130
+ """The UI relay (port + 1) only serves widgets: losing it must not keep the
131
+ combiner from serving — as before the relay was bound up front."""
132
+ port = free_port()
133
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as squatter:
134
+ squatter.bind(("127.0.0.1", port + 1))
135
+ squatter.listen(1)
136
+ config = write_servers_config(tmp_path / "servers.json", {})
137
+ combiner = await procs.start_combiner(
138
+ config, port=port, extra_args=["--log-file", str(tmp_path / "combiner.log")]
139
+ )
140
+ async with httpx2.AsyncClient(timeout=5.0) as http:
141
+ assert (await http.get(f"http://127.0.0.1:{combiner.port}/health")).status_code == 200
142
+ assert "UI relay: can't listen" in (tmp_path / "combiner.log").read_text()
@@ -712,7 +712,7 @@ wheels = [
712
712
 
713
713
  [[package]]
714
714
  name = "mcp-combiner"
715
- version = "0.20.0-dev.1"
715
+ version = "0.20.0-dev.2"
716
716
  source = { editable = "." }
717
717
  dependencies = [
718
718
  { name = "fastmcp" },