@hubfluencer/mcp 0.15.0 → 0.17.0

package/src/output-schemas.ts

@@ -41,6 +41,15 @@
  */
 
 import { z } from "zod";
+import { generationSummarySchema } from "./generation-summary.js";
+
+/**
+ * Fallback contract for tools whose server-owned payload is intentionally
+ * open-ended. Advertising an object schema is still materially better than
+ * omitting outputSchema: clients can request structured output consistently,
+ * while the stable/high-value tools below keep their precise schemas.
+ */
+export const genericToolOutput = z.object({}).passthrough();
 
 /** A presigned URL or a local-null field that may be absent/variable. */
 const urlish = z.unknown().optional();
@@ -62,9 +71,16 @@ export const getStatusOutput = z
 		ready: z.boolean().optional(),
 		video_url: z.union([z.string(), z.null()]).optional(),
 		error: z.union([z.string(), z.null()]).optional(),
+		generation_summary: generationSummarySchema.optional(),
+		run_id: z.union([z.string(), z.null()]).optional(),
+		workflow: z.union([z.string(), z.null()]).optional(),
+		revision: z.union([z.number(), z.null()]).optional(),
+		poll_after_ms: z.union([z.number(), z.null()]).optional(),
+		available_actions: z.array(z.string()).optional(),
 		stale: z.boolean().optional(),
 		active_segment_ids: z.array(z.union([z.number(), z.string()])).optional(),
 		stale_segment_ids: z.array(z.union([z.number(), z.string()])).optional(),
+		autopilot_contract_satisfied: z.boolean().optional(),
 		// Short only, additive (normalizeStatus forwards each gated on its typeof,
 		// so the precise type can never reject a payload).
 		failed_stage: z
@@ -91,10 +107,6 @@ export const getStatusOutput = z
 			.number()
 			.optional()
 			.describe("Short only: paid generation attempt number that failed."),
-		generation_attempt: z
-			.number()
-			.optional()
-			.describe("Short only: current paid attempt; echo when cancelling."),
 		segments_completed: z.number().optional(),
 		segments_total: z.number().optional(),
 		active_segment_positions: z.array(z.number()).optional(),
@@ -103,6 +115,24 @@ export const getStatusOutput = z
 	})
 	.passthrough();
 
+/**
+ * get_editor -> full or concise Editor state.
+ *
+ * The payload is intentionally otherwise permissive because the full Editor
+ * graph is additive and much larger than the MCP review projection. The
+ * lifecycle authority is the one field that is never optional: advertising it
+ * here makes strict MCP clients see the same requirement that the handler
+ * enforces at runtime.
+ */
+export const getEditorOutput = z
+	.object({
+		generation_summary: generationSummarySchema,
+		slug: z.string().optional(),
+		segments: z.array(z.unknown()).optional(),
+		latest_render: z.unknown().optional(),
+	})
+	.passthrough();
+
 /** wait_for_completion → get_status plus the download/timeout bookkeeping. */
 export const waitForCompletionOutput = z
 	.object({
@@ -113,9 +143,16 @@ export const waitForCompletionOutput = z
 		ready: z.boolean().optional(),
 		video_url: z.union([z.string(), z.null()]).optional(),
 		error: z.union([z.string(), z.null()]).optional(),
+		generation_summary: generationSummarySchema.optional(),
+		run_id: z.union([z.string(), z.null()]).optional(),
+		workflow: z.union([z.string(), z.null()]).optional(),
+		revision: z.union([z.number(), z.null()]).optional(),
+		poll_after_ms: z.union([z.number(), z.null()]).optional(),
+		available_actions: z.array(z.string()).optional(),
 		stale: z.boolean().optional(),
 		active_segment_ids: z.array(z.union([z.number(), z.string()])).optional(),
 		stale_segment_ids: z.array(z.union([z.number(), z.string()])).optional(),
+		autopilot_contract_satisfied: z.boolean().optional(),
 		// Short only, additive — mirrors getStatusOutput (see there).
 		failed_stage: z
 			.string()
@@ -141,10 +178,6 @@ export const waitForCompletionOutput = z
 			.number()
 			.optional()
 			.describe("Short only: paid generation attempt number that failed."),
-		generation_attempt: z
-			.number()
-			.optional()
-			.describe("Short only: current paid attempt; echo when cancelling."),
 		segments_completed: z.number().optional(),
 		segments_total: z.number().optional(),
 		active_segment_positions: z.array(z.number()).optional(),
@@ -152,6 +185,7 @@ export const waitForCompletionOutput = z
 		last_free_rerender_failed: z.boolean().optional(),
 		saved_to: z.union([z.string(), z.null()]).optional(),
 		timed_out: z.boolean().optional(),
+		polling_stopped: z.boolean().optional(),
 	})
 	.passthrough();
 
@@ -212,26 +246,63 @@ export const getSliderOutput = z
 
 // ── Projects listing ────────────────────────────────────────────────────────────
 
-/** A normalized status row inside list_projects (permissive — server-derived). */
+/** A permissive normalized status row reused by nested create-tool results. */
 const projectRow = z
 	.object({
 		kind: z.string().optional(),
 		slug: z.string().optional(),
 		stage: z.string().optional(),
+		kind_detail: z.union([z.string(), z.null()]).optional(),
 		terminal: z.boolean().optional(),
 		ready: z.boolean().optional(),
 		video_url: z.union([z.string(), z.null()]).optional(),
 		error: z.union([z.string(), z.null()]).optional(),
+		generation_summary: generationSummarySchema.optional(),
+		run_id: z.union([z.string(), z.null()]).optional(),
+		workflow: z.union([z.string(), z.null()]).optional(),
+		revision: z.union([z.number(), z.null()]).optional(),
+		poll_after_ms: z.union([z.number(), z.null()]).optional(),
+		available_actions: z.array(z.string()).optional(),
+		segments_completed: z.number().optional(),
+		segments_total: z.number().optional(),
+		active_segment_positions: z.array(z.number()).optional(),
 		latest_render_free: z.boolean().optional(),
 		last_free_rerender_failed: z.boolean().optional(),
 	})
 	.passthrough();
 
-/** list_projects → the two normalized lanes plus an optional truncation note. */
+/** Summary-bearing Short row emitted by normalizeStatus in list_projects. */
+const listedShortProject = projectRow.extend({
+	kind: z.literal("short"),
+	slug: z.string(),
+	stage: z.string(),
+	terminal: z.boolean(),
+	ready: z.boolean(),
+	video_url: z.union([z.string(), z.null()]),
+	error: z.union([z.string(), z.null()]),
+	generation_summary: generationSummarySchema,
+	run_id: z.union([z.string(), z.null()]),
+	workflow: z.union([z.string(), z.null()]),
+	revision: z.union([z.number(), z.null()]),
+	poll_after_ms: z.union([z.number(), z.null()]),
+	available_actions: z.array(z.string()),
+});
+
+/** Summary-free mixed-kind discovery row emitted by normalizeFactoryIndexProject. */
+const listedGenericProject = z
+	.object({
+		slug: z.string(),
+		kind_detail: z.union([z.string(), z.null()]),
+		stage: z.string(),
+		video_url: z.union([z.string(), z.null()]),
+	})
+	.passthrough();
+
+/** list_projects → two always-present lanes plus an optional truncation note. */
 export const listProjectsOutput = z
 	.object({
-		shorts: z.array(projectRow).optional(),
-		projects: z.array(projectRow).optional(),
+		shorts: z.array(listedShortProject),
+		projects: z.array(listedGenericProject),
 		note: z.string().optional(),
 	})
 	.passthrough();
@@ -292,6 +363,8 @@ export const makeVideoOutput = z
 		charged: z.boolean().optional(),
 		saved_to: z.union([z.string(), z.null()]).optional(),
 		timed_out: z.boolean().optional(),
+		replayed: z.boolean().optional(),
+		polling_stopped: z.boolean().optional(),
 		note: z.string().optional(),
 	})
 	.passthrough();

package/src/polling.ts

@@ -0,0 +1,64 @@
+export interface PollOptions<T> {
+	read: (deadline: number) => Promise<T>;
+	isTerminal: (value: T) => boolean;
+	/** False means the server has explicitly told this client to stop polling. */
+	shouldContinue?: (value: T) => boolean;
+	budgetMs: number;
+	intervalMs: number | ((value: T) => number);
+	onPoll?: (value: T, pollNumber: number) => Promise<void>;
+	now?: () => number;
+	sleep?: (milliseconds: number) => Promise<void>;
+}
+
+/**
+ * Poll within a fixed budget, then perform one separately bounded
+ * reconciliation read. The final read closes the common race where work
+ * finishes during the last partial interval and the caller otherwise returns
+ * the stale pre-completion snapshot.
+ */
+export async function pollWithFinalReconciliation<T>({
+	read,
+	isTerminal,
+	shouldContinue = () => true,
+	budgetMs,
+	intervalMs,
+	onPoll,
+	now = Date.now,
+	sleep = (milliseconds) =>
+		new Promise<void>((resolve) => setTimeout(resolve, milliseconds)),
+}: PollOptions<T>): Promise<T> {
+	const deadline = now() + budgetMs;
+	let value = await read(deadline);
+	let pollNumber = 0;
+	let lastIntervalMs = resolveInterval(intervalMs, value);
+
+	while (!isTerminal(value) && shouldContinue(value)) {
+		const remainingMs = deadline - now();
+		if (remainingMs <= 0) break;
+		await onPoll?.(value, ++pollNumber);
+		lastIntervalMs = resolveInterval(intervalMs, value);
+		await sleep(Math.min(lastIntervalMs, remainingMs));
+		if (now() >= deadline) break;
+		value = await read(deadline);
+	}
+
+	if (!isTerminal(value) && shouldContinue(value)) {
+		const finalReadDeadline =
+			now() + Math.min(5_000, Math.max(1_000, lastIntervalMs));
+		try {
+			value = await read(finalReadDeadline);
+		} catch {
+			// The normal timeout/resume contract uses the last successful state.
+		}
+	}
+
+	return value;
+}
+
+function resolveInterval<T>(
+	interval: PollOptions<T>["intervalMs"],
+	value: T,
+): number {
+	const resolved = typeof interval === "function" ? interval(value) : interval;
+	return Number.isFinite(resolved) && resolved > 0 ? resolved : 1_000;
+}

package/src/skill-installer.ts

@@ -0,0 +1,100 @@
+import { access, cp, mkdir, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { VERSION } from "./version.js";
+
+export const SKILL_CLIENTS = [
+	"codex",
+	"claude-code",
+	"opencode",
+	"pi",
+] as const;
+export type SkillClient = (typeof SKILL_CLIENTS)[number];
+
+const sourceDirectory = fileURLToPath(
+	new URL("../skill/hubfluencer-create", import.meta.url),
+);
+
+function parseClient(value: string | undefined): SkillClient {
+	if (SKILL_CLIENTS.includes(value as SkillClient)) return value as SkillClient;
+	throw new Error(
+		`install-skill requires one client: ${SKILL_CLIENTS.join(", ")}.`,
+	);
+}
+
+export function skillTarget(
+	client: SkillClient,
+	project: boolean,
+	cwd = process.cwd(),
+	home = homedir(),
+): string {
+	const root = project ? cwd : home;
+	switch (client) {
+		case "codex":
+			return join(root, ".agents", "skills", "hubfluencer-create");
+		case "claude-code":
+			return join(root, ".claude", "skills", "hubfluencer-create");
+		case "opencode":
+			return project
+				? join(root, ".opencode", "skills", "hubfluencer-create")
+				: join(root, ".config", "opencode", "skills", "hubfluencer-create");
+		case "pi":
+			return project
+				? join(root, ".pi", "skills", "hubfluencer-create")
+				: join(root, ".pi", "agent", "skills", "hubfluencer-create");
+	}
+}
+
+export type InstallSkillOptions = {
+	client: SkillClient;
+	project: boolean;
+	force: boolean;
+	source?: string;
+	cwd?: string;
+	home?: string;
+};
+
+export async function installSkill(
+	options: InstallSkillOptions,
+): Promise<string> {
+	const source = options.source ?? sourceDirectory;
+	const target = skillTarget(
+		options.client,
+		options.project,
+		options.cwd,
+		options.home,
+	);
+	await access(source);
+	try {
+		await access(target);
+		if (!options.force) {
+			throw new Error(
+				`Skill already exists at ${target}. Re-run with --force to replace it.`,
+			);
+		}
+		await rm(target, { recursive: true, force: true });
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+	}
+	await mkdir(dirname(target), { recursive: true });
+	await cp(source, target, { recursive: true });
+	return target;
+}
+
+export async function runInstallSkill(args: string[]): Promise<void> {
+	const positional = args.filter((arg) => !arg.startsWith("--"));
+	const clientFlag = args.indexOf("--client");
+	const client = parseClient(
+		clientFlag >= 0 ? args[clientFlag + 1] : positional[1],
+	);
+	const target = await installSkill({
+		client,
+		project: args.includes("--project"),
+		force: args.includes("--force"),
+	});
+	console.log(`Installed hubfluencer-create for ${client}: ${target}`);
+	console.log(
+		`Restart the agent so it discovers the skill, then run \`npx -y @hubfluencer/mcp@${VERSION} doctor --profile creator\`.`,
+	);
+}

package/src/tool-profile.ts

@@ -0,0 +1,93 @@
+/**
+ * Tool discovery profiles.
+ *
+ * `full` remains the default so existing MCP configurations keep the exact
+ * surface they already use. `creator` is an opt-in, low-context surface for
+ * agents that primarily need to create, iterate, recover, and download assets.
+ * The server still owns the same implementation; this only changes tools/list.
+ */
+
+export const TOOL_PROFILES = ["full", "creator"] as const;
+export type ToolProfile = (typeof TOOL_PROFILES)[number];
+
+export const CREATOR_TOOL_NAMES = [
+	"make_video",
+	"get_credits",
+	"list_voices",
+	"list_projects",
+	"create_short",
+	"update_short",
+	"generate_short",
+	"cancel_short_generation",
+	"rerender_short",
+	"set_short_product",
+	"set_short_logo",
+	"set_short_poster",
+	"create_slider",
+	"generate_slider",
+	"get_slider",
+	"restyle_slider",
+	"edit_slider_slide",
+	"create_tracking_video",
+	"create_editor_ad",
+	"start_autopilot",
+	"provide_generation_input",
+	"get_editor",
+	"retry_segment_generation",
+	"cancel_segment_generation",
+	"retry_render",
+	"retry_editor_batch",
+	"cancel_editor_batch",
+	"cancel_autopilot",
+	"get_status",
+	"wait_for_completion",
+	"download_result",
+] as const;
+
+const creatorTools = new Set<string>(CREATOR_TOOL_NAMES);
+
+export function parseProfile(value: string | undefined): ToolProfile {
+	const normalized = value?.trim().toLowerCase();
+	if (!normalized || normalized === "full") return "full";
+	if (normalized === "creator") return "creator";
+	throw new Error(
+		`Unknown Hubfluencer MCP profile "${value}". Use "creator" or "full".`,
+	);
+}
+
+export function profileFromArgs(
+	args: string[],
+	envValue = process.env.HUBFLUENCER_MCP_PROFILE,
+): ToolProfile {
+	const equalsArg = args.find((arg) => arg.startsWith("--profile="));
+	if (equalsArg) return parseProfile(equalsArg.slice("--profile=".length));
+
+	const index = args.indexOf("--profile");
+	if (index >= 0) {
+		const value = args[index + 1];
+		if (!value || value.startsWith("-")) {
+			throw new Error("--profile requires creator or full.");
+		}
+		return parseProfile(value);
+	}
+
+	return parseProfile(envValue);
+}
+
+export function withoutProfileArgs(args: string[]): string[] {
+	const result: string[] = [];
+	for (let index = 0; index < args.length; index += 1) {
+		const arg = args[index];
+		if (arg.startsWith("--profile=")) continue;
+		if (arg === "--profile") {
+			index += 1;
+			continue;
+		}
+		result.push(arg);
+	}
+	return result;
+}
+
+export function toolEnabled(profile: ToolProfile, name: string): boolean {
+	return profile === "full" || creatorTools.has(name);
+}