@metorial/mcp-session

Manages the complete lifecycle of Model Context Protocol sessions, including initialization, context state tracking, and graceful teardown. Implements session-scoped state management that persists across multiple tool invocations within a single session, using an internal state machine to track session phases (init → active → closing → closed) and coordinate cleanup of resources.

Provides a registry pattern for declaratively registering tools with MCP sessions, binding each tool's initialization, execution, and cleanup handlers to the session lifecycle. Uses a descriptor-based approach where tools define their schema, input/output types, and lifecycle hooks that are automatically invoked at appropriate session phases, enabling tools to acquire resources on session init and release them on session close.

Maintains isolated execution contexts for each tool invocation within a session, ensuring that context variables, request metadata, and execution state are properly scoped and propagated without cross-contamination between concurrent or sequential tool calls. Uses context-local storage patterns (similar to Node.js AsyncLocalStorage) to bind context to the execution stack of each tool handler.

Provides structured error handling for tool invocations with session-aware recovery strategies, including error classification (transient vs permanent), automatic retry logic with exponential backoff, and fallback tool invocation. Errors are caught at the session level and routed through configurable error handlers that can decide whether to retry, fallback, or propagate the error based on error type and session state.

Emits structured events at key session lifecycle points (session-created, tool-registered, tool-invoked, tool-completed, tool-failed, session-closing, session-closed) that can be subscribed to for monitoring, logging, and observability. Uses an event emitter pattern where listeners can hook into session events to implement custom logging, metrics collection, tracing, or audit trails without modifying session or tool code.

Provides mechanisms to serialize session state at any point in time, creating checkpoints that can be inspected for debugging or used for session recovery. Serialization captures the current session phase, active tools, context state, and execution history in a structured format (JSON) that can be logged, stored, or transmitted for analysis or recovery purposes.

Validates tool invocation inputs against registered tool schemas (JSON Schema) and performs automatic type coercion before passing inputs to tool handlers. Validation happens at the session level before tool execution, catching schema violations early and providing detailed validation error messages that include which fields failed and why, enabling graceful error handling without tool-side validation code.

Enables multiple tools to be invoked concurrently within a session while maintaining proper context isolation and execution coordination. Uses Promise-based concurrency patterns to execute independent tools in parallel, with optional dependency tracking to ensure tools with dependencies execute in the correct order. Provides coordination primitives (barriers, semaphores) to synchronize tool execution when needed.