@claude-flow/mcp

Implements a standalone Model Context Protocol server that accepts client connections via three distinct transport mechanisms: stdio (for local process communication), HTTP (for REST-based polling or long-polling), and WebSocket (for bidirectional real-time communication). The server handles JSON-RPC 2.0 message framing and routing across all transports, allowing a single MCP server instance to serve multiple client types simultaneously without transport-specific business logic.

Manages a pool of active client connections with automatic lifecycle tracking, including connection establishment, heartbeat/keep-alive mechanisms, graceful disconnection, and resource cleanup. The pool maintains metadata about each connection (transport type, client capabilities, session state) and handles reconnection logic for transient failures, preventing resource leaks and zombie connections.

Implements MCP resource protocol methods (list_resources, read_resource) allowing servers to expose files, documents, or data as resources that clients can discover and read. Supports resource metadata (name, description, MIME type), streaming of large resources via chunked responses, and resource filtering/search. Handles resource access control and error cases (not found, permission denied).

Implements MCP prompt protocol methods (list_prompts, get_prompt) allowing servers to expose reusable prompt templates that clients can discover and instantiate. Supports prompt metadata (name, description, arguments), argument substitution, and prompt versioning. Enables clients to use server-provided prompts without hardcoding them, facilitating prompt reuse and management.

Implements MCP sampling protocol allowing servers to request LLM inference from clients, with model selection, temperature/top-p control, and streaming responses. Servers can ask clients to run inference using their configured LLM (e.g., Claude), enabling tool servers to leverage LLM capabilities without managing their own model. Supports both synchronous and streaming sampling.

Provides a centralized registry for MCP tools with JSON Schema validation, allowing developers to define tools once with input/output schemas and expose them to multiple client types. The registry validates incoming tool calls against declared schemas, enforces type safety, and supports tool discovery via the MCP list_tools protocol, enabling clients to introspect available capabilities before calling them.

Implements complete JSON-RPC 2.0 protocol compliance with automatic message framing, ID tracking, error code mapping, and response correlation. Handles malformed requests, missing required fields, invalid method names, and server errors with proper JSON-RPC error responses (including error codes like -32600 for invalid request, -32601 for method not found). Supports both request-response and notification patterns (requests without IDs that expect no response).

Routes incoming MCP protocol methods (initialize, list_tools, call_tool, list_resources, read_resource, etc.) to appropriate handlers based on method name and request type. Maintains a method registry where developers can register custom handlers for standard MCP methods, with automatic parameter extraction and response formatting. Supports both built-in MCP methods and custom extensions, with fallback to 'method not found' errors for unregistered methods.

Implements MCP stdio transport for local inter-process communication, where the MCP server reads JSON-RPC messages from stdin and writes responses to stdout. Handles process lifecycle (parent process exit detection), signal handling (SIGTERM, SIGINT), and proper cleanup of file descriptors. Supports the stdio transport used by Claude Desktop and other local MCP clients, enabling seamless integration with local development environments.

Implements MCP HTTP transport where clients send JSON-RPC requests via HTTP POST and receive responses via HTTP responses. Supports both synchronous request-response (client waits for response) and long-polling patterns (client polls for responses). Handles HTTP status codes, CORS headers, and content negotiation. Integrates with standard Node.js HTTP servers or frameworks like Express, allowing MCP servers to be exposed as HTTP APIs.

Implements MCP WebSocket transport for bidirectional, full-duplex communication where both client and server can send messages independently. Handles WebSocket connection lifecycle (upgrade, ping/pong, close), automatic reconnection on client side, and streaming of large responses. Supports both text frames (JSON) and binary frames, with automatic serialization/deserialization. Enables real-time tool interactions and server-initiated notifications.

Handles the MCP server initialization handshake where the server declares its capabilities (supported tools, resources, prompts, etc.) and the client declares its capabilities. Implements the initialize method that exchanges protocol version, server name/version, and feature flags. Stores negotiated capabilities for use in subsequent method calls, enabling clients to understand what the server can do before making requests.

Executes registered tools in response to call_tool requests, with automatic input validation against declared schemas, timeout enforcement, and error handling. Captures tool output (success or error), formats responses according to MCP protocol, and handles exceptions gracefully. Supports both synchronous and asynchronous tool handlers, with automatic promise resolution and error propagation.