@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

``bash
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

$3

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

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

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

$3

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

#### Stream session manager

`javascript
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

`javascript
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

$3

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)

$3

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

$3

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 {
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