内容
# SF Symbols MCP
用于搜索和导出苹果 SF Symbols 作为真正的矢量 SVG 的 MCP 服务器。
SF Symbols MCP 允许 AI 代理和开发者搜索完整的 SF Symbols 目录，获取符号元数据，并将任何符号导出为矢量 SVG — 真实的贝塞尔曲线路径，而不是栅格化图像。它使用苹果的私有 CoreUI 框架从系统资产目录中提取实际的 glyph 数据。
---
## 快速入门
### 构建
需要安装 **macOS 14+** 和 Xcode 或命令行工具。
```bash
git clone https://github.com/ygrec-app/sf-symbols-mcp.git
cd sf-symbols-mcp
swiftc sf_symbol_cli.swift -o sf-symbol-cli -framework AppKit -framework CoreText
```
### 安装 Python 依赖
需要 [uv](https://docs.astral.sh/uv/):
```bash
uv sync
```
### 与 Claude Code (MCP) 一起使用
在项目级别的 `.mcp.json` 中添加:
```json
{
"mcpServers": {
"sf-symbols": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/sf-symbols-mcp",
"python",
"server.py"
]
}
}
}
```
将 `/path/to/sf-symbols-mcp` 替换为实际的仓库克隆路径。
然后询问 Claude: "为我找到一个用于通知的 SF Symbol" 或 "将 star.fill 符号导出为 SVG."
---
## MCP 工具
| 工具 | 描述 |
|------|-------------|
| `search_symbols` | 按名称或关键词搜索 SF Symbol 名称 |
| `get_symbol_info` | 获取可用性、相关符号和可渲染性信息 |
| `export_symbol` | 将符号导出为矢量 SVG，带有权重/大小选项 |
| `list_symbols` | 列出可用的 SF Symbol 名称 |
### 导出选项
| 参数 | 默认值 | 描述 |
|-----------|---------|-------------|
| `name` | 必需 | SF Symbol 名称（例如 `star.fill`，`chevron.right`） |
| `weight` | `regular` | ultralight, thin, light, regular, medium, semibold, bold, heavy, black |
| `size` | `100` | 渲染点大小 |
| `output_path` | 无 | 保存 SVG 的文件路径（如果省略则返回内容） |
| `raw_coords` | `false` | 输出原始 CoreGraphics Y-up 坐标而不是标准 SVG Y-down |
### 从 CLI 使用
Swift CLI 也可以直接使用:
```bash
./sf-symbol-cli search star
./sf-symbol-cli export star.fill --weight bold --size 200
./sf-symbol-cli export chevron.right --output ./icons/chevron.svg
./sf-symbol-cli info heart.fill
./sf-symbol-cli list --limit 50
```
---
## 工作原理
```
MCP 服务器（Python） Swift CLI
───────────────── ─────────────────────────────
FastMCP 工具处理程序 → CoreUI 私有框架
├── CUICatalog（Assets.car）
├── CUINamedVectorGlyph
└── CGPath → SVG 路径数据
```
SF Symbols 存储为苹果编译资产目录（`Assets.car`）中的矢量 glyph，位于 SFSymbols 私有框架中。Swift CLI 使用 Objective-C 运行时桥接访问 `CUICatalog` 并提取 `CGPath` 贝塞尔曲线数据，然后转换为 SVG `<path d="...">` 元素。
输出是真正的矢量 SVG（~1-2KB），带有实际的贝塞尔曲线 — 而不是嵌入在 SVG 中的栅格化 PNG。
---
## 要求
- **macOS 14+**（Sonoma 或更高版本）
- **Xcode** 或命令行工具（用于 Swift 编译器）
- **Python 3.13+**，带有 [uv](https://docs.astral.sh/uv/)
- **SF Symbols** 已内置于 macOS — 无需额外安装
---
## 许可证
MIT
