@gleanwork/mcp-server-utils

Provides standardized initialization, configuration, and shutdown patterns for MCP server implementations. Abstracts common server setup tasks including resource initialization, error handling, and graceful termination, reducing boilerplate across multiple MCP server packages. Works by exposing utility functions that wrap the MCP protocol's server lifecycle hooks and provide consistent patterns for state management.

Validates and registers MCP tool and resource definitions against the MCP protocol schema, ensuring type safety and protocol compliance before server startup. Implements schema validation using JSON Schema or similar mechanisms to catch configuration errors early, and provides a registry pattern for managing multiple tools/resources within a single server instance.

Provides consistent error handling middleware and structured logging utilities for MCP servers, including error serialization, context propagation, and protocol-compliant error responses. Implements patterns for capturing request context, formatting errors according to MCP protocol specifications, and routing logs to appropriate destinations with configurable verbosity levels.

Implements a composable middleware pattern for intercepting and transforming MCP requests and responses, enabling cross-cutting concerns like authentication, rate limiting, request validation, and response transformation. Works by providing a middleware registration API that chains handlers in order, with each handler able to inspect, modify, or reject requests/responses before passing to the next handler.

Provides a fluent API for constructing type-safe MCP tool definitions with input schema validation, parameter type checking, and IDE autocomplete support. Uses TypeScript generics and builder patterns to ensure tool definitions are validated at compile-time and runtime, reducing errors from schema mismatches between tool definition and implementation.

Provides utilities for managing MCP resource lifecycle, including resource discovery, lazy loading, and caching strategies to reduce redundant operations. Implements patterns for registering resource providers, managing resource state, and invalidating caches based on time or event triggers, enabling efficient resource serving without repeated expensive operations.