Armorial

Armorialは、ローカルファーストでデザインシステムに対応したアイコンワークベンチであり、人間とAIエージェントのための決定論的なサービスです。既存のIconParkジオメトリを取得し、1つの実行可能なプロジェクトポリシーを適用し、Web UI、ライブラリ、CLI、またはMCPサーバーを通じて同じ承認済みアセットを返します。

モデルにSVGを描画させることはありません。また、stroke-widthを変更することで任意の塗りつぶしアイコンライブラリを正規化できると偽ることもありません。

動作しているもの

• @icon-park/svg@1.4.2の全2,658アイコンに対する検証済みローカルインデックス。

• 名前、タイトル、カテゴリ、タグ、複数形、コンパクトなUIエイリアスにわたる英語および簡体字中国語検索。

• テーマ、サイズ、ストローク幅、キャップ、結合、色、サーフェスごとのオーバーライド、およびセマンティックアイコン選択のためのプロジェクトポリシー。

• 同等のセマンティック候補がポリシーで固定されていない場合の明示的な曖昧性。

• 決定論的なSVG。安定した内部クリップパスID、アイコンごとの正確なviewBox、バイト数、ハッシュ、ライセンス、機能、実行可能ポリシー準拠フィールドを含む。

• ブラウズ/検索、プレビュー、SVGコピー、ダウンロード、標準ベースの外部ドラッグを備えたスタンドアロンのビジュアルワークベンチ。

• 明示的な「アタッチ」および「選択して続行」アクションを備えたオプションのMCP Appピッカー。通常の人間の使用ではエージェントは不要。

• 5つのモデル向けMCPツール：resolve_icon、search_icons、get_icon、get_icons、および明示的なビジュアル決定ルートchoose_icon。

• MCP Appの可視性メタデータによりモデル使用から除外された、アプリ専用のbrowse_iconsヘルパー。強制はホスト側。

• 人間の検査とシェル構成のためのCLI相当機能。

• 厳格な入出力スキーマ、制限付きクエリとバッチ、安全なカラー文法、制限付きSVG/応答サイズ、およびアイテムごとのバッチ障害。

• コピーしてチャットに貼り付け、接続された継続のための決定論的で制限付きのicon_selection決定形式。生のSVGや任意の命令は含まれません。

プロダクトモデルには、ユーザーフローと1コールのエージェントルート予算が記録されています。レビュー契約には、現在の敵対的シーケンスが記録されています。

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をビルドして起動します。

npm run build
npm run start:ui

http://127.0.0.1:4178を開きます。検索またはブラウズして1つのアイコンを選択し、次の操作を行います。

• SVGをコピー：生のSVGをコピーし、それを受け入れる任意のエディタで直接使用できます。

• ダウンロード：.svgファイルを保存します。

• アイコンセルを外側にドラッグします。アプリはimage/svg+xml、プレーンなSVGテキスト、およびダウンロード転送を提供します。ブラウザのドラッグを受け入れるかどうかは宛先によって制御されるため、コピーとダウンロードが保証されたキャリアです。

• エージェント用にコピー：SVGではなく、コンパクトな[icon-selection:v1]決定をコピーします。エージェントの会話に貼り付けて、正確なIDとポリシーレンダリングされたアセットハッシュを保持します。

右側のインスペクタは、有効なプロジェクトポリシーを報告します。これは意図的に2番目のポリシーエディタではありません。人間とエージェントが同じ選択されたアセットを再現できる必要があります。

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ファイルを書き込みません。人間が意図的に宛先を選択した場合に、パイプまたはstdoutをリダイレクトします。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つのポリシーファイルを次の順序で解決します。

1. ICON_SVG_SELECT_POLICY環境変数（絶対パスまたは作業ディレクトリからの相対パス）。プラグインホストとシェルプロファイルは起動引数を変更せずにこれを注入できます。Codexプラグインでは絶対パスを使用します。宣言された作業ディレクトリはキャッシュされたプラグインルートであるためです。

2. サーバーの作業ディレクトリにあるicon-policy.json。これは、ホストがプロジェクトルートからサーバーを起動するときに、プロジェクトが独自のデザインシステムポリシーを固定する方法です。

3. 組み込みのデフォルトポリシー。

MCPツールは、パス、URL、生のSVG、またはソースコードを受け入れません。

主要なエージェントリクエストは1回の呼び出しで行う必要があります。

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

ポリシーがそのセマンティックインテントを固定している場合、結果には選択されたIDとレンダリングされたSVGが含まれます。複数の候補が同じ基準を持つ場合、結果はambiguousとなり、ジオメトリを生成せずに候補をリストします。

人間が明示的に視覚的に比較したい場合、または以前の選択を拒否した場合は、次を使用します。

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

MCP Apps対応ホストは同じピッカーを開きます。グリッドクリックはローカルプレビューのみを変更します。「会話にアタッチ」は将来のモデルコンテキストを更新します。「選択して続行」は、型指定された決定を明示的なユーザーメッセージとして送信します。MCP Appsのないホストは、4つの直接ツールとスタンドアロンUI/コピーのフォールバックを引き続き使用します。

リポジトリルートはCodexプラグインバンドルでもあります。plugin.json、.mcp.json、および簡潔な説明用のプロダクトスキルはすべて、同じビルド済みサーバーにルーティングされます。公開されたtarballは自己完結型です。npm packはprepackを実行し、ビルド済みのdist/（ソースマップは除外）を出荷するため、ライフサイクルスクリプトを実行せずに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のままです。レンダリングされた結果はそのライセンスを識別します。