hermoso 0.1.112 → 0.1.114

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.
 
-**519 tools.** `tools/list` is always the authoritative set; `hermoso_capabilities` (free) returns the live model
+**522 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 519 tools cover
+### What the 522 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

@@ -2241,13 +2241,21 @@ export function registerTools(rawServer, opts = {}) {
   }));
   server.registerTool('x_post_metrics', {
     title: 'Read performance of a post on X',
-    description: 'Read the PUBLIC metrics of a post on X — impressions, likes, reposts, replies, quotes and bookmarks — to judge whether a hook landed before spending more behind it. For the advertiser numbers (link clicks, video views, profile visits) use x_post_insights instead. Costs a small number of credits (X bills per API read). Needs X connected.',
-    inputSchema: { id: z.string().describe('the numeric X post id — the last part of the post URL') },
-    outputSchema: { id: z.string().optional(), text: z.string().optional(), postedAt: z.string().nullable().optional(), url: z.string().optional(), impressions: z.number().nullable().optional(), likes: z.number().nullable().optional(), reposts: z.number().nullable().optional(), replies: z.number().nullable().optional(), quotes: z.number().nullable().optional(), bookmarks: z.number().nullable().optional(), costCredits: z.number().optional() },
+    description: "THE X ANALYTICS TOOL THAT WORKS — impressions, likes, reposts, replies, quotes and bookmarks for any post, PLUS the advertiser numbers (link clicks, profile clicks, engagements) for YOUR OWN posts published in the last 30 days. X serves those private metrics on this same lookup with the user-context connection you already have; that is X's own design, not a workaround. Prefer this over x_post_insights, whose endpoint family X has retired. If a post is deleted, protected or suspended, X answers with no data at all and this says so — that is MISSING DATA, never zero engagement, and must never be reported as a measured zero. Costs a small number of credits (X bills per API read). Needs X connected.",
+    inputSchema: {
+      id: z.string().describe('the numeric X post id — the last part of the post URL'),
+      publishedAt: z.number().optional().describe('epoch ms the post went out, if known — lets the private owned-post metrics be requested only inside X\'s 30-day window instead of costing a refused call'),
+    },
+    outputSchema: { id: z.string().optional(), found: z.boolean().optional(), note: z.string().optional(), text: z.string().optional(), postedAt: z.string().nullable().optional(), url: z.string().optional(), impressions: z.number().nullable().optional(), likes: z.number().nullable().optional(), reposts: z.number().nullable().optional(), replies: z.number().nullable().optional(), quotes: z.number().nullable().optional(), bookmarks: z.number().nullable().optional(), urlClicks: z.number().nullable().optional(), profileClicks: z.number().nullable().optional(), engagements: z.number().nullable().optional(), organicImpressions: z.number().nullable().optional(), organicLikes: z.number().nullable().optional(), privateMetrics: z.boolean().optional(), costCredits: z.number().optional() },
     annotations: { readOnlyHint: true, openWorldHint: true },
   }, wrap(async (a) => {
-    const d = await apiGet('/api/x/metrics', { id: a.id });
-    return ok(`${d.impressions ?? '?'} impressions, ${d.likes ?? '?'} likes, ${d.reposts ?? '?'} reposts, ${d.replies ?? '?'} replies — ${d.url}`, d);
+    const d = await apiGet('/api/x/metrics', { id: a.id, publishedAt: a.publishedAt });
+    // The private half is reported only when X actually served it — an absent link-click count means "outside the
+    // 30-day window or not your post", which is not zero clicks and must not be printed as a number.
+    const priv = d.privateMetrics
+      ? ` · ${d.urlClicks ?? '?'} link clicks, ${d.profileClicks ?? '?'} profile clicks, ${d.engagements ?? '?'} engagements`
+      : '';
+    return ok(`${d.impressions ?? '?'} impressions, ${d.likes ?? '?'} likes, ${d.reposts ?? '?'} reposts, ${d.replies ?? '?'} replies${priv} — ${d.url}`, d);
   }));
   server.registerTool('x_post_insights', {
     title: 'Advertiser analytics for your own posts on X',
@@ -3750,6 +3758,63 @@ export function registerTools(rawServer, opts = {}) {
     const d = await apiGet('/api/merchant/products', { merchantCenterId: a.merchantCenterId, limit: a.limit });
     return ok(`Merchant Center ${d.merchantCenterId}: ${d.count} product(s).\n${JSON.stringify(d.products || []).slice(0, 4000)}`, d);
   }));
+  // ── SHOPIFY: the merchant's own storefront (2026-08-19) ──────────────────────────────────────────────────────
+  // These close the LAST web-only capability in the product. `publish_to_product` existed only inside the Shopify
+  // admin iframe, because its route authenticated with a ~60-second App Bridge JWT no headless caller can mint —
+  // so a merchant driving Hermoso from Claude or Cursor could generate an ad FOR their product and then had to go
+  // click it into the listing by hand. Web-only is the one direction the parity law calls a defect.
+  //
+  // There is deliberately no `shop` parameter on either tool. The store is derived server-side from the verified
+  // account (a Shopify merchant's Hermoso account IS `shopify:<shop>`); accepting one from the caller would be a
+  // forgeable instruction to publish into somebody else's storefront.
+  server.registerTool('list_shopify_products', {
+    title: 'List the Shopify catalog',
+    description: "The merchant's real Shopify products — id, title, description, price, images and storefront URL. This is where the productId for publish_to_shopify_product comes from, and it doubles as ground truth about what the brand actually sells (real titles and real photos, not a guess from the website). Newest-updated first. Only works for accounts created by installing Hermoso from the Shopify App Store. Read-only, free.",
+    inputSchema: {
+      limit: z.number().optional().describe('how many products (1–100, default 24)'),
+      cursor: z.string().optional().describe('pageInfo.endCursor from a previous call, to page further'),
+    },
+    outputSchema: { shop: z.string().optional(), products: z.array(z.any()).optional(), pageInfo: z.any().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/shopify/products', { limit: a.limit, cursor: a.cursor });
+    const list = d.products || [];
+    const lines = list.map((p) => `• ${p.title} — ${p.id}${p.price ? ` (${p.price.currency} ${p.price.min})` : ''}`).join('\n');
+    return ok(`${d.shop}: ${list.length} product(s)${d.pageInfo?.hasNextPage ? ' (more available — pass cursor)' : ''}.\n${lines}`, d);
+  }));
+
+  server.registerTool('publish_to_shopify_product', {
+    title: 'Publish an image onto a Shopify product',
+    description: "Attach a finished image to one of the merchant's Shopify product listings, as product media. Pass productId (from list_shopify_products — the gid://shopify/Product/… form) and a PUBLIC https imageUrl, which is what every Hermoso render returns. Shopify fetches the image server-side and processes it asynchronously, so the media can come back status PROCESSING and appear on the listing a moment later — that is success, not a failure. Only works for accounts created by installing Hermoso from the Shopify App Store. Free — the render was already paid for.",
+    inputSchema: {
+      productId: z.string().describe('gid://shopify/Product/… from list_shopify_products'),
+      imageUrl: z.string().describe('a public https image URL — any Hermoso render URL works'),
+      alt: z.string().optional().describe('alt text for accessibility and SEO; defaults to a generic credit'),
+    },
+    outputSchema: { shop: z.string().optional(), ok: z.boolean().optional(), productId: z.string().optional(), productUrl: z.string().optional(), media: z.any().optional() },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/shopify/publish-to-product', { productId: a.productId, imageUrl: a.imageUrl, alt: a.alt });
+    const st = d.media?.status || 'UNKNOWN';
+    return ok(`Published to ${d.productId} on ${d.shop} — media ${d.media?.id || '?'} is ${st}`
+      + (st === 'PROCESSING' ? ' (Shopify is still processing it; it will appear on the listing shortly).' : '.')
+      + (d.productUrl ? `\nListing: ${d.productUrl}` : ''), d);
+  }));
+
+  server.registerTool('merchant_report', {
+    title: 'Merchant Center reports — competitive visibility, best sellers, price benchmarks',
+    description: "COMPETITOR INTELLIGENCE GOOGLE COMPUTES FOR FREE, for any retail brand with a Merchant Center. Ten report views, read with a SQL-like MCQL query. The three worth reaching for first: `competitive_visibility_competitor_view` (WHICH other domains appear beside this merchant, their rank, page-overlap and higher-position rates — i.e. who is actually beating them), `best_sellers_product_cluster_view` (what is SELLING on Google in a category right now, with an inventory_status saying whether this merchant even stocks it) and `price_insights_product_view` (Google's own suggested price plus the predicted click and conversion change). Also: competitive_visibility_benchmark_view, competitive_visibility_top_merchant_view, best_sellers_brand_view, price_competitiveness_product_view, product_view, product_performance_view, non_product_performance_view.\n\nMCQL IS NOT SQL: no OR, no subqueries, no GROUP BY, no aggregates, no JOIN, and ORDER BY may only name fields already in SELECT. Date filters use `WHERE date BETWEEN '2026-01-01' AND '2026-01-31'` or `WHERE date DURING LAST_30_DAYS`. Several views REQUIRE specific fields in SELECT and in WHERE — competitive visibility needs report_category_id + report_country_code + traffic_source, and top_merchant uniquely REQUIRES a date condition while FORBIDDING date in SELECT. An unknown view is refused by name with the list.\n\nNOT AVAILABLE ON MULTI-CLIENT (MCA) ACCOUNTS — pass a subaccount id. An empty result is often a normal state (price insights are only produced where Google predicts a substantial gain), and the note says which kind of empty it is. Read-only, free, no new permission.",
+    inputSchema: {
+      merchantCenterId: z.string().describe('from list_merchant_accounts — a STANDALONE account or a SUBACCOUNT, never a multi-client (MCA) account'),
+      query: z.string().describe("the MCQL query, e.g. \"SELECT id, title, price, suggested_price, effectiveness FROM price_insights_product_view\""),
+      pageSize: z.number().optional().describe('rows per response, 1–100000 (default 1000). 100,000 is GOOGLE\'s ceiling, not ours.'),
+      pageToken: z.string().optional().describe('nextPageToken from a previous call — resend the IDENTICAL query and pageSize with it, which Google requires'),
+    },
+    outputSchema: { merchantCenterId: z.string().optional(), view: z.string().optional(), count: z.number().optional(), rows: z.array(z.any()).optional(), pageSize: z.number().optional(), truncated: z.boolean().optional(), nextPageToken: z.string().optional(), query: z.string().optional(), note: z.string().optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/merchant/report', { merchantCenterId: a.merchantCenterId, query: a.query, pageSize: a.pageSize, pageToken: a.pageToken });
+    return ok(`${d.note}\n${JSON.stringify(d.rows || []).slice(0, 4000)}`, d);
+  }));
   server.registerTool('list_merchant_issues', {
     description: "Read the account-level issues Google reports on a Merchant Center — the answer to \"why is this product not showing?\", which Google Ads reporting CANNOT give you, because a disapproved product has no impressions to report on. Needs merchantCenterId from list_merchant_accounts. Read-only and free.",
     inputSchema: { merchantCenterId: z.string().describe('from list_merchant_accounts') },
@@ -4356,19 +4421,25 @@ export function registerTools(rawServer, opts = {}) {
       dimensions: z.array(z.string()).optional().describe('GA4 dimension names to break the metrics down by — omit for a single total row'),
       startDate: z.string().optional().describe('YYYY-MM-DD or a GA4 relative date like "28daysAgo" (default 28daysAgo)'),
       endDate: z.string().optional().describe('YYYY-MM-DD or "today" (default today)'),
-      limit: z.number().optional().describe('rows, 1–1000 (default 50)'),
+      limit: z.number().optional().describe('rows to return, 1–250000 (default 50). 250,000 is GOOGLE\'s per-request maximum, not ours — asking for more is silently capped there.'),
+      offset: z.number().optional().describe('skip this many rows — how you page past `limit`. Use the nextOffset the previous call returns.'),
       orderByMetric: z.string().optional().describe('sort by this metric — must be one of the metrics requested'),
       orderDesc: z.boolean().optional().describe('default true (largest first) when orderByMetric is set'),
       dimensionFilter: z.record(z.any()).optional().describe('NARROW THE REPORT — a GA4 FilterExpression, exactly one of andGroup | orGroup | notExpression | filter. Without it a report is the WHOLE property. Example: {"filter":{"fieldName":"sessionSource","stringFilter":{"matchType":"EXACT","value":"google"}}}; combine with {"andGroup":{"expressions":[…]}}. METRICS CANNOT BE USED HERE — use metricFilter.'),
       metricFilter: z.record(z.any()).optional().describe('Filter the AGGREGATED rows, GA4\'s having-clause — same FilterExpression shape. Example: {"filter":{"fieldName":"sessions","numericFilter":{"operation":"GREATER_THAN","value":{"int64Value":"30"}}}}. DIMENSIONS CANNOT BE USED HERE — use dimensionFilter.'),
     },
-    outputSchema: { property: z.string().optional(), rows: z.array(z.any()).optional(), rowCount: z.number().optional(), dimensions: z.array(z.string()).optional(), metrics: z.array(z.string()).optional(), filtered: z.boolean().optional(), sampled: z.boolean().optional() },
+    outputSchema: { property: z.string().optional(), rows: z.array(z.any()).optional(), rowCount: z.number().optional(), returned: z.number().optional(), offset: z.number().optional(), truncated: z.boolean().optional(), nextOffset: z.number().optional(), dimensions: z.array(z.string()).optional(), metrics: z.array(z.string()).optional(), filtered: z.boolean().optional(), sampled: z.boolean().optional() },
     annotations: { readOnlyHint: true, openWorldHint: true },
   }, wrap(async (a) => {
     const d = await apiPost('/api/analytics/report', a);
     // SAY WHETHER IT WAS FILTERED. A narrow answer and a small property look identical in a row list, so a reader
     // who did not send the filter cannot otherwise tell which one they are looking at.
-    return ok(`${d.rowCount || 0} row(s) for property ${d.property}${d.filtered ? ' (FILTERED — this is a SUBSET of the property, not its total)' : ''}${d.sampled ? ' (SAMPLED — GA4 dropped rows to answer this; say so when reporting)' : ''}.\n${rowLines(d.rows)}`, d);
+    // rowCount is GA4's TOTAL, `returned` is what is actually in this response. Printing only the total put a big
+    // number above a short list and let a partial answer read as a complete one.
+    const head = d.truncated
+      ? `${d.returned} of ${d.rowCount} row(s) for property ${d.property} — THIS IS A PARTIAL ANSWER. Call again with offset:${d.nextOffset} for the next page, or raise limit (max 250000).`
+      : `${d.rowCount || 0} row(s) for property ${d.property}`;
+    return ok(`${head}${d.filtered ? ' (FILTERED — this is a SUBSET of the property, not its total)' : ''}${d.sampled ? ' (SAMPLED — GA4 dropped rows to answer this; say so when reporting)' : ''}.\n${rowLines(d.rows)}`, d);
   }));
   server.registerTool('analytics_realtime', {
     title: 'Who is on the site right now (GA4 realtime)',
@@ -5646,6 +5717,7 @@ export function registerTools(rawServer, opts = {}) {
       bid: z.string().optional().describe('MAX_CONVERSIONS only — the target CPA. Refused on MANUAL_CPT.'),
       currency: z.string().optional().describe('Defaults to the connected ad account’s currency; an account cannot mix currencies.'),
       startTime: z.string().optional(), endTime: z.string().optional().describe('Omit to run indefinitely.'),
+      budgetOrderIds: z.array(z.string()).optional().describe('budget order id(s) from list_apple_ads_budget_orders to assign this campaign to — a budget order is a spend CEILING SHARED across every campaign assigned to it, and it works ALONGSIDE dailyBudget rather than instead of it. Without this a budget order can never be drawn from.'),
     },
     outputSchema: { ok: z.boolean().optional(), level: z.string().optional(), id: z.string().optional(), verified: z.boolean().optional(), bornPaused: z.boolean().optional(), read: z.any().optional(), summary: z.string().optional(), note: z.string().optional() },
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
@@ -5725,6 +5797,7 @@ export function registerTools(rawServer, opts = {}) {
       rules: z.array(z.object({ field: z.string(), operator: z.string(), value: z.any() })).optional().describe('Location group only (DYNAMIC). REPLACES every rule and puts the group back to PENDING.'),
       description: z.string().optional().describe('Location group only.'),
       startTime: z.string().optional(), endTime: z.string().optional(), currency: z.string().optional(),
+      budgetOrderIds: z.array(z.string()).optional().describe('budget order id(s) from list_apple_ads_budget_orders to assign this campaign to — a budget order is a spend CEILING SHARED across every campaign assigned to it, and it works ALONGSIDE dailyBudget rather than instead of it. Without this a budget order can never be drawn from.'),
     },
     outputSchema: { ok: z.boolean().optional(), level: z.string().optional(), id: z.string().optional(), verified: z.boolean().optional(), read: z.any().optional(), summary: z.string().optional(), note: z.string().optional() },
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
@@ -7830,8 +7903,15 @@ export function registerTools(rawServer, opts = {}) {
   // ways a caller gets it wrong and neither is guessable: money is MICRO-currency (1,000,000 = 1 unit) and a
   // creative headline is capped at 34 characters.
   //
-  // NOT LIVE-VERIFIED. Every shape here comes from developers.snap.com read on 2026-08-10; no Snapchat call has
-  // been made from this codebase, because no SNAPCHAT_CLIENT_ID exists in the deployment yet.
+  // VERIFIED-LIVE 2026-08-10 — this header said the OPPOSITE until 2026-08-19 and was wrong for nine days.
+  // It read "NOT LIVE-VERIFIED … no Snapchat call has been made from this codebase, because no SNAPCHAT_CLIENT_ID
+  // exists in the deployment yet". The credential landed and the whole tree was swept the SAME DAY the shapes were
+  // read: every Snapchat cell in tools/lib/ads-matrix.json is VERIFIED-LIVE against ad account
+  // a6ef8b0b-2f33-4c41-b7e8-d756f9c987a4, and that sweep FOUND AND FIXED three defects (SNAP-1's 100%-failing
+  // budget/status writes, SNAP-3, SNAP-6) — which is precisely the work a "docs only" header tells the next reader
+  // has not happened. A stale not-verified claim is not harmlessly conservative: it makes someone redo a live sweep,
+  // or distrust code that works. The one thing still genuinely unexercised is the chunked upload transport, and
+  // that is stated where it lives (lib/snapchat-ads.mjs).
   server.registerTool('list_snapchat_ads_accounts', {
     title: 'List Snapchat organizations and ad accounts',
     description: 'List the Snapchat AD ACCOUNTS SHARED WITH THIS BRAND — the ones it may actually build on and spend from, which is NOT everything the Snapchat login can reach — id, name, currency, timezone and status. Every other Snapchat Ads tool needs an adAccountId and this is where it comes from. One call returns both tiers, because Snap nests ad accounts inside their organization. An account flagged as a TEST account is marked as such — those cannot serve real ads. Read-only, free.',

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "hermoso",
-  "version": "0.1.112",
+  "version": "0.1.114",
   "mcpName": "io.github.hermoso-ai/hermoso",
-  "description": "AI ad studio + marketing MCP (519 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 (522 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.",
   "type": "module",
   "bin": {
     "hermoso": "bin/hermoso.mjs"