@tmcp/session-manager 0.1.1 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @tmcp/session-manager
 
+## 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

package/README.md

@@ -1,6 +1,6 @@
 # @tmcp/session-manager
 
-Session management for TMCP (TypeScript Model Context Protocol) transport implementations. This package provides the base `SessionManager` interface and an in-memory implementation for managing client sessions in MCP servers.
+Session management for TMCP (TypeScript Model Context Protocol) transport implementations. This package provides the base classes and in-memory implementations for both streaming session coordination and session metadata persistence.
 
 ## Installation
 
@@ -10,132 +10,151 @@ pnpm add @tmcp/session-manager
 
 ## Overview
 
-Session managers handle the storage and communication with client sessions in TMCP transport layers. They manage:
+Session management is split into two 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.
+
+Together they manage:
 
 - **Session Creation**: Establishing new client sessions with stream controllers
-- **Session Deletion**: Cleaning up disconnected sessions
-- **Session Queries**: Checking if sessions exist
-- **Message Broadcasting**: Sending messages to specific sessions or all sessions
+- **Session Deletion**: Cleaning up disconnected sessions and metadata
+- **Session Queries**: Checking whether a given session is still attached
+- **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
 
 ## Usage
 
-### In-Memory Session Manager (Default)
+### In-Memory Session Managers (Default)
 
-The `InMemorySessionManager` stores sessions in memory and is suitable for single-server deployments:
+The package ships with `InMemoryStreamSessionManager` and `InMemoryInfoSessionManager`. Together they are suitable for single-server deployments or tests:
 
 ```javascript
-import { InMemorySessionManager } from '@tmcp/session-manager';
-
-const sessionManager = new InMemorySessionManager();
+import {
+	InMemoryStreamSessionManager,
+	InMemoryInfoSessionManager,
+} from '@tmcp/session-manager';
+
+const sessionManagers = {
+	streams: new InMemoryStreamSessionManager(),
+	info: new InMemoryInfoSessionManager(),
+};
 ```
 
-### Custom Session Manager
+### Custom Session Managers
+
+You can implement your own managers by extending the base classes that ship with this package.
 
-You can implement your own session manager by extending the base `SessionManager` class:
+#### Stream session manager
 
 ```javascript
-import { SessionManager } from '@tmcp/session-manager';
-
-class CustomSessionManager extends SessionManager {
-	/**
-	 * Create a new session with the given ID and controller
-	 * @param {string} id - Session ID
-	 * @param {ReadableStreamDefaultController} controller - Stream controller
-	 */
+import { StreamSessionManager } from '@tmcp/session-manager';
+
+class CustomStreamSessionManager extends StreamSessionManager {
 	create(id, controller) {
-		// Implementation here
+		// Persist the ReadableStream controller for later notifications
 	}
 
-	/**
-	 * Delete a session by ID
-	 * @param {string} id - Session ID to delete
-	 */
 	delete(id) {
-		// Implementation here
+		// Clean up the controller and any associated timers
 	}
 
-	/**
-	 * Check if a session exists
-	 * @param {string} id - Session ID to check
-	 * @returns {Promise<boolean>} - Whether the session exists
-	 */
 	async has(id) {
-		// Implementation here
+		// Return whether a controller for the session exists
 	}
 
-	/**
-	 * Send data to specific sessions or all sessions
-	 * @param {string[] | undefined} sessions - Session IDs to send to (undefined = all sessions)
-	 * @param {string} data - Data to send
-	 */
 	send(sessions, data) {
-		// Implementation here
+		// Fan out the payload to the targeted sessions (or everyone if sessions is undefined)
 	}
 }
 ```
 
-## API
-
-### `SessionManager` (Abstract Base Class)
+#### Info session manager
 
-#### Methods
-
-##### `create(id: string, controller: ReadableStreamDefaultController): void`
-
-Creates a new session with the specified ID and associates it with a stream controller.
-
-**Parameters:**
+```javascript
+import { InfoSessionManager } from '@tmcp/session-manager';
 
-- `id` - Unique session identifier
-- `controller` - ReadableStreamDefaultController for sending data to the client
+class CustomInfoSessionManager extends InfoSessionManager {
+	async getClientInfo(id) {
+		// Return the last clientInfo payload for the session
+	}
 
-##### `delete(id: string): void`
+	setClientInfo(id, info) {
+		// Persist clientInfo for later requests
+	}
 
-Removes a session and cleans up its resources.
+	async getClientCapabilities(id) {
+		// Retrieve cached client capabilities
+	}
 
-**Parameters:**
+	setClientCapabilities(id, capabilities) {
+		// Persist the negotiated capabilities
+	}
 
-- `id` - Session ID to delete
+	async getLogLevel(id) {
+		// Return the log level requested by the client
+	}
 
-##### `has(id: string): Promise<boolean>`
+	setLogLevel(id, level) {
+		// Store the latest log level
+	}
 
-Checks whether a session with the given ID exists.
+	async getSubscriptions(uri) {
+		// Return all session ids subscribed to the URI
+	}
 
-**Parameters:**
+	addSubscription(id, uri) {
+		// Track that the session subscribed to the URI
+	}
 
-- `id` - Session ID to check
+	delete(id) {
+		// Remove all metadata for the session (client info, capabilities, subscriptions, etc.)
+	}
+}
+```
 
-**Returns:**
+## API
 
-- Promise resolving to true if the session exists, false otherwise
+### `StreamSessionManager` (Abstract Base Class)
 
-##### `send(sessions: string[] | undefined, data: string): void`
+Responsible for creating and managing streaming controllers.
 
-Sends data to one or more sessions.
+- `create(id, controller)` – register a session and associate its stream controller
+- `delete(id)` – remove the controller and clean up resources
+- `has(id)` – resolve to `true` when a controller for the session exists
+- `send(sessions, data)` – push a payload to selected sessions (or everyone when `sessions` is `undefined`)
 
-**Parameters:**
+### `InfoSessionManager` (Abstract Base Class)
 
-- `sessions` - Array of session IDs to send to, or undefined to send to all sessions
-- `data` - String data to send (typically SSE-formatted)
+Stores session metadata that needs to survive across HTTP requests or reconnects.
 
-### `InMemorySessionManager`
+- `getClientInfo(id)` / `setClientInfo(id, info)`
+- `getClientCapabilities(id)` / `setClientCapabilities(id, capabilities)`
+- `getLogLevel(id)` / `setLogLevel(id, level)`
+- `getSubscriptions(uri)` – return all session IDs that subscribed to a resource
+- `addSubscription(id, uri)` – record a new resource subscription
+- `delete(id)` – remove all metadata for a session when it disconnects
 
-Concrete implementation that stores sessions in a JavaScript Map. Suitable for single-server deployments.
+### `InMemoryStreamSessionManager` & `InMemoryInfoSessionManager`
 
-#### Usage with Transport Layers
+Concrete in-memory implementations that cover both responsibilities. Combine them when configuring a transport:
 
 ```javascript
 import { HttpTransport } from '@tmcp/transport-http';
 import { SseTransport } from '@tmcp/transport-sse';
-import { InMemorySessionManager } from '@tmcp/session-manager';
-
-const sessionManager = new InMemorySessionManager();
-
-// Use with HTTP transport
-const httpTransport = new HttpTransport(server, { sessionManager });
-
-// Use with SSE transport
-const sseTransport = new SseTransport(server, { sessionManager });
+import {
+	InMemoryStreamSessionManager,
+	InMemoryInfoSessionManager,
+} from '@tmcp/session-manager';
+
+const sessionManagers = {
+	streams: new InMemoryStreamSessionManager(),
+	info: new InMemoryInfoSessionManager(),
+};
+
+const httpTransport = new HttpTransport(server, { sessionManager: sessionManagers });
+const sseTransport = new SseTransport(server, { sessionManager: sessionManagers });
 ```
 
 ## Related Packages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tmcp/session-manager",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "",
   "main": "src/index.js",
   "repository": {
@@ -23,6 +23,9 @@
     }
   },
   "type": "module",
+  "peerDependencies": {
+    "tmcp": "^1.16.0"
+  },
   "publishConfig": {
     "access": "public"
   },

package/src/index.js

@@ -1,9 +1,13 @@
 /* eslint-disable no-unused-vars */
 
+/**
+ * @import { Context } from "tmcp";
+ */
+
 /**
  * @abstract
  */
-export class SessionManager {
+export class StreamSessionManager {
 	/**
 	 * @abstract
 	 * @param {string} id
@@ -43,7 +47,7 @@ export class SessionManager {
 	}
 }
 
-export class InMemorySessionManager extends SessionManager {
+export class InMemoryStreamSessionManager extends StreamSessionManager {
 	/**
 	 * @type {Map<string, ReadableStreamDefaultController>}
 	 */
@@ -64,13 +68,16 @@ export class InMemorySessionManager extends SessionManager {
 	delete(id) {
 		const controller = this.#sessions.get(id);
 		if (controller) {
-			controller.close();
 			this.#sessions.delete(id);
+			try {
+				controller.close();
+			} catch {
+				// could error if the controller is already closed
+			}
 		}
 	}
 
 	/**
-	 * @abstract
 	 * @param {string} id
 	 * @returns {Promise<boolean>}
 	 */
@@ -90,3 +97,194 @@ export class InMemorySessionManager extends SessionManager {
 		}
 	}
 }
+
+/**
+ * @abstract
+ */
+export class InfoSessionManager {
+	/**
+	 * @abstract
+	 * @param {string} id
+	 * @returns {Promise<NonNullable<Context["sessionInfo"]>["clientInfo"]>}
+	 */
+	getClientInfo(id) {
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {string} id
+	 * @param {NonNullable<Context["sessionInfo"]>["clientInfo"]} client_info
+	 */
+	setClientInfo(id, client_info) {
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {string} id
+	 * @returns {Promise<NonNullable<Context["sessionInfo"]>["clientCapabilities"]>}
+	 */
+	getClientCapabilities(id) {
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {string} id
+	 * @param {NonNullable<Context["sessionInfo"]>["clientCapabilities"]} client_capabilities
+	 */
+	setClientCapabilities(id, client_capabilities) {
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {string} id
+	 * @returns {Promise<NonNullable<Context["sessionInfo"]>["logLevel"]>}
+	 */
+	getLogLevel(id) {
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {string} id
+	 * @param {NonNullable<Context["sessionInfo"]>["logLevel"]} log_level
+	 */
+	setLogLevel(id, log_level) {
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {string} uri
+	 * @returns {Promise<string[]>}
+	 */
+	getSubscriptions(uri) {
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {string} id
+	 * @param {string} uri
+	 */
+	addSubscription(id, uri) {
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {string} id
+	 */
+	delete(id) {
+		throw new Error('Method not implemented.');
+	}
+}
+
+export class InMemoryInfoSessionManager extends InfoSessionManager {
+	/**
+	 * @type {Map<string, NonNullable<Context["sessionInfo"]>["clientInfo"]>}
+	 */
+	#client_info = new Map();
+	/**
+	 * @type {Map<string, NonNullable<Context["sessionInfo"]>["clientCapabilities"]>}
+	 */
+	#client_capabilities = new Map();
+	/**
+	 * @type {Map<string, NonNullable<Context["sessionInfo"]>["logLevel"]>}
+	 */
+	#log_level = new Map();
+	/**
+	 * @type {Map<string, Set<string>>}
+	 */
+	#subscriptions = new Map();
+
+	/**
+	 * @param {string} session
+	 * @param {string} name
+	 * @returns {Promise<never>}
+	 */
+	async #invariant(session, name) {
+		throw new Error(`${name} not found for session ${session}`);
+	}
+
+	/**
+	 * @type {InfoSessionManager["getClientInfo"]}
+	 */
+	getClientInfo(id) {
+		return Promise.resolve(
+			this.#client_info.get(id) ?? this.#invariant(id, 'Client info'),
+		);
+	}
+
+	/**
+	 * @type {InfoSessionManager["setClientInfo"]}
+	 */
+	setClientInfo(id, client_info) {
+		this.#client_info.set(id, client_info);
+	}
+
+	/**
+	 * @type {InfoSessionManager["getClientCapabilities"]}
+	 */
+	getClientCapabilities(id) {
+		return Promise.resolve(
+			this.#client_capabilities.get(id) ??
+				this.#invariant(id, 'Client capabilities'),
+		);
+	}
+
+	/**
+	 * @type {InfoSessionManager["setClientCapabilities"]}
+	 */
+	setClientCapabilities(id, client_capabilities) {
+		this.#client_capabilities.set(id, client_capabilities);
+	}
+
+	/**
+	 * @type {InfoSessionManager["getLogLevel"]}
+	 */
+	getLogLevel(id) {
+		return Promise.resolve(
+			this.#log_level.get(id) ?? this.#invariant(id, 'Log Level'),
+		);
+	}
+
+	/**
+	 * @type {InfoSessionManager["setLogLevel"]}
+	 */
+	setLogLevel(id, log_level) {
+		this.#log_level.set(id, log_level);
+	}
+
+	/**
+	 * @type {InfoSessionManager["getSubscriptions"]}
+	 */
+	getSubscriptions(uri) {
+		return Promise.resolve([...(this.#subscriptions.get(uri) ?? [])]);
+	}
+
+	/**
+	 * @type {InfoSessionManager["addSubscription"]}
+	 */
+	addSubscription(id, uri) {
+		let subscriptions = this.#subscriptions.get(uri);
+		if (!subscriptions) {
+			subscriptions = new Set();
+			this.#subscriptions.set(uri, subscriptions);
+		}
+		subscriptions.add(id);
+	}
+
+	/**
+	 * @type {InfoSessionManager["delete"]}
+	 */
+	delete(id) {
+		this.#subscriptions.delete(id);
+		this.#log_level.delete(id);
+		this.#client_capabilities.delete(id);
+		this.#client_info.delete(id);
+	}
+}

package/src/types/index.d.ts

@@ -1,8 +1,12 @@
 declare module '@tmcp/session-manager' {
+    import type { Context } from 'tmcp';
+    /**
+     * @import { Context } from "tmcp";
+     */
     /**
      * @abstract
      */
-    export abstract class SessionManager {
+    export abstract class StreamSessionManager {
         /**
          * @abstract
          * */
@@ -20,14 +24,55 @@ declare module '@tmcp/session-manager' {
          * */
         abstract send(sessions: string[] | undefined, data: string): void | Promise<void>;
     }
-    export class InMemorySessionManager extends SessionManager {
+    export class InMemoryStreamSessionManager extends StreamSessionManager {
         create(id: string, controller: ReadableStreamDefaultController): void;
         delete(id: string): void;
+        has(id: string): Promise<boolean>;
+        send(sessions: string[] | undefined, data: string): void;
+        #private;
+    }
+    /**
+     * @abstract
+     */
+    export abstract class InfoSessionManager {
         /**
          * @abstract
          * */
-        abstract has(id: string): Promise<boolean>;
-        send(sessions: string[] | undefined, data: string): void;
+        abstract getClientInfo(id: string): Promise<NonNullable<Context["sessionInfo"]>["clientInfo"]>;
+        /**
+         * @abstract
+         * */
+        abstract setClientInfo(id: string, client_info: NonNullable<Context["sessionInfo"]>["clientInfo"]): void;
+        /**
+         * @abstract
+         * */
+        abstract getClientCapabilities(id: string): Promise<NonNullable<Context["sessionInfo"]>["clientCapabilities"]>;
+        /**
+         * @abstract
+         * */
+        abstract setClientCapabilities(id: string, client_capabilities: NonNullable<Context["sessionInfo"]>["clientCapabilities"]): void;
+        /**
+         * @abstract
+         * */
+        abstract getLogLevel(id: string): Promise<NonNullable<Context["sessionInfo"]>["logLevel"]>;
+        /**
+         * @abstract
+         * */
+        abstract setLogLevel(id: string, log_level: NonNullable<Context["sessionInfo"]>["logLevel"]): void;
+        /**
+         * @abstract
+         * */
+        abstract getSubscriptions(uri: string): Promise<string[]>;
+        /**
+         * @abstract
+         * */
+        abstract addSubscription(id: string, uri: string): void;
+        /**
+         * @abstract
+         * */
+        abstract delete(id: string): void;
+    }
+    export class InMemoryInfoSessionManager extends InfoSessionManager {
         #private;
     }
     export {};

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

@@ -2,8 +2,10 @@
 	"version": 3,
 	"file": "index.d.ts",
 	"names": [
-		"SessionManager",
-		"InMemorySessionManager"
+		"StreamSessionManager",
+		"InMemoryStreamSessionManager",
+		"InfoSessionManager",
+		"InMemoryInfoSessionManager"
 	],
 	"sources": [
 		"../index.js"
@@ -11,6 +13,6 @@
 	"sourcesContent": [
 		null
 	],
-	"mappings": ";;;;cAKaA,cAAcA;;;;;;;;;;;;;;;;;;cAwCdC,sBAAsBA",
+	"mappings": ";;;;;;;;cASaA,oBAAoBA;;;;;;;;;;;;;;;;;;cAwCpBC,4BAA4BA;;;;;;;;;;;;;;cAsD5BC,kBAAkBA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAkFlBC,0BAA0BA",
 	"ignoreList": []
 }