json-rpc 2.0 bidirectional message protocol implementation
Implements full JSON-RPC 2.0 specification with bidirectional request-response semantics, enabling both clients and servers to initiate requests and handle responses asynchronously. Uses Swift's Codable protocol for type-safe serialization/deserialization of protocol messages, with support for request IDs, error objects, and notification patterns (requests without response expectations). The protocol layer abstracts transport mechanisms, allowing the same message handling logic to work across stdio, HTTP, and network transports.
Unique: Uses Swift's actor-based concurrency model with Codable for type-safe JSON-RPC 2.0 implementation, enabling compile-time verification of message structures across bidirectional communication flows without runtime reflection
vs alternatives: Stronger type safety than generic JSON-RPC libraries due to Swift's static typing and Codable, with built-in actor isolation preventing race conditions in concurrent message handling
actor-based concurrent client connection management
Implements the Client actor (Sources/MCP/Base/Client.swift) using Swift's structured concurrency model to manage thread-safe connections to MCP servers. The actor encapsulates connection state, request lifecycle management, and server capability invocation, ensuring all access is serialized through actor isolation. Handles connection initialization with capability negotiation, maintains request-response correlation via message IDs, and manages cancellation tokens for in-flight requests.
Unique: Uses Swift's actor model for compile-time data race prevention in concurrent MCP client access, eliminating need for manual locks or semaphores while maintaining type safety across async boundaries
vs alternatives: Safer than thread-based approaches (no manual locking) and more efficient than callback-based concurrency, with compiler-enforced isolation preventing data races at compile time
roots management for client-side context and file system access
Provides a roots system allowing clients to declare accessible file system paths or context roots that servers can reference when processing requests. Clients can list roots via listRoots() and servers can use root information to understand what resources are available. Roots support URI schemes and optional metadata, enabling servers to make context-aware decisions. The implementation allows clients to update roots dynamically, with servers receiving notifications of root changes.
Unique: Provides declarative root management allowing clients to communicate accessible file system context to servers, with dynamic updates via notifications for context changes
vs alternatives: More flexible than static path configuration because roots can be updated dynamically, and more secure than unrestricted access because clients explicitly declare accessible paths
request batching with correlated response handling
Supports batching multiple requests into a single message for efficiency, with automatic response correlation based on request IDs. Clients can send multiple requests in a batch; the SDK correlates responses to requests using message IDs. The implementation handles partial failures gracefully, returning individual responses for each request. Batching reduces message overhead and network round-trips, particularly useful for high-latency transports.
Unique: Implements automatic request-response correlation via message IDs for batched requests, enabling efficient multi-request operations without manual correlation logic
vs alternatives: More efficient than sequential requests because multiple requests are sent in one message, and more reliable than manual batching because SDK handles response correlation automatically
testing infrastructure with mocktransport and integration testing utilities
Provides testing utilities including MockTransport for in-memory testing without real network connections, and integration testing helpers for roundtrip testing of client-server interactions. MockTransport enables unit testing of MCP clients and servers in isolation, while integration tests verify end-to-end behavior. The implementation includes test doubles for all major components, enabling comprehensive testing without external dependencies.
Unique: Provides MockTransport and integration testing utilities enabling comprehensive testing of MCP applications without external dependencies, with support for both unit and integration test scenarios
vs alternatives: More comprehensive than manual mocking because SDK provides pre-built test doubles, and faster than integration tests with real servers because MockTransport operates in-memory
error handling with typed error responses and recovery patterns
Implements structured error handling using typed error responses that include error codes, messages, and optional data. Errors are propagated through the JSON-RPC 2.0 protocol with standardized error codes (parse error, invalid request, method not found, invalid params, internal error, server error). The implementation provides error recovery patterns and allows servers to define custom error codes. Clients can match on error codes to implement specific recovery logic.
Unique: Provides typed error responses with standardized JSON-RPC 2.0 error codes plus support for custom domain-specific error codes, enabling both standard and application-specific error handling
vs alternatives: More structured than string-based errors because error codes enable programmatic handling, and more flexible than fixed error sets because custom codes can be defined per application
notification system for asynchronous server-to-client events
Implements a notification system allowing servers to send asynchronous events to clients without requiring a corresponding request. Notifications are one-way messages (no response expected) used for log messages, resource updates, tool list changes, root changes, and progress updates. The implementation uses the JSON-RPC 2.0 notification pattern (requests without IDs) and allows clients to subscribe to notification types via handlers.
Unique: Implements JSON-RPC 2.0 notification pattern for one-way server-to-client events, enabling real-time updates without request-response overhead
vs alternatives: More efficient than polling because servers push notifications, and more flexible than request-response patterns because notifications don't require client initiation
multi-transport abstraction layer with pluggable implementations
Provides a Transport protocol abstraction enabling the same client/server code to work across stdio, HTTP, network, and in-memory transports. Each transport implementation handles protocol-specific details: StdioTransport uses swift-system for cross-platform file descriptor operations, HTTPClientTransport uses Server-Sent Events (SSE) for server-to-client messages, NetworkTransport handles TCP/IP connections, and InMemoryTransport enables testing. The abstraction layer decouples message protocol (JSON-RPC 2.0) from transport mechanism, allowing custom transports to be implemented by conforming to the Transport protocol.
Unique: Protocol-based transport abstraction with four built-in implementations (stdio, HTTP, network, in-memory) plus extensibility for custom transports, enabling same MCP code to run in CLI, server, mobile, and test environments without modification
vs alternatives: More flexible than fixed-transport SDKs because transport is swappable at runtime, and more testable than frameworks requiring real network connections due to in-memory and mock transport support
+7 more capabilities