SwiftMCP

A Swift Package that implements an MCP (Model Context Protocol) client for iOS and macOS, enabling native API integration through a JSON-RPC interface. The package also includes an OpenAI-compatible function calling bridge.

Features

- Open source function definitions for Apple's native APIs like HealthKit
- JSON-RPC 2.0 compliant interface
- Some test coverage

Requirements

- iOS 15.0+ / macOS 12.0+
- Swift 6.0+
- Xcode 15.0+

Installation

Swift Package Manager

Add the following dependency to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/compiler-inc/SwiftMCP.git", from: "1.0.0")
]

Architecture

Usage

Basic Setup

import SwiftMCP
// Create a tool registry

let registry = ToolRegistry()
// Create an MCP client with a response handler

let client = MCPClient(toolRegistry: registry) { response in

    print("Received response: \(response)")

}
// Register tools

do {

    let healthKitTool = try HealthKitTool()

    registry.register(tool: healthKitTool)

} catch {

    print("Failed to initialize HealthKit tool: \(error)")

}

OpenAI Integration

This example demonstrates:

1. Setting up the MCP client with HealthKit tool
2. Creating an OpenAI bridge and registering the tool schema
3. Converting MCP tools to OpenAI function definitions
4. Sending an initial request to OpenAI
5. Processing any tool calls through MCP
6. Sending the tool results back to OpenAI for final summarization

The flow allows OpenAI to:

- Request step count data using the HealthKit getData action
- Request workout data using the HealthKit getWorkouts action
- Receive the actual health and workout data through MCP
- Provide a natural language summary of the data

import SwiftMCP
import OpenAI
// 1. Set up MCP client and tools

let registry = ToolRegistry()

let client = MCPClient(toolRegistry: registry) { response in

    print("Received response: \(response)")

}
// Initialize HealthKit tool

let healthKitTool = try HealthKitTool()

registry.register(tool: healthKitTool)
// 2. Set up OpenAI bridge

let openAIRegistry = OpenAIToolRegistry()

let healthKitSchema = JSONSchema(

    type: .object,

    properties: [

        "action": .init(type: .string, enum: ["getData", "getWorkouts"]),

        "dataType": .init(type: .string, description: "Type of health data to retrieve (e.g., stepCount, heartRate)"),

        "timeRange": .init(type: .string, enum: ["today", "yesterday", "this_week", "last_week"]),

        "workoutType": .init(type: .string, enum: ["running", "cycling", "walking"]),

        "includeRoutes": .init(type: .boolean)

    ],

    required: ["action"]

)
// Register the HealthKit tool with its schema

openAIRegistry.registerTool(healthKitTool, schema: healthKitSchema)
// 3. Get OpenAI function definitions

let functions = try openAIRegistry.getOpenAIFunctions()
// 4. Create OpenAI client and chat request

let openAI = OpenAI(apiToken: "your-api-key")

let query = "What was my step count today and how many calories did I burn in my last run?"
let chatRequest = ChatRequest(

    model: .gpt4o,

    messages: [

        .init(role: .user, content: query)

    ],

    functions: functions,

    functionCall: "auto"

)
// 5. Send request to OpenAI

let result = try await openAI.chat(request: chatRequest)
// 6. Handle any tool calls from OpenAI

if let toolCalls = result.choices.first?.message.toolCalls {

    // Process each tool call through MCP

    let toolResponses = try await openAIRegistry.handleToolCalls(toolCalls)
// 7. Send follow-up request to OpenAI with tool results

    let followUpRequest = ChatRequest(

        model: .gpt4,

        messages: [

            .init(role: .user, content: query),

            result.choices.first!.message,

            .init(role: .assistant, content: nil, toolCalls: toolResponses)

        ]

    )
// 8. Get final summarized response

    let finalResult = try await openAI.chat(request: followUpRequest)

    print(finalResult.choices.first?.message.content ?? "No response")

}

Note: Make sure to handle errors appropriately and replace "your-api-key" with your actual OpenAI API key.

OpenAI Function Calling Bridge

// Create and set up the OpenAI bridge
let openAIRegistry = OpenAIToolRegistry()
// Register your MCP tools with their schemas

openAIRegistry.registerTool(healthKitTool, schema: healthKitToolSchema)
// Get OpenAI function definitions

let functions = try openAIRegistry.getOpenAIFunctions()
// Handle OpenAI tool calls

let toolCalls: [OpenAIBridge.ToolCall] = ... // from OpenAI response

let toolResponses = try await openAIRegistry.handleToolCalls(toolCalls)

Handling JSON-RPC Requests

// Example JSON-RPC request for health data
let request = JSONRPCRequest(
    jsonrpc: "2.0",
    method: "healthKit",
    params: [
        "action": .string("getData"),
        "dataType": .string("stepCount"),
        "timeRange": .string("today")
    ],
    id: "1"
)
// Example JSON-RPC request for workouts

let workoutRequest = JSONRPCRequest(

    jsonrpc: "2.0",

    method: "healthKit",

    params: [

        "action": .string("getWorkouts"),

        "workoutType": .string("running"),

        "includeRoutes": .bool(true),

        "timeRange": .string("last_week")

    ],

    id: "2"

)
if let data = try? JSONEncoder().encode(request) {

    try await client.handleIncomingMessage(data: data)

}

Creating Custom Tools

class CustomTool: MCPTool {
    let methodName = "custom/method"
func handle(params: [String: JSON]) async throws -> [String: JSON] {

        // Implement your custom functionality here

        return [

            "status": .string("success"),

            "result": .object(["data": .string("your data here")])

        ]

    }

}

Available Tools

HealthKitTool

Provides comprehensive access to HealthKit data through the MCP interface.

Methods

- healthKit

- Actions:

- getData: Retrieve health metrics

- Parameters:
- dataType: Type of health data to retrieve (e.g., "stepCount", "heartRate")
- timeRange (optional): Predefined range ("today", "yesterday", "this_week", etc.)
- duration (optional): ISO 8601 duration string (e.g., "P7D" for 7 days)
- Returns:
- dataType: The type of data retrieved
- unit: The unit of measurement
- samples: Array of data points with values and timestamps

- getWorkouts: Retrieve workout data
- Parameters:
- workoutType (optional): Type of workout to filter by (e.g., "running", "cycling")
- includeRoutes (optional): Boolean to include GPS route data
- timeRange (optional): Predefined range
- duration (optional): ISO 8601 duration string
- Returns:
- workouts: Array of workout data including:
- type: Workout type
- startDate: Start timestamp
- endDate: End timestamp
- duration: Duration in seconds
- distance (optional): Distance in meters
- calories (optional): Energy burned in kilocalories
- route (optional): Array of GPS coordinates with timestamps

Error Handling

The package uses the MCPError type for error handling, which includes:

- toolNotFound: When the requested method doesn't exist
- invalidParams: When the request parameters are invalid
- toolError: Generic error case for tool-specific errors with a descriptive message
- jsonParsingError: When JSON parsing fails
- invalidRequest: When the JSON-RPC request format is invalid

Contributing

I want to add as many iOS APIs as possible to this repo. The goal is to create a comprehensive collection of MCP-compatible tools for iOS development.

Any contributions are welcome! Please feel free to submit a PR.

License

This project is licensed under the MIT License - see the LICENSE file for details.

MLX Swift Integration

Overview

SwiftMCP now includes support for function calling (tool use) with MLX models running locally on-device. This feature allows you to leverage the power of local large language models with tool use capabilities without relying on external API services.

Setup

To use MLX Swift function calling, first add the MLX Swift dependency to your project:

dependencies: [
    .package(url: "https://github.com/compiler-inc/SwiftMCP.git", from: "1.0.0")
    .package(url: "https://github.com/ml-explore/mlx-swift", from: "0.21.0")
]

Basic Usage

This example demonstrates:

1. Setting up the MLX tool registry
2. Loading and initializing an MLX model
3. Registering tools with the MLX bridge
4. Generating text with tool calling capabilities

import SwiftMCP
import MLX
// 1. Set up MLX Tool Registry

let mlxRegistry = MLXToolRegistry()
// 2. Register tools

let weatherTool = WeatherTool()

mlxRegistry.registerTool(weatherTool, schema: WeatherTool.getJSONSchema())
// 3. Create model handler and load model

let modelType = MLXModelFactory.detectModelType(from: modelURL)

let modelHandler = MLXModelFactory.createModelHandler(

    modelType: modelType,

    toolRegistry: mlxRegistry

)
try await modelHandler.loadModel(from: modelURL)
// 4. Generate text with function calling

let prompt = "What's the weather like in San Francisco?"

let response = try await modelHandler.generateWithFunctionCalling(

    prompt: prompt,

    systemPrompt: "You are a helpful assistant with access to weather information.",

    parameters: [

        "temperature": 0.7,

        "max_tokens": 1024

    ]

)
print(response)

Supported Models

The MLX integration currently supports the following model architectures:

- Mistral (7B, 8x7B)
- Llama (2, 3)
- Phi

Model Loading

Models need to be in the MLX format, which can be obtained by converting models from Hugging Face using the MLX conversion tools. For detailed instructions, visit the MLX repository.

Creating Custom Tools for MLX Models

Creating tools for MLX models follows the same pattern as other tools in SwiftMCP:

class CustomTool: MCPTool {
    let methodName = "custom/method"
func handle(params: [String: JSON]) async throws -> [String: JSON] {

        // Implement your custom functionality here

        return [

            "status": .string("success"),

            "result": .object(["data": .string("your data here")])

        ]

    }
static func getJSONSchema() -> String {

        return """

        {

            "type": "function",

            "function": {

                "name": "custom_method",

                "description": "Performs a custom operation",

                "parameters": {

                    "type": "object",

                    "properties": {

                        "param1": {

                            "type": "string",

                            "description": "First parameter"

                        },

                        "param2": {

                            "type": "number",

                            "description": "Second parameter"

                        }

                    },

                    "required": ["param1"]

                }

            }

        }

        """

    }

}