@tmcp/session-manager 0.2.1 → 0.3.0-next.0

package/README.md

@@ -10,10 +10,11 @@ pnpm add @tmcp/session-manager
 
 ## Overview
 
-Session management is split into two concerns:
+Session management is split into three concerns:
 
 - **Stream session managers** handle the storage of long-lived streaming connections (SSE/HTTP) and the fan-out of notifications back to the right session.
 - **Info session managers** persist metadata that MCP transports need across requests, such as client capabilities, client info, requested log level, and resource subscriptions.
+- **Subscription managers** route MCP `2026-07-28` per-request change notifications to long-lived `subscriptions/listen` streams.
 
 Together they manage:
 
@@ -23,6 +24,7 @@ Together they manage:
 - **Message Delivery**: Sending messages to specific sessions or everyone
 - **Client Metadata**: Persisting capabilities, `clientInfo`, and log level between requests
 - **Resource Subscriptions**: Tracking which sessions subscribed to which URIs
+- **Per-Request Subscriptions**: Acknowledging, filtering, ordering, and closing sessionless notification streams
 
 ## Usage
 
@@ -42,6 +44,8 @@ const sessionManagers = {
 };
 ```
 
+`InMemorySubscriptionManager` is the default for transports that support the per-request protocol. It preserves JSON-RPC ID types, buffers changes until acknowledgement completes, and serializes delivery per subscription.
+
 ### Custom Session Managers
 
 You can implement your own managers by extending the base classes that ship with this package.
@@ -108,6 +112,10 @@ class CustomInfoSessionManager extends InfoSessionManager {
 		// Track that the session subscribed to the URI
 	}
 
+	removeSubscription(id, uri) {
+		// Stop tracking this resource subscription
+	}
+
 	delete(id) {
 		// Remove all metadata for the session (client info, capabilities, subscriptions, etc.)
 	}
@@ -116,6 +124,17 @@ class CustomInfoSessionManager extends InfoSessionManager {
 
 ## API
 
+### `SubscriptionManager` (Abstract Base Class)
+
+Transport-owned manager for `subscriptions/listen` registrations.
+
+- `create(subscription, callbacks)` – atomically register `{ id, origin, filters }` and acknowledge before delivering buffered changes
+- `send(notification)` – route one change to every matching registration
+- `close(id, origin, reason)` – close one registration without conflating numeric and string IDs
+- `closeAll(origin?, reason?)` – close all registrations, optionally for one transport origin
+
+Only the descriptor is suitable for persistence. Callback functions remain on the instance serving the response stream; distributed implementations should use pub/sub only to fan notifications out to that instance. Registration and closure stay local to the process that owns the response stream.
+
 ### `StreamSessionManager` (Abstract Base Class)
 
 Responsible for creating and managing streaming controllers.
@@ -134,6 +153,7 @@ Stores session metadata that needs to survive across HTTP requests or reconnects
 - `getLogLevel(id)` / `setLogLevel(id, level)`
 - `getSubscriptions(uri)` – return all session IDs that subscribed to a resource
 - `addSubscription(id, uri)` – record a new resource subscription
+- `removeSubscription(id, uri)` – remove one resource subscription
 - `delete(id)` – remove all metadata for a session when it disconnects
 
 ### `InMemoryStreamSessionManager` & `InMemoryInfoSessionManager`
@@ -153,8 +173,12 @@ const sessionManagers = {
 	info: new InMemoryInfoSessionManager(),
 };
 
-const httpTransport = new HttpTransport(server, { sessionManager: sessionManagers });
-const sseTransport = new SseTransport(server, { sessionManager: sessionManagers });
+const httpTransport = new HttpTransport(server, {
+	sessionManager: sessionManagers,
+});
+const sseTransport = new SseTransport(server, {
+	sessionManager: sessionManagers,
+});
 ```
 
 ## Related Packages

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@tmcp/session-manager",
-  "version": "0.2.1",
+  "version": "0.3.0-next.0",
+  "license": "MIT",
   "description": "",
   "main": "src/index.js",
+  "files": [
+    "src/"
+  ],
   "repository": {
     "type": "git",
     "url": "git+https://github.com/paoloricciuti/tmcp.git",
@@ -24,7 +28,7 @@
   },
   "type": "module",
   "peerDependencies": {
-    "tmcp": "^1.16.3"
+    "tmcp": "^1.20.0-next.0 || ^1.20.0"
   },
   "publishConfig": {
     "access": "public"
@@ -32,10 +36,16 @@
   "devDependencies": {
     "dts-buddy": "^0.6.2",
     "publint": "^0.3.12",
+    "vitest": "^4.0.0",
+    "tmcp": "^1.20.0-next.0",
     "@tmcp/internal-ts-helpers": "^1.0.0"
   },
+  "dependencies": {
+    "json-rpc-2.0": "^1.7.1"
+  },
   "scripts": {
     "generate:types": "dts-buddy && node scripts/abstractify.js && publint",
-    "prepublish": "pnpm generate:types"
+    "prepublish": "pnpm generate:types",
+    "test": "vitest --run"
   }
 }

package/src/index.js

@@ -1,9 +1,255 @@
 /* eslint-disable no-unused-vars */
 
 /**
- * @import { Context } from "tmcp";
+ * @import { Context, SubscriptionFilter } from "tmcp";
+ * @import { JSONRPCRequest } from "json-rpc-2.0";
  */
 
+/**
+ * @typedef {{ id: string | number, origin: string, filters: SubscriptionFilter }} Subscription
+ * @typedef {{ acknowledge: () => void | Promise<void>, send: (notification: JSONRPCRequest) => void | Promise<void>, close: (reason: 'closed' | 'cancelled') => void | Promise<void> }} SubscriptionCallbacks
+ */
+
+/**
+ * Determine whether a notification belongs on a subscription stream.
+ * Distributed managers can use this directly or maintain equivalent indexes.
+ * @param {SubscriptionFilter} filters
+ * @param {JSONRPCRequest} notification
+ */
+export function matchesSubscription(filters, notification) {
+	if (notification.method === 'notifications/tools/list_changed') {
+		return filters.toolsListChanged === true;
+	}
+	if (notification.method === 'notifications/prompts/list_changed') {
+		return filters.promptsListChanged === true;
+	}
+	if (notification.method === 'notifications/resources/list_changed') {
+		return filters.resourcesListChanged === true;
+	}
+	if (notification.method === 'notifications/resources/updated') {
+		const uri = /** @type {Record<string, unknown> | undefined} */ (
+			notification.params
+		)?.uri;
+		return (
+			typeof uri === 'string' &&
+			filters.resourceSubscriptions?.includes(uri) === true
+		);
+	}
+	return false;
+}
+
+/**
+ * Routes notifications to long-lived per-request subscription streams.
+ * Callbacks remain local to the process serving the response stream. Brokered
+ * implementations can distribute notifications without persisting descriptors.
+ * @abstract
+ */
+export class SubscriptionManager {
+	/**
+	 * @abstract
+	 * Atomically register a subscription. Matching notifications must be
+	 * buffered until acknowledgement completes and then delivered in order.
+	 * @param {Subscription} subscription
+	 * @param {SubscriptionCallbacks} callbacks
+	 * @returns {boolean | Promise<boolean>}
+	 */
+	create(subscription, callbacks) {
+		void subscription;
+		void callbacks;
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {JSONRPCRequest} notification
+	 * @returns {void | Promise<void>}
+	 */
+	send(notification) {
+		void notification;
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * Request closure of one subscription. Implementations must preserve the
+	 * JSON-RPC ID type when identifying a registration.
+	 * @param {string | number} id
+	 * @param {string} origin
+	 * @param {'closed' | 'cancelled'} reason
+	 * @returns {boolean | Promise<boolean>}
+	 */
+	close(id, origin, reason) {
+		void id;
+		void origin;
+		void reason;
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * Close every subscription, optionally limited to one transport origin.
+	 * @param {string} [origin]
+	 * @param {'closed' | 'cancelled'} [reason]
+	 * @returns {void | Promise<void>}
+	 */
+	closeAll(origin, reason = 'cancelled') {
+		void origin;
+		void reason;
+		throw new Error('Method not implemented.');
+	}
+}
+
+/**
+ * Process-local subscription manager. Distributed implementations should
+ * mirror its acknowledgement buffering and per-subscription ordering.
+ */
+export class InMemorySubscriptionManager extends SubscriptionManager {
+	/** @type {Map<string, Map<string | number, { subscription: Subscription, callbacks: SubscriptionCallbacks, queue: Promise<'active' | 'failed'>, close_promise?: Promise<boolean> }>>} */
+	#subscriptions = new Map();
+
+	/**
+	 * @param {{ subscription: Subscription, callbacks: SubscriptionCallbacks, queue: Promise<'active' | 'failed'>, close_promise?: Promise<boolean> }} record
+	 * @param {JSONRPCRequest} notification
+	 */
+	#enqueue(record, notification) {
+		const delivery = record.queue.then(async (state) => {
+			if (state === 'failed' || record.close_promise) return state;
+			await record.callbacks.send(notification);
+			return /** @type {const} */ ('active');
+		});
+		// A failed send rejects its caller without poisoning later queue entries.
+		record.queue = delivery.catch(() => 'active');
+		return delivery.then(() => {});
+	}
+
+	/**
+	 * @param {Subscription} subscription
+	 * @param {SubscriptionCallbacks} callbacks
+	 * @returns {Promise<boolean>}
+	 */
+	async create(subscription, callbacks) {
+		let subscriptions = this.#subscriptions.get(subscription.origin);
+		if (!subscriptions) {
+			subscriptions = new Map();
+			this.#subscriptions.set(subscription.origin, subscriptions);
+		}
+		if (subscriptions.has(subscription.id)) return false;
+		/** @type {(value?: void) => void} */
+		let resolve_acknowledgement = () => {};
+		/** @type {(reason?: unknown) => void} */
+		let reject_acknowledgement = () => {};
+		const acknowledge_promise = new Promise((resolve, reject) => {
+			resolve_acknowledgement = resolve;
+			reject_acknowledgement = reject;
+		});
+		/** @type {{ subscription: Subscription, callbacks: SubscriptionCallbacks, queue: Promise<'active' | 'failed'>, close_promise?: Promise<boolean> }} */
+		const record = {
+			subscription,
+			callbacks,
+			// Starting behind acknowledgement replaces both active and pending state.
+			queue: acknowledge_promise.then(
+				() => /** @type {const} */ ('active'),
+				() => /** @type {const} */ ('failed'),
+			),
+		};
+		subscriptions.set(subscription.id, record);
+		try {
+			Promise.resolve(callbacks.acknowledge()).then(
+				resolve_acknowledgement,
+				reject_acknowledgement,
+			);
+		} catch (error) {
+			reject_acknowledgement(error);
+		}
+		try {
+			await acknowledge_promise;
+			if (record.close_promise) return true;
+			await record.queue;
+			return true;
+		} catch (error) {
+			if (!record.close_promise) {
+				subscriptions.delete(subscription.id);
+				if (subscriptions.size === 0) {
+					this.#subscriptions.delete(subscription.origin);
+				}
+			}
+			throw error;
+		}
+	}
+
+	/**
+	 * @param {JSONRPCRequest} notification
+	 * @returns {Promise<void>}
+	 */
+	async send(notification) {
+		/** @type {Promise<void>[]} */
+		const deliveries = [];
+		for (const subscriptions of this.#subscriptions.values()) {
+			for (const record of subscriptions.values()) {
+				if (
+					record.close_promise ||
+					!matchesSubscription(
+						record.subscription.filters,
+						notification,
+					)
+				) {
+					continue;
+				}
+				deliveries.push(this.#enqueue(record, notification));
+			}
+		}
+		await Promise.all(deliveries);
+	}
+
+	/**
+	 * @param {string | number} id
+	 * @param {string} origin
+	 * @param {'closed' | 'cancelled'} reason
+	 * @returns {Promise<boolean>}
+	 */
+	async close(id, origin, reason) {
+		const subscriptions = this.#subscriptions.get(origin);
+		if (!subscriptions) return false;
+		const record = subscriptions.get(id);
+		if (!record) return false;
+		if (record.close_promise) return record.close_promise;
+
+		record.close_promise = (async () => {
+			try {
+				await record.queue;
+				await record.callbacks.close(reason);
+				return true;
+			} finally {
+				if (subscriptions.get(id) === record) subscriptions.delete(id);
+				if (subscriptions.size === 0)
+					this.#subscriptions.delete(origin);
+			}
+		})();
+		return record.close_promise;
+	}
+
+	/**
+	 * @param {string} [origin]
+	 * @param {'closed' | 'cancelled'} [reason]
+	 * @returns {Promise<void>}
+	 */
+	async closeAll(origin, reason = 'cancelled') {
+		/** @type {Array<[string | number, string]>} */
+		const registrations = [];
+		for (const [stored_origin, subscriptions] of this.#subscriptions) {
+			if (origin !== undefined && stored_origin !== origin) continue;
+			for (const id of subscriptions.keys()) {
+				registrations.push([id, stored_origin]);
+			}
+		}
+		await Promise.all(
+			registrations.map(([id, stored_origin]) =>
+				this.close(id, stored_origin, reason),
+			),
+		);
+	}
+}
+
 /**
  * @abstract
  */
@@ -92,7 +338,11 @@ export class InMemoryStreamSessionManager extends StreamSessionManager {
 	send(sessions, data) {
 		for (const [id, controller] of this.#sessions.entries()) {
 			if (sessions == null || sessions.includes(id)) {
-				controller.enqueue(this.#text_encoder.encode(data));
+				try {
+					controller.enqueue(this.#text_encoder.encode(data));
+				} catch {
+					this.#sessions.delete(id);
+				}
 			}
 		}
 	}
@@ -301,7 +551,10 @@ export class InMemoryInfoSessionManager extends InfoSessionManager {
 	 * @type {InfoSessionManager["delete"]}
 	 */
 	delete(id) {
-		this.#subscriptions.delete(id);
+		for (const [uri, subscriptions] of this.#subscriptions) {
+			subscriptions.delete(id);
+			if (subscriptions.size === 0) this.#subscriptions.delete(uri);
+		}
 		this.#log_level.delete(id);
 		this.#client_capabilities.delete(id);
 		this.#client_info.delete(id);

package/src/types/index.d.ts

@@ -1,8 +1,55 @@
 declare module '@tmcp/session-manager' {
-    import type { Context } from 'tmcp';
+    import type { SubscriptionFilter, Context } from 'tmcp';
+    import type { JSONRPCRequest } from 'json-rpc-2.0';
     /**
-     * @import { Context } from "tmcp";
+     * @import { Context, SubscriptionFilter } from "tmcp";
+     * @import { JSONRPCRequest } from "json-rpc-2.0";
      */
+    /**
+     * Determine whether a notification belongs on a subscription stream.
+     * Distributed managers can use this directly or maintain equivalent indexes.
+     * */
+    export function matchesSubscription(filters: SubscriptionFilter, notification: JSONRPCRequest): boolean;
+    /**
+     * Routes notifications to long-lived per-request subscription streams.
+     * Callbacks remain local to the process serving the response stream. Brokered
+     * implementations can distribute notifications without persisting descriptors.
+     * @abstract
+     */
+    export abstract class SubscriptionManager {
+        /**
+         * @abstract
+         * Atomically register a subscription. Matching notifications must be
+         * buffered until acknowledgement completes and then delivered in order.
+         * */
+        abstract create(subscription: Subscription, callbacks: SubscriptionCallbacks): boolean | Promise<boolean>;
+        /**
+         * @abstract
+         * */
+        abstract send(notification: JSONRPCRequest): void | Promise<void>;
+        /**
+         * @abstract
+         * Request closure of one subscription. Implementations must preserve the
+         * JSON-RPC ID type when identifying a registration.
+         * */
+        abstract close(id: string | number, origin: string, reason: "closed" | "cancelled"): boolean | Promise<boolean>;
+        /**
+         * @abstract
+         * Close every subscription, optionally limited to one transport origin.
+         * */
+        abstract closeAll(origin?: string, reason?: "closed" | "cancelled"): void | Promise<void>;
+    }
+    /**
+     * Process-local subscription manager. Distributed implementations should
+     * mirror its acknowledgement buffering and per-subscription ordering.
+     */
+    export class InMemorySubscriptionManager extends SubscriptionManager {
+        create(subscription: Subscription, callbacks: SubscriptionCallbacks): Promise<boolean>;
+        send(notification: JSONRPCRequest): Promise<void>;
+        close(id: string | number, origin: string, reason: "closed" | "cancelled"): Promise<boolean>;
+        closeAll(origin?: string, reason?: "closed" | "cancelled"): Promise<void>;
+        #private;
+    }
     /**
      * @abstract
      */
@@ -79,6 +126,16 @@ declare module '@tmcp/session-manager' {
     export class InMemoryInfoSessionManager extends InfoSessionManager {
         #private;
     }
+    export type Subscription = {
+        id: string | number;
+        origin: string;
+        filters: SubscriptionFilter;
+    };
+    export type SubscriptionCallbacks = {
+        acknowledge: () => void | Promise<void>;
+        send: (notification: JSONRPCRequest) => void | Promise<void>;
+        close: (reason: "closed" | "cancelled") => void | Promise<void>;
+    };
     export {};
 }
 //# sourceMappingURL=index.d.ts.map

package/src/types/index.d.ts.map

@@ -2,10 +2,15 @@
 	"version": 3,
 	"file": "index.d.ts",
 	"names": [
+		"matchesSubscription",
+		"SubscriptionManager",
+		"InMemorySubscriptionManager",
 		"StreamSessionManager",
 		"InMemoryStreamSessionManager",
 		"InfoSessionManager",
-		"InMemoryInfoSessionManager"
+		"InMemoryInfoSessionManager",
+		"Subscription",
+		"SubscriptionCallbacks"
 	],
 	"sources": [
 		"../index.js"
@@ -13,6 +18,6 @@
 	"sourcesContent": [
 		null
 	],
-	"mappings": ";;;;;;;;cASaA,oBAAoBA;;;;;;;;;;;;;;;;;;cAwCpBC,4BAA4BA;;;;;;;;;;;;;;cAsD5BC,kBAAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2FlBC,0BAA0BA",
+	"mappings": ";;;;;;;;;;;;iBAkBgBA,mBAAmBA;;;;;;;cA4BtBC,mBAAmBA;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2DnBC,2BAA2BA;;;;;;;;;;;;;;cAsJ3BC,oBAAoBA;;;;;;;;;;;;;;;;;;cAwCpBC,4BAA4BA;;;;;;;;;;;;;;cA0D5BC,kBAAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2FlBC,0BAA0BA;;;aApb4CC,YAAYA;;;;;aAC0FC,qBAAqBA",
 	"ignoreList": []
 }

package/CHANGELOG.md

@@ -1,43 +0,0 @@
-# @tmcp/session-manager
-
-## 0.2.1
-
-### Patch Changes
-
-- 5613d43: fix: handle `resources/unsubscribe`
-- Updated dependencies [5613d43]
-    - tmcp@1.16.3
-
-## 0.2.0
-
-### Minor Changes
-
-- 8a04ee2: breaking: move sessions out of core into the transports and allow for persistent mcp state
-
-    This release moves the session management out of the core package into the SSE and HTTP transport separately.
-    While technically a breaking change if you update both `tmcp` and your transport (`@tmcp/transport-http`,
-    `@tmcp/transport-sse`, or `@tmcp/transport-stdio`), you will not face a breaking change unless you were using a
-    session manager.
-
-    If you were testing your `McpServer` instance manually you might need to update them to pass the `sessionInfo`
-    in the context parameter (only if you were reading them in the tool/resource/prompt).
-
-    Sorry for the "breaking" but this was a necessary step to unlock persistent state. 🧡
-
-### Patch Changes
-
-- Updated dependencies [8a04ee2]
-- Updated dependencies [a9254cb]
-    - tmcp@1.16.0
-
-## 0.1.2
-
-### Patch Changes
-
-- c0f7d7f: fix: try catch closing controller in case it's already closed
-
-## 0.1.1
-
-### Patch Changes
-
-- 957805b: fix: await session manager calls

package/scripts/abstractify.js

@@ -1,3 +0,0 @@
-import { abstractify } from '@tmcp/internal-ts-helpers';
-
-abstractify();

package/tsconfig.json

@@ -1,16 +0,0 @@
-{
-	"compilerOptions": {
-		"target": "esnext",
-		"module": "nodenext",
-		"moduleResolution": "nodenext",
-		"allowJs": true,
-		"checkJs": true,
-		"declaration": true,
-		"emitDeclarationOnly": false,
-		"strict": true,
-		"noEmit": true,
-		"skipLibCheck": true
-	},
-	"include": ["src/**/*"],
-	"exclude": ["node_modules"]
-}