Swift MCP SDK

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.

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.

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.

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.

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.

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.

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.

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.

Enables servers to expose tools (functions) to clients with JSON Schema descriptions and input validation, and enables clients to discover and invoke those tools. Servers register tools with the SDK, which handles schema serialization and parameter validation. Clients call listTools() to discover available tools, then callTool() to invoke them with validated parameters. The implementation uses Codable for type-safe parameter handling and JSON Schema for cross-language compatibility, supporting tools with complex nested parameters and return types.

Provides a resource system allowing servers to expose files, documents, or data streams to clients with automatic change notifications. Servers register resources with URI schemes and content providers; clients discover resources via listResources() and read content via readResource(). The implementation supports streaming large resources without loading into memory, and servers can emit resource update notifications to alert clients of changes. Resources are identified by URI, enabling hierarchical organization and filtering.

Implements a prompt management system allowing servers to expose reusable prompt templates with parameters that clients can discover and instantiate. Servers register prompts with descriptions and argument schemas; clients call listPrompts() to discover available prompts, then getPrompt() to retrieve filled prompts with parameters substituted. Prompts support multiple arguments with descriptions, enabling AI models to understand what parameters are available and how to use them. The implementation uses Codable for type-safe argument handling.

Enables servers to request LLM completions and user input from clients during request processing, supporting agentic workflows where servers make decisions based on model outputs. Servers call client.sample() to request model completions with specified parameters (model, temperature, max tokens, etc.), and client.elicit() to request user input. Clients implement these handlers to integrate with their LLM providers or user interfaces. The implementation uses async/await for non-blocking requests and supports streaming responses.

Implements a logging system where servers emit structured log messages that clients receive as notifications, enabling real-time monitoring and debugging of server operations. Uses swift-log for structured logging throughout the SDK, with support for log levels (debug, info, warning, error) and metadata. Servers emit logs via notifications; clients subscribe to log notifications and can filter by level or metadata. The implementation integrates with Swift's standard logging infrastructure, allowing logs to be captured by system loggers or custom handlers.

Provides mechanisms for tracking in-flight requests, cancelling long-running operations, and reporting progress to clients. Clients can cancel requests via cancellation tokens; servers respect cancellation and stop processing. Progress tracking allows servers to report completion percentage or status updates during long operations via notifications. The implementation uses Swift's Task cancellation model for cooperative cancellation and supports progress notifications for real-time feedback.

Implements automatic capability negotiation when clients connect to servers, allowing both sides to declare supported features (roots, sampling, elicitation) and agree on protocol version. During initialization, clients send their capabilities and configuration; servers respond with their capabilities. The implementation uses the Capability system to track which features are supported, enabling graceful degradation when features are unavailable. Clients can query server capabilities before attempting to use features.