# @tmcp/session-manager

Latest version **0.3.0** (published 2026-08-14) · MIT license · 0 weekly downloads

## Install

```sh
npm install @tmcp/session-manager
pnpm add @tmcp/session-manager
yarn add @tmcp/session-manager
bun add @tmcp/session-manager
```

## Health

**Score 75/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; has provenance; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.3.0 |
| Published | 2026-08-14 |
| First published | 2025-08-21 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 28.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Provenance | attested (GitHub Actions) |
| GitHub stars | 203 |
| Maintainers | pablopang |
| Keywords | tmcp, http, transport, session, manager |

## Links

- npm: https://www.npmjs.com/package/@tmcp/session-manager
- Repository: https://github.com/paoloricciuti/tmcp
- npm.io page: https://npm.io/package/@tmcp/session-manager

## Dependencies (1)

- [json-rpc-2.0](https://npm.io/package/json-rpc-2.0.md) ^1.7.1

## Alternatives

- [@clerk/clerk-expo](https://npm.io/package/@clerk/clerk-expo.md) — 133.6K weekly downloads
- [@pothos/plugin-authz](https://npm.io/package/@pothos/plugin-authz.md) — 12.4K weekly downloads
- [@bounded-sh/client](https://npm.io/package/@bounded-sh/client.md) — 3.2K weekly downloads
- [@luigi-project/plugin-auth-oauth2](https://npm.io/package/@luigi-project/plugin-auth-oauth2.md) — 2.3K weekly downloads
- [@nocobase/plugin-verification](https://npm.io/package/@nocobase/plugin-verification.md) — 2.0K weekly downloads

## Recent versions

- 0.3.0 (latest) — 2026-08-14
- 0.3.0-next.0 (next) — 2026-08-06
- 0.2.2 — 2026-05-14
- 0.2.1 — 2025-11-06
- 0.2.0 — 2025-10-29
- 0.1.2 — 2025-09-20
- 0.1.1 — 2025-08-26
- 0.1.0 — 2025-08-21

## README

# @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 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:

- **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
- **Per-Request Subscriptions**: Acknowledging, filtering, ordering, and closing sessionless notification streams

## Usage

### In-Memory Session Managers (Default)

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(),
};
```

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

#### 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
	}

	removeSubscription(id, uri) {
		// Stop tracking this resource subscription
	}

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

## 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.

- `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
- `removeSubscription(id, uri)` – remove one 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:

```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`](../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

---
_Source: https://npm.io/package/@tmcp/session-manager · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._