Magic Envelope MCP Server

✉ Magic Envelope

Free invitations and letters: birthdays, weddings, parties, dinners, letters… Pick a ready-made template or build one from typed blocks. Send a link and the guest opens a sealed envelope.

Not an editor. Everything is typed and modular.

Run

pnpm install
pnpm dev          # http://localhost:3000

Locally, without any keys, published cards and uploaded images are saved under .data/. Only AI images need a key.

For agents

Everything the app does is available without a browser:

• MCP — https://magic-envelope.com/api/mcp (tools: get_catalog, create_letter, get_letter, update_letter)
• REST — POST /api/v1/letters, GET|PATCH /api/v1/letters/:id (Authorization: Bearer <editKey>), GET /api/v1/catalog
• Specs — /api/v1/openapi.json, /api/v1/schema, /llms.txt, docs at /developers

The REST and MCP adapters share one service layer (src/lib/api.server.ts) and validate with the same Zod schemas as the editor.

Native apps (Capacitor 8)

The iOS/Android apps are thin shells around the hosted web app (it needs API routes, so no static export). capacitor.config.ts points the WebView at CAP_SERVER_URL (default https://magic-envelope.com); native-shell/ is only the offline page.

pnpm dev:lan                                   # dev server reachable from your phone
CAP_SERVER_URL=http://192.168.1.20:3000 pnpm cap:android   # or cap:ios (opens Android Studio / Xcode)

src/lib/native.ts is the single bridge: each function uses the Capacitor plugin in the app and the web API in the browser.

Environment

Architecture

src/lib/model.ts        Zod schemas: Card, 15 Block types, kinds, themes, languages
src/lib/blocks.ts       block registry (icons, palette, factories) + 24 templates (8 kinds × 3)
src/lib/ui.ts           app UI copy (always English)
src/lib/styles.ts       letter styles = design-system tokens (fonts, colors, background, frame, control shape, envelope) + per-letter overrides
src/lib/i18n.ts         letter languages es · en · fr · pt · it · de (guest-facing copy + presets)
src/lib/fields.ts       field kinds (phone, email, url, date…): one validator for editor + renderer
src/lib/craft.ts        seal shapes/marks & envelope geometry/palettes (shared by app and OG image)
src/lib/color.ts        opaque shading helpers
src/lib/themes.ts       6 themes (parchment, midnight, rose, forest, sky, ink)
src/lib/actions.ts      calendar (.ics / Google), maps, RSVP deep links, music embeds
src/lib/drafts.ts       drafts in localStorage (no account needed)
src/lib/store.server.ts Vercel Blob storage, or .data/ in local dev

src/components/sketch.tsx         Excalidraw-style rough.js frames and buttons
src/components/card/blocks.tsx    renderer per block type
src/components/craft.tsx          wax seal, envelope art, envelope opener
src/components/editor/            tap-a-block editor, "+" palette, theme, share sheet
src/components/wizard.tsx         language → kind → template

/                 home (drafts)
/new              wizard (?kind=wedding jumps to templates)
/edit/[id]        editor (local draft)
/c/[id]           public envelope (+ OG image for WhatsApp/iMessage previews)
/e/[id]#key       "edit on another device": imports the card into local drafts
/api/publish      save/overwrite a card (id + secret edit key)
/api/upload       image upload (resized client-side)
/api/imagine      AI image → stored → URL
/api/card/[id]    card JSON for holders of the edit key

src/lib/personalize.ts            {name} token: resolution and fallbacks
src/lib/mail.ts                   envelope slots (fixed block types), stamps, per-style envelope defaults
src/components/editor/envelope-editor.tsx  envelope canvas + slot/seal editors
src/components/export-stage.tsx   flat PNG/ZIP rendering (fonts embedded per style)
src/components/editor/guests-panel.tsx, send-panel.tsx

Adding a block type

1. Add a schema in lib/model.ts and include it in the Block union (add a migration there if you change an existing shape).
2. Add an icon, a palette entry and a factory in lib/blocks.ts, and its label in lib/ui.ts.
3. Add a renderer case and an isEmpty rule in components/card/blocks.tsx.
4. Add an editor case in components/editor/block-editor.tsx, using Field with the right field kind.
5. Add any guest-facing words to lib/i18n.ts.

TypeScript's exhaustive switches flag every step you missed.

Features

• Wizard: letter language → style (15 styles: Classic, Elegant, Modern, Playful, Retro) → blank letter (default) or an occasion preset
• Style panel in the editor: switch style, customize accent/paper/text colors and title/text fonts, seal (symbol, initials or none), text written on the envelope (supports the guest name)
• Preview page mirrors the editor's Link/Image choice and "preview as" guest, and can send directly
• App UI is English; each letter has its own language (changeable from the Style panel)
• 15 blocks: title, text, image, date, place + map, countdown, RSVP (WhatsApp/SMS/email), QR, link, schedule, dress code moodboard (colors, emojis, words, pictures), gifts (IBAN copy / registry), music (Spotify/YouTube/SoundCloud), signature, divider
• AI images in 4 styles (storybook, medieval, sketch, photo) and photo upload
• Six themes, custom wax-seal glyph, an envelope addressed "To: …"
• Guest list: add, paste a list ("Name, phone/email") or pick from contacts; {name} in any text addresses each guest
  • every guest gets their own link (/c/<id>?g=<guest>) — only their name is ever sent to their browser
  • send per guest via their channel (WhatsApp / email / share sheet), track who was sent, copy all links, CSV
  • RSVP replies carry the guest's name; the envelope is addressed to them
• Envelope (link letters): fixed slots holding real blocks — Title (recipient), Text (sender, note, under the seal) and Stamp (postage, 14 perforated stamps) — edited with the same editor, placeholders and rules as the letter; seal in 4 shapes (scalloped, round, flower, octagon) with a vector mark (12 icons, 1–3 initials, a couple "A ♥ J", plain or none), always legible on any wax colour. Styles ship their own envelope (trim + stamp). Guests receive the front, turn it over with a tap, open it with a second; the real letter slides out.
• Preview shows exactly what a guest receives: the envelope (replayable) for links, the actual exported PNG for images.
• Two outputs from one letter: the interactive link, or flat images (PNG per guest, ZIP for all, print/PDF). Blocks with actions render flat automatically in images, and each can turn its buttons off for the link too.
• Share: link, native share sheet, WhatsApp, downloadable QR, print/PDF
• Guests get "add to calendar", directions, a live countdown and one-tap RSVP
• Installable PWA (iOS/Android home screen), dark-mode chrome, reduced-motion support
• Published links are noindex; each card can be re-published from the device that created it