@tmcp/session-manager

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

pnpm add @tmcp/session-manager

Overview

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 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 Managers (Default)

The package ships with InMemoryStreamSessionManager and InMemoryInfoSessionManager. Together they are suitable for single-server deployments or tests:

import {
	InMemoryStreamSessionManager,
	InMemoryInfoSessionManager,
} from '@tmcp/session-manager';

const sessionManagers = {
	streams: new InMemoryStreamSessionManager(),
	info: new InMemoryInfoSessionManager(),
};

Custom Session Managers

You can implement your own managers by extending the base classes that ship with this package.

Stream session manager

import { StreamSessionManager } from '@tmcp/session-manager';

class CustomStreamSessionManager extends StreamSessionManager {
	create(id, controller) {
		// Persist the ReadableStream controller for later notifications
	}

	delete(id) {
		// Clean up the controller and any associated timers
	}

	async has(id) {
		// Return whether a controller for the session exists
	}

	send(sessions, data) {
		// Fan out the payload to the targeted sessions (or everyone if sessions is undefined)
	}
}

Info session manager

import { InfoSessionManager } from '@tmcp/session-manager';

class CustomInfoSessionManager extends InfoSessionManager {
	async getClientInfo(id) {
		// Return the last clientInfo payload for the session
	}

	setClientInfo(id, info) {
		// Persist clientInfo for later requests
	}

	async getClientCapabilities(id) {
		// Retrieve cached client capabilities
	}

	setClientCapabilities(id, capabilities) {
		// Persist the negotiated capabilities
	}

	async getLogLevel(id) {
		// Return the log level requested by the client
	}

	setLogLevel(id, level) {
		// Store the latest log level
	}

	async getSubscriptions(uri) {
		// Return all session ids subscribed to the URI
	}

	addSubscription(id, uri) {
		// Track that the session subscribed to the URI
	}

	delete(id) {
		// Remove all metadata for the session (client info, capabilities, subscriptions, etc.)
	}
}

API

StreamSessionManager (Abstract Base Class)

Responsible for creating and managing streaming controllers.

• 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)

InfoSessionManager (Abstract Base Class)

Stores session metadata that needs to survive across HTTP requests or reconnects.

• 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

InMemoryStreamSessionManager & InMemoryInfoSessionManager

Concrete in-memory implementations that cover both responsibilities. Combine them when configuring a transport:

import { HttpTransport } from '@tmcp/transport-http';
import { SseTransport } from '@tmcp/transport-sse';
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

• @tmcp/session-manager-redis - Redis-based session manager for multi-server deployments
• @tmcp/transport-http - HTTP transport using session managers
• @tmcp/transport-sse - SSE transport using session managers
• tmcp - Core TMCP server implementation

License

MIT