@hubfluencer/mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Monocursive
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,110 @@
+# @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.
+
+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.
+
+## Setup
+
+No install step — run it on demand with `npx` (commands below). For local development,
+build from source instead: see [Develop](#develop).
+
+### 1. Connect (recommended — no copy-paste)
+
+Run the device-link login. It prints a URL + short code; you approve it in the signed-in
+Hubfluencer app, and a scoped access token is saved locally to `~/.hubfluencer/credentials.json`
+(mode 0600) — the MCP server reads it from there automatically.
+
+```bash
+npx -y -p @hubfluencer/mcp hubfluencer-login "Claude Code"
+#  1. Open:        https://hubfluencer.com/connect?code=ABCD-EFGH
+#  2. Confirm code: ABCDEFGH
+#  3. Click Approve.  →  ✓ Connected.
+```
+
+Then register the server (no token env needed — it uses the stored credential):
+
+```bash
+claude mcp add hubfluencer -- npx -y @hubfluencer/mcp
+```
+
+### Alternative: paste an access token
+
+Create a token in the app (**Settings → Access tokens**, scoped `video:generate`+`video:read` —
+it **cannot** delete your account, change credentials, publish, or create more tokens), then:
+
+```bash
+claude mcp add hubfluencer --env HUBFLUENCER_API_TOKEN=YOUR_TOKEN -- npx -y @hubfluencer/mcp
+```
+
+| 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) |
+
+## Tools
+
+**One-shot & status**
+
+| 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` | Create a short draft (0 credits) / render it (15 credits) |
+| `create_editor_ad` | Create an editor project **and** run autopilot end-to-end |
+| `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
+
+| Tool | What it does |
+|---|---|
+| `create_editor_draft` | Editor project, no autopilot (0 credits) |
+| `generate_scenario` / `set_scenario` | AI-draft the scenario (1 assist) **or** write your own (free) |
+| `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) |
+
+**AI assists** — a free daily quota of AI helper calls
+
+| Tool | What it does |
+|---|---|
+| `get_ai_assists` / `unlock_ai_assists` | Check the daily quota / spend 1 credit for +10 |
+| `enhance_prompt` / `suggest_next_scene` / `suggest_music_prompt` | AI helpers (1 assist each) |
+
+## Typical flow
+
+**One shot (recommended):**
+`make_video({ prompt: "an ad for…", save_path: "ad.mp4" })` → returns `{ ready, video_url, saved_to, estimated_credits, available_credits }`.
+It prices the job and only charges if it's affordable (and within `max_credits` if you set one); otherwise it returns
+`charged:false` with the estimate and a free draft slug. Preview first with `make_video({ prompt, dry_run:true })`.
+If it returns `terminal:false`, the render is still going — call `wait_for_completion` with the returned slug.
+
+**Granular (control/recovery):**
+`create_short` → `generate_short` → `wait_for_completion {kind:"short"}` → `download_result`, or
+`create_editor_ad` → `wait_for_completion {kind:"editor"}` → `download_result`.
+
+> 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.
+
+## Develop
+
+```bash
+bun install
+bun run typecheck
+bun run dev        # runs the stdio server (talk to it via an MCP client)
+bun run build      # emits dist/
+```
+
+## License
+
+[MIT](./LICENSE) © Monocursive