AppleFoundationMCPTool

A Swift package that acts as a dynamic bridge between Apple's FoundationModels framework (or AnyLanguageModel)and any server implementing the Model Context Protocol (MCP).

A Note on This Project

This project was largely developed by AI agents as a technical demonstration of integrating Apple's FoundationModels framework with the Model Context Protocol (MCP).

While functional, it should be considered a proof-of-concept rather than a production-ready solution. The practical utility is currently limited by the context size of the models available in the FoundationModels framework, which can make it challenging for the model to effectively use tools with complex input schemas or lengthy descriptions. Switching to AnyLanguageModel fixes this problem that allowing bigger models

Overview

With the introduction of new on-device AI capabilities in macOS 26.0, Apple's FoundationModels framework provides a powerful way to interact with large language models. This project enables that new framework to communicate with a broader ecosystem of tools and servers by leveraging the open-standard Model Context Protocol.

AppleFoundationMCPTool discovers tools available on an MCP server at runtime and dynamically creates corresponding FoundationModels.Tool objects. This allows an LLM within a FoundationModels session to see and execute external tools without needing to know their specifics at compile time.

Features

• Dynamic Tool Bridging: Automatically discovers and wraps MCP tools for use with FoundationModels.
• Flexible Connections: Supports connecting to MCP servers via two methods:
  • HTTP/SSE: Connects to a remote MCP server at a given URL.
  • Stdio: Launches a local MCP server executable and communicates with it over standard input/output.
• Process Management: Automatically manages the lifecycle of the server process when using a stdio connection.
• Modern & Type-Safe: Built with modern Swift concurrency (async/await) and leverages the latest FoundationModels APIs.

Requirements

• macOS 26.0+
• Swift 6.0+
• An MCP-compliant server or server executable.

Usage

The primary entry point for this library is the MCPToolBridge class.

1. Add the Package Dependency

Add the following to your Package.swift file:

dependencies: [
    .package(url: "https://github.com/your-username/AppleFoundationMCPTool.git", from: "1.0.0")
]

Then add the dependency to your target:

.target(
    name: "YourTarget",
    dependencies: [
        "AppleFoundationMCPTool"
    ]
)

2. Initialize the Bridge

You can initialize the MCPToolBridge in one of two ways, depending on your server setup.

Option A: Connect to an HTTP Server

Use this method if you have an MCP server running and listening on a specific URL.

import AppleFoundationMCPTool
import Foundation

let serverURL = URL(string: "http://127.0.0.1:8000/mcp")!
let bridge = MCPToolBridge(serverURL: serverURL)

Option B: Launch a Local Executable (Stdio)

Use this method to have the bridge launch and manage a local MCP server executable, communicating with it over stdin/stdout.

import AppleFoundationMCPTool

let serverPath = "/path/to/your/mcp_server_executable"
let bridge = MCPToolBridge(executablePath: serverPath)

3. Connect and Use Tools

Once the bridge is initialized, you can connect to the server, discover its tools, and use them in a FoundationModels session.

import AppleFoundationMCPTool // Will also import FoundationModels or AnyLanguageModel, depending on how the Package was built

// Assuming you have a SessionManager or similar class to manage the LLM session
do {
    // Connect to the server and get the dynamically created Apple Foundation tools
    let tools = try await bridge.connectAndDiscoverTools()
    print("Successfully discovered \(appleTools.count) tools.")

    let session = LanguageModelSession(model: model, tools: tools) 

    // You can now use the session, and the LLM will be able to see and call the tools.
    let response = try await session.prompt("Use the 'add' tool to calculate 5 + 7.")
    print(response)

} catch {
    print("An error occurred: \(error.localizedDescription)")
}

// Don't forget to disconnect when you're done.
// This will also terminate the server process if it was launched by the bridge.
await bridge.disconnect()

Example Targets

This project includes two executable targets to demonstrate its functionality.

AppleFoundationMCPToolChat (Recommended Example)

This is a fully interactive command-line chat application that demonstrates the end-to-end functionality of the bridge. It connects to an MCP server, registers the discovered tools, and allows you to chat with an LLM that can use those tools.

How to Run

1. Modify main.swift: Open Sources/AppleFoundationMCPToolChat/main.swift and configure the MCPToolBridge initialization to point to your MCP server (either via URL or executable path).
2. Run from the command line:

   swift run AppleFoundationMCPToolChat
   

AppleFoundationMCPToolExample

This target contains various conceptual code snippets. It is less of a working example and more of a scratchpad that shows different ways the library components could be used. For a practical, working demonstration, please refer to the AppleFoundationMCPToolChat example.