framlit-mcp 0.1.1 → 0.2.0

package/README.md

@@ -1,8 +1,8 @@
-# Framlit MCP
+# Framlit MCP + CLI
 
-MCP (Model Context Protocol) server for [Framlit](https://framlit.app) - AI-powered video generation.
+MCP server and CLI for [Framlit](https://framlit.app) — AI-powered video generation.
 
-Generate Remotion videos directly from your IDE using natural language.
+Generate Remotion videos from your IDE or terminal using natural language.
 
 ## Features
 
@@ -11,6 +11,9 @@ Generate Remotion videos directly from your IDE using natural language.
 - **Project Management**: Create, list, and update Framlit projects
 - **Video Rendering**: Render videos to MP4 via AWS Lambda
 - **Templates**: Browse and use video templates
+- **Narration**: AI-generated voiceover with ElevenLabs TTS
+- **Style Variations**: Generate multiple visual styles from one prompt
+- **Batch Rendering**: Render multiple videos at once with variable substitution
 
 ## Installation
 
@@ -22,12 +25,13 @@ Generate Remotion videos directly from your IDE using natural language.
 ### Get Your API Key
 
 1. Go to [Framlit Settings](https://framlit.app/settings/api-keys)
-2. Click "Create API Key"
-3. Copy the key (you'll only see it once!)
+2. Click "Create Key" and copy the key (you'll only see it once!)
 
-### Configure in Cursor
+### MCP Server (IDE Integration)
 
-Add to your Cursor settings (`.cursor/mcp.json`):
+Add to your editor's MCP config:
+
+**Cursor** (`.cursor/mcp.json`), **Claude Desktop** (`claude_desktop_config.json`), **VS Code** (MCP settings), **Windsurf** (MCP settings):
 
 ```json
 {
@@ -43,43 +47,77 @@ Add to your Cursor settings (`.cursor/mcp.json`):
 }
 ```
 
-Or install globally:
+### CLI (Terminal)
 
 ```bash
+# Use directly via npx
+npx framlit generate "A logo animation with rotating 3D text"
+
+# Or install globally
 npm install -g framlit-mcp
+framlit generate "Product demo with fade-in text"
 ```
 
-## Usage
+## CLI Usage
 
-Once configured, you can use Framlit tools in Cursor:
+```bash
+# Generate video code
+framlit generate "Logo animation with rotating text" --format landscape
 
-### Generate Video Code
+# Modify existing code
+framlit modify --code ./video.tsx --instruction "Change background to blue"
 
-```
-Create a 3D logo animation with the text "HELLO" rotating in space
-```
+# Manage projects
+framlit projects list
+framlit projects get <id>
+framlit projects create "My Video" --code ./video.tsx
+framlit projects update <id> --name "New Name"
 
-The AI will use `framlit_generate_code` to generate Remotion code.
+# Render video
+framlit render <projectId>
+framlit render status <renderId> --poll   # Stream progress as NDJSON
 
-### Modify Existing Code
+# Browse templates
+framlit templates --category social
 
-```
-Change the background color to blue and make the text larger
-```
+# Preview code
+framlit preview ./video.tsx
 
-Uses `framlit_modify_code` with your existing code.
+# Check credits
+framlit credits
 
-### Manage Projects
+# Discover tool schemas (agent-friendly)
+framlit schema                           # List all tools
+framlit schema framlit_generate_code     # JSON Schema for a specific tool
 
-```
-List my Framlit projects
-Create a new project called "Product Demo"
+# Start MCP server from CLI
+framlit mcp
 ```
 
-### Render Video
+### Agent-Friendly Features
 
-```
-Render the project to MP4
+The CLI is designed to work seamlessly with AI agents:
+
+- **`--output json`**: Structured JSON output (auto-enabled when piped)
+- **`--json '{"prompt":"..."}'`**: Raw JSON input, bypass arg parsing
+- **`--dry-run`**: Preview mutations without executing
+- **`framlit schema <tool>`**: Runtime schema introspection (Zod → JSON Schema)
+- **`--poll`**: NDJSON streaming for render progress tracking
+
+### Full Render Workflow
+
+```bash
+# 1. Generate code
+framlit generate "Product demo video" --output json > code.json
+
+# 2. Create a project
+framlit projects create "Product Demo" --code ./generated.tsx --output json
+
+# 3. Start render
+framlit render <projectId> --output json
+
+# 4. Poll until complete
+framlit render status <renderId> --poll
 ```
 
 ## Available Tools
@@ -89,27 +127,40 @@ Render the project to MP4
 | `framlit_generate_code` | Generate Remotion code from text | 1 |
 | `framlit_modify_code` | Modify existing code | 1 |
 | `framlit_list_projects` | List your projects | 0 |
-| `framlit_get_project` | Get project details | 0 |
+| `framlit_get_project` | Get project details with code | 0 |
 | `framlit_create_project` | Create a new project | 0 |
 | `framlit_update_project` | Update a project | 0 |
 | `framlit_render_video` | Start video rendering | 0 |
 | `framlit_get_render_status` | Check render progress | 0 |
 | `framlit_list_templates` | Browse templates | 0 |
 | `framlit_get_credits` | Check credit balance | 0 |
+| `framlit_preview_code` | Create temporary preview URL | 0 |
 
 ## Pricing
 
-MCP uses the same credit system as the Framlit web app:
+MCP and CLI use the same credit system as the Framlit web app:
+
+- **Hobby (Free)**: 30 credits/month
+- **Pro**: 500 credits/month ($29/mo)
+- **Team**: 2,000 credits/month ($99/mo)
+- **Credit Packs**: 100 for $6 / 350 for $19 / 700 for $35
 
-- **Free Plan**: 50 credits/month
-- **Pro Plan**: 500 credits/month ($29/mo)
-- **Credit Packs**: Available for purchase
+### Credit Costs
 
-Each code generation or modification costs 1 credit.
+| Action | Credits |
+|--------|---------|
+| Text-to-Code generation | 1 |
+| Code modification | 1 |
+| Image analysis | 3 |
+| Narration (voiceover) | 5 |
+| Style variation | 1 |
+| Batch rendering (per video) | 0.2 |
+| MP4 rendering | 0 |
+| Preview | 0 |
 
 ### Watermark
 
-- Free/Hobby plans: Videos include a Framlit watermark
+- Hobby plan: Videos include a Framlit watermark
 - Pro/Team plans: No watermark
 
 [View Pricing](https://framlit.app/pricing)
@@ -120,14 +171,20 @@ Each code generation or modification costs 1 credit.
 # Install dependencies
 npm install
 
-# Run in development mode
+# Run MCP server in development mode
 npm run dev
 
+# Run CLI in development mode
+npm run dev:cli -- generate "test"
+
 # Build
 npm run build
 
-# Test locally
+# Test MCP server locally
 FRAMLIT_API_KEY=fml_xxx npm start
+
+# Test CLI locally
+FRAMLIT_API_KEY=fml_xxx npm run start:cli -- credits
 ```
 
 ## Environment Variables
@@ -140,8 +197,9 @@ FRAMLIT_API_KEY=fml_xxx npm start
 ## Resources
 
 - [Framlit Website](https://framlit.app)
+- [Developer Guide](https://framlit.app/developers)
 - [Documentation](https://framlit.app/docs)
-- [Pricing](https://framlit.app/pricing)
+- [Pricing](https://framlit.app/docs/pricing)
 - [API Key Settings](https://framlit.app/settings/api-keys)
 
 ## License

package/dist/api/client.js

@@ -21,7 +21,7 @@ class FramlitClient {
             headers: {
                 'Authorization': `Bearer ${this.apiKey}`,
                 'Content-Type': 'application/json',
-                'User-Agent': 'framlit-mcp/0.1.0',
+                'User-Agent': 'framlit-mcp/0.2.0',
                 ...options.headers,
             },
         });

package/dist/cli/index.d.ts

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * Framlit CLI
+ *
+ * Human-friendly and agent-friendly CLI for Framlit.
+ * Shares core logic with the MCP server.
+ *
+ * Usage:
+ *   framlit generate <prompt> [--format landscape|portrait|square] [--output json|text] [--dry-run]
+ *   framlit modify --code <code|file> --instruction <text> [--output json|text] [--dry-run]
+ *   framlit projects list [--output json|text]
+ *   framlit projects get <id>
+ *   framlit projects create <name> --code <code|file> [--format landscape|portrait|square] [--dry-run]
+ *   framlit projects update <id> [--name <name>] [--code <code|file>] [--dry-run]
+ *   framlit render <projectId> [--dry-run]
+ *   framlit render status <renderId> [--poll] [--output json|text]
+ *   framlit templates [--category <cat>] [--official]
+ *   framlit preview <code|file>
+ *   framlit credits [--output json|text]
+ *   framlit schema [tool-name]
+ *   framlit mcp
+ *   framlit version
+ *   framlit help
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cli/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}