@pikku/modelcontextprotocol

Provides a Node.js runtime environment for spinning up Model Context Protocol servers using the official MCP SDK. Handles server instantiation, connection negotiation, and graceful shutdown through a standardized initialization pattern that abstracts away low-level MCP protocol details. The runtime manages the server's lifecycle from startup through message routing to connected clients.

Enables developers to define tools (callable functions exposed to MCP clients) using JSON Schema for input validation and type safety. The runtime validates tool definitions against the MCP specification and registers them in a central tool registry that clients can discover via the MCP tools/list endpoint. Supports complex nested schemas, optional parameters, and description metadata for client-side UI rendering.

Allows servers to expose resources (files, documents, data) to MCP clients through a resource registry with URI-based addressing. Supports streaming large resources via chunked responses and lazy-loading content, preventing memory bloat when exposing large datasets. Resources are discoverable via the MCP resources/list endpoint and can be fetched with optional filtering and pagination parameters.

Enables servers to define reusable prompt templates that MCP clients can discover and instantiate with dynamic arguments. Templates support variable substitution, conditional sections, and metadata for client-side UI hints (e.g., input field types). The runtime manages template registration and provides clients with the prompts/list and prompts/get endpoints for discovery and instantiation.

Implements the MCP JSON-RPC 2.0 message protocol with automatic request routing to registered handlers, response serialization, and error handling. Routes incoming messages to appropriate tool handlers, resource readers, or prompt resolvers based on method names; catches exceptions and converts them to MCP-compliant error responses with proper error codes and messages. Handles both request-response and notification patterns.

Manages incoming client connections, performs MCP protocol version negotiation, and maintains connection state throughout the server's lifetime. Handles the initialization handshake where clients declare their capabilities and the server responds with its supported features. Manages connection cleanup and graceful disconnection, including resource teardown for long-lived connections.

Exposes the server's ability to request sampling (LLM inference) from connected clients through the sampling/create endpoint. Allows servers to invoke language models on the client side (e.g., Claude running in Claude Desktop) with specified prompts, model parameters, and system instructions. Responses are streamed back to the server, enabling agentic patterns where servers can reason about tool results and decide next steps.