Armorial

Armorial — это локально-ориентированная, учитывающая дизайн-систему иконная рабочая среда и детерминированный сервис для людей и ИИ-агентов. Она извлекает существующую геометрию IconPark, применяет одну исполняемую политику проекта и возвращает тот же утверждённый актив через веб-интерфейс, библиотеку, CLI или MCP-сервер.

Она не просит модель рисовать SVG. Она также не делает вид, что произвольные библиотеки залитых иконок можно нормализовать, изменив stroke-width.

Что работает

• Проверенный локальный индекс по всем 2 658 иконкам в @icon-park/svg@1.4.2.

• Поиск на английском и упрощённом китайском по именам, заголовкам, категориям, тегам, множественным числам и компактным псевдонимам интерфейса.

• Политика проекта для темы, размера, толщины обводки, типа концовки, соединения, цветов, переопределений для каждой поверхности и семантического выбора иконок.

• Явная неоднозначность, когда равные семантические кандидаты не закреплены политикой.

• Детерминированный SVG, включая стабильные идентификаторы внутренних clip-path, точный viewBox для каждой иконки, количество байт, хеш, лицензию, возможности и поля соответствия исполняемой политике.

• Автономная визуальная рабочая среда для просмотра/поиска, предпросмотра, копирования SVG, скачивания и стандартного перетаскивания наружу.

• Опциональное MCP-приложение с явными действиями «Прикрепить» и «Выбрать и продолжить»; обычное использование человеком никогда не требует агента.

• Пять инструментов MCP для модели: resolve_icon, search_icons, get_icon, get_icons и явный визуальный маршрут принятия решений choose_icon.

• Один вспомогательный инструмент только для приложения browse_icons, исключённый из использования моделью через метаданные видимости MCP App; обеспечение на стороне хоста.

• Эквиваленты CLI для человеческой проверки и композиции в командной оболочке.

• Строгие схемы ввода/вывода, ограниченные запросы и пакеты, безопасная грамматика цветов, ограниченные размеры SVG/ответов и по-элементные сбои в пакетах.

• Детерминированный, ограниченный формат решения icon_selection для копирования в чат и связанного продолжения. Он не содержит сырого SVG или произвольных инструкций.

Модель продукта описывает потоки пользователей и бюджет маршрута для одного вызова агента. Контракт проверки описывает текущие состязательные последовательности.

Related MCP server: Svg/icons MCP

Установка и проверка

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 App перед запуском браузера, поэтому он никогда не проверяет устаревший вывод dist.

Визуальная рабочая среда

Соберите и запустите локальный UI только на loopback:

npm run build
npm run start:ui

Откройте http://127.0.0.1:4178. Найдите или просмотрите, выберите одну иконку, затем:

• Copy SVG копирует сырой SVG для прямого использования в любом редакторе, который его принимает.

• Download сохраняет .svg файл.

• перетащите ячейку иконки наружу; приложение предоставляет image/svg+xml, обычный текст SVG и передачу для скачивания. Принимает ли место назначения перетаскивание браузера, контролируется этим местом назначения, поэтому копирование и скачивание являются гарантированными носителями.

• Copy for Agent копирует компактное решение [icon-selection:v1], а не SVG. Вставьте его в разговор с агентом, чтобы сохранить точный идентификатор и хеш актива, отрисованного по политике.

Правая панель инспектора сообщает действующую политику проекта. Она намеренно не является вторым редактором политики: человек и агент должны иметь возможность воспроизвести тот же выбранный актив.

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 (абсолютный или относительный путь от рабочего каталога), которую хостинги плагинов и профили оболочки могут внедрить без изменения аргументов запуска; используйте абсолютный путь с плагином Codex, так как его объявленный рабочий каталог — это корень кэшированного плагина;

2. icon-policy.json в рабочем каталоге сервера, что позволяет проекту закрепить собственную политику дизайн-системы, когда хост запускает сервер из корня проекта;

3. встроенная политика по умолчанию.

Инструменты MCP не принимают пути, URL, сырой SVG или исходный код.

Доминирующий запрос агента должен занимать один вызов:

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

Если политика закрепила это семантическое намерение, результат включает выбранный идентификатор и отрисованный SVG. Если несколько кандидатов имеют одинаковую основу, результат — ambiguous и перечисляет кандидатов без создания геометрии.

Когда человек явно просит сравнить визуально или отклоняет предыдущий выбор, используйте:

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

Хост с поддержкой MCP Apps открывает тот же выборщик. Клики по сетке только меняют локальный предпросмотр. «Attach to conversation» обновляет будущий контекст модели; «Select & continue» отправляет типизированное решение как явное сообщение пользователя. Хосты без MCP Apps продолжают использовать четыре прямых инструмента и резервный вариант с автономным UI/копированием.

Корень репозитория также является пакетом плагина Codex: plugin.json, .mcp.json и тонкое описательное навык продукта все ведут к одному и тому же собранному серверу. Опубликованные тарболы самодостаточны: npm pack запускает prepack и поставляет собранную dist/ (без карт исходников), поэтому хосты, устанавливающие npm-пакеты без выполнения скриптов жизненного цикла, запускают точки входа напрямую.

Для локального тестирования хоста выполните npm run plugin:check. Он собирает игнорируемый каталог plugins/armorial/ из точного содержимого npm pack, устанавливает production-зависимости из package-lock.json без скриптов жизненного цикла, даёт подготовленному манифесту свежий локальный кэш-бастер Codex и проверяет изолированный MCP-вход с политикой проекта. .agents/plugins/marketplace.json указывает на этот сгенерированный каталог, поэтому в свежем клоне необходимо выполнить эту команду перед добавлением локального маркетплейса. Замена стадии отклоняет предков символьных ссылок и не раскрывает наполовину записанный плагин. Результат не содержит исходников, тестов, dev-зависимостей, блокировки пакетов или данных 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 дополнительно проверяет коллизии нормализации семантических ключей и то, существуют ли выбранные идентификаторы иконок в закреплённом провайдере.

size и strokeWidth — это конечные отрисованные значения в CSS-пикселях. Провайдер преобразует эту видимую толщину обводки в единицы исходного viewBox перед тем, как попросить IconPark отрисовать, поэтому 2 остаётся обводкой в 2px при выходном размере 20px или 24px.

Архитектура

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; отрисованные результаты идентифицируют эту лицензию.