mcp-combiner 0.20.0.dev5__tar.gz → 0.21.0.dev1__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 (100) hide show
  1. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/CHANGELOG.md +25 -0
  2. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/PKG-INFO +1 -1
  3. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/config.py +12 -0
  4. mcp_combiner-0.21.0.dev1/mcp_combiner/listpaging.py +115 -0
  5. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/mounts.py +27 -6
  6. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/server.py +5 -0
  7. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/pyproject.toml +1 -1
  8. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/conftest.py +17 -1
  9. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_authprompt.py +2 -2
  10. mcp_combiner-0.21.0.dev1/tests/test_listpaging.py +108 -0
  11. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/uv.lock +1 -1
  12. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/.gitignore +0 -0
  13. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/.python-version +0 -0
  14. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/LICENSE +0 -0
  15. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/README.md +0 -0
  16. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/__init__.py +0 -0
  17. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/__main__.py +0 -0
  18. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/asgi.py +0 -0
  19. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/auth.py +0 -0
  20. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/authprompt.py +0 -0
  21. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/backing.py +0 -0
  22. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/binding.py +0 -0
  23. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/connections.py +0 -0
  24. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/ctl.py +0 -0
  25. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/era.py +0 -0
  26. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/externalservers.py +0 -0
  27. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/fastvalidate.py +0 -0
  28. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/handover.py +0 -0
  29. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/heldcalls.py +0 -0
  30. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/inbound_auth.py +0 -0
  31. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/isolated.py +0 -0
  32. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/listen.py +0 -0
  33. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/meta_tools.py +0 -0
  34. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/middleware.py +0 -0
  35. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/mockserver.py +0 -0
  36. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/notifications.py +0 -0
  37. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/nvim_channel.py +0 -0
  38. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/nvim_proxy.py +0 -0
  39. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/permissions.py +0 -0
  40. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/proxyfactory.py +0 -0
  41. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/py.typed +0 -0
  42. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/resume_transport.py +0 -0
  43. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/routes.py +0 -0
  44. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/runtime.py +0 -0
  45. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/schema.py +0 -0
  46. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/schemafix.py +0 -0
  47. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/sharedserver.py +0 -0
  48. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/status.py +0 -0
  49. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/toolcache.py +0 -0
  50. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/ui_host/__init__.py +0 -0
  51. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/ui_host/advertise.py +0 -0
  52. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/ui_host/holder.py +0 -0
  53. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/ui_host/routes.py +0 -0
  54. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/ui_host/sessions.py +0 -0
  55. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/ui_host/static/app-bridge.bundle.js +0 -0
  56. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/ui_host/templates.py +0 -0
  57. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/upstream_era.py +0 -0
  58. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/upstream_listen.py +0 -0
  59. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/mcp_combiner/upstream_session.py +0 -0
  60. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/pyrightconfig.json +0 -0
  61. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/fakes.py +0 -0
  62. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/fixtures/servers.json +0 -0
  63. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_advertised_origin.py +0 -0
  64. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_app_meta.py +0 -0
  65. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_auth.py +0 -0
  66. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_binding.py +0 -0
  67. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_combiner_reconnect.py +0 -0
  68. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_config.py +0 -0
  69. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_connections.py +0 -0
  70. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_ctl_lifecycle.py +0 -0
  71. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_elicit_e2e.py +0 -0
  72. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_era.py +0 -0
  73. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_externalservers.py +0 -0
  74. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_handover.py +0 -0
  75. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_inbound_auth.py +0 -0
  76. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_isolated.py +0 -0
  77. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_isolated_lifecycle_e2e.py +0 -0
  78. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_isolated_stdio.py +0 -0
  79. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_live_claude.py +0 -0
  80. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_mockserver.py +0 -0
  81. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_mounts.py +0 -0
  82. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_notifications.py +0 -0
  83. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_notifications_e2e.py +0 -0
  84. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_nvim_channel.py +0 -0
  85. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_nvim_e2e.py +0 -0
  86. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_oauth_mock.py +0 -0
  87. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_permissions.py +0 -0
  88. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_public_url.py +0 -0
  89. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_reload_config.py +0 -0
  90. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_resume_transport.py +0 -0
  91. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_route_matrix.py +0 -0
  92. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_schema_fixes.py +0 -0
  93. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_session_filter.py +0 -0
  94. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_session_independence.py +0 -0
  95. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_sharedserver.py +0 -0
  96. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_tool_fetch_wedge.py +0 -0
  97. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_ui_host.py +0 -0
  98. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_upstream_restart.py +0 -0
  99. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_upstream_session.py +0 -0
  100. {mcp_combiner-0.20.0.dev5 → mcp_combiner-0.21.0.dev1}/tests/test_visibility_and_reset_e2e.py +0 -0
@@ -8,6 +8,31 @@ tagged `vX.Y.Z`.
8
8
 
9
9
  ### Added
10
10
 
11
+ - **List paging.** `tools/list`, `resources/list`, `resources/templates/list`
12
+ and `prompts/list` are paged at `MCP_COMBINER_LIST_PAGE_SIZE` items (default
13
+ 1000; `0` = off). A server listing thousands of resources (13k from two
14
+ metrics servers in one setup) made a single ~17 MB response, past pi's 16 MiB
15
+ SSE event limit, so interactive-resource discovery failed. The later pages of
16
+ a `resources/list` walk are served from the first page's listing (one
17
+ upstream fan-out per walk, consistent pages). The Neovim plugin now follows
18
+ `nextCursor` for all list calls.
19
+ - **`resourceFilter`** (per server): glob patterns on resource URIs (and
20
+ template URI templates) as the server names them; only matching ones are
21
+ listed. `["ui://*"]` keeps only interactive widgets. Listing only — reading
22
+ a resource by URI still works.
23
+
24
+ ## [0.20.0] — 2026-11-03
25
+
26
+ Both MCP revisions, upstream and down. Upgrade notes: upstreams default to
27
+ `protocol: auto`, so a server that offers the 2026-07-28 revision is connected
28
+ on it and owns its own sessions (no per-chat isolation) — set
29
+ `"protocol": "legacy"` for one that still keeps per-connection state (svg-mcp
30
+ < 0.10). The combiner still answers clients on the handshake unless
31
+ `MCP_COMBINER_OFFER_2026=1`. `bind.host` may now be a list; `auto` / `{auto}`
32
+ name this machine on its tailnet in bind, advertise and `oauth.public_url`.
33
+
34
+ ### Added
35
+
11
36
  - Era translation, part 2 (still behind `MCP_COMBINER_OFFER_2026=1`):
12
37
  permission consent prompts work on the 2026-07-28 revision. A call that
13
38
  needs consent returns an `InputRequiredResult` with the same question and
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: mcp-combiner
3
- Version: 0.20.0-dev.5
3
+ Version: 0.21.0-dev.1
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
@@ -422,6 +422,14 @@ class ServerConfig(BaseModel):
422
422
  Examples: ``["gmail_*", "calendar_*"]`` to only include Gmail and Calendar tools.
423
423
  """
424
424
 
425
+ resource_filter: list[str] = Field(default_factory=list)
426
+ """Glob patterns choosing which of this server's resources (and resource
427
+ templates) are listed. Empty (default) lists all. Patterns match the URI as
428
+ the server names it (templates: their URI template), e.g. ``["ui://*"]``
429
+ keeps only interactive widgets — for a server that lists thousands of
430
+ resources (one per metric) its tools already cover. Listing only: a
431
+ resource read by URI still works."""
432
+
425
433
  permissions: PermissionPolicy | None = None
426
434
  """Per-call permission policy for this server (overrides/extends the global
427
435
  ``permissions`` block). ``None`` = inherit the global policy. See
@@ -494,6 +502,8 @@ class ServerConfig(BaseModel):
494
502
  "external_server",
495
503
  "toolFilter",
496
504
  "tool_filter",
505
+ "resourceFilter",
506
+ "resource_filter",
497
507
  "permissions",
498
508
  "isolate",
499
509
  "protocol",
@@ -518,6 +528,7 @@ class ServerConfig(BaseModel):
518
528
  shared_server = data.get("sharedServer") or data.get("shared_server")
519
529
  external_server = data.get("externalServer") or data.get("external_server")
520
530
  tool_filter = data.get("toolFilter") or data.get("tool_filter") or []
531
+ resource_filter = data.get("resourceFilter") or data.get("resource_filter") or []
521
532
 
522
533
  return cls(
523
534
  name=name,
@@ -533,6 +544,7 @@ class ServerConfig(BaseModel):
533
544
  shared_server=shared_server,
534
545
  external_server=external_server,
535
546
  tool_filter=tool_filter,
547
+ resource_filter=resource_filter,
536
548
  permissions=PermissionPolicy.from_dict(data.get("permissions")),
537
549
  isolate=(None if data.get("isolate") is None else bool(data["isolate"])),
538
550
  protocol=_upstream_protocol(name, data.get("protocol")),
@@ -0,0 +1,115 @@
1
+ """Paginated list responses (``tools/list``, ``resources/list``, …).
2
+
3
+ Some upstreams list thousands of resources (a metrics server exposing one per
4
+ metric). Unpaginated, the combiner's aggregate ``resources/list`` became one
5
+ JSON-RPC message — one SSE event — of tens of megabytes, past clients' event
6
+ limits (pi's is 16 MiB). So list responses are paginated: at most
7
+ :func:`list_page_size` items per page (``MCP_COMBINER_LIST_PAGE_SIZE``,
8
+ default 1000; ``0`` turns paging off), with a ``nextCursor`` the client follows.
9
+
10
+ fastmcp paginates by offset, re-running the full listing for every page. For
11
+ tools that is a cache hit; resources are fanned out to every upstream, so the
12
+ first page's full listing is kept per chat (:class:`ResourceListSnapshots`)
13
+ and the later pages of that walk are cut from it — consistent pages, one
14
+ upstream fan-out per walk.
15
+ """
16
+
17
+ from __future__ import annotations
18
+
19
+ import os
20
+ import time
21
+ from collections.abc import Sequence
22
+ from typing import Any
23
+
24
+ import mcp.types as mt
25
+ from fastmcp.resources import Resource
26
+ from fastmcp.server.middleware import CallNext, Middleware, MiddlewareContext
27
+
28
+ PAGE_SIZE_ENV = "MCP_COMBINER_LIST_PAGE_SIZE"
29
+ DEFAULT_PAGE_SIZE = 1000
30
+ #: How long a walk's snapshot serves later pages (a client fetches them back to back).
31
+ SNAPSHOT_TTL_S = 120.0
32
+ _MAX_SNAPSHOTS = 256
33
+
34
+
35
+ def list_page_size() -> int | None:
36
+ """Items per list page, or ``None`` for no paging."""
37
+ raw = os.environ.get(PAGE_SIZE_ENV, "").strip()
38
+ if not raw:
39
+ return DEFAULT_PAGE_SIZE
40
+ try:
41
+ size = int(raw)
42
+ except ValueError:
43
+ return DEFAULT_PAGE_SIZE
44
+ return size if size > 0 else None
45
+
46
+
47
+ class ResourceListSnapshots:
48
+ """The full resource listing of each chat's current list walk."""
49
+
50
+ def __init__(self) -> None:
51
+ self._walks: dict[str, tuple[float, Sequence[Resource]]] = {}
52
+
53
+ def keep(self, key: str, resources: Sequence[Resource]) -> None:
54
+ now = time.monotonic()
55
+ self._walks = {k: v for k, v in self._walks.items() if now - v[0] < SNAPSHOT_TTL_S}
56
+ if len(self._walks) >= _MAX_SNAPSHOTS:
57
+ del self._walks[min(self._walks, key=lambda k: self._walks[k][0])]
58
+ self._walks[key] = (now, resources)
59
+
60
+ def get(self, key: str) -> Sequence[Resource] | None:
61
+ entry = self._walks.get(key)
62
+ if entry is None or time.monotonic() - entry[0] >= SNAPSHOT_TTL_S:
63
+ return None
64
+ return entry[1]
65
+
66
+ def reset(self) -> None:
67
+ self._walks.clear()
68
+
69
+
70
+ SNAPSHOTS = ResourceListSnapshots()
71
+
72
+
73
+ class ResourceListPagingMiddleware(Middleware):
74
+ """Serve the later pages of a ``resources/list`` walk from its first page's listing."""
75
+
76
+ async def on_list_resources(
77
+ self,
78
+ context: MiddlewareContext[mt.ListResourcesRequest],
79
+ call_next: CallNext[mt.ListResourcesRequest, Sequence[Resource]],
80
+ ) -> Sequence[Resource]:
81
+ page_size = list_page_size()
82
+ key = _walk_key(context)
83
+ if page_size is None or key is None:
84
+ return await call_next(context)
85
+ if _cursor(context) is not None:
86
+ snapshot = SNAPSHOTS.get(key)
87
+ if snapshot is not None:
88
+ return snapshot
89
+ resources = await call_next(context)
90
+ if len(resources) > page_size:
91
+ SNAPSHOTS.keep(key, resources)
92
+ return resources
93
+
94
+
95
+ def _walk_key(context: MiddlewareContext[Any]) -> str | None:
96
+ """The chat whose walk this is: its token, else its connection."""
97
+ from mcp_combiner.middleware import _chat_token
98
+ from mcp_combiner.runtime import downstream_connection
99
+
100
+ token = _chat_token()
101
+ if token:
102
+ return f"token:{token}"
103
+ fctx = context.fastmcp_context
104
+ rc = fctx.request_context if fctx is not None else None
105
+ connection = downstream_connection(rc.session) if rc is not None else None
106
+ return f"conn:{id(connection)}" if connection is not None else None
107
+
108
+
109
+ def _cursor(context: MiddlewareContext[Any]) -> str | None:
110
+ """The request's pagination cursor (fastmcp's list middleware sees no params)."""
111
+ fctx = context.fastmcp_context
112
+ rc = fctx.request_context if fctx is not None else None
113
+ params = rc._srctx.params if rc is not None else None
114
+ cursor = params.get("cursor") if isinstance(params, dict) else None
115
+ return cursor if isinstance(cursor, str) and cursor else None
@@ -51,7 +51,9 @@ class BoundedListProvider(Provider):
51
51
  fires for them and call routing would silently break ("Unknown tool").
52
52
  """
53
53
 
54
- def __init__(self, inner: Any, timeout: float | None = None) -> None:
54
+ def __init__(
55
+ self, inner: Any, timeout: float | None = None, server_name: str | None = None
56
+ ) -> None:
55
57
  super().__init__()
56
58
  if timeout is None:
57
59
  from mcp_combiner.toolcache import UPSTREAM_TOOL_LIST_TIMEOUT
@@ -59,6 +61,7 @@ class BoundedListProvider(Provider):
59
61
  timeout = UPSTREAM_TOOL_LIST_TIMEOUT
60
62
  self._inner = inner
61
63
  self._timeout = timeout
64
+ self._server_name = server_name
62
65
 
63
66
  def __getattr__(self, name: str) -> Any:
64
67
  # Only reached for names not found locally or on Provider — delegate
@@ -114,10 +117,10 @@ class BoundedListProvider(Provider):
114
117
  return await self._bounded("get_app_tool", app_name, tool_name)
115
118
 
116
119
  async def list_resources(self) -> Any:
117
- return await self._bounded("list_resources") or []
120
+ return self._filtered(await self._bounded("list_resources") or [], "uri")
118
121
 
119
122
  async def _list_resources(self) -> Any:
120
- return await self._bounded("list_resources") or []
123
+ return self._filtered(await self._bounded("list_resources") or [], "uri")
121
124
 
122
125
  async def get_resource(self, uri: str, version: Any = None) -> Any:
123
126
  return await self._bounded("get_resource", uri, version)
@@ -126,10 +129,28 @@ class BoundedListProvider(Provider):
126
129
  return await self._bounded("get_resource", uri, version)
127
130
 
128
131
  async def list_resource_templates(self) -> Any:
129
- return await self._bounded("list_resource_templates") or []
132
+ return self._filtered(await self._bounded("list_resource_templates") or [], "uri_template")
130
133
 
131
134
  async def _list_resource_templates(self) -> Any:
132
- return await self._bounded("list_resource_templates") or []
135
+ return self._filtered(await self._bounded("list_resource_templates") or [], "uri_template")
136
+
137
+ def _filtered(self, items: Any, attr: str) -> Any:
138
+ """*items* narrowed by the server's ``resourceFilter`` (read per listing,
139
+ so a config reload applies without a remount)."""
140
+ from mcp_combiner.runtime import RUNTIME
141
+
142
+ config = RUNTIME.config
143
+ srv = config.servers.get(self._server_name) if config and self._server_name else None
144
+ if srv is None or not srv.resource_filter:
145
+ return items
146
+ import fnmatch
147
+
148
+ patterns = srv.resource_filter
149
+ return [
150
+ item
151
+ for item in items
152
+ if any(fnmatch.fnmatchcase(str(getattr(item, attr, "")), p) for p in patterns)
153
+ ]
133
154
 
134
155
  async def get_resource_template(self, uri: str, version: Any = None) -> Any:
135
156
  return await self._bounded("get_resource_template", uri, version)
@@ -208,7 +229,7 @@ def mount_server_provider(combiner: FastMCP, proxy: Any, server_name: str) -> No
208
229
 
209
230
  raw = FastMCPProvider(proxy) if isinstance(proxy, FastMCP) else proxy
210
231
  before = list(combiner.providers)
211
- combiner.add_provider(BoundedListProvider(raw), namespace=server_name)
232
+ combiner.add_provider(BoundedListProvider(raw, server_name=server_name), namespace=server_name)
212
233
  added = [p for p in combiner.providers if not any(p is q for q in before)]
213
234
  if not added:
214
235
  logger.warning(
@@ -20,6 +20,7 @@ from mcp_combiner.config import (
20
20
  CombinerConfig, # noqa: PLC2701
21
21
  )
22
22
  from mcp_combiner.connections import ConnectionManager
23
+ from mcp_combiner.listpaging import ResourceListPagingMiddleware, list_page_size
23
24
  from mcp_combiner.middleware import ( # noqa: F401 (ToolProcessingMiddleware re-export)
24
25
  ToolErrorPassthroughMiddleware,
25
26
  ToolProcessingMiddleware,
@@ -445,6 +446,8 @@ def create_combiner(
445
446
  "server's tools online."
446
447
  ),
447
448
  dereference_schemas=False, # Disabled: circular $ref causes infinite recursion
449
+ # Large aggregate lists are paged (mcp_combiner.listpaging).
450
+ list_page_size=list_page_size(),
448
451
  middleware=[
449
452
  # Outermost: catch-all safety net for any unhandled exception
450
453
  # (tool-visible errors pass through as isError results).
@@ -458,6 +461,8 @@ def create_combiner(
458
461
  retry_exceptions=(ConnectionError, TimeoutError),
459
462
  logger=logger,
460
463
  ),
464
+ # Later pages of a resources/list walk come from its first page's listing.
465
+ ResourceListPagingMiddleware(),
461
466
  # Innermost: caching, filtering, sanitization, domain error handling
462
467
  ToolProcessingMiddleware(),
463
468
  ],
@@ -1,6 +1,6 @@
1
1
  [project]
2
2
  name = "mcp-combiner"
3
- version = "0.20.0-dev.5"
3
+ version = "0.21.0-dev.1"
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"
@@ -72,6 +72,22 @@ def free_port() -> int:
72
72
  return port
73
73
 
74
74
 
75
+ def free_port_pair() -> int:
76
+ """A free port whose successor is free too: a combiner also serves its UI
77
+ relay on port + 1, which tests reach directly."""
78
+ for _ in range(50):
79
+ port = free_port()
80
+ probe = socket.socket()
81
+ try:
82
+ probe.bind(("127.0.0.1", port + 1))
83
+ except OSError:
84
+ continue
85
+ finally:
86
+ probe.close()
87
+ return port
88
+ raise RuntimeError("no free port pair found")
89
+
90
+
75
91
  def mockserver_argv(
76
92
  name: str,
77
93
  transport: str,
@@ -325,7 +341,7 @@ class ProcFactory:
325
341
  env: dict[str, str] | None = None,
326
342
  wait: bool = True,
327
343
  ) -> CombinerHandle:
328
- port = port or free_port()
344
+ port = port or free_port_pair()
329
345
  argv = [
330
346
  sys.executable,
331
347
  "-m",
@@ -27,7 +27,7 @@ from conftest import (
27
27
  OAuthMockFactory,
28
28
  ProcFactory,
29
29
  ServedOAuthMock,
30
- free_port,
30
+ free_port_pair,
31
31
  poll_until,
32
32
  write_servers_config,
33
33
  )
@@ -399,7 +399,7 @@ class TestCombinerPublicUrlFlow:
399
399
  env: dict[str, str] | None = None,
400
400
  protocol: str | None = None,
401
401
  ) -> str:
402
- port = free_port()
402
+ port = free_port_pair()
403
403
  entry: dict[str, Any] = {"url": mock.mcp_url, "transport": "http", "auth": "oauth"}
404
404
  if protocol is not None:
405
405
  entry["protocol"] = protocol
@@ -0,0 +1,108 @@
1
+ """Paginated list responses (mcp_combiner.listpaging)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from pathlib import Path
6
+
7
+ import pytest
8
+ from conftest import ProcFactory, http_mock_entry, write_servers_config
9
+ from fastmcp import Client
10
+ from fastmcp.resources import Resource
11
+
12
+ from mcp_combiner import listpaging
13
+ from mcp_combiner.listpaging import PAGE_SIZE_ENV, ResourceListSnapshots, list_page_size
14
+ from mcp_combiner.runtime import CLIENT_CONNECT_MODE
15
+
16
+
17
+ class TestPageSize:
18
+ def test_default_and_overrides(self, monkeypatch: pytest.MonkeyPatch) -> None:
19
+ monkeypatch.delenv(PAGE_SIZE_ENV, raising=False)
20
+ assert list_page_size() == listpaging.DEFAULT_PAGE_SIZE
21
+ monkeypatch.setenv(PAGE_SIZE_ENV, "50")
22
+ assert list_page_size() == 50
23
+ monkeypatch.setenv(PAGE_SIZE_ENV, "0")
24
+ assert list_page_size() is None
25
+ monkeypatch.setenv(PAGE_SIZE_ENV, "lots")
26
+ assert list_page_size() == listpaging.DEFAULT_PAGE_SIZE
27
+
28
+
29
+ class TestSnapshots:
30
+ def _resources(self, n: int) -> list[Resource]:
31
+ return [
32
+ Resource.from_function(lambda: "x", uri=f"mem://r/{i}", name=f"r{i}") for i in range(n)
33
+ ]
34
+
35
+ def test_keeps_per_walk_and_expires(self, monkeypatch: pytest.MonkeyPatch) -> None:
36
+ snaps = ResourceListSnapshots()
37
+ clock = [1000.0]
38
+ monkeypatch.setattr("mcp_combiner.listpaging.time.monotonic", lambda: clock[0])
39
+ a, b = self._resources(2), self._resources(3)
40
+ snaps.keep("token:a", a)
41
+ snaps.keep("token:b", b)
42
+ assert snaps.get("token:a") is a and snaps.get("token:b") is b
43
+ clock[0] += listpaging.SNAPSHOT_TTL_S
44
+ assert snaps.get("token:a") is None
45
+
46
+ def test_bounded(self, monkeypatch: pytest.MonkeyPatch) -> None:
47
+ snaps = ResourceListSnapshots()
48
+ clock = [0.0]
49
+ monkeypatch.setattr("mcp_combiner.listpaging.time.monotonic", lambda: clock[0])
50
+ for i in range(listpaging._MAX_SNAPSHOTS + 5):
51
+ clock[0] += 0.01
52
+ snaps.keep(f"token:{i}", [])
53
+ assert snaps.get("token:0") is None
54
+ assert snaps.get(f"token:{listpaging._MAX_SNAPSHOTS + 4}") == []
55
+
56
+
57
+ @pytest.mark.e2e
58
+ async def test_lists_page_and_clients_get_everything(procs: ProcFactory, tmp_path: Path) -> None:
59
+ mock = await procs.start_http_mock("mockup")
60
+ config = write_servers_config(tmp_path / "servers.json", {"mockup": http_mock_entry(mock.port)})
61
+ combiner = await procs.start_combiner(config, env={PAGE_SIZE_ENV: "1"})
62
+ await combiner.wait_server_state("mockup", ("ready",))
63
+ url = f"{combiner.mcp_url}/paging-0001"
64
+ async with Client(url, mode=CLIENT_CONNECT_MODE) as c:
65
+ everything = {str(r.uri) for r in await c.list_resources()}
66
+ assert len(everything) >= 2, everything
67
+
68
+ # Walk it by hand: one resource per page, every one once, then no cursor.
69
+ seen: list[str] = []
70
+ page = await c.list_resources_mcp()
71
+ while True:
72
+ assert len(page.resources) == 1
73
+ seen.extend(str(r.uri) for r in page.resources)
74
+ if page.next_cursor is None:
75
+ break
76
+ page = await c.list_resources_mcp(cursor=page.next_cursor)
77
+ assert sorted(seen) == sorted(everything)
78
+
79
+ # Tools page too, and the auto-paginating client still sees them all.
80
+ first = await c.list_tools_mcp()
81
+ assert len(first.tools) == 1 and first.next_cursor is not None
82
+ assert len(await c.list_tools()) > 1
83
+
84
+
85
+ @pytest.mark.e2e
86
+ async def test_resource_filter_narrows_a_servers_listing(
87
+ procs: ProcFactory, tmp_path: Path
88
+ ) -> None:
89
+ mock = await procs.start_http_mock("mockup")
90
+ unfiltered = write_servers_config(
91
+ tmp_path / "plain.json", {"mockup": http_mock_entry(mock.port)}
92
+ )
93
+ plain = await procs.start_combiner(unfiltered)
94
+ await plain.wait_server_state("mockup", ("ready",))
95
+ async with Client(f"{plain.mcp_url}/rfilter-0000", mode=CLIENT_CONNECT_MODE) as c:
96
+ assert "data://mockup/mock/readme" in [str(r.uri) for r in await c.list_resources()]
97
+
98
+ entry = {**http_mock_entry(mock.port), "resourceFilter": ["ui://*"]}
99
+ config = write_servers_config(tmp_path / "servers.json", {"mockup": entry})
100
+ combiner = await procs.start_combiner(config)
101
+ await combiner.wait_server_state("mockup", ("ready",))
102
+ async with Client(f"{combiner.mcp_url}/rfilter-0001", mode=CLIENT_CONNECT_MODE) as c:
103
+ uris = [str(r.uri) for r in await c.list_resources()]
104
+ assert uris and all(u.startswith("ui://") for u in uris), uris
105
+ hidden = "data://mockup/mock/readme"
106
+ # Listing only: a filtered-out resource can still be read by URI.
107
+ assert hidden not in uris
108
+ assert (await c.read_resource(hidden))[0] is not None
@@ -712,7 +712,7 @@ wheels = [
712
712
 
713
713
  [[package]]
714
714
  name = "mcp-combiner"
715
- version = "0.20.0-dev.5"
715
+ version = "0.21.0-dev.1"
716
716
  source = { editable = "." }
717
717
  dependencies = [
718
718
  { name = "fastmcp" },