@transcend-io/mcp-server-core

Provides core infrastructure for implementing Model Context Protocol (MCP) servers with standardized request/response handling, message routing, and server lifecycle hooks. Abstracts the MCP protocol specification into reusable TypeScript classes and interfaces, enabling developers to focus on tool/resource implementation rather than protocol mechanics. Handles bidirectional JSON-RPC communication, capability negotiation, and graceful shutdown patterns.

Enables declarative registration of tools/functions that MCP clients can discover and invoke, with built-in schema validation, parameter type checking, and execution context binding. Uses a registry pattern where tools are defined with JSON Schema descriptions and TypeScript type signatures, then automatically exposed through the MCP protocol. Handles tool invocation routing, argument validation, and error propagation back to clients.

Provides infrastructure for exposing read-only resources (documents, data, configurations) through MCP with support for streaming large payloads and templated resource URIs. Resources are registered with URI templates and content types, enabling clients to request specific resources by URI and receive streamed responses. Handles resource discovery, URI parameter substitution, and content negotiation.

Provides extensibility hooks for intercepting and transforming MCP requests and responses at various stages of processing (pre-validation, post-execution, error handling). Implemented as a middleware chain pattern where handlers can inspect/modify messages, perform logging, add telemetry, or enforce policies before tools/resources are invoked. Supports both synchronous and asynchronous middleware.

Implements MCP-compliant error handling with standardized error codes, messages, and response formats. Converts application exceptions into properly formatted MCP error responses that clients can parse and handle consistently. Supports error categorization (validation errors, not-found, permission denied, internal errors) with appropriate HTTP-like status codes.

Leverages TypeScript's type system to provide compile-time safety for tool parameters, return types, and resource content. Tool definitions are written as TypeScript functions with full type annotations, and the framework automatically generates JSON Schema from these types and validates runtime values against the schema. Enables IDE autocomplete and type checking for tool implementations.

Handles MCP server initialization handshake, including protocol version negotiation, capability declaration, and client/server metadata exchange. Implements the MCP initialization sequence where the server declares which tools, resources, and prompts it supports, and the client declares its capabilities. Manages server state transitions from uninitialized to ready.

Provides hooks and utilities for graceful server shutdown, including resource cleanup, connection draining, and signal handling. Implements patterns for waiting for in-flight requests to complete before terminating, closing database connections, and releasing file handles. Supports both SIGTERM and SIGINT signals with configurable shutdown timeouts.

Provides structured logging hooks and observability integration points for monitoring MCP server operations, tool invocations, and errors. Supports pluggable logger implementations and structured logging with context propagation. Enables teams to integrate with observability platforms (DataDog, New Relic, etc.) by providing hooks for metrics, traces, and logs.

Enables registration and management of reusable prompts that MCP clients can discover and use. Prompts are defined with templates, arguments, and descriptions, allowing clients to request specific prompts and provide argument values. Supports prompt versioning and metadata. Handles prompt discovery and argument validation.