@hubfluencer/mcp 0.1.0 → 0.3.0

package/src/index.ts

@@ -35,9 +35,11 @@ import {
 	normalizeStatus,
 	resolveSavePath,
 } from "./core.js";
+import { runLogin } from "./login.js";
 import {
 	IMAGE_EXTS,
 	uploadImageFile,
+	uploadShortPoster,
 	uploadVideoFile,
 	VIDEO_EXTS,
 } from "./uploads.js";
@@ -322,7 +324,7 @@ const WRITE = {
 	openWorldHint: true,
 };
 
-const server = new McpServer({ name: "hubfluencer", version: "0.1.0" });
+const server = new McpServer({ name: "hubfluencer", version: "0.3.0" });
 
 // The SDK's `registerTool` is generic over the Zod input shape; with this many
 // tools its conditional types hit TS2589 ("excessively deep"). Inputs are still
@@ -423,7 +425,12 @@ registerTool(
 			"WITHOUT charging (returns {estimated_credits, available_credits, slug}); pass max_credits to cap the " +
 			"spend. kind defaults to 'auto' — a multi-scene editor ad for ad/promo/story briefs, a single-clip short " +
 			"for simple/short ones; the chosen kind is reported back as kind_inferred. If it returns terminal=false " +
-			"the render is still running — call wait_for_completion with the returned slug to finish.",
+			"the render is still running — call wait_for_completion with the returned slug to finish. " +
+			"BE PROACTIVE WITH BRANDING: pass headline (the on-screen TITLE) and subheadline (secondary title) plus " +
+			"music_vibe/theme so a one-shot short isn't bare — these apply to SHORTS (music_vibe/headline/subheadline " +
+			"are ignored for editor; theme applies to both). For richer branding — a product image, brand logo, or " +
+			"closing card — drive the granular path instead: create_short + set_short_product/set_short_poster, or " +
+			"create_editor_draft + set_product/set_logo/set_closing_image, then start_autopilot/generate_short.",
 		// Schema kept intentionally flat (no .min/.max/.int chains) — the SDK's
 		// generic inference on registerTool hits TS2589 ("excessively deep") on
 		// larger schemas with chained validators. Ranges are enforced in code.
@@ -451,6 +458,30 @@ registerTool(
 				.describe(
 					"Preferred narration voice id for editor ads (see list_voices); shorts have no voiceover",
 				),
+			headline: z
+				.string()
+				.optional()
+				.describe(
+					"SHORTS only: the on-screen TITLE overlay (≤160). Set this so the short isn't bare.",
+				),
+			subheadline: z
+				.string()
+				.optional()
+				.describe("SHORTS only: the secondary title / supporting line (≤200)"),
+			music_vibe: z
+				.string()
+				.optional()
+				.describe(
+					"SHORTS only: music mood — Upbeat (default), Cinematic, Minimal, Luxury, Playful, Jazz",
+				),
+			theme: z
+				.string()
+				.optional()
+				.describe(
+					"Visual theme (both kinds): none (literal — no imposed style), realistic (default), cinematic, " +
+						"anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, " +
+						"minimalist, cyberpunk",
+				),
 			save_path: z
 				.string()
 				.optional()
@@ -485,6 +516,10 @@ registerTool(
 				language?: string;
 				aspect?: string;
 				voice_id?: string;
+				headline?: string;
+				subheadline?: string;
+				music_vibe?: string;
+				theme?: string;
 				save_path?: string;
 				max_wait_seconds?: number;
 				dry_run?: boolean;
@@ -514,13 +549,31 @@ registerTool(
 			//    make_video (or a dry_run then a real run) reuses this same draft.
 			let slug: string;
 			if (kind === "short") {
+				// Carry the creative fields inline so a one-shot short can be titled
+				// and branded (headline/subheadline/music_vibe are short-only; theme
+				// applies to both kinds).
 				const created = await client.post<{ data: { slug: string } }>(
 					"/shorts",
-					{ product_prompt: args.prompt, language: args.language },
+					{
+						product_prompt: args.prompt,
+						language: args.language,
+						headline: args.headline,
+						subheadline: args.subheadline,
+						music_vibe: args.music_vibe,
+						theme: args.theme,
+					},
 					// Fold every create-affecting param into the key: two calls that
-					// differ only in language must NOT dedup to the same draft, and a
-					// transport retry of an identical call must reuse it.
-					idemKey("make-short", args.prompt, args.language ?? ""),
+					// differ only in a creative field must NOT dedup to the same draft,
+					// and a transport retry of an identical call must reuse it.
+					idemKey(
+						"make-short",
+						args.prompt,
+						args.language ?? "",
+						args.headline ?? "",
+						args.subheadline ?? "",
+						args.music_vibe ?? "",
+						args.theme ?? "",
+					),
 				);
 				slug = created.data.slug;
 			} else {
@@ -531,6 +584,7 @@ registerTool(
 						product_prompt: args.prompt,
 						export_aspect_ratio: args.aspect,
 						voice_id: args.voice_id,
+						theme: args.theme,
 					},
 					idemKey(
 						"make-editor",
@@ -538,6 +592,7 @@ registerTool(
 						args.language ?? "en",
 						args.aspect ?? "",
 						args.voice_id ?? "",
+						args.theme ?? "",
 					),
 				);
 				slug = created.data.slug;
@@ -676,7 +731,23 @@ registerTool(
 		inputSchema: {},
 		annotations: { title: "Get credits", ...RO },
 	},
-	tool(async (_args, client) => ok(await client.get("/studio/credits"))),
+	tool(async (_args, client) => {
+		const res = await client.get<{ data: unknown }>("/studio/credits");
+		const d = asRecord(asRecord(res).data);
+		// Whitelist generation-relevant fields only. Deliberately DROP
+		// `first_editor_video_pack_available`: it's a purchase-funnel flag for the
+		// PAID one-time starter pack (33 credits — not free), and this server has
+		// no billing scope, so it can't act on it. Passing it through only invited
+		// the agent to misread `true` as "your first video may be free", which
+		// contradicts the product (the first video is never free).
+		return ok({
+			credits: d.credits,
+			spendable_credits: d.spendable_credits,
+			reserved_credits: d.reserved_credits,
+			remaining_reserved_credits: d.remaining_reserved_credits,
+			message: d.message,
+		});
+	}),
 );
 
 // ── Voices ────────────────────────────────────────────────────────────────
@@ -769,8 +840,13 @@ registerTool(
 	{
 		title: "Create a short (draft)",
 		description:
-			"Creates a short draft from a product prompt (min 10 chars). Returns the slug. Costs 0 credits. " +
-			"Follow with generate_short to render. Prefer make_video for the one-shot path.",
+			"Creates a short draft from a product prompt (min 10 chars). A short is a 12s vertical (two 6s AI " +
+			"segments + an on-screen title overlay + music; 14s when an end-card poster is set). Returns the slug, " +
+			"costs 0 credits. Follow with generate_short to render. " +
+			"BE PROACTIVE: don't ship a bare clip — set a headline (the on-screen TITLE) and subheadline (secondary " +
+			"title), and pick a music_vibe and theme that fit the brand. To brand it further, attach a product image " +
+			"(set_short_product) or an end-card poster (set_short_poster) before generate_short. (Shorts have no logo " +
+			"overlay — that's an editor-only feature; use create_editor_ad for logo branding.)",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -780,21 +856,109 @@ registerTool(
 				.string()
 				.optional()
 				.describe('Language code, e.g. "en" (default)'),
-			theme: z.string().optional(),
-			headline: z.string().optional(),
-			subheadline: z.string().optional(),
-			music_vibe: z.string().optional(),
+			headline: z
+				.string()
+				.max(160)
+				.optional()
+				.describe(
+					"The on-screen TITLE composited over the short (poster text overlay). ≤160 chars. Set this.",
+				),
+			subheadline: z
+				.string()
+				.max(200)
+				.optional()
+				.describe(
+					"The SECONDARY title / supporting line under the headline. ≤200 chars.",
+				),
+			theme: z
+				.string()
+				.optional()
+				.describe(
+					"Visual theme (default realistic). One of: none (no imposed style — follows the prompt literally), " +
+						"realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, " +
+						"gaming, retro_80s, minimalist, cyberpunk.",
+				),
+			music_vibe: z
+				.string()
+				.optional()
+				.describe(
+					"Background-music mood. Recognized: Upbeat (default), Cinematic, Minimal, Luxury, Playful, Jazz.",
+				),
+			music_instruments: z
+				.array(z.string())
+				.optional()
+				.describe('Optional instrument hints, e.g. ["piano", "strings"]'),
+			text_position: z
+				.enum(["top", "center", "bottom"])
+				.optional()
+				.describe("Where the title overlay sits (default bottom)"),
+			text_animation: z
+				.enum(["reveal", "typewriter", "fade_in", "pop", "bounce"])
+				.optional()
+				.describe("Title overlay animation (default fade_in)"),
+			font_family: z
+				.string()
+				.optional()
+				.describe(
+					"Overlay font (default ShortFontSpaceGrotesk). One of: ShortFontSpaceGrotesk, ShortFontMontserrat, " +
+						"ShortFontTheBold, ShortFontImpact, ShortFontLato, ShortFontProximaNova, ShortFontAnton, " +
+						"ShortFontBebasNeue, ShortFontOswald, ShortFontArchivoBlack, ShortFontPoppins, ShortFontInter, " +
+						"ShortFontTikTokSans, ShortFontBangers.",
+				),
 		},
 		annotations: { title: "Create short", ...WRITE, idempotentHint: true },
 	},
-	tool(async (args: Record<string, unknown>, client) => {
-		const res = await client.post<{ data: { slug: string } }>(
-			"/shorts",
-			args,
-			idemKey("create-short", String(args.product_prompt ?? "")),
-		);
-		return ok({ slug: res.data.slug, kind: "short", next: "generate_short" });
-	}),
+	tool(
+		async (
+			args: {
+				product_prompt: string;
+				language?: string;
+				headline?: string;
+				subheadline?: string;
+				theme?: string;
+				music_vibe?: string;
+				music_instruments?: string[];
+				text_position?: string;
+				text_animation?: string;
+				font_family?: string;
+			},
+			client,
+		) => {
+			// Map the agent-friendly field names onto the API's short_* params.
+			const body: Record<string, unknown> = {
+				product_prompt: args.product_prompt,
+			};
+			if (args.language !== undefined) body.language = args.language;
+			if (args.headline !== undefined) body.headline = args.headline;
+			if (args.subheadline !== undefined) body.subheadline = args.subheadline;
+			if (args.theme !== undefined) body.theme = args.theme;
+			if (args.music_vibe !== undefined) body.music_vibe = args.music_vibe;
+			if (args.music_instruments !== undefined)
+				body.music_instruments = args.music_instruments;
+			if (args.text_position !== undefined)
+				body.short_text_position = args.text_position;
+			if (args.text_animation !== undefined)
+				body.short_text_animation = args.text_animation;
+			if (args.font_family !== undefined)
+				body.short_font_family = args.font_family;
+			const res = await client.post<{ data: { slug: string } }>(
+				"/shorts",
+				body,
+				idemKey(
+					"create-short",
+					args.product_prompt,
+					args.language ?? "",
+					args.headline ?? "",
+					args.subheadline ?? "",
+				),
+			);
+			return ok({
+				slug: res.data.slug,
+				kind: "short",
+				next: "set_short_product / set_short_poster (optional branding), then generate_short",
+			});
+		},
+	),
 );
 
 registerTool(
@@ -828,7 +992,11 @@ registerTool(
 			"Creates an editor project from a product prompt and starts autopilot (server-orchestrated " +
 			"scenario → segments → narration → voice → music → render). Each AI-generated scene is a fixed 8 seconds. " +
 			"Returns the slug. Costs credits. Then poll with get_status / wait_for_completion (kind=editor). Prefer " +
-			"make_video for the one-shot path.",
+			"make_video for the one-shot path. " +
+			"BRANDING: to attach the user's own product image, brand logo, or closing card, create the draft with " +
+			"create_editor_draft first, call set_product / set_logo / set_closing_image (all 0 credits), then " +
+			"start_autopilot — autopilot weaves them in. (Editor ads carry their copy in-scene/narration, not as a " +
+			"title overlay; for an on-screen title/subtitle use a short with headline/subheadline instead.)",
 		inputSchema: {
 			product_prompt: z
 				.string()
@@ -841,7 +1009,9 @@ registerTool(
 			theme: z
 				.string()
 				.optional()
-				.describe('Visual theme (default "realistic")'),
+				.describe(
+					'Visual theme (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
+				),
 			voice_id: z
 				.string()
 				.optional()
@@ -986,7 +1156,9 @@ registerTool(
 			theme: z
 				.string()
 				.optional()
-				.describe('Visual theme (default "realistic")'),
+				.describe(
+					'Visual theme (default "realistic"). One of: none (no imposed style — segments follow your prompts literally), realistic, cinematic, anime, sci_fi, fantasy, noir, superhero, horror, mockumentary, sports, gaming, retro_80s, minimalist, cyberpunk.',
+				),
 			voice_id: z
 				.string()
 				.regex(/^[A-Za-z0-9_-]+$/)
@@ -2158,6 +2330,89 @@ registerTool(
 	),
 );
 
+// ── Shorts: branding images (product + end-card poster) ──────────────────────
+//
+// The editor branding tools above hit /editor/...; these hit /shorts/... A short
+// has no logo overlay (editor-only), but it CAN feature a product image woven
+// into the footage and a closing end-card poster. Both are 0 credits.
+
+registerTool(
+	"set_short_product",
+	{
+		title: "Attach a product image to a short (0 credits)",
+		description:
+			"Uploads a local product image and attaches it to a SHORT so the product is woven into the footage. " +
+			"Accepted: " +
+			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
+			" (≤20 MB), local path confined to HUBFLUENCER_INPUT_DIR (or cwd). 0 credits. Optional description " +
+			"(≤500 chars) guides how it's featured. Attach BEFORE generate_short so the product is part of the scenes. " +
+			"(This is the shorts equivalent of set_product for editor projects.)",
+		inputSchema: {
+			slug: z.string().describe("Short slug (from create_short)"),
+			file_path: z
+				.string()
+				.describe("Local product image path (.jpg/.jpeg/.png)"),
+			description: z
+				.string()
+				.max(500)
+				.optional()
+				.describe("Product description (≤500 chars)"),
+		},
+		annotations: {
+			title: "Set short product",
+			...WRITE,
+			idempotentHint: false,
+		},
+	},
+	tool(
+		async (
+			args: { slug: string; file_path: string; description?: string },
+			client,
+		) => {
+			const { s3_key } = await uploadImageFile(
+				client,
+				`/shorts/${args.slug}/product/presign`,
+				args.file_path,
+			);
+			const res = await client.post<{ data: unknown }>(
+				`/shorts/${args.slug}/product/confirm`,
+				{ s3_key, product_description: args.description },
+			);
+			return ok(asRecord(res).data ?? res);
+		},
+	),
+);
+
+registerTool(
+	"set_short_poster",
+	{
+		title: "Set a short's end-card poster image (0 credits)",
+		description:
+			"Uploads a local image as the SHORT's end-card poster — a closing still shown at the end (extends the " +
+			"render from 12s to 14s). Accepted: " +
+			IMAGE_EXTS.map((e) => `.${e}`).join(", ") +
+			" (≤20 MB), confined to HUBFLUENCER_INPUT_DIR/cwd. 0 credits. There is one poster per short; calling " +
+			"again replaces it. (Shorts have no logo overlay — for a brand logo use an editor project + set_logo.)",
+		inputSchema: {
+			slug: z.string().describe("Short slug (from create_short)"),
+			file_path: z.string().describe("Local poster image (.jpg/.jpeg/.png)"),
+		},
+		annotations: { title: "Set short poster", ...WRITE, idempotentHint: false },
+	},
+	tool(async (args: { slug: string; file_path: string }, client) => {
+		const { s3_key } = await uploadShortPoster(
+			client,
+			args.slug,
+			args.file_path,
+		);
+		const res = await client.post<{ data: unknown }>(
+			`/shorts/${args.slug}/poster/confirm`,
+			{ s3_key },
+		);
+		return ok(asRecord(res).data ?? res);
+	}),
+);
+
 // ── Status / waiting ──────────────────────────────────────────────────────────
 
 registerTool(
@@ -2298,6 +2553,13 @@ registerTool(
 // ── Boot ──────────────────────────────────────────────────────────────────────
 
 async function main() {
+	// `hubfluencer-mcp login [name]` runs the device-link login instead of the
+	// server. Single bin keeps the install idiomatic: `npx -y @hubfluencer/mcp`
+	// starts the server; `npx -y @hubfluencer/mcp login` connects an account.
+	if (process.argv[2] === "login") {
+		await runLogin(process.argv[3]);
+		return;
+	}
 	const transport = new StdioServerTransport();
 	await server.connect(transport);
 	// stderr is safe; stdout is reserved for the MCP protocol.

package/src/login.ts

@@ -1,6 +1,9 @@
-#!/usr/bin/env node
 /**
- * `hubfluencer-login` — device-link CLI.
+ * Device-link login for the Hubfluencer MCP.
+ *
+ * Exposed as the `login` subcommand of the single `hubfluencer-mcp` bin:
+ *
+ *     npx -y @hubfluencer/mcp login ["Client Name"]
  *
  * Connects this agent to a Hubfluencer account without copy-pasting a token:
  * starts a link request, prints a URL + code for the user to approve in the
@@ -14,17 +17,21 @@ import { dirname } from "node:path";
 import { assertSafeBaseUrl } from "./client.js";
 import { CREDENTIALS_PATH } from "./credentials.js";
 
-const BASE = (process.env.HUBFLUENCER_BASE_URL || "https://hubfluencer.com")
-	.replace(/\/+$/, "")
-	.replace(/\/api$/, "");
-// Fail before printing a code / polling if the base would leak the token.
-assertSafeBaseUrl(BASE);
 const MAX_POLLS = 120;
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
-async function main() {
-	const clientName = process.argv[2] || "Claude Code";
+/**
+ * Runs the device-link login flow. Resolves once the token is stored; calls
+ * `process.exit(1)` on a terminal failure (it's a CLI entry path). Invoked from
+ * index.ts when the bin is run as `hubfluencer-mcp login [name]`.
+ */
+export async function runLogin(clientName = "Claude Code"): Promise<void> {
+	const BASE = (process.env.HUBFLUENCER_BASE_URL || "https://hubfluencer.com")
+		.replace(/\/+$/, "")
+		.replace(/\/api$/, "");
+	// Fail before printing a code / polling if the base would leak the token.
+	assertSafeBaseUrl(BASE);
 
 	const startRes = await fetch(`${BASE}/api/agent-link/start`, {
 		method: "POST",
@@ -77,7 +84,7 @@ async function main() {
 		};
 
 		if (pollRes.ok && body.status === "approved" && body.token) {
-			await storeToken(body.token);
+			await storeToken(body.token, BASE);
 			console.error(
 				`\n✓ Connected. Access token saved to ${CREDENTIALS_PATH}.`,
 			);
@@ -101,12 +108,12 @@ async function main() {
 	process.exit(1);
 }
 
-async function storeToken(token: string) {
+async function storeToken(token: string, base: string) {
 	const dir = dirname(CREDENTIALS_PATH);
 	await mkdir(dir, { recursive: true, mode: 0o700 });
 	await writeFile(
 		CREDENTIALS_PATH,
-		JSON.stringify({ token, base_url: BASE }, null, 2),
+		JSON.stringify({ token, base_url: base }, null, 2),
 		{
 			mode: 0o600,
 		},
@@ -122,8 +129,3 @@ async function storeToken(token: string) {
 		// chmod is hardening — never fail the login over it
 	}
 }
-
-main().catch((e) => {
-	console.error("Fatal:", e instanceof Error ? e.message : String(e));
-	process.exit(1);
-});

package/src/uploads.ts

@@ -365,5 +365,30 @@ export async function uploadImageFile(
 	return { s3_key };
 }
 
+/**
+ * Uploads a local image as a short's end-card POSTER. The short poster presign
+ * is older than the editor asset presign and uses a different envelope: it takes
+ * `{ content_type }` and returns a bare `{ upload_url, s3_key }` (no `data`
+ * wrapper, `upload_url` not `presigned_url`, and a single fixed key per short).
+ * Kept separate from `uploadImageFile` (which speaks the editor `{data:{...}}`
+ * shape) so neither has to branch on the surface. Returns the `s3_key` to thread
+ * into `/shorts/:slug/poster/confirm`.
+ */
+export async function uploadShortPoster(
+	client: HubfluencerClient,
+	slug: string,
+	filePath: string,
+): Promise<{ s3_key: string }> {
+	const file = await resolveReadPath(filePath, IMAGE_EXT_MIME, MAX_IMAGE_BYTES);
+	const presign = await client.post<{ upload_url: string; s3_key: string }>(
+		`/shorts/${slug}/poster/presign`,
+		{ content_type: file.mime },
+	);
+	const { upload_url, s3_key } = presign;
+	const buf = await readFile(file.path);
+	await putToPresignedUrl(upload_url, buf, file.mime);
+	return { s3_key };
+}
+
 export const LOGO_MAX_BYTES = MAX_LOGO_BYTES;
 export const IMAGE_MAX_BYTES = MAX_IMAGE_BYTES;