Armorial

Armorial es un banco de trabajo de iconos determinista y consciente del sistema de diseño, de prioridad local, para humanos y Agentes de IA. Recupera la geometría existente de IconPark, aplica una política de proyecto ejecutable y devuelve el mismo activo aprobado a través de una interfaz web, biblioteca, CLI o servidor MCP.

No pide a un modelo que dibuje SVG. Tampoco pretende que las bibliotecas de iconos rellenos arbitrarios puedan normalizarse cambiando stroke-width.

Lo que funciona

• Índice local validado de los 2.658 iconos en @icon-park/svg@1.4.2.

• Búsqueda en inglés y chino simplificado entre nombres, títulos, categorías, etiquetas, plurales y alias de interfaz de usuario compactos.

• Política de proyecto para tema, tamaño, ancho de trazo, extremo, unión, colores, anulaciones por superficie y selecciones semánticas de iconos.

• Ambigüedad explícita cuando candidatos semánticos iguales no están fijados por política.

• SVG determinista, incluyendo identificadores de clip-path internos estables, viewBox exacto por icono, recuento de bytes, hash, licencia, capacidad y campos de cumplimiento de política ejecutable.

• Banco de trabajo visual independiente con navegación/búsqueda, vista previa, Copiar SVG, descarga y arrastre externo basado en estándares.

• Selector opcional de MCP App con acciones explícitas de Adjuntar y Seleccionar y continuar; el uso humano ordinario nunca requiere un Agente.

• Cinco herramientas MCP orientadas al modelo: resolve_icon, search_icons, get_icon, get_icons y la ruta explícita de decisión visual choose_icon.

• Un ayudante browse_icons solo para la aplicación, excluido del uso del modelo mediante metadatos de visibilidad de MCP App; la aplicación se aplica en el lado del anfitrión.

• Equivalentes CLI para inspección humana y composición de shell.

• Esquemas estrictos de entrada/salida, consultas y lotes acotados, gramática de color segura, tamaños de SVG/respuesta limitados y fallos por lote por elemento.

• Un formato de decisión icon_selection determinista y acotado para copiar al chat y continuación conectada. No contiene SVG en bruto ni instrucciones arbitrarias.

El modelo de producto registra los flujos de usuario y el presupuesto de ruta de Agente en una sola llamada. El contrato de revisión registra las secuencias adversariales actuales.

Related MCP server: brain-mcp-icon-visual

Instalar y verificar

npm install
npm run check

npm run check ejecuta verificaciones de tipos, pruebas negativas/núcleo/CLI/MCP, detección de desviación del esquema de política, la compilación de producción y una sonda de proceso fresco del CLI compilado y el servidor MCP stdio.

Ejecute la línea de regresión del navegador por separado después de instalar la versión de Chromium gestionada por Playwright declarada por este proyecto:

npx playwright install chromium
npm run ui:e2e

npm run ui:e2e reconstruye el servidor Node, la interfaz de usuario independiente y el recurso de MCP App antes de lanzar el navegador, por lo que nunca valida la salida dist obsoleta.

Banco de trabajo visual

Construya y lance la interfaz de usuario local solo de bucle invertido:

npm run build
npm run start:ui

Abra http://127.0.0.1:4178. Busque o navegue, seleccione un icono, luego:

• Copiar SVG copia el SVG en bruto para uso directo en cualquier editor que lo acepte.

• Descargar guarda un archivo .svg.

• arrastre una celda de icono hacia afuera; la aplicación proporciona image/svg+xml, texto SVG plano y una transferencia de descarga. Si un destino acepta un arrastre del navegador está controlado por ese destino, por lo que copiar y descargar son los transportistas garantizados.

• Copiar para Agente copia una decisión compacta [icon-selection:v1], no el SVG. Péguela en una conversación de Agente para preservar el identificador exacto y el hash del activo renderizado por política.

El inspector derecho informa la política de proyecto efectiva. Intencionalmente no es un segundo editor de políticas: un humano y un Agente deben poder reproducir el mismo activo seleccionado.

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

El CLI nunca escribe archivos SVG. Canalice o redirija stdout cuando un humano elige deliberadamente un destino. El CLI resuelve su política de la misma manera que el servidor MCP: --policy, luego ICON_SVG_SELECT_POLICY, luego ./icon-policy.json en el directorio de trabajo, luego el valor predeterminado incorporado.

MCP

Construya primero, luego configure un cliente MCP para lanzar:

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

La política es una decisión de inicio del operador del servidor, nunca una entrada de herramienta. Cuando no se proporciona el argumento --policy, el servidor resuelve un archivo de política al inicio, en este orden:

1. la variable de entorno ICON_SVG_SELECT_POLICY (ruta absoluta o relativa al directorio de trabajo), que los complementos del anfitrión y los perfiles de shell pueden inyectar sin cambiar los argumentos de lanzamiento; use una ruta absoluta con el complemento Codex porque su directorio de trabajo declarado es la raíz del complemento en caché;

2. un icon-policy.json en el directorio de trabajo del servidor, que es como un proyecto fija su propia política de sistema de diseño cuando el anfitrión lanza el servidor desde la raíz del proyecto;

3. la política predeterminada incorporada.

Las herramientas MCP no aceptan rutas, URL, SVG en bruto ni código fuente.

La solicitud dominante del Agente debería tomar una sola llamada:

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

Si la política ha fijado esa intención semántica, el resultado incluye el identificador elegido y el SVG renderizado. Si varios candidatos tienen la misma base, el resultado es ambiguous y enumera los candidatos sin producir geometría.

Cuando el humano pide explícitamente comparar visualmente o rechaza una elección anterior, use:

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

Un anfitrión con capacidad de MCP Apps abre el mismo selector. Los clics en la cuadrícula solo cambian la vista previa local. Adjuntar a la conversación actualiza el contexto futuro del modelo; Seleccionar y continuar envía la decisión escrita como un mensaje de usuario explícito. Los anfitriones sin MCP Apps continúan usando las cuatro herramientas directas y la interfaz de usuario independiente/alternativa de copia.

La raíz del repositorio también es un paquete de complemento de Codex: plugin.json, .mcp.json y la Skill de producto descriptiva delgada, todos enrutan al mismo servidor compilado. Los tarballs publicados son autocontenidos: npm pack ejecuta prepack y envía el dist/ compilado (excluyendo mapas de origen), por lo que los anfitriones que instalan paquetes npm sin ejecutar scripts de ciclo de vida inician los puntos de entrada directamente.

Para pruebas locales del anfitrión, ejecute npm run plugin:check. Ensambla el directorio ignorado plugins/armorial/ desde el contenido exacto de npm pack, instala las dependencias de producción desde package-lock.json sin scripts de ciclo de vida, da al manifiesto preparado un nuevo cachebuster local de Codex y prueba la entrada MCP aislada con una política de proyecto. .agents/plugins/marketplace.json apunta a ese directorio generado, por lo que un clon nuevo debe ejecutar este comando antes de agregar el mercado local. El intercambio de preparación rechaza los ancestros de enlaces simbólicos y no expone un complemento a medio escribir. El resultado no contiene fuentes, pruebas, dependencias de desarrollo, bloqueo de paquetes ni datos de Git. Después de cambiar el complemento, vuelva a ejecutar el comando, reinstale e inicie una nueva sesión de Codex para que la copia en caché se actualice. Para distribución pública después de npm publish, cambie la entrada del mercado a una fuente npm:

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

Política

Comience desde icon-policy.example.json. selections es la capa de decisión semántica propiedad del proyecto:

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

El esquema estructural es icon-policy.schema.json y se genera a partir del modelo Zod en tiempo de ejecución. Los campos desconocidos son rechazados. policy validate adicionalmente verifica colisiones de normalización de claves semánticas y si los identificadores de iconos seleccionados existen en el proveedor fijado.

size y strokeWidth son valores finales renderizados en píxeles CSS. El proveedor convierte ese ancho de trazo visible en las unidades del viewBox de origen antes de pedir a IconPark que renderice, por lo que un 2 sigue siendo un trazo de 2px tanto en tamaño de salida de 20px como de 24px.

Arquitectura

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

Deliberadamente no hay cuenta en la nube, lastSelection compartido, editor de políticas, colección de respaldo o bifurcación de producto solo para Figma. Un futuro adaptador de Figma debería consumir los mismos SVG y contratos de selección en lugar de recrear sus reglas.

Licencias

Este proyecto está licenciado bajo la Licencia Apache 2.0; vea LICENSE y NOTICE. El código y los activos de IconPark permanecen bajo Apache-2.0; los resultados renderizados identifican esa licencia.