mcp-combiner 0.20.0.dev1__tar.gz → 0.20.0.dev3__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 (98) hide show
  1. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/CHANGELOG.md +20 -0
  2. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/PKG-INFO +1 -1
  3. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/__main__.py +41 -17
  4. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/asgi.py +25 -17
  5. mcp_combiner-0.20.0.dev3/mcp_combiner/binding.py +128 -0
  6. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/config.py +51 -2
  7. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/runtime.py +3 -0
  8. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/ui_host/advertise.py +73 -15
  9. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/pyproject.toml +1 -1
  10. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/conftest.py +3 -0
  11. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_advertised_origin.py +43 -0
  12. mcp_combiner-0.20.0.dev3/tests/test_binding.py +152 -0
  13. mcp_combiner-0.20.0.dev3/tests/test_public_url.py +59 -0
  14. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/uv.lock +1 -1
  15. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/.gitignore +0 -0
  16. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/.python-version +0 -0
  17. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/LICENSE +0 -0
  18. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/README.md +0 -0
  19. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/__init__.py +0 -0
  20. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/auth.py +0 -0
  21. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/authprompt.py +0 -0
  22. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/backing.py +0 -0
  23. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/connections.py +0 -0
  24. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/ctl.py +0 -0
  25. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/era.py +0 -0
  26. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/externalservers.py +0 -0
  27. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/fastvalidate.py +0 -0
  28. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/handover.py +0 -0
  29. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/heldcalls.py +0 -0
  30. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/inbound_auth.py +0 -0
  31. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/isolated.py +0 -0
  32. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/listen.py +0 -0
  33. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/meta_tools.py +0 -0
  34. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/middleware.py +0 -0
  35. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/mockserver.py +0 -0
  36. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/mounts.py +0 -0
  37. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/notifications.py +0 -0
  38. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/nvim_channel.py +0 -0
  39. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/nvim_proxy.py +0 -0
  40. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/permissions.py +0 -0
  41. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/proxyfactory.py +0 -0
  42. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/py.typed +0 -0
  43. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/resume_transport.py +0 -0
  44. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/routes.py +0 -0
  45. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/schema.py +0 -0
  46. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/schemafix.py +0 -0
  47. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/server.py +0 -0
  48. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/sharedserver.py +0 -0
  49. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/status.py +0 -0
  50. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/toolcache.py +0 -0
  51. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/ui_host/__init__.py +0 -0
  52. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/ui_host/holder.py +0 -0
  53. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/ui_host/routes.py +0 -0
  54. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/ui_host/sessions.py +0 -0
  55. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/ui_host/static/app-bridge.bundle.js +0 -0
  56. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/ui_host/templates.py +0 -0
  57. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/upstream_era.py +0 -0
  58. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/upstream_listen.py +0 -0
  59. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/mcp_combiner/upstream_session.py +0 -0
  60. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/pyrightconfig.json +0 -0
  61. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/fakes.py +0 -0
  62. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/fixtures/servers.json +0 -0
  63. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_app_meta.py +0 -0
  64. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_auth.py +0 -0
  65. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_authprompt.py +0 -0
  66. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_combiner_reconnect.py +0 -0
  67. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_config.py +0 -0
  68. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_connections.py +0 -0
  69. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_ctl_lifecycle.py +0 -0
  70. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_elicit_e2e.py +0 -0
  71. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_era.py +0 -0
  72. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_externalservers.py +0 -0
  73. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_handover.py +0 -0
  74. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_inbound_auth.py +0 -0
  75. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_isolated.py +0 -0
  76. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_isolated_lifecycle_e2e.py +0 -0
  77. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_isolated_stdio.py +0 -0
  78. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_live_claude.py +0 -0
  79. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_mockserver.py +0 -0
  80. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_mounts.py +0 -0
  81. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_notifications.py +0 -0
  82. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_notifications_e2e.py +0 -0
  83. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_nvim_channel.py +0 -0
  84. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_nvim_e2e.py +0 -0
  85. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_oauth_mock.py +0 -0
  86. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_permissions.py +0 -0
  87. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_reload_config.py +0 -0
  88. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_resume_transport.py +0 -0
  89. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_route_matrix.py +0 -0
  90. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_schema_fixes.py +0 -0
  91. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_session_filter.py +0 -0
  92. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_session_independence.py +0 -0
  93. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_sharedserver.py +0 -0
  94. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_tool_fetch_wedge.py +0 -0
  95. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_ui_host.py +0 -0
  96. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_upstream_restart.py +0 -0
  97. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_upstream_session.py +0 -0
  98. {mcp_combiner-0.20.0.dev1 → mcp_combiner-0.20.0.dev3}/tests/test_visibility_and_reset_e2e.py +0 -0
@@ -15,6 +15,26 @@ 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", "auto"]` serves loopback and the tailnet but not the
21
+ LAN. `auto` 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 `auto`).
26
+ A host name that doesn't resolve at startup is skipped like an address
27
+ that isn't up.
28
+ - **Portable tailnet settings.** `auto` as a whole value, or `{auto}` as the
29
+ host inside a URL, means this machine on its tailnet, in `bind.host`,
30
+ `MCP_COMBINER_UI_ADVERTISE` and `oauth.public_url`. Advertise `auto` (the
31
+ default) now names the MagicDNS name (`tailscale status`) rather than the
32
+ raw tailnet IP, falling back to the IP. `oauth.public_url: "auto"` is
33
+ `http://<magicdns name>:<port>`; `"https://{auto}"` suits `tailscale serve`.
34
+ New `MCP_COMBINER_OAUTH_PUBLIC_URL` (a literal URL) overrides the setting.
35
+ - An explicit advertised origin keeps its own port
36
+ (`MCP_COMBINER_UI_ADVERTISE=http://host:443` gave `http://host:443:9741`),
37
+ and a bare IPv6 host is bracketed.
18
38
  - **Per-server `protocol` setting** — `auto` (default), `legacy` or `2026`:
19
39
  which MCP revision the combiner speaks to an upstream. `auto` asks the server
20
40
  (`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.3
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
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
349
356
 
350
- return CombinerConfig.load(config_path).bind.host
351
- except Exception:
352
- return "127.0.0.1"
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:
@@ -360,6 +368,7 @@ def create_app(options: ServeOptions | None = None) -> Starlette:
360
368
  """
361
369
  if options is None:
362
370
  options = ServeOptions.from_env()
371
+ RUNTIME.serve_port = options.port
363
372
 
364
373
  combiner, proc_manager = create_combiner(
365
374
  options.config,
@@ -436,7 +445,6 @@ def create_app(options: ServeOptions | None = None) -> Starlette:
436
445
  logger.info("auth: inbound bearer required on /mcp, /sessions, /handover")
437
446
  # The UI host's loopback clients read this to present the same bearer on
438
447
  # their /mcp/<token> calls (the middleware does not exempt loopback).
439
- from mcp_combiner.runtime import RUNTIME
440
448
 
441
449
  RUNTIME.inbound_auth_token = options.auth_token
442
450
  RUNTIME.local_origin = f"http://127.0.0.1:{options.port}"
@@ -0,0 +1,128 @@
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
+ "auto"]}``, 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
+ - ``auto`` — this machine's tailnet IPv4, looked up at startup (the tailnet
9
+ detection the widget URLs use, ``ui_host.advertise``; an IP, so no DNS);
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
+ - a host name — resolved when binding; one that doesn't resolve is skipped
13
+ like an address that isn't up. (Prefer ``auto`` to a MagicDNS name: same
14
+ address, no DNS dependency.)
15
+
16
+ An address that isn't up when the combiner starts (Tailscale down, an
17
+ interface gone) is skipped with a warning rather than failing startup; a
18
+ restart binds it once it's back. Startup fails only when none bind. A port in
19
+ use is still fatal.
20
+ """
21
+
22
+ from __future__ import annotations
23
+
24
+ import errno
25
+ import ipaddress
26
+ import logging
27
+ import socket
28
+ from collections.abc import Sequence
29
+
30
+ from mcp_combiner.ui_host.advertise import AUTO
31
+
32
+ logger = logging.getLogger("mcp-combiner")
33
+
34
+ DEFAULT_HOST = "127.0.0.1"
35
+ WILDCARDS = frozenset({"0.0.0.0", "::"})
36
+
37
+
38
+ def parse_hosts(value: str | Sequence[str] | None) -> list[str]:
39
+ """Bind entries from a comma-separated string or a list, in order, deduplicated."""
40
+ if value is None:
41
+ return []
42
+ items = value.split(",") if isinstance(value, str) else [str(v) for v in value]
43
+ hosts: list[str] = []
44
+ for item in items:
45
+ host = item.strip()
46
+ if host and host not in hosts:
47
+ hosts.append(host)
48
+ return hosts
49
+
50
+
51
+ def resolve_hosts(entries: Sequence[str]) -> list[str]:
52
+ """Concrete addresses for *entries*: ``auto`` looked up, wildcards
53
+ collapsed, unavailable aliases dropped (warned). ``[]`` → the default."""
54
+ hosts: list[str] = []
55
+ for entry in entries or [DEFAULT_HOST]:
56
+ if entry.lower() == AUTO:
57
+ address = tailnet_address()
58
+ if address is None:
59
+ logger.warning(
60
+ "bind: no Tailscale address on this machine (tailscaled down?) — "
61
+ "not listening on the tailnet; restart once it's up"
62
+ )
63
+ continue
64
+ entry = address
65
+ if entry not in hosts:
66
+ hosts.append(entry)
67
+ wildcards = [h for h in hosts if h in WILDCARDS]
68
+ if wildcards and len(wildcards) < len(hosts):
69
+ logger.info("bind: %s covers every interface; ignoring the other addresses", wildcards)
70
+ return wildcards
71
+ return hosts
72
+
73
+
74
+ def tailnet_address() -> str | None:
75
+ """This machine's Tailscale IPv4, or ``None``."""
76
+ from mcp_combiner.ui_host.advertise import tailnet_ip
77
+
78
+ return tailnet_ip()
79
+
80
+
81
+ def is_loopback(host: str) -> bool:
82
+ try:
83
+ return ipaddress.ip_address(host).is_loopback
84
+ except ValueError:
85
+ return host == "localhost"
86
+
87
+
88
+ def bind_sockets(hosts: Sequence[str], port: int) -> list[socket.socket]:
89
+ """Listening sockets on *port* for each of *hosts*. An address that isn't
90
+ available here is skipped (warned); any other failure — a port in use —
91
+ raises. Raises ``OSError`` when nothing bound."""
92
+ sockets: list[socket.socket] = []
93
+ try:
94
+ for host in hosts:
95
+ sock = _bind_one(host, port)
96
+ if sock is not None:
97
+ sockets.append(sock)
98
+ except BaseException:
99
+ for sock in sockets:
100
+ sock.close()
101
+ raise
102
+ if not sockets:
103
+ raise OSError(errno.EADDRNOTAVAIL, f"none of the bind addresses {list(hosts)} is available")
104
+ return sockets
105
+
106
+
107
+ def _bind_one(host: str, port: int) -> socket.socket | None:
108
+ family = socket.AF_INET6 if ":" in host else socket.AF_INET
109
+ sock = socket.socket(family, socket.SOCK_STREAM)
110
+ try:
111
+ sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
112
+ if family == socket.AF_INET6:
113
+ # Keep "::" from also claiming IPv4, so it can sit beside 0.0.0.0.
114
+ sock.setsockopt(socket.IPPROTO_IPV6, socket.IPV6_V6ONLY, 1)
115
+ sock.bind((host, port))
116
+ sock.listen(2048)
117
+ except OSError as exc:
118
+ sock.close()
119
+ # gaierror: a name that doesn't resolve (yet) — e.g. a MagicDNS name
120
+ # while Tailscale is down.
121
+ if isinstance(exc, socket.gaierror) or exc.errno in (
122
+ errno.EADDRNOTAVAIL,
123
+ errno.EAFNOSUPPORT,
124
+ ):
125
+ logger.warning("bind: %s:%d isn't available here (%s) — skipped", host, port, exc)
126
+ return None
127
+ raise
128
+ return sock
@@ -692,6 +692,12 @@ class OAuthConfig(BaseModel):
692
692
  OAuth client (for Google: a Web-application client). When unset, the
693
693
  loopback callback is used, which completes only from a browser on the
694
694
  combiner host.
695
+
696
+ ``"auto"`` keeps the config portable: this machine's Tailscale MagicDNS
697
+ name on the combiner's port, or unset when there is no tailnet. Inside a
698
+ URL, ``{auto}`` is that name (``"https://{auto}"`` for ``tailscale
699
+ serve``). ``$MCP_COMBINER_OAUTH_PUBLIC_URL`` (a literal URL) overrides the
700
+ setting. Stored resolved — see :func:`resolve_public_url`.
695
701
  """
696
702
 
697
703
  prompt: AuthPrompt | None = None
@@ -711,7 +717,7 @@ class OAuthConfig(BaseModel):
711
717
  public_url = data.get("public_url") or data.get("publicUrl")
712
718
  if public_url is not None and not isinstance(public_url, str):
713
719
  raise ValueError("oauth.public_url must be a string")
714
- public_url = public_url.rstrip("/") if public_url else None
720
+ public_url = resolve_public_url(public_url)
715
721
  raw_prompt = data.get("prompt")
716
722
  prompt = (
717
723
  None
@@ -726,6 +732,45 @@ class OAuthConfig(BaseModel):
726
732
  )
727
733
 
728
734
 
735
+ PUBLIC_URL_ENV = "MCP_COMBINER_OAUTH_PUBLIC_URL"
736
+
737
+
738
+ def resolve_public_url(setting: str | None) -> str | None:
739
+ """The concrete ``oauth.public_url``.
740
+
741
+ ``$MCP_COMBINER_OAUTH_PUBLIC_URL``, when set, is the URL, verbatim.
742
+ Otherwise the *setting*: a literal URL; ``auto`` — this machine's
743
+ Tailscale MagicDNS name (else its tailnet IP) on the combiner's port; or a
744
+ URL with ``{auto}`` as its host (``https://{auto}`` for ``tailscale
745
+ serve``). No tailnet → ``None``: links use the loopback callback.
746
+ """
747
+ env = os.environ.get(PUBLIC_URL_ENV, "").strip()
748
+ if env:
749
+ return env.rstrip("/")
750
+ from mcp_combiner.ui_host.advertise import AUTO, AUTO_HOST, tailnet_host
751
+
752
+ value = (setting or "").strip().rstrip("/")
753
+ if not value:
754
+ return None
755
+ if value.lower() == AUTO:
756
+ value = f"http://{AUTO_HOST}"
757
+ elif "://" not in value:
758
+ value = f"http://{value}"
759
+ if AUTO_HOST not in value:
760
+ return value
761
+ name = tailnet_host()
762
+ if name is None:
763
+ logger.info("oauth.public_url %s: no tailnet here — links use the loopback callback", value)
764
+ return None
765
+ scheme, _, rest = value.partition("://")
766
+ authority, slash, path = rest.partition("/")
767
+ if authority == AUTO_HOST and scheme == "http":
768
+ from mcp_combiner.runtime import RUNTIME
769
+
770
+ authority = f"{AUTO_HOST}:{RUNTIME.serve_port or 9741}"
771
+ return f"{scheme}://{authority.replace(AUTO_HOST, name)}{slash}{path}"
772
+
773
+
729
774
  class IsolationConfig(BaseModel):
730
775
  """Lifecycle knobs for token-keyed isolated upstream sessions.
731
776
 
@@ -763,9 +808,13 @@ class BindConfig(BaseModel):
763
808
  ``MCP_COMBINER_HOST`` > this setting > the ``127.0.0.1`` default. Binding
764
809
  ``0.0.0.0`` serves loopback + every interface (LAN + tailnet) — required
765
810
  for the remote widget leg (docs/designs/advertised-ui-origin.md).
811
+
812
+ ``host`` may be a list — ``["127.0.0.1", "auto"]`` listens on loopback
813
+ and the tailnet only (``auto`` resolves to this machine's tailnet
814
+ address at startup); see ``mcp_combiner.binding``.
766
815
  """
767
816
 
768
- host: str = "127.0.0.1"
817
+ host: str | list[str] = "127.0.0.1"
769
818
 
770
819
 
771
820
  class ValidationConfig(BaseModel):
@@ -389,6 +389,9 @@ class CombinerRuntime:
389
389
  # The combiner's own loopback base URL (http://127.0.0.1:<port>), set by
390
390
  # create_app — where locally-opened links (OAuth short links) point.
391
391
  local_origin: str | None = None
392
+ # The port the combiner serves on, set by create_app before the config is
393
+ # loaded (oauth.public_url "auto" without a port defaults to it).
394
+ serve_port: int | None = None
392
395
  conn_manager: ConnectionManager | None = None
393
396
  proc_manager: BackingProcessManager | None = None
394
397
 
@@ -8,14 +8,16 @@ advertise knob changes only the origin prefix of `/ui/<token>/…` URLs.
8
8
 
9
9
  Modes (MCP_COMBINER_UI_ADVERTISE, default ``auto``):
10
10
 
11
- - ``auto`` — two-tier discovery: (1) ask tailscaled (``tailscale ip -4`` — the
12
- authoritative answer when the daemon runs), (2) fall back to scanning
13
- interface addresses for Tailscale's reserved CGNAT range (100.64.0.0/10 —
14
- with the caveat that some ISPs assign CGNAT space too, which is why tier 1
15
- exists), (3) neither finds a tailnet → the bind host (loopback today).
11
+ - ``auto`` — this machine's tailnet name, by :func:`tailnet_host`: (1) its
12
+ MagicDNS name (``tailscale status --json``, ``Self.DNSName``), (2) its
13
+ tailnet IP from tailscaled (``tailscale ip -4``), (3) an interface address in
14
+ Tailscale's reserved CGNAT range (100.64.0.0/10 — some ISPs assign CGNAT
15
+ space too, which is why the daemon outranks it); none → the bind host
16
+ (loopback).
16
17
  - ``loopback`` — force local-only URLs (the pre-feature behavior).
17
- - ``http://host[:port]`` — explicit override, the only machine-specific form,
18
- for the tailscale-serve (TLS/MagicDNS) variant.
18
+ - ``http://host[:port]`` — explicit override; ``{auto}`` as the host stands for
19
+ the tailnet name (``https://{auto}`` for the tailscale-serve variant), so the
20
+ setting stays portable. Braces can't occur in a real host name.
19
21
 
20
22
  v1 resolves once at boot (tailnet IP changes are rare; a restart heals). The
21
23
  design doc notes the refinement: a TTL cache behind the URL constructors so
@@ -62,6 +64,45 @@ def _tailscale_ip() -> str | None:
62
64
  return None
63
65
 
64
66
 
67
+ def _tailscale_dns_name() -> str | None:
68
+ """This machine's MagicDNS name from the tailscale daemon, or ``None``
69
+ (daemon absent, MagicDNS off)."""
70
+ import json
71
+
72
+ if shutil.which("tailscale") is None:
73
+ return None
74
+ try:
75
+ out = subprocess.run(
76
+ ["tailscale", "status", "--json", "--peers=false"],
77
+ capture_output=True,
78
+ text=True,
79
+ timeout=_TIER1_TIMEOUT_S,
80
+ check=False,
81
+ )
82
+ status = json.loads(out.stdout or "{}")
83
+ except (OSError, subprocess.TimeoutExpired, ValueError):
84
+ return None
85
+ me = status.get("Self") if isinstance(status, dict) else None
86
+ name = me.get("DNSName") if isinstance(me, dict) else None
87
+ return name.rstrip(".") or None if isinstance(name, str) else None
88
+
89
+
90
+ #: A setting's whole value meaning "this machine's tailnet" (bind, advertise,
91
+ #: oauth.public_url), and the same as a host placeholder inside a URL.
92
+ AUTO = "auto"
93
+ AUTO_HOST = "{auto}"
94
+
95
+
96
+ def tailnet_host() -> str | None:
97
+ """This machine's tailnet name for URLs: MagicDNS name, else tailnet IP."""
98
+ return _tailscale_dns_name() or _tailscale_ip() or _interface_scan_ip()
99
+
100
+
101
+ def tailnet_ip() -> str | None:
102
+ """This machine's tailnet IPv4 (for binding: no DNS involved)."""
103
+ return _tailscale_ip() or _interface_scan_ip()
104
+
105
+
65
106
  def _interface_scan_ip() -> str | None:
66
107
  """Tier 2: scan interface addresses for the CGNAT range.
67
108
 
@@ -108,22 +149,39 @@ def resolve_advertised_host(bind_host: str, mode: str | None = None) -> str:
108
149
  """
109
150
  import os
110
151
 
111
- advertise = (mode or os.environ.get(_ENV) or "auto").strip().lower()
112
- if advertise in ("", "auto"):
113
- found = _tailscale_ip() or _interface_scan_ip()
114
- if found:
115
- return found
116
- # Bind-all is a bind, not a name — never construct URLs with it.
117
- return "127.0.0.1" if bind_host in ("0.0.0.0", "::", "") else bind_host
152
+ advertise = (mode or os.environ.get(_ENV) or AUTO).strip().lower()
153
+ # Bind-all is a bind, not a name — never construct URLs with it.
154
+ local = "127.0.0.1" if bind_host in ("0.0.0.0", "::", "") else bind_host
155
+ if advertise in ("", AUTO):
156
+ return tailnet_host() or local
118
157
  if advertise in ("loopback", "local", "none"):
119
158
  return bind_host
120
159
  # Explicit origin: accept scheme://host[:port] and a bare host alike.
121
160
  if "://" in advertise:
122
161
  advertise = advertise.split("://", 1)[1]
123
- return advertise.rstrip("/") or bind_host
162
+ advertise = advertise.rstrip("/")
163
+ if AUTO_HOST in advertise:
164
+ name = tailnet_host()
165
+ if name is None:
166
+ return local
167
+ advertise = advertise.replace(AUTO_HOST, name)
168
+ return advertise or bind_host
124
169
 
125
170
 
126
171
  def advertised_origin(bind_host: str, port: int, mode: str | None = None) -> str:
127
172
  """The full advertised origin for the UI host page (``http://<host>:<port>``)."""
128
173
  host = resolve_advertised_host(bind_host, mode)
174
+ if _has_port(host):
175
+ return f"http://{host}" # an explicit origin's own port wins
176
+ if ":" in host and not host.startswith("["):
177
+ host = f"[{host}]" # a bare IPv6 address
129
178
  return f"http://{host}:{port}"
179
+
180
+
181
+ def _has_port(host: str) -> bool:
182
+ """Whether *host* already carries ``:port`` (``name:80``, ``[::1]:80``;
183
+ a bare IPv6 address does not)."""
184
+ head, sep, tail = host.rpartition(":")
185
+ if not sep or not tail.isdigit():
186
+ return False
187
+ return head.endswith("]") or ":" not in head
@@ -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.3"
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
 
@@ -21,6 +21,8 @@ from mcp_combiner.ui_host.advertise import (
21
21
  @pytest.fixture(autouse=True)
22
22
  def _clean_env(monkeypatch: pytest.MonkeyPatch) -> None:
23
23
  monkeypatch.delenv("MCP_COMBINER_UI_ADVERTISE", raising=False)
24
+ # No MagicDNS name unless a test gives one (never the real machine's).
25
+ monkeypatch.setattr("mcp_combiner.ui_host.advertise._tailscale_dns_name", lambda: None)
24
26
 
25
27
 
26
28
  def test_cgnat_range_shape() -> None:
@@ -79,3 +81,44 @@ def test_origin_composition() -> None:
79
81
  advertised_origin("127.0.0.1", 9741, "combiner.example") == "http://combiner.example:9741"
80
82
  )
81
83
  assert advertised_origin("127.0.0.1", 9741, "loopback") == "http://127.0.0.1:9741"
84
+
85
+
86
+ def test_auto_prefers_the_magicdns_name(monkeypatch: pytest.MonkeyPatch) -> None:
87
+ monkeypatch.setattr(
88
+ "mcp_combiner.ui_host.advertise._tailscale_dns_name", lambda: "box.tailnet.ts.net"
89
+ )
90
+ monkeypatch.setattr("mcp_combiner.ui_host.advertise._tailscale_ip", lambda: "100.64.5.5")
91
+ assert resolve_advertised_host("127.0.0.1") == "box.tailnet.ts.net"
92
+ assert advertised_origin("127.0.0.1", 9741, "AUTO") == "http://box.tailnet.ts.net:9741"
93
+
94
+
95
+ def test_auto_placeholder_inside_an_explicit_origin(monkeypatch: pytest.MonkeyPatch) -> None:
96
+ monkeypatch.setattr(
97
+ "mcp_combiner.ui_host.advertise._tailscale_dns_name", lambda: "box.tailnet.ts.net"
98
+ )
99
+ assert advertised_origin("127.0.0.1", 9741, "https://{auto}:443") == (
100
+ "http://box.tailnet.ts.net:443"
101
+ )
102
+ assert advertised_origin("127.0.0.1", 9741, "{auto}") == "http://box.tailnet.ts.net:9741"
103
+ # A host that happens to be called "auto" is just a host.
104
+ assert advertised_origin("127.0.0.1", 9741, "http://auto:8000") == "http://auto:8000"
105
+
106
+
107
+ def test_auto_placeholder_without_a_tailnet_is_local(monkeypatch: pytest.MonkeyPatch) -> None:
108
+ monkeypatch.setattr("mcp_combiner.ui_host.advertise._tailscale_ip", lambda: None)
109
+ monkeypatch.setattr("mcp_combiner.ui_host.advertise._interface_scan_ip", lambda: None)
110
+ assert resolve_advertised_host("0.0.0.0", "https://{auto}") == "127.0.0.1"
111
+
112
+
113
+ @pytest.mark.parametrize(
114
+ ("mode", "origin"),
115
+ [
116
+ ("http://box.tailnet.ts.net", "http://box.tailnet.ts.net:9741"),
117
+ ("http://box.tailnet.ts.net:443", "http://box.tailnet.ts.net:443"),
118
+ ("box.tailnet.ts.net:8080/", "http://box.tailnet.ts.net:8080"),
119
+ ("http://[fd7a::1]:9000", "http://[fd7a::1]:9000"),
120
+ ("fd7a::1", "http://[fd7a::1]:9741"),
121
+ ],
122
+ )
123
+ def test_an_explicit_origin_keeps_its_own_port(mode: str, origin: str) -> None:
124
+ assert advertised_origin("127.0.0.1", 9741, mode) == origin
@@ -0,0 +1,152 @@
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", " auto "]) == ["127.0.0.1", "auto"]
33
+ assert binding.parse_hosts("") == []
34
+ assert binding.parse_hosts(None) == []
35
+
36
+ def test_auto_resolves_to_the_tailnet_address(self, monkeypatch: pytest.MonkeyPatch) -> None:
37
+ monkeypatch.setattr(binding, "tailnet_address", lambda: "100.101.102.103")
38
+ assert binding.resolve_hosts(["127.0.0.1", "auto"]) == [
39
+ "127.0.0.1",
40
+ "100.101.102.103",
41
+ ]
42
+
43
+ def test_auto_without_a_tailnet_is_skipped_with_a_warning(
44
+ self, monkeypatch: pytest.MonkeyPatch, caplog: pytest.LogCaptureFixture
45
+ ) -> None:
46
+ monkeypatch.setattr(binding, "tailnet_address", lambda: None)
47
+ with caplog.at_level(logging.WARNING, logger="mcp-combiner"):
48
+ assert binding.resolve_hosts(["127.0.0.1", "Auto"]) == ["127.0.0.1"]
49
+ assert "no Tailscale address" in caplog.text
50
+
51
+ def test_a_wildcard_covers_the_rest(self) -> None:
52
+ assert binding.resolve_hosts(["127.0.0.1", "0.0.0.0", "::1"]) == ["0.0.0.0"]
53
+ assert binding.resolve_hosts(["0.0.0.0", "::"]) == ["0.0.0.0", "::"]
54
+
55
+ def test_empty_means_loopback(self) -> None:
56
+ assert binding.resolve_hosts([]) == ["127.0.0.1"]
57
+
58
+ def test_precedence_cli_env_config(
59
+ self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
60
+ ) -> None:
61
+ config = write_servers_config(
62
+ tmp_path / "servers.json", {}, bind={"host": ["::1", "127.0.0.1"]}
63
+ )
64
+ monkeypatch.delenv("MCP_COMBINER_HOST", raising=False)
65
+ assert resolve_bind_hosts(None, str(config)) == ["::1", "127.0.0.1"]
66
+ monkeypatch.setenv("MCP_COMBINER_HOST", "127.0.0.1,::1")
67
+ assert resolve_bind_hosts(None, str(config)) == ["127.0.0.1", "::1"]
68
+ assert resolve_bind_hosts("::1", str(config)) == ["::1"]
69
+
70
+ def test_loopback_detection(self) -> None:
71
+ assert binding.is_loopback("127.0.0.1") and binding.is_loopback("::1")
72
+ assert binding.is_loopback("localhost")
73
+ assert not binding.is_loopback("100.101.102.103") and not binding.is_loopback("0.0.0.0")
74
+
75
+
76
+ class TestBindSockets:
77
+ def test_unavailable_addresses_are_skipped(self, caplog: pytest.LogCaptureFixture) -> None:
78
+ port = free_port()
79
+ with caplog.at_level(logging.WARNING, logger="mcp-combiner"):
80
+ sockets = binding.bind_sockets(["127.0.0.1", TEST_NET], port)
81
+ try:
82
+ assert [s.getsockname()[:2] for s in sockets] == [("127.0.0.1", port)]
83
+ assert f"{TEST_NET}:{port} isn't available" in caplog.text
84
+ finally:
85
+ for s in sockets:
86
+ s.close()
87
+
88
+ def test_nothing_available_is_an_error(self) -> None:
89
+ with pytest.raises(OSError) as caught:
90
+ binding.bind_sockets([TEST_NET], free_port())
91
+ assert caught.value.errno == errno.EADDRNOTAVAIL
92
+
93
+ def test_a_port_in_use_is_fatal_and_releases_what_bound(self) -> None:
94
+ port = free_port()
95
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as squatter:
96
+ squatter.bind(("127.0.0.1", port))
97
+ squatter.listen(1)
98
+ with pytest.raises(OSError) as caught:
99
+ binding.bind_sockets(["127.0.0.1"], port)
100
+ assert caught.value.errno == errno.EADDRINUSE
101
+
102
+
103
+ @pytest.mark.e2e
104
+ @pytest.mark.skipif(not _has_ipv6_loopback(), reason="no IPv6 loopback here")
105
+ async def test_a_combiner_serves_on_every_listed_address(
106
+ procs: ProcFactory, tmp_path: Path
107
+ ) -> None:
108
+ config = write_servers_config(
109
+ tmp_path / "servers.json", {}, bind={"host": ["127.0.0.1", "::1", TEST_NET]}
110
+ )
111
+ combiner = await procs.start_combiner(
112
+ config, extra_args=["--log-file", str(tmp_path / "combiner.log")]
113
+ )
114
+ async with httpx2.AsyncClient(timeout=5.0) as http:
115
+ for base in (f"http://127.0.0.1:{combiner.port}", f"http://[::1]:{combiner.port}"):
116
+ response = await http.get(f"{base}/health")
117
+ assert response.status_code == 200, base
118
+ # The UI relay (port + 1) follows the same bind.
119
+ relay = await http.get(f"http://[::1]:{combiner.port + 1}/")
120
+ assert relay.status_code < 500
121
+ assert f"{TEST_NET}:{combiner.port} isn't available" in (tmp_path / "combiner.log").read_text()
122
+
123
+
124
+ @pytest.mark.e2e
125
+ async def test_a_busy_relay_port_does_not_stop_the_combiner(
126
+ procs: ProcFactory, tmp_path: Path
127
+ ) -> None:
128
+ """The UI relay (port + 1) only serves widgets: losing it must not keep the
129
+ combiner from serving — as before the relay was bound up front."""
130
+ port = free_port()
131
+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as squatter:
132
+ squatter.bind(("127.0.0.1", port + 1))
133
+ squatter.listen(1)
134
+ config = write_servers_config(tmp_path / "servers.json", {})
135
+ combiner = await procs.start_combiner(
136
+ config, port=port, extra_args=["--log-file", str(tmp_path / "combiner.log")]
137
+ )
138
+ async with httpx2.AsyncClient(timeout=5.0) as http:
139
+ assert (await http.get(f"http://127.0.0.1:{combiner.port}/health")).status_code == 200
140
+ assert "UI relay: can't listen" in (tmp_path / "combiner.log").read_text()
141
+
142
+
143
+ def test_an_unresolvable_name_is_skipped(caplog: pytest.LogCaptureFixture) -> None:
144
+ port = free_port()
145
+ with caplog.at_level(logging.WARNING, logger="mcp-combiner"):
146
+ sockets = binding.bind_sockets(["127.0.0.1", "no-such-host.invalid"], port)
147
+ try:
148
+ assert len(sockets) == 1
149
+ assert "no-such-host.invalid" in caplog.text
150
+ finally:
151
+ for s in sockets:
152
+ s.close()
@@ -0,0 +1,59 @@
1
+ """``oauth.public_url``: the portable ``auto`` setting and the env override."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import pytest
6
+
7
+ from mcp_combiner.config import PUBLIC_URL_ENV, OAuthConfig, resolve_public_url
8
+ from mcp_combiner.runtime import RUNTIME
9
+
10
+ NAME = "box.tailnet.ts.net"
11
+
12
+
13
+ @pytest.fixture(autouse=True)
14
+ def _tailnet(monkeypatch: pytest.MonkeyPatch) -> None:
15
+ monkeypatch.delenv(PUBLIC_URL_ENV, raising=False)
16
+ monkeypatch.setattr("mcp_combiner.ui_host.advertise._tailscale_dns_name", lambda: NAME)
17
+ monkeypatch.setattr(RUNTIME, "serve_port", 9741)
18
+
19
+
20
+ @pytest.mark.parametrize(
21
+ ("setting", "resolved"),
22
+ [
23
+ ("auto", f"http://{NAME}:9741"),
24
+ ("AUTO", f"http://{NAME}:9741"),
25
+ ("{auto}", f"http://{NAME}:9741"),
26
+ ("http://{auto}", f"http://{NAME}:9741"),
27
+ ("https://{auto}", f"https://{NAME}"),
28
+ ("https://{auto}:8443/", f"https://{NAME}:8443"),
29
+ ("http://{auto}:80/prefix", f"http://{NAME}:80/prefix"),
30
+ ("https://auto", "https://auto"), # a host named auto is just a host
31
+ ("https://combiner.example.com/", "https://combiner.example.com"),
32
+ ("combiner.example.com:9741", "http://combiner.example.com:9741"),
33
+ ("", None),
34
+ (None, None),
35
+ ],
36
+ )
37
+ def test_setting_forms(setting: str | None, resolved: str | None) -> None:
38
+ assert resolve_public_url(setting) == resolved
39
+
40
+
41
+ def test_the_env_var_is_a_literal_url_and_wins(monkeypatch: pytest.MonkeyPatch) -> None:
42
+ monkeypatch.setenv(PUBLIC_URL_ENV, "https://auth.example.com/")
43
+ assert resolve_public_url("auto") == "https://auth.example.com"
44
+ assert OAuthConfig.from_dict({}).public_url == "https://auth.example.com"
45
+ monkeypatch.setenv(PUBLIC_URL_ENV, "https://{auto}") # not special in the env
46
+ assert resolve_public_url(None) == "https://{auto}"
47
+
48
+
49
+ def test_auto_without_a_tailnet_means_loopback_links(monkeypatch: pytest.MonkeyPatch) -> None:
50
+ monkeypatch.setattr("mcp_combiner.ui_host.advertise._tailscale_dns_name", lambda: None)
51
+ monkeypatch.setattr("mcp_combiner.ui_host.advertise._tailscale_ip", lambda: None)
52
+ monkeypatch.setattr("mcp_combiner.ui_host.advertise._interface_scan_ip", lambda: None)
53
+ assert resolve_public_url("auto") is None
54
+ config = OAuthConfig.from_dict({"public_url": "auto"})
55
+ assert config.public_url is None and config.prompt is None
56
+
57
+
58
+ def test_the_config_stores_the_resolved_url() -> None:
59
+ assert OAuthConfig.from_dict({"public_url": "auto"}).public_url == f"http://{NAME}:9741"
@@ -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.3"
716
716
  source = { editable = "." }
717
717
  dependencies = [
718
718
  { name = "fastmcp" },