Wedding Invitation Builder MCP

원본 모바일 청첩장의 풍부한 섹션과 상호작용을 누구나 자기 정보로 다시 만들 수 있는 FastMCP v1 서버입니다. 이름 몇 개만 바꾸는 고정 페이지가 아니라, 대화로 필수 정보를 받고 구조화된 세부 항목을 추가해 모바일 HTML 청첩장과 휴대 가능한 공유 토큰을 만듭니다.

이 저장소에는 기존 개인 청첩장의 이름, 사진, 전화번호, 계좌, 지도 링크, 음악, 영상이 포함되지 않습니다. examples/assets/와 데모의 모든 내용은 비식별 가상 자료입니다.

기능 범위는 원본 minwoo19930301/wedding을 기준으로 재구성했지만, 원본의 개인 데이터와 자산은 복사하지 않았습니다.

핵심 기능

• MCP elicitation 지원 client에서는 start_invitation이 이름·날짜·시간·장소를 폼으로 요청
• elicitation 미지원 client나 테스트에서는 동일한 순서의 questions_fallback 반환
• Pydantic 구조화 데이터: 달력, 양가/보호자와 연락, RSVP, 공지, 주차·대중교통·셔틀, 복수 지도, 최대 40장 갤러리, 영상, 수동 재생 BGM, 계좌 복사·송금 링크
• DOM과 레이아웃 자체가 다른 4개 디자인
• 생성/수정 응답은 compact metadata만 반환하고 HTML은 preview/export에서만 제공
• expected_revision 기반 낙관적 잠금으로 동시 수정 유실 방지
• 정렬 JSON + zlib + base64url로 만든 결정적 share token: 같은 입력은 같은 token
• 사용자 텍스트 HTML escape, http(s) URL만 허용, 압축 해제 크기 제한
• 모바일 CSS, 키보드/모션 감소 대응, 갤러리 lightbox, 계좌·링크 복사

디자인

template_id	구조	메인 사진 표현
tide-letter	몰입형 해저 인트로 + 긴 편지형 스택	화면 끝까지 차는 cover와 물빛 overlay
city-edition	비대칭 에디토리얼 그리드 + issue rail	타이포 옆 독립 사진 패널
hanji-vow	한지 질감 + 겹선 문틀 + 접지 패널 + 주홍 인장	족자/인화지 프레임
film-notes	슬레이트 + voice-over + 필름 contact sheet	opening frame

사진이 없으면 네 디자인 모두 타이포 중심 hero로 자연스럽게 돌아갑니다.

실행

Python 3.11 이상과 MCP Python SDK v1 (mcp<2) 를 사용합니다.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
python server.py

• Streamable HTTP MCP: http://127.0.0.1:8000/mcp
• Health: http://127.0.0.1:8000/health
• Fictional demos: http://127.0.0.1:8000/demo/tide-letter 등 4개

HOST와 PORT를 읽으므로 PORT=9000 python server.py처럼 배포 환경의 포트를 바꿀 수 있습니다. 런타임 의존성은 재현 가능한 배포를 위해 requirements.txt에 정확한 버전으로 고정되어 있습니다.

stdio가 필요한 client에서는 다음처럼 실행합니다.

MCP_TRANSPORT=stdio python server.py

Docker:

docker build -t wedding-invitation-builder-mcp .
docker run --rm -p 8000:8000 wedding-invitation-builder-mcp

이미지는 전용 비루트 app 사용자로 서버를 실행하고 /health Docker healthcheck를 포함합니다.

권장 대화 흐름

1. list_templates로 디자인을 보여줍니다.
2. start_invitation을 호출합니다.
3. elicitation 결과를 수락하면 최소 청첩장이 바로 생성됩니다.
4. 미지원 client라면 반환된 questions를 사용자에게 묻고 create_invitation을 호출합니다.
5. 선택 섹션은 update_invitation(draft_id, expected_revision, patch)로 채웁니다.
6. preview_path로 확인하고 export_path 또는 export_html로 저장합니다.

최소 details 예시:

{
  "partner_one": {"name": "강해온"},
  "partner_two": {"name": "윤새봄"},
  "event": {
    "date": "2027-05-22",
    "time": "14:00",
    "venue_name": "별빛정원 아트홀",
    "address": "서울시 가온구 새봄로 100 (가상 주소)"
  }
}

이 필드만으로도 달력·일시·장소·초대문이 있는 완성 HTML이 나옵니다. 이후 다음 구조를 부분 patch로 추가할 수 있습니다.

{
  "notices": [{"title": "참석 여부", "body": "예식 2주 전까지 알려주세요."}],
  "families": [{
    "label": "해온 측",
    "members": [{"name": "강가람", "relation": "보호자", "phone": "010-0000-0000"}]
  }],
  "transport": {
    "parking": ["지하 주차장 3시간 무료"],
    "subway": ["별빛역 2번 출구 도보 6분"]
  },
  "maps": [{"provider": "지도", "url": "https://example.com/maps/sample"}],
  "gallery": [{"url": "https://example.com/photo.jpg", "alt": "예비부부 사진"}],
  "media": {
    "video_url": "https://example.com/wedding-film.mp4",
    "bgm_url": "https://example.com/wedding-theme.mp3"
  },
  "accounts": [{
    "side": "해온 측",
    "holder": "강해온",
    "bank": "데모은행",
    "account_number": "DEMO-0000-0000"
  }]
}

배열은 patch 시 전체 교체되고, 객체는 재귀적으로 merge됩니다. 수정 요청에는 직전 응답의 revision을 expected_revision으로 반드시 전달하세요. 다르면 revision_conflict와 현재 revision이 반환됩니다.

MCP tools

• list_templates()
• get_questions(template_id)
• start_invitation(template_id, prefer_elicitation)
• create_invitation(details, template_id)
• update_invitation(draft_id, expected_revision, patch, template_id)
• get_preview(draft_id)
• open_share_token(share_token)
• export_html(draft_id | share_token)

생성/수정 응답에는 전체 HTML 대신 preview_path, export_path, share_path, share_export_path, share_token이 들어갑니다. share_path는 서버 메모리가 초기화되어도 token 자체에서 페이지를 복원합니다.

Share token과 개인정보

share token은 암호화가 아니라 압축·인코딩이며 서명, 인증, 접근 제어 수단도 아닙니다. 연락처나 계좌를 넣었다면 token을 해당 정보와 동일하게 취급하고 공개 채널에 게시하지 마세요. 동일 입력의 token은 항상 같으며, 임의 draft ID나 timestamp는 token payload에 들어가지 않습니다. draft는 현재 프로세스 메모리에만 최대 500개 보관되며 서버 재시작 시 사라집니다. 또한 token을 URL에 넣으면 서버 로그, 브라우저 방문 기록, 링크 미리보기에 남을 수 있으므로 접근 제어가 필요한 정보는 별도의 인증된 저장소를 사용하세요. 민감 정보가 있으면 HTTPS와 제한된 공유 채널을 사용하고, 필요하면 계좌·전화번호를 뺀 공개용 초대장을 따로 만드세요.

허용 URL은 절대 http:// 또는 https://뿐입니다. javascript:, data:, URL 내 credential, 제어 문자는 거부합니다. BGM은 브라우저 정책과 사용자 선택을 존중해 자동 재생하지 않습니다.

Fictional demo와 테스트

서버의 /demo/{template_id}가 요청 origin에 맞춰 비식별 JPEG를 사용합니다. 정적 HTML 4개를 만들려면 서버를 켠 상태에서 다음을 실행하세요.

python scripts/render_demo.py

테스트:

pip install -r requirements-dev.txt
pytest
python scripts/smoke_mcp.py

테스트는 최소 입력 즉시 생성, 4개 DOM 차이, 메인 사진 배치, 전체 구조 섹션, XSS escape, URL scheme 차단, token 결정성·round-trip, revision 충돌, questions fallback을 확인합니다. smoke_mcp.py는 빈 로컬 포트를 골라 실제 Streamable HTTP 서버를 띄운 다음 initialize → listTools → callTool을 수행합니다. 구체 output schema, tool title/annotations, elicitation 미지원 fallback과 지원 client의 accept 경로, preview/share/export HTTP 응답, token round-trip, revision 충돌까지 확인하고 서버를 종료합니다.

커스터마이징 범위와 라이선스

models.py의 데이터 구조, renderer.py의 레이아웃/CSS/상호작용, server.py의 tool 흐름을 수정해 새 테마나 섹션을 만들 수 있습니다. 사용자 사진·폰트·음원·영상·브랜드 자산은 각자 권리를 확인해 직접 제공해야 하며, 이 프로젝트는 그러한 개인 자산을 묶어 배포하지 않습니다.

코드는 CC BY-NC 4.0입니다. 저작자 표시를 유지한 비상업적 공유·수정은 허용되지만 상업적 이용은 LICENSE의 안내에 따라 저작권자와 별도 라이선스 계약이 필요합니다.