Add proxy support for MCP resources and prompts

Author: odrobnik

README.md

@@ -154,8 +154,8 @@ try await tcpTransport.run()
 ## Typed Client Proxy
 
 SwiftMCP can generate a typed client proxy for any server. This proxy mirrors the
-`@MCPTool` signatures and forwards calls through `MCPServerProxy`. Enable it with
-`generateClient: true` on the server macro.
+`@MCPTool`, `@MCPResource`, and `@MCPPrompt` signatures and forwards calls through
+`MCPServerProxy`. Enable it with `generateClient: true` on the server macro.
 
 ```swift
 @MCPServer(generateClient: true)
@@ -191,7 +191,8 @@ Notes:
 
 Use `SwiftMCPUtility generate-proxy` to create a client proxy for any MCP server,
 including non-SwiftMCP servers. The generated proxy calls `MCPServerProxy` under
-the hood and always returns `String` because MCP does not include output schemas.
+the hood, generates typed tool methods from MCP tool schemas, and adds first-class
+resource/prompt convenience APIs when the server advertises those capabilities.
 Input parameters are inferred from the server's tool schemas, and only string
 formats such as `date-time`, `uri`, `uuid`, and `byte` can be mapped to native
 types (`Date`, `URL`, `UUID`, `Data`).

Sources/SwiftMCP/Client/MCPServerProxy.swift

@@ -131,47 +131,8 @@ public final actor MCPServerProxy: Sendable {
             return cachedTools
         }
 
-        let requestId = nextRequestID()
-        let request = JSONRPCMessage.request(id: requestId, method: "tools/list")
-        let response = try await send(request)
-
-        guard case let .response(respData) = response, let result = respData.result else {
-            throw MCPServerProxyError.communicationError("Invalid response type for tools/list")
-        }
-
-        if let isError = result["isError"]?.value as? Bool, isError {
-            throw MCPServerProxyError.communicationError("Server does not provide any tools")
-        }
-
-        guard let toolsData = result["tools"]?.value as? [[String: Any]] else {
-            throw MCPServerProxyError.communicationError("Invalid response format for tools/list")
-        }
-
-        let tools = try toolsData.compactMap { toolData -> MCPTool? in
-            guard let name = toolData["name"] as? String,
-                  let inputSchema = toolData["inputSchema"] as? [String: Any] else {
-                return nil
-            }
-
-            let description = toolData["description"] as? String
-            let schema = try JSONDecoder().decode(JSONSchema.self, from: JSONSerialization.data(withJSONObject: inputSchema))
-            let outputSchema: JSONSchema?
-            if let outputSchemaData = toolData["outputSchema"] as? [String: Any] {
-                outputSchema = try JSONDecoder().decode(JSONSchema.self, from: JSONSerialization.data(withJSONObject: outputSchemaData))
-            } else {
-                outputSchema = nil
-            }
-
-            // Parse annotations if present
-            let annotations: MCPToolAnnotations?
-            if let annotationsData = toolData["annotations"] as? [String: Any] {
-                annotations = try JSONDecoder().decode(MCPToolAnnotations.self, from: JSONSerialization.data(withJSONObject: annotationsData))
-            } else {
-                annotations = nil
-            }
-
-            return MCPTool(name: name, description: description, inputSchema: schema, outputSchema: outputSchema, annotations: annotations)
-        }
+        let result = try await requestResult(method: "tools/list")
+        let tools: [MCPTool] = try decodeResultField("tools", from: result, method: "tools/list")
 
         if cacheToolsList {
             cachedTools = tools
@@ -180,6 +141,48 @@ public final actor MCPServerProxy: Sendable {
         return tools
     }
 
+    /// Lists all static resources available from the server.
+    public func listResources() async throws -> [SimpleResource] {
+        let result = try await requestResult(method: "resources/list")
+        return try decodeResultField("resources", from: result, method: "resources/list")
+    }
+
+    /// Lists all resource templates available from the server.
+    public func listResourceTemplates() async throws -> [SimpleResourceTemplate] {
+        let result = try await requestResult(method: "resources/templates/list")
+        return try decodeResultField("resourceTemplates", from: result, method: "resources/templates/list")
+    }
+
+    /// Reads a resource at the specified URI.
+    public func readResource(uri: URL) async throws -> [GenericResourceContent] {
+        let result = try await requestResult(
+            method: "resources/read",
+            params: ["uri": AnyCodable(uri.absoluteString)]
+        )
+        return try decodeResultField("contents", from: result, method: "resources/read")
+    }
+
+    /// Lists all prompts available from the server.
+    public func listPrompts() async throws -> [Prompt] {
+        let result = try await requestResult(method: "prompts/list")
+        return try decodeResultField("prompts", from: result, method: "prompts/list")
+    }
+
+    /// Gets a prompt by name with optional arguments.
+    public func getPrompt(
+        name: String,
+        arguments: [String: any Sendable] = [:]
+    ) async throws -> PromptResult {
+        let result = try await requestResult(
+            method: "prompts/get",
+            params: [
+                "name": AnyCodable(name),
+                "arguments": AnyCodable(arguments.mapValues(AnyCodable.init))
+            ]
+        )
+        return try decodeResultField("self", from: result, method: "prompts/get", as: PromptResult.self)
+    }
+
     /// Calls a tool by name on the connected MCP server with the provided arguments.
     public func callTool(
         _ name: String,
@@ -205,18 +208,21 @@ public final actor MCPServerProxy: Sendable {
         let request = JSONRPCMessage.request(id: requestId, method: "tools/call", params: params)
         let responseMessage = try await send(request)
 
-        guard case let .response(responseData) = responseMessage, let result = responseData.result else {
+        let result: [String: AnyCodable]
+        switch responseMessage {
+        case .response(let responseData):
+            guard let responseResult = responseData.result else {
+                throw MCPServerProxyError.communicationError("Invalid response type for tools/call, expected JSONRPCResponse")
+            }
+            result = responseResult
+        case .errorResponse(let errorResponse):
+            throw MCPServerProxyError.toolError(errorResponse.error.message)
+        default:
             throw MCPServerProxyError.communicationError("Invalid response type for tools/call, expected JSONRPCResponse")
         }
 
         if let isError = result["isError"]?.value as? Bool, isError {
-            var errorMessage = "Tool call failed with an unspecified error."
-            if let contentArray = result["content"]?.value as? [Any],
-               let firstContent = contentArray.first as? [String: Any],
-               let text = firstContent["text"] as? String {
-                errorMessage = text
-            }
-            throw MCPServerProxyError.toolError(errorMessage)
+            throw MCPServerProxyError.toolError(errorMessage(from: result) ?? "Tool call failed with an unspecified error.")
         }
 
         guard let contentValue = result["content"]?.value else {
@@ -714,6 +720,72 @@ public final actor MCPServerProxy: Sendable {
         return nil
     }
 
+    private func requestResult(
+        method: String,
+        params: [String: AnyCodable]? = nil
+    ) async throws -> [String: AnyCodable] {
+        let requestId = nextRequestID()
+        let request = JSONRPCMessage.request(id: requestId, method: method, params: params)
+        let response = try await send(request)
+
+        switch response {
+        case .response(let responseData):
+            guard let result = responseData.result else {
+                throw MCPServerProxyError.communicationError("Invalid response type for \(method)")
+            }
+            if let isError = result["isError"]?.value as? Bool, isError {
+                throw MCPServerProxyError.communicationError(errorMessage(from: result) ?? "Request failed for \(method)")
+            }
+            return result
+        case .errorResponse(let errorResponse):
+            throw MCPServerProxyError.communicationError(errorResponse.error.message)
+        default:
+            throw MCPServerProxyError.communicationError("Invalid response type for \(method)")
+        }
+    }
+
+    private func decodeResultField<T: Decodable>(
+        _ field: String,
+        from result: [String: AnyCodable],
+        method: String,
+        as type: T.Type = T.self
+    ) throws -> T {
+        let value: AnyCodable
+        if field == "self" {
+            value = AnyCodable(result)
+        } else if let fieldValue = result[field] {
+            value = fieldValue
+        } else {
+            throw MCPServerProxyError.communicationError("Invalid response format for \(method)")
+        }
+
+        let encoder = JSONEncoder()
+        encoder.dateEncodingStrategy = .iso8601WithTimeZone
+        let data = try encoder.encode(value)
+
+        let decoder = JSONDecoder()
+        decoder.dateDecodingStrategy = .iso8601WithTimeZone
+        return try decoder.decode(type, from: data)
+    }
+
+    private func errorMessage(from result: [String: AnyCodable]) -> String? {
+        if let message = stringValue(result["message"]) {
+            return message
+        }
+        if let contentValue = result["content"]?.value {
+            let contentArray: [Any]
+            if let array = contentValue as? [Any] {
+                contentArray = array
+            } else if let array = contentValue as? [AnyCodable] {
+                contentArray = array.map(\.value)
+            } else {
+                contentArray = []
+            }
+            return extractTextPayload(from: contentArray)
+        }
+        return nil
+    }
+
 
     private func extractServerDescription(from result: [String: AnyCodable]) -> String? {
         guard let serverInfoValue = result["serverInfo"]?.value else {

Sources/SwiftMCP/Models/Prompts/Prompt.swift

@@ -2,7 +2,7 @@ import Foundation
 import AnyCodable
 
 /// Represents a prompt that can be provided by an MCP server
-public struct Prompt: Encodable, Sendable {
+public struct Prompt: Codable, Sendable {
     /// Unique name of the prompt
     public let name: String
 
@@ -24,6 +24,28 @@ extension Prompt {
         case name, description, arguments
     }
 
+    private struct ArgumentPayload: Codable {
+        let name: String
+        let description: String?
+        let required: Bool?
+    }
+
+    public init(from decoder: Decoder) throws {
+        let container = try decoder.container(keyedBy: CodingKeys.self)
+        name = try container.decode(String.self, forKey: .name)
+        description = try container.decodeIfPresent(String.self, forKey: .description)
+
+        let args = try container.decodeIfPresent([ArgumentPayload].self, forKey: .arguments) ?? []
+        arguments = args.map { argument in
+            MCPParameterInfo(
+                name: argument.name,
+                type: String.self,
+                description: argument.description?.isEmpty == false ? argument.description : nil,
+                isRequired: argument.required ?? false
+            )
+        }
+    }
+
     public func encode(to encoder: Encoder) throws {
         var container = encoder.container(keyedBy: CodingKeys.self)
         try container.encode(name, forKey: .name)

Sources/SwiftMCP/Models/Prompts/PromptResult.swift

@@ -0,0 +1,12 @@
+import Foundation
+
+/// The result returned by `prompts/get`.
+public struct PromptResult: Codable, Sendable {
+    public let description: String?
+    public let messages: [PromptMessage]
+
+    public init(description: String? = nil, messages: [PromptMessage]) {
+        self.description = description
+        self.messages = messages
+    }
+}

Sources/SwiftMCP/Models/Resources/MCPResourceMetadata.swift

@@ -106,4 +106,11 @@ public struct SimpleResourceTemplate: MCPResourceTemplate {
     public let name: String
     public let description: String?
     public let mimeType: String?
-} 
+
+    public init(uriTemplate: String, name: String, description: String? = nil, mimeType: String? = nil) {
+        self.uriTemplate = uriTemplate
+        self.name = name
+        self.description = description
+        self.mimeType = mimeType
+    }
+}

Sources/SwiftMCP/SwiftMCP.docc/Tutorials/BuildingAnMCPClient.tutorial

@@ -1,9 +1,9 @@
 @Tutorial(time: 15) {
     @Intro(title: "Building an MCP Client") {
-        Learn how to generate a typed client proxy from a SwiftMCP server and call tools
+        Learn how to generate a typed client proxy from a SwiftMCP server and call tools, resources, and prompts
         over JSON-RPC using `MCPServerProxy`.
 
-        The generated client mirrors your `@MCPTool` signatures and includes the
+        The generated client mirrors your `@MCPTool`, `@MCPResource`, and `@MCPPrompt` signatures and includes the
         same documentation for autocompletion.
 
         @Image(source: "placeholder.png", alt: "Illustration showing a SwiftMCP client calling tools")
@@ -13,14 +13,14 @@
         @ContentAndMedia {
             Opt in to client generation by passing `generateClient: true` to the
             `@MCPServer` macro. This creates a nested `Client` type that mirrors
-            the `@MCPTool` functions.
+            the server's MCP tools, resources, and prompts.
 
             @Image(source: "placeholder.png", alt: "Illustration showing a generated client nested type")
         }
 
         @Steps {
             @Step {
-                Create a server with tools and enable client generation.
+                Create a server with MCP surfaces and enable client generation.
 
                 @Code(name: "Calculator.swift", file: "07-client-server.swift")
             }
@@ -30,7 +30,7 @@
     @Section(title: "Connect and Call Tools") {
         @ContentAndMedia {
             Use `MCPServerProxy` to connect to the server, then instantiate the
-            generated client and call tools with native types.
+            generated client and call tools, resources, and prompts with native types.
 
             Client methods always throw to surface transport or server errors.
 
@@ -45,7 +45,7 @@
             }
 
             @Step {
-                Call tools with native input and output types.
+                Call generated client APIs with native input and output types.
 
                 @Code(name: "Client.swift", file: "09-client-calls.swift")
             }