mcp-server

Implements the Model Context Protocol (MCP) server-side specification, handling bidirectional JSON-RPC 2.0 message transport over stdio, WebSocket, or SSE channels. Manages server initialization handshake, capability negotiation, and graceful shutdown. Routes incoming requests to registered handlers and enforces protocol versioning and feature compatibility checks during the initialization phase.

Provides a declarative API for registering tools with JSON Schema input specifications and handler functions. Automatically validates incoming tool call requests against schemas before routing to handlers, rejecting malformed inputs with schema violation errors. Supports nested object schemas, arrays, enums, and custom validation constraints through standard JSON Schema Draft 7 syntax.

Allows registration of static or dynamic resources (files, API responses, computed data) with URI templates and MIME type declarations. Handles resource read requests by matching URIs against registered patterns and serving content with appropriate content-type headers. Supports text, binary, and streaming resource types with optional caching hints.

Enables registration of reusable prompt templates with arguments and descriptions that clients can discover and invoke. Templates are advertised during capability negotiation and can include placeholders for dynamic argument substitution. Supports organizing prompts with names and descriptions for client-side UI rendering and selection.

Abstracts transport layer details behind a unified server interface, supporting stdio (for CLI/subprocess integration), WebSocket (for persistent connections), and Server-Sent Events (for HTTP-based streaming). Automatically selects transport based on environment or explicit configuration, handling connection lifecycle, message framing, and error recovery for each transport type.

Implements JSON-RPC 2.0 error response formatting with MCP-specific error codes and messages. Catches exceptions in tool handlers and resource readers, wrapping them in protocol-compliant error objects with stack traces (in development) and user-friendly messages. Supports custom error codes for domain-specific failures (e.g., tool validation errors, resource not found).

Implements the MCP initialization handshake where the server advertises its capabilities (tools, resources, prompts) and protocol version to clients. Negotiates protocol compatibility by comparing client and server versions, rejecting incompatible clients with clear error messages. Stores initialization state for later request routing and capability queries.

Maintains JSON-RPC 2.0 message ID tracking to correlate responses with requests, ensuring responses are delivered to the correct handler even with concurrent requests. Implements message ordering guarantees where applicable and handles out-of-order responses gracefully. Supports both request-response and notification (fire-and-forget) message patterns.