Armorial

Armorial은 로컬 우선, 디자인 시스템 인식 아이콘 워크벤치이자 인간과 AI 에이전트를 위한 결정론적 서비스입니다. 기존 IconPark 지오메트리를 검색하고, 하나의 실행 가능한 프로젝트 정책을 적용하며, 웹 UI, 라이브러리, CLI 또는 MCP 서버를 통해 동일한 승인된 자산을 반환합니다.

모델에게 SVG를 그리도록 요청하지 않습니다. 또한 임의의 채워진 아이콘 라이브러리가 stroke-width를 변경하여 정규화될 수 있다고 가정하지 않습니다.

작동 중인 기능

• @icon-park/svg@1.4.2의 모든 2,658개 아이콘에 대한 검증된 로컬 인덱스.

• 이름, 제목, 카테고리, 태그, 복수형 및 간결한 UI 별칭에 대한 영어 및 중국어 간체 검색.

• 테마, 크기, 선 두께, 캡, 조인, 색상, 표면별 재정의 및 의미론적 아이콘 선택을 위한 프로젝트 정책.

• 동등한 의미론적 후보가 정책에 의해 고정되지 않은 경우 명시적 모호성.

• 결정론적 SVG(안정적인 내부 클립 경로 ID, 정확한 아이콘별 viewBox, 바이트 수, 해시, 라이선스, 기능 및 실행 가능한 정책 준수 필드 포함).

• 검색/찾아보기, 미리보기, SVG 복사, 다운로드 및 표준 기반 외부 드래그 기능을 갖춘 독립형 시각적 워크벤치.

• 명시적 연결 및 선택 및 계속 작업이 포함된 선택적 MCP 앱 피커; 일반적인 인간 사용은 에이전트를 필요로 하지 않음.

• 5개의 모델 지향 MCP 도구: resolve_icon, search_icons, get_icon, get_icons, 그리고 명시적 시각적 결정 경로 choose_icon.

• MCP 앱 가시성 메타데이터에 의해 모델 사용에서 제외된 앱 전용 browse_icons 헬퍼; 적용은 호스트 측에서 이루어짐.

• 인간 검사 및 셸 구성을 위한 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를 복사합니다.

• 다운로드는 .svg 파일을 저장합니다.

• 아이콘 셀을 외부로 드래그하면 앱이 image/svg+xml, 일반 SVG 텍스트 및 다운로드 전송을 제공합니다. 브라우저 드래그를 대상이 수락하는지 여부는 대상에 의해 제어되므로, 복사 및 다운로드가 보장된 전달자입니다.

• 에이전트용 복사는 SVG가 아닌 간결한 [icon-selection:v1] 결정을 복사합니다. 에이전트 대화에 붙여넣어 정확한 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 파일을 쓰지 않습니다. 인간이 의도적으로 대상을 선택할 때 파이프 또는 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. ICON_SVG_SELECT_POLICY 환경 변수(절대 경로 또는 작업 디렉토리 상대 경로), 플러그인 호스트 및 셸 프로필이 실행 인수를 변경하지 않고 주입할 수 있음; 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/(소스 맵 제외)를 제공하므로, 수명 주기 스크립트를 실행하지 않고 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 하에 유지됩니다. 렌더링된 결과는 해당 라이선스를 식별합니다.