@hubfluencer/mcp 0.5.0 → 0.7.0

package/README.md

@@ -1,11 +1,15 @@
 # @hubfluencer/mcp
 
 A [Model Context Protocol](https://modelcontextprotocol.io) server that lets an AI agent
-(e.g. Claude Code) drive Hubfluencer end-to-end: turn a text prompt into a finished,
-post-ready short or multi-scene editor ad.
+(e.g. Claude Code) drive Hubfluencer end-to-end — from a single text prompt to a finished,
+post-ready short or multi-scene editor ad, and up through the whole content operation:
+ingest a product page, plan a campaign, draft a month of ads, mint review links, stage a
+reminder calendar, and learn from performance.
 
-The server is a thin wrapper over the public Hubfluencer REST API. It holds **no state** —
-auth is an opaque bearer token passed through from an env var.
+The server is a thin wrapper over the public Hubfluencer REST API. Auth is an opaque bearer
+token — passed through from an env var, or read from a local credentials file written by the
+device-link `login` command (see [Setup](#setup)). It keeps **no in-memory session state**;
+the only thing it persists is that credentials file.
 
 ## Setup
 
@@ -25,7 +29,7 @@ Hubfluencer app, and a scoped access token is saved locally to `~/.hubfluencer/c
 
 ```bash
 npx -y @hubfluencer/mcp login "Claude Code"
-#  1. Open:        https://hubfluencer.com/connect?code=ABCD-EFGH
+#  1. Open:        https://app.hubfluencer.com/connect?code=ABCD-EFGH
 #  2. Confirm code: ABCDEFGH
 #  3. Click Approve.  →  ✓ Connected.
 ```
@@ -51,49 +55,182 @@ it **cannot** delete your account, change credentials, publish, or create more t
 claude mcp add hubfluencer --env HUBFLUENCER_API_TOKEN=YOUR_TOKEN -- npx -y @hubfluencer/mcp
 ```
 
+### Environment variables
+
 | Env var | Required | Default | Purpose |
 |---|---|---|---|
-| `HUBFLUENCER_API_TOKEN` | no¹ | — | Access token (¹falls back to `~/.hubfluencer/credentials.json` from `login`) |
-| `HUBFLUENCER_BASE_URL` | no | `https://hubfluencer.com` | API base URL |
-| `HUBFLUENCER_OUTPUT_DIR` | no | current working dir | Allowlisted base dir for `save_path` downloads (writes are confined here) |
+| `HUBFLUENCER_API_TOKEN` | no¹ | — | Access token. ¹Falls back to the credentials file written by `login`. |
+| `HUBFLUENCER_BASE_URL` | no | `https://hubfluencer.com` | API base URL. The token is never sent over a non-https / private-IP origin. |
+| `HUBFLUENCER_WEB_URL` | no | `https://app.hubfluencer.com` | Web-app origin used to build the absolute no-login **review URL** (`/review/<token>`). This is the front web app, a **different** host from the API base — set it only if your web app is served elsewhere. |
+| `HUBFLUENCER_CREDENTIALS` | no | `~/.hubfluencer/credentials.json` | Path to the device-link credentials file (`login` writes it; the server reads it as the token fallback). |
+| `HUBFLUENCER_INPUT_DIR` | no | current working dir | **Read confinement.** Every local file the agent uploads (video clips, product / logo / closing / poster images, catalog assets) must resolve **inside** this directory — a path outside it is refused. This is a security control: it stops an agent from reading arbitrary local files (`~/.ssh/...`, `.env`, …). |
+| `HUBFLUENCER_OUTPUT_DIR` | no | current working dir | **Write confinement.** Downloads via `save_path` (`make_video` / `wait_for_completion` / `download_result` / `create_tracking_video`) must resolve inside this directory and end in `.mp4`; anything outside is refused. |
 
 ## Tools
 
-**One-shot & status**
+89 tools, grouped by workflow. Every tool prices its action in its own `description` — costs
+below are the ground truth. **"$0" means it spends no video credits**; planning/AI-helper tools
+instead draw a **free daily quota of 20 AI assists** (top up with `unlock_ai_assists`: 1 credit
+→ +10). Reads need the `video:read` scope; writes need `video:generate`. Nothing here needs
+`account:admin`.
+
+### Make one asset (start here)
+
+| Tool | What it does | Cost |
+|---|---|---|
+| **`make_video`** | **One shot: prompt → finished MP4** (create → **price** → start → poll → download). `kind:"auto"` picks a multi-scene editor ad for ad/promo/story briefs, a short for simple ones (reported as `kind_inferred`). Pass `dry_run:true` to preview the cost without spending, or `max_credits` to cap it. | short **15**, editor ~**28** (`dry_run`/`max_credits` gate it) |
+| `create_short` | Create a short draft (12s vertical: two 6s AI segments + title overlay + music; 14s with an end-card poster). Set `headline`/`subheadline`/`music_vibe`/`visual_language` so it isn't bare. Optional opt-in conversion graphics: `offer_text`/`cta_text`/`badge_text`/`star_rating` (off unless you set them). | **0** |
+| `update_short` | Patch an existing short draft — brief (`product_prompt`), copy, styling, or the opt-in conversion graphics; only the fields you pass change. Clear one with `""` (`[]` for `text_beats`, `0` for `star_rating`). Re-run `generate_short` to apply. | **0** |
+| `generate_short` | Render an existing short. Safe to re-call (in-flight = reported, no double charge; a failed short can re-generate). | **15** |
+| `generate_short_text` | AI-draft editable headline / subheadline / caption beats for a short. | 1 assist |
+| `create_editor_ad` | Create an editor project **and** run autopilot end-to-end. Style it with `creative_format` + `visual_language` + `theme`. | credits (est. first) |
+| `start_autopilot` | Run autopilot on an **existing** editor draft (resume a `make_video` `dry_run`, or after a top-up). | credits |
+| `create_slider` | Create an image-carousel draft: one prompt → N still slides + a ready-to-post caption + hashtags. `mode` `creative` (story) or `ad_driven` (facts). | **0** |
+| `generate_slider` | Render a carousel (copy → AI backgrounds → composite). Poll `get_slider` until `completed`. | **1 / slide** (3–10) |
+| `get_slider` | Read a carousel's status and, when completed, the per-slide image URLs + caption + hashtags. | **0** |
+| `restyle_slider` | Re-composite **all** slides of a completed carousel under a new template/accent/position — reuses the AI backgrounds. | **0** |
+| `edit_slider_slide` | Rewrite one slide's headline/body/kicker and re-composite just that slide. | **0** |
+| **`create_tracking_video`** | **One shot: upload a local clip → burn a CV object-tracking overlay → download.** Source ≤60s, ≤1080p. Optional `classes` (COCO-80 ids) / `color` ([r,g,b,a]). Times out on a slow upload / cold GPU → call again with `slug` to resume (no re-upload, no re-charge). A completed slug is final — for a variant, start a NEW project. | **1** on render (refunded on failure) |
+
+### Granular editor pipeline (write the scenario / scenes / audio yourself)
+
+| Tool | What it does | Cost |
+|---|---|---|
+| `create_editor_draft` | Editor project, **no** autopilot. Accepts `creative_format` / `visual_language` / `theme`. | **0** |
+| `get_editor` | Full project state (scenario, segments, narration, music, latest render, quota) — the review step. | **0** |
+| `set_scenario` / `generate_scenario` | Write your own scenario (free) **or** AI-draft it. `generate_scenario` can also persist `creative_format` / `visual_language` / `theme`. | free / 1 assist |
+| `set_scene_count` | Grow/shrink to N scenes (1–20); deletes only trailing un-generated scenes. Each AI scene is a fixed 8s. | **0** |
+| `set_segment_prompt` | Write one scene's prompt (1–2000 chars), identified by segment id. | **0** |
+| `generate_segment` | Render one scene (re-call to retry a failed one). | **5** |
+| `generate_all_segments` | Render every not-yet-completed scene in order (continuity preserved); capped ~280s → re-run to continue. | **5 / segment** |
+| `set_narration_script` / `generate_narration` | Write your own voiceover script (free) **or** AI-draft it. | free / 1 assist |
+| `generate_voice` | Synthesize the voiceover. `voice_id` required (see `list_voices`). | **3** |
+| `generate_music` | Generate background music (each call is a fresh take). | **5** |
+| `render` | Final MP4. Auto-charges any still-ungenerated scenes first (4/scene in a batch of ≥3). | **0** |
+| `list_renders` | List every render version for an editor project (id, version, status, video_url, error) — find a failed render or recover a finished URL. | **0** |
+| `retry_render` | Re-run a **failed** render from its exact saved snapshot (recovery without re-driving the pipeline). | **0** |
+| `enhance_prompt` / `suggest_next_scene` / `suggest_music_prompt` | AI helpers along the way. | 1 assist each |
+
+### Uploads & local media (bring your own footage / images)
+
+Reads are confined to `HUBFLUENCER_INPUT_DIR`. All $0.
+
+| Tool | What it does |
+|---|---|
+| `upload_video` | Upload a local clip into an editor project (presign → PUT, resumable multipart for large files → confirm → poll to ready) and, by default, add it to the timeline. An uploaded clip keeps its native duration. |
+| `add_segment_from_upload` | Append a **ready** upload to the timeline as a new scene. |
+| `use_asset_for_segment` | Set a specific scene's video from a ready upload **or** a completed scene in the same project (pass exactly one). |
+| `set_product` | Upload a local product image and attach it as the project product. |
+| `set_product_placement` | Set where the product appears on pending AI scenes: `throughout` or `end`. |
+| `set_closing_image` | Set the ~2s end-card image (upload a file, or reuse the product image with `from_product:true`). |
+| `set_logo` | Upload a brand logo overlay (editor only; optional treatment/position/duration). |
+| `set_short_product` | Attach a product image to a **short**. |
+| `set_short_poster` | Set a short's end-card poster (extends the render 12s → 14s). |
+
+### Status & delivery
+
+| Tool | What it does |
+|---|---|
+| `get_status` | Normalized `{stage, terminal, ready, video_url, error}` for a short / editor / tracking / slider. |
+| `wait_for_completion` | Block-poll until terminal (bounded ≤280s; returns `terminal:false` to re-call). `save_path` downloads the MP4 when ready. |
+| `download_result` | Get (or save, to `HUBFLUENCER_OUTPUT_DIR`) the finished MP4 URL. Not for sliders — use `get_slider`. |
+| `get_credits` / `list_voices` / `list_projects` | Credit balance; narration voices; recent projects (`include_completed:true` to recover a finished short's slug). |
+| `get_ai_assists` / `unlock_ai_assists` | The free daily assist quota / spend 1 credit for +10. |
+
+### Campaign engine — onboard a product, plan, and draft (the delegation surface)
+
+Everything here is **$0** (draft creates + planning against the free assist quota). Generation
+of each draft stays a separate, explicit, paid step (`start_autopilot` / `generate_short` /
+`generate_slider`).
 
 | Tool | What it does |
 |---|---|
-| **`make_video`** | **One shot: prompt → finished MP4** (create → **price** → start → poll → download). Use this by default. Prices the job and checks your balance before charging; pass `dry_run:true` to preview the cost without spending, or `max_credits` to cap it. `kind:"auto"` picks a multi-scene editor ad for ad/promo/story briefs, a short for simple ones (reported as `kind_inferred`). |
-| `create_short` / `generate_short` / `generate_short_text` | Create a short draft (0 credits) / generate editable overlay copy (1 AI assist) / render it (15 credits) |
-| `create_slider` / `generate_slider` / `get_slider` | Create an image carousel draft (0 credits) / render it (1 credit per slide, 3–10) / read the per-slide image URLs + caption + hashtags. One prompt → N still slides + ready-to-post text. |
-| `restyle_slider` / `edit_slider_slide` | Re-composite a **completed** carousel for **free** (0 credits): swap the template/accent on every slide, or rewrite one slide's headline/body/kicker. Reuses the AI backgrounds; poll `get_slider` until `completed`. |
-| `create_editor_ad` | Create an editor project **and** run autopilot end-to-end. Style it with `creative_format` (narrative arc) + `visual_language` (render look) + `theme` (genre overlay). |
-| `start_autopilot` | Run autopilot on an **existing** editor draft (e.g. resume a `make_video` `dry_run`, or after topping up) |
-| `get_status` / `wait_for_completion` | Normalized `{stage, terminal, ready, video_url, error}`; block-poll until terminal (bounded) |
-| `download_result` | Get (or save) the finished MP4 URL |
-| `get_credits` / `list_voices` / `list_projects` | Credit balance; narration voices; recent projects |
-
-**Granular editor pipeline** — write the scenario / scenes / audio yourself, full control
+| **`create_campaign`** | **One shot: a product URL (or `product_profile_id`) → a persisted pack full of editable DRAFTS.** Runs extract → save profile → import image/logo → plan → hook variations → create pack → materialize drafts. Never generates/renders. |
+| `extract_product_page` | Server-side, SSRF-guarded fetch of a product page → parsed facts (name, description, benefits, price, brand) + candidate image/logo URLs (URLs only; no download). Rate limit 30/min. |
+| `import_product_image` | Server-side, SSRF-guarded fetch of an image URL (JPEG/PNG, magic-byte verified) → stored as a catalog asset linked to a product profile (`link_as` `primary_image` default / `logo`). Rate limit 30/min. |
+| `list_product_profiles` / `create_product_profile` / `update_product_profile` | Reusable product fact sheets (benefits, offer, proof points, audience, CTA, banned claims, tone) that ground planning + generation. |
+| `list_brand_profiles` / `create_brand_profile` / `update_brand_profile` | Reusable brand identities (logo, colors, fonts, tone, default CTA, preferred visual_language/creative_format). `update_brand_profile` also attaches/detaches catalog assets. |
+| `plan_campaign` | Product facts → a campaign PLAN: hooks, recommended formats, positioning line, and a credit ESTIMATE. Persists nothing. Rate limit 30/min. |
+| `generate_hook_variations` | Product facts (+ optional brand) → 3–6 distinct hook variations, each with a script, caption, hashtags, suggested format, and a per-variation estimate. Rate limit 30/min. |
+| `create_campaign_pack` | Persist a pack (the planning container) + any inline hook/caption text items. Link a product/brand profile so drafts inherit them. |
+| `list_campaign_packs` | List your packs at the pack level (id, title, status, source, profiles). Per-item detail is NOT included — the list endpoint doesn't load items; use `get_campaign_pack` for that. |
+| `get_campaign_pack` | Read one pack **with** its items (per-item kind, status, materialized draft slug + route, credit estimate). |
+| `add_pack_variations` | Persist selected hook variations under a pack and (by default) materialize each into a draft. ≤12 per call; rate limit 15/min; per-variation best-effort. |
+| `materialize_pack_item` | Materialize one planned item into a draft. Safe to retry — no duplicate is ever created; a sequential re-call of an already-materialized item returns **422 "already materialized"** (read the existing draft via `get_campaign_pack`). Rate limit 60/min. |
+
+### Series — recurring content shows
+
+| Tool | What it does |
+|---|---|
+| `create_series` / `list_series` / `update_series` | A reusable recurring-content show template ("Myth vs Fact", "Founder Tip") bound to an optional brand + product profile; toggle `active`/`paused`/`archived`. |
+| `plan_series_episodes` | Draft 3–5 upcoming episode ideas for a series (free assist quota). Rate limit 30/min. |
+| `list_series_episodes` | List a series' episodes (idea → drafted → published) with their materialized draft slug + route. |
+| `materialize_episode` | Turn an idea episode into a 0-credit draft under the series' rolling pack. Safe to retry — no duplicate is ever created; a sequential re-call of an already-materialized episode returns **422 "already materialized"** (find the draft via `list_series_episodes`). Rate limit 60/min. |
+| `get_series_dashboard` | One series' episodes grouped into lanes: upcoming (ideas) / drafted / published, with per-item performance notes. |
+| `mark_episode_posted` | Record that you posted a drafted episode manually (drafted → published; stamps `posted_at`; idempotent). |
+
+### Content calendar — reminder-only scheduling
+
+These stage a **reminder** (a push to *you* at the due time) — they never attach a social
+account, so publishing stays a human step in the app. All $0.
 
 | Tool | What it does |
 |---|---|
-| `create_editor_draft` | Editor project, no autopilot (0 credits). Accepts `creative_format` / `visual_language` / `theme`. |
-| `generate_scenario` / `set_scenario` | AI-draft the scenario (1 assist) **or** write your own (free). `generate_scenario` can also persist `creative_format` / `visual_language` / `theme`. |
-| `get_editor` | Full project state — the review step |
-| `set_scene_count` | Grow/shrink to N scenes (1–20) |
-| `set_segment_prompt` / `generate_segment` / `generate_all_segments` | Write a scene prompt (free); render one (5 credits) or every scene in order |
-| `set_narration_script` / `generate_narration` | Write the voiceover script (free) **or** AI-draft it (1 assist) |
-| `generate_voice` / `generate_music` | TTS voiceover (3 credits) / background music (5 credits) |
-| `render` | Final MP4 (0 credits; auto-charges any still-ungenerated scenes) |
+| `schedule_post` | Schedule a completed video result for a future UTC instant as a manual-posting reminder (≤500 pending posts per user). |
+| `list_scheduled_posts` | Your calendar (ordered by `scheduled_at`), with the staged caption/hashtags + presigned export URL; filter by `from`/`to`/`status`. |
+| `reschedule_post` | Move a scheduled/reminded post to a new future instant. |
+| `cancel_scheduled_post` | Cancel a scheduled/reminded/failed post. |
+| `mark_scheduled_posted` | Record that you posted it manually (scheduled/reminded → posted). |
 
-**AI assists** — a free daily quota of AI helper calls
+### Performance — learn from your own results
 
 | Tool | What it does |
 |---|---|
-| `get_ai_assists` / `unlock_ai_assists` | Check the daily quota / spend 1 credit for +10 |
-| `generate_short_text` / `enhance_prompt` / `suggest_next_scene` / `suggest_music_prompt` | AI helpers (1 assist each) |
+| `record_performance` | Attach a performance snapshot (platform + engagement/conversion counts + optional revenue/watch time) to a campaign-pack item. Many per item. Rate limit 30/min. |
+| `list_performance` | A campaign-pack item's snapshots (newest first) + a small summary. |
+| `set_item_attributes` / `get_item_attributes` | The single creative-attributes row (hook_type, creative_format, visual_language, product_category, CTA, length, caption_style) the recommendation loop correlates with performance (atomic upsert). |
+| `get_recommendations` | A **cautious**, sample-size-aware read of your own best hook/format/visual_language by average views, with an honest confidence tier and a non-causal `note` — present them as-is, never upgrade them. No LLM, no quota. |
+| `make_more_like_winner` | Spin 3 fresh hook variations from a winning item, threading its angle/format while keeping its brand + product. Feed a chosen one back into `add_pack_variations`. Rate limit 30/min. |
 
-## Typical flow
+### Review links — no-login approval loop
+
+| Tool | What it does |
+|---|---|
+| `create_review_link` | Mint an expiring, hashed-token link for one completed output (a video result **or** a slider). The plaintext token + URL are returned **once** — surface them immediately. `expires_in_hours` default 168 (7 days). |
+| `list_review_links` | Your links (pending → viewed → approved / changes_requested / revoked) with visible comment counts. Never returns the token. |
+| `revoke_review_link` | Revoke a link — its no-login URL stops working immediately. |
+
+### Asset catalog — cross-project reusable media
+
+Subscription-gated (a 402 `subscription_required` means the account needs an active subscription).
+
+| Tool | What it does |
+|---|---|
+| `list_assets` | Your reusable asset catalog (images + videos) with presigned URLs + your storage quota; page with `limit`/`offset`. |
+| `get_asset_quota` | Your catalog storage quota (limit / used / pending / reserved / remaining bytes). |
+| `upload_asset` | Upload a local image (≤20 MiB) or video (≤500 MB; `duration_seconds` required, ≤60) into the catalog so it can be reused across projects. Reads confined to `HUBFLUENCER_INPUT_DIR`. Rate limit 30/min. |
+
+### Credit prices (reference)
+
+Spend happens server-side; each tool prices the action first. `create_*` and every draft
+edit are **0 credits** — you only pay to generate/render.
+
+| Action | Credits |
+|---|---|
+| Any draft create / edit / reorder | 0 |
+| Short render | **15** |
+| Editor AI scene (`generate_segment`) | **5** (4 each in a batch of ≥3) |
+| Editor voice | **3** |
+| Editor music | **5** |
+| Editor render | **0** (auto-charges only still-ungenerated scenes) |
+| Editor autopilot (whole pipeline, ~5 scenes) | ~**28** (preview with `make_video` `dry_run`) |
+| Carousel render | **1 / slide** (3–10 slides) |
+| Carousel restyle / per-slide edit | **0** |
+| Tracking render | **1** (refunded on failure) |
+| Unlock AI assists | **1 credit → +10 assists** |
+| Onboard / plan / pack / materialize / series / calendar / performance / review / profiles | **0** (planning tools draw the free daily assist quota) |
+
+## Typical flows
 
 **One shot (recommended):**
 `make_video({ prompt: "an ad for…", save_path: "ad.mp4" })` → returns `{ ready, video_url, saved_to, estimated_credits, available_credits }`.
@@ -112,6 +249,25 @@ returned `caption` + `hashtags`. To tweak the look afterward without re-paying,
 (new template/accent, re-renders every slide) or `edit_slider_slide` (rewrite one slide's text) — both
 free; poll `get_slider` again until `completed`.
 
+**Tracking overlay (your own clip):**
+`create_tracking_video({ video_path: "clip.mp4", save_path: "tracked.mp4" })` → uploads the clip, waits for it
+to be ready, renders the CV object-tracking overlay (1 credit), polls to completion, and downloads the result.
+Optionally pass `classes` (COCO-80 ids, e.g. `[0]`=person, `[16]`=dog; omit to track all) and `color` ([r,g,b,a]).
+If it returns `terminal:false`, call it again with the returned `slug` to resume, or poll
+`wait_for_completion({ slug, kind: "tracking" })` then `download_result`. Resuming a slug whose render already
+**completed** just returns the finished video — a completed project is final; for a variant (different classes/color),
+start a NEW project (omit `slug`, pass `video_path`).
+
+**Delegate a content operation (the full loop — steps 1–3 are $0):**
+1. `extract_product_page(url)` → `create_product_profile` + `create_brand_profile` (persist the identity once).
+2. `plan_campaign` / `generate_hook_variations` (free quota), or `create_campaign(url | product_profile_id)` to do 1–2 end-to-end.
+3. `create_campaign_pack` → `add_pack_variations` / `materialize_pack_item` → editable **drafts**.
+4. Generate each draft explicitly (credits): `start_autopilot` / `generate_short` / `generate_slider`.
+5. `create_review_link` for a no-login human approval; gate spend/posting on it.
+6. `schedule_post` a reminder calendar; after you post the export, `mark_scheduled_posted`.
+7. `record_performance` + `set_item_attributes` → `get_recommendations` → `make_more_like_winner` → back to step 3.
+8. Recurring: `create_series` + `plan_series_episodes` → `materialize_episode`; `get_series_dashboard` tracks the lanes.
+
 > Result URLs are presigned and expire (~24h). Download promptly. Publishing to
 > TikTok/Instagram requires a human-linked social account and is out of scope —
 > return the MP4 + a suggested caption instead.
@@ -124,6 +280,8 @@ free; poll `get_slider` again until `completed`.
 | `npm error could not determine executable to run` | You're on a cached **0.1.x** (which shipped two bins). 0.2.0+ ships a single bin and resolves cleanly. Force a fresh fetch: `npx --ignore-existing -y @hubfluencer/mcp`. |
 | `npm error 404 … @hubfluencer/mcp` immediately after a release | npm registry/CDN propagation lag (a couple of minutes after publish). Wait and retry — it self-heals. |
 | Tools fail with **"Not connected to Hubfluencer"** | No token resolved. Run `npx -y @hubfluencer/mcp login`, or pass `--env HUBFLUENCER_API_TOKEN=…`. |
+| A local-file tool fails with a **path-outside-base** error | The file is outside `HUBFLUENCER_INPUT_DIR` (reads) or `save_path` is outside `HUBFLUENCER_OUTPUT_DIR` (writes). Move the file into the allowed dir, or point the env var at it. |
+| An asset-catalog tool returns **subscription required** | `list_assets` / `get_asset_quota` / `upload_asset` need an active subscription — subscribe in the app. |
 
 ## Develop