@cyanmycelium/mcp-broker 1.3.3 → 1.4.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _cyanmycelium_mcp_core from '@cyanmycelium/mcp-core';
-import { McpBehavior, McpResource, McpTool, McpResourceTemplate, GrammarResolverOptions, IMcpServer, IMessageTransport, McpGrammar, IAccessTokenClaims, IMcpPrincipal, McpAuthError, ITokenValidator, IProtectedResourceMetadata, McpAdapterBase, McpResourceContent, McpToolResult } from '@cyanmycelium/mcp-core';
+import { IEventSource, McpBehavior, McpResourceContent, McpResource, McpTool, McpResourceTemplate, GrammarResolverOptions, IMcpServer, IMessageTransport, McpGrammar, IAccessTokenClaims, IMcpPrincipal, McpAuthError, ITokenValidator, IProtectedResourceMetadata, McpAdapterBase, McpToolResult } from '@cyanmycelium/mcp-core';
 export { IAccessTokenClaims, IProtectedResourceMetadata, ITokenValidator } from '@cyanmycelium/mcp-core';
 import { IncomingMessage, ServerResponse } from 'http';
 
@@ -56,6 +56,18 @@ interface IBrokerContext {
      * a slot that cannot exist at host start.
      */
     getStdioBridgeTarget?(): string | null | undefined;
+    /**
+     * Fires with the names of the slots whose *state* changed: a slot
+     * appeared, a provider attached or detached, a slot joined or left `_all`.
+     * Changes in the same tick arrive as one batch.
+     *
+     * Counters (`pendingCount`, `clientCount`, `sessionCount`) deliberately do
+     * not fire it: reading a resource moves them, so notifying on them would
+     * make every read trigger the next notification. They stay readable on
+     * demand. `_broker` turns this into `notifications/resources/updated` on
+     * `broker://providers` and `broker://providers/<name>`.
+     */
+    readonly onProvidersChanged?: IEventSource<readonly string[]>;
 }
 /**
  * Membership snapshot of the reserved `_all` aggregate slot.
@@ -123,6 +135,13 @@ interface IBrokerProviderInfo {
     sessionCount: number;
     /** Number of in-flight JSON-RPC requests awaiting a response. */
     pendingCount: number;
+    /**
+     * Client/URI pairs held by `resources/subscribe` on this slot. A number
+     * that only grows is the signature of Streamable HTTP clients leaving
+     * without `DELETE`: their sessions, and so their subscriptions, never
+     * expire. Optional so hand-written contexts keep compiling.
+     */
+    resourceSubscriptionCount?: number;
 }
 /** @deprecated Use {@link IBrokerContext}. */
 type BrokerContext = IBrokerContext;
@@ -138,6 +157,12 @@ type BrokerProviderInfo = IBrokerProviderInfo;
 declare class BrokerInfoBehavior extends McpBehavior {
     static readonly NAMESPACE = "broker";
     constructor(context: IBrokerContext);
+    /**
+     * Always reads live. `McpBehavior` caches the content of its root
+     * resource on first read and never refreshes it, which suits static
+     * content but froze this snapshot at whatever the first reader saw.
+     */
+    readResourceAsync(uri: string): Promise<McpResourceContent | undefined>;
     protected _buildResources(): McpResource[];
     protected _buildTools(): McpTool[];
 }
@@ -154,6 +179,12 @@ declare class BrokerInfoBehavior extends McpBehavior {
 declare class BrokerProvidersBehavior extends McpBehavior {
     static readonly NAMESPACE = "broker_providers";
     constructor(context: IBrokerContext);
+    /**
+     * Always reads live. `McpBehavior` caches the content of its root
+     * resource on first read and never refreshes it, which suits static
+     * content but froze this snapshot at whatever the first reader saw.
+     */
+    readResourceAsync(uri: string): Promise<McpResourceContent | undefined>;
     protected _buildResources(): McpResource[];
     protected _buildTemplate(): McpResourceTemplate[];
     protected _buildTools(): McpTool[];
@@ -1022,6 +1053,151 @@ type ProviderPrincipal = IProviderPrincipal;
 /** @deprecated Use {@link IProviderAuthenticator}. */
 type ProviderAuthenticator = IProviderAuthenticator;
 
+/**
+ * Per-slot bookkeeping for `resources/subscribe`.
+ *
+ * A slot is one MCP server shared by every client attached to it, so the
+ * provider behind it must not see one subscription per browser tab: it sees
+ * one per URI. This registry owns that reference count. The first subscriber
+ * of a URI triggers the upstream `resources/subscribe`, the last one to leave
+ * triggers the upstream `resources/unsubscribe`, and everybody in between is
+ * answered locally.
+ *
+ * Every operation on one `(slot, uri)` pair runs through a queue, so two
+ * clients subscribing at the same instant cannot both send upstream, and an
+ * unsubscribe cannot overtake the subscribe it undoes. A second subscriber that
+ * arrives while the first upstream round trip is in flight waits for it: on
+ * success it is added locally, with no second upstream call; on failure it
+ * asks the provider itself, since the first refusal may have been transient.
+ *
+ * The registry does no I/O. The tunnel supplies the upstream calls through
+ * {@link IResourceSubscriptionUpstream} and decides what a subscriber is: `S`
+ * is whatever it needs to deliver a notification later.
+ */
+/** Identifies one consumer across transports, e.g. `ws:7`, `http:<session>`, `stdio`. */
+type ClientKey = string;
+/** An upstream answer, reduced to what the registry needs. */
+type SubscriptionOutcome = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+    };
+};
+/** What the tunnel provides so the registry can talk to a provider. */
+interface IResourceSubscriptionUpstream {
+    /** Sends one request to the provider behind `slot` and resolves with its answer, never rejects. */
+    request(slot: string, method: "resources/subscribe" | "resources/unsubscribe", uri: string): Promise<SubscriptionOutcome>;
+    /** `true` when a provider currently serves `slot`. */
+    isConnected(slot: string): boolean;
+}
+/**
+ * Bounds on what clients can make the broker hold. Without them one client, or
+ * many sessions a client never closes, could grow the registry without limit
+ * and pin upstream subscriptions forever.
+ */
+interface IResourceSubscriptionLimits {
+    /** Distinct URIs one client may be subscribed to at once. */
+    readonly maxSubscriptionsPerClient: number;
+    /** Client/URI pairs one slot may hold at once. */
+    readonly maxSubscriptionsPerSlot: number;
+    /** Longest URI accepted, in UTF-16 code units. */
+    readonly maxResourceUriLength: number;
+}
+declare const DEFAULT_RESOURCE_SUBSCRIPTION_LIMITS: IResourceSubscriptionLimits;
+/**
+ * Where a URI stands with the provider.
+ *
+ * - `inactive`: not subscribed upstream. Either nothing was ever sent, or the
+ *   provider disconnected and the subscription waits for {@link ResourceSubscriptionRegistry.replay}.
+ * - `subscribing` / `unsubscribing`: an upstream round trip is in flight.
+ * - `active`: the provider confirmed the subscription.
+ */
+type SubscriptionState = "inactive" | "subscribing" | "active" | "unsubscribing";
+/** Error code for a subscription refused by a broker limit. JSON-RPC reserves -32000..-32099 for servers. */
+declare const SUBSCRIPTION_LIMIT_ERROR_CODE = -32000;
+/** One URI whose upstream subscription was re-sent after a provider reconnected. */
+interface IReplayResult<S> {
+    readonly uri: string;
+    readonly outcome: SubscriptionOutcome;
+    /** Who was subscribed at the time; they are dropped when the outcome is a failure. */
+    readonly subscribers: ReadonlyArray<{
+        readonly client: ClientKey;
+        readonly sink: S;
+    }>;
+}
+declare class ResourceSubscriptionRegistry<S> {
+    private readonly _upstream;
+    private readonly _limits;
+    /** slot → uri → entry. */
+    private readonly _slots;
+    /**
+     * client → slot → URIs, counting subscriptions still being confirmed.
+     * Counting those is what makes the per-client limit hold under concurrent
+     * requests: a reservation is taken before the upstream call, not after.
+     */
+    private readonly _clients;
+    /** slot → number of client/URI pairs, reserved ones included. */
+    private readonly _slotCounts;
+    constructor(upstream: IResourceSubscriptionUpstream, limits?: Partial<IResourceSubscriptionLimits>);
+    get limits(): IResourceSubscriptionLimits;
+    /**
+     * Subscribes `client` to `uri` on `slot`. Idempotent: subscribing twice
+     * keeps one entry and answers success.
+     */
+    subscribe(slot: string, client: ClientKey, sink: S, uri: string): Promise<SubscriptionOutcome>;
+    /**
+     * Unsubscribes `client` from `uri`. Always succeeds, including for a URI
+     * the client never subscribed to: the client asked not to be subscribed,
+     * and it is not. The provider is told only when the last subscriber leaves,
+     * and only when it is connected; its answer does not change ours.
+     */
+    unsubscribe(slot: string, client: ClientKey, uri: string): Promise<SubscriptionOutcome>;
+    /** Confirmed subscribers of `uri` on `slot`, the only ones a notification may reach. */
+    subscribers(slot: string, uri: string): ReadonlyArray<{
+        readonly client: ClientKey;
+        readonly sink: S;
+    }>;
+    /** Where `uri` stands with the provider behind `slot`. */
+    stateOf(slot: string, uri: string): SubscriptionState;
+    /** Number of client/URI pairs on `slot`, subscriptions being confirmed included. */
+    countFor(slot: string): number;
+    /** `true` when `slot` has at least one URI someone is subscribed to. */
+    hasSubscriptions(slot: string): boolean;
+    /**
+     * Drops every subscription `client` holds, on every slot. Safe to call
+     * repeatedly and for a client that holds nothing.
+     */
+    removeClient(client: ClientKey): Promise<void>;
+    /**
+     * Records that the provider behind `slot` went away: whatever it had
+     * subscribed is gone with it. Subscribers are kept, so {@link replay} can
+     * restore them when a provider comes back.
+     */
+    providerDisconnected(slot: string): void;
+    /**
+     * Re-sends one upstream `resources/subscribe` per URI that still has
+     * subscribers, after a provider (re)attached to `slot`. A URI the new
+     * provider refuses is dropped along with its subscribers, since nothing
+     * will ever notify them; the result lists them so the caller can tell them.
+     */
+    replay(slot: string): Promise<IReplayResult<S>[]>;
+    /** Forgets everything without calling upstream. Used when the broker stops. */
+    clear(): void;
+    private _enqueue;
+    private _entry;
+    /** Removes an entry nobody holds or waits for, once its queue is idle. */
+    private _dropIfUnused;
+    private _reserve;
+    private _release;
+    private _isReserved;
+    /** `true` when some client reserved `uri` on `slot`, confirmed or not. */
+    private _hasReservation;
+    private _clientTotal;
+}
+
 /**
  * What the broker does when a provider connects to a slot another socket
  * already holds.
@@ -1199,6 +1375,18 @@ interface IWsTunnelOptions {
      * @default 60000
      */
     providerRequestTimeoutMs?: number;
+    /**
+     * Bounds on `resources/subscribe` bookkeeping. Every field is optional and
+     * falls back to {@link DEFAULT_RESOURCE_SUBSCRIPTION_LIMITS}: 64 URIs per
+     * client, 1024 client subscriptions per slot, URIs of at most 2048
+     * characters. A subscription past a limit is refused with `-32000`, an
+     * overlong URI with `-32602`.
+     *
+     * The per-slot bound is what caps a Streamable HTTP client that closes its
+     * tab without `DELETE`: its session never expires, so neither do its
+     * subscriptions.
+     */
+    resourceSubscriptions?: Partial<IResourceSubscriptionLimits>;
     /**
      * Optional static-file mounts served over plain HTTP.
      * Matched by longest URL prefix; directory requests fall back to `index.html`.
@@ -1439,6 +1627,24 @@ declare class WsTunnel implements IBrokerContext {
     /** Provider principals captured during successful WebSocket upgrades. */
     private readonly _pendingProviderPrincipals;
     private readonly _providerPrincipals;
+    /**
+     * `resources/subscribe` bookkeeping for every slot: who is subscribed to
+     * what, and the one upstream subscription per URI that stands for them.
+     */
+    private readonly _subscriptions;
+    /** Stable id per raw WS client socket, the WS part of a {@link ClientKey}. */
+    private readonly _wsClientIds;
+    private _nextWsClientId;
+    /** Stable id per in-process client, the internal part of a {@link ClientKey}. */
+    private readonly _internalClientIds;
+    private _nextInternalClientId;
+    /** Emitter behind {@link onProvidersChanged}. */
+    private readonly _providersChanged;
+    /** Slots changed since the last {@link _providersChanged} batch went out. */
+    private readonly _changedSlots;
+    private _changedSlotsTimer;
+    /** Slots already warned about for a malformed `notifications/resources/updated`. */
+    private readonly _invalidUpdateWarnedProviders;
     constructor(options: IWsTunnelOptions);
     get version(): string;
     get name(): string;
@@ -1471,6 +1677,8 @@ declare class WsTunnel implements IBrokerContext {
      * `_all` by hand.
      */
     getAggregateInfo(): IBrokerAggregateInfo;
+    /** See {@link IBrokerContext.onProvidersChanged}. */
+    get onProvidersChanged(): IEventSource<readonly string[]>;
     getProvidersInfo(): IBrokerProviderInfo[];
     getProviderInfo(name: string): IBrokerProviderInfo | undefined;
     private _buildProviderInfo;
@@ -1890,6 +2098,71 @@ declare class WsTunnel implements IBrokerContext {
     private _isProviderConnected;
     /** Returns the state for `name`, creating it lazily if it doesn't exist yet. */
     private _getOrCreateProviderState;
+    /** The {@link ClientKey} of a raw WS client socket. */
+    private _wsClientKey;
+    /** The {@link ClientKey} of a sink that is a client, `null` for the broker's own and internal sinks. */
+    private _clientKeyOf;
+    /** The {@link ClientKey} of an in-process client from {@link openInternalClient}. */
+    private _internalClientKey;
+    /** The principal behind a client sink, for the per-notification policy check. */
+    private _principalOfSink;
+    /**
+     * Answers `resources/subscribe` and `resources/unsubscribe` from the
+     * broker's own registry instead of relaying them. Returns `true` when the
+     * frame was one of those and has been (or will be) answered.
+     *
+     * Also remembers the last `initialize` of the slot, for {@link _replaySubscriptions}.
+     *
+     * Runs after the policy check. `resources/unsubscribe` is not classified,
+     * so it is never refused: a client whose read grant was revoked must
+     * still be able to drop what it holds. `_all` is skipped: it serves tools
+     * and prompts only, and answers resources methods with `-32601` itself.
+     */
+    private _interceptClientFrame;
+    /**
+     * Sends one aggregated `resources/subscribe` or `resources/unsubscribe` to
+     * the provider behind `slot` and resolves with its answer. Never rejects:
+     * a disconnect or a timeout arrives as an error answer through the same
+     * pending-request machinery every client request uses.
+     */
+    private _subscriptionRequest;
+    /** Sends a request of the broker's own to a provider and resolves with the parsed answer. */
+    private _brokerRequest;
+    /**
+     * Delivers a provider's `notifications/resources/updated` to the sessions
+     * subscribed to its URI, and to nobody else.
+     *
+     * A frame without a usable URI is dropped, never broadcast: there is no
+     * safe audience for it. Each recipient is re-checked against the policy,
+     * because a grant can be revoked after the subscription was accepted; a
+     * recipient that fails the check is unsubscribed as well as skipped.
+     */
+    private _routeResourceUpdated;
+    private _deliverResourceUpdated;
+    /** A provider now serves `name`: announce it, and restore the subscriptions it should hold. */
+    private _onProviderAttached;
+    /**
+     * Re-subscribes a provider that (re)attached to URIs clients still hold,
+     * once per URI.
+     *
+     * The provider is handshaken first, with the last `initialize` a client
+     * sent on this slot, because a fresh provider has no session: requests
+     * before `initialize` break the MCP lifecycle, and an mcp-core server
+     * suppresses its list_changed notifications until it sees
+     * `notifications/initialized`.
+     *
+     * Every subscriber then gets one `notifications/resources/updated`: the
+     * content may have changed while nobody was watching, so a re-read is due.
+     * Where the new provider refuses a URI, that is also what tells its
+     * subscribers, since their re-read fails; their subscription is dropped.
+     */
+    private _replaySubscriptions;
+    /**
+     * Queues `name` for the next {@link onProvidersChanged} batch. Batched per
+     * tick, so a multiplexed socket announcing ten slots, or a slot attaching
+     * and joining `_all` in the same breath, produces one notification.
+     */
+    private _emitProviderChanged;
     private _handleSamplesIndex;
     private _serveStatic;
 }
@@ -1925,6 +2198,7 @@ declare class WsTunnelBuilder {
     private _providerHeartbeatIntervalMs;
     private _providerTakeover;
     private _providerRequestTimeoutMs;
+    private _resourceSubscriptions;
     private _staticMounts;
     private _stdioUpstreams;
     private _remoteUpstreams;
@@ -2040,6 +2314,12 @@ declare class WsTunnelBuilder {
      * @default 60000
      */
     withProviderRequestTimeout(timeoutMs: number): this;
+    /**
+     * Bounds what `resources/subscribe` can make the broker hold. Fields left
+     * out keep their default: 64 URIs per client, 1024 client subscriptions per
+     * slot, URIs of at most 2048 characters.
+     */
+    withResourceSubscriptionLimits(limits: Partial<IResourceSubscriptionLimits>): this;
     /**
      * Adds a static-file mount served over plain HTTP.
      * Can be called multiple times; longest-prefix match wins at runtime.
@@ -2541,6 +2821,17 @@ interface IBrokerConfig {
      * @default 60000
      */
     providerRequestTimeoutMs?: number;
+    /**
+     * Bounds on `resources/subscribe` bookkeeping. Each field maps to an env
+     * var: `MCP_BROKER_MAX_SUBSCRIPTIONS_PER_CLIENT` (default 64),
+     * `MCP_BROKER_MAX_SUBSCRIPTIONS_PER_SLOT` (default 1024),
+     * `MCP_BROKER_MAX_RESOURCE_URI_LENGTH` (default 2048).
+     */
+    resourceSubscriptions?: {
+        maxSubscriptionsPerClient?: number;
+        maxSubscriptionsPerSlot?: number;
+        maxResourceUriLength?: number;
+    };
     /**
      * What happens when a provider connects to a slot another socket already
      * holds. Maps to `MCP_BROKER_PROVIDER_TAKEOVER`.
@@ -2783,4 +3074,4 @@ type BrokerConfig = IBrokerConfig;
 /** @deprecated Use {@link ILoadedBrokerConfig}. */
 type LoadedBrokerConfig = ILoadedBrokerConfig;
 
-export { type AccessTokenClaims, type AggregateScopeFilter, type AllowedOrigins, type AuditContext, AuthError, type AuthErrorCode, type AuthorizationAuditConfig, type AuthorizationAuditEvent, type AuthorizationDecision, type AuthorizationDecisionReason, type AuthorizationPolicyConfig, type AuthorizationRequest, type AuthorizationSubject, BROKER_AGGREGATE_NAME, BROKER_GUIDES, BROKER_GUIDE_MIME_TYPE, BROKER_GUIDE_TOPICS, BROKER_GUIDE_URI_PREFIX, BROKER_GUIDE_URI_TEMPLATE, BROKER_PROVIDER_NAME, BROKER_RESERVED_SLOTS, type BrokerAuthConfig, type BrokerConfig, type BrokerContext, BrokerDiagnoseAdapter, BrokerDiagnoseBehavior, type BrokerDiagnosisRuleId, type BrokerDiagnosisSeverity, type BrokerGrammarEntry, BrokerGuideAdapter, BrokerGuideBehavior, type BrokerGuideTopic, BrokerInfoBehavior, type BrokerLocale, type BrokerProviderInfo, type BrokerProviderTransport, BrokerProvidersBehavior, type BrokerUserAgent, type CapabilityClassifier, type ClassifiedCapability, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DefaultSlotResourceResolver, type DenyPolicy, HttpAuthGuard, type IAuditContext, type IAuthorizationAuditConfig, type IAuthorizationAuditEvent, type IAuthorizationDecision, type IAuthorizationPolicyConfig, type IAuthorizationRequest, type IAuthorizationSubject, type IBrokerAggregateInfo, type IBrokerAuthConfig, type IBrokerConfig, type IBrokerContext, type IBrokerDiagnosis, type IBrokerDiagnosisProblem, type IBrokerDiagnosisSkippedCheck, type IBrokerDiagnosisSlot, type IBrokerGrammarEntry, type IBrokerGuide, type IBrokerProviderInfo, type IBrokerSecurityInfo, type ICapabilityClassifier, type IClassifiedCapability, type IDenyPolicy, type IInternalClient, type IJwtAuthOptions, type IJwtValidatorOptions, type ILoadedBrokerConfig, type IMcpOperation, type IMcpbBundleConfig, type IOpenTargetResolution, type IPolicyAssignment, type IPolicyAuthorization, type IPolicyEngine, type IPrincipal, type IProviderAuthenticator, type IProviderPrincipal, type IProviderPublishDecision, type IRemoteUpstreamConfig, type IResolvedAuth, type IRoleDefinition, type ISlotResourceResolver, type IStartBrokerServerOptions, type IStaticMount, type IStdioUpstreamConfig, type ISubjectMapper, type ISubjectMappingConfig, type IUpstream, type IWsTunnelOptions, type InternalClient, type JwtAuthOptions, JwtSubjectMapper, JwtTokenValidator, type JwtValidatorOptions, type LoadedBrokerConfig, type McpOperation, type McpbBundleConfig, PACKAGE_NAME, type PolicyAssignment, type PolicyAuthorization, type PolicyEngine, type Principal, type ProtectedResourceMetadata, type ProviderAuthenticationResult, type ProviderAuthenticator, type ProviderAuthenticatorReturn, type ProviderPrincipal, type ProviderPublishDenialReason, type ProviderTakeoverMode, RemoteUpstream, type RemoteUpstreamConfig, type ResolvedAuth, ResourcePath, ResourcePathPattern, type RoleDefinition, SharedSecretProviderAuthenticator, type SlotResourceResolver, type StartBrokerServerOptions, type StaticMount, StdioUpstream, type StdioUpstreamConfig, type SubjectMapper, type SubjectMappingConfig, SubjectMappingError, type TokenValidator, type Upstream, VERSION, WsTunnel, WsTunnelBuilder, type WsTunnelOptions, authorizationWithEngine, brokerGrammarKey, brokerGuide, brokerGuideIndex, brokerGuideTopicFromUri, brokerGuideUri, buildJwtAuth, buildResourceMetadata, compileAuthorizationPolicy, compileProviderAllowedResources, diagnoseBroker, hasAuthorizationPolicies, isReservedBrokerSlot, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerConfig, loadBrokerGrammar, loadMcpbBundle, normalizeProviderAuthentication, providerMayPublish, providerPublishDecision, resolveOpenTarget, scopesOf, startBrokerServer, unzipMcpb, validateCapability };
+export { type AccessTokenClaims, type AggregateScopeFilter, type AllowedOrigins, type AuditContext, AuthError, type AuthErrorCode, type AuthorizationAuditConfig, type AuthorizationAuditEvent, type AuthorizationDecision, type AuthorizationDecisionReason, type AuthorizationPolicyConfig, type AuthorizationRequest, type AuthorizationSubject, BROKER_AGGREGATE_NAME, BROKER_GUIDES, BROKER_GUIDE_MIME_TYPE, BROKER_GUIDE_TOPICS, BROKER_GUIDE_URI_PREFIX, BROKER_GUIDE_URI_TEMPLATE, BROKER_PROVIDER_NAME, BROKER_RESERVED_SLOTS, type BrokerAuthConfig, type BrokerConfig, type BrokerContext, BrokerDiagnoseAdapter, BrokerDiagnoseBehavior, type BrokerDiagnosisRuleId, type BrokerDiagnosisSeverity, type BrokerGrammarEntry, BrokerGuideAdapter, BrokerGuideBehavior, type BrokerGuideTopic, BrokerInfoBehavior, type BrokerLocale, type BrokerProviderInfo, type BrokerProviderTransport, BrokerProvidersBehavior, type BrokerUserAgent, type CapabilityClassifier, type ClassifiedCapability, type ClientKey, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DEFAULT_RESOURCE_SUBSCRIPTION_LIMITS, DefaultSlotResourceResolver, type DenyPolicy, HttpAuthGuard, type IAuditContext, type IAuthorizationAuditConfig, type IAuthorizationAuditEvent, type IAuthorizationDecision, type IAuthorizationPolicyConfig, type IAuthorizationRequest, type IAuthorizationSubject, type IBrokerAggregateInfo, type IBrokerAuthConfig, type IBrokerConfig, type IBrokerContext, type IBrokerDiagnosis, type IBrokerDiagnosisProblem, type IBrokerDiagnosisSkippedCheck, type IBrokerDiagnosisSlot, type IBrokerGrammarEntry, type IBrokerGuide, type IBrokerProviderInfo, type IBrokerSecurityInfo, type ICapabilityClassifier, type IClassifiedCapability, type IDenyPolicy, type IInternalClient, type IJwtAuthOptions, type IJwtValidatorOptions, type ILoadedBrokerConfig, type IMcpOperation, type IMcpbBundleConfig, type IOpenTargetResolution, type IPolicyAssignment, type IPolicyAuthorization, type IPolicyEngine, type IPrincipal, type IProviderAuthenticator, type IProviderPrincipal, type IProviderPublishDecision, type IRemoteUpstreamConfig, type IReplayResult, type IResolvedAuth, type IResourceSubscriptionLimits, type IResourceSubscriptionUpstream, type IRoleDefinition, type ISlotResourceResolver, type IStartBrokerServerOptions, type IStaticMount, type IStdioUpstreamConfig, type ISubjectMapper, type ISubjectMappingConfig, type IUpstream, type IWsTunnelOptions, type InternalClient, type JwtAuthOptions, JwtSubjectMapper, JwtTokenValidator, type JwtValidatorOptions, type LoadedBrokerConfig, type McpOperation, type McpbBundleConfig, PACKAGE_NAME, type PolicyAssignment, type PolicyAuthorization, type PolicyEngine, type Principal, type ProtectedResourceMetadata, type ProviderAuthenticationResult, type ProviderAuthenticator, type ProviderAuthenticatorReturn, type ProviderPrincipal, type ProviderPublishDenialReason, type ProviderTakeoverMode, RemoteUpstream, type RemoteUpstreamConfig, type ResolvedAuth, ResourcePath, ResourcePathPattern, ResourceSubscriptionRegistry, type RoleDefinition, SUBSCRIPTION_LIMIT_ERROR_CODE, SharedSecretProviderAuthenticator, type SlotResourceResolver, type StartBrokerServerOptions, type StaticMount, StdioUpstream, type StdioUpstreamConfig, type SubjectMapper, type SubjectMappingConfig, SubjectMappingError, type SubscriptionOutcome, type SubscriptionState, type TokenValidator, type Upstream, VERSION, WsTunnel, WsTunnelBuilder, type WsTunnelOptions, authorizationWithEngine, brokerGrammarKey, brokerGuide, brokerGuideIndex, brokerGuideTopicFromUri, brokerGuideUri, buildJwtAuth, buildResourceMetadata, compileAuthorizationPolicy, compileProviderAllowedResources, diagnoseBroker, hasAuthorizationPolicies, isReservedBrokerSlot, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerConfig, loadBrokerGrammar, loadMcpbBundle, normalizeProviderAuthentication, providerMayPublish, providerPublishDecision, resolveOpenTarget, scopesOf, startBrokerServer, unzipMcpb, validateCapability };

package/dist/index.js

@@ -1,3 +1,3 @@
-export { AuthError, BROKER_AGGREGATE_NAME, BROKER_GUIDES, BROKER_GUIDE_MIME_TYPE, BROKER_GUIDE_TOPICS, BROKER_GUIDE_URI_PREFIX, BROKER_GUIDE_URI_TEMPLATE, BROKER_PROVIDER_NAME, BROKER_RESERVED_SLOTS, BrokerDiagnoseAdapter, BrokerDiagnoseBehavior, BrokerGuideAdapter, BrokerGuideBehavior, BrokerInfoBehavior, BrokerProvidersBehavior, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DefaultSlotResourceResolver, HttpAuthGuard, JwtSubjectMapper, JwtTokenValidator, PACKAGE_NAME, RemoteUpstream, ResourcePath, ResourcePathPattern, SharedSecretProviderAuthenticator, StdioUpstream, SubjectMappingError, VERSION, WsTunnel, WsTunnelBuilder, authorizationWithEngine, brokerGrammarKey, brokerGuide, brokerGuideIndex, brokerGuideTopicFromUri, brokerGuideUri, buildJwtAuth, buildResourceMetadata, compileAuthorizationPolicy, compileProviderAllowedResources, diagnoseBroker, hasAuthorizationPolicies, isReservedBrokerSlot, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerConfig, loadBrokerGrammar, loadMcpbBundle, normalizeProviderAuthentication, providerMayPublish, providerPublishDecision, resolveOpenTarget, scopesOf, startBrokerServer, unzipMcpb, validateCapability } from './chunk-J5TN5RYU.js';
+export { AuthError, BROKER_AGGREGATE_NAME, BROKER_GUIDES, BROKER_GUIDE_MIME_TYPE, BROKER_GUIDE_TOPICS, BROKER_GUIDE_URI_PREFIX, BROKER_GUIDE_URI_TEMPLATE, BROKER_PROVIDER_NAME, BROKER_RESERVED_SLOTS, BrokerDiagnoseAdapter, BrokerDiagnoseBehavior, BrokerGuideAdapter, BrokerGuideBehavior, BrokerInfoBehavior, BrokerProvidersBehavior, ConfigPolicyEngine, ConfiguredCapabilityClassifier, DEFAULT_CONFIG_FILENAME, DEFAULT_RESOURCE_SUBSCRIPTION_LIMITS, DefaultSlotResourceResolver, HttpAuthGuard, JwtSubjectMapper, JwtTokenValidator, PACKAGE_NAME, RemoteUpstream, ResourcePath, ResourcePathPattern, ResourceSubscriptionRegistry, SUBSCRIPTION_LIMIT_ERROR_CODE, SharedSecretProviderAuthenticator, StdioUpstream, SubjectMappingError, VERSION, WsTunnel, WsTunnelBuilder, authorizationWithEngine, brokerGrammarKey, brokerGuide, brokerGuideIndex, brokerGuideTopicFromUri, brokerGuideUri, buildJwtAuth, buildResourceMetadata, compileAuthorizationPolicy, compileProviderAllowedResources, diagnoseBroker, hasAuthorizationPolicies, isReservedBrokerSlot, iterAvailableBrokerGrammars, iterBrokerGrammarsFrom, loadBrokerConfig, loadBrokerGrammar, loadMcpbBundle, normalizeProviderAuthentication, providerMayPublish, providerPublishDecision, resolveOpenTarget, scopesOf, startBrokerServer, unzipMcpb, validateCapability } from './chunk-YTRVLPHP.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@cyanmycelium/mcp-broker",
-    "version": "1.3.3",
+    "version": "1.4.0",
     "description": "WebSocket-based Model Context Protocol broker. Aggregates multiple MCP providers behind a single endpoint with stdio, SSE, and Streamable HTTP client transports.",
     "type": "module",
     "license": "Apache-2.0",
@@ -69,7 +69,7 @@
         "prepublishOnly": "npm run lint && npm run build && npm test"
     },
     "dependencies": {
-        "@cyanmycelium/mcp-core": "^1.1.0",
+        "@cyanmycelium/mcp-core": "^1.3.0",
         "jose": "^6.2.3",
         "open": "^11.0.0",
         "ws": "^8.18.0"

package/src/authorization/capability.classifier.ts

@@ -22,6 +22,11 @@ interface IProviderMapping {
 const STATIC_CAPABILITIES: Readonly<Record<string, string>> = {
     "resources/list": "mcp.resources.read",
     "resources/read": "mcp.resources.read",
+    "resources/templates/list": "mcp.resources.read",
+    // Subscribing is reading over time. Unsubscribing is deliberately absent:
+    // an unclassified method is not refused, and a client whose grant was
+    // revoked must still be able to drop what it holds.
+    "resources/subscribe": "mcp.resources.read",
     "tools/list": "mcp.tools.list",
     "prompts/list": "mcp.prompts.read",
     "prompts/get": "mcp.prompts.read",
@@ -34,6 +39,14 @@ const STATIC_CAPABILITIES: Readonly<Record<string, string>> = {
 
 const BROKER_READ_TOOLS = new Set(["broker_info", "providers_list", "provider_status"]);
 
+/**
+ * Methods that only read broker state. On `_broker` they all need
+ * `broker.providers.read`, the capability its tools need, rather than the
+ * generic `mcp.resources.read`: otherwise a caller could read the list and
+ * not subscribe to it, or the reverse.
+ */
+const BROKER_READ_METHODS = new Set(["tools/list", "resources/list", "resources/read", "resources/templates/list", "resources/subscribe", "notifications/resources/updated"]);
+
 function toolNameFrom(params: unknown): string | undefined {
     if (typeof params !== "object" || params === null || Array.isArray(params)) return undefined;
     const name = (params as Readonly<Record<string, unknown>>)["name"];
@@ -80,7 +93,7 @@ export class ConfiguredCapabilityClassifier implements ICapabilityClassifier {
         if (!method) return undefined;
 
         if (provider === "_broker") {
-            if (method === "tools/list" || method === "resources/list" || method === "resources/read") {
+            if (BROKER_READ_METHODS.has(method)) {
                 return { capability: "broker.providers.read" };
             }
             if (method === "tools/call") {

package/src/bin.ts

@@ -176,6 +176,9 @@ envFromConfig("MCP_BROKER_SSE_PATH", config.paths?.sse);
 envFromConfig("MCP_BROKER_MESSAGES_PATH", config.paths?.messages);
 envFromConfig("MCP_BROKER_PROVIDER_HEARTBEAT_MS", config.providerHeartbeatIntervalMs);
 envFromConfig("MCP_BROKER_PROVIDER_REQUEST_TIMEOUT_MS", config.providerRequestTimeoutMs);
+envFromConfig("MCP_BROKER_MAX_SUBSCRIPTIONS_PER_CLIENT", config.resourceSubscriptions?.maxSubscriptionsPerClient);
+envFromConfig("MCP_BROKER_MAX_SUBSCRIPTIONS_PER_SLOT", config.resourceSubscriptions?.maxSubscriptionsPerSlot);
+envFromConfig("MCP_BROKER_MAX_RESOURCE_URI_LENGTH", config.resourceSubscriptions?.maxResourceUriLength);
 envFromConfig("MCP_BROKER_PROVIDER_TAKEOVER", config.providerTakeover);
 // `www.open` is `boolean | string`: `true` means the root, a string is a path
 // or a same-origin URL. Both travel as the env string and are resolved once,
@@ -253,6 +256,24 @@ function millisFromEnv(envName: string): number | undefined {
 const providerHeartbeatIntervalMs = millisFromEnv("MCP_BROKER_PROVIDER_HEARTBEAT_MS");
 const providerRequestTimeoutMs = millisFromEnv("MCP_BROKER_PROVIDER_REQUEST_TIMEOUT_MS");
 
+/** Reads a positive whole number from the environment, or `undefined` (with a warning) for anything else. */
+function countFromEnv(envName: string): number | undefined {
+    const raw = process.env[envName];
+    if (raw === undefined || raw.trim() === "") return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value < 1) {
+        console.warn(`[mcp-broker] Ignoring ${envName}="${raw}": expected a whole number of at least 1. Using the default.`);
+        return undefined;
+    }
+    return value;
+}
+
+const resourceSubscriptionLimits = {
+    maxSubscriptionsPerClient: countFromEnv("MCP_BROKER_MAX_SUBSCRIPTIONS_PER_CLIENT"),
+    maxSubscriptionsPerSlot: countFromEnv("MCP_BROKER_MAX_SUBSCRIPTIONS_PER_SLOT"),
+    maxResourceUriLength: countFromEnv("MCP_BROKER_MAX_RESOURCE_URI_LENGTH"),
+};
+
 const takeoverRaw = process.env["MCP_BROKER_PROVIDER_TAKEOVER"]?.trim().toLowerCase();
 let providerTakeover: ProviderTakeoverMode | undefined;
 if (takeoverRaw) {
@@ -367,6 +388,11 @@ async function main(): Promise<void> {
     if (providerRequestTimeoutMs !== undefined) {
         builder.withProviderRequestTimeout(providerRequestTimeoutMs);
     }
+    // Only the limits actually set: an `undefined` field would override the default.
+    const limits = Object.fromEntries(Object.entries(resourceSubscriptionLimits).filter(([, v]) => v !== undefined));
+    if (Object.keys(limits).length > 0) {
+        builder.withResourceSubscriptionLimits(limits);
+    }
     if (providerTakeover) {
         builder.withProviderTakeover(providerTakeover);
     }

package/src/broker/adapters/broker.adapter.providers.ts

@@ -8,6 +8,15 @@ export const PROVIDERS_URI = "broker://providers";
 /** RFC 6570 URI template for one specific provider slot. */
 export const PROVIDER_URI_TEMPLATE = "broker://providers/{name}";
 
+/**
+ * The URI of one slot's resource, as the `broker://providers/{name}` template
+ * expands it. The name is percent-encoded, so a slot such as `a/b` is
+ * `broker://providers/a%2Fb`; a subscription must use that exact string.
+ */
+export function providerUri(name: string): string {
+    return `broker://providers/${encodeURIComponent(name)}`;
+}
+
 /**
  * Adapter that exposes the broker's current provider slots, both as a list
  * (read of `broker://providers`) and individually (`broker://providers/<name>`).
@@ -15,6 +24,15 @@ export const PROVIDER_URI_TEMPLATE = "broker://providers/{name}";
 export class BrokerProvidersAdapter extends McpAdapterBase {
     constructor(private readonly _context: IBrokerContext) {
         super("broker");
+
+        // Each batch of slot changes updates the list once, and each slot's
+        // own resource once. The server delivers them only to a session that
+        // subscribed to that exact URI.
+        _context.onProvidersChanged?.subscribe((names) => {
+            if (names.length === 0) return;
+            this._forwardResourceContentChanged(PROVIDERS_URI);
+            for (const name of new Set(names)) this._forwardResourceContentChanged(providerUri(name));
+        });
     }
 
     public async readResourceAsync(uri: string): Promise<McpResourceContent | undefined> {

package/src/broker/aggregate/aggregate.server.ts

@@ -68,6 +68,12 @@ export class AggregateServer implements IMessageTransport {
     onClose: (() => void) | null = null;
     onError: ((error: Error) => void) | null = null;
 
+    /**
+     * Called with a slot name whenever it joins or leaves the aggregate, so the
+     * broker can announce the change on `broker://providers`.
+     */
+    onMembershipChanged: ((name: string) => void) | null = null;
+
     constructor(openClient: InternalClientFactory) {
         this._openClient = openClient;
     }
@@ -139,6 +145,7 @@ export class AggregateServer implements IMessageTransport {
 
         const session = new ProviderClientSession(name, this._openClient(name));
         this._sessions.set(name, session);
+        this.onMembershipChanged?.(name);
 
         session.onCatalogChanged = (): void => {
             this._catalog.setProvider(name, { tools: session.tools, prompts: session.prompts });
@@ -181,6 +188,7 @@ export class AggregateServer implements IMessageTransport {
         session.close();
         this._catalog.removeProvider(name);
         this._emitListChanged();
+        this.onMembershipChanged?.(name);
     }
 
     private _subjectFor(principal: IPrincipal | null): IAuthorizationSubject {

package/src/broker/behaviors/broker.behavior.info.ts

@@ -1,5 +1,5 @@
 import { McpBehavior } from "@cyanmycelium/mcp-core";
-import type { McpResource, McpTool } from "@cyanmycelium/mcp-core";
+import type { McpResource, McpResourceContent, McpTool } from "@cyanmycelium/mcp-core";
 import { BROKER_INFO_URI, BrokerInfoAdapter } from "../adapters/broker.adapter.info";
 import { brokerBaselineResourceDescription, brokerBaselineResourceName, brokerBaselineToolDescription } from "../broker.grammars";
 import type { IBrokerContext } from "../broker.context";
@@ -19,6 +19,15 @@ export class BrokerInfoBehavior extends McpBehavior {
         });
     }
 
+    /**
+     * Always reads live. `McpBehavior` caches the content of its root
+     * resource on first read and never refreshes it, which suits static
+     * content but froze this snapshot at whatever the first reader saw.
+     */
+    public override readResourceAsync(uri: string): Promise<McpResourceContent | undefined> {
+        return this.adapter.readResourceAsync(uri);
+    }
+
     protected override _buildResources(): McpResource[] {
         return [
             {

package/src/broker/behaviors/broker.behavior.providers.ts

@@ -1,5 +1,5 @@
 import { McpBehavior } from "@cyanmycelium/mcp-core";
-import type { McpResource, McpResourceTemplate, McpTool } from "@cyanmycelium/mcp-core";
+import type { McpResource, McpResourceContent, McpResourceTemplate, McpTool } from "@cyanmycelium/mcp-core";
 import { BrokerProvidersAdapter, PROVIDERS_URI, PROVIDER_URI_TEMPLATE } from "../adapters/broker.adapter.providers";
 import {
     brokerBaselinePropertyDescription,
@@ -29,6 +29,15 @@ export class BrokerProvidersBehavior extends McpBehavior {
         });
     }
 
+    /**
+     * Always reads live. `McpBehavior` caches the content of its root
+     * resource on first read and never refreshes it, which suits static
+     * content but froze this snapshot at whatever the first reader saw.
+     */
+    public override readResourceAsync(uri: string): Promise<McpResourceContent | undefined> {
+        return this.adapter.readResourceAsync(uri);
+    }
+
     protected override _buildResources(): McpResource[] {
         return [
             {

package/src/broker/broker.context.ts

@@ -1,3 +1,5 @@
+import type { IEventSource } from "@cyanmycelium/mcp-core";
+
 /**
  * Read-only view of the broker's runtime state, exposed to broker behaviors.
  *
@@ -76,6 +78,19 @@ export interface IBrokerContext {
      * a slot that cannot exist at host start.
      */
     getStdioBridgeTarget?(): string | null | undefined;
+
+    /**
+     * Fires with the names of the slots whose *state* changed: a slot
+     * appeared, a provider attached or detached, a slot joined or left `_all`.
+     * Changes in the same tick arrive as one batch.
+     *
+     * Counters (`pendingCount`, `clientCount`, `sessionCount`) deliberately do
+     * not fire it: reading a resource moves them, so notifying on them would
+     * make every read trigger the next notification. They stay readable on
+     * demand. `_broker` turns this into `notifications/resources/updated` on
+     * `broker://providers` and `broker://providers/<name>`.
+     */
+    readonly onProvidersChanged?: IEventSource<readonly string[]>;
 }
 
 /**
@@ -159,6 +174,14 @@ export interface IBrokerProviderInfo {
 
     /** Number of in-flight JSON-RPC requests awaiting a response. */
     pendingCount: number;
+
+    /**
+     * Client/URI pairs held by `resources/subscribe` on this slot. A number
+     * that only grows is the signature of Streamable HTTP clients leaving
+     * without `DELETE`: their sessions, and so their subscriptions, never
+     * expire. Optional so hand-written contexts keep compiling.
+     */
+    resourceSubscriptionCount?: number;
 }
 
 /** @deprecated Use {@link IBrokerContext}. */