Bedtime Book Studio 📚✨

Turn a quick photo (or character description) and a bedtime story idea into an interactive, mobile-friendly landscape children's picture book in minutes.

Bedtime Book Studio is an open-source Agent Skill and Model Context Protocol (MCP) server that works with any AI coding/chat agent (Claude Code, Cursor, Antigravity, Windsurf, OpenClaw, etc.).

When your book finishes building, you get:

1. A Single-File HTML Picture Book (books/<slug>.html): Every illustration (.webp), stylesheet, and interactive page-turn/flap script is bundled into one self-contained .html file. You can double-click it to open in any browser, AirDrop/text/email it straight to your phone or iPad for bedtime, or drop that single file onto any static web host.

2. Instant Local Hosting on Your Device: By default, Bedtime Book Studio automatically serves your books locally on your machine (http://localhost:8765/<slug>/) and prints your device's local Wi-Fi URL (http://<your-lan-ip>:8765/<slug>/) so you can open the book immediately on a phone or tablet on the same Wi-Fi network.

3. Optional Custom Self-Hosting: If you run your own web server or static site folder, you can optionally set PUBLISH_WEB_ROOT and PUBLISH_BASE_URL in .env to auto-copy new books to your server.

✨ Two Interactive Book Modes

1. Lift-the-Flap Mode (lift-the-flap — Default):

   • Every story page shows the everyday Reality scene on a tactile, stitched cardboard flap.

   • Kids can tap the button, press Space/F, or drag the flap upward with their finger to lift it in 3D and reveal the Imaginary world underneath!

2. Standard Picture-Book Mode (standard):

   • Classic single-illustration landscape spreads with big read-aloud typography, a Aa Text Only focus mode, and a celebratory "Hooray! The End" confetti finale.

Related MCP server: Once Upon YOUR Child MCP server

🚀 Step-by-Step Setup (2 Minutes)

Prerequisites

• Python 3.10+

• Any AI agent that supports MCP or Skills (and has access to an image generation tool/subagent).

Step 1: Clone the Repo & Run Setup

git clone https://github.com/danmaps/bedtime-book-studio.git
cd bedtime-book-studio
./setup.sh

What ./setup.sh does:

1. Creates a local Python virtual environment (.venv/) and installs Pillow + mcp.

2. Launches the interactive onboarding wizard to set up your main character and defaults, saving everything locally in .env (which is gitignored).

3. Prints the exact copy-paste config snippet for your AI agent.

Tip: Want your AI agent to interview you in chat instead of using the terminal wizard? Run ./setup.sh --skip-onboard. The first time you ask your agent to make a book, it will detect that .env isn't configured yet and walk you through onboarding right in chat!

Step 2: Connect Your AI Agent

Choose MCP Server, Agent Skill, or both:

Option A: Connect via MCP (Claude Code, Cursor, Antigravity, Windsurf)

Add bedtime-book-studio to your agent's MCP config file (for example ~/.claude.json, .cursor/mcp.json, or ~/.gemini/config/mcp_config.json):

{
  "mcpServers": {
    "bedtime-book-studio": {
      "command": "/absolute/path/to/bedtime-book-studio/.venv/bin/python",
      "args": [
        "/absolute/path/to/bedtime-book-studio/scripts/mcp_server.py"
      ]
    }
  }
}

(Note: ./setup.sh prints this exact JSON block with your real absolute paths filled in!)

Option B: Connect via Agent Skill (SKILL.md)

Symlink the repo into your agent's skills folder:

mkdir -p ~/.agents/skills
ln -sfn "$(pwd)" ~/.agents/skills/bedtime-book-studio

Step 3: Onboard Your Main Character (Photo and/or Text)

During onboarding (via ./setup.sh, python3 scripts/book_studio.py onboard, or in chat with your agent), you configure your default character once:

• Name & Age: e.g. Leo, age 4

• Visual Reference (Photo, Text, or Both):

  • Photo(s): Provide path(s) to 1 or more photos of your main character. They are copied into ./local_profile/references/ (gitignored) and automatically included as visual references in future books.

  • Text Description & Outfit: Describe their hair, eyes, skin tone, and signature outfit (e.g., "4-year-old with curly brown hair, wearing a red striped T-shirt and denim overalls"). You can use text alone or combine it with reference photos for rock-solid consistency.

• Supporting Cast & Favorite Toys (Optional): Pets, siblings, parents, or favorite real-world toys that frequently appear in bedtime stories.

• Book Defaults: lift-the-flap vs. standard mode, default page count (12), and default illustration style.

All of these settings live in your local .env file. You can re-run onboarding anytime:

./.venv/bin/python scripts/book_studio.py onboard

📖 Making a Bedtime Book

Once connected, just ask your AI agent in plain English:

"Make a new lift-the-flap bedtime book in bold Maisy style! Here's a photo of our cardboard box (/path/to/box.jpg). The story is about turning a cardboard moving box in the living room into a rocket ship landing on the moon."

🎨 Built-In Art Style Presets

You can set a default style preset in .env (DEFAULT_STYLE_PRESET) or pick a different style per book (--style-preset):

📝 Optional Dry-Run Planning Mode (book-plan.md)

Want to review or tweak the story text, page count, flap reveals, and visual prompts before spending time or credits generating illustrations? Ask your agent for a dry-run book plan (or run plan from the CLI):

# 1. Create a self-contained, editable Markdown plan (0 images generated, no site built yet)
./.venv/bin/python scripts/book_studio.py plan \
  --slug "leos-cardboard-rocket" \
  --title "Leo's Cardboard Rocket" \
  --idea "Leo turns a cardboard moving box in the living room into a lunar rocket ship" \
  --style-preset "bold-gouache"

# 2. Open and edit books/leos-cardboard-rocket/book-plan.md in any editor
#    (change story paragraphs, page titles, style preset, flap transformations, or visual prompts)

# 3. Apply your edits into storyboard.json + prompts.md + preview.html
./.venv/bin/python scripts/book_studio.py apply-plan --slug "leos-cardboard-rocket"

What Happens Behind the Scenes:

1. create_book_project / create_book_plan: Scaffolds books/<slug>/ (and optionally books/<slug>/book-plan.md for dry-run editing), resolving your character/pet/prop identities and chosen style_preset.

2. save_book_storyboard / apply_book_plan: Writes storyboard.json, prompts.md, and preview.html with locked character continuity and matching Reality + Imaginary scene prompts for every page.

3. ingest_generated_images: Your agent generates the illustrations, and Bedtime Book Studio center-crops every image to 1280x960 (4:3 landscape) and exports .png + .webp.

4. build_and_publish_book:

   • Generates the single-file standalone HTML book at books/<slug>.html (with all CSS, JS, and .webp images inlined so each published book is only 1 file).

   • Starts the local device web server so you can read immediately!

📱 Reading on Your iPad, Phone, or Computer

1. Recommended for iPad & Phones: Scan the Local Wi-Fi QR Code

When publish (or preview) runs, Bedtime Book Studio automatically:

• Starts a lightweight local HTTP server on port 8765 (configurable via LOCAL_SERVER_PORT in .env).

• Generates a scannable QR code (books/<slug>/qr-lan.svg + a terminal ASCII QR code in the CLI/MCP output) pointing to http://<your-lan-ip>:8765/<slug>.html.

• Point your iPad or iPhone Camera app at the QR code to open the book directly in Mobile Safari with full lift-the-flap touch/drag gestures, 🌙 Bedtime Mode, and "Add to Home Screen" support.

• Need to restart the local server or print the QR code later? Run:

  ./.venv/bin/python scripts/book_studio.py serve

2. Single-File HTML Book (books/<slug>.html)

• Every published book is a single, completely self-contained books/<slug>.html file (~1.5–5 MB total, with all .webp illustrations, CSS, and JS embedded).

• On Mac / PC / Android: Double-click books/<slug>.html to open in any desktop browser with full interactivity.

• Static Hosting: Drag-and-drop books/<slug>.html onto Netlify Drop, Cloudflare Pages, GitHub Pages, S3, or any static host for a permanent HTTPS link you can text to family.

📊 Verified iPad & Mobile Delivery Matrix

🔧 Local Wi-Fi & Port Troubleshooting

• iPad can't reach http://<lan-ip>:8765?

  1. Ensure your computer and iPad are on the same Wi-Fi network (avoid "Guest" Wi-Fi networks that enable AP client isolation).

  2. If macOS/Linux firewall prompts to allow incoming connections for Python, click Allow (or open TCP port 8765 via ufw allow 8765/tcp).

  3. If port 8765 is already in use, pass --port 8888 to publish / serve or set LOCAL_SERVER_PORT="8888" in .env.

3. Optional Custom Self-Hosting (PUBLISH_WEB_ROOT)

If you run a local or remote web server directory (Nginx, Caddy, Tailscale Serve, etc.), set these optional variables in .env:

PUBLISH_WEB_ROOT="/var/www/my-site/books"
PUBLISH_BASE_URL="https://example.com/books"

Whenever a book is published, Bedtime Book Studio will automatically copy the single-file book into <PUBLISH_WEB_ROOT>/<slug>.html and return <PUBLISH_BASE_URL>/<slug>.html.

Optional Bookshelf

The bookshelf template is a single HTML file with a black background and a responsive, scrollable grid of cover thumbnails. Tap a cover to read its book in an iframe, then use Back to shelf to return to the same shelf position.

Ask your agent: "Set up the optional bookshelf with my books." Agents can find the instructions in AGENTS.md.

To populate it yourself:

1. Copy templates/bookshelf.html to books/index.html (or your chosen hosting folder).

2. Find the BOOK PATHS comment. Copy its example link outside the comment for each book, setting href to the single-file book HTML (<slug>.html) and src to its inlined data:image/webp;base64,... cover URI (or cover image path). Set alt to the book's name for accessibility.

3. Serve the shelf and single-file books together using your local or static hosting. With the existing local server serving books/, open http://<your-lan-ip>:8765/index.html on your phone or tablet.

The template is optional and starts as an empty black page until you add links. It shows only covers, with no visible title, captions, or metadata. Comments mark places for optional decoration: ask your agent afterward to add a kid's name, theme colors, or another personal touch.

🛠️ CLI & MCP Tool Reference

🔒 Privacy by Design

• .env, local_profile/, and books/ are all gitignored in .gitignore.

• Your personal family photos, character names, and generated books never leave your device unless you choose to share them.

📄 License

MIT License — see LICENSE.