# apple-fm-mcp

[![CI](https://github.com/yihan2099/apple-fm-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/yihan2099/apple-fm-mcp/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

MCP server for Apple on-device Foundation Models. Use Apple Intelligence from any MCP client — Claude Code, Cursor, Windsurf — running locally on your Mac for free.

Built on [`python-apple-fm-sdk`](https://github.com/apple/python-apple-fm-sdk) and the [Model Context Protocol](https://modelcontextprotocol.io).

## Requirements

- macOS 26+ (Tahoe) with Apple Intelligence enabled
- Apple Silicon Mac (M1+)
- Python 3.10+
- [`apple-fm-sdk`](https://github.com/apple/python-apple-fm-sdk) — Apple's Python SDK for on-device Foundation Models

## Installation

### From source (recommended)

```bash
git clone https://github.com/yihan2099/apple-fm-mcp.git
cd apple-fm-mcp
uv sync
```

You also need the Apple Foundation Models SDK:

```bash
pip install git+https://github.com/apple/python-apple-fm-sdk.git
```

> **Note:** `apple-fm-mcp` is not yet published to PyPI. `uv tool install` and `pip install` from PyPI will be available in a future release.

## Usage

### Claude Code

```bash
claude mcp add apple-fm -- apple-fm-mcp
```

### Cursor / Windsurf

Add to your MCP config (`~/.cursor/mcp.json` or equivalent):

```json
{
  "mcpServers": {
    "apple-fm": {
      "command": "apple-fm-mcp"
    }
  }
}
```

### MCP Inspector

```bash
npx @modelcontextprotocol/inspector apple-fm-mcp
```

## Tools

| Tool | Description |
|------|-------------|
| `check_model_availability` | Check if the on-device model is available |
| `generate` | One-shot text generation with optional instructions |
| `generate_structured` | JSON output matching a provided schema |
| `chat` | Multi-turn conversation with named sessions |
| `tag_content` | Content tagging using Apple's CONTENT_TAGGING use case |
| `list_sessions` | List active conversation sessions |
| `clear_session` | Delete a named session |
| `clear_all_sessions` | Delete all sessions |

### Examples

**Generate text:**
> "Use apple-fm to explain what a closure is in Swift"

**Structured output:**
> "Use apple-fm generate_structured to extract {name, email, company} from this text: ..."

**Multi-turn chat:**
> "Start an apple-fm chat session called 'code-review' and ask it to review this function"
> "In the 'code-review' session, ask it to suggest improvements"

## Resources

| URI | Description |
|-----|-------------|
| `apple-fm://status` | Model availability + device info |
| `apple-fm://sessions` | Active sessions metadata |
| `apple-fm://transcript/{name}` | Conversation transcript for a session |

## Prompt Templates

| Prompt | Parameters | Description |
|--------|-----------|-------------|
| `summarize` | `text`, `style` (concise/detailed/bullet-points) | Summarize text |
| `extract_structured` | `text`, `fields` (comma-separated) | Extract named fields as JSON |
| `classify` | `text`, `categories` (comma-separated) | Single-label classification |

## Limitations

- **macOS only** — Apple Foundation Models require Apple Silicon and macOS 26+
- **No streaming** — MCP tools return complete responses
- **In-memory sessions** — conversation state is lost when the server restarts
- **On-device model limits** — the model is optimized for short tasks (summarization, extraction, classification), not long-form generation
- **No image/audio** — text-only; multimodal support may come in future SDK versions

## SDK Documentation

This project wraps [`apple-fm-sdk`](https://github.com/apple/python-apple-fm-sdk). Key references:

- [Official SDK docs](https://apple.github.io/python-apple-fm-sdk/) — getting started, guides, full API reference
- [Local API reference](docs/SDK_API_REFERENCE.md) — curated extract of the classes and enums used by this MCP server

## Development

```bash
git clone https://github.com/yihan2099/apple-fm-mcp.git
cd apple-fm-mcp
uv sync --dev
uv run pytest
```

Tests mock `apple_fm_sdk` so they run on any platform.

### Linting

```bash
uv run ruff check src/ tests/
uv run ruff format src/ tests/
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

MIT