SwiftMCP: Model Context Protocol for Swift

The TCPBonjourTransport allows for local discovery of MCP services. Identity is managed via the instance name and a scope.

Scopes:

• .localUser (Default): Advertises as Name (user). Limits discovery to the same user on the same machine to prevent collisions between different user accounts.
• .localMachine: Advertises as Name. Visible on the local loopback.
• .localNetwork: Advertises on the attached link. Note that TCP transport has no built-in authorization, so anything on the network can reach the service.

To connect to a discovered service, the client must use the same base name and scope as the server.

// Server side
let transport = TCPBonjourTransport(server: server) // Defaults to .localUser

// Client side
let config = MCPServerTcpConfig(instanceName: "MyServerName") // Matches .localUser
let proxy = MCPServerProxy(config: .tcp(config: config))
try await proxy.connect()

SwiftMCP separates the responsibility of moving bytes (the transport) from the responsibility of answering messages (the server). This is achieved through two protocols:

1. MCPDispatcher: The dispatch surface that a transport calls. It provides methods to handle a single JSONRPCMessage or a batch of messages. The dispatcher manages the 'gate' (e.g., rejecting requests before initialization).
2. MCPTransport: A Service that owns the wire and its sessions. It routes decoded payloads through an injected MCPDispatcher.

The MCPServer.serve(over:...) method acts as the glue, connecting the dispatcher to every transport and managing their lifecycle and ordered shutdown.

public protocol MCPDispatcher: Sendable {
    func handle(_ message: JSONRPCMessage) async -> JSONRPCMessage?
    func handle(_ batch: [JSONRPCMessage]) async -> [JSONRPCMessage]
}

public protocol MCPTransport: Service {
    func connect(to dispatcher: any MCPDispatcher)
}

Roots are filesystem locations provided by the client. You can retrieve the list of available roots using session.listRoots().

To react to changes in the client's filesystem environment, implement the handleRootsListChanged() method within your @MCPServer actor.

@MCPTool
func listClientRoots() async throws -> [String] {
    guard let session = Session.current else {
        throw MCPServerError.noActiveSession
    }
    
    guard await session.clientCapabilities?.roots != nil else {
        return ["Client does not support roots"]
    }
    
    let roots = try await session.listRoots()
    return roots.map { "\(\($0.name ?? "Unnamed")): \($0.uri)" }
}

@MCPServer(name: "MyServer")
actor MyServer {
    func handleRootsListChanged() async {
        guard let session = Session.current else { return }
        do {
            let updatedRoots = try await session.listRoots()
            // Handle updated roots...
        } catch {
            // Handle error...
        }
    }
}

The @MCPResource macro allows you to expose functions as resources accessible via URI templates. This enables clients to access data using structured URIs with path and query parameters.

Key Features

• URI Templates: Define patterns using curly braces for placeholders (e.g., {param}).
• Path Parameters: Extract values directly from the URI path.
• Query Parameters: Extract values from the query string (e.g., ?q={query}).
• Optional Parameters: Supports Swift default values for optional parameters.
• MIME Types: You can specify the content type using the mimeType: parameter.
• Type Safety: Parameters are automatically converted from URI strings to the correct Swift types.

Automatic Server Capabilities

When using @MCPResource, the server automatically handles:

• Resource discovery via mcpResourceTemplates.
• URI matching and parameter extraction.
• Type conversion, validation, and error handling for invalid parameters.

@MCPServer(name: "ResourceServer")
actor ResourceServer {
    /// Get user profile by ID
    @MCPResource("users://{user_id}/profile")
    func getUserProfile(user_id: Int) -> String {
        return "Profile for user \(user_id)"
    }
    
    /// Search users with pagination
    @MCPResource("users://search?q={query}&page={page}", mimeType: "application/json")
    func searchUsers(query: String, page: Int = 1) -> String {
        return "{\"query\": الش\"query\"\", \"page\": \(page)\"}"
    }
}