hermoso 0.1.23 → 0.1.25

package/README.md

@@ -1,14 +1,17 @@
 # Hermoso — MCP, CLI & Skills
 
-Drive [Hermoso](https://hermoso.ai) — the AI ad studio — from **any AI agent**: Claude Code, Claude.ai, Cursor,
-Codex, or your own scripts. Research the ads already winning in a market, plan a creative, and generate finished
-image & video ads (your real product composited in, copy + CTA included) — all over
-[MCP](https://modelcontextprotocol.io) tools, a CLI, or installable Claude skills.
+Run your whole marketing operation from **any AI agent**: Claude Code, Claude.ai, Cursor, Codex, or your own
+scripts. Research the ads already winning in a market, generate finished image & video ads (your real product
+composited in, copy + CTA included), publish them to your own social channels, and build & manage the ad
+campaigns behind them — all over [MCP](https://modelcontextprotocol.io) tools, a CLI, or installable Claude skills.
+
+**247 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
+catalog with exact per-render credit costs plus the full capability map.
 
 ## Instant: the hosted Claude.ai connector
 
 Paste **`https://app.hermoso.ai/mcp`** into Claude → Settings → Connectors → *Add custom connector*, approve with
-your Hermoso account, done — the full studio toolset with your saved brand context, billed to your plan.
+your Hermoso account, done — the full toolset with your saved brand context, billed to your plan.
 
 ## Quickstart for Claude Code / Cursor / scripts (2 minutes)
 
@@ -27,8 +30,8 @@ learned memory you set up in the web app apply automatically (`get_brand` shows
 
 ## 1. MCP server (stdio) — Claude Code / Cursor / Codex
 
-`hermoso mcp` runs a stdio MCP server exposing the full studio toolset (40+ tools). The published `hermoso`
-package means no clone — `npx -y hermoso mcp` fetches and runs it:
+`hermoso mcp` runs a stdio MCP server exposing the full toolset. The published `hermoso` package means no clone —
+`npx -y hermoso mcp` fetches and runs it:
 
 ```bash
 claude mcp add hermoso -e HERMOSO_TOKEN=hmk_… -- npx -y hermoso mcp
@@ -43,25 +46,67 @@ Cursor / Codex — add to `mcp.json` (Codex uses the TOML equivalent):
 
 Then ask your agent: *“Generate an image ad with Hermoso.”*
 
-**Tools (40+):** research/ad-spy (`find_competitors`, `pull_competitor_ads`, `research_ads`, `search_meta_ads`,
-`search_google_ads`, `search_linkedin_ads`, `search_tiktok`, `search_instagram`, `search_youtube`, `search_reddit`,
-`search_threads`, `scrapecreators_fetch`), plan → generate → finish (`plan_ad`, `plan_variations`, `generate_image`,
-`generate_video`, `generate_avatar`, `render_ad`, `make_template_ad`, `stitch_video`, `reframe_video`,
-`upscale_video`, `dub_video`, `change_voice`, `recast_motion`, `remix_static`, `finish_video`, `fix_beat`),
-brand + account (`get_brand`, `list_brands`, `use_brand`, `draft_brand`, `list_product_photos`, `set_product_image`,
-`hermoso_capabilities`, `hermoso_credits`, `buy_credits`), and analysis/jobs (`analyze_video`, `score_ad`,
-`check_ad_policy`, `competitor_teardown`, `mine_angles`, `get_job`, `list_jobs`, `get_skill`, `list_skills`,
-`fetch_asset`). Call `hermoso_capabilities` first — it returns valid model ids and per-render credit costs;
-`tools/list` is the authoritative current set. Render jobs queue server-side and poll to completion, returning a
-served URL.
+### What the 247 tools cover
+
+**Ad spy / research** — `find_competitors`, `competitor_teardown`, `pull_competitor_ads`, `research_ads`; the
+Meta / Google / LinkedIn ad libraries (`search_meta_ads`, `search_google_ads`, `search_linkedin_ads`); organic
+social (`search_tiktok`, `search_instagram`, `search_youtube`, `search_reddit`, `search_threads`);
+`scrapecreators_fetch`, `mine_angles`, `analyze_video`, `check_ad_policy`, `list_skills` / `get_skill`.
+
+**Create** — `draft_brand` → `plan_ad` → `render_ad` (the Studio quality pipeline: composited text, clean speech,
+music, brand end card), or `generate_image` / `generate_video` / `generate_avatar` (UGC creators + lip-sync).
+Also `make_template_ad` (native HTML ad formats), `make_explainer`, `product_sizzle`, `make_thumbnail`,
+`remix_static`, `recast_motion`, `reframe_video`, `upscale_video`, `dub_video`, `change_voice`, `finish_video`,
+`fix_beat`, `stitch_video`, `clip_video`, `post_edit`, plus `plan_variations` + `score_ad` to fan out and rank.
+**Length is yours to set:** pass `durationSeconds` to `plan_ad` and the storyboard is *authored* to it — ≤15s
+renders as one continuous clip, longer is stitched from acts (40s = 15+15+10), never time-compressed.
+
+**Raw model playground** — the full catalog (30+ image / video / voice / writing models, each with its exact
+per-render credit cost) with no ad framing: `generate_image` / `generate_video` with `useBrand:false`,
+`generate_voice`, `generate_text`.
+
+**Publish to your own channels** — Facebook, Instagram and Threads (`post_to_meta`), TikTok (`post_to_tiktok`),
+YouTube (`post_to_youtube` + `update_youtube_video`, `youtube_video_insights`, comments read/reply), X
+(`post_to_x`, `x_post_metrics`, `x_post_insights`, `x_mentions`), LinkedIn profile **and** company Pages
+(`post_to_linkedin`, `post_to_linkedin_page`), Pinterest (`post_to_pinterest` + boards), and Google Business
+Profile (`post_to_google_business` — Google grants this API per project, so access must be approved before Posts
+publish). `schedule_post` / `list_scheduled` / `cancel_scheduled` give you one content calendar across channels.
+`upload_file` brings in any external or local media, not just Hermoso renders.
+*X posting bills credits per API call (X charges per request); a post containing a link costs 13× one without.*
+
+**Run the ads** — full campaign trees, built paused and read back before anything is reported, with every spend
+change confirm-gated, on **Meta**, **Google Ads**, **LinkedIn Ads**, **Pinterest Ads**, **Microsoft Advertising**
+and **ChatGPT Ads** (OpenAI's Advertiser API). Each has list + report + create + budget/status tools
+(e.g. `list_google_ads_campaigns`, `google_ads_report`, `create_google_ads_campaign`, `set_google_ads_budget`,
+`set_google_ads_status`). *X Ads are not supported — X posting only.*
+
+**Files** — Google Drive CRUD (`save_to_drive`, `list_drive_files`, `update_drive_file`, `delete_drive_file`,
+`create_drive_folder`), Google Sheets (`create_sheet`, `append_to_sheet`, `read_sheet`), Google Docs
+(`create_doc`, `append_to_doc`), and OneDrive (`save_to_onedrive` + full CRUD).
+
+**Workspace & account** — brand workspaces (`list_brands`, `create_brand`, `use_brand`, `update_brand`,
+`delete_brand` — one account holds many brands, so an agency runs every client through here), memory
+(`remember`, `forget`, `list_memory`), custom skills (`save_skill`, `delete_skill`), AI employees
+(`save_employee`, `list_employees`, `set_active_employee`), team (`list_team`, `invite_member`, `remove_member`,
+`set_role`), settings (`get_settings`, `update_settings` — including the **language** every ad, script and plan
+is written in), connectors (`list_connectors`, `list_connector_accounts`, `set_connector_accounts`,
+`disconnect_connector`), and billing (`hermoso_credits`, `billing_status`, `buy_credits`, `upgrade_plan`,
+`set_auto_reload`), plus `list_jobs` / `get_job` for async renders.
+
+**Connector accounts are picked, not guessed.** One person often administers several Facebook Pages, Google Ads
+customers or LinkedIn company Pages. Only the accounts ticked for a brand are usable — enforced server-side, and
+an empty selection shares nothing. Linking a *new* account is the one step that is not headless (it is an OAuth
+consent screen, so the user does it in the app).
+
+Render jobs queue server-side and poll to completion, returning a served URL.
 
 ## 2. CLI — the token-cheap path for terminal agents
 
-`bin/hermoso.mjs` mirrors the tools as subprocess commands, so an agent can shell out instead of carrying a fat
-tool manifest.
+`bin/hermoso.mjs` mirrors the core tools as subprocess commands, so an agent can shell out instead of carrying a
+fat tool manifest.
 
 ```bash
-npm install -g .                                   # installs `hermoso`
+npm install -g hermoso                             # installs `hermoso`
 hermoso capabilities                               # valid model ids + costs (run first)
 hermoso create --brand "YourBrand" --product "your best-selling product" --format image
 hermoso generate image --prompt "…" --ref ./product.png --wait
@@ -88,8 +133,9 @@ Then invoke `/hermoso-ad-from-brand an ad for yourbrand.com — our hero product
 | Env | Meaning |
 | --- | --- |
 | `HERMOSO_API_BASE` | The Hermoso API origin (default `https://app.hermoso.ai` — set `http://localhost:3000` if you run the app yourself) |
-| `HERMOSO_TOKEN` | Bearer token — required against the hosted app (rolling out) |
+| `HERMOSO_TOKEN` | Bearer agent key (`hmk_…`) — required against the hosted app |
 | `HERMOSO_PROFILE` | Brand-workspace id, for accounts with multiple brand profiles |
+| `HERMOSO_OWNER` | Only for a brand **another account shared with you** (a team workspace): the owning account id. Set it together with `HERMOSO_PROFILE`, and set `HERMOSO_PROFILE` to that workspace's **profileUuid** — a brand's short slug is refused. Run `list_brands` (or `hermoso brands`) to print both values for every workspace you can enter. The server re-authorizes the pair on every request, so a wrong value is refused, never trusted. |
 
 `mcp/http.mjs` is the hosted remote-connector transport (paste-a-URL into Claude.ai → Connectors). It ships in
 this repo for transparency and refuses to mount without authenticated identity — no anonymous spend, ever.

package/bin/hermoso.mjs

@@ -78,6 +78,7 @@ async function main() {
   process.env.HERMOSO_API_BASE = process.env.HERMOSO_API_BASE || cfg.apiBase || 'https://app.hermoso.ai';
   if (cfg.token && !process.env.HERMOSO_TOKEN) process.env.HERMOSO_TOKEN = cfg.token;
   if (cfg.profile && !process.env.HERMOSO_PROFILE) process.env.HERMOSO_PROFILE = cfg.profile;
+  if (cfg.owner && !process.env.HERMOSO_OWNER) process.env.HERMOSO_OWNER = cfg.owner; // shared team workspace: the owning account (server re-authorizes it)
 
   // `hermoso mcp` → run the stdio MCP server (Claude Code / Cursor / Codex spawn this, e.g. `npx -y hermoso mcp`).
   // It OWNS stdout as the JSON-RPC channel, so hand off immediately and print nothing to stdout here. The

package/mcp/client.mjs

@@ -17,11 +17,26 @@ const TOKEN = process.env.HERMOSO_TOKEN || '';
 // header > key.keyProfileId > 'default' (adapters/auth/middleware.js), so always sending the header permanently
 // masks the brand `use_brand` saved against the key — connectors on any non-default brand then look disconnected.
 export const PROFILE = process.env.HERMOSO_PROFILE || '';
+// SHARED TEAM WORKSPACE: the OWNING account. The web client sends this as x-hermoso-owner from PROFILE_OWNER
+// (public/app.js ctxHeaders) whenever the active brand belongs to someone else's account; the MCP twins never did,
+// so a member driving Hermoso headlessly resolved every brand-scoped read against their OWN empty account —
+// resolveWs's `if (owner && owner !== own)` branch simply never ran and it fell through to the own-account path.
+// Symptom (live 2026-07-31): 0 connectors over MCP on a workspace showing 10 in the browser, with NO error.
+// SAFE TO SEND: the server RE-AUTHORIZES it against profile_members on every request (adapters/auth/middleware.js
+// resolveWs), so a forged or stale value is 403'd, never trusted. Like the profile header it must stay UNSET by
+// default — sending an owner for your own account would make resolveWs take the shared branch against yourself.
+// PAIR IT WITH THE PROFILE UUID, not the slug: profile_members keys on profiles.id, so a client_slug is the one
+// thing isMember() cannot match and it 403s. list_brands names both values for every workspace you can enter.
+export const OWNER = process.env.HERMOSO_OWNER || '';
+// The env-var prefix THIS build reads. tools.mjs is byte-identical across the two twins, so it cannot
+// hardcode either name when it tells a user which variables to set — it asks its own client.
+export const ENV_PREFIX = 'HERMOSO';
 
 function headers(extra = {}) {
   const ctx = mcpCtx.getStore();
   const prof = ctx?.profile || PROFILE; // omitted when unpinned so the key's saved brand wins server-side
-  const h = { 'Content-Type': 'application/json', ...(prof ? { 'x-hermoso-user': prof } : {}), ...extra };
+  const own = ctx?.owner || OWNER; // the wire name is x-hermoso-owner on BOTH twins — it is the server's header, not a brand
+  const h = { 'Content-Type': 'application/json', ...(prof ? { 'x-hermoso-user': prof } : {}), ...(own ? { 'x-hermoso-owner': own } : {}), ...extra };
   const tok = ctx?.token || TOKEN;
   if (tok) h.Authorization = `Bearer ${tok}`;
   return h;
@@ -131,4 +146,4 @@ export async function toRef(srcOrPath) {
   return `data:${mime};base64,${buf.toString('base64')}`;
 }
 
-export const authState = () => ({ apiBase: API_BASE, hasToken: !!TOKEN, profile: PROFILE });
+export const authState = () => ({ apiBase: API_BASE, hasToken: !!TOKEN, profile: PROFILE, owner: OWNER });