hermoso 0.1.23 → 0.1.24

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.
+
+**205 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 205 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,7 +133,7 @@ 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 |
 
 `mcp/http.mjs` is the hosted remote-connector transport (paste-a-URL into Claude.ai → Connectors). It ships in

package/mcp/tools.mjs

@@ -1858,14 +1858,14 @@ export function registerTools(server) {
   }));
   server.registerTool('microsoft_ads_report', {
     title: 'Microsoft Advertising performance report',
-    description: 'Performance for a Microsoft Advertising account — impressions, clicks, CTR, average CPC, spend, conversions, broken down by campaign. Window via timePeriod (Today | Yesterday | LastSevenDays | ThisWeek | LastWeek | LastFourWeeks | ThisMonth | LastMonth | LastThreeMonths | LastSixMonths | ThisYear | LastYear) or since+until (YYYY-MM-DD). Microsoft generates reports ASYNCHRONOUSLY: this can return pending:true with a reportRequestId, and you must call again rather than reporting any numbers. A report that succeeds with ZERO rows genuinely means there was no delivery in that window — say exactly that; never present zeros as measured performance. Read-only, free.',
+    description: 'Performance for a Microsoft Advertising account — impressions, clicks, CTR, average CPC, spend, conversions, broken down by campaign. Window via timePeriod (Today | Yesterday | LastSevenDays | Last14Days | Last30Days | ThisWeek | LastWeek | LastFourWeeks | ThisMonth | LastMonth | LastThreeMonths | LastSixMonths | ThisYear | LastYear | ThisWeekStartingMonday | LastWeekStartingMonday | LastFourWeeksStartingMonday) or since+until (YYYY-MM-DD) — default Last30Days. An unrecognised timePeriod is REFUSED, never silently swapped for another window. Microsoft generates reports ASYNCHRONOUSLY: this can return pending:true with a reportRequestId, and you must call again rather than reporting any numbers. A report that succeeds with ZERO rows genuinely means there was no delivery in that window — say exactly that; never present zeros as measured performance. Read-only, free.',
     inputSchema: {
       accountId: z.string().optional().describe('Microsoft ad account id — omit to use the brand’s single shared account'),
-      timePeriod: z.string().optional().describe('predefined window, default LastMonth'),
+      timePeriod: z.string().optional().describe('predefined Microsoft window, default Last30Days — must be one of the values in the description; anything else is rejected'),
       since: z.string().optional().describe('YYYY-MM-DD custom range start (with until)'),
       until: z.string().optional().describe('YYYY-MM-DD custom range end'),
       columns: z.array(z.string()).optional().describe('report columns — defaults to campaign performance'),
-      reportRequestId: z.string().optional().describe('pick up a report that came back pending'),
+      reportRequestId: z.string().optional().describe('pick up a report that came back pending — pass it back and this RESUMES that exact report instead of submitting a new one'),
     },
     outputSchema: { accountId: z.string().optional(), count: z.number().optional(), rows: z.array(z.any()).optional(), pending: z.boolean().optional(), reportRequestId: z.string().optional(), note: z.string().optional() },
     annotations: { readOnlyHint: true, openWorldHint: true },
@@ -2275,6 +2275,318 @@ export function registerTools(server) {
     return ok(d.note || `${d.level || 'campaign'} → ${d.verifiedStatus || a.status}.`, d);
   }));
 
+
+  // ══ REDDIT ADS (2026-07-31) ════════════════════════════════════════════════════════════════════════════════
+  // Reddit's object graph is campaign → ad group → ad, and the AD HAS NO CREATIVE OF ITS OWN: it points at a
+  // POST, which is published as a PROFILE. So the build order is profile → post → campaign → ad group → ad, and
+  // an agent that stops at "campaign created" has produced something that can never serve an impression.
+  // Every id is authorised against the accounts ticked under Manage accounts; nothing here can reach an ad
+  // account the brand was not given, and everything is created PAUSED with no override.
+  server.registerTool('list_reddit_ads_campaigns', {
+    title: 'List Reddit ad accounts / campaigns',
+    description: 'Read the brand’s connected Reddit AD account(s). Call with NO adAccountId to list the ad accounts shared with this brand — do this first to pick a target. Call WITH adAccountId to read that account’s whole tree at once: campaigns, ad groups and ads, each with its configured status and Reddit’s own effective status (the effective one is what says whether it could actually serve — PENDING_APPROVAL, CAMPAIGN_PAUSED, REJECTED and so on). Read-only, free. Needs Reddit Ads connected (Settings ▸ Connectors ▸ Reddit Ads) and the ad account ticked under Manage accounts.',
+    inputSchema: { adAccountId: z.string().optional().describe('Reddit ad account id (a2_…) — omit to list the ad accounts shared with this brand') },
+    outputSchema: { accounts: z.array(z.any()).optional(), adAccountId: z.string().optional(), name: z.string().optional(), campaigns: z.array(z.any()).optional(), adGroups: z.array(z.any()).optional(), ads: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    if (!a.adAccountId) {
+      const d = await apiGet('/api/reddit-ads/shared-accounts', {});
+      if (!(d.accounts || []).length) return ok('No Reddit ad account is shared with this brand yet. Ask the user to tick the ones it may use in Settings ▸ Connectors ▸ Reddit Ads ▸ Manage accounts (or call set_connector_accounts), then retry.', d);
+      const lines = (d.accounts || []).map(c => `• ${c.name} (${c.id})${c.currency ? ` — ${c.currency}` : ''}`);
+      return ok(`${(d.accounts || []).length} Reddit ad account(s) shared with this brand:\n${lines.join('\n')}\nPass an adAccountId to read its campaigns, ad groups and ads.`, d);
+    }
+    const d = await apiGet('/api/reddit-ads/campaigns', { adAccountId: a.adAccountId });
+    const c = (d.campaigns || []).map(x => `• campaign ${x.name} (${x.id}) — ${x.configured_status}/${x.effective_status}, ${x.objective}`);
+    const g = (d.adGroups || []).map(x => `• ad group ${x.name} (${x.id}) — ${x.configured_status}/${x.effective_status}`);
+    const s = (d.ads || []).map(x => `• ad ${x.name} (${x.id}) — ${x.configured_status}/${x.effective_status}`);
+    return ok(`Reddit ad account ${d.adAccountId}${d.name ? ` (${d.name})` : ''}: ${(d.campaigns || []).length} campaign(s), ${(d.adGroups || []).length} ad group(s), ${(d.ads || []).length} ad(s).\n${[...c, ...g, ...s].join('\n') || '(empty)'}`, d);
+  }));
+  server.registerTool('reddit_ads_report', {
+    title: 'Reddit ads performance report',
+    description: 'Performance for a Reddit ad account — impressions, clicks, spend, CTR, CPC, eCPM, reach and any of Reddit’s ~450 metric fields, optionally broken down by campaign, ad group, ad, date, hour, community, country, gender, interest, keyword, placement and more. Money comes back in WHOLE UNITS of the ad account’s currency (Reddit reports micro-currency; the conversion is done for you) — and that currency is not necessarily dollars, so check the account. Reddit only accepts HOURLY window boundaries; plain YYYY-MM-DD dates are accepted here and snapped for you. A report with ZERO rows genuinely means nothing delivered in that window — say exactly that and never present zeros as measured performance. Read-only, free.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      since: z.string().optional().describe('YYYY-MM-DD or full ISO timestamp, default 30 days ago'),
+      until: z.string().optional().describe('YYYY-MM-DD or full ISO timestamp, default today'),
+      fields: z.array(z.string()).optional().describe('Reddit metric names, UPPER_SNAKE (IMPRESSIONS, CLICKS, SPEND, CTR, CPC, ECPM, REACH, FREQUENCY, CONVERSION_ROAS, VIDEO_WATCHED_100_PERCENT, CONVERSION_PURCHASE_TOTAL_VALUE…). Omit for a sensible default set; if you name one Reddit does not know, its error lists every valid value.'),
+      breakdowns: z.array(z.enum(['AD_ACCOUNT_ID', 'AD_GROUP_ID', 'AD_ID', 'CAMPAIGN_ID', 'COUNTRY', 'DATE', 'HOUR', 'DMA', 'METRO', 'CAROUSEL_CARD', 'GALLERY_ITEM_ID', 'GENDER', 'INTEREST', 'KEYWORD', 'PLACEMENT', 'OS_TYPE', 'ASSET_ID', 'REGION', 'COMMUNITY', 'LANGUAGE'])).optional().describe('up to 3 (4 if both COUNTRY and REGION). Omit for one aggregate row.'),
+      filter: z.string().optional().describe('Reddit filter expression to restrict rows to particular ids/values'),
+      timeZoneId: z.string().optional().describe('IANA zone, e.g. America/New_York'),
+    },
+    outputSchema: { ok: z.boolean().optional(), adAccountId: z.string().optional(), since: z.string().optional(), until: z.string().optional(), count: z.number().optional(), rows: z.array(z.any()).optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/reddit-ads/report', a);
+    return ok(`${d.note}\n${JSON.stringify((d.rows || []).slice(0, 40))}`, d);
+  }));
+  server.registerTool('list_reddit_ads_profiles', {
+    title: 'List the Reddit profiles an ad account can publish as',
+    description: 'List the Reddit PROFILES attached to an ad account. A Reddit ad promotes a POST, and every post is published AS one of these profiles — so this is the first call in any Reddit creative build, and its id is what create_reddit_ads_post needs. If it comes back empty, the ad account has no profile attached and nothing can be advertised from it yet. Read-only, free.',
+    inputSchema: { adAccountId: z.string().optional() },
+    outputSchema: { adAccountId: z.string().optional(), count: z.number().optional(), profiles: z.array(z.any()).optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/reddit-ads/profiles', a);
+    return ok(`${d.note}\n${(d.profiles || []).map(p => `• ${p.name} (${p.id})`).join('\n')}`, d);
+  }));
+  server.registerTool('search_reddit_ads_targeting', {
+    title: 'Resolve Reddit communities / geolocations / interests for targeting',
+    description: 'Look up the exact values Reddit ad-group targeting expects, so none of them has to be guessed. kind:"communities" searches subreddits by keyword and returns each one’s NAME plus its subscriber count — targeting wants the bare name ("running"), NOT the t5_ id and NOT "r/running". kind:"geolocations" lists targetable places (pass country like US, or a city search) — targeting accepts a country code or one of the returned ids. kind:"interests" lists Reddit’s interest taxonomy — targeting wants the id ("pets_v3"). Read-only, free. Use this before create_reddit_ads_ad_group rather than inventing a community name.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      kind: z.enum(['communities', 'geolocations', 'interests']).optional().describe('default communities'),
+      query: z.string().optional().describe('keyword — required for communities, filters interests, searches cities for geolocations'),
+      country: z.string().optional().describe('2-letter country code, geolocations only'),
+      postalCode: z.string().optional(),
+      limit: z.number().optional().describe('max results, default 15'),
+    },
+    outputSchema: { kind: z.string().optional(), count: z.number().optional(), results: z.array(z.any()).optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/reddit-ads/targeting', a);
+    return ok(`${d.note}\n${JSON.stringify((d.results || []).slice(0, 30))}`, d);
+  }));
+  server.registerTool('reddit_ads_forecast', {
+    title: 'Forecast Reddit audience size and delivery',
+    description: 'Ask Reddit how big a targeting set is and roughly what a budget would buy — total reachable audience, the targeted slice, and estimated impressions, clicks and reach. Free, creates nothing, spends nothing, so run it BEFORE building an ad group to sanity-check targeting that may be far too narrow or far too broad. Budget is an ordinary amount in the ad account’s currency. These are Reddit’s estimates, not a guarantee — say so when reporting them.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      budget: z.number().describe('budget in the ad account’s currency (not micro-currency — the conversion is handled)'),
+      objective: z.enum(['APP_INSTALLS', 'CATALOG_SALES', 'CLICKS', 'CONVERSIONS', 'IMPRESSIONS', 'LEAD_GENERATION', 'VIDEO_VIEWABLE_IMPRESSIONS']).optional().describe('default CLICKS'),
+      goalType: z.enum(['DAILY_SPEND', 'LIFETIME_SPEND']).optional(),
+      bidType: z.enum(['CPC', 'CPM', 'CPV', 'CPV6']).optional(),
+      bidStrategy: z.enum(['BIDLESS', 'MANUAL_BIDDING', 'MAXIMIZE_VOLUME', 'TARGET_CPX']).optional(),
+      bidAmount: z.number().optional(),
+      startTime: z.string().optional().describe('ISO 8601'),
+      endTime: z.string().optional(),
+      targeting: z.any().optional().describe('same shape as create_reddit_ads_ad_group targeting'),
+    },
+    outputSchema: { totalAudienceSize: z.number().optional(), targetAudienceRange: z.any().optional(), deliveryEstimates: z.any().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/reddit-ads/forecast', a);
+    return ok(d.note, d);
+  }));
+  server.registerTool('reddit_ads_bid_suggestion', {
+    title: 'Ask Reddit what to bid',
+    description: 'Reddit’s own suggested bid for a given objective, bid type and targeting — a median, a sensible range, and the hard floor below which Reddit will not accept a bid. Amounts come back in the ad account’s currency. Free, creates nothing. Use it to pick bidAmount for create_reddit_ads_ad_group instead of guessing a number that either never wins an auction or overpays.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      budget: z.number().describe('budget in the ad account’s currency'),
+      objective: z.enum(['APP_INSTALLS', 'CATALOG_SALES', 'CLICKS', 'CONVERSIONS', 'IMPRESSIONS', 'LEAD_GENERATION', 'VIDEO_VIEWABLE_IMPRESSIONS']).optional().describe('default CLICKS'),
+      bidType: z.enum(['CPC', 'CPM', 'CPV', 'CPV6']).optional().describe('default CPC — must fit the campaign objective'),
+      bidStrategy: z.enum(['BIDLESS', 'MANUAL_BIDDING', 'MAXIMIZE_VOLUME', 'TARGET_CPX']).optional(),
+      goalType: z.enum(['DAILY_SPEND', 'LIFETIME_SPEND']).optional(),
+      startTime: z.string().optional(),
+      endTime: z.string().optional(),
+      currency: z.string().optional(),
+      targeting: z.any().optional(),
+    },
+    outputSchema: { minBid: z.number().optional(), suggestedBid: z.number().optional(), suggestedRange: z.any().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/reddit-ads/bid-suggestion', a);
+    return ok(d.note, d);
+  }));
+  server.registerTool('list_reddit_ads_posts', {
+    title: 'List a Reddit profile’s ad posts',
+    description: 'List the POSTS on a Reddit profile — these are the creatives Reddit ads promote. Use it to find an existing post to advertise rather than creating a near-duplicate. Call list_reddit_ads_profiles first for redditProfileId. Read-only, free.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      redditProfileId: z.string().describe('the Reddit profile id (t2_…) from list_reddit_ads_profiles'),
+      type: z.enum(['TEXT', 'IMAGE', 'VIDEO', 'CAROUSEL']).optional(),
+      limit: z.number().optional(),
+    },
+    outputSchema: { count: z.number().optional(), posts: z.array(z.any()).optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/reddit-ads/posts', a);
+    return ok(`${d.note}\n${(d.posts || []).map(p => `• ${p.type} "${p.headline}" (${p.id})`).join('\n')}`, d);
+  }));
+  server.registerTool('create_reddit_ads_post', {
+    title: 'Create the Reddit post an ad will promote',
+    description: 'Create the CREATIVE for a Reddit ad. This is the step people skip: a Reddit ad has no creative of its own — it points at a post — so a campaign and ad group with no post behind them can never serve. Types are TEXT (headline + body), IMAGE, VIDEO and CAROUSEL (up to 6 images). For image/video/carousel pass media[] with a PUBLIC mediaUrl; Reddit fetches and validates it itself (minimum 140×140), and a video also needs a thumbnailUrl. The destination for a click rides on the media entry’s destinationUrl, NOT on the ad. Reddit’s call-to-action values are human-readable strings with spaces and capitals — "Learn More", "Shop Now", "Sign Up" — not SCREAMING_SNAKE; the error lists all of them. The post is published on the profile immediately, so show the user the exact headline and body first.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      redditProfileId: z.string().describe('the Reddit profile id (t2_…) to publish as — from list_reddit_ads_profiles'),
+      type: z.enum(['TEXT', 'IMAGE', 'VIDEO', 'CAROUSEL']).optional().describe('default TEXT'),
+      headline: z.string().describe('the post title — this is the ad’s headline'),
+      body: z.string().optional().describe('body copy, TEXT posts'),
+      media: z.array(z.object({
+        mediaUrl: z.string().optional().describe('PUBLIC url of the image/video — Reddit fetches it, minimum 140×140'),
+        destinationUrl: z.string().optional().describe('where a click goes — required for image and carousel posts'),
+        displayUrl: z.string().optional().describe('shown instead of the destination; must be the same domain'),
+        caption: z.string().optional().describe('carousel card caption'),
+        callToAction: z.string().optional().describe('e.g. "Learn More", "Shop Now" — exact human-readable strings'),
+      })).optional().describe('one entry for IMAGE/VIDEO, up to 6 for CAROUSEL'),
+      callToAction: z.string().optional().describe('applies to every media entry that has none'),
+      thumbnailUrl: z.string().optional().describe('required for VIDEO posts'),
+      allowComments: z.boolean().optional().describe('Reddit ads can carry a public comment thread — decide deliberately'),
+    },
+    outputSchema: { id: z.string().optional(), type: z.string().optional(), headline: z.string().optional(), postUrl: z.string().nullable().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/reddit-ads/posts', a);
+    return ok(`${d.note} Pass postId:"${d.id}" to create_reddit_ads_ad.`, d);
+  }));
+  server.registerTool('update_reddit_ads_post', {
+    title: 'Edit a Reddit ad post',
+    description: 'Edit an existing Reddit ad post’s headline, body or comment setting. The post is already public, so an edit is publicly visible — show the user the exact new text first.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      postId: z.string().describe('the post id (t3_…)'),
+      headline: z.string().optional(),
+      body: z.string().optional(),
+      allowComments: z.boolean().optional(),
+    },
+    outputSchema: { id: z.string().optional(), headline: z.string().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/reddit-ads/posts/update', a);
+    return ok(d.note, d);
+  }));
+  server.registerTool('create_reddit_ads_ad_group', {
+    title: 'Create a Reddit ad group (targeting, budget, bidding, schedule)',
+    description: 'Create an ad group under an existing Reddit campaign — this is the tier that holds the budget, the bid and ALL the targeting. ALWAYS created PAUSED; it spends nothing until set_reddit_ads_status(confirm:true). Reddit requires more here than most platforms and refuses the create without it: a bidType, a bidStrategy, a startTime, a budget with its goalType, a bidAmount whenever the bid type is a paid rate, and a conversion pixel (resolved automatically when the ad account has exactly one). THE BID TYPE MUST FIT THE CAMPAIGN’S OBJECTIVE — a CLICKS campaign takes CPC and refuses CPM; Reddit’s error says which. Money is ordinary amounts in the ad account’s currency (micro-currency is handled for you). Resolve community names and interest ids with search_reddit_ads_targeting first, and consider reddit_ads_forecast + reddit_ads_bid_suggestion before committing. Everything is READ BACK from Reddit before you are told it exists — print the returned note verbatim.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      campaignId: z.string().describe('the campaign this ad group belongs to'),
+      name: z.string(),
+      budget: z.number().describe('budget in the ad account’s currency, paired with goalType'),
+      goalType: z.enum(['DAILY_SPEND', 'LIFETIME_SPEND']).optional().describe('default DAILY_SPEND'),
+      bidType: z.enum(['CPC', 'CPM', 'CPV', 'CPV6']).describe('must fit the campaign objective — CLICKS campaigns take CPC'),
+      bidStrategy: z.enum(['BIDLESS', 'MANUAL_BIDDING', 'MAXIMIZE_VOLUME', 'TARGET_CPX']).describe('MANUAL_BIDDING needs bidAmount'),
+      bidAmount: z.number().optional().describe('bid in the ad account’s currency — required for paid bid types; ask reddit_ads_bid_suggestion'),
+      startTime: z.string().describe('ISO 8601, e.g. 2026-08-15T00:00:00Z — Reddit rejects the create without one'),
+      endTime: z.string().optional(),
+      conversionPixelId: z.string().optional().describe('only needed when the ad account has more than one pixel'),
+      optimizationGoal: z.string().optional().describe('cannot be changed later'),
+      targeting: z.object({
+        communities: z.array(z.string()).optional().describe('bare subreddit NAMES, e.g. ["running"] — not t5_ ids, not "r/running"'),
+        excludedCommunities: z.array(z.string()).optional(),
+        geolocations: z.array(z.string()).optional().describe('country codes like ["US"], or ids from search_reddit_ads_targeting'),
+        excludedGeolocations: z.array(z.string()).optional(),
+        interests: z.array(z.string()).optional().describe('interest ids like ["pets_v3"]'),
+        excludedInterests: z.array(z.string()).optional(),
+        keywords: z.array(z.string()).optional(),
+        excludedKeywords: z.array(z.string()).optional(),
+        customAudienceIds: z.array(z.string()).optional(),
+        excludedCustomAudienceIds: z.array(z.string()).optional(),
+        carriers: z.array(z.string()).optional(),
+        languages: z.array(z.string()).optional().describe('e.g. ["EN"]'),
+        platforms: z.array(z.string()).optional().describe('ALL / DESKTOP / MOBILE_NATIVE / MOBILE_WEB — at least one mobile type is expected'),
+        locations: z.array(z.string()).optional().describe('FEED and/or COMMENTS_PAGE'),
+        viewModes: z.array(z.string()).optional().describe('ALL / CARD / CLASSIC / COMPACT / IMMERSIVE'),
+        devices: z.array(z.any()).optional(),
+        gender: z.string().optional().describe('MALE or FEMALE — omit for all'),
+        expandTargeting: z.boolean().optional().describe('let Reddit widen the audience automatically'),
+      }).optional(),
+      schedule: z.array(z.object({
+        startDay: z.number().describe('0 = Sunday … 6 = Saturday'),
+        endDay: z.number(),
+        startHour: z.number().describe('0-23, in the ad group’s time zone'),
+        endHour: z.number(),
+      })).optional().describe('weekly dayparting windows — omit to run all week'),
+    },
+    outputSchema: { id: z.string().optional(), name: z.string().optional(), status: z.string().optional(), effectiveStatus: z.string().optional(), budget: z.number().nullable().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/reddit-ads/ad-groups', a);
+    return ok(`${d.note} To make it spend, use set_reddit_ads_status(confirm:true) after the user approves.`, d);
+  }));
+  server.registerTool('update_reddit_ads_ad_group', {
+    title: 'Edit a Reddit ad group',
+    description: 'Change an existing Reddit ad group’s name, budget, goal type, bid, schedule dates or targeting. Budget and bid are ordinary amounts in the ad account’s currency. Targeting is REPLACED by what you pass, not merged — send the whole set you want. This does NOT activate or pause anything; use set_reddit_ads_status for that. The result is read back from Reddit.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      adGroupId: z.string(),
+      name: z.string().optional(),
+      budget: z.number().optional(),
+      goalType: z.enum(['DAILY_SPEND', 'LIFETIME_SPEND']).optional(),
+      bidAmount: z.number().optional(),
+      bidType: z.enum(['CPC', 'CPM', 'CPV', 'CPV6']).optional(),
+      bidStrategy: z.enum(['BIDLESS', 'MANUAL_BIDDING', 'MAXIMIZE_VOLUME', 'TARGET_CPX']).optional(),
+      startTime: z.string().optional(),
+      endTime: z.string().optional(),
+      targeting: z.any().optional().describe('same shape as create_reddit_ads_ad_group — REPLACES the existing targeting'),
+      schedule: z.array(z.any()).optional(),
+    },
+    outputSchema: { id: z.string().optional(), name: z.string().optional(), status: z.string().optional(), budget: z.number().nullable().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/reddit-ads/ad-groups/update', a);
+    return ok(d.note, d);
+  }));
+  server.registerTool('create_reddit_ads_ad', {
+    title: 'Create a Reddit ad',
+    description: 'Create the ad itself — the object that binds a POST (the creative) to an AD GROUP (the targeting and budget). Create the post first with create_reddit_ads_post and pass its id as postId; without a post there is nothing to show. ALWAYS created PAUSED, and Reddit additionally has to APPROVE it, so a fresh ad reports effective status PENDING_APPROVAL — report that rather than calling it live. GOTCHA: a TEXT ("free form") post’s ad may not carry clickUrl at all — Reddit refuses it. The click destination for image and link ads lives on the POST’s media destinationUrl, not here.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      adGroupId: z.string().describe('the ad group whose targeting and budget this ad runs under'),
+      name: z.string(),
+      postId: z.string().describe('the post to promote (t3_…) from create_reddit_ads_post or list_reddit_ads_posts'),
+      clickUrl: z.string().optional().describe('leave unset for TEXT-post ads — Reddit rejects "Free form ads cannot have a click url"'),
+      redditProfileId: z.string().optional().describe('the post author profile — required for catalog sales campaigns'),
+      eventTrackers: z.array(z.object({ type: z.enum(['CLICK', 'VIEW']), url: z.string() })).optional().describe('third-party measurement URLs; only Reddit-approved providers are accepted'),
+    },
+    outputSchema: { id: z.string().optional(), name: z.string().optional(), status: z.string().optional(), effectiveStatus: z.string().optional(), postId: z.string().nullable().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/reddit-ads/ads', a);
+    return ok(`${d.note} To make it spend, use set_reddit_ads_status(confirm:true) after the user approves.`, d);
+  }));
+  server.registerTool('update_reddit_ads_ad', {
+    title: 'Edit a Reddit ad',
+    description: 'Rename a Reddit ad, point it at a different post, or change its click url. Does not activate or pause it — use set_reddit_ads_status. Swapping the post changes what people see, so confirm the new creative with the user first. The result is read back from Reddit.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      adId: z.string(),
+      name: z.string().optional(),
+      postId: z.string().optional().describe('promote a different post'),
+      clickUrl: z.string().optional().describe('pass an empty string to clear it'),
+    },
+    outputSchema: { id: z.string().optional(), name: z.string().optional(), status: z.string().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/reddit-ads/ads/update', a);
+    return ok(d.note, d);
+  }));
+  server.registerTool('update_reddit_ads_campaign', {
+    title: 'Edit a Reddit campaign',
+    description: 'Change an existing Reddit campaign’s name, spend cap, budget, goal type or flight dates. Amounts are ordinary numbers in the ad account’s currency. This does NOT activate, pause or archive anything — use set_reddit_ads_status for that. The result is read back from Reddit before you are told it took.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      campaignId: z.string(),
+      name: z.string().optional(),
+      spendCap: z.number().optional().describe('lifetime spend ceiling in the ad account’s currency'),
+      budget: z.number().optional(),
+      goalType: z.enum(['DAILY_SPEND', 'LIFETIME_SPEND']).optional(),
+      startTime: z.string().optional(),
+      endTime: z.string().optional(),
+    },
+    outputSchema: { id: z.string().optional(), name: z.string().optional(), status: z.string().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: false, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/reddit-ads/campaign/update', a);
+    return ok(d.note, d);
+  }));
+  server.registerTool('set_reddit_ads_status', {
+    title: 'Activate, pause, archive or delete a Reddit campaign / ad group / ad',
+    description: 'The one switch that arms real money on Reddit, and the only way to retire anything. Pass kind ("campaign", "ad_group" or "ad") plus the object id. ACTIVE starts real spend as soon as Reddit approves — show the user exactly what will run and get an explicit yes, then call again with confirm:true. PAUSED is always safe and never gated. REDDIT HAS NO DELETE OPERATION: removal is a status. ARCHIVED retires an object and works immediately; DELETED is permanent AND time-gated — Reddit refuses to delete anything modified in the last 3 hours, so prefer ARCHIVED and only reach for DELETED when the user truly wants it gone. Both ARCHIVED and DELETED are confirm-gated. Remember Reddit’s three tiers all have to be ACTIVE for a single impression to serve: activating the campaign alone does nothing if its ad group and ad are still paused. The resulting status is READ BACK from Reddit.',
+    inputSchema: {
+      adAccountId: z.string().optional(),
+      kind: z.enum(['campaign', 'ad_group', 'ad']),
+      id: z.string(),
+      status: z.enum(['ACTIVE', 'PAUSED', 'ARCHIVED', 'DELETED']).describe('ACTIVE = start spending; PAUSED = stop; ARCHIVED = retire; DELETED = permanent, and blocked for 3h after any change'),
+      confirm: z.boolean().optional().describe('REQUIRED true for ACTIVE (real spend), ARCHIVED and DELETED'),
+    },
+    outputSchema: { id: z.string().optional(), kind: z.string().optional(), name: z.string().optional(), status: z.string().optional(), effectiveStatus: z.string().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/reddit-ads/status', a);
+    return ok(d.note, d);
+  }));
+
   // ══ LINKEDIN COMPANY PAGES + ADS (2026-07-30) ══════════════════════════════════════════════════════════════
   server.registerTool('list_linkedin_pages', {
     title: 'List the LinkedIn company Pages this account administers',

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hermoso",
-  "version": "0.1.23",
+  "version": "0.1.24",
   "mcpName": "io.github.hermoso-ai/hermoso",
-  "description": "Generate finished VIDEO ADS, image ads and UGC avatar ads for any brand with AI \u2014 and spy on competitor ads across the Meta, Google and LinkedIn ad libraries plus TikTok/Instagram/YouTube organic. MCP server, CLI and Claude skills for Hermoso, the AI ad studio: brand onboarding, 30+ image/video models, finished-ad pipeline (script, voiceover, music, brand end card), ad scoring and competitor teardowns.",
+  "description": "Generate finished VIDEO ADS, image ads and UGC avatar ads for any brand with AI — spy on competitor ads across the Meta, Google and LinkedIn ad libraries plus TikTok/Instagram/YouTube organic — then publish to Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn and Pinterest and build & manage the ad campaigns behind them on Meta, Google Ads, LinkedIn, Pinterest, Microsoft Advertising and ChatGPT Ads. MCP server (205 tools), CLI and Claude skills for Hermoso, the AI ad studio: brand onboarding, 30+ image/video models, finished-ad pipeline (script, voiceover, music, brand end card), ad scoring and competitor teardowns.",
   "type": "module",
   "bin": {
     "hermoso": "bin/hermoso.mjs"
@@ -24,12 +24,15 @@
     "claude",
     "cli",
     "competitor-analysis",
+    "google-ads",
     "image-generation",
     "marketing",
     "mcp",
     "mcp-server",
+    "meta-ads",
     "model-context-protocol",
     "seedance",
+    "social-media-publishing",
     "ugc",
     "veo",
     "video-ads",