hermoso 0.1.87 → 0.1.89

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.
 
-**415 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
+**420 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.
 
 **It is not all-or-nothing.** Research, creation, publishing/scheduling and ads management are four *independent*
@@ -53,7 +53,7 @@ Cursor / Codex — add to `mcp.json` (Codex uses the TOML equivalent):
 
 Then ask your agent: *“Generate an image ad with Hermoso.”*
 
-### What the 415 tools cover
+### What the 420 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

@@ -1652,12 +1652,18 @@ export function registerTools(rawServer, opts = {}) {
   // HTTP route and the in-app agent call.
   server.registerTool('retry_scheduled', {
     title: 'Retry a failed scheduled post',
-    description: 'Send a post that FAILED again. A scheduled post fans out across its channels INDEPENDENTLY, so a failure is usually PARTIAL — LinkedIn 401s while Instagram published fine — and this re-fires ONLY the channels that did not succeed by default (list_scheduled reports them as `retryable`). It re-queues the same content as a NEW post that goes out RIGHT AWAY — the queue picks it up on its next pass, within seconds — and the original keeps its failure record so the history still shows what went wrong. Naming a channel that already published is REFUSED rather than quietly posting a second time. Two independent belts stop a double-post: a channel that genuinely published can only REPLAY (nothing is posted), and a channel whose outcome is UNRESOLVED — the platform timed out and may be holding the post — refuses with that reason instead of guessing. Retry after fixing the cause: reconnecting the account, picking a board, shortening the caption. To send the same thing again ON PURPOSE, use duplicate_scheduled.',
+    description: 'Send a post that FAILED again. A scheduled post fans out across its channels INDEPENDENTLY, so a failure is usually PARTIAL — LinkedIn 401s while Instagram published fine — and this re-fires ONLY the channels that did not succeed by default (list_scheduled reports them as `retryable`). It re-queues the same content as a NEW post that goes out RIGHT AWAY — the queue picks it up on its next pass, within seconds — and the original keeps its failure record so the history still shows what went wrong. Naming a channel that already published is REFUSED rather than quietly posting a second time. Two independent belts stop a double-post: a channel that genuinely published can only REPLAY (nothing is posted), and a channel whose outcome is UNRESOLVED — the platform timed out and may be holding the post — refuses with that reason instead of guessing. Retry after fixing the cause — and you can fix it IN THIS CALL: pass `boardId`, `pageId`, `linkedinOrganizationId`, `locationId`, `message` or `captions` to correct the value that failed, and the corrected post is re-validated exactly like a fresh schedule. That matters because the commonest cause is a field, not an outage: a Pin aimed at the wrong board fails identically however many times it is re-sent. Anything you do not name is copied from the original. To send the same thing again ON PURPOSE, use duplicate_scheduled.',
     inputSchema: {
       id: z.string().describe('the scheduled post id from list_scheduled'),
       channels: z.array(z.enum(['facebook', 'instagram', 'threads', 'tiktok', 'youtube', 'linkedin', 'x', 'pinterest', 'google_business'])).optional().describe('retry only these channels (default: every channel that did not publish)'),
       at: z.string().optional().describe('hold the retry until a later time — ISO timestamp or epoch milliseconds. Leave it out to retry immediately, which is almost always what you want. A time you name here must be at least a minute from now, exactly like any other scheduled post.'),
       allowDuplicate: z.boolean().optional().describe('ONLY for a channel you have checked by hand and confirmed the post is genuinely NOT there. It bypasses the double-post protection and can publish a second public copy, so never set it to work around a refusal you have not investigated.'),
+      boardId: z.string().optional().describe('CORRECT THE BOARD on retry — the Pinterest board the Pin goes on, from list_pinterest_boards. A Pin aimed at a board Pinterest refuses fails the same way on every retry until this is changed.'),
+      pageId: z.string().optional().describe('CORRECT THE PAGE on retry — which connected Facebook Page (and its linked Instagram/Threads) publishes, from list_meta_pages.'),
+      linkedinOrganizationId: z.string().optional().describe('CORRECT THE LINKEDIN AUTHOR on retry — the company Page id from list_linkedin_pages. Set it to an empty string to fall back to the personal profile.'),
+      locationId: z.string().optional().describe('CORRECT THE LISTING on retry — which Google Business Profile location, e.g. "locations/123" from list_business_locations.'),
+      message: z.string().optional().describe('CORRECT THE CAPTION on retry — use this when the original was refused for length or content. Anything not named here is copied from the original post.'),
+      captions: z.record(z.string()).optional().describe('CORRECT ONE CHANNEL’S CAPTION on retry, e.g. { "x": "..." } when only that channel refused the text.'),
     },
     outputSchema: { id: z.string().optional(), at: z.string().optional(), channels: z.array(z.string()).optional(), retryOf: z.string().optional(), retrying: z.array(z.string()).optional(), alreadyPublished: z.array(z.string()).optional(), note: z.string().optional() },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
@@ -4508,6 +4514,65 @@ export function registerTools(rawServer, opts = {}) {
     outputSchema: { campaignId: z.string().nullable().optional(), lineItemId: z.string().nullable().optional(), status: z.string().optional(), parentStatus: z.string().nullable().optional(), note: z.string().optional() },
     annotations: { openWorldHint: true },
   }, wrap(async (a) => { const d = await apiPost('/api/x-ads/status', a); return ok(d.note, d); }));
+  // ── APPLE ADS (Apple Search Ads) — READ-ONLY (2026-08-14) ──────────────────────────────────────────────────────
+  // Every description says read-only in its own words, because an agent that believes it can build a campaign here
+  // will try, fail, and the user will blame Hermoso ([[prompt-rosters-go-stale]]). When write tools land, these
+  // sentences move with them.
+  server.registerTool('list_apple_ads_campaigns', {
+    title: 'List Apple Ads campaigns',
+    description: 'Read the brand’s connected Apple Ads (Apple Search Ads) campaigns — App Store search ads. Each row carries status, servingStatus, daily and total budget, the countries it runs in and, when a campaign cannot run, servingStateReasons stating exactly why. Read-only, free, zero spend risk. Needs Apple Ads connected (Settings ▸ Connectors ▸ Apple Ads): there is no OAuth — Hermoso generates an EC signing key, the user pastes the public half into Apple Ads ▸ Account Settings ▸ API and pastes back clientId / teamId / keyId. Hermoso CANNOT create or edit Apple Ads campaigns — never offer that.',
+    inputSchema: {
+      limit: z.number().optional().describe('page size, default 100, Apple’s max is 1000'),
+      offset: z.number().optional().describe('offset pagination'),
+    },
+    outputSchema: { ok: z.boolean().optional(), level: z.string().optional(), count: z.number().optional(), total: z.number().nullable().optional(), campaigns: z.array(z.any()).optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => { const d = await apiGet('/api/apple-ads/campaigns', a); return ok(`${d.count} Apple Ads campaign(s):\n${d.note}`, d); }));
+  server.registerTool('list_apple_ads_ad_groups', {
+    title: 'List Apple Ads ad groups',
+    description: 'Ad groups inside one Apple Ads campaign — status, servingStatus, default bid, and whether Search Match (Apple’s automated keyword matching) is on. campaignId is REQUIRED: Apple publishes no org-wide ad-group list, so an ad group can only be reached through its campaign. Read-only, free.',
+    inputSchema: {
+      campaignId: z.string().describe('REQUIRED — from list_apple_ads_campaigns'),
+      limit: z.number().optional(), offset: z.number().optional(),
+    },
+    outputSchema: { ok: z.boolean().optional(), level: z.string().optional(), campaignId: z.string().optional(), count: z.number().optional(), total: z.number().nullable().optional(), adGroups: z.array(z.any()).optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => { const d = await apiGet('/api/apple-ads/adgroups', a); return ok(`${d.count} ad group(s) in Apple Ads campaign ${d.campaignId}:\n${d.note}`, d); }));
+  server.registerTool('list_apple_ads_keywords', {
+    title: 'List Apple Ads targeting or negative keywords',
+    description: 'Targeting or negative keywords with their match type, status and bid. Apple splits these four ways and the paths are not interchangeable: TARGETING keywords are listed PER AD GROUP, so pass campaignId AND adGroupId. NEGATIVE keywords (negative:true) exist at campaign level — pass campaignId alone — or per ad group with both ids. Apple allows up to 5000 keywords per ad group. Read-only, free.',
+    inputSchema: {
+      campaignId: z.string().describe('REQUIRED'),
+      adGroupId: z.string().optional().describe('required for TARGETING keywords; optional for negatives'),
+      negative: z.boolean().optional().describe('list negative keywords instead of targeting keywords'),
+      limit: z.number().optional(), offset: z.number().optional(),
+    },
+    outputSchema: { ok: z.boolean().optional(), level: z.string().optional(), campaignId: z.string().optional(), adGroupId: z.string().nullable().optional(), count: z.number().optional(), total: z.number().nullable().optional(), keywords: z.array(z.any()).optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => { const d = await apiGet('/api/apple-ads/keywords', a); return ok(`${d.count} ${d.level === 'negativeKeyword' ? 'negative ' : ''}keyword(s):\n${d.note}`, d); }));
+  server.registerTool('apple_ads_report', {
+    title: 'Apple Ads performance report',
+    description: 'Apple Ads performance — impressions, taps, installs, spend, TTR, CPT, CPA. level is campaign (organization-wide) or adgroup / keyword / searchterm / ad, and every level except campaign REQUIRES campaignId. startTime and endTime are REQUIRED, as YYYY-MM-DD. Apple enforces three interlocking rules and the reply reports back which were applied: with no granularity row totals are forced on; with granularity grand totals are forced off; grouping by a demographic or geo dimension forces BOTH off — so a total of zero can mean "Apple did not return that total", not "no spend". A report with NO rows genuinely means there was NO delivery in that window: say exactly that, and never present zeros as measured performance. Read-only and free, so run it first after connecting — it proves the credentials work with zero spend risk.',
+    inputSchema: {
+      level: z.enum(['campaign', 'adgroup', 'keyword', 'searchterm', 'ad']).optional().describe('default campaign'),
+      campaignId: z.string().optional().describe('REQUIRED for every level except campaign'),
+      startTime: z.string().describe('YYYY-MM-DD (required)'),
+      endTime: z.string().describe('YYYY-MM-DD (required)'),
+      granularity: z.enum(['HOURLY', 'DAILY', 'WEEKLY', 'MONTHLY']).optional(),
+      groupBy: z.array(z.string()).optional().describe('adminArea, ageRange, countryCode, countryOrRegion, deviceClass, gender, locality'),
+      timeZone: z.enum(['ORTZ', 'UTC']).optional().describe('ORTZ = the organization time zone, Apple’s default'),
+      limit: z.number().optional(),
+    },
+    outputSchema: { ok: z.boolean().optional(), level: z.string().optional(), startTime: z.string().optional(), endTime: z.string().optional(), count: z.number().optional(), rows: z.array(z.any()).optional(), grandTotals: z.any().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => { const d = await apiPost('/api/apple-ads/report', a); return ok(`${d.note}\n${JSON.stringify((d.rows || []).slice(0, 40))}`, d); }));
+  server.registerTool('list_apple_ads_orgs', {
+    title: 'List Apple Ads organizations',
+    description: 'The Apple Ads organizations these credentials can act as, with each one’s currency, time zone, payment model and the API roles held. Apple treats an orgId like a CAMPAIGN GROUP, so one login can cover several — an agency managing multiple clients has one per client. Reading this does NOT switch organization: Apple Ads is pinned to the ONE organization chosen when the connection was made, so an agent can never act as another client’s campaign group. To use a different one, reconnect Apple Ads and name it there. A payment model of null is worth reporting: Apple states that without one, campaigns cannot run. Read-only, free.',
+    inputSchema: {},
+    outputSchema: { ok: z.boolean().optional(), active: z.string().nullable().optional(), count: z.number().optional(), orgs: z.array(z.any()).optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async () => { const d = await apiGet('/api/apple-ads/orgs', {}); return ok(d.note, d); }));
   // ── X: managing what you built — update, remove, and the reads both depend on (2026-08-05) ────────────────────
   // Hermoso could build an X campaign and activate it and then change NOTHING about it, and could remove nothing at
   // all: X was the eighth ad platform in the product and the only one with no removal path. Every field offered

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hermoso",
-  "version": "0.1.87",
+  "version": "0.1.89",
   "mcpName": "io.github.hermoso-ai/hermoso",
-  "description": "AI ad studio + marketing MCP (415 tools): build and manage ad campaigns on Meta, Google Ads, Reddit, X, TikTok, Snapchat, LinkedIn, Pinterest, Microsoft Advertising and ChatGPT Ads — generate finished video, image and UGC avatar ads, publish them to Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn and Pinterest, spy on competitor ads across the Meta, Google and LinkedIn ad libraries plus organic TikTok/Instagram/YouTube/Reddit, and read what they achieved in Google Analytics 4. 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": "AI ad studio + marketing MCP (420 tools): build and manage ad campaigns on Meta, Google Ads, Reddit, X, TikTok, Snapchat, LinkedIn, Pinterest, Microsoft Advertising and ChatGPT Ads \u2014 generate finished video, image and UGC avatar ads, publish them to Facebook, Instagram, Threads, TikTok, YouTube, X, LinkedIn and Pinterest, spy on competitor ads across the Meta, Google and LinkedIn ad libraries plus organic TikTok/Instagram/YouTube/Reddit, and read what they achieved in Google Analytics 4. 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"