Presentation Generator API

A Docker-based REST API for generating standalone HTML presentations from JSON data.

Features

• 🚀 REST API endpoint for presentation generation
• 🐳 Docker containerized for easy deployment
• 🔒 Signed URLs for secure file access with expiration
• 📁 Automatic file storage and management
• 🎨 Support for all existing presentation components
• 🖼️ Image embedding and processing
• 🗜️ HTML minification and obfuscation
• 📦 Fully self-contained builds (no host dependencies)

Quick Start

Using Docker Compose (Recommended)

1. Clone the repository and navigate to the directory
2. Build and start the container:

docker-compose up --build

The API will be available at http://localhost:3000

Using Docker directly

# Build the image
docker build -t presentation-api .

# Run the container
docker run -p 3000:3000 -e SIGNED_URL_SECRET=your-secret-key presentation-api

API Endpoints

Health Check

GET /health

Returns the API status and version information.

Generate Presentation

POST /api/generate
Content-Type: application/json

Send your presentation JSON data in the request body. Returns a response with a signed download URL.

Example request:

curl -X POST http://localhost:3000/api/generate \
  -H "Content-Type: application/json" \
  -d @presentation-data.json

Example response:

{
  "success": true,
  "filename": "presentation-12345678-1234-1234-1234-123456789012.html",
  "downloadUrl": "http://localhost:3000/api/download/presentation-12345678-1234-1234-1234-123456789012.html?expires=1642694400&signature=abc123...",
  "size": 156789,
  "expiresIn": 3600,
  "generatedAt": "2024-01-20T10:30:00.000Z"
}

Download Presentation

GET /api/download/:filename?expires=timestamp&signature=hash

Download the generated presentation using the signed URL. URLs expire after the configured time (default: 1 hour).

List Generated Files (Debug)

GET /api/files

Returns a list of all generated presentation files (useful for debugging).

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | PORT | 3000 | Port for the API server | | OUTPUT_DIR | ./generated | Directory for generated presentations | | SIGNED_URL_SECRET | your-secret-key-change-in-production | Secret for signing URLs | | SIGNED_URL_EXPIRY | 3600 | URL expiration time (seconds) | | NODE_ENV | - | Node environment (development, production) |

Security

• URLs are signed with HMAC-SHA256 and expire after a configurable time
• Container runs as non-root user
• Input validation on all endpoints
• File path validation to prevent directory traversal
• CORS and security headers enabled

File Storage

Generated presentations are stored in the /app/generated directory inside the container. For persistent storage across container restarts, mount a volume:

docker run -p 3000:3000 -v $(pwd)/generated:/app/generated presentation-api

Development

To run in development mode:

npm install
npm run dev

Original CLI Usage

The original command-line interface is still available:

node generate-presentation.js [input-file.json] [--both]

JSON Format

The API expects the same JSON format as the original CLI tool. See presentation-data.json for an example.

Required fields:

• meta.title: Presentation title
• meta.totalSlides: Number of slides
• slides: Array of slide objects

Error Handling

The API returns appropriate HTTP status codes:

• 200: Success
• 400: Bad request (invalid JSON, missing fields)
• 403: Forbidden (invalid/expired download link)
• 404: File not found
• 500: Server error

Error responses include a descriptive message:

{
  "error": "Invalid presentation data. Missing meta.title.",
  "message": "Additional error details"
}

MCP STDIO Mode (Experimental)

You can now run the presentation generator as an MCP-compliant STDIO server, suitable for LLM agent integration and npx-based workflows. This mode does not affect the existing REST API.

Usage

npx @modelcontextprotocol/sdk run ./mcp-stdio-server.js

• Accepts MCP messages via STDIO (see Model Context Protocol docs)
• Supports the same presentation generation logic as the REST API
• Does not start an HTTP server or interfere with API endpoints