carousels-mcp: Instructions file for Claude Code

carousels-mcp

MCP server that converts articles, transcripts, and markdown into social media carousels (LinkedIn PDFs, Instagram/Threads PNGs).

Architecture

src/
  index.ts              — MCP server entry, tool registration (StdioServerTransport)
  types.ts              — SlideType union (11 types), SlidePlan, CarouselOutput, Platform, PLATFORM_DIMENSIONS
  engine/
    content-extractor.ts — Splits raw text/markdown into SlidePlan with auto-detection (numbers→stat, ordered lists→steps, emphasis→takeaway, before/after→comparison)
    svg-generator.ts     — Template-driven SVG generation, one function per slide type, shared helpers for progress bar/swipe arrows
    pdf-converter.ts     — Puppeteer wrapper (optional dep) for SVG→PDF and SVG→PNG conversion
    pdf-merger.ts        — pdf-lib merge of individual slide PDFs into single carousel.pdf
    text-utils.ts        — XML escaping, text wrapping, tspan generation
    template-loader.ts   — Loads built-in + user JSON templates
    output-dir.ts        — Resolves output directory (env var → ~/Documents/carousels/YYYY-MM-DD-{slug}/)
  tools/
    schemas.ts           — Zod input schemas for all 5 tools
    list-templates.ts    — Lists built-in + user custom templates
    preview-slides.ts    — Content → SlidePlan (no rendering)
    render-slides.ts     — SlidePlan → SVG + PDF/PNG
    create-carousel.ts   — Full pipeline: content → plan → render → output
    create-template.ts   — Creates user brand kit JSON from base template + overrides
  templates/
    types.ts             — CarouselTemplate interface, TemplateSlideLayouts, TemplateTypography
    defaults/            — 6 built-in template JSONs

Key patterns

Platform branching

LinkedIn gets PDF output (individual PDFs merged via pdf-lib). Instagram/Threads get PNG output (2x deviceScaleFactor for crisp social images). Platform dimensions are injected into the template before SVG generation:

const dimensions = PLATFORM_DIMENSIONS[platform]; // { width, height }
const templateWithDims = { ...template, dimensions };