hermoso 0.1.209 → 0.1.211

package/README.md

@@ -5,7 +5,7 @@ scripts. Research the ads already winning in a market, generate finished image &
 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.
 
-**791 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
+**795 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.
 
 **What it connects to.** Ad platforms: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads,
@@ -171,7 +171,7 @@ block entirely if you signed in above; it is there for CI, where the process can
 
 Then ask your agent: *“Generate an image ad with Hermoso.”*
 
-### What the 791 tools cover
+### What the 795 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

package/mcp/tools.mjs

@@ -2103,7 +2103,7 @@ const makeEnableToolsHandler = (ctx) => async ({ groups }) => {
       // THE GROUP FLIP MUST NOT UNDO THE CONNECTOR GATE (2026-08-26). Enabling a group is a statement about SIZE —
       // "I am willing to carry these schemas" — not a claim that the workspace has connected eleven ad platforms.
       // A blind `h.enable()` here would have re-listed every tool applyToolGates had just held back, so the saving
-      // would survive exactly until the first `enable_tools(['ads'])`. Counted, not silently skipped: the reply
+      // would survive exactly until the first `enable_tools(["ads"])`. Counted, not silently skipped: the reply
       // says how many and why, because a group that turns on "8 tools" when the agent expected 240 with no
       // explanation is the [[prompt-rosters-go-stale]] failure — the agent concludes the capability is missing.
       if (toolHeldBackByConnectors(name, ctx.conn)) { heldBack++; continue; }
@@ -3474,6 +3474,78 @@ function buildTools(rawServer, opts = {}, sink = null) {
     return ok(`${d.summary}${d.note ? ` ${d.note}` : ''}`, d);
   }));
 
+  // INSTAGRAM AUDIO + COLLAB INVITES (2026-09-06) — Instagram's 2026 changelog, on permissions already held. The
+  // audio one is the reason to care: everything it returns is music Instagram has cleared for third-party use, i.e.
+  // safe under a Reel. The invite pair is the OTHER direction from instagram_collaborators — a creator tagged the
+  // brand, and the post reaches the brand's profile only when the brand accepts, which no agent could do before.
+  server.registerTool('search_instagram_audio', {
+    title: 'Trending or searched Instagram audio',
+    description: 'Audio the brand may legally put under a Reel — music or original sound — with title, artist, length, whether it is eligible for ads, a preview link and a download link. Omit the query for what is TRENDING right now; pass one to search. Everything returned is audio Instagram has authorized for third-party use. Download links expire after roughly 1.5 days. Read-only, free.',
+    inputSchema: {
+      audioType: z.enum(['music', 'original_sound']).optional().describe('default music'),
+      query: z.string().optional().describe('omit for trending audio'),
+      limit: z.number().optional().describe('1–50, default 15'),
+      account: z.string().optional().describe('which Instagram account — an @handle or id from list_connector_accounts("instagram"); omit for the one Page-linked account'),
+      pageId: z.string().optional().describe('Facebook Page id — omit when only one Page is connected'),
+    },
+    outputSchema: { instagramId: z.string().optional(), kind: z.string().optional(), query: z.string().nullable().optional(), trending: z.boolean().optional(), count: z.number().optional(), audio: z.array(z.any()).optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/instagram/audio', { audioType: a.audioType, query: a.query, limit: a.limit, account: a.account, pageId: a.pageId });
+    if (!d.count) return ok(`Instagram returned no ${d.kind === 'music' ? 'tracks' : 'original sounds'}${d.trending ? ' for trending' : ` for "${d.query}"`}.`, d);
+    return ok(`${d.count} ${d.kind === 'music' ? 'track' : 'original sound'}(s)${d.trending ? ' trending' : ` for “${d.query}”`}:\n${d.audio.map(x => `• ${x.title || '(untitled)'} — ${x.artist || '—'}${x.seconds != null ? ` · ${x.seconds}s` : ''}${x.adsEligible ? ' · ads-eligible' : ''} · id ${x.id}${x.preview ? ` · ${x.preview}` : ''}`).join('\n')}\n${d.note}`, d);
+  }));
+
+  server.registerTool('list_instagram_collab_invites', {
+    title: 'Collab invites waiting on the brand',
+    description: 'Posts where a creator tagged this Instagram account as a COLLABORATOR and is waiting for an answer. The post appears on the brand’s profile only once the brand accepts, and Instagram sends no notification here, so this list is the only way to see them. Answer each with respond_instagram_collab_invite. Read-only, free. Instagram allows 300 reads per account per day.',
+    inputSchema: {
+      limit: z.number().optional().describe('1–100, default 25'),
+      after: z.string().optional().describe('cursor from a previous page'),
+      account: z.string().optional().describe('which Instagram account — @handle or id; omit for the one Page-linked account'),
+      pageId: z.string().optional().describe('Facebook Page id — omit when only one Page is connected'),
+    },
+    outputSchema: { instagramId: z.string().optional(), count: z.number().optional(), invites: z.array(z.any()).optional(), cursor: z.string().nullable().optional() },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/instagram/collab-invites', { limit: a.limit, after: a.after, account: a.account, pageId: a.pageId });
+    if (!d.count) return ok('No collab invites are waiting on this Instagram account.', d);
+    return ok(`${d.count} collab invite(s) waiting:\n${d.invites.map(i => `• from @${i.from || '?'} — ${String(i.caption || '(no caption)').replace(/\s+/g, ' ').slice(0, 90)} · media ${i.mediaId}`).join('\n')}\nAnswer each with respond_instagram_collab_invite(mediaId, accept:true|false).`, d);
+  }));
+
+  server.registerTool('respond_instagram_collab_invite', {
+    title: 'Accept or decline a collab invite',
+    description: 'Answer a collab invite from list_instagram_collab_invites. accept:true makes this account a co-author and the creator’s post appears on its profile; accept:false declines. `accept` is REQUIRED — never guess which way the user wants it. The reply is read back from Instagram (the invite leaves the pending list), not taken from the vendor’s 200. Free. Instagram allows 50 answers per account per day.',
+    inputSchema: {
+      mediaId: z.string().describe('the media id from list_instagram_collab_invites'),
+      accept: z.boolean().describe('true = accept and co-author the post; false = decline'),
+      account: z.string().optional().describe('which Instagram account — @handle or id; omit for the one Page-linked account'),
+      pageId: z.string().optional().describe('Facebook Page id — omit when only one Page is connected'),
+    },
+    outputSchema: { mediaId: z.string().optional(), accepted: z.boolean().optional(), vendorSuccess: z.boolean().optional(), confirmed: z.boolean().optional(), summary: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/instagram/collab-invites/respond', { mediaId: a.mediaId, accept: a.accept, account: a.account, pageId: a.pageId });
+    return ok(d.summary, d);
+  }));
+
+  server.registerTool('list_instagram_collab_media', {
+    title: 'Posts this account co-authors',
+    description: 'Every collaborative post this Instagram account is a co-author on — who posted it, and the COMBINED engagement across all co-authors (total likes and comments, plus saves, shares and reposts where Instagram provides them). Read-only, free.',
+    inputSchema: {
+      limit: z.number().optional().describe('1–100, default 25'),
+      after: z.string().optional().describe('cursor from a previous page'),
+      account: z.string().optional().describe('which Instagram account — @handle or id; omit for the one Page-linked account'),
+      pageId: z.string().optional().describe('Facebook Page id — omit when only one Page is connected'),
+    },
+    outputSchema: { instagramId: z.string().optional(), count: z.number().optional(), media: z.array(z.any()).optional(), cursor: z.string().nullable().optional() },
+    annotations: { readOnlyHint: true, destructiveHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/instagram/collab-media', { limit: a.limit, after: a.after, account: a.account, pageId: a.pageId });
+    if (!d.count) return ok('This Instagram account is not a co-author on any collaborative post.', d);
+    return ok(`${d.count} collaborative post(s):\n${d.media.map(m => `• [${m.mediaKind}] with @${m.by || '?'} — ${String(m.caption || '(no caption)').replace(/\s+/g, ' ').slice(0, 70)} — ${m.totalLikes ?? m.likes ?? '—'} likes, ${m.totalComments ?? m.comments ?? '—'} comments${m.saves != null ? `, ${m.saves} saves` : ''}${m.shares != null ? `, ${m.shares} shares` : ''} · ${m.url || m.id}`).join('\n')}`, d);
+  }));
+
   server.registerTool('list_meta_comments', {
     title: 'Read comments on a Meta post',
     description: 'Read the comments under a Facebook Page post or Instagram media object — customer questions, objections and the exact language real people use about the product. Good raw material for ad copy, and the first step before replying or moderating. REPLIES: a reply is a comment ON a comment, and its id exists only under its PARENT — it is never returned by the post. Each row says how many replies it has; to read them (and to get the id reply_to_meta_comment / moderate_meta_comment need), call this tool again with postId set to that COMMENT id.',
@@ -6132,7 +6204,7 @@ function buildTools(rawServer, opts = {}, sink = null) {
   }));
   server.registerTool('reply_to_meta_message', {
     title: 'Reply to a Messenger / Instagram DM',
-    description: 'Send a text reply to someone who has messaged the brand. THIS REACHES A REAL PERSON — show the user the exact text and who it goes to, get a yes, then send. Pass `conversationId` as well as `recipientId` and Hermoso checks Meta’s 24-hour window for free BEFORE sending, and refuses with the real reason instead of letting Meta refuse it; without one it sends and discloses that the window could not be checked. HERMOSO SENDS REPLIES ONLY: messaging_type is always RESPONSE, and proactive messages and message tags are not offered at all — that is a deliberate product boundary, not a gap, and a closed window is a RULE that only the person writing again reopens. `recipientId` is a PAGE-SCOPED ID on Messenger and an INSTAGRAM-SCOPED ID on Instagram (read_meta_conversation returns it as `replyTo`); a username or a handle is not one and cannot be turned into one. ACCEPTED IS NOT DELIVERED — never report it as delivered or read. 0 credits.',
+    description: 'Send a text reply to someone who has messaged the brand. THIS REACHES A REAL PERSON — show the user the exact text and who it goes to, get a yes, then send. Pass `conversationId` as well as `recipientId` and Hermoso checks Meta’s 24-hour window for free BEFORE sending, and refuses with the real reason instead of letting Meta refuse it; without one it sends and discloses that the window could not be checked. HERMOSO SENDS REPLIES ONLY: messaging_type is always RESPONSE, and proactive messages and message tags are not offered at all — that is a deliberate product boundary, not a gap. THE ONE PROACTIVE THING MESSENGER ALLOWS IS A MARKETING-MESSAGES SUBSCRIPTION: to ask a person in the inbox to SUBSCRIBE to marketing messages, call request_messenger_optin (Meta’s own opt-in template, in the ads group — enable_tools(["ads"]) or find_tools if it is not in your list). Never answer that with a plain-text reply asking them to say YES, and never say the capability does not exist. And a closed window is a RULE that only the person writing again reopens. `recipientId` is a PAGE-SCOPED ID on Messenger and an INSTAGRAM-SCOPED ID on Instagram (read_meta_conversation returns it as `replyTo`); a username or a handle is not one and cannot be turned into one. ACCEPTED IS NOT DELIVERED — never report it as delivered or read. 0 credits.',
     inputSchema: {
       recipientId: z.string().describe('the PSID (Messenger) or IGSID (Instagram) to reply to — `replyTo` from read_meta_conversation'),
       text: z.string().describe('the reply'),
@@ -9498,7 +9570,7 @@ function buildTools(rawServer, opts = {}, sink = null) {
     title: z.string().describe('the headline — 3 to 50 characters, enforced'),
     body: z.string().describe('the description under the headline — 100 characters maximum, enforced'),
     targetUrl: z.string().describe('the landing page (must not block OAI-AdsBot / OAI-SearchBot in robots.txt)'),
-    imageUrl: z.string().optional().describe('public https URL of a STILL image — a video URL is refused, this channel has no video format'),
+    imageUrl: z.string().optional().describe('public https URL of a STILL image — REQUIRED on every text ad (ChatGPT Ads refuses an ad with no creative.file_id unless the campaign is a product feed; measured 2026-09-06); a video URL is refused, this channel has no video format'),
     price: z.string().optional().describe('optional price string shown on the card'),
   });
   server.registerTool('list_openai_ads_campaigns', {
@@ -18111,7 +18183,7 @@ function memoryNoteVerdict(text) {
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
   }, wrap(async (a) => {
     const d = await apiPost('/api/posts/collect', { ...(a.includeMetered ? { includeMetered: true } : {}), ...(a.max ? { max: a.max } : {}) });
-    const bits = [`Read ${d.collected} post(s)`, d.couldNotTell ? `${d.couldNotTell} could NOT be read (that is "could not tell", not zero engagement)` : null, d.remaining ? `${d.remaining} still due — call again` : null, d.meteredNote || null].filter(Boolean);
+    const bits = [`Read ${d.collected} post(s)`, d.couldNotTell ? `${d.couldNotTell} could NOT be read (that is "could not tell", not zero engagement)` : null, d.gone ? `${d.gone} no longer exist at the platform (deleted or taken down) and will not be read again` : null, d.remaining ? `${d.remaining} still due — call again` : null, d.meteredNote || null].filter(Boolean);
     return ok(`${bits.join('. ')}.${d.collected ? ' Ask post_performance which hooks are winning.' : ''}`, d);
   }));
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hermoso",
-  "version": "0.1.209",
+  "version": "0.1.211",
   "mcpName": "io.github.hermoso-ai/hermoso",
-  "description": "AI ad studio and marketing MCP server with 791 tools. Research the ads already running in any market, generate finished image, video and UGC avatar ads, publish and schedule them to your own channels, build and manage the ad campaigns behind them, and read what they achieved. AD PLATFORMS: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads, Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads and ChatGPT Ads, plus product feeds in Google Merchant Center. PUBLISHING AND SCHEDULING: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky and Telegram. AD RESEARCH: the Meta, Google and LinkedIn ad libraries plus organic TikTok, Instagram, YouTube, Threads and Reddit. ANALYTICS: Google Analytics 4, Google Search Console and every connected platform's own post and campaign insights. Also brand onboarding, 50+ image and video generation models, ad scoring, competitor teardowns, Google Drive and OneDrive, a CLI and installable Claude skills.",
+  "description": "AI ad studio and marketing MCP server with 795 tools. Research the ads already running in any market, generate finished image, video and UGC avatar ads, publish and schedule them to your own channels, build and manage the ad campaigns behind them, and read what they achieved. AD PLATFORMS: Meta, Google Ads, TikTok Ads, LinkedIn Ads, Reddit Ads, X Ads, Pinterest Ads, Snapchat Ads, Microsoft Advertising, Apple Search Ads and ChatGPT Ads, plus product feeds in Google Merchant Center. PUBLISHING AND SCHEDULING: Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn, Pinterest, Bluesky and Telegram. AD RESEARCH: the Meta, Google and LinkedIn ad libraries plus organic TikTok, Instagram, YouTube, Threads and Reddit. ANALYTICS: Google Analytics 4, Google Search Console and every connected platform's own post and campaign insights. Also brand onboarding, 50+ image and video generation models, ad scoring, competitor teardowns, Google Drive and OneDrive, a CLI and installable Claude skills.",
   "type": "module",
   "bin": {
     "hermoso": "bin/hermoso.mjs"