thumbnailgpt 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+# ThumbnailGPT CLI & MCP Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official command-line interface and [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for **[ThumbnailGPT](https://thumbnailgpt.com)**.
+
+Create viral, high-CTR YouTube thumbnails directly from your terminal or AI code assistants (Cursor, Claude Desktop, Windsurf).
+
+---
+
+## Quick Start (Zero Install)
+
+You can run commands directly using `npx`:
+
+```bash
+# 1. Log in with your Personal API Key (get one from https://thumbnailgpt.com/settings)
+npx thumbnailgpt login
+
+# 2. Check your credit balance & user identity
+npx thumbnailgpt whoami
+
+# 3. Generate a thumbnail
+npx thumbnailgpt generate "Surviving 24 Hours in Arctic Snow" --resolution 2K --output ./thumb.webp
+```
+
+---
+
+## MCP Server Setup (Cursor & Claude Desktop)
+
+The package includes a built-in stdio MCP server.
+
+### 1. Cursor IDE Setup
+Add to your project's `.cursor/mcp.json` or your global Cursor settings:
+
+```json
+{
+  "mcpServers": {
+    "thumbnailgpt": {
+      "command": "npx",
+      "args": ["-y", "thumbnailgpt", "mcp"],
+      "env": {
+        "THUMBNAILGPT_API_KEY": "tgpt_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### 2. Claude Desktop Setup
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "thumbnailgpt": {
+      "command": "npx",
+      "args": ["-y", "thumbnailgpt", "mcp"],
+      "env": {
+        "THUMBNAILGPT_API_KEY": "tgpt_live_YOUR_KEY_HERE"
+      }
+    }
+  }
+}
+```
+
+### Exposed MCP Tools:
+- `thumbnailgpt_generate`: Synthesize YouTube thumbnails with custom prompts, aspect ratios (`16:9`, `9:16`), resolutions (`1K`, `2K`, `4K`), and reference images.
+- `thumbnailgpt_get_credits`: Query available credits and subscription status.
+- `thumbnailgpt_list_chats`: List recent Studio conversation sessions.
+- `thumbnailgpt_get_chat`: Retrieve full message history and generated thumbnail URLs.
+
+---
+
+## CLI Commands Reference
+
+### Authentication
+```bash
+# Interactive login
+npx thumbnailgpt login
+
+# Clear saved credentials
+npx thumbnailgpt logout
+
+# Print active profile & balance
+npx thumbnailgpt whoami
+```
+
+### Generate Thumbnails
+```bash
+# Standard 16:9 1K thumbnail
+npx thumbnailgpt generate "Extreme Minecraft Hardcore Survival"
+
+# 4K resolution saved to local file
+npx thumbnailgpt generate "Cyberpunk Underground Hacker Room" --resolution 4K --output ./thumb.webp
+
+# 9:16 Shorts format with reference image URL
+npx thumbnailgpt generate "Shocked reaction expression" --aspect 9:16 --ref "https://example.com/face.png"
+
+# Recreate thumbnail from YouTube video URL
+npx thumbnailgpt generate "Upgrade lighting and contrast" --youtube "https://youtube.com/watch?v=VIDEO_ID"
+```
+
+### Interactive Studio Mode
+```bash
+# Launch interactive conversation session in terminal
+npx thumbnailgpt studio
+
+# List all past studio conversations
+npx thumbnailgpt chats list
+
+# View messages and image URLs of a specific conversation
+npx thumbnailgpt chats show <chatId>
+```
+
+---
+
+## Environment Variables
+
+- `THUMBNAILGPT_API_KEY`: Your Personal API Key (`tgpt_live_...`). If set, overrides the stored login credentials.
+- `THUMBNAILGPT_API_URL`: Custom backend gateway URL (defaults to `https://thumbnailgpt.com`).
+
+---
+
+## License
+
+MIT © [ThumbnailGPT](https://thumbnailgpt.com)

package/bin/thumbnailgpt.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+import("../dist/index.js").catch((err) => {
+  console.error("Failed to run thumbnailgpt CLI:", err);
+  process.exit(1);
+});

package/dist/client.d.ts

@@ -0,0 +1,31 @@
+import type { CreditBalanceResponse, StudioGenerateOptions, StudioDispatchResult, StudioConversationResponse, GenerationSettledResult } from "./types.js";
+export declare class ThumbnailGPTClient {
+    private apiKey;
+    private apiUrl;
+    constructor(apiKey?: string, apiUrl?: string);
+    private request;
+    /**
+     * Check current user credit balance and plan status
+     */
+    getCredits(): Promise<CreditBalanceResponse>;
+    /**
+     * Dispatch a studio generation job
+     */
+    dispatchStudio(options: StudioGenerateOptions): Promise<StudioDispatchResult>;
+    /**
+     * Fetch conversation messages and thumbnails
+     */
+    getChat(chatId: string): Promise<StudioConversationResponse>;
+    /**
+     * List recent studio conversations
+     */
+    listChats(): Promise<any>;
+    /**
+     * Asynchronously dispatch and poll until completion
+     */
+    generateAndWait(options: StudioGenerateOptions, onProgress?: (elapsedSec: number, status: string) => void, timeoutSec?: number): Promise<GenerationSettledResult>;
+    /**
+     * Download image to local filesystem
+     */
+    downloadImage(imageUrl: string, outputPath: string): Promise<string>;
+}

package/dist/client.js

@@ -0,0 +1,152 @@
+import { getApiKey, getApiUrl } from "./config.js";
+import fs from "fs";
+import path from "path";
+export class ThumbnailGPTClient {
+    apiKey;
+    apiUrl;
+    constructor(apiKey, apiUrl) {
+        this.apiKey = (apiKey || getApiKey() || "").trim();
+        this.apiUrl = (apiUrl || getApiUrl() || "").replace(/\/$/, "");
+        if (!this.apiKey) {
+            throw new Error("Missing ThumbnailGPT API Key. Run 'thumbnailgpt login' or set the THUMBNAILGPT_API_KEY environment variable.");
+        }
+    }
+    async request(endpoint, options = {}) {
+        const url = `${this.apiUrl}${endpoint.startsWith("/") ? "" : "/"}${endpoint}`;
+        const headers = {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${this.apiKey}`,
+            ...options.headers,
+        };
+        const res = await fetch(url, { ...options, headers });
+        const data = (await res.json().catch(() => ({})));
+        if (!res.ok) {
+            const errorMsg = data.error ||
+                data.message ||
+                `Request failed with status ${res.status}: ${res.statusText}`;
+            const err = new Error(errorMsg);
+            err.status = res.status;
+            err.data = data;
+            throw err;
+        }
+        return data;
+    }
+    /**
+     * Check current user credit balance and plan status
+     */
+    async getCredits() {
+        return this.request("/api/credits/balance");
+    }
+    /**
+     * Dispatch a studio generation job
+     */
+    async dispatchStudio(options) {
+        return this.request("/api/studio", {
+            method: "POST",
+            body: JSON.stringify({
+                chatId: options.chatId,
+                feature: "recreate_thumbnail",
+                prompt: options.prompt,
+                aspectRatio: options.aspectRatio || "16:9",
+                resolution: options.resolution || "1K",
+                referenceImages: options.referenceImages || [],
+                youtubeUrl: options.youtubeUrl,
+                personaId: options.personaId,
+                baseImage: options.baseImage,
+            }),
+        });
+    }
+    /**
+     * Fetch conversation messages and thumbnails
+     */
+    async getChat(chatId) {
+        return this.request(`/api/studio/${chatId}`);
+    }
+    /**
+     * List recent studio conversations
+     */
+    async listChats() {
+        return this.request("/api/studio");
+    }
+    /**
+     * Asynchronously dispatch and poll until completion
+     */
+    async generateAndWait(options, onProgress, timeoutSec = 120) {
+        // 1. Credit Pre-check
+        const credits = await this.getCredits();
+        const resolutionCosts = { "1K": 10, "2K": 20, "4K": 30 };
+        const required = resolutionCosts[options.resolution || "1K"] || 10;
+        if (credits.credits < required) {
+            throw new Error(`Insufficient credits. Required: ${required}, Available: ${credits.credits}. Top up at https://thumbnailgpt.com/pricing`);
+        }
+        // 2. Dispatch generation
+        const dispatch = await this.dispatchStudio(options);
+        const chatId = dispatch.chatId;
+        const targetThumbnailId = dispatch.thumbnailId;
+        const startTime = Date.now();
+        const maxMs = timeoutSec * 1000;
+        // 3. Poll loop
+        while (Date.now() - startTime < maxMs) {
+            await new Promise((r) => setTimeout(r, 2000));
+            const elapsed = Math.round((Date.now() - startTime) / 1000);
+            try {
+                const thread = await this.getChat(chatId);
+                const thumbs = thread.thumbnails || [];
+                // Match thumbnail by ID or latest
+                const matched = thumbs.find((t) => t.id === targetThumbnailId) ||
+                    thumbs[thumbs.length - 1];
+                if (matched) {
+                    if (matched.status === "failed") {
+                        const errorReason = matched.error_reason || "Generation failed. Your credits were automatically refunded.";
+                        return {
+                            success: false,
+                            chatId,
+                            thumbnailId: matched.id,
+                            prompt: options.prompt,
+                            status: "failed",
+                            error: errorReason,
+                        };
+                    }
+                    if (matched.thumbnail_url && (matched.status === "completed" || matched.status === "success")) {
+                        const remaining = await this.getCredits().catch(() => ({ credits: credits.credits - required }));
+                        return {
+                            success: true,
+                            chatId,
+                            thumbnailId: matched.id,
+                            imageUrl: matched.thumbnail_url,
+                            prompt: options.prompt,
+                            status: "completed",
+                            creditsRemaining: remaining.credits,
+                        };
+                    }
+                }
+                if (onProgress) {
+                    onProgress(elapsed, "Synthesizing thumbnail with AI...");
+                }
+            }
+            catch (pollErr) {
+                console.warn(`[ThumbnailGPTClient] Polling check warning:`, pollErr.message);
+            }
+        }
+        return {
+            success: false,
+            chatId,
+            prompt: options.prompt,
+            status: "timeout",
+            error: `Generation timed out after ${timeoutSec}s. Check status later with 'thumbnailgpt chats show ${chatId}'`,
+        };
+    }
+    /**
+     * Download image to local filesystem
+     */
+    async downloadImage(imageUrl, outputPath) {
+        const res = await fetch(imageUrl);
+        if (!res.ok)
+            throw new Error(`Failed to download image from ${imageUrl}`);
+        const buffer = Buffer.from(await res.arrayBuffer());
+        const resolvedPath = path.resolve(outputPath);
+        fs.mkdirSync(path.dirname(resolvedPath), { recursive: true });
+        fs.writeFileSync(resolvedPath, buffer);
+        return resolvedPath;
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_API_URL: string;
+export declare function getApiKey(): string | undefined;
+export declare function setApiKey(apiKey: string): void;
+export declare function clearApiKey(): void;
+export declare function getApiUrl(): string;
+export declare function setApiUrl(url: string): void;

package/dist/config.js

@@ -0,0 +1,20 @@
+import Conf from "conf";
+const config = new Conf({
+    projectName: "thumbnailgpt",
+});
+export const DEFAULT_API_URL = process.env.THUMBNAILGPT_API_URL || "https://thumbnailgpt.com";
+export function getApiKey() {
+    return process.env.THUMBNAILGPT_API_KEY || config.get("apiKey");
+}
+export function setApiKey(apiKey) {
+    config.set("apiKey", apiKey.trim());
+}
+export function clearApiKey() {
+    config.delete("apiKey");
+}
+export function getApiUrl() {
+    return process.env.THUMBNAILGPT_API_URL || config.get("apiUrl") || DEFAULT_API_URL;
+}
+export function setApiUrl(url) {
+    config.set("apiUrl", url.trim().replace(/\/$/, ""));
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/index.js

@@ -0,0 +1,255 @@
+import { Command } from "commander";
+import readline from "readline";
+import ora from "ora";
+import pc from "picocolors";
+import { setApiKey, clearApiKey, getApiUrl } from "./config.js";
+import { ThumbnailGPTClient } from "./client.js";
+import { runMcpServer } from "./mcp.js";
+const program = new Command();
+program
+    .name("thumbnailgpt")
+    .description("Official CLI and MCP server for ThumbnailGPT Studio")
+    .version("1.0.0");
+// 1. Auth Login
+program
+    .command("login")
+    .description("Authenticate the CLI with your Personal API Key")
+    .option("-k, --key <key>", "Pass the API key directly")
+    .action(async (options) => {
+    if (options.key) {
+        setApiKey(options.key);
+        console.log(pc.green("✔ API key saved successfully!"));
+        return;
+    }
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    console.log(pc.bold("\nThumbnailGPT Authentication"));
+    console.log(pc.gray("Generate an API key in your Web Studio at: Settings -> Developers -> API Keys & MCP\n"));
+    rl.question(pc.cyan("Enter your Personal API Key (tgpt_live_...): "), (key) => {
+        rl.close();
+        const trimmed = key.trim();
+        if (!trimmed.startsWith("tgpt_live_")) {
+            console.error(pc.red("\n❌ Invalid format. API keys begin with 'tgpt_live_'"));
+            process.exit(1);
+        }
+        setApiKey(trimmed);
+        console.log(pc.green("\n✔ Logged in successfully! Key saved to local config."));
+    });
+});
+// 2. Auth Logout
+program
+    .command("logout")
+    .description("Log out and clear stored API key")
+    .action(() => {
+    clearApiKey();
+    console.log(pc.green("✔ Logged out. Stored credentials cleared."));
+});
+// 3. Whoami / Credits
+program
+    .command("whoami")
+    .description("Display your account and available credit balance")
+    .action(async () => {
+    try {
+        const client = new ThumbnailGPTClient();
+        const spinner = ora("Fetching account details...").start();
+        const credits = await client.getCredits();
+        spinner.stop();
+        console.log(pc.bold("\nThumbnailGPT Account"));
+        console.log(`${pc.gray("Endpoint:")}     ${getApiUrl()}`);
+        console.log(`${pc.gray("Plan Status:")}  ${pc.cyan(credits.subscription_status.toUpperCase())}`);
+        console.log(`${pc.gray("Credits:")}      ${pc.green(pc.bold(String(credits.credits)))} available`);
+        console.log(`${pc.gray("Cost Tiers:")}  1K = 10 cr | 2K = 20 cr | 4K = 30 cr\n`);
+    }
+    catch (err) {
+        console.error(pc.red(`\n❌ Error: ${err.message}`));
+        process.exit(1);
+    }
+});
+// 4. One-shot Generate
+program
+    .command("generate <prompt>")
+    .description("Generate a YouTube thumbnail from a prompt")
+    .option("-r, --ratio <ratio>", "Aspect ratio: 16:9 or 9:16", "16:9")
+    .option("-q, --res <resolution>", "Resolution: 1K, 2K, or 4K", "1K")
+    .option("--ref <urls...>", "Reference image file paths or URLs (max 5)")
+    .option("--yt <url>", "YouTube video URL for reference")
+    .option("-c, --chat <chatId>", "Continue an existing studio conversation thread")
+    .option("-o, --out <filepath>", "Download result directly to file (e.g. ./thumb.png)")
+    .option("--async", "Dispatch job and return immediately without waiting")
+    .action(async (prompt, options) => {
+    try {
+        const client = new ThumbnailGPTClient();
+        if (options.async) {
+            const spinner = ora("Dispatching to ThumbnailGPT Studio...").start();
+            const dispatch = await client.dispatchStudio({
+                prompt,
+                chatId: options.chat,
+                aspectRatio: options.ratio,
+                resolution: options.res,
+                referenceImages: options.ref,
+                youtubeUrl: options.yt,
+            });
+            spinner.succeed("Generation dispatched successfully!");
+            console.log(`\n${pc.bold("Chat ID:")}       ${dispatch.chatId}`);
+            console.log(`${pc.bold("Thumbnail ID:")}  ${dispatch.thumbnailId || "Pending"}`);
+            console.log(`Check status with: ${pc.cyan(`thumbnailgpt chats show ${dispatch.chatId}`)}\n`);
+            return;
+        }
+        const spinner = ora("Validating credits & dispatching...").start();
+        const result = await client.generateAndWait({
+            prompt,
+            chatId: options.chat,
+            aspectRatio: options.ratio,
+            resolution: options.res,
+            referenceImages: options.ref,
+            youtubeUrl: options.yt,
+        }, (elapsedSec) => {
+            spinner.text = `Synthesizing thumbnail with AI [${elapsedSec}s elapsed]...`;
+        });
+        if (!result.success || !result.imageUrl) {
+            spinner.fail(`Generation failed: ${result.error}`);
+            process.exit(1);
+        }
+        spinner.succeed(pc.green("Thumbnail generated successfully!"));
+        console.log(`\n${pc.bold("Image URL:")}       ${pc.cyan(result.imageUrl)}`);
+        console.log(`${pc.bold("Chat ID:")}         ${result.chatId}`);
+        console.log(`${pc.bold("Credits Left:")}    ${result.creditsRemaining ?? "N/A"}`);
+        console.log(`${pc.bold("Web Studio:")}      https://thumbnailgpt.com/studio/${result.chatId}`);
+        if (options.out) {
+            const downloadSpinner = ora(`Downloading to ${options.out}...`).start();
+            const savedPath = await client.downloadImage(result.imageUrl, options.out);
+            downloadSpinner.succeed(`Saved to ${pc.green(savedPath)}`);
+        }
+        console.log();
+    }
+    catch (err) {
+        console.error(pc.red(`\n❌ Error: ${err.message}`));
+        process.exit(1);
+    }
+});
+// 5. Interactive Studio TUI REPL
+program
+    .command("studio [initialChatId]")
+    .description("Launch an interactive conversation Studio session in your terminal")
+    .action(async (initialChatId) => {
+    try {
+        const client = new ThumbnailGPTClient();
+        let currentChatId = initialChatId;
+        console.clear();
+        console.log(pc.bold(pc.yellow("✦ ThumbnailGPT Studio CLI ✦")));
+        const credits = await client.getCredits();
+        console.log(`${pc.gray("Credits:")} ${pc.green(String(credits.credits))} • ${pc.gray("Plan:")} ${credits.subscription_status}`);
+        if (currentChatId) {
+            console.log(`${pc.gray("Resuming thread:")} ${currentChatId}`);
+        }
+        console.log(pc.gray("Type your prompt or visual tweak. Press Ctrl+C anytime to exit.\n"));
+        const rl = readline.createInterface({
+            input: process.stdin,
+            output: process.stdout,
+        });
+        const askPrompt = () => {
+            rl.question(pc.cyan("\nstudio > "), async (input) => {
+                const text = input.trim();
+                if (!text) {
+                    askPrompt();
+                    return;
+                }
+                const spinner = ora("Generating thumbnail...").start();
+                try {
+                    const result = await client.generateAndWait({
+                        prompt: text,
+                        chatId: currentChatId,
+                        aspectRatio: "16:9",
+                        resolution: "1K",
+                    }, (elapsed) => {
+                        spinner.text = `Synthesizing with AI [${elapsed}s elapsed]...`;
+                    });
+                    if (!result.success || !result.imageUrl) {
+                        spinner.fail(`Failed: ${result.error}`);
+                    }
+                    else {
+                        currentChatId = result.chatId;
+                        spinner.succeed(pc.green("Thumbnail updated!"));
+                        console.log(`${pc.bold("Image:")}      ${pc.cyan(result.imageUrl)}`);
+                        console.log(`${pc.bold("Remaining:")}  ${result.creditsRemaining} credits`);
+                        console.log(`${pc.gray("Web Studio:")} https://thumbnailgpt.com/studio/${currentChatId}`);
+                    }
+                }
+                catch (err) {
+                    spinner.fail(`Error: ${err.message}`);
+                }
+                askPrompt();
+            });
+        };
+        askPrompt();
+    }
+    catch (err) {
+        console.error(pc.red(`\n❌ Error: ${err.message}`));
+        process.exit(1);
+    }
+});
+// 6. Chats Subcommand
+const chats = program.command("chats").description("Manage studio conversations");
+chats
+    .command("list")
+    .description("List recent studio conversations")
+    .action(async () => {
+    try {
+        const client = new ThumbnailGPTClient();
+        const spinner = ora("Fetching conversations...").start();
+        const res = await client.listChats();
+        spinner.stop();
+        const chatList = res.chats || [];
+        if (chatList.length === 0) {
+            console.log(pc.gray("No conversations found."));
+            return;
+        }
+        console.log(pc.bold("\nRecent Studio Conversations:\n"));
+        chatList.forEach((c) => {
+            console.log(`• ${pc.bold(c.title || "Untitled")} ${pc.gray(`(${c.id})`)}`);
+            console.log(`  ${pc.gray("Updated:")} ${new Date(c.updated_at).toLocaleString()}`);
+        });
+        console.log();
+    }
+    catch (err) {
+        console.error(pc.red(`\n❌ Error: ${err.message}`));
+        process.exit(1);
+    }
+});
+chats
+    .command("show <chatId>")
+    .description("View conversation history and thumbnails")
+    .action(async (chatId) => {
+    try {
+        const client = new ThumbnailGPTClient();
+        const spinner = ora("Fetching thread...").start();
+        const res = await client.getChat(chatId);
+        spinner.stop();
+        console.log(pc.bold(`\nThread: ${res.chat?.title || chatId}\n`));
+        (res.messages || []).forEach((m) => {
+            const prefix = m.role === "user" ? pc.cyan("You:") : pc.yellow("Assistant:");
+            console.log(`${prefix} ${m.content}`);
+        });
+        if (res.thumbnails && res.thumbnails.length > 0) {
+            console.log(pc.bold("\nThumbnails:"));
+            res.thumbnails.forEach((t) => {
+                console.log(`• [${t.status}] ${t.thumbnail_url || "Processing"}`);
+            });
+        }
+        console.log();
+    }
+    catch (err) {
+        console.error(pc.red(`\n❌ Error: ${err.message}`));
+        process.exit(1);
+    }
+});
+// 7. MCP Server Mode
+program
+    .command("mcp")
+    .description("Run the ThumbnailGPT MCP server via standard I/O (stdio)")
+    .action(async () => {
+    await runMcpServer();
+});
+program.parse(process.argv);

package/dist/mcp.d.ts

@@ -0,0 +1 @@
+export declare function runMcpServer(): Promise<void>;

package/dist/mcp.js

@@ -0,0 +1,202 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { ThumbnailGPTClient } from "./client.js";
+import { getApiKey } from "./config.js";
+export async function runMcpServer() {
+    const apiKey = getApiKey();
+    if (!apiKey) {
+        console.error(JSON.stringify({
+            error: "Missing THUMBNAILGPT_API_KEY. Set it in your environment or run 'thumbnailgpt login'.",
+        }));
+        process.exit(1);
+    }
+    const client = new ThumbnailGPTClient(apiKey);
+    const server = new Server({
+        name: "thumbnailgpt-mcp",
+        version: "1.0.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // 1. List available tools
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        return {
+            tools: [
+                {
+                    name: "thumbnailgpt_generate",
+                    description: "Create or iteratively refine high-CTR YouTube thumbnails using ThumbnailGPT Studio. Supports aspect ratios, reference images, creator personas, and resolution tiers.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            prompt: {
+                                type: "string",
+                                description: "Detailed instructions for thumbnail creation, style direction, text overlays, or visual tweaks.",
+                            },
+                            chatId: {
+                                type: "string",
+                                description: "Optional UUID of an existing conversation thread to iterate on. Omit to start a new chat.",
+                            },
+                            aspectRatio: {
+                                type: "string",
+                                enum: ["16:9", "9:16"],
+                                default: "16:9",
+                                description: "16:9 for YouTube standard videos, 9:16 for Shorts / Reels.",
+                            },
+                            resolution: {
+                                type: "string",
+                                enum: ["1K", "2K", "4K"],
+                                default: "1K",
+                                description: "1K (10 credits), 2K (20 credits), 4K (30 credits).",
+                            },
+                            referenceImages: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Up to 5 reference image URLs or base64 strings.",
+                            },
+                            youtubeUrl: {
+                                type: "string",
+                                description: "Optional YouTube video URL for context.",
+                            },
+                            baseImage: {
+                                type: "string",
+                                description: "Base image URL for inpainting / iterations.",
+                            },
+                        },
+                        required: ["prompt"],
+                    },
+                },
+                {
+                    name: "thumbnailgpt_get_credits",
+                    description: "Retrieve current ThumbnailGPT available credit balance, subscription status, and resolution cost tiers.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                {
+                    name: "thumbnailgpt_list_chats",
+                    description: "List recent ThumbnailGPT studio conversations and thumbnail sessions.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
+                {
+                    name: "thumbnailgpt_get_chat",
+                    description: "Retrieve full message history and generated thumbnails for a studio conversation.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            chatId: {
+                                type: "string",
+                                description: "UUID of the conversation thread to inspect.",
+                            },
+                        },
+                        required: ["chatId"],
+                    },
+                },
+            ],
+        };
+    });
+    // 2. Handle tool execution
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            if (name === "thumbnailgpt_get_credits") {
+                const credits = await client.getCredits();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                availableCredits: credits.credits,
+                                subscriptionStatus: credits.subscription_status,
+                                costs: { "1K": "10 credits", "2K": "20 credits", "4K": "30 credits" },
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            if (name === "thumbnailgpt_generate") {
+                const prompt = args?.prompt || "";
+                const chatId = args?.chatId;
+                const aspectRatio = args?.aspectRatio || "16:9";
+                const resolution = args?.resolution || "1K";
+                const referenceImages = args?.referenceImages;
+                const youtubeUrl = args?.youtubeUrl;
+                const baseImage = args?.baseImage;
+                const result = await client.generateAndWait({
+                    prompt,
+                    chatId,
+                    aspectRatio,
+                    resolution,
+                    referenceImages,
+                    youtubeUrl,
+                    baseImage,
+                });
+                if (!result.success || !result.imageUrl) {
+                    return {
+                        isError: true,
+                        content: [
+                            {
+                                type: "text",
+                                text: `❌ Thumbnail generation failed: ${result.error || "Unknown error"}\nChat ID: ${result.chatId}`,
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `✅ Thumbnail successfully generated!\n\n` +
+                                `**Preview**: ![Generated Thumbnail](${result.imageUrl})\n\n` +
+                                `**Direct Image URL**: ${result.imageUrl}\n` +
+                                `**Conversation Thread ID**: \`${result.chatId}\` (pass this \`chatId\` to iterate or refine)\n` +
+                                `**Remaining Credits**: ${result.creditsRemaining ?? "N/A"}\n` +
+                                `**Web Studio Link**: https://thumbnailgpt.com/studio/${result.chatId}`,
+                        },
+                    ],
+                };
+            }
+            if (name === "thumbnailgpt_list_chats") {
+                const chats = await client.listChats();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(chats, null, 2),
+                        },
+                    ],
+                };
+            }
+            if (name === "thumbnailgpt_get_chat") {
+                const chatId = args?.chatId;
+                const thread = await client.getChat(chatId);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(thread, null, 2),
+                        },
+                    ],
+                };
+            }
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Unknown tool: ${name}` }],
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [{ type: "text", text: `Error: ${err.message || String(err)}` }],
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("ThumbnailGPT MCP server running on stdio");
+}

package/dist/types.d.ts

@@ -0,0 +1,67 @@
+export type AspectRatio = "16:9" | "9:16";
+export type Resolution = "1K" | "2K" | "4K";
+export interface StudioGenerateOptions {
+    prompt: string;
+    chatId?: string;
+    aspectRatio?: AspectRatio;
+    resolution?: Resolution;
+    referenceImages?: string[];
+    youtubeUrl?: string;
+    personaId?: string;
+    baseImage?: string;
+}
+export interface StudioDispatchResult {
+    success: boolean;
+    chatId: string;
+    batchId?: string;
+    taskId?: string;
+    thumbnailId?: string;
+    message?: string;
+    error?: string;
+    requiredCredits?: number;
+    availableCredits?: number;
+}
+export interface CreditBalanceResponse {
+    credits: number;
+    subscription_status: string;
+    error?: string;
+}
+export interface ThumbnailItem {
+    id: string;
+    chat_id?: string;
+    thumbnail_url?: string;
+    status?: string;
+    error_reason?: string;
+    prompt?: string;
+    created_at: string;
+}
+export interface ChatMessageItem {
+    id: string;
+    chat_id: string;
+    role: "user" | "assistant";
+    content: string;
+    status?: string;
+    created_at: string;
+}
+export interface StudioConversationResponse {
+    success: boolean;
+    chat?: {
+        id: string;
+        title: string;
+        created_at: string;
+        updated_at: string;
+    };
+    messages?: ChatMessageItem[];
+    thumbnails?: ThumbnailItem[];
+    error?: string;
+}
+export interface GenerationSettledResult {
+    success: boolean;
+    chatId: string;
+    thumbnailId?: string;
+    imageUrl?: string;
+    prompt: string;
+    status: "completed" | "failed" | "timeout";
+    error?: string;
+    creditsRemaining?: number;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "thumbnailgpt",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Official CLI and Model Context Protocol (MCP) server for ThumbnailGPT",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "thumbnailgpt": "bin/thumbnailgpt.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "mcp": "node dist/index.js mcp"
+  },
+  "keywords": [
+    "thumbnailgpt",
+    "mcp",
+    "model-context-protocol",
+    "youtube",
+    "thumbnails",
+    "ai",
+    "claude-desktop",
+    "cursor"
+  ],
+  "author": "ThumbnailGPT",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "commander": "^13.1.0",
+    "conf": "^13.1.0",
+    "ora": "^8.2.0",
+    "picocolors": "^1.1.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.4",
+    "typescript": "^5.7.3"
+  }
+}