MCP SVG to Font

MCP SVG to Font

一个用于从 SVG 文件生成和管理图标字体的模型上下文协议（MCP）服务。此工具提供全面的字体生成功能，并支持向后兼容和高级字形提取。

✨ 功能

• 🎨 SVG 转字体：将 SVG 图标转换为多种字体格式（TTF、WOFF、WOFF2）
• 📝 CSS 生成：自动生成包含 font-face 声明和图标类的 CSS
• 🔷 TypeScript 支持：生成类型定义，实现类型安全的图标使用
• 🔄 扩展字体：在保留向后兼容性的同时，向现有字体添加新图标
• 🔍 高级字形提取：无需原始 SVG，即可从 TTF 文件中提取现有字形
• 📁 目录扫描：列出并分析目录中的 SVG 文件
• 🤖 AI 集成：全面兼容模型上下文协议，支持与 AI Agent 集成

📋 前置条件

• Node.js：20.x 或更高版本

🚀 快速开始（npm）

使用此 MCP 服务最简单的方式是通过 npm。无需克隆或构建。

1. 添加到 MCP 客户端

Cursor — 添加到 .cursor/mcp.json 或全局 MCP 设置：

{
  "mcpServers": {
    "mcp-svg-to-fonts": {
      "command": "npx",
      "args": ["-y", "mcp-svg-to-fonts"]
    }
  }
}

Claude Desktop — 添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "mcp-svg-to-fonts": {
      "command": "npx",
      "args": ["-y", "mcp-svg-to-fonts"]
    }
  }
}

2. 验证是否正常运行

npx -y mcp-svg-to-fonts

服务会启动并等待 stdio 输入——这表示它已就绪。使用 Ctrl+C 停止。

3. 在项目中使用

将 MCP 工具指向存放 SVG 图标的文件夹。例如，向 AI 助手提问：

“从 ./src/assets/icons 中的 SVG 生成图标字体，并输出到 ./fonts”

此服务提供 4 个工具：list-svgs、generate-font-from-svgs、extend-existing-font 和 extend-font-advanced。

🛠️ 开发

如需贡献或进行本地开发，你需要 pnpm 10.x。

克隆并构建

git clone https://github.com/omy13/mcp-svg-to-fonts.git
cd mcp-svg-to-fonts
pnpm install
pnpm build

开发模式

pnpm dev

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector npx tsx src/main.ts

本地 MCP 配置（不使用 npm）

{
  "mcpServers": {
    "mcp-svg-to-fonts": {
      "command": "npx",
      "args": ["tsx", "src/main.ts"],
      "cwd": "/path/to/mcp-svg-to-fonts"
    }
  }
}

或者使用编译后的构建：

{
  "mcpServers": {
    "mcp-svg-to-fonts": {
      "command": "node",
      "args": ["./dist/main.js"],
      "cwd": "/path/to/mcp-svg-to-fonts"
    }
  }
}

🛠️ 可用工具

1. list-svgs

用途：扫描并列出目录中的所有 SVG 文件

参数：

• directory（字符串，必需）：要扫描 SVG 文件的目录路径

使用场景：

• 在生成字体前盘点可用图标
• 检查 SVG 文件的结构和命名
• 批量处理前进行质量保证

示例：

{
  "directory": "./icons"
}

2. generate-font-from-svgs

用途：从一组 SVG 文件创建全新的图标字体

参数：

• directory（字符串，必需）：包含 SVG 文件的目录
• fontName（字符串，可选）：字体系列名称（默认值："IconFont"）
• outputDir（字符串，可选）：输出目录（默认值："./fonts"）
• formats（数组，可选）：要生成的字体格式（默认值：["woff2", "woff", "ttf"]）
• cssPrefix（字符串，可选）：CSS 类前缀（默认值："icon"）
• generateTypes（布尔值，可选）：是否生成 TypeScript 类型（默认值：true）

使用场景：

• 从头开始创建字体
• 完整搭建图标系统
• 从图标库迁移到自定义字体

生成的文件：

• FontName.ttf、FontName.woff、FontName.woff2
• 包含 font-face 和图标类的 FontName.css
• 包含 TypeScript 定义的 FontName.types.ts

3. extend-existing-font

用途：向现有字体添加新图标，同时保留所有现有图标及其 Unicode 值

参数：

• existingFontDir（字符串，必填）：包含现有字体文件（.css 和字体文件）的目录
• originalSvgDirectory（字符串，必填）：包含用于创建现有字体的原始 SVG 文件的目录
• newSvgDirectory（字符串，必填）：包含要添加的新 SVG 文件的目录
• fontName（字符串，可选）：字体名称（未提供时自动检测）
• outputDir（字符串，可选）：输出目录（默认与现有字体相同）
• cssPrefix（字符串，可选）：CSS 类前缀（未提供时自动检测）
• generateTypes（布尔值，可选）：生成 TypeScript 类型（默认：true）

使用场景：

• 向成熟的图标系统添加新图标
• 保持与现有应用程序的向后兼容性
• 增量扩展图标库

要求：

• 需要访问用于创建现有字体的原始 SVG 文件
• 需要现有 CSS 文件以检测 Unicode 映射

兼容性： ✅ 100% 向后兼容——现有项目无需更改即可继续运行

4. extend-font-advanced

用途：通过直接从 TTF 文件提取原始字形，向现有字体添加新图标，无需原始 SVG 文件

参数：

• existingFontDir（字符串，必填）：包含现有字体文件（.css 和 .ttf 文件）的目录
• newSvgDirectory（字符串，必填）：包含要添加的新 SVG 文件的目录
• fontName（字符串，可选）：字体名称（从文件中自动检测）
• outputDir（字符串，可选）：输出目录（默认与现有字体相同）
• cssPrefix（字符串，可选）：CSS 类前缀（从 CSS 中自动检测）
• generateTypes（布尔值，可选）：生成 TypeScript 类型（默认：true）
• preserveMetrics（布尔值，可选）：保留原始字体度量（默认：true）

使用场景：

• 扩展第三方图标字体
• 使用无法获取 SVG 源文件的旧版字体
• 对现有字体资源进行逆向工程和增强

高级功能：

• 字形提取：使用 OpenType.js 从 TTF 文件中提取矢量路径
• Unicode 保留：保留所有原始 Unicode 映射
• 字体度量保留：保留原始字体尺寸和间距
• CSS 集成：将提取的字形映射到 CSS 类名

要求：

• 原始 TTF 字体文件
• 包含 Unicode 映射的 CSS 文件（用于检测字形名称）
• 格式：CSS 类的格式类似 .icon-name:before { content: "\\e001"; }

技术流程：

1. 解析 TTF 文件以提取字形矢量数据
2. 将字形 Unicode 值映射到 CSS 类名
3. 将提取的字形转换回临时 SVG 文件
4. 将提取的字形与新 SVG 文件合并
5. 生成保留 Unicode 值的新字体

兼容性： ✅ 100% 向后兼容——所有原始图标均保留其 Unicode 值

📁 生成的字体结构

字体生成后，你将获得：

fonts/
├── IconFont.css          # CSS with font-face and icon classes
├── IconFont.ttf          # TrueType font
├── IconFont.woff         # Web Open Font Format
├── IconFont.woff2        # Web Open Font Format 2.0
└── IconFont.types.ts     # TypeScript type definitions

💻 使用示例

基本 HTML 用法

<!DOCTYPE html>
<html>
  <head>
    <link rel="stylesheet" href="./fonts/IconFont.css" />
  </head>
  <body>
    <i class="icon icon-home"></i>
    <i class="icon icon-user"></i>
    <i class="icon icon-settings"></i>
  </body>
</html>

CSS 样式

.icon {
  font-family: 'IconFont';
  font-size: 24px;
  color: #333;
}

.icon-home:before {
  content: '\e001';
}

TypeScript 集成

import { IconName, getIconClass, ICON_NAMES } from './fonts/IconFont.types';

// Type-safe icon usage
const iconName: IconName = 'home';
const className = getIconClass(iconName); // Returns "icon-home"

// Get all available icons
const allIcons = ICON_NAMES; // ['home', 'user', 'settings', ...]

React 组件示例

import { IconName, getIconClass } from './fonts/IconFont.types';

interface IconProps {
  name: IconName;
  className?: string;
}

const Icon: React.FC<IconProps> = ({ name, className = '' }) => {
  return <i className={`icon ${getIconClass(name)} ${className}`} />;
};

// Usage
<Icon name="home" className="text-blue-500" />;

🔄 工作流示例

场景 1：创建新的图标系统

1. 将 SVG 图标放入目录中
2. 使用 list-svgs 验证文件
3. 使用 generate-font-from-svgs 创建字体
4. 将生成的 CSS 和字体集成到项目中

场景 2：向现有字体添加图标

1. 将新的 SVG 文件放入目录中
2. 使用原始 SVG 文件运行 extend-existing-font
3. 用新字体文件替换旧字体文件
4. 现有代码继续运行，同时可使用新图标

场景 3：扩展第三方字体

1. 获取第三方字体的 TTF 文件和 CSS
2. 创建新的 SVG 图标
3. 使用 extend-font-advanced 合并它们
4. 获得同时包含原始图标和新图标的新字体

⚠️ 重要说明

字体扩展要求

• 对于 extend-existing-font：需要原始 SVG 文件
• 对于 extend-font-advanced：需要 TTF 文件和包含 Unicode 映射的 CSS

高级扩展的 CSS 格式

CSS 文件必须包含以下格式的 Unicode 映射：

.icon-home:before {
  content: '\e001';
}
.icon-user:before {
  content: '\e002';
}
.icon-settings:before {
  content: '\e003';
}

最佳实践

• 使用一致的 SVG 尺寸（最好为正方形）
• 生成字体前优化 SVG
• 在不同浏览器中测试字体
• 备份原始 SVG 文件
• 使用语义化的图标名称

🐛 故障排除

常见问题

“未找到 SVG 文件”

• 确认目录路径
• 确保 SVG 文件的扩展名为 .svg
• 检查文件权限

“检测到图标名称冲突”

• 重命名冲突的 SVG 文件
• 避免图标名称重复

“未找到 TTF 文件”

• 确保指定目录中存在 TTF 文件
• 检查文件扩展名（.ttf）

“无法解析现有字体”

• 检查 CSS 文件格式
• 确保包含 Unicode 映射