Overview

This project provides an MCP (Model Context Protocol) server that wraps Apple’s FoundationModels to expose a simple, networked text-generation API. It lets you run FoundationModels locally on Apple silicon or on macOS environments and access those models through the MCP-compatible HTTP endpoints. The server handles model loading, prompt handling, streaming responses, and basic usage limits so you can integrate Apple-backed text generation into web services, mobile apps, or backend pipelines.

For developers, the server reduces integration friction: instead of embedding model-specific code in each app, you run a single process that adheres to MCP conventions and translates incoming requests into FoundationModels calls. This makes it easier to scale, monitor, and swap underlying models while keeping client integrations stable.

Features

MCP-compatible HTTP endpoints for text generation and model metadata
Adapter to Apple FoundationModels (runs on macOS / Apple silicon)
Configurable model selection, token limits, and timeouts
Streaming and non-streaming response modes
Simple rate limiting and request logging hooks
Docker / local run options for development and deployment
Example clients and curl usage for quick testing

Installation / Configuration

Prerequisites

macOS on Apple Silicon or other Apple-compatible environment where FoundationModels can be used
Swift 5.9+ (if running the Swift implementation locally) or Docker for containerized execution
Xcode / command-line tools if building from source

Clone the repository:

git clone https://github.com/phimage/mcp-foundation-models.git
cd mcp-foundation-models

Run locally with Swift (example):

# Build
swift build -c release

# Run (reads config from ./config.yml or environment variables)
.build/release/mcp-foundation-models

Run with Docker:

# Build image
docker build -t mcp-foundation-models .

# Run container (expose port 8080)
docker run -p 8080:8080 \
  -e MCP_PORT=8080 \
  -e MCP_MODEL="apple-text-1" \
  mcp-foundation-models

Example configuration file (config.yml):

server:
  host: "0.0.0.0"
  port: 8080

model:
  name: "apple-text-1"   # replace with a model name supported by FoundationModels
  max_tokens: 1024
  temperature: 0.7

limits:
  max_requests_per_minute: 60
  max_concurrent_requests: 4

Environment variables (common):

MCP_PORT — port the server listens on (default: 8080)
MCP_MODEL — default model name used for generation
MCP_MAX_TOKENS — default maximum tokens to generate
MCP_LOG_LEVEL — logging verbosity

Available Resources

Source code and examples: https://github.com/phimage/mcp-foundation-models
Apple FoundationModels documentation: consult Apple Developer site for model names and platform requirements
MCP (Model Context Protocol) reference: use the MCP specification to understand request/response shapes and compatibility
Example clients: the repo contains sample curl commands and minimal client snippets for Node.js and Swift (see examples/)

API Examples

List models (GET):

curl http://localhost:8080/mcp/models

Synchronous generation (POST):

curl -X POST http://localhost:8080/mcp/generate \
  -H "Content-Type: application/json" \
  -d '{
    "model": "apple-text-1",
    "input": "Write a short developer-friendly explanation of MCP.",
    "parameters": {"max_tokens": 150, "temperature": 0.5}
  }'

Streaming generation (server-sent events):

curl -N -X POST http://localhost:8080/mcp/generate?stream=true \
  -H "Content-Type: application/json" \
  -d '{"model":"apple-text-1","input":"Write a poem about code."}'

The server will send incremental chunks as they are produced by the FoundationModels backend.

Use Cases

In-app assistants: host a local MCP server on-device (Apple silicon) to provide privacy-preserving, low-latency suggestions and completions in macOS or iOS companion apps.
Content generation pipeline: centralize text generation for email campaigns, knowledge-base drafts, or product descriptions behind a uniform API so multiple services can consume the same model logic.
Documentation and code helpers: power IDE plugins or CI jobs that generate code snippets, changelogs, or documentation, keeping model-specific configuration in one place.
Prototyping and testing: run different FoundationModels or tweak parameters centrally while client teams iterate against a stable MCP endpoint.

Notes and Best Practices

Platform: FoundationModels are provided by Apple and typically require macOS and Apple silicon for local execution; verify compatibility and licensing with Apple Developer documentation.
Model selection: pick model names supported by your local FoundationModels runtime. The server simply forwards options—ensure resource limits (RAM/CPU) fit the selected model.
Security: place the MCP server behind authentication or internal network controls if exposing it to production traffic. Treat generated content carefully and validate outputs before presenting to end users.
Monitoring: enable request logging and attach standard metrics to watch request rates, latencies, and model invocation errors.

For more detailed examples and platform-specific notes, see the repository: https://github.com/phimage/mcp-foundation-models.

FoundationModels MCP Server for Apple Text Generation