Armorial

Armorial 是一个本地优先、设计系统感知的图标工作台和确定性服务，适用于人类和 AI 代理。它检索现有的 IconPark 几何图形，应用一个可执行的项目策略，并通过 Web UI、库、CLI 或 MCP 服务器返回相同的已批准资产。

它不要求模型绘制 SVG。它也不假装可以通过更改 stroke-width 来标准化任意填充图标库。

当前可用的功能

• 已验证的本地索引，涵盖 @icon-park/svg@1.4.2 中的所有 2,658 个图标。

• 支持英文和简体中文搜索，包括名称、标题、类别、标签、复数形式和紧凑的 UI 别名。

• 项目策略，涵盖主题、大小、描边宽度、端点样式、连接样式、颜色、每表面覆盖以及语义图标选择。

• 当同等语义候选项未被策略固定时，明确显示歧义。

• 确定性 SVG，包括稳定的内部剪辑路径 ID、每个图标的精确 viewBox、字节数、哈希值、许可证、功能以及可执行策略合规字段。

• 独立的可视化工作台，支持浏览/搜索、预览、复制 SVG、下载以及基于标准的外部拖放。

• 可选的 MCP 应用程序选择器，具有明确的“附加”和“选择并继续”操作；普通人类使用永远不需要代理。

• 五个面向模型的 MCP 工具：resolve_icon、search_icons、get_icon、get_icons 以及显式的视觉决策路径 choose_icon。

• 一个仅应用程序的 browse_icons 辅助工具，通过 MCP 应用程序可见性元数据排除在模型使用之外；强制在主机端执行。

• 用于人类检查和 shell 组合的 CLI 等价工具。

• 严格的输入/输出模式、受限的查询和批处理、安全的颜色语法、受限的 SVG/响应大小以及每项批处理失败。

• 一个确定性的、受限的 icon_selection 决策格式，用于复制到聊天和连接的延续。它不包含原始 SVG 或任意指令。

产品模型 记录了用户流程和单次调用的代理路径预算。审查合同 记录了当前的对抗序列。

Related MCP server: brain-mcp-icon-visual

安装与验证

npm install
npm run check

npm run check 运行类型检查、负面/核心/CLI/MCP 测试、策略模式漂移检测、生产构建以及已构建 CLI 和 stdio MCP 服务器的新进程探测。

在安装此项目声明的 Playwright 管理的 Chromium 版本后，单独运行浏览器回归测试：

npx playwright install chromium
npm run ui:e2e

npm run ui:e2e 在启动浏览器之前重建 Node 服务器、独立 UI 和 MCP 应用程序资源，因此它永远不会验证过时的 dist 输出。

可视化工作台

构建并启动仅回环的本地 UI：

npm run build
npm run start:ui

打开 http://127.0.0.1:4178。搜索或浏览，选择一个图标，然后：

• 复制 SVG 复制原始 SVG，可直接用于任何接受它的编辑器。

• 下载 保存一个 .svg 文件。

• 向外拖动图标单元格；应用程序提供 image/svg+xml、纯 SVG 文本以及下载传输。目标是否接受浏览器拖动由该目标控制，因此复制和下载是保证的传输方式。

• 复制给代理 复制一个紧凑的 [icon-selection:v1] 决策，而不是 SVG。将其粘贴到代理对话中，以保留确切的 ID 和策略渲染的资产哈希。

右侧检查器报告有效的项目策略。它有意不作为第二个策略编辑器：人类和代理必须能够复现相同的选定资产。

CLI

# Compact candidate list
node dist/adapters/cli.js search settings --limit 5

# Structured resolution using the example project policy
node dist/adapters/cli.js resolve 设置 \
  --policy icon-policy.example.json \
  --context toolbar

# Pure SVG on stdout
node dist/adapters/cli.js get icon-park:search --format svg

# Validate a project policy
node dist/adapters/cli.js policy validate icon-policy.example.json

CLI 从不写入 SVG 文件。当人类有意选择目标时，使用管道或重定向标准输出。CLI 以与 MCP 服务器相同的方式解析其策略：--policy，然后是 ICON_SVG_SELECT_POLICY，然后是工作目录中的 ./icon-policy.json，最后是内置默认值。

MCP

首先构建，然后配置 MCP 客户端启动：

node /absolute/path/to/armorial/dist/adapters/mcp.js \
  --policy /absolute/path/to/project/icon-policy.json

策略是服务器操作员的启动决策，从来不是工具输入。当未提供 --policy 参数时，服务器在启动时解析一个策略文件，顺序如下：

1. ICON_SVG_SELECT_POLICY 环境变量（绝对路径或相对于工作目录的路径），插件主机和 shell 配置文件可以注入该变量而无需更改启动参数；对 Codex 插件使用绝对路径，因为其声明的工作目录是缓存的插件根目录；

2. 服务器工作目录中的 icon-policy.json，当主机从项目根目录启动服务器时，项目通过此文件固定其自己的设计系统策略；

3. 内置默认策略。

MCP 工具不接受路径、URL、原始 SVG 或源代码。

主要的代理请求应只需一次调用：

resolve_icon({ intent: "settings", context: "toolbar" })

如果策略已固定该语义意图，结果包括选定的 ID 和渲染的 SVG。如果多个候选项具有相同的基础，结果将是 ambiguous 并列出候选项，而不生成几何图形。

当人类明确要求视觉比较或拒绝先前选择时，使用：

choose_icon({ intent: "notification", requestId: "optional-correlation" })

支持 MCP 应用程序的主机打开相同的选择器。网格点击仅更改本地预览。“附加到对话”更新未来的模型上下文；“选择并继续”将键入的决策作为显式用户消息发送。不支持 MCP 应用程序的主机继续使用四个直接工具以及独立 UI/复制后备方案。

仓库根目录也是一个 Codex 插件包：plugin.json、.mcp.json 以及简洁的描述性产品技能都指向同一个已构建的服务器。发布的 tarball 是自包含的：npm pack 运行 prepack 并打包构建的 dist/（排除 source maps），因此那些安装 npm 包但不运行生命周期脚本的主机可以直接启动入口点。

对于本地主机测试，运行 npm run plugin:check。它会从确切的 npm pack 内容组装被忽略的 plugins/armorial/ 目录，从 package-lock.json 安装生产依赖而不运行生命周期脚本，为暂存清单提供一个新的本地 Codex 缓存破坏者，并使用项目策略探测隔离的 MCP 入口。.agents/plugins/marketplace.json 指向该生成的目录，因此新克隆必须先运行此命令，然后再添加本地市场。暂存交换拒绝符号链接祖先，并且不会暴露部分写入的插件。结果不包含任何源代码、测试、开发依赖、包锁或 Git 数据。更改插件后，重新运行命令，重新安装，并启动新的 Codex 会话，以便缓存副本更新。对于 npm publish 后的公共分发，将市场条目切换到 npm 源：

"source": {
  "source": "npm",
  "package": "armorial",
  "version": "0.1.0",
  "registry": "https://registry.npmjs.org"
}

策略

从 icon-policy.example.json 开始。selections 是项目拥有的语义决策层：

{
  "selections": {
    "settings": "icon-park:setting-two",
    "设置": "icon-park:setting-two"
  }
}

结构模式是 icon-policy.schema.json，并从运行时 Zod 模型生成。未知字段被拒绝。policy validate 额外检查语义键规范化冲突以及所选图标 ID 是否存在于固定的提供者中。

size 和 strokeWidth 是最终渲染的 CSS 像素值。提供者将在询问 IconPark 渲染之前，将该可见描边宽度转换为源 viewBox 单位，因此一个 2 在 20px 或 24px 输出大小时仍然是 2px 描边。

架构

Standalone UI ─┐
CLI ───────────┼── adapters ── IconKernel ── validated search index ── @icon-park/svg
MCP tools ─────┤                    │
MCP App UI ────┘                    ├── policy + semantic selections
                                    ├── ambiguity and stable errors
                                    └── deterministic, sanitized SVG result

故意没有云账户、共享的 lastSelection、策略编辑器、后备集合或仅限 Figma 的产品分支。未来的 Figma 适配器应使用相同的 SVG 和选择合同，而不是重新创建其规则。

许可证

本项目根据 Apache License 2.0 许可；请参阅 LICENSE 和 NOTICE。IconPark 代码和资产仍受 Apache-2.0 许可；渲染结果标识该许可证。