@tmcp/session-manager 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paolo Ricciuti
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# @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.
+
+## Installation
+
+```bash
+pnpm add @tmcp/session-manager
+```
+
+## Overview
+
+Session managers handle the storage and communication with client sessions in TMCP transport layers. 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
+
+## Usage
+
+### In-Memory Session Manager (Default)
+
+The `InMemorySessionManager` stores sessions in memory and is suitable for single-server deployments:
+
+```javascript
+import { InMemorySessionManager } from '@tmcp/session-manager';
+
+const sessionManager = new InMemorySessionManager();
+```
+
+### Custom Session Manager
+
+You can implement your own session manager by extending the base `SessionManager` class:
+
+```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
+	 */
+	create(id, controller) {
+		// Implementation here
+	}
+
+	/**
+	 * Delete a session by ID
+	 * @param {string} id - Session ID to delete
+	 */
+	delete(id) {
+		// Implementation here
+	}
+
+	/**
+	 * Check if a session exists
+	 * @param {string} id - Session ID to check
+	 * @returns {Promise<boolean>} - Whether the session exists
+	 */
+	async has(id) {
+		// Implementation here
+	}
+
+	/**
+	 * 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
+	}
+}
+```
+
+## API
+
+### `SessionManager` (Abstract Base Class)
+
+#### Methods
+
+##### `create(id: string, controller: ReadableStreamDefaultController): void`
+
+Creates a new session with the specified ID and associates it with a stream controller.
+
+**Parameters:**
+
+- `id` - Unique session identifier
+- `controller` - ReadableStreamDefaultController for sending data to the client
+
+##### `delete(id: string): void`
+
+Removes a session and cleans up its resources.
+
+**Parameters:**
+
+- `id` - Session ID to delete
+
+##### `has(id: string): Promise<boolean>`
+
+Checks whether a session with the given ID exists.
+
+**Parameters:**
+
+- `id` - Session ID to check
+
+**Returns:**
+
+- Promise resolving to true if the session exists, false otherwise
+
+##### `send(sessions: string[] | undefined, data: string): void`
+
+Sends data to one or more sessions.
+
+**Parameters:**
+
+- `sessions` - Array of session IDs to send to, or undefined to send to all sessions
+- `data` - String data to send (typically SSE-formatted)
+
+### `InMemorySessionManager`
+
+Concrete implementation that stores sessions in a JavaScript Map. Suitable for single-server deployments.
+
+#### Usage with Transport Layers
+
+```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 });
+```
+
+## Related Packages
+
+- [`@tmcp/session-manager-redis`](../session-manager-redis) - Redis-based session manager for multi-server deployments
+- [`@tmcp/transport-http`](../transport-http) - HTTP transport using session managers
+- [`@tmcp/transport-sse`](../transport-sse) - SSE transport using session managers
+- [`tmcp`](../tmcp) - Core TMCP server implementation
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@tmcp/session-manager",
+  "version": "0.1.0",
+  "description": "",
+  "main": "src/index.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/paoloricciuti/tmcp.git",
+    "directory": "packages/session-manager"
+  },
+  "keywords": [
+    "tmcp",
+    "http",
+    "transport",
+    "session",
+    "manager"
+  ],
+  "types": "./src/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/types/index.d.ts",
+      "import": "./src/index.js"
+    }
+  },
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "dts-buddy": "^0.6.2",
+    "publint": "^0.3.12",
+    "@tmcp/internal-ts-helpers": "^1.0.0"
+  },
+  "scripts": {
+    "generate:types": "dts-buddy && node scripts/abstractify.js && publint",
+    "prepublish": "pnpm generate:types"
+  }
+}

package/scripts/abstractify.js

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

package/src/index.js

@@ -0,0 +1,89 @@
+/* eslint-disable no-unused-vars */
+
+/**
+ * @abstract
+ */
+export class SessionManager {
+	/**
+	 * @abstract
+	 * @param {string} id
+	 * @param {ReadableStreamDefaultController} controller
+	 */
+	create(id, controller) {
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {string} id
+	 */
+	delete(id) {
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {string} id
+	 * @returns {Promise<boolean>}
+	 */
+	has(id) {
+		throw new Error('Method not implemented.');
+	}
+
+	/**
+	 * @abstract
+	 * @param {string[] | undefined} sessions
+	 * @param {string} data
+	 */
+	send(sessions, data) {
+		throw new Error('Method not implemented.');
+	}
+}
+
+export class InMemorySessionManager extends SessionManager {
+	/**
+	 * @type {Map<string, ReadableStreamDefaultController>}
+	 */
+	#sessions = new Map();
+	#text_encoder = new TextEncoder();
+
+	/**
+	 * @param {string} id
+	 * @param {ReadableStreamDefaultController} controller
+	 */
+	create(id, controller) {
+		this.#sessions.set(id, controller);
+	}
+
+	/**
+	 * @param {string} id
+	 */
+	delete(id) {
+		const controller = this.#sessions.get(id);
+		if (controller) {
+			controller.close();
+			this.#sessions.delete(id);
+		}
+	}
+
+	/**
+	 * @abstract
+	 * @param {string} id
+	 * @returns {Promise<boolean>}
+	 */
+	async has(id) {
+		return this.#sessions.has(id);
+	}
+
+	/**
+	 * @param {string[] | undefined} sessions
+	 * @param {string} data
+	 */
+	send(sessions, data) {
+		for (const [id, controller] of this.#sessions.entries()) {
+			if (sessions == null || sessions.includes(id)) {
+				controller.enqueue(this.#text_encoder.encode(data));
+			}
+		}
+	}
+}

package/src/types/index.d.ts

@@ -0,0 +1,28 @@
+declare module '@tmcp/session-manager' {
+    /**
+     * @abstract
+     */
+    export abstract class SessionManager {
+        /**
+         * @abstract
+         * */
+        abstract create(id: string, controller: ReadableStreamDefaultController): void;
+        /**
+         * @abstract
+         * */
+        abstract delete(id: string): void;
+        /**
+         * @abstract
+         * */
+        abstract has(id: string): Promise<boolean>;
+        /**
+         * @abstract
+         * */
+        abstract send(sessions: string[] | undefined, data: string): void;
+    }
+    export class InMemorySessionManager extends SessionManager {
+        #private;
+    }
+    export {};
+}
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,16 @@
+{
+	"version": 3,
+	"file": "index.d.ts",
+	"names": [
+		"SessionManager",
+		"InMemorySessionManager"
+	],
+	"sources": [
+		"../index.js"
+	],
+	"sourcesContent": [
+		null
+	],
+	"mappings": ";;;;cAKaA,cAAcA;;;;;;;;;;;;;;;;;;cAqCdC,sBAAsBA",
+	"ignoreList": []
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+	"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"]
+}