hermoso 0.1.17 → 0.1.20

package/mcp/client.mjs

@@ -13,11 +13,15 @@ export const mcpCtx = new AsyncLocalStorage();
 
 export const API_BASE = (process.env.HERMOSO_API_BASE || 'https://app.hermoso.ai').replace(/\/+$/, '');
 const TOKEN = process.env.HERMOSO_TOKEN || '';
-export const PROFILE = process.env.HERMOSO_PROFILE || 'default';
+// PINNED profile, or '' when unpinned. MUST stay unset by default: the server resolves an API key's profile as
+// header > key.keyProfileId > 'default' (adapters/auth/middleware.js), so always sending the header permanently
+// masks the brand `use_brand` saved against the key — connectors on any non-default brand then look disconnected.
+export const PROFILE = process.env.HERMOSO_PROFILE || '';
 
 function headers(extra = {}) {
   const ctx = mcpCtx.getStore();
-  const h = { 'Content-Type': 'application/json', 'x-hermoso-user': ctx?.profile || PROFILE, ...extra };
+  const prof = ctx?.profile || PROFILE; // omitted when unpinned so the key's saved brand wins server-side
+  const h = { 'Content-Type': 'application/json', ...(prof ? { 'x-hermoso-user': prof } : {}), ...extra };
   const tok = ctx?.token || TOKEN;
   if (tok) h.Authorization = `Bearer ${tok}`;
   return h;
@@ -35,7 +39,12 @@ async function unwrap(res) {
 }
 
 export async function apiGet(p, query) {
-  const qs = query ? '?' + new URLSearchParams(query).toString() : '';
+  // URLSearchParams stringifies undefined/null as the LITERAL "undefined"/"null" — so an omitted optional param
+  // arrives as a truthy string and silently changes server behaviour. Live 2026-07-27: list_google_ads_campaigns
+  // sent since=undefined&until=undefined, the server saw two truthy values, took the BETWEEN branch, and its
+  // digit-strip reduced them to '' → GAQL "segments.date BETWEEN '' and ''". Drop empties before building the qs.
+  const clean = query && Object.fromEntries(Object.entries(query).filter(([, v]) => v !== undefined && v !== null && v !== ''));
+  const qs = clean && Object.keys(clean).length ? '?' + new URLSearchParams(clean).toString() : '';
   const res = await fetch(`${API_BASE}${p}${qs}`, { headers: headers() });
   return unwrap(res);
 }

package/mcp/tools.mjs

@@ -272,7 +272,7 @@ function registerAppResources(server) {
 // the whole {key:{value}} map, so a per-key READ resolves the value out of it. WRITES go through `PUT /api/store/:key`,
 // which union-merges the sync stores server-side (adapters/sync-merge.js) so a snapshot never clobbers another device's
 // concurrent work. Keys are per-profile namespaced exactly like the webapp's pk() (bare for default, `<base>.<id>` else).
-const pk = (base) => (PROFILE !== 'default' ? `${base}.${PROFILE}` : base);
+const pk = (base) => (PROFILE && PROFILE !== 'default' ? `${base}.${PROFILE}` : base); // '' (unpinned) behaves like default
 async function readStore(base) {
   let dump; try { dump = await apiGet('/api/store/bootstrap'); } catch { return null; }
   const raw = dump && dump[pk(base)] && dump[pk(base)].value;
@@ -556,6 +556,184 @@ export function registerTools(server) {
     return ok(`Now acting on ${hit.name} (${hit.id}) — brand, memory, renders and Library all scope to it.`, { ok: true, brand: hit });
   }));
 
+
+
+  // ---------- META engagement + insights (organic performance and the comment thread under a post) ----------
+  server.registerTool('meta_page_insights', {
+    title: 'Facebook Page + Instagram insights',
+    description: 'Organic performance for the brand’s connected Facebook Page and its linked Instagram account — impressions, reach, engagement, follower/fan counts. This is ORGANIC reach; use meta_insights for paid ad performance.',
+    inputSchema: {
+      pageId: z.string().optional().describe('Page id — omit when the brand has exactly one Page connected'),
+      period: z.enum(['day', 'week', 'days_28']).optional().describe('window (default week)'),
+    },
+    outputSchema: { pageName: z.string().optional(), page: z.array(z.any()).optional(), instagram: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/meta/page-insights', { pageId: a.pageId, period: a.period });
+    const fmt = (arr) => (arr || []).map(m => `  • ${m.name}: ${m.value ?? '—'}`).join('\n');
+    return ok(`${d.pageName} (${d.period})\nFacebook:\n${fmt(d.page) || '  (none)'}${d.instagram ? `\nInstagram:\n${fmt(d.instagram)}` : ''}${d.pageError ? `\n(page: ${d.pageError})` : ''}${d.instagramError ? `\n(instagram: ${d.instagramError})` : ''}`, d);
+  }));
+
+  server.registerTool('meta_post_insights', {
+    title: 'Insights for one Facebook/Instagram post',
+    description: 'Performance for a single organic post — impressions/reach, engagement and clicks on Facebook; reach, likes, comments, saves and shares on Instagram. Use it to find which organic posts earned their reach before turning one into a paid ad.',
+    inputSchema: {
+      postId: z.string().describe('post/media id returned by post_to_meta'),
+      target: z.enum(['facebook', 'instagram']).optional().describe('which metric set to ask for (default facebook)'),
+      pageId: z.string().optional().describe('Page id — omit when only one Page is connected'),
+    },
+    outputSchema: { postId: z.string().optional(), metrics: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/meta/post-insights', { postId: a.postId, target: a.target, pageId: a.pageId });
+    return ok(`${d.target} post ${d.postId}:\n${(d.metrics || []).map(m => `• ${m.name}: ${m.value ?? '—'}`).join('\n') || '(no metrics)'}`, 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.',
+    inputSchema: {
+      postId: z.string().describe('post/media id'),
+      pageId: z.string().optional().describe('Page id — omit when only one Page is connected'),
+      limit: z.number().optional().describe('how many comments (1–50, default 25)'),
+    },
+    outputSchema: { count: z.number().optional(), comments: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/meta/comments', { postId: a.postId, pageId: a.pageId, limit: a.limit });
+    const lines = (d.comments || []).map(c => `• ${c.author || '(unknown)'}: ${String(c.text).replace(/\s+/g, ' ').slice(0, 90)} — ${c.id}${c.hidden ? ' [hidden]' : ''}${c.likes ? ` · ${c.likes} likes` : ''}`);
+    return ok(`${d.count} comment(s) on ${d.postId}:\n${lines.join('\n') || '(none)'}`, d);
+  }));
+
+  server.registerTool('reply_to_meta_comment', {
+    title: 'Reply to a Facebook/Instagram comment',
+    description: 'Post a public reply to a comment on the brand’s Facebook or Instagram post. This is PUBLIC and posted as the brand — show the user the exact wording and get their go-ahead first.',
+    inputSchema: {
+      commentId: z.string().describe('comment id from list_meta_comments'),
+      message: z.string().describe('reply text'),
+      pageId: z.string().optional().describe('Page id — omit when only one Page is connected'),
+    },
+    outputSchema: { ok: z.boolean().optional(), id: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/meta/comment/reply', { commentId: a.commentId, message: a.message, pageId: a.pageId });
+    return ok(`Replied to comment ${a.commentId} (${d.id}).`, d);
+  }));
+
+  server.registerTool('moderate_meta_comment', {
+    title: 'Hide, unhide or delete a Meta comment',
+    description: 'Moderate a comment on the brand’s Facebook or Instagram post. Prefer hide over delete — hiding is reversible and invisible to the commenter. Deleting is PERMANENT and requires confirm:true after the user has agreed.',
+    inputSchema: {
+      commentId: z.string().describe('comment id from list_meta_comments'),
+      action: z.enum(['hide', 'unhide', 'delete']).optional().describe('default hide'),
+      confirm: z.boolean().optional().describe('required (true) only for delete'),
+      pageId: z.string().optional().describe('Page id — omit when only one Page is connected'),
+    },
+    outputSchema: { ok: z.boolean().optional(), action: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/meta/comment/moderate', { commentId: a.commentId, action: a.action, confirm: a.confirm, pageId: a.pageId });
+    return ok(`Comment ${d.commentId}: ${d.action}d.`, d);
+  }));
+
+  // ---------- THREADS read + manage (needs a connected Threads account; insights/replies/delete need Meta review) ----
+  server.registerTool('list_threads_posts', {
+    title: 'List your Threads posts',
+    description: 'List recent posts on the brand’s connected Threads account (id, text, media, permalink, timestamp). Use it to find a post id for threads_insights, list_threads_replies, reply_to_thread or delete_thread.',
+    inputSchema: { limit: z.number().optional().describe('how many posts (1–50, default 15)') },
+    outputSchema: { username: z.string().optional(), count: z.number().optional(), posts: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/threads/posts', { limit: a.limit });
+    const lines = (d.posts || []).map(p => `• ${String(p.text || '(no text)').replace(/\s+/g, ' ').slice(0, 80)} — ${p.id} · ${String(p.timestamp || '').slice(0, 10)} · ${p.permalink || ''}`);
+    return ok(`@${d.username} — ${d.count} post(s):\n${lines.join('\n') || '(none)'}`, d);
+  }));
+
+  server.registerTool('threads_insights', {
+    title: 'Threads insights',
+    description: 'Performance for ONE Threads post (views, likes, replies, reposts, quotes, shares) when postId is given, or for the whole account (plus follower count) when it is omitted. Use it to report results or to learn which posts worked before writing more.',
+    inputSchema: { postId: z.string().optional().describe('post id from list_threads_posts — omit for account-level insights') },
+    outputSchema: { scope: z.string().optional(), metrics: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/threads/insights', { postId: a.postId });
+    const lines = (d.metrics || []).map(m => `• ${m.name}: ${m.values?.[0]?.value ?? m.total_value?.value ?? '—'}`);
+    return ok(`${d.scope === 'post' ? `Post ${d.postId}` : `@${d.username} (account)`}\n${lines.join('\n') || '(no metrics returned)'}`, d);
+  }));
+
+  server.registerTool('list_threads_replies', {
+    title: 'List replies on a Threads post',
+    description: 'Read the replies on a Threads post. Set conversation:true to walk the entire thread rather than only direct replies. Use before reply_to_thread so you answer with the actual conversation in view.',
+    inputSchema: {
+      postId: z.string().describe('post id from list_threads_posts'),
+      conversation: z.boolean().optional().describe('true = the whole thread, not just direct replies'),
+      limit: z.number().optional().describe('how many replies (1–50, default 25)'),
+    },
+    outputSchema: { count: z.number().optional(), replies: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/threads/replies', { postId: a.postId, conversation: a.conversation ? 'true' : undefined, limit: a.limit });
+    const lines = (d.replies || []).map(r => `• @${r.username}: ${String(r.text || '').replace(/\s+/g, ' ').slice(0, 90)} — ${r.id}${r.hide_status === 'HIDDEN' ? ' [hidden]' : ''}`);
+    return ok(`${d.count} repl(ies) on ${d.postId}:\n${lines.join('\n') || '(none)'}`, d);
+  }));
+
+  server.registerTool('reply_to_thread', {
+    title: 'Reply on Threads',
+    description: 'Post a reply to a Threads post — the brand’s own or someone else’s. This PUBLISHES publicly under the brand’s account, so show the user the exact wording and get their go-ahead first.',
+    inputSchema: {
+      replyToId: z.string().describe('the post id being replied to'),
+      text: z.string().describe('reply text (max 500 characters)'),
+    },
+    outputSchema: { ok: z.boolean().optional(), id: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/threads/reply', { replyToId: a.replyToId, text: a.text });
+    return ok(`Replied on Threads (${d.id}).`, d);
+  }));
+
+  server.registerTool('hide_thread_reply', {
+    title: 'Hide or unhide a Threads reply',
+    description: 'Hide a reply on the brand’s Threads post (or unhide it with hide:false) — for spam and abuse moderation.',
+    inputSchema: {
+      replyId: z.string().describe('reply id from list_threads_replies'),
+      hide: z.boolean().optional().describe('false to UNHIDE (default true)'),
+    },
+    outputSchema: { ok: z.boolean().optional(), hidden: z.boolean().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/threads/reply/hide', { replyId: a.replyId, hide: a.hide });
+    return ok(`Reply ${a.replyId} ${d.hidden ? 'hidden' : 'unhidden'}.`, d);
+  }));
+
+  server.registerTool('delete_thread', {
+    title: 'Delete a Threads post',
+    description: 'Permanently delete one of the brand’s Threads posts. IRREVERSIBLE — you must confirm with the user first, then pass confirm:true.',
+    inputSchema: {
+      postId: z.string().describe('post id from list_threads_posts'),
+      confirm: z.boolean().describe('must be true; only set it after the user has explicitly agreed to the deletion'),
+    },
+    outputSchema: { ok: z.boolean().optional(), deleted: z.string().optional() },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiPost('/api/threads/delete', { postId: a.postId, confirm: a.confirm });
+    return ok(`Deleted Threads post ${d.deleted}.`, d);
+  }));
+
+  server.registerTool('search_threads_keyword', {
+    title: 'Search Threads by keyword',
+    description: 'Search PUBLIC Threads posts for a keyword or topic — competitor listening, finding what people say about a product, or sourcing real customer language for ad copy. Distinct from search_threads, which reads a specific profile.',
+    inputSchema: {
+      q: z.string().describe('keyword or phrase'),
+      searchType: z.enum(['TOP', 'RECENT']).optional().describe('TOP (default) or RECENT'),
+    },
+    outputSchema: { count: z.number().optional(), posts: z.array(z.any()).optional() },
+    annotations: { readOnlyHint: true, openWorldHint: true },
+  }, wrap(async (a) => {
+    const d = await apiGet('/api/threads/search', { q: a.q, searchType: a.searchType });
+    const lines = (d.posts || []).map(p => `• @${p.username}: ${String(p.text || '').replace(/\s+/g, ' ').slice(0, 90)} — ${p.permalink || p.id}`);
+    return ok(`${d.count} result(s) for "${d.q}":\n${lines.join('\n') || '(none)'}`, d);
+  }));
+
   // ---------- META publishing + ads management (needs a connected Meta account: Settings ▸ Connectors ▸ Meta) ----------
   server.registerTool('list_meta_pages', {
     title: 'List Meta pages & ad accounts',
@@ -2200,7 +2378,7 @@ export function registerTools(server) {
       try {
         const cur = save === true ? null : await apiGet('/api/brand/current').catch(() => null);
         if (save === true || !cur?.hasBrand) {
-          const bk = PROFILE !== 'default' ? `heist.brand.v1.${PROFILE}` : 'heist.brand.v1'; // mirror the webapp's per-profile key namespacing
+          const bk = PROFILE && PROFILE !== 'default' ? `heist.brand.v1.${PROFILE}` : 'heist.brand.v1'; // mirror the webapp's per-profile key namespacing
           await apiPut(`/api/store/${encodeURIComponent(bk)}`, { value: JSON.stringify(p) });
           saved = true;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hermoso",
-  "version": "0.1.17",
+  "version": "0.1.20",
   "mcpName": "io.github.hermoso-ai/hermoso",
   "description": "Generate finished VIDEO ADS, image ads and UGC avatar ads for any brand with AI — 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.",
   "type": "module",