hermoso 0.1.1 → 0.1.2

package/mcp/hermoso-mcp.mjs

@@ -12,7 +12,7 @@ import { registerTools } from './tools.mjs';
 import { API_BASE } from './client.mjs';
 
 const server = new McpServer({ name: 'hermoso-mcp', version: '1.0.0' }, {
-  instructions: 'Hermoso generates copyable, on-brand ad creative. Typical flow: hermoso_capabilities (learn valid model ids + costs) → optionally draft_brand → plan_ad (concept + copy) → generate_image / generate_video (returns a served URL). Use find_competitors / pull_competitor_ads / research_ads to gather proven ads to remix first. Always report the final media URL to the user.',
+  instructions: 'Hermoso generates copyable, on-brand ad creative. Typical flow: hermoso_capabilities (learn valid model ids + costs) → optionally draft_brand → plan_ad (concept + copy) → generate_image / generate_video (returns a served URL). Use find_competitors / pull_competitor_ads / research_ads to gather proven ads to remix first. Structured ad-spy when you know exactly what to pull: search_meta_ads / search_google_ads / search_linkedin_ads (ad libraries), search_tiktok / search_instagram / search_youtube / search_reddit / search_threads (organic), scrapecreators_fetch (any allowlisted endpoint). Always report the final media URL to the user.',
 });
 
 registerTools(server);

package/mcp/tools.mjs

@@ -134,14 +134,15 @@ export function registerTools(server) {
     inputSchema: {
       prompt: z.string().describe('the full image prompt — subject, composition, lighting, and any on-image ad text'),
       refImages: z.array(z.string()).optional().describe('local file paths or URLs of product/logo references to composite in'),
+      useBrand: z.boolean().optional().describe('default true: with no refImages, the server hydrates the SAVED brand’s product/logo references so the output lands on-brand; pass false for a pure prompt-only render'),
       aspectRatio: z.string().optional().describe("e.g. '1:1', '9:16', '16:9'"),
       model: z.string().optional().describe('image model id from hermoso_capabilities'),
       imageSize: z.string().optional(),
     },
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
-  }, wrap(async ({ prompt, refImages, aspectRatio, model, imageSize }) => {
+  }, wrap(async ({ prompt, refImages, useBrand, aspectRatio, model, imageSize }) => {
     const refs = refImages?.length ? (await Promise.all(refImages.map(toRef))).filter(Boolean) : undefined;
-    const d = await apiPost('/api/generate/image', { prompt, refImages: refs, aspectRatio, model, imageSize });
+    const d = await apiPost('/api/generate/image', { prompt, refImages: refs, useBrand: useBrand !== false, aspectRatio, model, imageSize }); // explicit boolean so the server's saved-brand hydration default is unambiguous
     const img = await imageBlock(abs(d.image)); // show the actual creative inline in Claude, not just a URL
     return { content: [{ type: 'text', text: `Image ready: ${abs(d.image)}${d.model ? `  (${d.model})` : ''}` }, ...(img ? [img] : [])], structuredContent: { ...d, image: abs(d.image) } };
   }));
@@ -154,11 +155,16 @@ export function registerTools(server) {
       model: z.string().optional().describe('video model id from hermoso_capabilities (default: the plan’s pick)'),
       durationSeconds: z.number().optional(),
       aspectRatio: z.string().optional(),
-      resolution: z.string().optional().describe("'720p' (default) or '1080p'"),
+      resolution: z.enum(['480p', '720p', '1080p', '4k']).optional().describe("'720p' default; '480p' = cheap fast draft pass, '1080p'/'4k' = premium final delivery (more credits)"),
+      captions: z.boolean().optional().describe('composited caption pills on/off (default: the recipe decides)'),
+      endCard: z.boolean().optional().describe('branded end card on/off (default: on, except organic recipes)'),
+      music: z.boolean().optional().describe('licensed music bed on/off (default on)'),
+      lockup: z.boolean().optional().describe('persistent brand-logo lockup overlay on/off'),
+      ttsVoice: z.string().optional().describe('voiceover voice name (e.g. Rachel / George) when the plan voices over'),
     },
     annotations: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },
   }, wrap(async (a) => {
-    const { input, notes } = await apiPost('/api/render/assemble', a);
+    const { input, notes } = await apiPost('/api/render/assemble', a); // a passes wholesale — resolution/captions/endCard/music/lockup/ttsVoice ride the body
     const r = await renderJob('video', input, 'MCP ad render');
     return okVideo(`Ad video ready: ${r.url}${r.model ? `  (${r.model})` : ''}  [job ${r.jobId}]\n${notes || ''}`, r);
   }));
@@ -171,7 +177,7 @@ export function registerTools(server) {
       durationSeconds: z.number().optional().describe('clip length in seconds'),
       aspectRatio: z.string().optional().describe("default '9:16'"),
       model: z.string().optional(),
-      resolution: z.string().optional().describe("'720p' (default) or '1080p'"),
+      resolution: z.enum(['480p', '720p', '1080p', '4k']).optional().describe("'720p' default; '480p' = cheap fast draft pass, '1080p'/'4k' = premium final delivery (more credits)"),
       ttsScript: z.string().optional().describe('voiceover script to speak'),
       ttsVoice: z.string().optional().describe('voice name, e.g. Rachel / George'),
       musicMood: z.string().optional(),
@@ -332,6 +338,191 @@ export function registerTools(server) {
     return ok(`${d.reply || ''}\n\n(${(d.results || []).length} ads found)`, { reply: d.reply, results: d.results, actions: d.actions });
   }));
 
+  // ---------- structured ad-spy (webapp Explore-chat parity: direct library/social pulls, no LLM loop) ----------
+  // For when the agent KNOWS what to pull (one brand / keyword / platform): a single API call returning compact
+  // JSON — cheaper + faster than research_ads, which stays the right tool for open-ended cross-platform judgment.
+  const qp = (o) => Object.fromEntries(Object.entries(o || {}).filter(([, v]) => v != null && v !== '')); // URLSearchParams renders undefined as the literal string "undefined" — strip empties before they hit the API
+  const trunc = (s, n = 200) => { const t = String(s || '').replace(/\s+/g, ' ').trim(); return t.length > n ? t.slice(0, n - 1) + '…' : t; };
+  const nAds = (n) => Math.min(25, Math.max(1, Math.round(+n) || 8));
+  const adsOut = (label, total, items) => ok(JSON.stringify({ found: total, showing: items.length, [label]: items }), { found: total, [label]: items }); // compact JSON summary, never the raw firehose
+
+  server.registerTool('search_meta_ads', {
+    description: "Structured Meta (Facebook/Instagram) Ad Library pull — use when you know exactly WHAT to fetch: a keyword (query) OR one advertiser (companyName / pageId). Returns compact JSON {page_name, body, cta, link, dates, media} per ad. For open-ended research that needs judgment across platforms, use research_ads instead. Spends ScrapeCreators credits (~1–2).",
+    inputSchema: {
+      query: z.string().optional().describe('keyword search across ALL advertisers (use INSTEAD of companyName/pageId)'),
+      companyName: z.string().optional().describe('one advertiser’s ads by brand name'),
+      pageId: z.string().optional().describe('one advertiser’s ads by Facebook page id (most precise)'),
+      country: z.string().optional().describe("2-letter code or 'ALL' (default ALL)"),
+      status: z.enum(['ACTIVE', 'INACTIVE', 'ALL']).optional().describe("ACTIVE = currently running; default ALL (includes proven past winners)"),
+      mediaType: z.enum(['ALL', 'IMAGE', 'VIDEO', 'MEME', 'IMAGE_AND_MEME', 'NONE']).optional(),
+      limit: z.number().int().optional().describe('max ads returned (1–25, default 8)'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    if (!a.query && !a.companyName && !a.pageId) throw new Error('Pass query (keyword) OR companyName/pageId (one advertiser).');
+    const common = qp({ country: a.country, status: a.status, media_type: a.mediaType });
+    const d = a.query
+      ? await apiGet('/api/fb/search', { query: a.query, ...common })
+      : await apiGet('/api/fb/company-ads', qp({ companyName: a.companyName, pageId: a.pageId, ...common }));
+    const raw = d.results || d.searchResults || []; // company-ads → results[], keyword search → searchResults[]
+    const ads = raw.slice(0, nAds(a.limit)).map((x) => {
+      const s = x.snapshot || {};
+      return qp({
+        page_name: x.page_name, body: trunc(typeof s.body === 'string' ? s.body : s.body?.text), cta: s.cta_text, link: s.link_url,
+        dates: [x.start_date_string, x.end_date_string].filter(Boolean).join(' → '),
+        media: s.videos?.[0]?.video_sd_url || s.images?.[0]?.resized_image_url || s.cards?.[0]?.resized_image_url || s.cards?.[0]?.video_sd_url || s.videos?.[0]?.video_preview_image_url,
+      });
+    });
+    return adsOut('ads', d.searchResultsCount ?? raw.length, ads);
+  }));
+
+  server.registerTool('search_google_ads', {
+    description: "Structured Google Ads Transparency pull for ONE advertiser (by domain or advertiserId) — use when you know the brand; use research_ads for open-ended research. Deliberately fetches the cheap BASIC listing (get_ad_details=false, ~1 credit — the detailed variant with per-ad headlines costs 25 credits/call and is not exposed here). Returns compact JSON {advertiser, format, adUrl, image, firstShown, lastShown} per ad.",
+    inputSchema: {
+      domain: z.string().optional().describe("the advertiser's domain, e.g. nike.com"),
+      advertiserId: z.string().optional().describe('Google advertiser id (AR…) when the domain is ambiguous'),
+      region: z.string().optional().describe('2-letter region, default US'),
+      limit: z.number().int().optional().describe('max ads returned (1–25, default 8)'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    if (!a.domain && !a.advertiserId) throw new Error('Pass domain or advertiserId.');
+    const d = await apiGet('/api/google/company-ads', qp({ domain: a.domain, advertiser_id: a.advertiserId, region: a.region, get_ad_details: 'false' }));
+    const raw = d.ads || [];
+    const ads = raw.slice(0, nAds(a.limit)).map((g) => qp({ advertiser: g.advertiserName, format: g.format, adUrl: g.adUrl, image: g.imageUrl, firstShown: g.firstShown, lastShown: g.lastShown }));
+    return adsOut('ads', d.number_of_ads_estimate ?? raw.length, ads);
+  }));
+
+  server.registerTool('search_linkedin_ads', {
+    description: "Structured LinkedIn Ad Library search by company name, keyword, or companyId — use for a targeted B2B pull; use research_ads for open-ended research. Returns compact JSON {advertiser, headline, description, cta, link, media, dates, impressions} per ad — LinkedIn is the one library exposing real impression counts. Spends ScrapeCreators credits (~1).",
+    inputSchema: {
+      company: z.string().optional().describe('advertiser company name'),
+      keyword: z.string().optional().describe('keyword across all advertisers'),
+      companyId: z.string().optional(),
+      countries: z.string().optional().describe("CSV of 2-letter codes like 'US,CA'; omit or 'ALL' = worldwide"),
+      limit: z.number().int().optional().describe('max ads returned (1–25, default 8)'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    if (!a.company && !a.keyword && !a.companyId) throw new Error('Pass company, keyword, or companyId.');
+    const d = await apiGet('/api/linkedin/search', qp({ company: a.company, keyword: a.keyword, companyId: a.companyId, countries: a.countries }));
+    const raw = d.ads || [];
+    const ads = raw.slice(0, nAds(a.limit)).map((x) => qp({
+      advertiser: x.advertiser, headline: trunc(x.headline, 120), description: trunc(x.description), cta: x.cta,
+      link: x.destinationUrl, media: x.video || x.image, dates: [x.startDate, x.endDate].filter(Boolean).join(' → '), impressions: x.totalImpressions,
+    }));
+    return adsOut('ads', d.totalAds ?? raw.length, ads);
+  }));
+
+  server.registerTool('search_tiktok', {
+    description: "Organic TikTok keyword search (there is NO TikTok ad library) — top-performing videos to mine for hooks/trends/remixable creative. Returns compact JSON {desc, author, handle, plays, likes, link, cover} per video, ranked by plays. Use research_ads for open-ended research. Spends ScrapeCreators credits (~1).",
+    inputSchema: {
+      query: z.string().describe('keyword or hashtag (no # needed)'),
+      limit: z.number().int().optional().describe('max videos returned (1–25, default 8)'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async ({ query, limit }) => {
+    const d = await apiGet('/api/sc/run', { __path: '/v1/tiktok/search/keyword', query });
+    const all = (d.search_item_list || []).map((x) => x.aweme_info).filter(Boolean).map((v) => {
+      const au = v.author || {}, st = v.statistics || {}, vid = v.video || {};
+      return qp({
+        desc: trunc(v.desc), author: au.nickname || au.unique_id, handle: au.unique_id, plays: st.play_count, likes: st.digg_count,
+        link: au.unique_id && v.aweme_id ? `https://www.tiktok.com/@${au.unique_id}/video/${v.aweme_id}` : '',
+        cover: vid.cover?.url_list?.[0] || vid.origin_cover?.url_list?.[0],
+      });
+    }).sort((a, b) => (b.plays || b.likes || 0) - (a.plays || a.likes || 0)); // TOP by plays — "top-performing" means ranked, not API order
+    return adsOut('videos', all.length, all.slice(0, nAds(limit)));
+  }));
+
+  server.registerTool('search_instagram', {
+    description: "Organic Instagram REELS keyword search (/v2/instagram/reels/search — ScrapeCreators' only IG keyword surface; profile/hashtag pulls go through scrapecreators_fetch with a handle). Returns compact JSON {desc, author, handle, plays, likes, link, cover} per reel, ranked by plays. Spends ScrapeCreators credits (~1).",
+    inputSchema: {
+      query: z.string().describe('keyword to search reels for'),
+      limit: z.number().int().optional().describe('max reels returned (1–25, default 8)'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async ({ query, limit }) => {
+    const d = await apiGet('/api/sc/run', { __path: '/v2/instagram/reels/search', query });
+    const all = (d.reels || d.items || []).map((r) => {
+      const o = r.owner || r.user || {};
+      return qp({
+        desc: trunc(typeof r.caption === 'string' ? r.caption : (r.caption?.text || r.accessibility_caption)),
+        author: o.full_name || o.username, handle: o.username,
+        plays: r.video_play_count || r.video_view_count, likes: r.like_count || r.edge_liked_by?.count,
+        link: r.url || (r.shortcode ? `https://www.instagram.com/reel/${r.shortcode}/` : ''),
+        cover: r.thumbnail_src || r.display_url,
+      });
+    }).filter((x) => x.cover || x.link).sort((a, b) => (b.plays || b.likes || 0) - (a.plays || a.likes || 0));
+    return adsOut('reels', all.length, all.slice(0, nAds(limit)));
+  }));
+
+  server.registerTool('search_youtube', {
+    description: "Organic YouTube keyword search (/v1/youtube/search) — videos to mine for hooks/angles/long-form structure. Returns compact JSON {desc (title), author, handle, plays, link, cover} per video, ranked by views. Spends ScrapeCreators credits (~1).",
+    inputSchema: {
+      query: z.string().describe('keyword to search videos for'),
+      limit: z.number().int().optional().describe('max videos returned (1–25, default 8)'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async ({ query, limit }) => {
+    const d = await apiGet('/api/sc/run', { __path: '/v1/youtube/search', query });
+    const all = (d.videos || []).filter((v) => (v.type || 'video') === 'video').map((v) => {
+      const ch = v.channel || {};
+      return qp({ desc: trunc(v.title, 120), author: ch.title || ch.handle, handle: ch.handle, plays: v.viewCountInt, link: v.url || (v.id ? `https://www.youtube.com/watch?v=${v.id}` : ''), cover: v.thumbnail });
+    }).filter((x) => x.cover || x.link).sort((a, b) => (b.plays || 0) - (a.plays || 0));
+    return adsOut('videos', all.length, all.slice(0, nAds(limit)));
+  }));
+
+  server.registerTool('search_reddit', {
+    description: "Reddit keyword search (/v1/reddit/search, top-ranked) — a goldmine for the customer's OWN words (pain points, objections, language) to mine into ad hooks and copy. Returns compact JSON {desc (title+selftext), subreddit, upvotes, comments, link} per post. Spends ScrapeCreators credits (~1).",
+    inputSchema: {
+      query: z.string().describe('what to search Reddit for'),
+      limit: z.number().int().optional().describe('max posts returned (1–25, default 8)'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async ({ query, limit }) => {
+    const d = await apiGet('/api/sc/run', { __path: '/v1/reddit/search', query, sort: 'top' });
+    const all = (d.posts || d.results || []).map((p) => qp({
+      desc: trunc([p.title, p.selftext].filter(Boolean).join(' — '), 260),
+      subreddit: p.subreddit ? `r/${p.subreddit}` : '', upvotes: p.ups ?? p.score, comments: p.num_comments,
+      link: p.permalink ? (/^https?:/.test(p.permalink) ? p.permalink : `https://www.reddit.com${p.permalink}`) : p.url,
+    })).filter((x) => x.desc || x.link);
+    return adsOut('posts', all.length, all.slice(0, nAds(limit)));
+  }));
+
+  server.registerTool('search_threads', {
+    description: "Organic Threads keyword search (/v1/threads/search) — short-form text/social posts for trend + voice research. Returns compact JSON {desc, author, handle, likes, link, cover} per post. Spends ScrapeCreators credits (~1).",
+    inputSchema: {
+      query: z.string().describe('keyword to search Threads for'),
+      limit: z.number().int().optional().describe('max posts returned (1–25, default 8)'),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async ({ query, limit }) => {
+    const d = await apiGet('/api/sc/run', { __path: '/v1/threads/search', query });
+    const all = (d.posts || d.results || []).map((p) => {
+      const u = p.user || {};
+      return qp({
+        desc: trunc((p.caption && (p.caption.text || (typeof p.caption === 'string' ? p.caption : ''))) || p.accessibility_caption),
+        author: u.full_name || u.username, handle: u.username, likes: p.like_count,
+        link: p.code && u.username ? `https://www.threads.net/@${u.username}/post/${p.code}` : '',
+        cover: p.image_versions2?.candidates?.[0]?.url,
+      });
+    }).filter((x) => x.desc || x.link || x.cover);
+    return adsOut('posts', all.length, all.slice(0, nAds(limit)));
+  }));
+
+  server.registerTool('scrapecreators_fetch', {
+    description: "Generic ScrapeCreators escape hatch for any ALLOWLISTED long-tail endpoint the dedicated search_* tools don't cover — e.g. {path:'/v1/instagram/profile', params:{handle:'nike'}}. Allowlisted platform families: TikTok (+ TikTok Shop), Instagram, YouTube, Facebook (organic profiles/posts/events/marketplace), LinkedIn (organic posts/companies), Twitter/X, Reddit, Threads, Snapchat, Pinterest, Twitch, Bluesky, Truth Social, Rumble, Spotify, SoundCloud, GitHub, Google search, link-in-bio pages (Linktree etc.). Param names vary per endpoint (profiles use `handle`, keyword searches use `query`, Reddit uses `subreddit`). WARNING: returns RAW provider JSON — large and messy; prefer the dedicated search_* tools. Spends ScrapeCreators credits.",
+    inputSchema: {
+      path: z.string().describe("exact SC endpoint path, e.g. '/v1/tiktok/profile' — non-allowlisted paths are rejected"),
+      params: z.object({}).passthrough().optional().describe("endpoint query params, e.g. {handle:'nike'}"),
+    },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async ({ path, params }) => {
+    const d = await apiGet('/api/sc/run', { __path: path, ...qp(params || {}) });
+    const raw = JSON.stringify(d);
+    return ok(raw.length > 24000 ? raw.slice(0, 24000) + '\n… (truncated — narrow the query or use a dedicated search_* tool)' : raw); // no structuredContent: raw payloads can be huge, the text IS the result
+  }));
+
   // ---------- brand onboarding ----------
   server.registerTool('get_brand', {
     description: 'What Hermoso ALREADY KNOWS for this account/workspace — the same saved brand profile (products, logos, palette, positioning) + learned memory the web Studio uses. Call this FIRST: if hasBrand is true you can omit brand everywhere; if false, onboard with draft_brand. 0 credits.',

package/package.json

@@ -1,14 +1,32 @@
 {
   "name": "hermoso",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Drive Hermoso — the AI ad studio — from any AI agent: MCP server, CLI, and Claude skills for researching winning ads and generating finished image & video ads.",
   "type": "module",
-  "bin": { "hermoso": "bin/hermoso.mjs" },
-  "scripts": { "mcp": "node mcp/hermoso-mcp.mjs" },
-  "dependencies": { "@modelcontextprotocol/sdk": "^1.12.0" },
-  "keywords": ["mcp", "model-context-protocol", "ai-ads", "ad-generator", "ugc", "claude", "cli", "video-ads"],
+  "bin": {
+    "hermoso": "bin/hermoso.mjs"
+  },
+  "scripts": {
+    "mcp": "node mcp/hermoso-mcp.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-ads",
+    "ad-generator",
+    "ugc",
+    "claude",
+    "cli",
+    "video-ads"
+  ],
   "homepage": "https://hermoso.ai",
-  "repository": { "type": "git", "url": "https://github.com/hermoso-ai/hermoso.git" },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hermoso-ai/hermoso.git"
+  },
   "license": "MIT",
   "author": "Hermoso <hello@hermoso.ai>"
 }