vegavisuals

vegavisuals는 재사용 가능한 Vega-Lite 및 원시 Vega 시각화 팩토리입니다. 하나의 중앙 테마 레지스트리, 하나의 프로젝트 매니페스트/잠금 계약, stdio FastMCP 어댑터, 그리고 vl-convert-python==1.9.0.post1 기반의 Docker 렌더러를 제공합니다. 소비자 프로젝트는 Node, Chromium 또는 호스트에 Vega 설치가 필요하지 않습니다.

호스트 CLI는 Python 3.10 이상과 Linux가 필요합니다. 게시는 descriptor-relative I/O, flock, 그리고 fail-closed renameat2 연산을 사용하기 때문입니다. 렌더링에는 Docker도 필요합니다. Linux x86_64는 릴리스 테스트 호스트이며, 다른 Linux 아키텍처의 소스 설치에는 모든 고정 종속성에 대한 호환 휠이 필요합니다.

기본 호환성 프로필은 vl-convert-1.9.0입니다: 기본적으로 Vega 6.2.0, Vega-Lite 6.4, SVG/PNG/PDF 출력, qpdf를 사용한 결정적 PDF 정규화, 그리고 명시적으로 설치된 DejaVu 글꼴 패밀리입니다. 기본 이미지는 레지스트리 다이제스트로 고정됩니다. 지원되는 전체 Vega-Lite 버전 세트와 런타임 정책은 vegavisuals compatibility-status로 노출됩니다. 소스 데이터는 src/vegavisuals/assets/compat/vl-convert-1.9.0.json에 있습니다.

빠른 시작

git clone https://github.com/dosquartsdedocs/vegavisuals.git
cd vegavisuals
python3 -m pip install '.[mcp]'
vegavisuals build-renderer

vegavisuals --project /path/to/consumer validate charts/summary.vl.json
vegavisuals --project /path/to/consumer render \
  charts/summary.vl.json public/summary.svg
vegavisuals --project /path/to/consumer render-all
vegavisuals --project /path/to/consumer check

첫 번째 렌더러 빌드는 Debian 및 PyPI 저장소에 접근해야 합니다. 렌더 컨테이너 자체는 네트워크 접근 없이 실행되며 이미지를 가져오지 않습니다. 사전 빌드된 렌더러 이미지는 게시되지 않습니다. 각 설치 환경은 라이선스가 있는 소스 패키지와 고정된 호환성 프로필에서 로컬 이미지를 빌드합니다.

두 저장소 예제는 프로젝트 로컬 CSV를 사용한 Vega-Lite 막대 차트와 원시 Vega 차트를 다룹니다:

vegavisuals render examples/vega-lite/bar.vl.json dist/examples/bar.svg
vegavisuals render examples/vega/raw.vg.json dist/examples/raw-vega.svg

Related MCP server: nyyon-figures

렌더링 경계

모든 렌더는 이미지의 고정된 작업자 진입점을 사용합니다. 호스트 레지스트리는 다음을 수행합니다:

• JSON을 자체적으로 파싱하고 중복 키와 비유한 숫자를 거부합니다.

• 소스, 데이터, 입력, 매니페스트, 캐시, 잠금 및 출력 경로를 소비자 루트로 제한합니다.

• 캐시, 잠금 및 출력 파일을 descriptor-relative, no-follow Linux 연산을 통해 게시합니다.

• 프로젝트 파일 잠금으로 최종 커밋을 직렬화하고, renameat2로 정확한 파일 스냅샷을 조건부로 교체하며, 잠금 게시가 실패하면 출력을 롤백합니다.

• 모든 폐기된 게시 inode를 mode-0700 .cache/vegavisuals/replaced/ 디렉터리 아래로 원자적으로 이동하여, 이미 열린 descriptor를 통한 늦은 쓰기가 명시적 캐시 정리까지 복구 가능하도록 합니다.

• HTTP/HTTPS 데이터, 이미지, 하이퍼링크 및 동적 URL 종속성을 거부합니다.

• 로컬 데이터를 소스 파일 기준으로 해석하고 모든 종속성의 지문을 생성합니다.

• 소비자 프로젝트를 렌더러에 마운트하지 않습니다.

• 준비된 스펙과 스테이징된 출력만 격리된 호스트 임시 디렉터리의 /output:rw에 마운트합니다.

• Docker를 --network none, --read-only, 모든 capabilities 제거, no-new-privileges, 비-root UID/GID, CPU/메모리/PID/파일 제한, 그리고 제한된 tmpfs로 실행합니다. 루트 호출자는 65534:65534를 사용합니다.

• PNG 청크와 CRC, 정규화된 PDF 구조, 재귀적 SVG 안전성 및 출력 크기를 검증합니다.

• 검증된 아티팩트를 임시 형제 파일로 복사하고 호스트에서 대상 파일을 원자적으로 교체합니다.

컨테이너는 소비자 프로젝트에 직접 게시할 수 없습니다. 실패한 렌더는 기존 대상을 변경하지 않습니다.

복구 아카이브는 생성된 캐시 데이터이며 자동으로 제거되지 않습니다. 게시 충돌이 보고된 후 이를 검사하십시오. make clean 또는 수동 캐시 제거가 폐기 시점입니다. 프로젝트 잠금, 관리되는 출력 및 .cache/vegavisuals/replaced/는 게시와 복구가 원자적으로 유지되도록 동일한 파일 시스템에 있어야 합니다.

소스 및 데이터 정책

자동 엔진 선택은 먼저 정확한 .vl.json 및 .vg.json 접미사를 사용하고, 그 다음 인식된 $schema, 마지막으로 Vega-Lite mark 또는 원시 Vega marks 구조를 사용합니다. 명시적 --engine vega-lite 또는 --engine vega는 JSON 소스에도 작동합니다. 인식된 접미사는 명시적 엔진과 모순될 수 없습니다.

파일 소스는 정적 프로젝트 상대 data.url을 사용할 수 있습니다. 이는 소스 디렉터리에서 해석되며, 프로젝트 내부의 UTF-8 일반 파일이어야 하고, 선언되거나 추론된 CSV, TSV 또는 JSON 형식으로 원시 인라인 values로 스테이징됩니다. 이는 file: 로더 모호성을 피하면서 Vega의 자체 형식 파서를 보존합니다. 심볼릭 링크 및 .. 이스케이프는 거부됩니다. HTTP, HTTPS, 프로토콜 상대, file:, data: 및 동적 데이터 URL은 거부됩니다. 이미지 및 하이퍼링크 URL 채널도 거부되어 게시된 SVG가 오프라인 상태를 유지합니다.

render-text는 동일한 종속성 정책을 적용합니다: 모든 종속성 url 또는 href 키가 거부되므로 인라인 값만 허용됩니다. 입력 텍스트는 1 MiB로 제한됩니다. 캐시 키에는 소스, 엔진, 형식, 프로필 및 테마가 포함됩니다.

프로젝트 매니페스트

.vegavisuals.yml은 버전이 지정된 명시적 프로젝트 계약입니다:

version: 1
profile: vl-convert-1.9.0
family: benizar
visualizations:
  - name: quarterly-bars
    source: charts/quarterly.vl.json
    output: public/quarterly.svg
    engine: vega-lite
    format: svg
    inputs:
      - charts/data/quarterly.csv
  - name: raw-overview
    source: charts/overview.vg.json
    output: public/overview.pdf

engine, format 및 inputs는 선택 사항입니다. 입력은 스펙에서 발견된 데이터 파일을 보완하며 지문 생성에 참여합니다.

.vegavisuals.lock.json은 잠금 버전 2를 사용합니다. 각 항목은 소스, 출력, 엔진, 선택된 Vega-Lite 버전, 형식, 프로필, 패밀리, 완전한 렌더 지문, 출력 SHA-256, 입력 및 불변 렌더러 이미지 출처를 엄격하게 기록합니다. status는 다음 상태를 보고합니다:

이식 가능한 지문은 로컬 Docker 이미지 ID가 아닌 렌더러 계약을 사용합니다. 깨끗한 빌드는 동일한 고정 입력을 사용하면서 다른 이미지 메타데이터 ID를 가질 수 있습니다. 관찰된 이미지 ID는 출처로 기록되며, 이미지는 렌더링 전에 일치하는 렌더러 계약 레이블을 가져야 합니다.

--force가 전달되지 않으면 신선한 출력은 건너뜁니다. 기존의 비관리 및 수정된 출력은 --replace도 전달되지 않는 한 교체되지 않습니다. 동일한 게시 규칙이 직접 파일 렌더 및 render-text의 명시적 출력에도 적용됩니다.

잘못된 매니페스트 또는 잠금은 시각화별 invalid 상태를 생성하는 대신 status 및 check를 중단합니다.

CLI

JSON을 생성하는 운영 명령은 구조화된 JSON을 반환합니다. 오류도 JSON과 0이 아닌 상태를 반환합니다. 도움말 및 --version은 일반 CLI 텍스트를 사용하며, mcp serve는 JSON 명령 출력 대신 MCP stdio 전송을 사용합니다.

vegavisuals [--project ROOT] version
vegavisuals [--project ROOT] profile-inventory
vegavisuals [--project ROOT] theme-inventory [--family FAMILY]
vegavisuals [--project ROOT] compatibility-status [--profile PROFILE]
vegavisuals [--project ROOT] factory-check
vegavisuals [--project ROOT] validate SOURCE [--engine auto|vega-lite|vega] [--input PATH]
vegavisuals [--project ROOT] render SOURCE OUTPUT [--format svg|png|pdf] [--name NAME]
vegavisuals [--project ROOT] render-text [--text JSON] [--output PATH]
vegavisuals [--project ROOT] status [--manifest .vegavisuals.yml]
vegavisuals [--project ROOT] check [--manifest .vegavisuals.yml]
vegavisuals [--project ROOT] render-all [--manifest .vegavisuals.yml]
vegavisuals [--project ROOT] factory-manifest
vegavisuals [--project ROOT] build-renderer [--profile PROFILE]
vegavisuals [--project ROOT] ensure-renderer [--profile PROFILE]
vegavisuals [--project ROOT] mcp serve
vegavisuals [--project ROOT] mcp client-config
vegavisuals [--project ROOT] mcp list-tools

계약 인식 명령은 문서화된 --profile, --family, 입력, 매니페스트 및 게시 정책 옵션도 허용합니다. 전체 개요는 vegavisuals COMMAND --help를 실행하십시오.

render, render-text 및 render-all은 --include-data, --replace, --force 및 --dry-run을 허용합니다. 인라인 아티팩트 데이터는 기본적으로 생략됩니다. 요청 시 SVG는 artifact.svg로 반환되고, PNG 및 PDF는 artifact.data_base64로 반환됩니다. 호환성 프로필은 아티팩트 및 응답 크기를 제한합니다.

validate는 엄격한 JSON, 깊이, 숫자, 스키마 버전, URL 정책 및 기본 Vega/Vega-Lite 구조 검사를 수행합니다. 완전한 JSON Schema 또는 컴파일러 검증을 주장하지 않습니다. 고정된 작업자가 전체 렌더러 의미론에 대해 권위 있는 역할을 합니다.

Python API

공개 패키지는 Registry, __version__ 및 타입화된 예외 계층을 내보냅니다. 하나의 Registry 인스턴스는 소비자 루트를 고정합니다:

from vegavisuals import Registry

registry = Registry("/path/to/consumer")
registry.validate_visualization("charts/chart.vl.json")
registry.render_visualization("charts/chart.vl.json", "public/chart.svg")
registry.render_visualization_text(spec_json, output_format="png")
registry.visualization_status()
registry.visualization_check()
registry.render_visualizations()
registry.theme_inventory()
registry.compatibility_status()
registry.factory_manifest()

렌더러 수명 주기 메서드는 build_renderer() 및 ensure_renderer()입니다. 인벤토리 헬퍼는 profile_inventory(), factory_check() 및 version_status()입니다.

MCP

소비자 루트는 FastMCP 서버가 시작되기 전에 한 번 해석되며 MCP 도구 인수가 아닙니다:

vegavisuals --project /path/to/consumer mcp serve

도구:

validate_visualization
render_visualization
render_visualization_text
visualization_status
visualization_check
render_visualizations
theme_inventory
compatibility_status
factory_manifest

리소스:

vegavisuals://agent-guide
vegavisuals://themes
vegavisuals://compatibility
vegavisuals://project/status
vegavisuals://project/check
vegavisuals://factory-manifest

MCP 도구는 문서화된 사전 결과 계약을 유지합니다. 예상되는 정책, 검증 및 렌더 실패는 MCP 전송 오류가 아닌 ok: false가 있는 타입화된 애플리케이션 결과입니다. 클라이언트는 ok를 검사해야 합니다.

다음으로 클라이언트 구성 템플릿을 생성합니다:

vegavisuals mcp client-config --workspace-placeholder '${workspaceFolder}'

기본 자리 표시자는 ${workspaceFolder}를 확장하는 클라이언트를 위한 리터럴입니다. 클라이언트가 해당 확장을 수행하지 않는 경우 절대 소비자 경로로 교체하십시오. 실행 파일이 클라이언트 PATH에 없는 경우 --command /absolute/path/to/vegavisuals를 사용하고, VS Code의 작업 공간 형태에는 --format vscode-workspace를 사용하십시오.

검증

python3 -m pip install -e '.[mcp,dev]'
make check
make tests
make tests-install
make docker-smoke
make mcp-smoke

make tests는 Docker를 모의 상태로 유지합니다. make docker-smoke는 두 엔진 모두에 대해 모든 형식을 렌더링하고 지연된 PDF 바이트 반복성을 확인합니다. make mcp-smoke는 stdio를 통해 두 렌더 엔진을 호출합니다. 휠 검증은 비편집 모드로 설치하고, site-packages에서 자산을 해석하며, 설치된 휠 MCP 실행 파일을 통해 두 실제 렌더 엔진을 호출합니다.

기여 검사는 CONTRIBUTING.md를, 지원 버전 및 비공개 취약점 보고는 SECURITY.md를 참조하십시오.

라이선스

vegavisuals는 GNU General Public License v3.0 only (GPL-3.0-only)로 라이선스가 부여됩니다. Vega, Vega-Lite, vl-convert 및 기타 런타임 종속성은 원래 라이선스를 유지합니다. THIRD_PARTY_NOTICES.md를 참조하십시오. Copyright (C) 2026 dosquartsdedocs.

독립형 CLI, Docker 렌더러 또는 MCP 서버를 호출하는 것 자체로는 소비자 프로젝트 또는 생성된 SVG, PNG 및 PDF 아티팩트의 라이선스가 변경되지 않습니다. Python 패키지를 복사, 수정, 링크 또는 직접 배포하는 애플리케이션은 GPLv3 조건을 준수해야 합니다.