luma-ai-video-engine-mcp

🎯 Core Functionality

This service exposes the advanced video generation functionalities offered by Luma AI via a standardized MCP endpoint. Key capabilities include synthetic video generation driven by natural language prompts, image-to-video transformation, temporal sequence augmentation, and sophisticated video morphing (interpolation).

📂 Structural Overview

src/ ├── types/ - Data structure definitions (Schemas & Types) │ ├── schemas.ts - Input validation contracts (e.g., Zod definitions) │ └── types.ts - Fundamental type declarations ├── services/ - Encapsulation of primary business logic flow ├── handlers/ - Request routing and processing layer │ └── tool-handlers.ts ├── clients/ - External communication modules │ └── luma-client.ts ├── utils/ - Auxiliary routines │ └── error-handler.ts ├── config/ - Environment and operational configuration │ └── server-config.ts └── index.ts - Service bootstrap and initialization

🚀 Deployment

Installation via Node Package Manager:

bash npm install @sunwood-ai-labs/luma-mcp-server

⚙️ Configuration Requirements

1. Credential Acquisition: Secure your operational API key from the official Luma AI Developer Portal.

2. Environment Variable Setup: Configure the necessary secret using system environment variables: bash export LUMA_API_KEY=your_secure_api_key

🛠️ Exposed MCP Operations

synthesize_from_text (Maps to generate_video)

Initiates video rendering based purely on a textual narrative input.

typescript { name: 'synthesize_from_text', arguments: { prompt: "A teddy bear in sunglasses playing electric guitar and dancing", loop: true, // Optional: Set for seamless looping playback callback_url: "https://your-notification-endpoint.com" // Optional: For async result delivery } }

synthesize_from_image (Maps to generate_video_from_image)

Generates a dynamic sequence starting from a provided visual anchor frame.

typescript { name: 'synthesize_from_image', arguments: { prompt: "Low-angle shot of a majestic tiger prowling through a snowy landscape", image_url: "https://your-asset-storage.com/start-frame.jpg", loop: true, // Optional callback_url: "https://your-notification-endpoint.com" // Optional } }

extend_temporal_sequence (Maps to extend_video)

Processes an existing generated video ID to append new frames, continuing the motion.

typescript { name: 'extend_temporal_sequence', arguments: { prompt: "Continue the dance sequence", source_generation_id: "existing-video-g_id_12345", loop: true, // Optional callback_url: "https://your-notification-endpoint.com" // Optional } }

blend_sequences (Maps to interpolate_videos)

Calculates the visual path between two distinct generated video results for smooth, transitional output.

typescript { name: 'blend_sequences', arguments: { prompt: "Create a smooth transition between the videos", start_generation_id: "first-video-g_id_A", end_generation_id: "second-video-g_id_B", callback_url: "https://your-notification-endpoint.com" // Optional } }

🧑‍💻 Developer Reference

Internal Architecture Breakdown

• Data Contracts (types/): Defines structural integrity using precise specifications.
• schemas.ts: Implements validation schemata (Zod).

• types.ts: Core interfaces and shared data types.

• Request Handling (handlers/): Manages the ingress and dispatch of MCP tool calls.

• tool-handlers.ts: Core logic for mapping external calls to internal methods.

• External Communication (clients/): Dedicated module for interacting with the Luma AI remote service.

• luma-client.ts: Handles HTTP transactions and token management for Luma API.

• Utilities (utils/): Common support functions.

• error-handler.ts: Standardizes exception management.

• Configuration (config/): Centralized control over runtime settings.

• server-config.ts: Environment-aware parameter loading.

Error Management Protocol

• Adherence to a unified exception handling framework.
• Precise translation of internal faults into standard MCP error enumerations.
• Robust logging for debugging and auditing purposes.

⚠️ Operational Notes

• Optimal performance is achieved when input prompts are articulated in English.
• Video synthesis is an inherently resource-intensive operation and may incur significant latency.
• Users must monitor their designated Luma API usage quotas.

🫂 Contribution Guidelines

1. Fork the repository.
2. Create a feature branch (git checkout -b feat/new-capability).
3. Commit changes distinctly (git commit -m 'feat: Integrated new feature X').
4. Push the branch (git push origin feat/new-capability).
5. Submit a comprehensive Pull Request.

📜 Licensing

Distributed under the terms of the MIT License. See the LICENSE file for specifics.