teguma

AI-native design bridge — Penpot MCP + brand context engine.

Figma/Claude Design의 페인포인트를 오픈소스로 해결합니다. AI 에이전트가 브랜드 컨텍스트를 유지하면서 Penpot 디자인을 읽고 쓸 수 있게 하는 MCP 서버입니다.

왜 teguma?

Related MCP server: ds-pilot

빠른 시작

설치

npm install -g teguma
# 또는
npx teguma

설정

환경변수:

export PENPOT_URL=https://your-penpot-instance.com
export PENPOT_TOKEN=your-mcp-key

Penpot에서 MCP 키 발급: 계정 → Integrations → MCP Server → 키 생성

Claude Code / Cursor에서 사용

.claude/settings.json 또는 MCP 설정에 추가:

{
  "mcpServers": {
    "teguma": {
      "command": "npx",
      "args": ["teguma"],
      "env": {
        "PENPOT_URL": "https://your-penpot.com",
        "PENPOT_TOKEN": "your-key"
      }
    }
  }
}

MCP 도구

총 24개 MCP 도구이며, 위 표의 디자인 엔진 도구는 12개다.

디자인 엔진

선언형 문서를 받아 채널별 사이즈로 리사이즈하고, 브랜드 키트를 적용하고, 검증한 뒤 내보내는 엔진입니다. Penpot 연결 없이도 동작합니다.

npm run design:demo          # 카드뉴스 3면 → PNG + PDF + 3개 채널 리사이즈
npm run design:gallery       # 12종 템플릿 PNG·104px 미리보기·리사이즈 비교·contact sheet

• 사이즈 프리셋 — 네이버 블로그 3종을 포함한 14종: 유튜브·인스타그램·페이스북·블로그·프레젠테이션·A4

• 리사이즈 4-모드 — fill 채우기, fit 맞추기, original 원본, adapt 종횡비 재구성. adapt는 원본 캔버스 전체(0,0·양축 일치)를 덮는 사각형만 가로 확장하고, 장식용 가로 밴드는 비율을 유지한다. fit의 무크롭 보장은 원본이 캔버스 안에 있을 때만 성립하며, 원래 밖의 레이어는 QA가 잡는다.

• 브랜드 키트 — 팔레트·폰트·로고 등록, 이탈 색상 자동 정규화와 로고 ID·소스까지 확인하는 위반 리포트

• 텍스트 측정·줄바꿈 — 등록 글꼴은 sfnt glyph advance로 측정한다. 굵기 미지정 시 등록 face 중 가장 넓은 advance를 쓰고, 등록되지 않은 글꼴은 문자군별 3em fallback을 쓴다. 음수 letterSpacing은 유한 수이면 허용하되 측정 폭을 가장 넓은 글리프 폭 아래로 내리지 않아, 과도한 음수 자간이 QA의 false fit을 만들지 않는다. 긴 토큰 분할, 줄 수 제한과 말줄임표를 지원한다.

• 자동 레이아웃·프리미티브·템플릿 — 41단계 결정론 글꼴 후보(기본 최소 60%), 기본 안전영역 내 성장 정책, 정렬·분배·측정 스택·세로 리듬, 12종 원본 채널 템플릿

• 자동 QA — 캔버스 이탈, 안전영역, 텍스트 불투명도를 배경과 합성한 4.5:1 대비·프레임 적합·완전 가림, 브랜드 준수. 둥근 사각형은 텍스트 프레임 전체가 유효 반지름 안쪽에 있을 때만 배경으로 인정하고, 그 밖과 이미지 배경은 fail-closed. exportDocument는 기본적으로 QA 실패를 거부하며 enforceQa: false로만 원시 렌더 가능

• 워크스페이스 정책 — check_design_policy는 NFKC 정규화 금지어·필수 문구, 승인 상태, 이미지·브랜드 색상·등록 프리셋·페이지 수 제한을 검사해 위반과 출고 허용 여부를 반환한다. regex는 리터럴·안전한 문자 클래스·^/$·리터럴/클래스 뒤의 {n}(0–64)만 허용하며 bare .·그룹·교대·escape class·{n,}/{n,m}는 거부한다. 줄바꿈으로 나뉜 한 텍스트 레이어의 용어는 잡지만, 레이어 간에는 읽기 순서를 신뢰할 수 없어 연결하지 않는다.

• 고전 이미지 처리 — process_design_image는 resolver 승인 원본을 순서대로 crop·scale·pad·단색 배경 제거·trim하고 동일한 hardened export writer로 PNG를 쓴다. 축 8,192px·16,000,000px 제한을 적용한다.

• 이미지·글꼴·저장 경계 — 이미지 resolver는 O_NOFOLLOW descriptor의 inode·크기(20MiB)를 확인해 제한된 바이트만 읽고, 출력은 디렉터리 inode 재검증·독점 no-follow 생성·regular file/link count 확인을 한다. Node에 openat가 없어 최종 검증 뒤 디렉터리 교체 시 외부 빈 파일이 생길 수 있고, 같은 자격 증명 주체는 검사 뒤 hardlink를 추가할 수 있으므로 절대적 containment는 보장하지 않는다. 번들 IBM Plex Sans KR는 loadSystemFonts: false로 자동 해석한다.

• 내보내기 제한 — SVG, PNG, JPG, PDF, PPTX, GIF, MP4를 지원한다. 축 8,192px, 페이지당 16,000,000px, 최대 10페이지·1,000레이어이며, GIF와 MP4는 문서 페이지를 프레임으로 묶어 각각 총 32,000,000 프레임 픽셀까지 허용한다. PDF는 FlateDecode 이미지와 UTF-16BE 메타데이터를 사용. PPTX는 고정 timestamp ZIP/PresentationML로 슬라이드별 단색 페이지 배경과 텍스트·사각형·이미지를 개별 편집 객체로 기록한다.

• 결정론 — 동일 입력 바이트 동일성은 회귀 테스트로 검증

jpg 형식 요청은 알파를 페이지 배경(또는 backgroundColor)에 평탄화한 실제 baseline JPEG를 .jpg 확장자로 반환한다. 내장 인코더는 의존성을 추가하지 않으며 기본 quality는 85(1–100 지정 가능), 텍스트의 컬러 가장자리를 보존하기 위해 4:4:4 chroma sampling을 쓴다. pptx는 슬라이드 자체의 <p:bg>에 페이지 배경을 기록하고 텍스트·사각형·이미지를 PowerPoint·Keynote·Google Slides에서 개별 편집할 수 있는 PresentationML 객체로 내보낸다. 복잡한 path·둥근 사각형 반지름·이미지 cover/contain crop·필터·그라데이션·애니메이션·전환은 아직 지원하지 않는다. GIF는 결정론적 GIF89a이며 문서 페이지가 프레임이 된다. 공용 팔레트는 최대 256색의 가중 median-cut 양자화와 명시적 동률 순서를 사용하고, 기본 지연은 10 centiseconds(100ms)다. Floyd–Steinberg 디더링은 평면 브랜드 패널을 거칠게 만들 수 있어 라이브러리 exportDocument의 gifDither에서만 선택적으로 켜며 기본은 꺼져 있다. 단일 페이지는 NETSCAPE2.0 루프 확장을 쓰지 않고, 여러 페이지는 무한 반복한다. 현재 MCP export_design_document 스키마는 gifFrameDelay·gifDither·mp4FrameDuration을 노출하지 않는다. MP4는 같은 페이지 순서를 Motion JPEG intra frame으로 담고 기본 프레임 길이는 100ms이며, 라이브러리 exportDocument에서는 mp4FrameDuration에 공통 값 또는 페이지별 값을 줄 수 있다. 고정 timestamp라 바이트 결정론적이고 홀수 치수도 된다. 다만 H.264 동등 품질보다 파일이 훨씬 크며 ffmpeg·QuickTime·VLC는 재생하지만 대부분 브라우저는 Motion JPEG MP4를 네이티브 재생하지 않는다. 짧은 인라인 루프에는 GIF, 비디오 파이프라인 전달에는 MP4를 권장한다. #15는 PPTX·GIF·MP4까지 완료되어 해결되었고, 12종 템플릿의 추가 확장은 선택 사항이며 #16에, 웹 에디터 UI는 #18에 남는다.

조사와 명세: 미리캔버스 파리티 조사, 디자인 엔진 명세

Open Design → Penpot 핸드오프

Open Design 산출물(SVG 엔트리 + CSS 커스텀 프로퍼티 토큰)을 handoff 번들 계약으로 Penpot 페이지에 반입합니다. 명세: docs/specs/019-open-design-handoff.md, 실측 근거: docs/research/019-open-design-export.md.

사용 순서 (생성 → 번들 → 반입 → 재조회)

1. 생성 — open-design MCP 도구가 노출된 새 Codex 태스크에서 collect_brief → start_run → get_run으로 비식별 샘플 생성 (SVG 엔트리 1개 + tokens.css).

2. 산출물 획득 — get_artifact({ project, entry })로 SVG 엔트리 + 참조 파일 획득, truncated 여부 확인.

3. 번들 구성 — 5장 계약으로 manifest.json + 파일 구성 (content hash는 CLI가 검증):

mkdir -p my-bundle
cp hero-section.svg tokens.css my-bundle/
# manifest.json 작성 — source.mode: user-handoff 또는 MCP 경로 metadata

4. 반입 미리보기 — Penpot 쓰기 없이 변환·loss report·action 확인:

teguma import-open-design --bundle ./my-bundle --dry-run

5. 반입 — Penpot 파일에 페이지 생성/교체 (idempotency: od-handoff-<sourceId12>-<hash12> 이름 기준):

PENPOT_URL=http://192.168.0.183:9001 PENPOT_SESSION_COOKIE=... teguma \
  import-open-design --bundle ./my-bundle --penpot-file-id <file-id>

6. 재조회 — get_page_layout(셰이프 트리)·get_tokens(압축 토큰)로 반입 결과 확인. canonical 문서는 data/imports/open-design/<sourceIdSlug>/tokens.canonical.json에 저장되어 재조회 검증의 기준이 된다 (POC 한계: includeCanonical 왕복은 #30 후속 — 13장).

7. idempotency 재현 — 같은 번들 재실행 → action: "unchanged", 번들 수정 후 재실행 → action: "replaced". --force는 Penpot 수동 편집 drift 복구용.

import_open_design 인자·출력

출력 예시 (요약):

{
  "action": "created",
  "pageName": "od-handoff-3830495a6aa9-ae9219aad83a",
  "summary": { "layers": { "source": 10, "imported": 9, "unsupported": 1 } },
  "lossReport": { "schemaVersion": "0.1.0", "items": [ { "category": "image", "severity": "unsupported", "code": "external-url-asset" } ] },
  "canonical": { "tokenCount": 8, "mode": "default" }
}

시크릿 경계 (6.1)

• PENPOT_SESSION_COOKIE·PENPOT_TOKEN은 환경변수로만 주입 (~/.codex/config.toml 또는 셸) — 문서·커밋·번들·채팅 노출 금지.

• Open Design cloud/BYOK 크레덴셜은 MCP 내부 전용 — chat·파일·번들·커밋에 기록 금지.

• fixture·번들에 개인·회사 시크릿 금지 (외부 URL 이미지는 example.invalid 같은 가짜 도메인만).

live smoke

scripts/smoke-open-design-handoff.sh — opt-in, CI 미포함 (13장). 네트워크·시크릿 필요:

PENPOT_URL=... PENPOT_SESSION_COOKIE=... PENPOT_FILE_ID=<id> \
  ./scripts/smoke-open-design-handoff.sh --bundle ./my-bundle

아키텍처

AI Agent (Claude Code / Cursor / Codex)
         │ MCP Protocol (stdio)
         ▼
┌─── teguma MCP Server ───┐
│  Brand Context Engine    │
│  Design Token Compressor │
│  Layout Constraints      │
└──────────┬───────────────┘
           │ HTTP RPC API
           ▼
    Penpot (self-hosted)

개발

npm install
npm run dev        # 개발 모드 (tsx)
npm run build      # TypeScript 컴파일
npm test           # Vitest

운영환경

AGENTS.md — 이슈 기반 개발, semver 릴리스, 리뷰 파이프라인.

리서치

• Figma 오픈소스 랜드스케이프

• Claude Design + Figma 페인포인트

• 자동 홍보 크리에이티브 조사

• 프로덕트 명세

실험

• 회사 홍보 썸네일 테스트베드 — SEVASA, 슈퍼쇼츠, 주식회사 로드맵 1080×1080 시안과 재현 가능한 SVG 렌더러

• 회사 홍보 에디토리얼 v2 — 자연광·현장 맥락·중립 타이포로 AI 특유의 시각 단서를 줄인 시안과 v1/v2 비교

• 네이버 실노출 썸네일 v3 — 104×104px 검색 결과와 홈피드 크롭에 맞춘 한 피사체·한 문구 대표 이미지

스톡 자산

• 생성형 회사 홍보 배경 원본 — 원본 PNG, 프롬프트, SHA-256, 파생 자산 관계

• 회사 홍보 v2 배경 원본 — 다큐멘터리형 원본 PNG와 AI provenance

• 회사 홍보 v3 배경 원본 — 네이버 대표 이미지용 클로즈업 원본과 AI provenance

라이선스

MIT

디렉토리

라이선스

TBD