thumbnailgpt 1.0.1 → 1.0.3

package/README.md

@@ -62,7 +62,8 @@ Add to `claude_desktop_config.json`:
 ```
 
 ### 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_generate`: Synthesize YouTube thumbnails with custom prompts, aspect ratios (`16:9`, `9:16`), resolutions (`1K`, `2K`, `4K`), reference images, and creator persona IDs (`personaId`).
+- `thumbnailgpt_get_personas`: Retrieve verified active creator personas (`id`, `name`). Raw image assets and unready personas are strictly protected and never exposed.
 - `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.
@@ -83,11 +84,23 @@ npx thumbnailgpt logout
 npx thumbnailgpt whoami
 ```
 
+### Creator Personas
+```bash
+# List your active creator personas (only ready personas with safe IDs/names are shown)
+npx thumbnailgpt personas list
+
+# New personas can only be trained in the Web UI
+npx thumbnailgpt personas add
+```
+
 ### Generate Thumbnails
 ```bash
 # Standard 16:9 1K thumbnail
 npx thumbnailgpt generate "Extreme Minecraft Hardcore Survival"
 
+# Generate thumbnail featuring your trained creator persona
+npx thumbnailgpt generate "24-Hour Survival Challenge" --persona <personaId>
+
 # 4K resolution saved to local file
 npx thumbnailgpt generate "Cyberpunk Underground Hacker Room" --resolution 4K --output ./thumb.webp
 

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import type { CreditBalanceResponse, StudioGenerateOptions, StudioDispatchResult, StudioConversationResponse, GenerationSettledResult } from "./types.js";
+import type { CreditBalanceResponse, StudioGenerateOptions, StudioDispatchResult, StudioConversationResponse, GenerationSettledResult, PersonaItem } from "./types.js";
 export declare class ThumbnailGPTClient {
     private apiKey;
     private apiUrl;
@@ -20,6 +20,12 @@ export declare class ThumbnailGPTClient {
      * List recent studio conversations
      */
     listChats(): Promise<any>;
+    /**
+     * Retrieve active, ready-to-use personas for the user.
+     * Only 'ready' personas are returned. Raw image URLs, character sheets,
+     * error traces, and database internals are strictly redacted.
+     */
+    getPersonas(): Promise<PersonaItem[]>;
     /**
      * Asynchronously dispatch and poll until completion
      */

package/dist/client.js

@@ -68,6 +68,19 @@ export class ThumbnailGPTClient {
     async listChats() {
         return this.request("/api/studio");
     }
+    /**
+     * Retrieve active, ready-to-use personas for the user.
+     * Only 'ready' personas are returned. Raw image URLs, character sheets,
+     * error traces, and database internals are strictly redacted.
+     */
+    async getPersonas() {
+        const res = await this.request("/api/personas");
+        return (res.personas || []).map((p) => ({
+            id: p.id,
+            name: p.name,
+            created_at: p.created_at,
+        }));
+    }
     /**
      * Asynchronously dispatch and poll until completion
      */

package/dist/index.js

@@ -9,7 +9,7 @@ const program = new Command();
 program
     .name("thumbnailgpt")
     .description("Official CLI and MCP server for ThumbnailGPT Studio")
-    .version("1.0.0");
+    .version("1.0.3");
 // 1. Auth Login
 program
     .command("login")
@@ -76,6 +76,7 @@ program
     .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("-p, --persona <personaId>", "Creator Persona UUID to feature in the thumbnail")
     .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) => {
@@ -90,6 +91,7 @@ program
                 resolution: options.res,
                 referenceImages: options.ref,
                 youtubeUrl: options.yt,
+                personaId: options.persona,
             });
             spinner.succeed("Generation dispatched successfully!");
             console.log(`\n${pc.bold("Chat ID:")}       ${dispatch.chatId}`);
@@ -105,6 +107,7 @@ program
             resolution: options.res,
             referenceImages: options.ref,
             youtubeUrl: options.yt,
+            personaId: options.persona,
         }, (elapsedSec) => {
             spinner.text = `Synthesizing thumbnail with AI [${elapsedSec}s elapsed]...`;
         });
@@ -245,7 +248,48 @@ chats
         process.exit(1);
     }
 });
-// 7. MCP Server Mode
+// 7. Creator Personas
+const personasCmd = program
+    .command("personas")
+    .description("Inspect active creator personas for thumbnail generation");
+personasCmd
+    .command("list")
+    .description("List your active creator personas (only ready personas are shown)")
+    .action(async () => {
+    try {
+        const client = new ThumbnailGPTClient();
+        const spinner = ora("Fetching active personas...").start();
+        const personas = await client.getPersonas();
+        spinner.stop();
+        if (personas.length === 0) {
+            console.log(pc.yellow("\nNo active personas found."));
+            console.log(`Train your first persona in the Web Studio at: ${pc.cyan("https://thumbnailgpt.com/studio")}\n`);
+            return;
+        }
+        console.log(pc.bold("\nActive Creator Personas:"));
+        console.log(pc.dim("--------------------------------------------------------------------------------"));
+        personas.forEach((p) => {
+            const dateStr = p.created_at ? pc.dim(new Date(p.created_at).toLocaleDateString()) : "";
+            console.log(`${pc.cyan(p.id)}  ${pc.bold(p.name)}  ${dateStr}`);
+        });
+        console.log(pc.dim("--------------------------------------------------------------------------------"));
+        console.log(`Use in generation: ${pc.green('npx thumbnailgpt generate "..." --persona <id>')}\n`);
+    }
+    catch (err) {
+        console.error(pc.red(`\n❌ Error: ${err.message}`));
+        process.exit(1);
+    }
+});
+personasCmd
+    .command("add")
+    .description("Instructions for creating and training a new creator persona")
+    .action(() => {
+    console.log(pc.bold("\nTraining New Creator Personas:"));
+    console.log("For quality and privacy, persona creation requires interactive multi-angle photo upload");
+    console.log("and face consistency training, which is exclusively supported in the Web Studio.");
+    console.log(`\n👉 Create your persona at: ${pc.cyan("https://thumbnailgpt.com/studio")}\n`);
+});
+// 8. MCP Server Mode
 program
     .command("mcp")
     .description("Run the ThumbnailGPT MCP server via standard I/O (stdio)")

package/dist/mcp.js

@@ -14,7 +14,7 @@ export async function runMcpServer() {
     const client = new ThumbnailGPTClient(apiKey);
     const server = new Server({
         name: "thumbnailgpt-mcp",
-        version: "1.0.0",
+        version: "1.0.3",
     }, {
         capabilities: {
             tools: {},
@@ -63,10 +63,22 @@ export async function runMcpServer() {
                                 type: "string",
                                 description: "Base image URL for inpainting / iterations.",
                             },
+                            personaId: {
+                                type: "string",
+                                description: "Optional UUID of an active Creator Persona to feature in the thumbnail. Get available persona IDs with thumbnailgpt_get_personas.",
+                            },
                         },
                         required: ["prompt"],
                     },
                 },
+                {
+                    name: "thumbnailgpt_get_personas",
+                    description: "Retrieve active, ready-to-use creator personas. Returns safe identifiers (id, name, created_at). Image URLs, internal storage paths, and failed personas are strictly omitted for privacy and security. (Note: New personas can only be trained in the Web UI at https://thumbnailgpt.com/studio).",
+                    inputSchema: {
+                        type: "object",
+                        properties: {},
+                    },
+                },
                 {
                     name: "thumbnailgpt_get_credits",
                     description: "Retrieve current ThumbnailGPT available credit balance, subscription status, and resolution cost tiers.",
@@ -119,6 +131,21 @@ export async function runMcpServer() {
                     ],
                 };
             }
+            if (name === "thumbnailgpt_get_personas") {
+                const personas = await client.getPersonas();
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                personas,
+                                count: personas.length,
+                                guidance: "Pass the persona 'id' to thumbnailgpt_generate as 'personaId' to render the creator in the thumbnail. To create new personas, use the Web UI at https://thumbnailgpt.com/studio.",
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
             if (name === "thumbnailgpt_generate") {
                 const prompt = args?.prompt || "";
                 const chatId = args?.chatId;
@@ -127,6 +154,7 @@ export async function runMcpServer() {
                 const referenceImages = args?.referenceImages;
                 const youtubeUrl = args?.youtubeUrl;
                 const baseImage = args?.baseImage;
+                const personaId = args?.personaId;
                 const result = await client.generateAndWait({
                     prompt,
                     chatId,
@@ -135,6 +163,7 @@ export async function runMcpServer() {
                     referenceImages,
                     youtubeUrl,
                     baseImage,
+                    personaId,
                 });
                 if (!result.success || !result.imageUrl) {
                     return {

package/dist/types.d.ts

@@ -65,3 +65,8 @@ export interface GenerationSettledResult {
     error?: string;
     creditsRemaining?: number;
 }
+export interface PersonaItem {
+    id: string;
+    name: string;
+    created_at?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "thumbnailgpt",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Official CLI and Model Context Protocol (MCP) server for ThumbnailGPT",
   "type": "module",
   "main": "dist/index.js",