Armorial

Armorial ist eine lokale, designsystembewusste Icon-Werkbank und ein deterministischer Dienst für Menschen und KI-Agenten. Er ruft vorhandene IconPark-Geometrie ab, wendet eine ausführbare Projektrichtlinie an und liefert dasselbe genehmigte Asset über eine Web-UI, eine Bibliothek, eine CLI oder einen MCP-Server.

Er bittet kein Modell darum, SVG zu zeichnen. Er gibt auch nicht vor, dass beliebige gefüllte Icon-Bibliotheken durch Änderung von stroke-width normalisiert werden können.

Was bereits funktioniert

• Validierter lokaler Index über alle 2.658 Symbole in @icon-park/svg@1.4.2.

• Englische und vereinfachte chinesische Suche über Namen, Titel, Kategorien, Tags, Pluralformen und kompakte UI-Aliasse.

• Projektrichtlinie für Theme, Größe, Strichstärke, Linienenden, Verbindungen, Farben, Übersteuerungen pro Oberfläche und semantische Symbolauswahlen.

• Explizite Mehrdeutigkeit, wenn gleichwertige semantische Kandidaten nicht durch die Richtlinie festgelegt sind.

• Deterministisches SVG, einschließlich stabiler interner Clip-Pfad-IDs, exaktem ViewBox pro Symbol, Byteanzahl, Hash, Lizenz, Fähigkeit und Feldern zur Einhaltung der ausführbaren Richtlinie.

• Eigenständige visuelle Werkbank mit Durchsuchen/Suchen, Vorschau, SVG kopieren, Herunterladen und standardbasiertem Ziehen nach außen.

• Optionaler MCP-App-Auswähler mit expliziten Aktionen „Anhängen“ und „Auswählen und fortfahren“; die normale menschliche Nutzung erfordert nie einen Agenten.

• Fünf modellorientierte MCP-Werkzeuge: resolve_icon, search_icons, get_icon, get_icons und der explizite visuelle Entscheidungsweg choose_icon.

• Ein reiner App-Helfer browse_icons, der durch MCP-App-Sichtbarkeitsmetadaten von der Modellnutzung ausgeschlossen ist; die Durchsetzung erfolgt hostseitig.

• CLI-Entsprechungen für die menschliche Inspektion und Shell-Komposition.

• Strenge Eingabe-/Ausgabeschemata, begrenzte Abfragen und Stapel, sichere Farbgrammatik, begrenzte SVG-/Antwortgrößen und Stapelfehler pro Element.

• Ein deterministisches, begrenztes icon_selection-Entscheidungsformat zum Kopieren in den Chat und für die verbundene Fortsetzung. Es enthält weder rohes SVG noch beliebige Anweisungen.

Das Produktmodell dokumentiert die Benutzerabläufe und das Ein-Aufruf-Agenten-Routenbudget. Der Überprüfungsvertrag dokumentiert die aktuellen adversarischen Sequenzen.

Related MCP server: brain-mcp-icon-visual

Installation und Überprüfung

npm install
npm run check

npm run check führt Typprüfungen, Negativ-/Kern-/CLI-/MCP-Tests, Erkennung von Richtlinienschema-Abweichungen, den Produktionsbuild und eine Frischprozess-Sonde der gebauten CLI und des Stdio-MCP-Servers aus.

Führen Sie die Browser-Regressionsstrecke separat aus, nachdem Sie die von diesem Projekt deklarierte, von Playwright verwaltete Chromium-Version installiert haben:

npx playwright install chromium
npm run ui:e2e

npm run ui:e2e baut den Node-Server, die eigenständige UI und die MCP-App-Ressource neu, bevor der Browser gestartet wird, sodass niemals veraltete dist-Ausgabe validiert wird.

Visuelle Werkbank

Erstellen und starten Sie die nur auf Loopback erreichbare lokale UI:

npm run build
npm run start:ui

Öffnen Sie http://127.0.0.1:4178. Suchen oder durchsuchen Sie, wählen Sie ein Symbol aus, dann:

• SVG kopieren kopiert das rohe SVG zur direkten Verwendung in einem Editor, der es akzeptiert.

• Herunterladen speichert eine .svg-Datei.

• Ziehen Sie eine Symbolzelle nach außen; die App stellt image/svg+xml, reinen SVG-Text und einen Download-Transfer bereit. Ob ein Ziel einen Browser-Drag akzeptiert, steuert das Ziel selbst; Kopieren und Herunterladen sind daher die garantierten Übertragungswege.

• Für Agenten kopieren kopiert eine kompakte [icon-selection:v1]-Entscheidung, nicht das SVG. Fügen Sie sie in eine Agenten-Unterhaltung ein, um die genaue ID und den richtlinienbasiert gerenderten Asset-Hash zu bewahren.

Der rechte Inspektor meldet die effektive Projektrichtlinie. Er ist bewusst kein zweiter Richtlinieneditor: Ein Mensch und ein Agent müssen in der Lage sein, dasselbe ausgewählte Asset zu reproduzieren.

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

Die CLI schreibt niemals SVG-Dateien. Leiten Sie die Standardausgabe weiter (Pipe oder Umleitung), wenn ein Mensch bewusst ein Ziel wählt. Die CLI löst ihre Richtlinie auf dieselbe Weise wie der MCP-Server: --policy, dann ICON_SVG_SELECT_POLICY, dann ./icon-policy.json im Arbeitsverzeichnis, dann die eingebaute Standardrichtlinie.

MCP

Zuerst bauen, dann einen MCP-Client für den Start konfigurieren:

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

Die Richtlinie ist eine Entscheidung des Serverbetreibers beim Start, niemals eine Werkzeugeingabe. Wenn kein --policy-Argument angegeben wird, löst der Server beim Start genau eine Richtliniendatei auf, in dieser Reihenfolge:

1. die Umgebungsvariable ICON_SVG_SELECT_POLICY (absoluter oder arbeitsverzeichnisrelativer Pfad), die Plugin-Hosts und Shell-Profile injizieren können, ohne die Startargumente zu ändern; verwenden Sie beim Codex-Plugin einen absoluten Pfad, da dessen deklariertes Arbeitsverzeichnis das zwischengespeicherte Plugin-Wurzelverzeichnis ist;

2. eine icon-policy.json im Arbeitsverzeichnis des Servers; so legt ein Projekt seine eigene Designsystem-Richtlinie fest, wenn der Host den Server aus dem Projektstammverzeichnis startet;

3. die eingebaute Standardrichtlinie.

MCP-Werkzeuge akzeptieren keine Pfade, URLs, rohes SVG oder Quellcode.

Die dominante Agentenanfrage sollte einen einzigen Aufruf benötigen:

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

Wenn die Richtlinie diese semantische Absicht festgelegt hat, enthält das Ergebnis die gewählte ID und das gerenderte SVG. Wenn mehrere Kandidaten dieselbe Grundlage haben, lautet das Ergebnis ambiguous und listet Kandidaten auf, ohne Geometrie zu erzeugen.

Wenn der Mensch explizit um einen visuellen Vergleich bittet oder eine frühere Wahl ablehnt, verwenden Sie:

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

Ein Host mit MCP-Apps öffnet denselben Auswähler. Klicks auf das Raster ändern nur die lokale Vorschau. Attach to conversation aktualisiert den zukünftigen Modellkontext; Select & continue sendet die eingegebene Entscheidung als explizite Benutzernachricht. Hosts ohne MCP-Apps verwenden weiterhin die vier direkten Werkzeuge und den Rückgriff auf die eigenständige UI bzw. das Kopieren.

Das Repository-Wurzelverzeichnis ist außerdem ein Codex-Plugin-Bundle: plugin.json, .mcp.json und das schlanke beschreibende Produkt-Skill führen alle zu demselben gebauten Server. Veröffentlichte Tarballs sind in sich geschlossen: npm pack führt prepack aus und liefert das gebaute dist/ (ohne Source-Maps), sodass Hosts, die npm-Pakete ohne Ausführung von Lebenszyklusskripten installieren, die Einstiegspunkte direkt starten.

Für lokale Host-Tests führen Sie npm run plugin:check aus. Es erstellt das ignorierte Verzeichnis plugins/armorial/ aus dem exakten Inhalt von npm pack, installiert Produktionsabhängigkeiten aus package-lock.json ohne Lebenszyklusskripte, versieht das bereitgestellte Manifest mit einem frischen lokalen Codex-Cachebuster und testet den isolierten MCP-Einstiegspunkt mit einer Projektrichtlinie. .agents/plugins/marketplace.json zeigt auf dieses erzeugte Verzeichnis. Daher muss ein frisches Klon diesen Befehl ausführen, bevor der lokale Marktplatz hinzugefügt wird. Der Staging-Tausch lehnt Symlink-Vorgänger ab und legt kein halb geschriebenes Plugin offen. Das Ergebnis enthält keine Quellen, Tests, Entwicklungsabhängigkeiten, Package-Lock oder Git-Daten. Nach einer Änderung am Plugin führen Sie den Befehl erneut aus, installieren neu und starten eine neue Codex-Sitzung, damit die zwischengespeicherte Kopie aktualisiert wird. Für die öffentliche Verteilung nach npm publish stellen Sie den Marktplatzeintrag auf eine npm-Quelle um:

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

Richtlinie

Beginnen Sie mit icon-policy.example.json. selections ist die projekteigene semantische Entscheidungsebene:

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

Das strukturelle Schema ist icon-policy.schema.json und wird aus dem Laufzeit-Zod-Modell erzeugt. Unbekannte Felder werden abgelehnt. policy validate prüft zusätzlich Kollisionen bei der Normalisierung semantischer Schlüssel und ob ausgewählte Symbol-IDs im festgelegten Anbieter existieren.

size und strokeWidth sind endgültig gerenderte CSS-Pixelwerte. Der Anbieter konvertiert diese sichtbare Strichstärke in die viewBox-Einheiten der Quelle, bevor er IconPark zum Rendern auffordert, sodass eine 2 bei 20px- und 24px-Ausgabegröße eine 2px-Strichstärke bleibt.

Architektur

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

Es gibt bewusst kein Cloud-Konto, kein gemeinsames lastSelection, keinen Richtlinieneditor, keine Fallback-Sammlung und keinen reinen Figma-Produktfork. Ein zukünftiger Figma-Adapter sollte dieselben SVG- und Auswahlverträge verwenden, anstatt deren Regeln neu zu erstellen.

Lizenzen

Dieses Projekt ist unter der Apache License 2.0 lizenziert; siehe LICENSE und NOTICE. IconPark-Code und -Assets bleiben unter Apache-2.0; gerenderte Ergebnisse weisen diese Lizenz aus.