SwiftMCP

SwiftMCP

iOS と macOS 向けの MCP (Model Context Protocol) クライアントを実装した Swift パッケージです。JSON-RPC インターフェースを通じてネイティブ API 統合を実現します。パッケージには OpenAI 互換の関数呼び出しブリッジも含まれています。

機能

• HealthKit のような Apple のネイティブ API のオープンソース関数定義
• JSON-RPC 2.0 準拠のインターフェース
• いくつかのテストカバレッジ

要件

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

インストール

Swift Package Manager

Package.swift ファイルに以下の依存関係を追加してください:

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

アーキテクチャ

使用法

基本的な設定

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 統合

この例では以下を示します:

1. HealthKit ツールを使用して MCP クライアントを設定
2. OpenAI ブリッジを作成してツールスキーマを登録
3. MCP ツールを OpenAI 関数定義に変換
4. OpenAI に初期リクエストを送信
5. MCP を通じてツール呼び出しを処理
6. ツール結果を OpenAI に送信して最終的な要約を取得

このフローにより OpenAI は以下の操作が可能になります:

• HealthKit の getData アクションを使用してステップ数データをリクエスト
• HealthKit の getWorkouts アクションを使用してワークアウトデータをリクエスト
• MCP を通じて実際のヘルスおよびワークアウトデータを受信
• データの自然言語による要約を提供

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")
}

注意: エラーを適切に処理し、「your-api-key」を実際の OpenAI API キーに置き換えてください。

OpenAI 関数呼び出しブリッジ

// 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)

JSON-RPC リクエストの処理

// 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)
}

カスタムツールの作成

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")])
        ]
    }
}

利用可能なツール

HealthKitTool

MCP インターフェースを通じて HealthKit データへの包括的なアクセスを提供します。

メソッド

• healthKit

  • アクション:

    • getData: ヘルスメトリクスを取得

      • パラメータ:
        • dataType: 取得するヘルスデータの種類（例："stepCount"、"heartRate"）
        • timeRange（オプション）: 定義済みの範囲（"today"、"yesterday"、"this_week" など）
        • duration（オプション）: ISO 8601 形式の期間文字列（例："P7D" は 7 日間）
      • 戻り値:
        • dataType: 取得したデータの種類
        • unit: 測定単位
        • samples: 値とタイムスタンプを含むデータポイントの配列

    • getWorkouts: ワークアウトデータを取得

      • パラメータ:
        • workoutType（オプション）: フィルタリングするワークアウトの種類（例："running"、"cycling"）
        • includeRoutes（オプション）: GPS ルートデータを含めるかどうかを示すブール値
        • timeRange（オプション）: 定義済みの範囲
        • duration（オプション）: ISO 8601 形式の期間文字列
      • 戻り値:
        • workouts: ワークアウトデータの配列（以下を含む）:
          • type: ワークアウトの種類
          • startDate: 開始タイムスタンプ
          • endDate: 終了タイムスタンプ
          • duration: 期間（秒単位）
          • distance（オプション）: 距離（メートル単位）
          • calories（オプション）: 消費エネルギー（キロカロリー単位）
          • route（オプション）: タイムスタンプ付きの GPS 座標の配列

エラーハンドリング

このパッケージは、以下を含む MCPError 型をエラーハンドリングに使用します:

• toolNotFound: 要求されたメソッドが存在しない場合
• invalidParams: リクエストパラメータが無効な場合
• toolError: ツール固有のエラーの汎用エラーケース（説明的なメッセージ付き）
• jsonParsingError: JSON パースに失敗した場合
• invalidRequest: JSON-RPC リクエスト形式が無効な場合

貢献

このリポジトリに可能な限り多くの iOS API を追加したいと考えています。目標は、iOS 開発向けの包括的な MCP 互換ツール集を作成することです。

すべての貢献を歓迎します。PR の提出をお気軽にしてください。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。詳細は LICENSE ファイルを参照してください。

MLX Swift インテグレーション

概要

SwiftMCP には、オンデバイスでローカルに実行される MLX モデルとのファンクションコーリング（ツール使用）のサポートが含まれるようになりました。この機能により、外部 API サービスに依存することなく、ツール使用機能を備えたローカル大規模言語モデルの力を活用できます。

セットアップ

MLX Swift のファンクションコーリングを使用するには、まずプロジェクトに MLX Swift 依存関係を追加します:

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")
]

基本的な使用方法

この例は以下を実演しています:

1. MLX ツールレジストリのセットアップ
2. MLX モデルの読み込みと初期化
3. MLX ブリッジへのツール登録
4. ツールコーリング機能を備えたテキスト生成

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)

サポートされているモデル

MLX インテグレーションは現在、以下のモデルアーキテクチャをサポートしています:

• Mistral（7B、8x7B）
• Llama（2、3）
• Phi

モデルの読み込み

モデルは MLX 形式である必要があり、MLX 変換ツールを使用して Hugging Face からモデルを変換することで取得できます。詳細な手順については、MLX リポジトリを参照してください。

MLX モデル用のカスタムツール作成

MLX モデル用のツール作成は、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"]
                }
            }
        }
        """
    }
}