mcp-font-split

English | API 参考 | English API | 行为说明

AI 生成代码声明

本项目由 AI 编程助理生成并持续维护。作者不对代码做任何保证，也不承担任何使用责任。代码按“原样”提供，不附带任何形式的担保。

一个 MCP (Model Context Protocol) 服务器，将 cn-font-split 封装为可由 AI agent 调用的字体分割、批量处理、目录整理和输出审计工具。

文档导航

Related MCP server: Font Tools MCP

目录结构不匹配速查

如果字体来自多个网站、压缩包解包目录、vendor dump 或混合根目录，先不要直接写入批量输出。推荐顺序是：

1. 用 inspect_font_inputs 只读预检目录。

2. 查看 inputDirectoryDecision.directoryOrganizationSafety 和 sourceLayoutMismatchSummary。

3. 如果需要整理，先调用 organize_font_directory + workflowPreset: "safe-preview"。

4. 只有审查计划后才使用 reviewed-write；它仍然只是 copy-only 写入 outputDir，不会移动、删除或重写源字体。

5. 对整理后的暂存目录重新执行 inspect_font_inputs，再进入 split_font_batch safe-preview 和最终输出审计。

非直觉点：organize_font_directory 的输出是“整理后的源目录暂存”，不是最终 web-font 拆分结果；最终结果仍必须由 split_font_batch 写出，并用 inspect_split_output 审计目录结构。 如果这个暂存目录里有 font-organization-manifest.json，inspect_split_output 会把它识别为 organized-font-source-staging，这时它仍然是暂存目录，不是最终拆分输出。

功能

• 将 TTF/OTF/TTC/OTC/WOFF/WOFF2 字体处理为 web-font 输出。

• 扫描、预检和批量处理字体目录。

• 在源目录混乱时生成整理计划，或非破坏性复制到暂存源目录。

• 使用 manifest 支持增量跳过和输出审计。

• 提供 get_agent_guidance，让 AI agent 用机器可读指南选择安全工作流。

• 提供 MCP 文档 resources 和 safe-batch-workflow prompt，让客户端可以直接发现项目文档和安全批量流程。

• 工具响应同时提供 structuredContent 和兼容旧客户端的 JSON 文本内容。

• 提供真实语料库 smoke suite，用复杂本地字体集合做代表性可靠性验证。

工具列表

MCP 资源和 Prompt

除工具外，服务还通过 MCP resources 暴露 README、API 和行为说明文档；通过 safe-batch-workflow prompt 提供“预检 → safe-preview → reviewed-write → 输出审计”的安全批量流程提示。支持 resources / prompts 的客户端可以直接从 MCP schema 发现这些入口。

常见工作流

1. 先让 agent 自我定位

{
  "tool": "get_agent_guidance",
  "arguments": {
    "workflow": "batch",
    "detailLevel": "compact"
  }
}

当目录形态、写入风险或下一步工具不确定时，先看 recommendedWorkflowPlan、nextToolDecisionSummary、toolSafetyQuickReference 和 responseFieldsToCheck。

2. 预检输入目录

{
  "tool": "inspect_font_inputs",
  "arguments": {
    "inputDir": "fonts",
    "maxFiles": 50000,
    "includeFiles": false
  }
}

先看 inputCountGuide、inputDirectoryDecision、inputDirectoryDecision.directoryOrganizationSafety、unsupportedFileDecision、unsupportedFileSummary、layout 和 maxFilesHit。压缩包和非字体文件会被报告为忽略项，不会被自动解压、复制或拆分。

3. 批量 safe-preview

{
  "tool": "split_font_batch",
  "arguments": {
    "inputDir": "fonts",
    "outputRoot": "split-output",
    "workflowPreset": "safe-preview",
    "limit": 50000,
    "maxFiles": 50000
  }
}

确认 dryRun: true、batchWarnings[]、dedupeDecisionSummary、batchPolicySummary、sourceSafetyDecision、recommendedNextActions[] 和 errors[] 后，再决定是否写入。

4. 审查后写入并审计输出

{
  "tool": "split_font_batch",
  "arguments": {
    "inputDir": "fonts",
    "outputRoot": "split-output",
    "workflowPreset": "reviewed-write",
    "limit": 50000,
    "maxFiles": 50000
  }
}

写入后运行：

{
  "tool": "inspect_split_output",
  "arguments": {
    "outDir": "split-output",
    "maxFiles": 200000,
    "includeFiles": false,
    "includeFamilies": false
  }
}

只有输出目录审计明确通过、没有扫描截断，并且结构诊断确认这是合格的拆分输出时，才把结果视为完成。字段级判定请看 API 参考 和 行为说明。

5. 源目录需要整理时

{
  "tool": "organize_font_directory",
  "arguments": {
    "inputDir": "fonts",
    "workflowPreset": "safe-preview",
    "includePlan": true,
    "maxFiles": 50000
  }
}

整理工具默认只返回计划。即使 reviewed-write，也只是 copy-only 写入 outputDir；它的输出是源目录式暂存，不是最终拆分输出。先用 inspect_font_inputs 检查暂存目录，再用 split_font_batch safe-preview。

关键风险

• ok: true 只表示工具按所选策略完成，不代表一定发生了正常多子集分片；优先看 resultType、outputMode、performedSplit、usedFallback、skipped 和 warnings。

• 所有路径都限制在 FONT_SPLIT_ROOT 内；工具响应里用 . 表示工作区根目录。

• 写入类工具完成后，不要只看 ok；还要看 sourceSafetyDecision、safetySummary、recommendedNextActions[] 和必要时的 inspect_split_output 审计结果。

• inputDirectoryDecision.directoryOrganizationSafety 是判断 organize_font_directory 是否可用、是否可能改动源文件的最短答案。

• organize_font_directory 不移动、不删除、不重写源字体；它写出的 outputDir 只是 copy-only 暂存源目录。

• split_font_batch 默认 batchNamingMode: "numeric-suffix"：先用裸名，只有真实冲突时才加 -1、-2 等稳定数字后缀。

• batchDedupeMode: "same-path" 只是路径/stem 级去重；batchDedupeMode: "font-identity" 会跨格式比较字体身份。

• font-identity 会按字体身份跨格式收敛等价 OTF/TTF/WOFF 输入；具体 name table 回退规则和诊断字段请看 API / 行为文档。

• .woff / .woff2 输入会先解压成 sfnt-like 数据，再进入处理流程。

• 显式传入的无效配置会被拒绝，而不是静默回退；需要默认行为时请省略该选项。

• 如果 outputRoot 位于 inputDir 内，真实写入仍会落在输入目录树里；描述“源目录树无写入”前必须检查 writesSourceTree 和 outputTreeInsideInputTree。

常用参数速览

批量自定义速查

完整参数、返回字段和错误形态请看 API 参考。

如何解释返回结果

这些字段是入口级阅读顺序，不替代 API 文档里的字段定义。

输出形态速查

安装

git clone https://github.com/WenZhimo/mcp-font-split.git
cd mcp-font-split
npm install

依赖的 cn-font-split WASM 资源会通过 postinstall 脚本准备；也可以手动运行：

npm run install:wasm

使用方式

作为 MCP Server

claude mcp add font-split -- node "/path/to/mcp-font-split/src/server.js"

独立运行

npm start
npm run batch:run -- . split-output 50000 50000 --dry-run

batch:run 是给 agent 和维护者使用的安全批量入口。默认真实运行走 reviewed-write；--dry-run 或 FONT_SPLIT_DRY_RUN=true 会走 safe-preview。需要稳定 JSON 时用 --json 或 FONT_SPLIT_JSON=true。无效 preset、环境变量、位置参数或配置值会被拒绝；完整 CLI 参数和错误字段以 API 参考 为准。

验证

npm run check
npm run check:compact
npm run --silent check:compact -- --json
npm run smoke:api-docs
npm run smoke:behavior-docs
npm run smoke:real-corpus-suite -- <字体语料目录>

npm run check 是推荐给 AI agent / CI 的入口。check:compact 用于快速看 syntax + smoke 是否都通过；smoke:real-corpus-suite 用真实语料做代表性可靠性门禁，不是逐字体或逐目录人工验收。真实语料 suite 会区分全库扫描数量和代表性抽样数量，并明确压缩包只作为忽略文件统计，不会被自动解压验证。

环境变量

致谢与来源

本项目封装并调用 cn-font-split，核心字体分割能力来自该项目。

许可证

本项目采用 Apache License 2.0。使用依赖项时也请遵守其各自许可证。