# sf-symbol-mcp

Languages: English | [简体中文](README.zh-CN.md)

`sf-symbol-mcp` is a local MCP server and CLI that lets coding agents query real SF Symbol names from the SF Symbols app installed on your Mac.

It helps Codex, Claude Code, Cursor, and other MCP clients stop guessing `Image(systemName:)` values before generating SwiftUI or UIKit code.

## Important Legal Note

This is not an Apple project and is not affiliated with Apple.

SF Symbols and the SF Symbols app are Apple resources. This package does not distribute Apple artwork, plist metadata, generated indexes, or a complete symbol database. It reads metadata from the user's locally installed SF Symbols app and writes a local index on that user's machine.

Use SF Symbols for in-app interface icons such as tabs, toolbar buttons, list rows, and status indicators. Do not use SF Symbols directly as App Store icons, launcher icons, logos, brand marks, trademarks, or marketing logos.

## Requirements

- macOS for the official SF Symbols app metadata path
- Node.js 20 or newer
- SF Symbols app installed at `/Applications/SF Symbols.app`, or `SF_SYMBOLS_APP_PATH` pointing to another `.app`

The CLI can also build a limited local index from a user-provided names file with `--names-file`.

## Quick Start

```bash
npm install -g sf-symbol-mcp
sf-symbol-mcp inspect
sf-symbol-mcp build-index
sf-symbol-mcp search "income trend chart" --platform iOS --min-os 17.0
sf-symbol-mcp serve
```

From a local checkout:

```bash
npm install
npm run build
npm install -g .
```

By default, the generated index is stored outside the package:

- macOS: `~/Library/Application Support/sf-symbol-mcp/sf-symbols-index.json`
- Other platforms: `~/.cache/sf-symbol-mcp/sf-symbols-index.json`

Override this with:

```bash
export SF_SYMBOLS_INDEX_PATH="$HOME/.sf-symbol-mcp/sf-symbols-index.json"
```

## Local Development

```bash
npm install
npm run build
npm test
node dist/cli.js inspect
node dist/cli.js build-index
node dist/cli.js serve
```

## Codex Setup

After global install:

```bash
codex mcp add sf-symbols -- sf-symbol-mcp serve
```

From a local checkout:

```bash
npm install
npm run build
codex mcp add sf-symbols -- node /absolute/path/to/sf-symbol-mcp/dist/cli.js serve
```

Add the rules in `AGENTS.md` to Apple-platform app projects where agents should validate SF Symbols before use.

## Claude / Cursor MCP Setup

Use stdio transport with the installed CLI:

```json
{
  "mcpServers": {
    "sf-symbols": {
      "command": "sf-symbol-mcp",
      "args": ["serve"]
    }
  }
}
```

For a local checkout, use:

```json
{
  "mcpServers": {
    "sf-symbols": {
      "command": "node",
      "args": ["/absolute/path/to/sf-symbol-mcp/dist/cli.js", "serve"]
    }
  }
}
```

## CLI Reference

```bash
sf-symbol-mcp inspect
sf-symbol-mcp build-index [--output path] [--names-file path]
sf-symbol-mcp search "calendar work schedule" --platform iOS --min-os 17.0 --limit 10
sf-symbol-mcp get calendar.badge.clock --platform iOS --min-os 17.0
sf-symbol-mcp suggest --intent "premium income trend card" --tone "premium, calm, not financial trading" --platform iOS --min-os 17.0
sf-symbol-mcp validate gearshape.fill fake.symbol --platform iOS --min-os 17.0
sf-symbol-mcp scan ./MyApp
sf-symbol-mcp validate-project ./MyApp --platform iOS --min-os 17.0
sf-symbol-mcp serve
```

## MCP Tools

- `health_check`: reports server health, data source, generated index state, and symbol count.
- `search_symbols`: searches symbols by name, keyword, category, and lightweight semantic expansion.
- `get_symbol`: checks whether an exact symbol exists and returns usage snippets.
- `suggest_symbols`: recommends symbols for a product intent and blocks logo/App icon usage.
- `validate_symbols`: validates symbol names and target platform compatibility.
- `usage_snippet`: generates SwiftUI or UIKit snippets for a symbol.

## Environment Variables

- `SF_SYMBOLS_APP_PATH`: custom path to `SF Symbols.app`.
- `SF_SYMBOLS_INDEX_PATH`: custom path for the generated local JSON index.

## Troubleshooting

### `SF Symbols.app` not found

Install SF Symbols from Apple Developer, or set:

```bash
export SF_SYMBOLS_APP_PATH="/path/to/SF Symbols.app"
```

### Index not found

Run:

```bash
sf-symbol-mcp build-index
```

If the default cache directory is not writable, use `--output` or `SF_SYMBOLS_INDEX_PATH`.

### MCP server prints unexpected output

`sf-symbol-mcp serve` reserves stdout for MCP protocol messages. Logs and diagnostics must go to stderr. Avoid wrapping the command in scripts that print banners or debug output to stdout.

### Availability looks approximate

SF Symbols metadata exposes SF Symbols release versions, not a perfect platform matrix. This project maps release years to likely Apple platform minimum versions as a practical guardrail. Verify edge cases against the SF Symbols app or Apple's documentation.

## Publishing Notes

The npm package intentionally excludes local SF Symbols data. Before publishing, check:

```bash
npm run build
npm test
npm pack --dry-run
```

The tarball must not contain `SF Symbols Names`, `data/generated/*`, Apple plist files, `.DS_Store`, editor swap files, or local indexes.