macpaw/openai

When using MCP tools, the model may generate tool calls that are executed on the remote server. You must handle MCP-specific output items in your response processing, specifically .mcpToolCall (to access the tool name and output) and .mcpApprovalRequest (if requireApproval is enabled).

// Handle MCP tool calls in streaming responses
for try await result in openAI.chatsStream(query: query) {
    for choice in result.choices {
        if let outputItem = choice.delta.content {
            switch outputItem {
            case .mcpToolCall(let mcpCall):
                print("MCP tool call: \(mcpCall.name)")
                if let output = mcpCall.output {
                    print("Result: \(output)")
                }
            case .mcpApprovalRequest(let approvalRequest):
                // Handle approval request if requireApproval is enabled
                print("MCP tool requires approval: \(approvalRequest)")
            default:
                // Handle other output types
                break
            }
        }
    }
}

The SDK supports the Model Context Protocol (MCP), allowing models to connect to external data sources and tools via standardized server connections. You can use the MCP Swift library to discover tools and then integrate them into an OpenAI ChatQuery using Tool.mcpTool.

MCP Tool Configuration

When creating an mcpTool, you can specify:

• serverLabel: A unique identifier for the MCP server.
• serverUrl: The URL endpoint of the MCP server.
• headers: Authentication and other HTTP headers.
• allowedTools: An optional list of specific tools to enable from the server.
• requireApproval: Determines if tool calls require user approval (.always, .never, or conditional).

// Create an MCP tool for connecting to a remote server
let mcpTool = Tool.mcpTool(
    .init(
        _type: .mcp,
        serverLabel: "GitHub_MCP_Server",
        serverUrl: "https://api.githubcopilot.com/mcp/",
        headers: .init(additionalProperties: [
            "Authorization": "Bearer YOUR_TOKEN_HERE"
        ]),
        allowedTools: .case1(["search_repositories", "get_file_contents"]),
        requireApproval: .case2(.always)
    )
)

let query = ChatQuery(
    messages: [
        .user(.init(content: .string("Search for Swift repositories on GitHub")))
    ],
    model: .gpt4_o,
    tools: [mcpTool]
)

While optimized for OpenAI, this SDK supports other providers by using specific parsingOptions in the OpenAI.Configuration. This allows the SDK to handle responses that do not strictly adhere to the OpenAI API schema.

Option 1: Relaxed Parsing

Use the .relaxed parsing option to handle both missing keys and additional key/value pairs in responses. This is the recommended approach for most non-OpenAI use cases.

Option 2: Specific Parsing Options

If .relaxed is insufficient, you can target specific schema discrepancies:

• Handle missing keys: If a provider omits a field that OpenAI considers required (e.g., Gemini omitting the id field), use .fillRequiredFieldIfKeyNotFound.
• Handle missing values: If a provider returns null for a field that OpenAI requires to be non-optional, use .fillRequiredFieldIfValueNotFound.

Supported Additional Fields

The SDK automatically maps certain provider-specific fields into the main model set:

• ChatResult.citations: Supported by Perplexity.
• ChatResult.Choice.Message.reasoningContent: Supported by Grok and DeepSeek.
• ChatResult.Choice.Message.reasoning: Supported by OpenRouter.

You can define schemas by implementing the JSONSchemaConvertible protocol on your Swift types (similar to Pydantic or Zod).

Requirements:

1. The type must conform to JSONSchemaConvertible and provide a static let example: Self property.
2. All enum types within the provided type must conform to JSONSchemaEnumConvertible and implement var caseNames: [String] { get } to return an array of all case names.

struct MovieInfo: JSONSchemaConvertible {
    
    let title: String
    let director: String
    let release: Date
    let genres: [MovieGenre]
    let cast: [String]
    
    static let example: Self = {
        .init(
            title: "Earth",
            director: "Alexander Dovzhenko",
            release: Calendar.current.date(from: DateComponents(year: 1930, month: 4, day: 1))!,
            genres: [.drama],
            cast: ["Stepan Shkurat", "Semyon Svashenko", "Yuliya Solntseva"]
        )
    }()
}
enum MovieGenre: String, Codable, JSONSchemaEnumConvertible {
    case action, drama, comedy, scifi
    
    var caseNames: [String] { Self.allCases.map { $0.rawValue } }
}
let query = ChatQuery(
    messages: [
        .system(
            .init(content: .textContent("Best Picture winner at the 2011 Oscars"))
        )
    ],
    model: .gpt4_o,
    responseFormat: .jsonSchema(
        .init(
            name: "movie-info",
            description: nil,
            schema: .derivedJsonSchema(MovieInfo.self),
            strict: true
        )
    )
)
let result = try await openAI.chats(query: query)

You can define a JSON schema using simple Dictionaries or a schema library by wrapping the dictionary in an AnyEncodable type that conforms to Encodable. This allows you to pass a dynamic schema via .derivedJsonSchema (or similar) to the responseFormat or text parameters.

struct AnyEncodable: Encodable {
    private let _encode: (Encoder) throws -> Void
    public init<T: Encodable>(_ wrapped: T) {
        _encode = wrapped.encode
    }
    func encode(to encoder: Encoder) throws {
        try _encode(encoder)
    }
}
let schema = [
    "type": AnyEncodable("object"),
    "properties": AnyEncodable([
        "title": AnyEncodable([
            "type": AnyEncodable("string")
        ]),
        "director": AnyEncodable([
            "type": AnyEncodable("string")
        ]),
        "release": AnyEncodable([
            "type": AnyEncodable("string")
        ]),
        "genres": AnyEncodable([
            "type": AnyEncodable("array"),
            "items": AnyEncodable([
                "type": AnyEncodable("string"),
                "enum": AnyEncodable(["action", "drama", "comedy", "scifi"])
            ])
        ]),
        "cast": AnyEncodable([
            "type": AnyEncodable("array"),
            "items": AnyEncodable([
                "type": AnyEncodable("string")
            ])
        ])
    ]),
    "additionalProperties": AnyEncodable(false)
]
let query = ChatQuery(messages: [.system(.init(content: .textContent("Return a structured response.")))], model: .gpt4_o, responseFormat: .jsonSchema(.init(name: "movie-info", schema: .dynamicJsonSchema(schema))))
let result = try await openAI.chats(query: query)

You can build a schema in a type-safe manner using initializers that accept [JSONSchemaField]. This is a direct but more verbose method of defining a schema structure.

let query = CreateModelResponseQuery(
    input: .textInput("Return structured output"),
    model: .gpt4_o,
    text: .jsonSchema(.init(
        name: "research_paper_extraction",
        schema: .jsonSchema(.init(
            .type(.object),
            .properties([
                "title": Schema.buildBlock(
                    .type(.string)
                ),
                "authors": .init(
                    .type(.array),
                    .items(.init(
                        .type(.string)
                    ))
                ),
                "abstract": .init(
                    .type(.string)
                ),
                "keywords": .init(
                    .type(.array),
                    .items(.init(
                        .type(.string)
                    ))
                )
            ]),
            .required(["title, authors, abstract, keywords"]),
            .additionalProperties(.boolean(false))
        )),
        description: "desc",
        strict: false
    ))
)

let response = try await openAIClient.responses.createResponse(query: query)
for output in response.output {
    switch output {
    case .outputMessage(let message):
        for content in message.content {
            switch content {
            case .OutputTextContent(let textContent):
                print("json output structured by the schema: ", textContent.text)
            case .RefusalContent(let refusal):
                // Handle refusal
                break
            }
        }
    default:
        // Handle other OutputItems
        break
    }
}

You can enable function calling by defining tools within a ChatQuery. Use ChatQuery.ChatCompletionToolParam.FunctionDefinition to describe your functions, including their name, description, and JSON Schema parameters. Pass these tools to the tools argument in the ChatQuery initializer. When the model decides to call a function, the toolCalls property on the message will be populated.

let openAI = OpenAI(apiToken: "...")

// Declare functions which model might decide to call.
let functions = [
    ChatQuery.ChatCompletionToolParam.FunctionDefinition(
        name: "get_weather",
        description: "Get current temperature for a given location.",
        parameters: .init(fields: [
            .type(.object),
            .properties([
                "location": .init(fields: [
                    .type(.string),
                    .description("City and country e.g. Bogotá, Colombia")
                ])
            ]),
            .required(["location"]),
            .additionalProperties(.boolean(false))
        ])
    )
]

let query = ChatQuery(
    messages: [
        .user(.init(content: .string("What is the weather like in Paris today?")))
    ],
    model: .gpt4_1,
    tools: functions.map { .init(function: $0) }
)

let result = try await openAI.chats(query: query)
print(result.choices[0].message.toolCalls)